From 8572ec2f2d3d23bd89d17627300968a9cd246e56 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Sat, 1 Aug 2026 14:18:24 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20[UX=20improvement]=20?=
 =?UTF-8?q?=EC=95=85=EB=B3=B4=20=EB=B7=B0=20=EB=B9=84=ED=99=9C=EC=84=B1?=
 =?UTF-8?q?=ED=99=94=20=EB=B2=84=ED=8A=BC=20=EC=A0=91=EA=B7=BC=EC=84=B1=20?=
 =?UTF-8?q?=EA=B0=9C=EC=84=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .Jules/palette.md                             |  1 +
 .../src/features/score/ScoreView.test.tsx     | 13 +++-
 apps/desktop/src/features/score/ScoreView.tsx | 63 ++++++++++++-------
 3 files changed, 51 insertions(+), 26 deletions(-)

diff --git a/.Jules/palette.md b/.Jules/palette.md
index 5c1c16989..d09ffc315 100644
--- a/.Jules/palette.md
+++ b/.Jules/palette.md
@@ -37,3 +37,4 @@
 ## 2026-07-02 - Inline clear buttons preserve focus
 **Learning:** Inline clear buttons often unmount immediately after clearing state, which can drop keyboard focus to the document body.
 **Action:** Move focus back to the owning input before clearing state, and cover the behavior with a DOM focus test.
+## 2026-08-01 - Disabled icon-only buttons wrapping rule\n**Learning:** When using custom components (e.g., Base UI `<Button>`) that internally rely on the `disabled` prop to function, wrapping them in a focusable `span` is necessary to provide accessible tooltips on hover and focus. When adding tests, make sure to query these specific wrappers accurately (e.g. `screen.getAllByTitle(...)`).\n**Action:** Use a focusable `span` wrapper with `tabIndex={isDisabled ? 0 : -1}`, `title`, and `aria-disabled="true"` around `<Button>` components that must remain functionally disabled, and include `.sr-only` text.
diff --git a/apps/desktop/src/features/score/ScoreView.test.tsx b/apps/desktop/src/features/score/ScoreView.test.tsx
index de4ccb95c..554532f80 100644
--- a/apps/desktop/src/features/score/ScoreView.test.tsx
+++ b/apps/desktop/src/features/score/ScoreView.test.tsx
@@ -95,9 +95,16 @@ describe("ScoreView", () => {
     render(<ScoreView song={song} projectId={null} onSongUpdate={vi.fn()} />);
 
     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: "Remove: opener.pdf" })).toBeDisabled();
+
+    // Open score 버튼이 비활성화됨을 확인
+    expect(screen.getByRole("button", { name: "Open score: opener.pdf" })).toHaveAttribute("aria-disabled", "true");
+
+    const wrappers = screen.getAllByTitle("scoreNavDisabledHint");
+    // Add score 래퍼가 비활성화됨을 확인
+    expect(wrappers[0]).toHaveAttribute("aria-disabled", "true");
+    // Remove score 래퍼가 비활성화됨을 확인 (Open score 버튼에도 title이 있으므로 index가 다름)
+    const removeWrapper = wrappers.find(el => el.tagName.toLowerCase() === 'span' && el.querySelector('button[aria-label="Remove: opener.pdf"]'));
+    expect(removeWrapper).toHaveAttribute("aria-disabled", "true");
 
     fireEvent.click(screen.getByRole("button", { name: "Open score: opener.pdf" }));
     expect(mockInvoke).not.toHaveBeenCalled();
diff --git a/apps/desktop/src/features/score/ScoreView.tsx b/apps/desktop/src/features/score/ScoreView.tsx
index 72732450f..ebfae967a 100644
--- a/apps/desktop/src/features/score/ScoreView.tsx
+++ b/apps/desktop/src/features/score/ScoreView.tsx
@@ -133,19 +133,27 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
               </h2>
               <p className="mt-1 max-w-2xl text-sm text-slate-400">{t("scoreViewSubtitle")}</p>
             </div>
-            <Button
-              onClick={projectId ? () => void handleAttach(projectId) : undefined}
-              disabled={!projectId || isAttaching}
-              variant="secondary"
-              className="min-h-11 border border-cyan-300/20 bg-cyan-300/10 font-semibold text-cyan-50 hover:bg-cyan-300/20"
+            <span
+              tabIndex={!projectId ? 0 : -1}
+              title={!projectId ? t("scoreNavDisabledHint") : undefined}
+              aria-disabled={!projectId ? "true" : undefined}
+              className="inline-flex"
             >
-              {isAttaching ? (
-                <Loader2 className="mr-2 size-4 animate-spin" aria-hidden="true" />
-              ) : (
-                <FilePlus2 className="mr-2 size-4" aria-hidden="true" />
-              )}
-              {isAttaching ? t("scoreAttaching") : t("scoreAttach")}
-            </Button>
+              {(!projectId) && <span className="sr-only">{t("scoreNavDisabledHint")}</span>}
+              <Button
+                onClick={projectId ? () => void handleAttach(projectId) : undefined}
+                disabled={!projectId || isAttaching}
+                variant="secondary"
+                className="min-h-11 border border-cyan-300/20 bg-cyan-300/10 font-semibold text-cyan-50 hover:bg-cyan-300/20"
+              >
+                {isAttaching ? (
+                  <Loader2 className="mr-2 size-4 animate-spin" aria-hidden="true" />
+                ) : (
+                  <FilePlus2 className="mr-2 size-4" aria-hidden="true" />
+                )}
+                {isAttaching ? t("scoreAttaching") : t("scoreAttach")}
+              </Button>
+            </span>
           </div>
 
           {!projectId && (
@@ -184,24 +192,33 @@ export function ScoreView({ song, projectId, onSongUpdate }: ScoreViewProps) {
                     <button
                       type="button"
                       onClick={projectId ? () => void openAttachment(projectId, attachment) : undefined}
-                      disabled={!projectId}
+                      aria-disabled={!projectId ? "true" : undefined}
+                      title={!projectId ? t("scoreNavDisabledHint") : 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"
+                      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 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>
                     </button>
-                    <Button
-                      variant="outline"
-                      size="icon"
-                      onClick={projectId ? () => void handleRemove(projectId, attachment) : undefined}
-                      disabled={!projectId}
-                      aria-label={`${t("scoreRemove")}: ${attachment.fileName}`}
-                      className="size-10 border-rose-300/25 text-rose-200 hover:bg-rose-400/10"
+                    <span
+                      tabIndex={!projectId ? 0 : -1}
+                      title={!projectId ? t("scoreNavDisabledHint") : undefined}
+                      aria-disabled={!projectId ? "true" : undefined}
+                      className="inline-flex"
                     >
-                      <Trash2 className="size-4" aria-hidden="true" />
-                    </Button>
+                      {(!projectId) && <span className="sr-only">{t("scoreNavDisabledHint")}</span>}
+                      <Button
+                        variant="outline"
+                        size="icon"
+                        onClick={projectId ? () => void handleRemove(projectId, attachment) : undefined}
+                        disabled={!projectId}
+                        aria-label={`${t("scoreRemove")}: ${attachment.fileName}`}
+                        className="size-10 border-rose-300/25 text-rose-200 hover:bg-rose-400/10"
+                      >
+                        <Trash2 className="size-4" aria-hidden="true" />
+                      </Button>
+                    </span>
                   </li>
                 ))}
               </ul>