8 definitions in this file:
The property identifier as used in code (e.g., 'variant', 'size', 'disabled', 'onClick').
The property's type as it would appear in a type signature (e.g., 'boolean', 'number', 'string', 'ReactNode', 'IconComponent'). For enum properties, use values instead of encoding members here.
What this property controls, how it affects the component, and any constraints or side effects.
Whether the consumer must provide this property. Defaults to false.
Default: false
The accepted values for enum-like properties (e.g., ['default', 'primary', 'ghost']). Use this instead of encoding members in type.
A JSON Schema (Draft 2020-12) object defining the property's type in machine-readable form. Follows the same conventions as OpenAPI parameter schemas.
The default value in its native JSON type. Accepts any JSON type: string, number, boolean, object, array, or null.
Example values for this property.
The version in which this property was introduced.
Whether this property is deprecated. Defaults to false.
Default: false
What to use instead, if deprecated.
References:
richText, example
[
{
"identifier": "variant",
"type": "string",
"values": [
"primary",
"secondary",
"ghost",
"danger"
],
"schema": {
"type": "string",
"enum": [
"primary",
"secondary",
"ghost",
"danger"
],
"default": "primary"
},
"description": "The visual style of the button. Determines background color, text color, and border treatment.",
"required": false,
"defaultValue": "primary",
"examples": [
{
"value": "primary",
"title": "High-emphasis — the main action on the surface",
"presentation": {
"kind": "code",
"code": "<Button variant=\"primary\">Save</Button>",
"language": "jsx"
}
},
{
"value": "danger",
"title": "Destructive — delete, remove, disconnect",
"presentation": {
"kind": "code",
"code": "<Button variant=\"danger\">Delete project</Button>",
"language": "jsx"
}
}
],
"since": "1.0.0"
},
{
"identifier": "disabled",
"type": "boolean",
"schema": {
"type": "boolean",
"default": false
},
"description": "When true, the button is non-interactive. The cursor changes to not-allowed, and the button is visually dimmed to 40% opacity.",
"required": false,
"defaultValue": false,
"since": "1.0.0"
},
{
"identifier": "loading",
"type": "boolean",
"schema": {
"type": "boolean",
"default": false
},
"description": "When true, the label is replaced with a spinner and the button is non-interactive. The button retains its dimensions to prevent layout shift.",
"required": false,
"defaultValue": false,
"since": "2.1.0"
},
{
"identifier": "size",
"type": "string",
"values": [
"small",
"medium",
"large"
],
"schema": {
"type": "string",
"enum": [
"small",
"medium",
"large"
],
"default": "medium"
},
"description": "The size of the button. Affects padding, font size, icon size, and minimum target area.",
"required": false,
"defaultValue": "medium",
"since": "1.0.0"
}
]
The event identifier (e.g., 'onClick', 'onChange', 'onDismiss').
When this event fires, what it communicates, and how consumers should respond.
Description of the event return shape (e.g., '(event: MouseEvent) => void', '{ value: string, index: number }').
The version in which this event was introduced.
References:
richText
[
{
"identifier": "onClick",
"description": "Fires when the button is activated via mouse click, touch tap, Enter key, or Space key. Does not fire when the button is disabled or loading.",
"returns": "(event: MouseEvent) => void",
"since": "1.0.0"
},
{
"identifier": "onFocus",
"description": "Fires when the button receives focus.",
"returns": "(event: FocusEvent) => void",
"since": "1.0.0"
},
{
"identifier": "onBlur",
"description": "Fires when the button loses focus.",
"returns": "(event: FocusEvent) => void",
"since": "1.0.0"
}
]
The slot identifier. Use 'default' for the unnamed/default slot.
What content this slot accepts and any constraints on its children.
Allowed content (e.g., 'Plain text or a text node. Do not nest interactive elements.').
The version in which this slot was introduced.
References:
richText
[
{
"identifier": "default",
"description": "The primary content slot. Accepts text, icons, or a combination of both. When both an icon and text are provided, the icon appears before the text by default.",
"acceptedContent": "Text, Icon, or a combination. Avoid placing interactive elements inside the button.",
"since": "1.0.0"
}
]
The full custom-property identifier including the -- prefix (e.g., '--button-background', '--button-border-radius').
Pattern: ^--
What visual attribute this property controls.
The default value (e.g., 'var(--color-action-primary)', '1rem', 'transparent').
The expected CSS value type (e.g., 'color', 'dimension', 'number').
The version in which this custom property was introduced.
References:
richText
[
{
"identifier": "--button-background",
"description": "The background color of the button container.",
"defaultValue": "var(--color-action-primary)",
"type": "color",
"since": "1.0.0"
},
{
"identifier": "--button-text-color",
"description": "The color of the label text.",
"defaultValue": "var(--color-text-on-action)",
"type": "color",
"since": "1.0.0"
},
{
"identifier": "--button-border-radius",
"description": "The border radius of the button container.",
"defaultValue": "var(--radius-medium)",
"type": "dimension",
"since": "1.0.0"
},
{
"identifier": "--button-padding-horizontal",
"description": "The left and right padding inside the button container.",
"defaultValue": "var(--space-4)",
"type": "dimension",
"since": "1.0.0"
}
]
The part identifier as used in ::part() selectors.
What element this part exposes and what styling it enables.
The version in which this part was introduced.
References:
richText
[
{
"identifier": "base",
"description": "The root container element of the button. Use for overriding background, border, and padding from outside the shadow DOM.",
"since": "1.0.0"
},
{
"identifier": "label",
"description": "The text label element. Use for overriding font styles from outside the shadow DOM.",
"since": "1.0.0"
},
{
"identifier": "icon",
"description": "The icon wrapper element. Use for adjusting icon size or color from outside the shadow DOM.",
"since": "2.0.0"
}
]
The full attribute identifier including the data- prefix (e.g., 'data-state', 'data-variant').
Pattern: ^data-
What this attribute reflects and how to use it for styling or testing.
The set of possible values (e.g., ['default', 'hover', 'active', 'disabled']).
The version in which this attribute was introduced.
References:
richText
[
{
"identifier": "data-variant",
"description": "Reflects the current variant. Useful for parent-level conditional styling.",
"values": [
"primary",
"secondary",
"ghost",
"danger"
],
"since": "1.0.0"
},
{
"identifier": "data-loading",
"description": "Present when the button is in a loading state. Useful for CSS selectors that target loading buttons.",
"values": [
"true"
],
"since": "2.1.0"
}
]
The method identifier (e.g., 'focus', 'reset', 'scrollTo').
What this method does, when to call it, and any side effects.
The parameter signature (e.g., '(options?: { preventScroll: boolean }) => void').
The return value (e.g., 'void', 'Promise<void>', 'HTMLElement | null').
The version in which this method was introduced.
References:
richText
[
{
"identifier": "focus",
"description": "Programmatically moves focus to the button element. Useful after closing a modal or completing a flow that should return focus to the triggering button.",
"parameters": "(options?: FocusOptions) — optional FocusOptions object with `preventScroll` boolean.",
"returnType": "void",
"since": "1.0.0"
},
{
"identifier": "click",
"description": "Programmatically triggers the button's click handler. Does not fire if the button is disabled or loading.",
"parameters": "none",
"returnType": "void",
"since": "1.0.0"
}
]
Identifies this guideline as an API spec.
The platform or framework this API describes (e.g., 'react', 'web-component', 'vue', 'angular', 'ios', 'android'). When omitted, the API is assumed to be the single/default platform.
Configurable properties (props, attributes, inputs) that consumers pass to the component.
Events emitted by the component that consumers can listen to.
Content insertion points where consumers can project child content.
CSS custom properties exposed for external styling.
CSS shadow parts exposed for external styling via ::part() selectors.
Data attributes that reflect component state or config into the DOM.
Public methods on the component instance.
AI-ready context for this document block. Provides structured info for AI/LLM use: constraints, disambiguation, anti-patterns, examples, and keywords.
References:
apiProperty, apiEvent, apiSlot, apiCssCustomProperty, apiCssPart, apiDataAttribute, apiMethod, agents
{
"properties": [
{
"identifier": "variant",
"type": "string",
"values": [
"primary",
"secondary",
"ghost",
"danger"
],
"description": "The visual style of the button.",
"required": false,
"defaultValue": "primary",
"since": "1.0.0"
},
{
"identifier": "disabled",
"type": "boolean",
"description": "When true, the button is non-interactive.",
"required": false,
"defaultValue": false,
"since": "1.0.0"
}
],
"events": [
{
"identifier": "onClick",
"description": "Fires when the button is activated.",
"returns": "(event: MouseEvent) => void",
"since": "1.0.0"
}
],
"slots": [
{
"identifier": "default",
"description": "The primary content slot.",
"acceptedContent": "Text, Icon, or a combination.",
"since": "1.0.0"
}
],
"cssCustomProperties": [
{
"identifier": "--button-background",
"description": "The background color of the button container.",
"defaultValue": "var(--color-action-primary)",
"type": "color",
"since": "1.0.0"
}
],
"cssParts": [
{
"identifier": "base",
"description": "The root container element of the button.",
"since": "1.0.0"
}
],
"dataAttributes": [
{
"identifier": "data-variant",
"description": "Reflects the current variant.",
"values": [
"primary",
"secondary",
"ghost",
"danger"
],
"since": "1.0.0"
}
],
"methods": [
{
"identifier": "focus",
"description": "Programmatically moves focus to the button element.",
"parameters": "(options?: FocusOptions)",
"returnType": "void",
"since": "1.0.0"
}
],
"kind": "api"
}
Design System Documentation Spec (DSDS) 0.2.1 — Draft Specification
GitHub