Review Packet: Accessibility and Design System

When to use

Use this packet for shared components, design-system changes, interaction primitives, theming, tokens, dialogs, menus, tables, forms, notifications, and any feature that introduces custom interaction behavior.

Intake questions

• What native element or ARIA pattern matches this behavior?
• What is the keyboard model?
• Where does focus move on entry, action, error, close, and route change?
• What is the accessible name, role, and state?
• What must be announced?
• Which props or overrides could break accessibility?
• Is this component product-specific or system-worthy?

Required artifacts

• Component contract.
• Keyboard and focus specification.
• Token and theming notes.
• Storybook states or equivalent docs.
• Automated and manual accessibility test notes.
• Migration plan for duplicate patterns.

Decision matrix

Need	Prefer
Native behavior exists	Native element with styling.
Reusable behavior across products	Design-system primitive.
Product-specific composition	App-level composition using system primitives.
High-risk custom interaction	Headless primitive with strict contract and tests.

Red flags

• Component looks reusable but encodes product-specific business rules.
• ARIA is added without keyboard and focus behavior.
• Tokens are named after colors instead of semantic roles.
• Product teams can override required accessibility props.
• Design-system release has no migration guidance.

Approval criteria

• Component purpose and ownership are clear.
• Accessibility behavior is part of the public contract.
• Theming does not require forks.
• Documentation covers states and anti-patterns.
• Migration path exists for existing consumers.

Example reviewer comments

• "This custom select needs a complete keyboard model or should use a native select."
• "The token name blue500 leaks implementation. Use semantic state tokens for product usage."
• "This prop allows consumers to remove the accessible name. Make it required or derive it safely."

Example ADR prompt

Write an ADR covering the component pattern, API, accessibility contract, theming model, ownership, alternatives, and migration plan.

Release readiness checklist

• Keyboard walkthrough complete.
• Focus behavior verified.
• Name/role/state checked.
• Docs include error/loading/disabled/empty states.
• Breaking changes include migration guidance.