From bab8f563479a2f685ff1bfc9976326935ef29dee Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Wed, 9 Sep 2026 04:11:39 +0000 Subject: [PATCH 01/45] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Add=20tooltips?= =?UTF-8?q?=20explaining=20disabled=20Settings=20and=20Help=20buttons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .jules/palette.md | 6 ++--- apps/desktop/src/App.tsx | 49 ++++++++++++++++++++++++---------------- 2 files changed, 32 insertions(+), 23 deletions(-) diff --git a/.jules/palette.md b/.jules/palette.md index c05638899..0379b3823 100644 --- a/.jules/palette.md +++ b/.jules/palette.md @@ -1,3 +1,3 @@ -## 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. +## 2026-09-09 - Accessible Tooltips on Disabled Elements +**Learning:** Native `title` attributes on `disabled` or `aria-disabled` elements do not reliably announce content to screen readers or display visually across all browsers in a consistent manner, especially for icon-only buttons. +**Action:** When creating icon-only buttons that may be disabled, use `aria-disabled="true"` instead of the native `disabled` attribute so they can remain focusable, and wrap them in a custom, accessible `Tooltip` component from the design system to clearly explain the disabled state (e.g., "Coming soon"). diff --git a/apps/desktop/src/App.tsx b/apps/desktop/src/App.tsx index f3d678454..55a4748e1 100644 --- a/apps/desktop/src/App.tsx +++ b/apps/desktop/src/App.tsx @@ -48,6 +48,7 @@ import { ScoreView } from "./features/score/ScoreView"; import { Workspace } from "./features/workspace/Workspace"; import { EmptyState, ErrorState, LoadingState } from "./features/workspace/WorkspaceStates"; import { Button } from "@/components/ui/button"; +import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"; import { Input } from "@/components/ui/input"; import { Progress } from "@/components/ui/progress"; import { Toaster } from "@/components/ui/sonner"; @@ -611,26 +612,34 @@ export function App() {
- - + + + + + {t("settingsComingSoon")} + + + + + + + {t("helpComingSoon")} + +
From 885551e8d81ebe16856a549fcfb80441df8a52d3 Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Wed, 9 Sep 2026 04:37:45 +0000 Subject: [PATCH 02/45] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Add=20tooltips?= =?UTF-8?q?=20explaining=20disabled=20Settings=20and=20Help=20buttons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- services/analysis-engine/tests/test_supply_chain_policy.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/services/analysis-engine/tests/test_supply_chain_policy.py b/services/analysis-engine/tests/test_supply_chain_policy.py index 1d8224c5a..6a0853944 100644 --- a/services/analysis-engine/tests/test_supply_chain_policy.py +++ b/services/analysis-engine/tests/test_supply_chain_policy.py @@ -1275,9 +1275,7 @@ def test_workflow_concurrency_cancels_only_superseded_pr_heads() -> None: workflow = (workflows_dir / workflow_name).read_text(encoding="utf-8") assert "concurrency:" in workflow, workflow_name assert "cancel-in-progress: false" in workflow, workflow_name - assert "contents: read" in workflow or "permissions: read-all" in workflow, ( - workflow_name - ) + assert "contents: read" in workflow or "permissions: read-all" in workflow, workflow_name assert "pull_request:" not in (workflows_dir / "release.yml").read_text(encoding="utf-8") From 26055edcadacde997191cb1ad2c558d950f48b6c Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Wed, 9 Sep 2026 05:18:44 +0000 Subject: [PATCH 03/45] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Add=20tooltips?= =?UTF-8?q?=20explaining=20disabled=20Settings=20and=20Help=20buttons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 2d678ee2aecf3a3caf7faf8fc6a92d8074f8ab9f Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Wed, 9 Sep 2026 05:41:35 +0000 Subject: [PATCH 04/45] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Add=20tooltips?= =?UTF-8?q?=20explaining=20disabled=20Settings=20and=20Help=20buttons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From cb92397039b48c6893b12e521584e61da89075e3 Mon Sep 17 00:00:00 2001 From: seonghobae <8172694+seonghobae@users.noreply.github.com> Date: Wed, 9 Sep 2026 05:51:45 +0000 Subject: [PATCH 05/45] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Add=20tooltips?= =?UTF-8?q?=20explaining=20disabled=20Settings=20and=20Help=20buttons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From 1ce663816be4fc2e84b5d444c052b9afea126ee1 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 9 Sep 2026 20:07:39 +0900 Subject: [PATCH 06/45] test(ui): pin tooltip locale and reduced-motion resilience --- .../components/ui/tooltip.resilience.test.tsx | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 apps/desktop/src/components/ui/tooltip.resilience.test.tsx diff --git a/apps/desktop/src/components/ui/tooltip.resilience.test.tsx b/apps/desktop/src/components/ui/tooltip.resilience.test.tsx new file mode 100644 index 000000000..9ea9a68b8 --- /dev/null +++ b/apps/desktop/src/components/ui/tooltip.resilience.test.tsx @@ -0,0 +1,23 @@ +import { render } from "@testing-library/react" +import { describe, expect, it } from "vitest" + +import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip" + +describe("Tooltip resilience contract", () => { + it("bounds expanded locale copy and disables decorative motion when requested", () => { + render( + + Settings + + Einstellungen sind in dieser Version noch nicht verfügbar und werden später bereitgestellt. + + + ) + + const tooltipContent = document.querySelector('[data-slot="tooltip-content"]') + expect(tooltipContent).toBeTruthy() + expect(tooltipContent).toHaveClass("max-w-[min(20rem,calc(100vw-2rem))]") + expect(tooltipContent).toHaveClass("break-words") + expect(tooltipContent).toHaveClass("motion-reduce:transition-none") + }) +}) From 8cb4eea4359589cf63d15463973edd1521baed58 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 9 Sep 2026 20:07:59 +0900 Subject: [PATCH 07/45] fix(ui): bound tooltip expansion and reduced motion --- apps/desktop/src/components/ui/tooltip.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/desktop/src/components/ui/tooltip.tsx b/apps/desktop/src/components/ui/tooltip.tsx index 8b954764b..790da93b1 100644 --- a/apps/desktop/src/components/ui/tooltip.tsx +++ b/apps/desktop/src/components/ui/tooltip.tsx @@ -36,8 +36,8 @@ function TooltipContent({ Date: Wed, 9 Sep 2026 20:08:29 +0900 Subject: [PATCH 08/45] docs(ui): record disabled tooltip interaction boundary --- .jules/palette.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.jules/palette.md b/.jules/palette.md index 0379b3823..092cd02ef 100644 --- a/.jules/palette.md +++ b/.jules/palette.md @@ -1,3 +1,3 @@ ## 2026-09-09 - Accessible Tooltips on Disabled Elements -**Learning:** Native `title` attributes on `disabled` or `aria-disabled` elements do not reliably announce content to screen readers or display visually across all browsers in a consistent manner, especially for icon-only buttons. -**Action:** When creating icon-only buttons that may be disabled, use `aria-disabled="true"` instead of the native `disabled` attribute so they can remain focusable, and wrap them in a custom, accessible `Tooltip` component from the design system to clearly explain the disabled state (e.g., "Coming soon"). +**Learning:** `aria-disabled="true"` exposes unavailable state but does not suppress activation. Icon-only controls therefore need an accessible name independent of the tooltip, and unavailable activation must still be blocked in code. +**Action:** Keep unavailable icon buttons focusable with `aria-disabled="true"`, give the trigger an `aria-label` matching the Tooltip text, and route pointer or keyboard-generated clicks through `preventUnavailableAction`. Use the design-system Tooltip only to explain the unavailable state; do not log or expose user-controlled values through tooltip copy. From e31f32e01afdac4db02fb152e364d7dafd760fb1 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 9 Sep 2026 20:11:04 +0900 Subject: [PATCH 09/45] docs(ui): doctor disabled tooltip accessibility boundary --- docs/doctoring/sidebar-disabled-tooltips.md | 52 +++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/doctoring/sidebar-disabled-tooltips.md diff --git a/docs/doctoring/sidebar-disabled-tooltips.md b/docs/doctoring/sidebar-disabled-tooltips.md new file mode 100644 index 000000000..8b32a10cf --- /dev/null +++ b/docs/doctoring/sidebar-disabled-tooltips.md @@ -0,0 +1,52 @@ +# Sidebar disabled-tooltip accessibility boundary + +## Problem and buyer impact + +The Settings and Help controls are intentionally unavailable but remain discoverable in the sidebar. Native `title` text is not the product authority for the unavailable state: the icon-only triggers need an accessible name independent of tooltip rendering, activation must remain suppressed while `aria-disabled="true"` keeps the controls in the focus order, and tooltip copy must remain readable when translated text expands or the viewport narrows. + +The shared Tooltip primitive also used an opacity transition for appearance/disappearance without an explicit reduced-motion override. The effect is small, but it is decorative rather than necessary to convey state, so the primitive should respect the operating-system/browser reduced-motion preference. + +## Constraints + +- Keep Settings and Help unavailable; this slice does not implement either feature. +- Keep the controls keyboard-discoverable and expose the same localized unavailable-state text as the accessible name and tooltip explanation. +- `aria-disabled` is semantic state, not an interaction lock. Existing `preventUnavailableAction` remains responsible for suppressing pointer- and keyboard-generated activation. +- Do not create a second locale ledger or copy translation authority into the Tooltip primitive. +- Long translated text must wrap within the viewport instead of depending on a fixed English-sized popup. +- The primitive must not claim browser, Narrator, VoiceOver, touch, or visual acceptance from jsdom/class assertions alone. + +## Decision + +The sidebar uses the existing design-system `Tooltip`, with `TooltipTrigger` retaining `aria-disabled="true"`, a localized `aria-label`, and `preventUnavailableAction`. The shared popup gains a viewport-bounded maximum width, word breaking for long tokens, and `motion-reduce:transition-none` for its decorative opacity transition. + +A focused regression renders expanded German tooltip copy and pins the responsive/reduced-motion class contract. This is deliberately a component contract rather than a product-level accessibility acceptance test. + +Alternatives rejected: + +- Native `disabled`: removes these currently unavailable controls from ordinary keyboard focus and defeats the chosen discoverability contract. +- `aria-disabled` without an event guard: exposes state but leaves activation behavior enabled. +- Tooltip-only naming: makes the accessible name depend on popup behavior rather than the trigger itself. +- Fixed popup width sized for English/Korean: does not address CJK/European-language expansion or narrow viewports. +- Removing all Tooltip animation globally: unnecessary; honoring the user preference is the narrower control. + +## Evidence and claim boundary + +MDN states that `aria-disabled="true"` communicates disabled semantics but does not suppress functionality; developers must suppress behavior themselves. W3C WCAG 2.2 SC 1.4.10 explains that ordinary text content should reflow within a viewport rather than force two-dimensional scrolling. MDN defines `prefers-reduced-motion` as the user preference for reducing non-essential motion. These sources support the chosen interaction, wrapping, and motion-preference boundaries; they do not prove BandScope conformance by themselves. + +Current automated evidence covers DOM semantics already present in `App.test.tsx` plus the Tooltip class contract. Current-head browser geometry, actual hover/focus popup placement, forced-colors behavior, Narrator/VoiceOver announcements, pointer/touch behavior, 400% zoom, and KO/EN/JA/ZH/VI/ES/DE/FR rendered acceptance remain separate UI Delivery Gate evidence. + +## TRACEABILITY + +- Sidebar product integration: `apps/desktop/src/App.tsx` +- Shared primitive: `apps/desktop/src/components/ui/tooltip.tsx` +- Existing focusable unavailable-control contract: `apps/desktop/src/App.test.tsx` +- Expanded-copy/reduced-motion regression: `apps/desktop/src/components/ui/tooltip.resilience.test.tsx` +- Reviewer learning note: `.jules/palette.md` + +## References + +Mozilla Developer Network. (2025, November 6). *ARIA: aria-disabled attribute*. MDN Web Docs. https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-disabled + +Mozilla Developer Network. (2026, June 10). *prefers-reduced-motion CSS media feature*. MDN Web Docs. https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion + +W3C Accessibility Guidelines Working Group. (2026, August 10). *Understanding Success Criterion 1.4.10: Reflow*. W3C Web Accessibility Initiative. https://www.w3.org/WAI/WCAG22/Understanding/reflow From c3ae33681974dcb3bfeabfd7140fb2a9a4702113 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 9 Sep 2026 20:13:53 +0900 Subject: [PATCH 10/45] test(ui): verify Base UI tooltip trigger forwarding --- .../components/ui/tooltip.resilience.test.tsx | 32 +++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/apps/desktop/src/components/ui/tooltip.resilience.test.tsx b/apps/desktop/src/components/ui/tooltip.resilience.test.tsx index 9ea9a68b8..df187580e 100644 --- a/apps/desktop/src/components/ui/tooltip.resilience.test.tsx +++ b/apps/desktop/src/components/ui/tooltip.resilience.test.tsx @@ -1,9 +1,37 @@ -import { render } from "@testing-library/react" -import { describe, expect, it } from "vitest" +import { fireEvent, render, screen } from "@testing-library/react" +import { describe, expect, it, vi } from "vitest" import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip" describe("Tooltip resilience contract", () => { + it("keeps Base UI trigger button semantics and native props", () => { + const onClick = vi.fn() + + render( + + + Settings + + Settings coming soon + + ) + + const trigger = screen.getByRole("button", { name: "Settings coming soon" }) + expect(trigger.tagName).toBe("BUTTON") + expect(trigger).toHaveAttribute("type", "button") + expect(trigger).toHaveAttribute("aria-disabled", "true") + expect(trigger).toHaveClass("focus-contract") + + fireEvent.click(trigger) + expect(onClick).toHaveBeenCalledTimes(1) + }) + it("bounds expanded locale copy and disables decorative motion when requested", () => { render( From fc5ba90985767e6c455ed7af83742b6dd0b1ee05 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 9 Sep 2026 20:14:32 +0900 Subject: [PATCH 11/45] docs(ui): trace Base UI trigger forwarding evidence --- docs/doctoring/sidebar-disabled-tooltips.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/doctoring/sidebar-disabled-tooltips.md b/docs/doctoring/sidebar-disabled-tooltips.md index 8b32a10cf..328dde49e 100644 --- a/docs/doctoring/sidebar-disabled-tooltips.md +++ b/docs/doctoring/sidebar-disabled-tooltips.md @@ -19,13 +19,16 @@ The shared Tooltip primitive also used an opacity transition for appearance/disa The sidebar uses the existing design-system `Tooltip`, with `TooltipTrigger` retaining `aria-disabled="true"`, a localized `aria-label`, and `preventUnavailableAction`. The shared popup gains a viewport-bounded maximum width, word breaking for long tokens, and `motion-reduce:transition-none` for its decorative opacity transition. -A focused regression renders expanded German tooltip copy and pins the responsive/reduced-motion class contract. This is deliberately a component contract rather than a product-level accessibility acceptance test. +A focused regression renders expanded German tooltip copy and pins the responsive/reduced-motion class contract. The same regression verifies the exact component-library integration: BandScope locks `@base-ui/react` 1.7.0, whose `TooltipTrigger` explicitly renders a ` + ) : ( + + + {buttonContent} + + {title && {title}} + ); })} @@ -611,26 +630,30 @@ export function App() {
- - + + + + {t("settingsComingSoon")} + + + + + {t("helpComingSoon")} +
@@ -641,26 +664,45 @@ export function App() { const { label, enabled, active, title } = navButtonState(item); const { icon: Icon, view } = item; - return ( + const buttonClass = `inline-flex min-h-10 shrink-0 items-center gap-2 rounded-xl px-3 text-sm font-semibold transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-300 ${ + active + ? "bg-blue-600/70 text-white" + : enabled + ? "text-slate-200 hover:bg-white/5" + : "cursor-not-allowed text-slate-500 opacity-70" + }`; + + const buttonContent = ( + <> +