12 definitions in this file:
Open map: keys are strings, values are any
References:
designValue
Padding and internal gaps within the component. Keys are named spatial relationships between anatomy parts or edges (e.g., 'container-horizontal', 'icon-to-label'). Values are token names or raw CSS values (e.g., 'space-4', '8px', '1rem').
Recommended margins and gaps between this component and siblings or container edges. Keys are named spatial relationships (e.g., 'button-to-button', 'button-group-gap', 'stack-gap'). Values are token names or raw CSS values. External spacing is a recommendation — the parent layout controls the space between components.
References:
designValue
Minimum width as a token name or raw value (e.g., 'size-button-min-width', '64px').
Maximum width as a token name or raw value (e.g., 'size-dialog-max-width', '600px', 'none').
Minimum height as a token name or raw value (e.g., 'size-button-min-height', '44px').
Maximum height as a token name or raw value.
Aspect ratio constraint as a ratio string (e.g., '16/9', '1/1', '4/3').
References:
designValue
Font family as a token name or raw value (e.g., 'font-family-body', 'Inter, sans-serif').
Font size as a token name or raw value (e.g., 'font-size-body', '14px', '0.875rem').
Font weight as a token name or raw value (e.g., 'font-weight-regular', '400', 'bold').
Line height as a token name or raw value (e.g., 'line-height-body', '1.5', '20px').
Letter spacing as a token name or raw value (e.g., 'letter-spacing-body', '0.01em').
Text transform value (e.g., 'uppercase', 'capitalize', 'none').
A composite typography token covering multiple typographic properties (e.g., '$body-compact-01', 'type-scale-body-sm'). When provided, individual properties (fontSize, fontWeight, etc.) document what the token resolves to.
References:
designValue
Open map: keys are strings, values are any
References:
typographyEntrySpec
The breakpoint name or value at which this behavior applies (e.g., 'small', 'medium', 'large', '768px', 'min-width: 1024px').
How the component's layout, sizing, or behavior changes at this breakpoint.
References:
richText
[
{
"breakpoint": "320px",
"description": "Below 320px, buttons expand to full width automatically to maintain a usable tap target."
},
{
"breakpoint": "768px",
"description": "Below 768px, buttons in a button group stack vertically and expand to full width."
},
{
"breakpoint": "1024px",
"description": "Above 1024px, the minimum button width increases from 44px to 64px to provide a more comfortable click target on desktop."
}
]
The variant identifier. Must match a value defined in the component's variants guideline (e.g., 'primary', 'secondary', 'ghost', 'danger').
How this variant's visual treatment differs.
Design properties for this variant. Keys are property names (e.g., 'background', 'text-color', 'border-color'). Values are token identifiers or raw CSS values.
Spacing adjustments for this variant, if any.
Sizing adjustments for this variant, if any.
Typography adjustments for this variant, if any.
References:
richText, designProperties, spacingSpec, sizingSpec, typographySpec
The size identifier. Must match a value defined in the component's variants guideline (e.g., 'small', 'medium', 'large', 'sm', 'md', 'lg').
This size's intended use.
Design properties for this size. Keys are property names (e.g., 'min-height', 'font-size', 'icon-size', 'padding-horizontal'). Values are token identifiers or raw CSS values.
Spacing for this size.
Dimension constraints for this size.
Typography settings for this size.
References:
richText, designProperties, spacingSpec, sizingSpec, typographySpec
The state identifier. Must match a value defined in the component's states guideline (e.g., 'hover', 'active', 'focus', 'disabled', 'loading').
How the component changes in this state.
Design properties for this state. Only properties that change from the default need to be listed. Keys are property names (e.g., 'background', 'opacity', 'focus-ring-color'). Values are token identifiers or raw CSS values.
Spacing adjustments for this state, if any.
Sizing adjustments for this state, if any.
Typography adjustments for this state, if any.
References:
richText, designProperties, spacingSpec, sizingSpec, typographySpec
The variant name (e.g., 'primary', 'danger').
The state name (e.g., 'hover', 'active', 'focus').
How this variant behaves in this state.
Design properties for this variant–state combination.
References:
richText, designProperties
Identifies this guideline as a design specs document.
Base design properties for the default config. Keys are property names describing what each value controls (e.g., 'background', 'text-color', 'border-radius'). Values are design token names or raw CSS values.
Base spacing spec for the default config.
Base sizing spec for the default config.
Base typography spec for the default config.
Responsive behavior describing how the component adapts across breakpoints. Entries are ordered from smallest to largest breakpoint.
Design properties grouped by variant. Each entry is a full set of property-to-value mappings for one variant. Values are the variant's own tokens (e.g., 'button-primary-bg') or raw values — not overrides of base tokens.
Design properties grouped by size. Each entry defines the dimensions, spacing, typography, and other properties that change at each size step.
Design properties grouped by interactive state. Each entry defines properties that change when the component enters a given state. Only properties that differ from the default need to be listed.
Design properties for specific variant–state combinations where the state's visual treatment differs across variants. Only needed when a single state entry cannot describe the behavior across all variants.
AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.
Constraint: At least one of properties, spacing, sizing, typography, responsive, variants, sizes, states, variantStates must be present.
References:
designProperties, spacingSpec, sizingSpec, typographySpec, responsiveEntry, specVariant, specSize, specState, specVariantState, agents
{
"kind": "design-specifications",
"properties": {
"background": "button-bg",
"text-color": "button-text",
"border-color": "button-border",
"border-width": "1px",
"border-radius": "button-radius",
"padding-horizontal": "button-padding-x",
"padding-vertical": "button-padding-y",
"font-family": "font-family-body",
"font-size": "14px",
"font-weight": "500",
"line-height": "20px",
"icon-size": "16px",
"icon-color": "inherit",
"icon-gap": "8px",
"focus-ring-color": "color-focus",
"focus-ring-width": "2px",
"focus-ring-offset": "2px",
"min-height": "40px",
"min-width": "64px",
"opacity": "1"
},
"spacing": {
"internal": {
"container-horizontal": "space-4",
"container-vertical": "space-2",
"icon-to-label": "space-2"
},
"external": {
"button-to-button": "space-2",
"button-group-gap": "space-3"
}
},
"sizing": {
"minWidth": "64px",
"minHeight": "40px"
},
"typography": {
"label": {
"fontFamily": "font-family-body",
"fontSize": "14px",
"fontWeight": "500",
"lineHeight": "20px",
"typeToken": "$body-compact-01"
}
},
"responsive": [
{
"breakpoint": "320px",
"description": "Below 320px, buttons expand to full width automatically to maintain a usable tap target."
},
{
"breakpoint": "768px",
"description": "Below 768px, buttons in a button group stack vertically and expand to full width."
},
{
"breakpoint": "1024px",
"description": "Above 1024px, the minimum button width increases from 44px to 64px."
}
],
"variants": [
{
"identifier": "primary",
"description": "High-emphasis filled button. Solid background with light text.",
"properties": {
"background": "button-primary-bg",
"text-color": "button-primary-text",
"border-color": "transparent",
"border-width": "0px",
"icon-color": "button-primary-text"
}
},
{
"identifier": "secondary",
"description": "Medium-emphasis outlined button. Transparent background with visible border.",
"properties": {
"background": "transparent",
"text-color": "button-secondary-text",
"border-color": "button-secondary-border",
"border-width": "1px",
"icon-color": "button-secondary-text"
}
},
{
"identifier": "ghost",
"description": "Low-emphasis button with no background or border in the default state.",
"properties": {
"background": "transparent",
"text-color": "button-ghost-text",
"border-color": "transparent",
"border-width": "0px",
"icon-color": "button-ghost-text"
}
},
{
"identifier": "danger",
"description": "High-emphasis destructive button. Solid danger background with light text.",
"properties": {
"background": "button-danger-bg",
"text-color": "button-danger-text",
"border-color": "transparent",
"border-width": "0px",
"icon-color": "button-danger-text"
}
}
],
"sizes": [
{
"identifier": "small",
"description": "Compact size for toolbars and dense layouts. 32px height.",
"properties": {
"min-height": "32px",
"font-size": "12px",
"line-height": "16px",
"icon-size": "14px",
"icon-gap": "4px",
"padding-horizontal": "space-3",
"padding-vertical": "space-1"
},
"spacing": {
"internal": {
"container-horizontal": "space-3",
"container-vertical": "space-1",
"icon-to-label": "space-1"
}
},
"sizing": {
"minWidth": "44px",
"minHeight": "32px"
},
"typography": {
"label": {
"fontSize": "12px",
"fontWeight": "500",
"lineHeight": "16px",
"typeToken": "$label-01"
}
}
},
{
"identifier": "medium",
"description": "Default size for most contexts. 40px height.",
"properties": {
"min-height": "40px",
"font-size": "14px",
"line-height": "20px",
"icon-size": "16px",
"icon-gap": "8px",
"padding-horizontal": "space-4",
"padding-vertical": "space-2"
},
"sizing": {
"minWidth": "64px",
"minHeight": "40px"
}
},
{
"identifier": "large",
"description": "Touch-optimized size for mobile-first surfaces. 48px height.",
"properties": {
"min-height": "48px",
"font-size": "16px",
"line-height": "24px",
"icon-size": "20px",
"icon-gap": "space-3",
"padding-horizontal": "space-5",
"padding-vertical": "space-3"
},
"spacing": {
"internal": {
"container-horizontal": "space-5",
"container-vertical": "space-3",
"icon-to-label": "space-3"
}
},
"sizing": {
"minWidth": "80px",
"minHeight": "48px"
},
"typography": {
"label": {
"fontSize": "16px",
"fontWeight": "500",
"lineHeight": "24px",
"typeToken": "$body-compact-02"
}
}
}
],
"states": [
{
"identifier": "hover",
"description": "Pointer moves over the button. Background shifts to indicate interactivity.",
"properties": {
"background": "button-hover-bg"
}
},
{
"identifier": "active",
"description": "Button is being pressed. Background shifts further to indicate activation.",
"properties": {
"background": "button-active-bg"
}
},
{
"identifier": "focus",
"description": "Button receives keyboard focus. A visible focus ring appears around the container.",
"properties": {
"focus-ring-color": "color-focus",
"focus-ring-width": "2px",
"focus-ring-offset": "2px"
}
},
{
"identifier": "disabled",
"description": "Button is non-interactive. Reduced opacity, pointer-events disabled. Uses aria-disabled to remain in tab order.",
"properties": {
"opacity": "0.4"
}
},
{
"identifier": "loading",
"description": "Label is replaced by a spinner. Button is non-interactive but retains its dimensions to prevent layout shift. Spinner respects prefers-reduced-motion."
}
],
"variantStates": [
{
"variant": "primary",
"state": "hover",
"description": "Primary fill darkens by 8%.",
"properties": {
"background": "button-primary-hover-bg"
}
},
{
"variant": "primary",
"state": "active",
"description": "Primary fill darkens by 16%.",
"properties": {
"background": "button-primary-active-bg"
}
},
{
"variant": "secondary",
"state": "hover",
"description": "Subtle background fill appears.",
"properties": {
"background": "button-secondary-hover-bg"
}
},
{
"variant": "secondary",
"state": "active",
"description": "Background fill darkens on press.",
"properties": {
"background": "button-secondary-active-bg"
}
},
{
"variant": "ghost",
"state": "hover",
"description": "Subtle background fill appears to signal interactivity.",
"properties": {
"background": "button-ghost-hover-bg"
}
},
{
"variant": "ghost",
"state": "active",
"description": "Background fill darkens on press.",
"properties": {
"background": "button-ghost-active-bg"
}
},
{
"variant": "danger",
"state": "hover",
"description": "Danger fill darkens by 8%.",
"properties": {
"background": "button-danger-hover-bg"
}
},
{
"variant": "danger",
"state": "active",
"description": "Danger fill darkens by 16%.",
"properties": {
"background": "button-danger-active-bg"
}
}
]
}
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub