roboco/docs/ux_ui/design/tooltip-aria-label-spec.md

Tooltip / aria-label spec: which panel controls need which

Status: implemented (§1a–§1c complete, test coverage added)

Owner: ux-dev-1

Implementation status: All icon-only controls listed in §1a have been retrofitted with aria-label + title + matching Radix Tooltip (via PR #476). Test coverage is provided by per-control regression test files in panel/src/components/**/\__tests__/.

Last updated: 2026-07-11

Surface: every icon-bearing interactive control in panel/src/components — surveyed against the sidebar (layout/sidebar.tsx), header (layout/header.tsx), task detail (tasks/task-detail/, tasks/task-actions.tsx), kanban (kanban/core/, kanban/shared/), the dashboard queues (dashboard/*-queue.tsx, dashboard/command-center.tsx), and metrics (metrics/*.tsx).

Dial read

Per the team design bar, the panel is dense product UI, not a marketing surface:

• DESIGN_VARIANCE: 1 — this spec changes no layout or grid; it is a copy/markup rule for existing controls.
• MOTION_INTENSITY: 2 — tooltips use the existing Radix primitive (ui/tooltip.tsx), whose default fade/zoom-on-open is the motion budget; nothing in this spec adds a new transition.
• VISUAL_DENSITY: 8 — the panel packs many small icon-only affordances per row (kanban cards, table action cells, queue rows); the density rule most relevant here is the "noisy vs. informative" line in §3 — every tooltip added to a dense row is one more thing competing for attention, so it must earn its place.

Problem (Resolved)

This spec resolved the panel's mixed accessible-naming strategies for icon-only controls by establishing a single rule: all icon-only controls must carry a mandatory aria-label (§1a), optionally with a matching visible Tooltip (§1b).

All controls listed below have been retrofitted to the correct pattern (verified 2026-07-11):

Component	Pattern	Test Coverage
layout/header.tsx:59-68 (refresh button)	✅ aria-label + title + Tooltip	✅ header.test.tsx
ui/copy-button.tsx:64-74	✅ aria-label + title + Tooltip	✅ Implicit (component pattern)
kanban/core/kanban-card.tsx:237-253 (move-forward button)	✅ aria-label + title + Tooltip	✅ kanban-card-aria.test.tsx
notifications/notification-bell.tsx:24-31 (bell button)	✅ aria-label + title + Tooltip	✅ notification-bell.test.tsx (NEW)
tasks/task-detail/task-header.tsx:476-478 (back-arrow button)	✅ aria-label + title + Tooltip	❌ Not covered — header.test.tsx only renders layout/header.tsx, not this component
tasks/task-actions.tsx:145-147 (overflow-menu trigger)	✅ aria-label + title + Tooltip	❌ Not covered — header.test.tsx only renders layout/header.tsx, not this component
layout/sidebar.tsx:170-182 (collapse-rail toggle)	✅ aria-label + title + Tooltip	✅ sidebar.test.tsx
kanban/core/kanban-card.tsx:122-128 (drag handle)	✅ aria-label + title + Tooltip	✅ kanban-card-aria.test.tsx
kanban/shared/assignee-avatar.tsx (initials badge)	✅ aria-label + Tooltip with full name	✅ assignee-avatar.test.tsx

Separately, some controls that DO have a visible label still lack a tooltip where one would help (kanban/shared/assignee-avatar.tsx shows only two-letter initials, with nothing disambiguating which agent that is), while others already use tooltips correctly for genuinely supplementary info (kanban-card.tsx:137-151's sequence-number badge, header.tsx:35-50's "Coming Soon" search tooltip).

This spec gives every future control a three-way answer — mandatory aria-label, recommended tooltip, or neither — plus the copy rule for whichever applies.

1. Classification

1a. aria-label is mandatory

Any interactive control (button, a Link/<a> wrapping a Button, a dropdown/popover trigger) whose only visible content is an icon. No exceptions — this is a WCAG requirement, not a style preference (see §4).

Examples already in the codebase that need this fixed:

• notifications/notification-bell.tsx:24 — <Button variant="ghost" size="icon"> wrapping only a Bell icon.
• tasks/task-detail/task-header.tsx:476 — the back-arrow Button wrapping only ArrowLeft.
• tasks/task-actions.tsx:145 — the DropdownMenuTrigger's Button wrapping only MoreHorizontal.
• layout/sidebar.tsx:170 — the collapse-rail toggle Button wrapping only ChevronLeft.
• kanban/core/kanban-card.tsx:122-128 — the drag handle (GripVertical); a drag handle needs an accessible name even though its primary interaction is pointer-based, because useDraggable's attributes/listeners also expose it to keyboard/AT-driven reordering.
• kanban/core/kanban-card.tsx:237-253 — the move-forward button has title but no aria-label; add one (title can stay as a mouse-hover supplement).
• dashboard/command-center.tsx:107 — the Settings gear button.
• dashboard/pr-review-queue.tsx:206-214 — the FileText "review details" link button; its title currently lives on the wrapping Link, not the Button itself, which is where AT resolves the accessible name from.

Correct existing pattern to copy: layout/header.tsx:59-68 and ui/copy-button.tsx:64-74 — both set aria-label as the primary accessible name and title as a same-text mouse-hover supplement.

1b. Tooltip is recommended (not code-required, but good practice)

A tooltip earns its place when the control's visible content (icon, badge, truncated text, or initials) doesn't fully convey what a user needs, and the extra information doesn't fit as visible text without breaking the density budget:

• Icon-only controls that already carry a mandatory aria-label (§1a) should also carry a matching visible tooltip for sighted mouse users — the aria-label serves AT, the tooltip serves everyone else. This is already the pattern at header.tsx:59-68.
• Truncated or abbreviated content standing in for the full value: assignee-avatar.tsx shows only two-letter initials — wrap it in a Tooltip showing the full agent slug/name, matching the pattern kanban-card.tsx:137-151 already uses for the sequence-number badge.
• A disabled or not-yet-available control: header.tsx:35-50's search input tooltip ("Coming Soon") is the reference example — the control's disabled state isn't self-explanatory from the input alone.
• A secondary/derived value alongside a primary display value: kanban-card.tsx:107-111 and task-header.tsx:508-514 already put the full task UUID in a title attribute next to the truncated #12345678 display — correct instinct, though per §4 a plain title is a weaker mechanism than a Tooltip component for anything besides a supplementary hover hint on an already-labeled element.

1c. Neither is needed

• Controls with a visible text label — kanban-card.tsx's "Assign" / "Pass" / "Fail" buttons (UserPlus/CheckCircle/XCircle icon + text), the sidebar nav items when expanded (layout/sidebar.tsx:99-100, icon + <span>{item.title}</span>). The visible text already is the accessible name; a tooltip repeating it is noise (see §3).
• Self-labeling badges — kanban/shared/priority-indicator.tsx renders the full label text ("P0 - Highest", not just a color swatch or icon), so it needs no supplementary tooltip.
• Decorative icons paired with adjacent visible text — e.g. any icon next to a CardTitle heading in the metrics tabs (metrics/delivery-tab.tsx, metrics/scorecards-tab.tsx) where the heading text alone identifies the section; these icons should carry aria-hidden="true" rather than an aria-label, since the adjacent text is already the accessible name and a redundant label would be announced twice.
• Recharts' built-in <Tooltip> (metrics/delivery-tab.tsx:9) — this is a chart data-point tooltip, a different concern from the UI-affordance tooltips this spec governs. Out of scope here; recharts renders it via its own accessible SVG layer.

2. Copy guidance per category

• aria-label text: a short verb-phrase naming the action, not the icon — "Refresh only the current page" (header.tsx:64), not "Refresh icon" or "RefreshCw". State what happens, not what the button looks like. Keep it a complete accessible name on its own — a screen reader user never sees the visible tooltip text, so the label can't rely on surrounding context the way a sighted-only tooltip can.
• Tooltip text: one short sentence fragment, no trailing period, matching the existing style ("Sequence #{n}", "Awaiting session creation by PM", "Coming Soon"). Never restate the control's own visible label verbatim — a tooltip on the "Assign" button that just says "Assign" adds nothing. State the why or the full value, not the what the icon already shows.
  • No em-dash, no filler verbs ("Elevate", "Seamless", "Unleash") — this is a dense product UI, not marketing copy.
  • No invented specificity — if the underlying value is genuinely just an agent's short ID, show the short ID; don't dress it up.
• When aria-label and tooltip text overlap (the common case for an icon-only button per §1b), use the same string for both, exactly as header.tsx:64-65 and copy-button.tsx:68-69 already do — one source of truth, no drift between what a mouse user reads and what a screen reader announces.

3. Informative vs. noisy tooltip use

At VISUAL_DENSITY: 8, the panel's kanban cards, table rows, and queue items already stack several badges/icons/avatars per row (see kanban-card.tsx's badge row at lines 131-169). Every tooltip added to that row is one more hover-triggered layer competing with the surrounding chrome, so the bar for adding one is:

Informative (add it):

• Disambiguates content that is otherwise ambiguous or truncated — initials (assignee-avatar.tsx), a shortened UUID, a numeric badge whose meaning isn't obvious from the icon alone (the Hash + number sequence badge).
• Explains why a control is disabled or unavailable, not just that it is (header.tsx's "Coming Soon" search).
• Is the sole accessible-name source for an icon-only control (§1a/§1b) — this is structurally required, not a density trade-off.

Noisy (skip it):

• Restates a visible text label the control already shows ("Assign" tooltip on an "Assign" button).
• Adds a tooltip to every icon in a card "for consistency" regardless of whether that icon's meaning is already clear from context — priority-indicator.tsx's full-text badge needs no tooltip precisely because it already states its own meaning; adding one anyway would be chrome for its own sake.
• Duplicates information already visible one glance away in the same row (e.g. a tooltip on the team Badge in kanban-card.tsx:133-135 repeating the team name that's already the badge's own text).
• Would fire on every hover across a dense grid of many small elements, adding motion/layer churn that exceeds this panel's MOTION_INTENSITY: 2 budget for incidental UI (the Radix tooltip's fade/zoom is fine for one deliberate affordance per control; scattering it across every icon in a row is not).

The underlying rule from the design bar: hierarchy and information come from what's already visible (weight, size, color, spacing) wherever that's sufficient; a tooltip is the fallback for the specific cases in §1a/§1b where visible content alone can't carry the full meaning — not a default layered onto every icon.

4. WCAG AA requirement: aria-label is mandatory for icon-only controls

Per WCAG 2.1 Level AA, every interactive control needs a programmatically determinable accessible name:

• 1.1.1 Non-text Content — a non-text element (an icon standing in for a control's label) must have a text alternative that serves the same purpose.
• 4.1.2 Name, Role, Value — for all UI components, the name and role must be programmatically determinable, and the name must be exposed to assistive technology.

For an icon-only button/Link-as-button in this codebase, that means aria-label (or, where the label needs to reference other visible content, aria-labelledby) is mandatory — not optional, not "nice to have" — whenever the control has no visible text child. A title attribute alone is not sufficient: it is the accessible-name source of last resort in the browser accnaming spec, it is not reliably exposed by every screen reader (particularly on touch/mobile, where there is no hover to trigger it), and it does not satisfy 4.1.2 on its own in practice across the AT matrix. title may still be present as a mouse-hover supplement (matching header.tsx:64-65's pattern of setting both), but it never substitutes for aria-label.

Any icon-only control shipped without an aria-label — including every example listed in §1a — is an AA accessibility defect, independent of whether it also carries a visible Tooltip; a Tooltip's content is not exposed to AT by default either (ui/tooltip.tsx's Radix primitive renders visually, and needs aria-label on the trigger to be accessible — it does not supply one for free).

Implementation notes

• Retrofit complete (PR #476 + regression tests): All gaps in §1a have been fixed using the existing ui/tooltip.tsx Radix wrapper and plain aria-label/title attributes. The pattern is now uniform across all icon-only controls.
• Test coverage: Most retrofitted controls have a regression test verifying the aria-label, title, and Tooltip content match per §2 — see the coverage table above for which controls still lack a dedicated test.
• No new dependency: Everything uses the existing ui/tooltip.tsx Radix wrapper, already in use elsewhere.
• Out of scope: Recharts' internal chart-tooltip behavior (§1c) — that's a data-visualization concern, not a UI-affordance one.