Improve accessibility across Kumo components, charts, and docs

[pedromenezes1]

This PR addresses accessibility gaps across Kumo’s component library, chart interactions, installable blocks, and docs examples.

The main goals are to improve screen reader context, keyboard and pointer access, reduced-motion behavior, localized accessibility copy, and form error associations without broad UI rewrites.

Components

• CommandPalette

  • Add a localizable dialogTitle so the dialog has an accessible name.
  • Add live-region support for loading and empty states.
  • Add busy support on the list so async result loading can be announced.
  • Update docs examples to show localized dialog and loading text.

• SensitiveInput

  • Replace the nested interactive masked container with native reveal/copy controls.
  • Add localizable labels and status text for reveal, hide, copy, copied, and hidden states.
  • Remove generic primary accessible names like “Sensitive value.”
  • Add warnings when no accessible name is provided.
  • Improve copy/reveal target areas with non-layout hit areas where possible.
  • Keep decorative icons hidden from assistive tech.

• Switch

  • Remove the generic "Switch" fallback accessible name.
  • Add warnings when no label, aria-label, or aria-labelledby is provided.
  • Associate group descriptions and errors with the group.
  • Add aria-invalid and announced error text for invalid groups.
  • Preserve the visual track size while improving the interactive hit area.

• Button

  • Warn when any icon-only button lacks an accessible name, not only square or circle buttons.
  • Mark decorative icons as hidden from assistive tech.
  • Improve compact/icon hit areas without broadly increasing visual size.

• Checkbox, Radio, and Switch groups

  • Generate stable IDs for group descriptions and errors.
  • Wire aria-describedby and aria-invalid to the group.
  • Announce group validation errors with role="alert".

• Select, Combobox, Autocomplete, SensitiveInput, and InputGroup

  • Improve helper and error association when controls use aria-label or aria-labelledby instead of a visible label.
  • Set aria-describedby and aria-invalid on the actual focusable control.
  • Avoid empty label output when no visible label is provided.

• Combobox and Autocomplete

  • Add accessible-name warnings for placeholder-only usage.
  • Preserve aria-label and aria-labelledby pass-through.
  • Document existing localized labels for clear, show-options, remove-chip, and empty-state text.
  • Improve compact control hit areas with pseudo-element targets where possible.

• Breadcrumbs

  • Add localizable labels for the breadcrumb navigation landmark, copy action, copy tooltip, and copied feedback.
  • Hide decorative breadcrumb icons and separators from assistive tech.
  • Reveal the clipboard action on keyboard focus as well as hover.

• Table

  • Use localized labels for selection checkboxes.
  • Allow localized labels for resize handles.
  • Improve resize handle hit areas while keeping the visual affordance slim.
  • Add targeted metadata so Kumo-owned table subcomponent props are documented without exposing inherited ARIA props globally.

Charts

• Chart wrapper

  • Add explicit accessible label and description support.
  • Preserve user ECharts aria options while adding accessible defaults.
  • Respect reduced-motion preferences without clobbering user chart options.

• TimeseriesChart

  • Add accessible loading announcements.
  • Add keyboard and single-pointer time-range controls so users do not need to drag-brush the chart.
  • Add localizable labels and formatting hooks for the fallback range controls.
  • Preserve existing brush behavior.

• SankeyChart

  • Add accessible labels and descriptions.
  • Enable ECharts aria support.
  • Add keyboard-accessible node and link action fallbacks.
  • Add localizable action labels.

• ChartLegend

  • Render static legend items as plain content instead of buttons.
  • Render interactive legend items as native buttons.
  • Expose toggle state with aria-pressed.
  • Improve small legend item hit areas without changing compact visuals.

Blocks

• DeleteResource
  • Use alert-dialog semantics for destructive confirmations.
  • Wire warning copy as the dialog description.
  • Announce error banners with alert semantics.

Docs

