🎨 Palette: 코드 수정 버튼에 접근성 있는 툴팁 지원 추가

CHANGELOG.md

@@ -7,6 +7,10 @@
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 
+### Fixed
+
+- 합주 워크스페이스의 읽기 전용 코드 수정 버튼이 키보드 포커스를 유지하고 `aria-disabled="true"`를 노출하며, 한·영 접근성 이름과 설명으로 편집 가능한 곡을 열어야 한다는 복구 방법을 안내하도록 개선했습니다. `aria-describedby`는 분석 데이터의 section/role 식별자 대신 렌더러가 소유하는 고유하고 공백 없는 ID를 사용하여 임의 문자열 식별자에서도 참조 무결성을 유지하고, 포인터 `title`에도 같은 복구 문구를 제공하며 클릭은 계속 실패-폐쇄 방식으로 차단됩니다.
+
 ## [0.1.3] - 2026-04-29
 
 ### Fixed

apps/desktop/src/features/workspace/SectionRoadmap.test.tsx

@@ -30,6 +30,7 @@ describe("SectionRoadmap", () => {
     expect(screen.getAllByText("코드").length).toBeGreaterThan(0);
     expect(screen.getAllByText("큐").length).toBeGreaterThan(0);
     expect(screen.getAllByTitle("우선순위: high").length).toBeGreaterThan(0);
+    expect(screen.getAllByTitle("코드를 바꾸려면 편집 가능한 곡을 여세요").length).toBeGreaterThan(0);
     expect(screen.getByText("사용자")).toBeTruthy();
   });
 
@@ -60,4 +61,49 @@ describe("SectionRoadmap", () => {
 
     expect(onSongUpdate).not.toHaveBeenCalled();
   });
+
+  it("applies aria-disabled when onSongUpdate is missing, describes how to recover, and prevents click", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    // Intentionally omit onSongUpdate to simulate readonly mode
+    render(<SectionRoadmap song={song} activeRole={null} />);
+
+    const button = screen.getByRole("button", { name: "Edit chord for Bass Guitar in verse, current C#m7" });
+    expect(button).toHaveAttribute("aria-disabled", "true");
+    expect(button).toHaveAttribute("title", "Open an editable song to change this chord");
+
+    const descriptionId = button.getAttribute("aria-describedby");
+    expect(descriptionId).toBeTruthy();
+    expect(document.getElementById(descriptionId ?? "")?.textContent).toBe(
+      "Open an editable song to change this chord"
+    );
+
+    const promptSpy = vi.spyOn(window, "prompt");
+    fireEvent.click(button);
+
+    // Verify click handler early returns and prevents prompt
+    expect(promptSpy).not.toHaveBeenCalled();
+  });
+
+  it("uses unique whitespace-free description IDs for arbitrary section and role IDs", () => {
+    setNavigatorLanguage("en-US");
+    const song = createDemoRehearsalSong();
+    song.sections[0].id = "verse 1";
+    song.sections[0].roles[0].id = "bass guitar";
+
+    render(<SectionRoadmap song={song} activeRole={null} />);
+
+    const buttons = screen.getAllByRole("button", { name: /^Edit chord for / });
+    const descriptionIds = buttons.map((button) => button.getAttribute("aria-describedby"));
+    expect(descriptionIds.every((id) => typeof id === "string" && id.length > 0)).toBe(true);
+
+    const ids = descriptionIds.filter((id): id is string => id !== null);
+    expect(ids.every((id) => !/\s/.test(id))).toBe(true);
+    expect(new Set(ids).size).toBe(buttons.length);
+    for (const id of ids) {
+      expect(document.getElementById(id)?.textContent).toBe(
+        "Open an editable song to change this chord"
+      );
+    }
+  });
 });

apps/desktop/src/features/workspace/SectionRoadmap.tsx

@@ -87,6 +87,11 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
     return <CheckCircle2 className="size-4 text-emerald-200" aria-hidden="true" />;
   };
 
