2 definitions in this file:
Machine-readable state identifier (e.g., 'default', 'hover', 'focus', 'active', 'disabled', 'loading', 'selected', 'error', 'read-only').
What triggers this state, how appearance and behavior change, and any constraints or side effects.
Human-readable name (e.g., 'Default', 'Hover', 'Focus', 'Active / Pressed', 'Disabled', 'Loading').
Design token overrides applied when this state is active. Keys are token property names scoped to the component (e.g., 'button-background', 'button-border-color'). Values are the token identifiers or resolved values used in this state. Only tokens that change from the default state need to be listed. Note: these token references are descriptive summaries for designers. Authoritative resolved values for each variant × state combination live in the design-specifications guideline's overrides array.
Why this state exists — the user need or design rationale it addresses.
Visual previews showing the component in this state.
References:
richText, purpose, example
[
{
"identifier": "default",
"name": "Default",
"description": "The button's resting state when no interaction is occurring."
},
{
"identifier": "hover",
"name": "Hover",
"description": "Triggered when the user's pointer moves over the button. The background darkens by 8% to indicate interactivity. Not applicable on touch devices.",
"tokens": {
"button-background": "color-action-primary-hover"
},
"preview": [
{
"title": "Primary button — hover state",
"presentation": {
"kind": "image",
"url": "https://design.acme.com/assets/button-primary-hover.png",
"alt": "A primary button with a slightly darker blue background indicating the hover state."
}
}
]
},
{
"identifier": "active",
"name": "Active / Pressed",
"description": "Triggered while the button is being pressed (mousedown or touch start). The background darkens by 16% from the default to indicate activation.",
"tokens": {
"button-background": "color-action-primary-active"
}
},
{
"identifier": "focus",
"name": "Focus",
"description": "Triggered when the button receives keyboard focus. A 2px focus ring appears with a 2px offset from the container edge. The focus ring uses the system focus color.",
"tokens": {
"button-focus-ring-color": "color-focus-ring",
"button-focus-ring-width": "border-width-focus",
"button-focus-ring-offset": "space-focus-offset"
},
"preview": [
{
"title": "Primary button — focus state",
"presentation": {
"kind": "image",
"url": "https://design.acme.com/assets/button-primary-focus.png",
"alt": "A primary button with a visible 2px blue focus ring offset from the button edge by 2px."
}
}
]
},
{
"identifier": "disabled",
"name": "Disabled",
"description": "The button is non-interactive. Opacity is reduced to 0.4. Pointer events are disabled. The button remains in the tab order when using aria-disabled instead of the HTML disabled attribute.",
"purpose": {
"kind": "purpose",
"useCases": [
{
"description": "When the user cannot interact with the button because a precondition has not been met (e.g., required fields are empty).",
"kind": "positive"
},
{
"description": "When the button is processing an asynchronous operation.",
"kind": "negative",
"alternative": {
"identifier": "loading",
"rationale": "The loading state provides feedback that an action is in progress. A disabled button gives no feedback."
}
}
]
}
},
{
"identifier": "loading",
"name": "Loading",
"description": "The button label is replaced by a spinner animation. The button is non-interactive. The button maintains its dimensions from the default state to prevent layout shift.",
"preview": [
{
"title": "Loading state transition",
"presentation": {
"kind": "video",
"url": "https://design.acme.com/assets/button-loading-interaction.mp4",
"alt": "A user clicks a primary button labeled Save. The label is replaced by a spinner animation while the button maintains its width. After two seconds, the spinner is replaced by a checkmark and the label changes to Saved."
}
}
]
}
]
Identifies this guideline as a states spec.
The interactive states. Each item documents a single state with its trigger, visual changes, token overrides, and optional previews. Ordering is significant — tools SHOULD display states in this order.
Min items: 1
AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.
References:
stateEntry, agents
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub