4 definitions in this file:
Identifies this document block as a variants spec.
The variant dimensions. Each item is either a flag (boolean toggle) or an enum (set of values). Ordering is significant, so tools SHOULD display dimensions in this order.
Min items: 1
References:
flagVariant, enumVariant
{
"kind": "variants",
"items": [
{
"kind": "enum",
"identifier": "emphasis",
"name": "Emphasis",
"description": "Controls the visual weight of the button to establish a visual hierarchy among actions on a surface.",
"values": [
{
"identifier": "primary",
"description": "High-emphasis — the main action on the surface."
},
{
"identifier": "secondary",
"description": "Medium-emphasis — important but not primary."
},
{
"identifier": "ghost",
"description": "Low-emphasis — tertiary actions and dense layouts."
},
{
"identifier": "danger",
"description": "Signals a destructive or irreversible action."
}
]
},
{
"kind": "enum",
"identifier": "size",
"name": "Size",
"description": "Controls the physical dimensions and internal padding of the button.",
"values": [
{
"identifier": "sm",
"name": "Small",
"description": "Compact size for toolbars, table rows, and dense layouts. 32px height."
},
{
"identifier": "md",
"name": "Medium",
"description": "Default size for most contexts. 40px height."
},
{
"identifier": "lg",
"name": "Large",
"description": "Touch-optimized size for mobile-first surfaces. 48px height."
}
]
},
{
"kind": "flag",
"identifier": "full-width",
"name": "Full Width",
"description": "The button stretches to fill the full width of its parent container."
},
{
"kind": "flag",
"identifier": "icon-only",
"name": "Icon Only",
"description": "The button renders a single icon with no visible label. An aria-label is required."
}
]
}
Identifies this variant as a boolean flag.
Machine-readable identifier of the flag (e.g., 'disabled', 'full-width', 'icon-only', 'loading').
What this flag controls and how it affects the component's appearance or behavior when active.
Human-readable name of the flag (e.g., 'Disabled', 'Full Width', 'Icon Only', 'Loading').
Why this flag exists: the user need or design rationale it addresses (e.g., 'Prevents user interaction during form submission to avoid duplicate requests').
Examples showing the component with this flag active.
Min items: 1
Design token overrides applied when this flag is active, as the shared token-override map: keys are token-purpose names, values are documented token identifiers.
References:
richText, example, tokenOverrides
[
{
"kind": "flag",
"identifier": "full-width",
"name": "Full Width",
"description": "When active, the button stretches to fill the full width of its parent container. Label text is centered.",
"rationale": "- Use when: When the button is the sole action in a narrow container such as a mobile sheet, a card footer, or a single-column form.\n- Avoid when: When multiple buttons appear side by side in a button group or dialog footer. Use `default width` instead — Full-width buttons in a horizontal group force a stacked layout, which breaks the expected left-to-right reading order for action groups."
},
{
"kind": "flag",
"identifier": "icon-only",
"name": "Icon Only",
"description": "When active, the button renders a single icon with no visible label. An aria-label is required."
}
]
Identifies this variant as an enumerated set of values.
Machine-readable identifier of the variant dimension (e.g., 'size', 'emphasis', 'shape'). This is the axis name, not a value within it.
What this dimension of variation controls and how its values affect the component's appearance or behavior.
The possible values for this variant. A single entry is valid — real systems carry single-value dimensions mid-migration (a new dimension introduced one value at a time). Ordering is significant, so tools SHOULD keep it for display.
Min items: 1
Human-readable name of the variant dimension (e.g., 'Size', 'Emphasis', 'Shape').
References:
richText, variantValue
[
{
"kind": "enum",
"identifier": "emphasis",
"name": "Emphasis",
"description": "Controls the visual weight of the button. Determines background fill, border treatment, and text color to establish a visual hierarchy among actions on a surface.",
"values": [
{
"identifier": "primary",
"description": "High-emphasis — the main action on the surface."
},
{
"identifier": "secondary",
"description": "Medium-emphasis — important but not primary."
},
{
"identifier": "ghost",
"description": "Low-emphasis — tertiary actions and dense layouts."
},
{
"identifier": "danger",
"description": "Signals a destructive or irreversible action."
}
]
},
{
"kind": "enum",
"identifier": "size",
"name": "Size",
"description": "Controls the physical dimensions and internal padding of the button. All sizes maintain a minimum 44×44 CSS pixel tap target.",
"values": [
{
"identifier": "small",
"description": "Compact size for toolbars, table rows, and dense layouts."
},
{
"identifier": "medium",
"description": "The default size. Suitable for most contexts including forms, dialogs, and page-level actions."
},
{
"identifier": "large",
"description": "Touch-optimized size for mobile-first surfaces and marketing pages."
}
]
}
]
Machine-readable value identifier (e.g., 'sm', 'md', 'lg', 'primary', 'secondary').
What this value looks like, when to use it, and how it differs from other values in this dimension.
Human-readable name (e.g., 'Small', 'Medium', 'Large', 'Primary', 'Secondary').
Why this value exists: the user need or design rationale it addresses (e.g., 'High emphasis directs the user to the single most important action on the surface'). For comparative when-to-use guidance across values, use the entity's useCases block instead.
Examples showing this variant value in isolation or in context.
Min items: 1
Design token overrides applied when this value is selected, as the shared token-override map: keys are token-purpose names, values are documented token identifiers.
References:
richText, example, tokenOverrides
[
{
"identifier": "primary",
"name": "Primary",
"description": "High-emphasis — the main action on the surface. Uses a solid, filled background. Limit to one primary button per surface.",
"rationale": "- Use when: When the action is the most important on the surface — the one the user is most likely to take (e.g., Save, Submit, Confirm).\n- Avoid when: When a surface already has a primary button. Adding a second dilutes visual hierarchy. Use `secondary` instead — Secondary emphasis maintains importance without competing with the existing primary action."
},
{
"identifier": "secondary",
"name": "Secondary",
"description": "Medium-emphasis — important but not the primary action. Uses a visible border and transparent background."
},
{
"identifier": "ghost",
"name": "Ghost",
"description": "Low-emphasis — for tertiary actions, toolbar actions, or dense layouts where visual weight must be minimized."
},
{
"identifier": "danger",
"name": "Danger",
"description": "Signals a destructive or irreversible action. Use for delete, remove, or disconnect actions.",
"rationale": "- Use when: When the action is destructive or irreversible — deleting a record, revoking access, removing a team member.\n- Avoid when: When the action is not destructive, even if it feels important or urgent. Use `primary` instead — The danger color is a strong signal reserved for destruction. Using it for non-destructive actions dilutes its meaning."
}
]
Design System Documentation Spec (DSDS) 0.14.0 — Draft Specification
GitHub