From 5e93633cd3831a26b948b320144b0910f52855f0 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Wed, 5 Aug 2026 14:55:07 +0000
Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20[=EC=A0=91?=
 =?UTF-8?q?=EA=B7=BC=EC=84=B1=20=EA=B0=9C=EC=84=A0]=20=EA=B8=B0=EB=B3=B8?=
 =?UTF-8?q?=20=EB=B2=84=ED=8A=BC=EC=9D=98=20disabled=20=EC=86=8D=EC=84=B1?=
 =?UTF-8?q?=EC=9D=84=20aria-disabled=EB=A1=9C=20=EA=B5=90=EC=B2=B4?=
 =?UTF-8?q?=ED=95=98=EC=97=AC=20=ED=88=B4=ED=8C=81=20=EC=A0=9C=EA=B3=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

기본 HTML `<button>`의 `disabled` 속성을 사용할 경우 스크린 리더에서 요소를 완전히 무시하고 마우스 호버 이벤트도 차단되어 툴팁 기능이 작동하지 않는 문제가 있었습니다. 이를 해결하기 위해 `disabled` 대신 `aria-disabled="true"`를 사용하도록 수정하고 클릭 핸들러에서 비활성화 조건을 검사하도록 개선했습니다. 또한 키보드 포커스와 툴팁(title)이 정상적으로 제공되도록 업데이트했습니다.

참고: 공유 UI 컴포넌트인 `<Button>` (예: @base-ui/react 기반)은 내부적으로 native disabled 상태를 필요로 하므로, 시각적 회귀를 막기 위해 순수 기본 HTML 버튼들만 수정했습니다.
---
 .jules/palette.md                                      | 4 ++++
 apps/desktop/src/features/score/ScoreView.test.tsx     | 2 +-
 apps/desktop/src/features/score/ScoreView.tsx          | 5 +++--
 apps/desktop/src/features/workspace/SectionRoadmap.tsx | 6 +++---
 4 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/.jules/palette.md b/.jules/palette.md
index c05638899..72c399baf 100644
--- a/.jules/palette.md
+++ b/.jules/palette.md
@@ -1,3 +1,7 @@
 ## 2024-05-19 - Replace HTML disabled with aria-disabled="true" for Accessible Tooltips
 **Learning:** Native HTML `disabled` attributes completely hide elements from screen readers and block all pointer/hover events, preventing tooltips from functioning for disabled elements.
 **Action:** Replace `disabled` with `aria-disabled="true"`, enforce block click handlers via `e.preventDefault()`, and add a title tooltip directly to the element to maintain full tooltip accessibility and keyboard focus support for visually impaired and mouse users.
+
+## 2025-02-19 - Do not replace disabled prop in shared UI components
+**Learning:** Native `<button>` accessibility requires `aria-disabled` and conditional `onClick` handlers, but shared design system `<Button>` components (which wrap external primitives) may break if their native `disabled` prop is replaced.
+**Action:** When updating elements for accessibility, exclusively modify native HTML buttons, leaving existing shared `<Button>` elements (e.g., from `@base-ui`) intact to prevent visual regressions.
diff --git a/apps/desktop/src/features/score/ScoreView.test.tsx b/apps/desktop/src/features/score/ScoreView.test.tsx
index de4ccb95c..7ad035f19 100644
--- a/apps/desktop/src/features/score/ScoreView.test.tsx
+++ b/apps/desktop/src/features/score/ScoreView.test.tsx
@@ -96,7 +96,7 @@ describe("ScoreView", () => {
 
     expect(screen.getByText("Scores attach to the active analysis project.")).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "Add score" })).toBeDisabled();
-    expect(screen.getByRole("button", { name: "Open score: opener.pdf" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "Open score: opener.pdf" })).toHaveAttribute("aria-disabled", "true");
     expect(screen.getByRole("button", { name: "Remove: opener.pdf" })).toBeDisabled();
 
     fireEvent.click(screen.getByRole("button", { name: "Open score: opener.pdf" }));
diff --git a/apps/desktop/src/features/score/ScoreView.tsx b/apps/desktop/src/features/score/ScoreView.tsx
index 72732450f..ab2151f22 100644
--- a/apps/desktop/src/features/score/ScoreView.tsx
+++ b/apps/desktop/src/features/score/ScoreView.tsx
@@ -184,10 +184,11 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
                     <button
                       type="button"
                       onClick={projectId ? () => void openAttachment(projectId, attachment) : undefined}
-                      disabled={!projectId}
+                      aria-disabled={!projectId ? "true" : undefined}
                       aria-current={selected?.id === attachment.id ? "true" : undefined}
                       aria-label={`${t("scoreOpen")}: ${attachment.fileName}`}
-                      className="flex min-h-10 min-w-0 flex-1 items-center gap-2 text-left text-sm font-semibold text-slate-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 disabled:cursor-not-allowed disabled:opacity-60"
+                      title={!projectId ? t("scoreRequiresProject") : undefined}
+                      className="flex min-h-10 min-w-0 flex-1 items-center gap-2 text-left text-sm font-semibold text-slate-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 disabled:cursor-not-allowed disabled:opacity-60 aria-disabled:cursor-not-allowed aria-disabled:opacity-60"
                     >
                       <FileMusic className="size-4 shrink-0 text-cyan-300" aria-hidden="true" />
                       <span className="truncate">{attachment.fileName}</span>
diff --git a/apps/desktop/src/features/workspace/SectionRoadmap.tsx b/apps/desktop/src/features/workspace/SectionRoadmap.tsx
index 6f27c2509..16d94cd75 100644
--- a/apps/desktop/src/features/workspace/SectionRoadmap.tsx
+++ b/apps/desktop/src/features/workspace/SectionRoadmap.tsx
@@ -152,7 +152,7 @@ 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 ${
+                          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,9 +161,9 @@ export function SectionRoadmap({ song, activeRole, onSongUpdate }: SectionRoadma
                               ? "bg-indigo-300/15 text-indigo-200"
                               : "text-cyan-100"
                           }`}
-                          onClick={() => handleChordEdit(section.id, role)}
+                          onClick={onSongUpdate ? () => handleChordEdit(section.id, role) : undefined}
                           title={onSongUpdate ? t("chordEditTitle") : undefined}
-                          disabled={!onSongUpdate}
+                          aria-disabled={!onSongUpdate ? "true" : undefined}
                         >
                           {role.harmony.chord}
                         </button>

From 1998ba60f1728bb5e8ce7702fe4d0408433f3aaf Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Wed, 5 Aug 2026 15:28:16 +0000
Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20[=EC=A0=91?=
 =?UTF-8?q?=EA=B7=BC=EC=84=B1=20=EA=B0=9C=EC=84=A0]=20=EA=B8=B0=EB=B3=B8?=
 =?UTF-8?q?=20=EB=B2=84=ED=8A=BC=EC=9D=98=20disabled=20=EC=86=8D=EC=84=B1?=
 =?UTF-8?q?=EC=9D=84=20aria-disabled=EB=A1=9C=20=EA=B5=90=EC=B2=B4?=
 =?UTF-8?q?=ED=95=98=EC=97=AC=20=ED=88=B4=ED=8C=81=20=EC=A0=9C=EA=B3=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

기본 HTML `<button>`의 `disabled` 속성을 사용할 경우 스크린 리더에서 요소를 완전히 무시하고 마우스 호버 이벤트도 차단되어 툴팁 기능이 작동하지 않는 문제가 있었습니다. 이를 해결하기 위해 `disabled` 대신 `aria-disabled="true"`를 사용하도록 수정하고 클릭 핸들러에서 비활성화 조건을 검사하도록 개선했습니다. 또한 키보드 포커스와 툴팁(title)이 정상적으로 제공되도록 업데이트했습니다.

참고: 공유 UI 컴포넌트인 `<Button>` (예: @base-ui/react 기반)은 내부적으로 native disabled 상태를 필요로 하므로, 시각적 회귀를 막기 위해 순수 기본 HTML 버튼들만 수정했습니다.