+  /** Return a renderer-owned, whitespace-free description ID for one unavailable chord action. */
+  const chordEditUnavailableDescriptionId = (sectionIndex: number, roleIndex: number): string => {
+    return `chord-edit-unavailable-${sectionIndex}-${roleIndex}`;
+  };
+
   return (
     <div className="mt-6 space-y-4">
       <div className="flex items-center justify-between">
@@ -103,7 +108,7 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
         tabIndex={0}
         aria-labelledby={sectionRoadmapTitleId}
       >
-        {song.sections.map((section) => (
+        {song.sections.map((section, sectionIndex) => (
           <Card
             key={section.id}
             className={`w-80 flex-none shrink-0 snap-start overflow-hidden shadow-[0_18px_60px_rgba(0,0,0,0.22)] transition duration-300 hover:-translate-y-1 hover:shadow-[0_24px_80px_rgba(0,0,0,0.32)] ${
@@ -124,7 +129,7 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
             <CardContent className="p-4 space-y-4">
               {section.roles
                 .filter(role => !activeRole || role.id === activeRole)
-                .map(role => (
+                .map((role, roleIndex) => (
                   <div
                     key={role.id}
                     className={`rounded-xl border-l-4 p-4 transition-all hover:translate-x-1 ${getPriorityColor(role.rehearsalPriority)}`}
@@ -152,7 +157,12 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
                         <button
                           type="button"
                           aria-label={editChordLabel(role, section.label)}
-                          className={`-ml-2 rounded px-2 py-0.5 text-lg font-black tracking-tight transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 ${
+                          aria-describedby={
+                            onSongUpdate
+                              ? undefined
+                              : chordEditUnavailableDescriptionId(sectionIndex, roleIndex)
+                          }
+                          className={`-ml-2 rounded px-2 py-0.5 text-lg font-black tracking-tight transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 aria-disabled:cursor-not-allowed aria-disabled:opacity-50 ${
                             onSongUpdate
                               ? "cursor-pointer hover:bg-white/10"
                               : "cursor-default"
@@ -161,12 +171,26 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
                               ? "bg-indigo-300/15 text-indigo-200"
                               : "text-cyan-100"
                           }`}
-                          onClick={() => handleChordEdit(section.id, role)}
-                          title={onSongUpdate ? t("chordEditTitle") : undefined}
-                          disabled={!onSongUpdate}
+                          onClick={(e) => {
+                            if (!onSongUpdate) {
+                              e.preventDefault();
+                              return;
+                            }
+                            handleChordEdit(section.id, role);
+                          }}
+                          title={onSongUpdate ? t("chordEditTitle") : t("chordEditUnavailableTitle")}
+                          aria-disabled={!onSongUpdate}
                         >
                           {role.harmony.chord}
                         </button>
+                        {!onSongUpdate && (
+                          <span
+                            id={chordEditUnavailableDescriptionId(sectionIndex, roleIndex)}
+                            className="sr-only"
+                          >
+                            {t("chordEditUnavailableTitle")}
+                          </span>
+                        )}
                         {role.harmony.source === "user" && (
                           <Badge variant="secondary" className="h-4 bg-indigo-300/20 px-1 text-[0.6rem] text-indigo-100 hover:bg-indigo-300/20">
                             {t("harmonySourceUserBadge")}

apps/desktop/src/locales/en/common.json

@@ -59,6 +59,7 @@
   "chordEditAriaLabel": "Edit chord for {roleName} in {sectionLabel}, current {chord}",
   "chordEditPrompt": "Enter new chord:",
   "chordEditTitle": "Click to edit chord",
+  "chordEditUnavailableTitle": "Open an editable song to change this chord",
   "harmonySourceUserBadge": "User",
   "roleSwitcherTitle": "Role-specific View",
   "allRoles": "All Roles",
@@ -149,4 +150,4 @@
   "practiceProgressLabel": "Practice Progress",
   "decreasePracticeProgressLabel": "Decrease progress",
   "increasePracticeProgressLabel": "Increase progress"
-}
+}

apps/desktop/src/locales/ko/common.json

@@ -59,6 +59,7 @@
   "chordEditAriaLabel": "{roleName}의 {sectionLabel} 코드 수정, 현재 {chord}",
   "chordEditPrompt": "새 코드 입력:",
   "chordEditTitle": "코드 수정",
+  "chordEditUnavailableTitle": "코드를 바꾸려면 편집 가능한 곡을 여세요",
   "harmonySourceUserBadge": "사용자",
   "roleSwitcherTitle": "악기/보컬 역할",
   "allRoles": "전체 보기",
@@ -149,4 +150,4 @@
   "practiceProgressLabel": "연습 진척도",
   "decreasePracticeProgressLabel": "진척도 감소",
   "increasePracticeProgressLabel": "진척도 증가"
-}
+}

docs/doctoring/accessible-disabled-chord-controls.md

@@ -0,0 +1,42 @@
+# Discoverable unavailable chord controls
+
+## Decision
+
+BandScope keeps the chord-edit button focusable when editing is unavailable because the action remains useful to discover during rehearsal. The control uses `aria-disabled="true"` rather than native `disabled`, blocks activation before the edit prompt, preserves its stable localized accessible name, and associates a localized recovery instruction with `aria-describedby`.
+
+The recovery copy is action-oriented: users are told to open an editable song to change the chord. The HTML `title` mirrors that recovery copy for pointer users, but BandScope does not treat `title` alone as sufficient assistive-technology evidence. The referenced description is the semantic explanation exposed for assistive technologies.
+
+## Conformance rationale
+
+WAI-ARIA 1.2 defines `aria-disabled` for elements that are perceivable but not operable, while `aria-describedby` identifies content that describes an object. The W3C ARIA Authoring Practices keyboard-interface guidance notes that unavailable controls can remain in the focus order when discoverability is important, using `aria-disabled` rather than native disabling where appropriate. The APG button pattern uses `aria-disabled="true"` for unavailable buttons, and the W3C ARIA1 technique documents `aria-describedby` as a programmatic association through an ID reference list whose referenced element IDs are unique.
+
+The HTML Standard additionally requires an element `id` to be unique in its tree, non-empty, and free of ASCII whitespace. BandScope therefore generates the description IDs from renderer-owned section and visible-role positions rather than from analysis-domain identifiers. This keeps the ARIA references unique and whitespace-free even when otherwise valid section or role IDs contain whitespace or punctuation, while leaving those domain identifiers unchanged for business logic.
+
+BandScope therefore verifies exact rendered values rather than inferring accessibility from CSS or source intent:
+
+- the unavailable chord control remains a button and remains keyboard-focusable;
+- `aria-disabled` renders exactly as `true`;
+- the accessible name remains the localized chord-edit action;
+- `aria-describedby` resolves to the exact localized recovery instruction;
+- description IDs remain unique and whitespace-free even when validated domain section or role IDs contain arbitrary string content;
+- the pointer `title` exposes the same recovery instruction;
+- activation does not open the edit prompt when the action is unavailable; and
+- enabled chord editing retains the existing localized action label, tooltip, prompt, and update behavior.
+
+## Scope boundary
+
+This change does not claim that a native `title` attribute implements the WAI-ARIA tooltip pattern. The APG tooltip pattern describes a distinct popup that appears on hover or keyboard focus and is referenced from the triggering element. If BandScope later requires a visible keyboard-focus popup, it should use the shared tooltip primitive and validate focus, dismissal, and description behavior explicitly.
+
+## References
+
+World Wide Web Consortium. (2023). *Accessible Rich Internet Applications (WAI-ARIA) 1.2*. https://www.w3.org/TR/wai-aria/
+
+World Wide Web Consortium, Web Accessibility Initiative. (2026, January 12). *ARIA1: Using the aria-describedby property to provide a descriptive label for user interface controls*. https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA1
+
+World Wide Web Consortium, Web Accessibility Initiative. (n.d.). *Button pattern*. ARIA Authoring Practices Guide. Retrieved August 15, 2026, from https://www.w3.org/WAI/ARIA/apg/patterns/button/
+
+World Wide Web Consortium, Web Accessibility Initiative. (n.d.). *Developing a keyboard interface*. ARIA Authoring Practices Guide. Retrieved August 15, 2026, from https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/
+
+World Wide Web Consortium, Web Accessibility Initiative. (n.d.). *Tooltip pattern*. ARIA Authoring Practices Guide. Retrieved August 15, 2026, from https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/
+
+WHATWG. (2026). *HTML Standard: The global attributes*. Retrieved August 15, 2026, from https://html.spec.whatwg.org/multipage/dom.html#the-id-attribute