Skip to content

a11y: fix the 39 todo stories' component bugs; popup stories wait; ratchet bans modern colour literals - #22

Merged
uzayer merged 2 commits into
mainfrom
ds-870-a11y-fixes
Nov 4, 2026
Merged

uzayer merged 2 commits into
mainfrom
ds-870-a11y-fixes

Conversation

@uzayer

@uzayer uzayer commented Nov 4, 2026

Copy link
Copy Markdown
Collaborator

Linear: ATL-870 (follow-up to #18: the 39 "todo" stories, popup waits, the ratchet's colour rule). Version not bumped. The README has no unreleased section, so the release note is at the end for you to fold in.

Summary

 components (the bug behind each todo)
~  ProfileMenu trigger         aria-label "Account — Name"   -> "UM, account — Name"   (label in name)
~  OrgSwitcher, collapsed      aria-label "Atlas"            -> "AT, Atlas"
+  SidebarItem link, collapsed aria-label={label}
~  Sidebar child <ul>          <span> rail                   -> the <ul>'s ::before   (a <ul> holds only <li>s)
+  UiScaleControl popover      aria-label "Interface scale"
+  SegmentMeter                label?: string   (MeterCard passes its own label)
+  CommandList                 "aria-label"? / "aria-labelledby"? -> its listbox
~  CommandPanel                role="listbox", except while a CommandEmpty is inside it
~  Select                      empty popup is role="presentation", not an empty listbox
+  DataTable scroller          tabIndex 0; its focus rings the whole card (as InputGroup does)
+  Code variant="block"        tabIndex 0
+  StreamingMarkdown           <pre> tabIndex 0; a GFM task checkbox is named for its item's words
~  ComboboxInput "Show options" tabIndex -1, as Base UI's own trigger is (our Button had set 0)

 stories
-  a11y: { test: "todo" }      x39, all removed
+  popup plays wait for the popup before axe runs: org switcher (menu, submenu), sidebar profile
+  and help menus, scale popover and its hint, context menu, hint overlay, command menu (Open,
+  ManyItems, LongText), app shell CommandOpen, toast seeds, Select Empty

 ratchet: colour-literal
   #hex | rgb( | hsl(                                   (unchanged)
+  oklch( | oklab( | lab( | lch( | hwb(  with arguments  ("oklch()" in prose passes)
+  color-mix( … a named colour … )      e.g. color-mix(in srgb, white 10%, …)
   color-mix of var()s, currentColor, transparent, ${interpolations}: still passes

Todo marks: all 39 removed. None remain.

Stories Fix
sidebar-controls (5), sidebar (6), app-shell (6) account name starts with the initials
org-switcher Collapsed, sidebar Collapsed, app-shell Collapsed collapsed org name starts with the initials; collapsed links are named
sidebar ChildActive the rail is ::before
ui-scale Open, AtMinimum popover named
command Empty, command-menu Empty CommandPanel drops listbox while empty
select Empty empty popup is not a listbox
command-palette InlineList CommandList aria-label
data-table ManyItems, Narrow scroller focusable
dot-matrix Meter, MeterHues; stat-card Meters, MeterNoHue SegmentMeter label
session-timeline Phone, streaming-markdown Long, code-block LongText <pre> / block <code> focusable
streaming-markdown Static task checkboxes labelled
combobox Open, Empty, ManyItems, LongText, Grouped trigger out of the tab order

The popup waits did not expose any new component bugs.

Behaviour changes worth knowing:

  • Tab no longer stops on the combobox's chevron. This matches Base UI's own tabIndex -1 for a trigger outside the popup, and the APG pattern: the input opens the list from the keyboard. Without it, axe fails all 5 open stories (checked by reverting the line).
  • Fences, block code and the data table's scroller are now tab stops.
  • The account and collapsed-org accessible names changed. Today only stories query them: web and desktop render their own copies of these shell components.

Known gaps, left as is:

  • Account name with a photo. The name keeps the initials even when the avatar shows a photo. The avatar's load state is Base UI's and isn't readable here.
  • Clear button while open. With showClear and the popup open, the clear button sits in the aria-hidden region. Base UI sets it to tabIndex -1, so axe doesn't flag it, but a screen reader can't reach it while the list is open. No story covers this.
  • Colour-rule misses. The rule doesn't see a named colour inside a nested call (var(--a, white)) or on a later line of a multi-line color-mix(), because the ratchet reads line by line. It is case-sensitive, like the rgb and hsl branches. A local helper function named lab(…), lch(…) or hwb(…) would be flagged.

Evidence

  • Before: bun run test:storybook showed 590 passed, 39 of them as todo warnings.
    After: 590 passed with no todo marks, on 3 consecutive runs.
  • Ratchet: new suite the colour-literal rule.
    • Flags oklch(0.7 0.12 250), bg-[oklab(…)], lab(…), lch(…), hwb(…), color-mix(in srgb, white 10%, …) and bg-[color-mix(in_srgb,40%_red,…)].
    • Passes the token mixes in popover.tsx and session.css, currentColor/transparent, srgb-linear/display-p3/longer hue, ${tone} interpolations, oklch() in prose and collab(x).
    • Still flags the hex, rgb() and hsl() cases.
    • The package's own sources pass with no new exemptions or allow comments.
    • Desktop's src/features, src/components and src/dev have 0 hits on the new branches.
  • Task checkboxes: streaming-markdown Static now asserts getByRole("checkbox", { name: "Port the sort" }).
  • Gates (local, macOS): typecheck, format:check, theme:check, test (356), build, test:consumer, build-storybook, storybook:smoke (590 stories) and test:storybook (590) all pass.
  • Screenshots: light and dark, in shots/ATL-870-a11y/. Focused data table, code block and fence; the open popups; the empty Select.
  • Sidebar rail: ChildActive was pixel-diffed before and after around the child rail. 0 pixels differ in dark and 4 in light, at the folder icons' edge (from their stagger animation), none on the rail.

Merge Danger

Door: two-way

Each fix is local to one component. Reverting the commits restores the todo marks.

Blast Radius: consumers

  • Ratchet: consumers that bump the pin get the stricter colour rule. Desktop has 0 hits today; web is unchecked.
  • Keyboard: the new tab stops (fences, code blocks, the data table) and the chevron dropping out of the tab order change keyboard paths.
  • Accessible names: any consumer test that queries the old account or collapsed-org names breaks.

Release note (for the upgrade notes): a11y fixes, with no visual change except focus rings.

  • New props: SegmentMeter takes label, and CommandList takes aria-label/aria-labelledby.
  • Tab stops: the data table scroller, block Code and markdown fences are tab stops.
  • Combobox: the chevron leaves the tab order.
  • Empty states: an empty CommandPanel/Select popup is not a listbox.
  • Names: the account trigger is now "<initials>, account — <name>", and the collapsed org switcher "<initials>, <name>".
  • Ratchet: colour-literal also bans oklch(), oklab(), lab(), lch(), hwb() and a color-mix() of a named colour.

…it; ratchet bans modern colour literals

Components:
- SidebarControls' account button and the collapsed OrgSwitcher start their
  names with the initials they show (label in name).
- Collapsed Sidebar links carry their label; the child list's rail is the
  <ul>'s ::before, so the list holds only <li>s.
- The interface-scale popover is named.
- SegmentMeter takes an optional label; MeterCard passes its own.
- CommandList passes aria-label/aria-labelledby to its listbox.
- CommandPanel stops being a listbox while a CommandEmpty is inside it;
  an empty Select popup stops being one too.
- DataTable's scroller, a block Code and markdown fences take keyboard
  focus; the table's focus rings the whole card.
- GFM task-list checkboxes are labelled.
- Combobox's Show options button is out of the tab order again, as Base
  UI's own trigger is; Button had put its tabIndex back.

Stories: every todo mark removed; popup stories wait for the popup before
axe runs (org switcher, sidebar menus, scale popover and hint, context
menu, hint overlay, command menu, app shell's command menu, toasts).

Ratchet: colour-literal also bans oklch(), oklab(), lab(), lch(), hwb()
with arguments, and a color-mix() of a named colour.
A GFM task's checkbox takes its item's words as its name, not a generic
"Task" (the fallback when an item has none). The combobox comment names
the real source of the stray tabIndex, and the color-mix() branch says
what it cannot see.
@uzayer
uzayer merged commit 0dbf69d into main Nov 4, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant