From 44078dbfaa3bb430be5edd44e5382dde6d16ea3c Mon Sep 17 00:00:00 2001
From: billlzzz10 <208072329+billlzzz10@users.noreply.github.com>
Date: Fri, 24 Jul 2026 17:12:33 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Add=20accessibility?=
 =?UTF-8?q?=20improvements=20to=20background=20music=20buttons?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
---
 .Jules/palette.md                               |  5 +++++
 src/components/kids/layout/background-music.tsx | 16 +++++++++++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/.Jules/palette.md b/.Jules/palette.md
index 7a724d13..f6cd528d 100644
--- a/.Jules/palette.md
+++ b/.Jules/palette.md
@@ -7,3 +7,8 @@
 
 **Learning:** For custom toggle buttons or selectable elements acting as a group (like language selection) that use standard HTML `<button>` tags, `aria-pressed={boolean}` should be applied to convey the active state to assistive technology. Furthermore, when decorative emojis are used alongside text labels, wrapping the emoji in a `<span>` with `aria-hidden="true"` prevents redundant or confusing screen reader announcements.
 **Action:** Always apply `aria-pressed` to custom toggle buttons and add `aria-hidden="true"` to wrapper spans around decorative emojis.
+
+## 2026-07-24 - Restore keyboard accessibility to custom buttons
+
+**Learning:** When styling custom interactive UI elements that remove native browser focus outlines (e.g., pixel-btn components or custom toggles), keyboard accessibility is lost for tab-navigation users.
+**Action:** Always restore keyboard accessibility by adding explicit focus-visible: utility classes (like focus-visible:ring-agent-cyan focus-visible:ring-2 focus-visible:outline-none) to custom buttons. This ensures keyboard users can see their focus state without applying persistent focus outlines for mouse users.
diff --git a/src/components/kids/layout/background-music.tsx b/src/components/kids/layout/background-music.tsx
index 1c815be3..83daaf6a 100644
--- a/src/components/kids/layout/background-music.tsx
+++ b/src/components/kids/layout/background-music.tsx
@@ -175,9 +175,10 @@ export function MusicButton() {
   return (
     <button
       onClick={toggleMusic}
-      className="pixel-btn pixel-btn-amber flex h-8 items-center px-2 py-1.5"
+      className="pixel-btn pixel-btn-amber focus-visible:ring-agent-cyan flex h-8 items-center px-2 py-1.5 focus-visible:ring-2 focus-visible:outline-none"
       aria-label={labelText}
       title={labelText}
+      aria-pressed={isPlaying}
     >
       {isPlaying ? <PixelSpeakerOn aria-hidden="true" /> : <PixelSpeakerOff aria-hidden="true" />}
     </button>
@@ -197,11 +198,20 @@ export function MusicVolumeSlider() {
       <div className="flex items-center justify-between">
         <button
           onClick={() => setIsPlaying(!isPlaying)}
-          className={`rounded-lg px-3 py-1.5 text-sm font-medium transition-colors ${
+          aria-pressed={isPlaying}
+          className={`focus-visible:ring-agent-cyan rounded-lg px-3 py-1.5 text-sm font-medium transition-colors focus-visible:ring-2 focus-visible:outline-none ${
             isPlaying ? "bg-[#22C55E] text-white" : "bg-gray-200 text-gray-600"
           }`}
         >
-          {isPlaying ? "🔊 On" : "🔇 Off"}
+          {isPlaying ? (
+            <>
+              <span aria-hidden="true">🔊</span> On
+            </>
+          ) : (
+            <>
+              <span aria-hidden="true">🔇</span> Off
+            </>
+          )}
         </button>
         <span className="text-sm text-[#5D4037]">{Math.round(volume * 100)}%</span>
       </div>