• Add a skip link so keyboard users can bypass repeated navigation.
• Add aria-current="page" to active sidebar links.
• Add disclosure semantics to sidebar sections with aria-expanded and aria-controls.
• Prevent hidden or collapsed sidebar content from staying focusable or exposed to assistive tech.
• Treat the mobile drawer as a modal drawer with initial focus, focus trapping, Escape close, focus restoration, and background inert handling.
• Hide visually hidden sticky header duplicates from the accessibility tree.
• Improve sticky header icon link hit areas.
• Hide decorative docs icons from assistive tech.
• Respect reduced-motion preferences in docs navigation and icon animations.
• Fix docs demos and snippets that used inaccessible patterns, including empty links, clickable non-interactive wrappers, placeholder-only controls, missing icon button labels, and href="#" examples.
• Add accessibility and localization guidance for Banner, ClipboardText, Combobox, Breadcrumbs, Table, CommandPalette, SensitiveInput, Switch, and chart pages.

---

• Reviews
• bonk has reviewed the change
• automated review not possible because: accessibility behavior requires human review with keyboard, screen reader, and visual checks
• Tests
• Tests included/updated
• Automated tests not possible - manual testing has been completed as follows: not selected
• Additional testing not necessary because: not selected

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@592

commit: 0f91456

[github-actions]

Docs Preview

View docs preview

Commit: 2c68363

[github-actions]

Visual Regression Report — 26 changed, 14 unchanged

26 screenshot(s) with visual changes:

Button / Variant: Outline

268 px (0.26%) changed

Before	After	Diff

Button / With Icon

953 px (0.94%) changed

Before	After	Diff

Button / Icon Only

0 px (0%) changed

Before	After	Diff

Button / Loading State

8 px (0.01%) changed

Before	After	Diff

Button / Disabled State

232 px (0.23%) changed

Before	After	Diff

Button / Link as Button

820 px (0.81%) changed

Before	After	Diff

Dialog / Dialog Basic

316 px (0.31%) changed

Before	After	Diff

Dialog / Dialog Alert

862 px (0.85%) changed

Before	After	Diff

Dialog / Custom Max Width

1,043 px (1.03%) changed

Before	After	Diff

Dialog / Dialog With Select

383 px (0.38%) changed

Before	After	Diff

Dialog / Dialog With Combobox

500 px (0.49%) changed

Before	After	Diff

Dialog / Dialog With Dropdown

480 px (0.47%) changed

Before	After	Diff

Dialog (Open)

96,863 px (0.45%) changed

Before	After	Diff

Select / Select Sizes

3,227 px (1.73%) changed

Before	After	Diff

Select / Select Without Label

746 px (0.73%) changed

Before	After	Diff

Select / Select With Description

2,099 px (1.77%) changed

Before	After	Diff

Select / Select Placeholder

1,270 px (1.25%) changed

Before	After	Diff

Select / Select With Tooltip

1,022 px (1.01%) changed

Before	After	Diff

Select / Select Custom Rendering

973 px (0.96%) changed

Before	After	Diff

Select / Select Loading

3,005 px (1.49%) changed

Before	After	Diff

Select / Select Multiple

1,563 px (1.54%) changed

Before	After	Diff

Select / Select Disabled Options

1,541 px (1.52%) changed

Before	After	Diff

Select / Select Disabled Items

793 px (0.78%) changed

Before	After	Diff

Select / Select Grouped

813 px (0.8%) changed

Before	After	Diff

Select / Select Grouped With Disabled

1,478 px (1.46%) changed

Before	After	Diff

Select / Select Long List

2,148 px (1.81%) changed

Before	After	Diff

14 screenshot(s) unchanged

• Button / Basic
• Button / Variant: Primary
• Button / Variant: Secondary
• Button / Variant: Ghost
• Button / Variant: Destructive
• Button / Variant: Secondary Destructive
• Button / Sizes
• Button / Title
• Dialog / Dialog With Actions
• Dialog / Dialog Confirmation
• Select / Select Basic
• Select / Select With Error
• Select / Select Complex
• Select (Open)

---

Generated by Kumo Visual Regression

[pedromenezes1]

/bonk any objections?

[ask-bonk]

/bonk review — approved with observations

This is an excellent, thorough accessibility improvement. The changes are well-scoped, tests are comprehensive, and the developer experience (dev warnings, localizable labels, preserved visual design) is thoughtful.

What looks great

• Accessible-name enforcement — Dev warnings on SensitiveInput, Switch, Button, CommandPalette.Input, Combobox, and Autocomplete when labels are missing. This will catch real product bugs without breaking builds.
• Localization — Labels are extracted into interfaces (SensitiveInputLabels, BreadcrumbsLabels, TimeseriesTimeRangeControlsLabels, etc.) with sensible English defaults. This matches Kumo's existing i18n patterns.
• Keyboard and pointer fallbacks — TimeseriesChart adds native select range controls without removing brush behavior. SankeyChart adds a visually-hidden focusable action list for nodes/links. Both preserve the existing mouse-driven UX.
• Hit-area expansion — Pseudo-element targets on compact Button, Switch, Table.ResizeHandle, SensitiveInput controls, and ChartLegend.SmallItem meet WCAG 2.2 target-size requirements without changing visual density.
• ARIA wiring — Group descriptions/errors are associated via stable IDs and aria-describedby on Checkbox.Group, Radio.Group, Switch.Group, InputGroup, Select, Combobox, and Autocomplete. aria-invalid is propagated where appropriate.
• Live regions — CommandPalette.List supports aria-busy, loading states announce via role="status", and SensitiveInput announces reveal/hide/copy state changes.
• Docs improvements — Skip link, mobile drawer focus trapping, aria-current="page", disclosure semantics in SidebarNav, and cleanup of inaccessible demo patterns (empty links, unlabeled icon buttons).
• Tests — 282 accessibility-related component tests pass. Coverage includes warning behavior, ARIA attribute association, live-region text, and keyboard action rendering.

Observations (non-blocking)

1. Pre-existing test failures — The 12 failures in add.test.ts and blocks.test.ts are caused by a missing ai/component-registry.json (auto-generated, gitignored). These failures exist on main and are unrelated to this PR.
2. Dynamic aria-label on copy button — In SensitiveInput, the copy button switches its aria-label between "Copy to clipboard" and "Copied". The live region below already announces "Copied to clipboard", which is the better pattern. Changing the accessible name itself can disorient screen-reader users. Consider keeping a static aria-label and relying on the live region for state feedback.
3. Switch color tokens — Switch still uses raw Tailwind colors (bg-blue-500, dark:bg-blue-600, bg-neutral-200, etc.). These are pre-existing, but worth noting that they violate Kumo's semantic-token convention. A future refactor should migrate these to bg-kumo-brand / light-dark() equivalents.
4. Duplicate aria-describedby on group wrappers — Both BaseCheckboxGroup (role="group") and Fieldset.Root receive aria-describedby and aria-invalid. The duplication is harmless (screen readers generally prefer the fieldset semantics), but it's slightly redundant.

Visual regression

The 26 changed screenshots are all expected: Button hit-area expansion, Dialog backdrop/alignment shifts from focus styles, Select padding adjustments from error/description association, and Breadcrumbs separator/icon hiding. Diffs are small (0–1.8%) and consistent with the PR's goals.

---

Verdict: Approve. No changes required.

[ask-bonk]

/bonk review posted on PR #592 — approved with observations.

I reviewed the key accessibility changes across components, charts, blocks, and docs. The PR is high-quality: comprehensive dev warnings for missing accessible names, well-structured localizable labels, keyboard fallbacks that preserve existing mouse behavior, expanded hit areas via pseudo-elements, and 282 passing component tests.

Noted (non-blocking):

• The 12 test failures in add.test.ts/blocks.test.ts are pre-existing (missing auto-generated ai/component-registry.json), not caused by this PR.
• A minor suggestion: SensitiveInput's copy button dynamically changes its aria-label between "Copy to clipboard" and "Copied" — the live region already handles this, so a static label would be slightly cleaner.
• Switch still uses raw Tailwind colors (bg-blue-500, dark:bg-*) — pre-existing, but should migrate to semantic tokens in future work.

Visual regression diffs are expected and small (0–1.8%).

github run