An open source design system that's fully customizable and agent ready
TypeScript
docs: require reusing existing accessibility primitives (VisuallyHidden, useAnnounce, focus hooks) over hand-rolled ones (#3801)
Cindy Zhang188a3dc4ec64
diff --git a/.github/instructions/packages.instructions.md b/.github/instructions/packages.instructions.mdindex 860afe5947..3fbff9bc98 100644--- a/.github/instructions/packages.instructions.md+++ b/.github/instructions/packages.instructions.md@@ -312,6 +312,23 @@ and the Design review section above), or to add `hidden: true` until it does.relationships, and often complicates focus/ARIA — call it out when a hook orprop would avoid it.- **Navigation** uses `useLinkComponent()`, never a hardcoded `<a>`.+- **Reuse the existing accessibility primitives — don't hand-roll.** Astryx+ ships shared a11y building blocks; new accessibility work should compose them+ rather than reinvent the behavior inline. Flag hand-rolled equivalents and+ point at the primitive:+ - Screen-reader-only content → the **`VisuallyHidden`** component, not a custom+ `sr-only`/clip-rect style or an off-screen `<span>`.+ - Live-region announcements → **`useAnnounce`**, not an ad-hoc `aria-live` node+ wired up by hand.+ - Roving focus / arrow-key navigation → **`useListFocus`**, **`useGridFocus`**,+ or **`useTreeFocus`**; typeahead → **`useTypeahead`**; a keyboard-shortcut+ hint → **`useKeyboardHint`**; focus trapping → **`useFocusTrap`**; interactive+ role/state wiring → **`useInteractiveRole`**.+ These already implement the WAI-ARIA APG patterns and are tested, so reusing+ them keeps behavior consistent across the system. A genuinely new a11y pattern+ with no existing primitive is fine — but call it out for careful review (see+ "When to flag for engineering / human judgment") rather than landing a bespoke+ implementation quietly.- **Docs in sync** — JSDoc file headers, `SYNC:` reminders, and `.doc.mjs`.`@example` fences in JSDoc must be plain ` ``` ` (never language-tagged), orStorybook autodocs won't render them.