An open source design system that's fully customizable and agent ready
TypeScript
docs: codify the accessibility bar — review criteria, authoring checklist, lab promotion gate (#4385)
Baraa Hamodib7b85dfb1cf0
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdindex 6b77f1a105..2890a9e64f 100644--- a/.github/copilot-instructions.md+++ b/.github/copilot-instructions.md@@ -88,6 +88,25 @@ fix is an open question — state the block, then ask about the approach.hybrids) over `hover: none` for "always show". Also blocking: focus lost onstate change, a focusable element removed from the DOM, or an interactivetarget below the minimum size.+- **Accessibility.** Beyond the broken-path rule above, each of these is a+ bright line on its own:+ - an interactive element without an accessible name;+ - a state change not exposed to assistive tech (visual-only state);+ - a keyboard trap, or an interaction that only works with a pointer;+ - state signaled by color alone;+ - focus not managed on open/close of an overlay (trap while open via+ `useFocusTrap`, restore on close);+ - a live announcement that bypasses `useAnnounce` (a hand-wired `aria-live`+ node);+ - hardcoded English in an AT-facing string (labels, announcements, hints —+ same i18n rule as visible text);+ - a new component that hasn't run the+ [Accessibility Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist).++ The `pr-a11y` axe audit catches the static/DOM-level subset of these+ automatically; axe cannot see keyboard, focus, or announcement _behavior_ —+ those are on the reviewer.+- **Hardcoded user-facing strings.** All UI text goes through `useTranslator()`/ the i18n key system (`@astryx/no-hardcoded-i18n-string`), and new keys mustmatch the required format (`@astryx/i18n-key-format`).diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex c5c9748e0f..9186f9ed07 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -294,6 +294,29 @@ export * from './MyComponent';> committed automatically when changes land on `main`. If you need to verify your> component will be included, run `pnpm sync:exports:check`.+## Accessibility Checklist++Every new component — and any change to an interactive one — must clear the+**[Accessibility Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist)**+(wiki) before review. The checklist lives on the wiki so accessibility+experts can refine it without a code PR; reviewers block on it (see the+blocking criteria in `.github/copilot-instructions.md`), and it is a hard+requirement for a lab → core promotion (see `packages/lab/README.md`).++Two repo-side rules worth restating here:++- Compose the shared primitives — `VisuallyHidden`, `useAnnounce`,+ `useFocusTrap`, and the focus hooks (`useListFocus`, `useGridFocus`,+ `useTreeFocus`) — rather than hand-rolling equivalents. They implement the+ WAI-ARIA APG patterns and are tested once; a bespoke reimplementation of+ one is a review reject.+- CI is the enforcement layer, not a replacement for the checklist: the+ `pr-a11y` workflow runs an axe audit on every PR, a weekly workflow scans+ the full component surface, and the `useAnnounce` lint rule rejects+ hand-wired `aria-live` regions. axe only catches static, DOM-level issues —+ keyboard behavior, focus management, and announcement timing are exactly+ what the checklist and the component's unit tests cover.+## Testing### Run Testsdiff --git a/packages/lab/README.md b/packages/lab/README.mdindex cb26aea437..1ed01a0321 100644--- a/packages/lab/README.md+++ b/packages/lab/README.md@@ -20,6 +20,12 @@ See the **[Component Lifecycle](https://github.com/facebook/astryx/wiki/Componen**Core:** Full keyboard/a11y, hover guards, theming story, status states, spec compliance, vibe tested. Shipped to consumers on `latest`.+## Promotion gate: accessibility++The [Accessibility Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist) is a hard requirement for graduating to core — every item, verified in the promotion PR, alongside the hardening bar linked above.++Lab components get the same scan coverage as core (the `pr-a11y` axe audit and the weekly full scan run against lab too), but a11y findings on a lab component do not block lab merges — they block **promotion**. Iterate freely in lab; clear the checklist to graduate.+## UsageInside the monorepo (storybook/sandbox), imports resolve via pnpm workspaces: