4 definitions in this file:
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 flag exists — the user need or design rationale it addresses (e.g., 'Prevents user interaction during form submission to avoid duplicate requests').
Visual previews showing this variant value in isolation or in context.
References:
richText, purpose, example
[
{
"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.",
"purpose": {
"kind": "purpose",
"useCases": [
{
"description": "When the action is the most important on the surface — the one the user is most likely to take (e.g., Save, Submit, Confirm).",
"kind": "positive"
},
{
"description": "When a surface already has a primary button. Adding a second dilutes visual hierarchy.",
"kind": "negative",
"alternative": {
"identifier": "secondary",
"rationale": "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.",
"purpose": {
"kind": "purpose",
"useCases": [
{
"description": "When the action is destructive or irreversible — deleting a record, revoking access, removing a team member.",
"kind": "positive"
},
{
"description": "When the action is not destructive, even if it feels important or urgent.",
"kind": "negative",
"alternative": {
"identifier": "primary",
"rationale": "The danger color is a strong signal reserved for destruction. Using it for non-destructive actions dilutes its meaning."
}
}
]
}
}
]
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 variant exists — the user need or design rationale it addresses (e.g., 'Prevents user interaction during form submission to avoid duplicate requests').
Visual preview showing the component with this flag active.
References:
richText, purpose, example
[
{
"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.",
"purpose": {
"kind": "purpose",
"useCases": [
{
"description": "When the button is the sole action in a narrow container such as a mobile sheet, a card footer, or a single-column form.",
"kind": "positive"
},
{
"description": "When multiple buttons appear side by side in a button group or dialog footer.",
"kind": "negative",
"alternative": {
"identifier": "default width",
"rationale": "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.",
"purpose": {
"kind": "purpose"
}
}
]
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. Must contain at least two entries — a single-value dimension should be modeled as a flag variant instead. Ordering is significant — tools SHOULD preserve it for display.
Min items: 2
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."
}
]
}
]
Identifies this guideline as a variants spec.
The variant dimensions. Each item is either a flag (boolean toggle) or an enum (set of values). Ordering is significant — tools SHOULD display dimensions 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:
flagVariant, enumVariant, agents
{
"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.",
"purpose": {
"kind": "purpose"
}
},
{
"kind": "flag",
"identifier": "icon-only",
"name": "Icon Only",
"description": "The button renders a single icon with no visible label. An aria-label is required.",
"purpose": {
"kind": "purpose"
}
}
]
}
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub