From 22b6de024a0cb4ac83fad502c5d32aea187a90ea Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Mon, 6 Jul 2026 14:31:44 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20=EB=B9=84=ED=99=9C?=
 =?UTF-8?q?=EC=84=B1=ED=99=94=EB=90=9C=20=EB=B2=84=ED=8A=BC=EC=9D=98=20?=
 =?UTF-8?q?=ED=88=B4=ED=8C=81=20=EC=A0=91=EA=B7=BC=EC=84=B1=20=EA=B0=9C?=
 =?UTF-8?q?=EC=84=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

비활성화된 요소에 툴팁을 제공할 때, 스크린 리더에서 읽어주기 위한 `sr-only` span 요소를 추가하여 접근성을 개선했습니다.
---
 .Jules/palette.md                                 | 3 +++
 apps/desktop/src/App.tsx                          | 1 +
 apps/desktop/src/features/workspace/Workspace.tsx | 4 ++++
 3 files changed, 8 insertions(+)

diff --git a/.Jules/palette.md b/.Jules/palette.md
index b6f5d5bf..3ec4fdcc 100644
--- a/.Jules/palette.md
+++ b/.Jules/palette.md
@@ -29,3 +29,6 @@
 ## 2024-07-01 - Testing components with focusable disabled button wrappers
 **Learning:** When native disabled buttons are wrapped in a focusable `span` to provide accessible tooltips, tests that previously found and clicked the `button` (by temporarily removing the `disabled` attribute) may fail or become overly complex. It is cleaner and more accurate to query the wrapper element (e.g. via its `title`) and fire events on it, reflecting the actual accessible DOM structure.
 **Action:** When testing UI components that wrap disabled buttons in a focusable span for accessibility (e.g., using a tooltip/title), use `screen.getByTitle(...)` to query the wrapper element for interactions like `fireEvent.click` rather than `screen.getByRole('button')`.
+## 2026-07-06 - 스크린 리더 텍스트 접근성 및 ARIA 속성 주의점
+**Learning:** 비활성화된 버튼을 `span`으로 감싸 툴팁을 제공할 때, `role="button"`과 `aria-disabled="true"` 속성이 적용된 상태에서 시각적으로 숨겨진 스크린 리더 전용 텍스트(`sr-only`)를 자식 요소로 추가하면 화면 리더기에서 툴팁 내용이 중복해서 읽히거나 혼란을 줄 수 있습니다. 반대로, 포커스 가능하게 만든 엘리먼트에 역할(role)이 없는 상태로 `tabIndex={0}`만 있으면 접근성에 어긋납니다. 기존 구현의 의도를 정확히 파악하여 ARIA 속성 유지 여부를 신중하게 결정해야 합니다.
+**Action:** 접근성 개선 작업 시 기존 구현의 `role`과 `aria-disabled` 속성을 임의로 삭제하지 말고, 스크린 리더에서 읽어주는 기존 텍스트(예: `title` 속성이나 `aria-label`)와 충돌하거나 중복을 초래하는 `sr-only` 텍스트 추가를 피해야 합니다.
diff --git a/apps/desktop/src/App.tsx b/apps/desktop/src/App.tsx
index 24f5fb09..582f3b27 100644
--- a/apps/desktop/src/App.tsx
+++ b/apps/desktop/src/App.tsx
@@ -647,6 +647,7 @@ export function App() {
                   </Button>
                 ) : (
                   <span tabIndex={0} role="button" aria-disabled="true" title="Analyze a song to enable saving" className="inline-block cursor-not-allowed rounded-xl focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300">
+                    <span className="sr-only">Analyze a song to enable saving</span>
                     <Button
                       disabled
                       variant="outline"
diff --git a/apps/desktop/src/features/workspace/Workspace.tsx b/apps/desktop/src/features/workspace/Workspace.tsx
index 2f990eec..e2a5f210 100644
--- a/apps/desktop/src/features/workspace/Workspace.tsx
+++ b/apps/desktop/src/features/workspace/Workspace.tsx
@@ -312,12 +312,15 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
                 <p className="mt-1 text-sm font-semibold text-slate-100">{activeRoleDetails?.name ?? activeRole}</p>
                 <div className="mt-3 flex flex-wrap gap-2">
                   <span tabIndex={0} role="button" aria-disabled="true" title="Coming soon" className="inline-block cursor-not-allowed rounded-xl focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300">
+                    <span className="sr-only">Coming soon</span>
                     <Button type="button" disabled variant="outline" className="min-h-11 border-white/10 bg-white/5 text-slate-400">Play stem</Button>
                   </span>
                   <span tabIndex={0} role="button" aria-disabled="true" title="Coming soon" className="inline-block cursor-not-allowed rounded-xl focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300">
+                    <span className="sr-only">Coming soon</span>
                     <Button type="button" disabled variant="outline" className="min-h-11 border-white/10 bg-white/5 text-slate-400">Loop section</Button>
                   </span>
                   <span tabIndex={0} role="button" aria-disabled="true" title="Coming soon" className="inline-block cursor-not-allowed rounded-xl focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300">
+                    <span className="sr-only">Coming soon</span>
                     <Button type="button" disabled variant="outline" className="min-h-11 border-white/10 bg-white/5 text-slate-400">Solo / mute others</Button>
                   </span>
                   {canTranscribeBass ? (
@@ -331,6 +334,7 @@ export function Workspace({ song, sourceBootstrap = null, onSongUpdate }: Worksp
                     </Button>
                   ) : (
                     <span tabIndex={0} role="button" aria-disabled="true" title={`${activeRoleDetails?.name ?? "This role"} transcription is coming soon. Bass is ready first.`} className="inline-block cursor-not-allowed rounded-xl focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300">
+                      <span className="sr-only">{`${activeRoleDetails?.name ?? "This role"} transcription is coming soon. Bass is ready first.`}</span>
                       <Button
                         type="button"
                         disabled