Skip to content

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.md
index 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 on
state change, a focusable element removed from the DOM, or an interactive
target 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 must
match the required format (`@astryx/i18n-key-format`).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 Tests
diff --git a/packages/lab/README.md b/packages/lab/README.md
index 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.
+
## Usage
Inside the monorepo (storybook/sandbox), imports resolve via pnpm workspaces: