DSDS States Document Block

2 definitions in this file:

states
stateEntry

Identifies this document block as a states spec.

The interactive states. Each item documents a single state with its trigger, visual changes, token overrides, and optional examples. Ordering is significant, so tools SHOULD display states in this order.
Min items: 1

References:

stateEntry

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 token identifiers. They are required when the system has a token layer, so the override can't silently drift from the token source. Raw values are only for token-less systems. List only tokens that change from the default state. 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.

Examples showing the component in this state.

References: richText, 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" }, "examples": [ { "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" }, "examples": [ { "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.", "rationale": "- Use when: When the user cannot interact with the button because a precondition has not been met (e.g., required fields are empty).\n- Avoid when: When the button is processing an asynchronous operation. Use `loading` instead — 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.", "examples": [ { "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." } } ] } ]