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.
[
{
"key": "Enter",
"action": "Activates the button."
},
{
"key": "Space",
"action": "Activates the button."
},
{
"key": "Tab",
"action": "Moves focus to the next focusable element in the tab order."
},
{
"key": "Shift+Tab",
"action": "Moves focus to the previous focusable element in the tab order."
},
{
"key": "Escape",
"action": "Closes the dialog and returns focus to the trigger element.",
"context": "When focus is inside an open dialog."
}
]
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
[
{
"attribute": "role",
"value": "button",
"description": "Applied automatically by the <button> element. Only set explicitly when using a non-button element as a button.",
"required": false
},
{
"attribute": "aria-disabled",
"value": "true | false",
"description": "Set to 'true' when the button is non-interactive. Preferred over the HTML disabled attribute when the button should remain focusable for screen reader discoverability.",
"required": false
},
{
"attribute": "aria-label",
"value": "string",
"description": "Provides an accessible name for icon-only buttons that lack visible text. Not needed when a visible label is present.",
"required": false
},
{
"attribute": "aria-expanded",
"value": "true | false",
"description": "Indicates whether a controlled element (menu, dialog, tooltip) is currently expanded or collapsed. Set dynamically when the controlled element opens and closes.",
"required": false
},
{
"attribute": "aria-busy",
"value": "true | false",
"description": "Set to 'true' when the button is in the loading state. Communicates to assistive technology that the button's action is in progress.",
"required": false
}
]
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').
[
{
"foreground": "color-text-on-action",
"background": "color-action-primary",
"contrastRatio": 7.2,
"level": "AAA",
"context": "Label text on primary button background in light mode."
},
{
"foreground": "color-text-on-action",
"background": "color-action-danger",
"contrastRatio": 6.5,
"level": "AAA",
"context": "Label text on danger button background in light mode."
},
{
"foreground": "color-action-primary",
"background": "color-background-default",
"contrastRatio": 4.8,
"level": "AA",
"context": "Secondary button border and text against the default page background."
},
{
"foreground": "color-text-primary",
"background": "color-background-default",
"contrastRatio": 15.3,
"level": "AAA",
"context": "Primary body text on the default background surface in light mode."
}
]
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').
AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.
References:
keyboardInteraction, ariaAttribute, richText, colorContrast, agents
{
"kind": "accessibility",
"wcagLevel": "AA",
"keyboardInteraction": [
{
"key": "Enter",
"action": "Activates the button."
},
{
"key": "Space",
"action": "Activates the button."
},
{
"key": "Tab",
"action": "Moves focus to the next focusable element in the tab order."
},
{
"key": "Shift+Tab",
"action": "Moves focus to the previous focusable element in the tab order."
}
],
"ariaAttributes": [
{
"attribute": "role",
"value": "button",
"description": "Applied automatically by the <button> element. Only set explicitly when using a non-button element as a button.",
"required": false
},
{
"attribute": "aria-disabled",
"value": "true | false",
"description": "Set to 'true' when the button is non-interactive. Preferred over the HTML disabled attribute when the button should remain focusable for screen reader discoverability.",
"required": false
},
{
"attribute": "aria-label",
"value": "string",
"description": "Provides an accessible name for icon-only buttons that lack visible text. Not needed when a visible label is present.",
"required": false
},
{
"attribute": "aria-busy",
"value": "true | false",
"description": "Set to 'true' when the button is in the loading state. Communicates to assistive technology that the button's action is in progress.",
"required": false
}
],
"screenReaderBehavior": "Announced as '[label], button'. When disabled via aria-disabled, announced as '[label], button, dimmed' (VoiceOver) or '[label], button, unavailable' (NVDA/JAWS). When loading, announced as '[label], button, busy'.",
"focusManagement": "The button participates in the normal tab order. It does not trap or redirect focus. When the button triggers a modal or popover, focus is moved to the opened element — this is the responsibility of the modal/popover component, not the button.",
"colorContrast": [
{
"foreground": "color-text-on-action",
"background": "color-action-primary",
"contrastRatio": 7.2,
"level": "AAA",
"context": "Label text on primary button background in light mode."
},
{
"foreground": "color-action-primary",
"background": "color-background-default",
"contrastRatio": 4.8,
"level": "AA",
"context": "Secondary button border/text against the default page background in light mode."
},
{
"foreground": "color-text-on-action",
"background": "color-action-danger",
"contrastRatio": 6.5,
"level": "AAA",
"context": "Label text on danger button background in light mode."
}
],
"motionConsiderations": "The loading spinner animation respects the prefers-reduced-motion media query. When reduced motion is preferred, the spinner is replaced with a static ellipsis indicator."
}
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub