From c6220c54880d50691a62a3ca880c6897f3177f6e Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Mon, 8 Jun 2026 21:32:12 +0000
Subject: [PATCH] feat(web): improve accessibility of OverviewStats collapsible
 section

- Added `useId` to generate a unique ID for the collapsible container
- Added `aria-controls` and `aria-expanded` to the toggle button
- Added `aria-hidden="true"` to visual-only elements to reduce screen reader noise
- Documented learnings in `.Jules/palette.md`
---
 .Jules/palette.md                                     |  3 +++
 .../web/src/components/dashboard/overview-stats.tsx   | 11 ++++++++---
 2 files changed, 11 insertions(+), 3 deletions(-)
 create mode 100644 .Jules/palette.md

diff --git a/.Jules/palette.md b/.Jules/palette.md
new file mode 100644
index 0000000..e34464b
--- /dev/null
+++ b/.Jules/palette.md
@@ -0,0 +1,3 @@
+## 2025-02-23 - Accessible Collapsible Sections and Screen Reader Noise Reduction
+**Learning:** When creating collapsible UI sections (like "What do these numbers mean?"), it's crucial to semantically link the toggle button to the content container using `aria-controls="[id]"` and `aria-expanded={boolean}` so screen readers understand the relationship. Additionally, visual-only decorative elements and instructional text that is evident visually but redundant to the component's functionality (e.g. `— click to expand`) should be hidden from screen readers using `aria-hidden="true"` to reduce cognitive load and noise.
+**Action:** Always verify that custom disclose/expand widgets have an explicit `id` on the target container, `aria-controls` on the button, and properly synced `aria-expanded`. Audit buttons with complex inner HTML and apply `aria-hidden="true"` to spans that are purely visual or decorative.
diff --git a/packages/web/src/components/dashboard/overview-stats.tsx b/packages/web/src/components/dashboard/overview-stats.tsx
index cce93b6..c6592a5 100644
--- a/packages/web/src/components/dashboard/overview-stats.tsx
+++ b/packages/web/src/components/dashboard/overview-stats.tsx
@@ -44,6 +44,8 @@ function StatTile({ label, value, valueTone = 'default', subtext }: StatTileProp
   )
 }
 
+import { useId } from 'react'
+
 export function OverviewStats({
   periodLabel,
   sessions,
@@ -56,6 +58,7 @@ export function OverviewStats({
   rangeSelector,
 }: OverviewStatsProps) {
   const [expanded, setExpanded] = useState(false)
+  const detailsId = useId()
 
   return (
     <div className="rounded-xl bg-card ring-1 ring-foreground/10 p-4 sm:p-5">
@@ -85,15 +88,17 @@ export function OverviewStats({
       <button
         type="button"
         onClick={() => setExpanded(v => !v)}
+        aria-expanded={expanded}
+        aria-controls={detailsId}
         className="mt-4 flex items-center gap-2 text-xs text-muted-foreground hover:text-foreground transition-colors"
       >
-        <span className={cn('inline-block transition-transform', expanded && 'rotate-90')}>▸</span>
+        <span aria-hidden="true" className={cn('inline-block transition-transform', expanded && 'rotate-90')}>▸</span>
         <span className="font-medium text-foreground">What do these numbers mean?</span>
-        <span>— {expanded ? 'click to collapse' : 'click to expand'}</span>
+        <span aria-hidden="true">— {expanded ? 'click to collapse' : 'click to expand'}</span>
       </button>
 
       {expanded && (
-        <div className="mt-3 text-xs text-muted-foreground space-y-2 leading-relaxed">
+        <div id={detailsId} className="mt-3 text-xs text-muted-foreground space-y-2 leading-relaxed">
           <p>
             <span className="font-medium text-foreground">Sessions</span> — 팀원들이 시작한 Claude Code 세션 수.
           </p>