4 definitions in this file:
The key or key combination (e.g., 'Enter', 'Space', 'Tab', 'Shift+Tab', 'Escape', 'Arrow Down', 'Home', 'End').
What happens when this key is pressed (e.g., 'Activates the button', 'Moves focus to the next item in the list', 'Closes the dialog and returns focus to the trigger').
Preconditions for this interaction (e.g., 'When the menu is open', 'When focus is on the trigger element', 'When the component is not disabled'). When omitted, the interaction applies in all contexts.
The ARIA attribute name (e.g., 'role', 'aria-label', 'aria-expanded', 'aria-disabled', 'aria-live', 'aria-controls').
What this attribute communicates to assistive technology and when to apply it. Include guidance on dynamic value changes when applicable.
The expected value or value pattern (e.g., 'true | false', 'string', 'button', 'dialog', 'assertive | polite').
Whether this attribute is always required on the artifact. Defaults to false, meaning the attribute is conditionally required or optional.
Default: false
References:
richText
The foreground token name or resolved color value (e.g., 'color-text-primary', '#1a1a1a', 'var(--button-text-color)').
The background token name or resolved color value (e.g., 'color-background-default', '#ffffff', 'var(--button-background)').
The contrast ratio as a decimal (e.g., 4.5, 7.2, 15.3). Represents the ratio N:1 where N is this value. Tools MAY format for display as 'N:1'.
The WCAG conformance level met by this contrast ratio. AA requires 4.5:1 for normal text and 3:1 for large text. AAA requires 7:1 for normal text and 4.5:1 for large text.
Where this foreground/background combination is used (e.g., 'Label text on primary button background in light mode', 'Secondary text on card surface').
Identifies this guideline as an accessibility spec.
The minimum WCAG conformance level targeted by this artifact. Most design systems target AA. Set to AAA when the artifact exceeds standard requirements.
Keyboard interaction specs — what happens when each key or key combination is pressed while the artifact has focus.
ARIA attribute docs. Lists every ARIA attribute the artifact uses, what it communicates, and when to apply it.
How the artifact is announced by screen readers in various states. Include announcements for default, focused, disabled, loading, expanded, and other relevant states. Name specific screen readers (VoiceOver, NVDA, JAWS) when behavior differs.
How focus moves into, within, and out of the artifact. Document focus trapping (for modals/dialogs), focus restoration (when dismissing overlays), and programmatic focus movement. Describe both keyboard and programmatic focus behavior.
Contrast ratio documentation for foreground/background color pairs used by this artifact. Each entry documents a specific pairing, its measured ratio, and the WCAG level it meets.
How the artifact respects the prefers-reduced-motion media query. Document what animations or transitions exist and what happens when reduced motion is preferred (e.g., 'The loading spinner is replaced with a static ellipsis indicator').
Agent-optimized context for this document block. Provides structured information for AI/LLM consumption — constraints, disambiguation, anti-patterns, examples, and keywords.
References:
keyboardInteraction, ariaAttribute, richText, colorContrast, agents
Design System Documentation Standard (DSDS) 0.1 — Draft Specification
GitHub