@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/button.json

@@ -0,0 +1,1006 @@
+{
+  "family": "button",
+  "ui": "button",
+  "binding": "react",
+  "catalog": {
+    "group": "Actions",
+    "summary": "Button, link button, icon button and toggle button."
+  },
+  "axes": {
+    "tone": [
+      "accent",
+      "secondary",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "variant": [
+      "solid",
+      "outline",
+      "ghost"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "shape": [
+      "square",
+      "circle"
+    ]
+  },
+  "members": {
+    "button": {
+      "nativeElement": "button",
+      "defaults": {
+        "tone": "accent",
+        "variant": "solid",
+        "size": "md",
+        "type": "button",
+        "fullWidth": false,
+        "disabled": false,
+        "focusableWhenDisabled": false,
+        "loading": false,
+        "loadingDelay": 0
+      },
+      "capabilities": [
+        "appearance",
+        "content",
+        "fullWidth",
+        "disabled",
+        "loading"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "start",
+        "label",
+        "end",
+        "indicator"
+      ]
+    },
+    "buttonLink": {
+      "nativeElement": "a",
+      "defaults": {
+        "tone": "accent",
+        "variant": "solid",
+        "size": "md",
+        "fullWidth": false,
+        "disabled": false
+      },
+      "capabilities": [
+        "appearance",
+        "content",
+        "fullWidth",
+        "disabled"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "start",
+        "label",
+        "end"
+      ]
+    },
+    "iconButton": {
+      "nativeElement": "button",
+      "defaults": {
+        "tone": "secondary",
+        "variant": "ghost",
+        "size": "md",
+        "shape": "square",
+        "type": "button",
+        "disabled": false,
+        "focusableWhenDisabled": false,
+        "loading": false,
+        "loadingDelay": 0
+      },
+      "capabilities": [
+        "appearance",
+        "shape",
+        "disabled",
+        "loading",
+        "pressed"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "loading",
+        "pressed"
+      ],
+      "parts": [
+        "root",
+        "icon",
+        "indicator"
+      ]
+    },
+    "toggleButton": {
+      "nativeElement": "button",
+      "defaults": {
+        "tone": "secondary",
+        "variant": "outline",
+        "size": "md",
+        "type": "button",
+        "fullWidth": false,
+        "disabled": false,
+        "focusableWhenDisabled": false,
+        "loading": false,
+        "loadingDelay": 0,
+        "defaultPressed": false
+      },
+      "capabilities": [
+        "appearance",
+        "content",
+        "fullWidth",
+        "disabled",
+        "loading",
+        "pressed"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "loading",
+        "pressed"
+      ],
+      "parts": [
+        "root",
+        "start",
+        "label",
+        "end",
+        "indicator"
+      ]
+    }
+  },
+  "docs": {
+    "button": {
+      "imports": {
+        "source": "import {\n  Button,\n  ButtonDefaultsProvider,\n  ButtonLink,\n  IconButton,\n  ToggleButton,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "button, or the element render returns",
+          "required": true,
+          "purpose": "The control. Carries data-ui=\"button\", data-tone, data-variant and data-size. It also carries data-full-width, data-disabled and data-loading when they apply."
+        },
+        {
+          "part": "start",
+          "element": "span",
+          "required": false,
+          "purpose": "Wraps the start content. Rendered only when start is passed. While loading, it holds the indicator."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "Wraps the children. Always rendered, because the accessible name is computed from it. With reduced motion or forced colours, a loading button with no icon fades it in place, and it keeps its size."
+        },
+        {
+          "part": "end",
+          "element": "span",
+          "required": false,
+          "purpose": "Wraps the end content. Rendered only when end is passed. While loading, it holds the indicator when there is no start content."
+        },
+        {
+          "part": "indicator",
+          "element": "span with role=\"progressbar\"",
+          "required": false,
+          "purpose": "The loading indicator. Carries data-ui=\"spinner\", is named by messages.loading, and has no value, so it reads as indeterminate. Rendered in the start box, else in the end box, else centred over the label, once loadingDelay has passed."
+        }
+      ],
+      "api": [
+        {
+          "name": "tone",
+          "type": "accent | secondary | success | warning | danger",
+          "defaultValue": "accent",
+          "appliesTo": "Button",
+          "description": "The semantic colour: accent for the primary action, secondary for a neutral one, and success, warning or danger for what the action does."
+        },
+        {
+          "name": "variant",
+          "type": "solid | outline | ghost",
+          "defaultValue": "solid",
+          "appliesTo": "Button",
+          "description": "How the tone is painted: solid, outline or ghost."
+        },
+        {
+          "name": "size",
+          "type": "sm | md | lg",
+          "defaultValue": "md",
+          "appliesTo": "Button",
+          "description": "The step of the control scale. Each step reads the --slotted-control-* tokens, so the density of the theme sets the height."
+        },
+        {
+          "name": "start",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Button",
+          "description": "Content before the label, such as an icon. It mirrors in a right-to-left document."
+        },
+        {
+          "name": "end",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Button",
+          "description": "Content after the label, such as an icon. It mirrors in a right-to-left document."
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Button",
+          "description": "Fills the inline size of the container."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Button",
+          "description": "Refuses the action and marks the control unavailable. On its own, it sets the native disabled attribute, which also removes the control from the tab sequence."
+        },
+        {
+          "name": "focusableWhenDisabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Button",
+          "description": "Keeps a disabled control in the tab sequence: aria-disabled replaces the native attribute, and activation is still refused."
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Button",
+          "description": "Refuses activation, keeps focus, and shows a progress indicator named by messages.loading."
+        },
+        {
+          "name": "loadingDelay",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "Button",
+          "description": "Milliseconds before the indicator appears. Activation is refused from the start of the wait."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<ButtonMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Button",
+          "description": "Overrides for the strings of the active locale, key by key. loading names the progress indicator."
+        },
+        {
+          "name": "render",
+          "type": "(rootProps) => ReactElement",
+          "defaultValue": "—",
+          "appliesTo": "Button",
+          "description": "Renders the root through another element. The function receives every root prop and must pass all of them on."
+        },
+        {
+          "name": "type",
+          "type": "button | submit | reset",
+          "defaultValue": "button",
+          "appliesTo": "Button",
+          "description": "The native button type. Set submit only for a button that submits its form."
+        }
+      ],
+      "composition": [
+        {
+          "name": "ButtonDefaultsProvider",
+          "type": "{ size?, tone?, variant?, children }",
+          "defaultValue": "—",
+          "appliesTo": "Button",
+          "description": "Sets the default size, tone and variant of every button inside it, ButtonLink, IconButton and ToggleButton included. An explicit prop wins, and an axis left unset keeps each member’s own default."
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "Button renders a native button element, so Space, Enter, focus and the disabled state come from the platform. The visible label supplies the accessible name.",
+        "While loading, the indicator is a progress bar named by messages.loading, and the button announces aria-disabled while it keeps focus. React Aria’s pending button and Primer’s loading button use the same pattern. aria-busy is not set: screen readers do not announce it reliably on a button, and one mechanism already carries the state.",
+        "Where motion is allowed, the indicator is not drawn: once loadingDelay has passed, a band in the button’s own ink sweeps behind the label and the icon, which stay visible. With reduced motion or forced colours, the indicator is a ring drawn in the start or end icon’s box; a button with neither draws it over the label, which drops to zero opacity but stays in the accessibility tree and in the layout, so the accessible name survives the wait and the button keeps its size.",
+        "loading refuses activation in the capture phase, before any click handler you attach, so a submit button cannot submit its form twice.",
+        "focusableWhenDisabled keeps a disabled button reachable. Use it when the button has a tooltip or an explanation a keyboard user needs, such as inside a toolbar. A reachable disabled button uses muted text on the subtle neutral background, at a contrast of 4.5:1 or more; a natively disabled button keeps the disabled grey.",
+        "An icon in start or end repeats the label, so mark it aria-hidden. Glyph sets aria-hidden itself.",
+        "type defaults to button. Set submit only for a button that submits its form."
+      ]
+    },
+    "buttonLink": {
+      "imports": {
+        "source": "import {\n  Button,\n  ButtonDefaultsProvider,\n  ButtonLink,\n  IconButton,\n  ToggleButton,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "a, or the element render returns",
+          "required": true,
+          "purpose": "The control. Carries data-ui=\"button\", data-tone, data-variant and data-size. It also carries data-full-width and data-disabled when they apply."
+        },
+        {
+          "part": "start",
+          "element": "span",
+          "required": false,
+          "purpose": "Wraps the start content. Rendered only when start is passed."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "Wraps the children. Always rendered, because the accessible name is computed from it."
+        },
+        {
+          "part": "end",
+          "element": "span",
+          "required": false,
+          "purpose": "Wraps the end content. Rendered only when end is passed."
+        }
+      ],
+      "api": [
+        {
+          "name": "href",
+          "type": "string",
+          "defaultValue": "required without render",
+          "appliesTo": "ButtonLink",
+          "description": "The destination. A disabled ButtonLink does not render it."
+        },
+        {
+          "name": "render",
+          "type": "(rootProps) => ReactElement",
+          "defaultValue": "—",
+          "appliesTo": "ButtonLink",
+          "description": "Renders the root through a router’s link component. The function receives every root prop and must pass all of them on."
+        },
+        {
+          "name": "tone",
+          "type": "accent | secondary | success | warning | danger",
+          "defaultValue": "accent",
+          "appliesTo": "ButtonLink",
+          "description": "The semantic colour: accent for the primary action, secondary for a neutral one, and success, warning or danger for what the action does."
+        },
+        {
+          "name": "variant",
+          "type": "solid | outline | ghost",
+          "defaultValue": "solid",
+          "appliesTo": "ButtonLink",
+          "description": "How the tone is painted: solid, outline or ghost."
+        },
+        {
+          "name": "size",
+          "type": "sm | md | lg",
+          "defaultValue": "md",
+          "appliesTo": "ButtonLink",
+          "description": "The step of the control scale. Each step reads the --slotted-control-* tokens, so the density of the theme sets the height."
+        },
+        {
+          "name": "start",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "ButtonLink",
+          "description": "Content before the label, such as an icon. It mirrors in a right-to-left document."
+        },
+        {
+          "name": "end",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "ButtonLink",
+          "description": "Content after the label, such as an icon. It mirrors in a right-to-left document."
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ButtonLink",
+          "description": "Fills the inline size of the container."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ButtonLink",
+          "description": "Removes the href and refuses activation. The link stays focusable with role=\"link\" and aria-disabled."
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "ButtonLink renders an anchor, so it is announced as a link and activates on Enter. Space does not activate it, as it does not activate any link.",
+        "Use ButtonLink for navigation only. An action without a destination is a Button.",
+        "A disabled ButtonLink renders no href. An anchor that kept its destination and only blocked click would still navigate on a middle click or a modified click.",
+        "A disabled ButtonLink stays in the tab sequence with role=\"link\" and aria-disabled, so a keyboard user can discover that it is unavailable.",
+        "The render function receives every root prop, including the accessible name and the data attributes, and must pass all of them to the element it renders."
+      ]
+    },
+    "iconButton": {
+      "imports": {
+        "source": "import {\n  Button,\n  ButtonDefaultsProvider,\n  ButtonLink,\n  IconButton,\n  ToggleButton,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "button, or the element render returns",
+          "required": true,
+          "purpose": "The control. Carries data-ui=\"button\", data-tone, data-variant and data-size. It also carries data-shape, and data-disabled, data-loading and data-pressed when they apply."
+        },
+        {
+          "part": "icon",
+          "element": "span",
+          "required": true,
+          "purpose": "Wraps the children. While loading, it holds the indicator drawn over the icon, so the control keeps its size."
+        },
+        {
+          "part": "indicator",
+          "element": "span with role=\"progressbar\"",
+          "required": false,
+          "purpose": "The loading indicator. Carries data-ui=\"spinner\", is named by messages.loading, and has no value, so it reads as indeterminate. Rendered inside the icon box once loadingDelay has passed."
+        }
+      ],
+      "api": [
+        {
+          "name": "aria-label | aria-labelledby",
+          "type": "string",
+          "defaultValue": "required",
+          "appliesTo": "IconButton",
+          "description": "The accessible name. Required, because an icon supplies no text. When both are present, aria-labelledby names the button."
+        },
+        {
+          "name": "tone",
+          "type": "accent | secondary | success | warning | danger",
+          "defaultValue": "secondary",
+          "appliesTo": "IconButton",
+          "description": "The semantic colour: accent for the primary action, secondary for a neutral one, and success, warning or danger for what the action does."
+        },
+        {
+          "name": "variant",
+          "type": "solid | outline | ghost",
+          "defaultValue": "ghost",
+          "appliesTo": "IconButton",
+          "description": "How the tone is painted: solid, outline or ghost."
+        },
+        {
+          "name": "size",
+          "type": "sm | md | lg",
+          "defaultValue": "md",
+          "appliesTo": "IconButton",
+          "description": "The step of the control scale. Each step reads the --slotted-control-* tokens, so the density of the theme sets the height."
+        },
+        {
+          "name": "shape",
+          "type": "square | circle",
+          "defaultValue": "square",
+          "appliesTo": "IconButton",
+          "description": "The corners of the control: square keeps the radius of the control scale, circle rounds it fully. Both are as wide as they are tall."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "IconButton",
+          "description": "Refuses the action and marks the control unavailable. On its own, it sets the native disabled attribute, which also removes the control from the tab sequence."
+        },
+        {
+          "name": "focusableWhenDisabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "IconButton",
+          "description": "Keeps a disabled control in the tab sequence: aria-disabled replaces the native attribute, and activation is still refused."
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "IconButton",
+          "description": "Refuses activation, keeps focus, and shows a progress indicator named by messages.loading."
+        },
+        {
+          "name": "loadingDelay",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "IconButton",
+          "description": "Milliseconds before the indicator appears. Activation is refused from the start of the wait."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<ButtonMessages>",
+          "defaultValue": "—",
+          "appliesTo": "IconButton",
+          "description": "Overrides for the strings of the active locale, key by key. loading names the progress indicator."
+        },
+        {
+          "name": "render",
+          "type": "(rootProps) => ReactElement",
+          "defaultValue": "—",
+          "appliesTo": "IconButton",
+          "description": "Renders the root through another element. The function receives every root prop and must pass all of them on."
+        },
+        {
+          "name": "pressed",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "IconButton",
+          "description": "The pressed state, controlled. Passing it makes the button a toggle whose value you own."
+        },
+        {
+          "name": "defaultPressed",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "IconButton",
+          "description": "The initial pressed state when the button owns it, read once. Passing it makes the button a toggle."
+        },
+        {
+          "name": "onPressedChange",
+          "type": "(pressed, request) => void",
+          "defaultValue": "—",
+          "appliesTo": "IconButton",
+          "description": "Called with the requested value and the request: value, previous value, reason (pointer or keyboard), event and cancel()."
+        },
+        {
+          "name": "type",
+          "type": "button | submit | reset",
+          "defaultValue": "button",
+          "appliesTo": "IconButton",
+          "description": "The native button type. Set submit only for a button that submits its form."
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "The type requires an accessible name: pass aria-label or aria-labelledby. An icon supplies no text the name could be computed from.",
+        "aria-pressed is rendered only when pressed or defaultPressed is passed, so a plain icon button does not announce a toggle state it does not have.",
+        "Keep the name the same in both pressed states. The APG toggle button pattern announces the state beside an unchanging label.",
+        "A pressed icon button uses the selected colours of the theme — accent text on the accent selection background, inside the accent edge — whatever its tone and variant. On hover it uses the hover step of that background, not the neutral hover of an unpressed button.",
+        "The control is as wide as it is tall, at the control height, and never smaller than the WCAG 2.2 minimum target of 24 by 24 CSS pixels at any density.",
+        "Add a tooltip when the icon alone does not say what the action does. The accessible name does not replace a visible label."
+      ]
+    },
+    "toggleButton": {
+      "imports": {
+        "source": "import {\n  Button,\n  ButtonDefaultsProvider,\n  ButtonLink,\n  IconButton,\n  ToggleButton,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "button, or the element render returns",
+          "required": true,
+          "purpose": "The control. Carries data-ui=\"button\", data-tone, data-variant and data-size. It also carries data-full-width, data-disabled, data-loading and data-pressed when they apply."
+        },
+        {
+          "part": "start",
+          "element": "span",
+          "required": false,
+          "purpose": "Wraps the start content. Rendered only when start is passed. While loading, it holds the indicator."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "Wraps the children. Always rendered, because the accessible name is computed from it. With reduced motion or forced colours, a loading button with no icon fades it in place, and it keeps its size."
+        },
+        {
+          "part": "end",
+          "element": "span",
+          "required": false,
+          "purpose": "Wraps the end content. Rendered only when end is passed. While loading, it holds the indicator when there is no start content."
+        },
+        {
+          "part": "indicator",
+          "element": "span with role=\"progressbar\"",
+          "required": false,
+          "purpose": "The loading indicator. Carries data-ui=\"spinner\", is named by messages.loading, and has no value, so it reads as indeterminate. Rendered in the start box, else in the end box, else centred over the label, once loadingDelay has passed."
+        }
+      ],
+      "api": [
+        {
+          "name": "tone",
+          "type": "accent | secondary | success | warning | danger",
+          "defaultValue": "secondary",
+          "appliesTo": "ToggleButton",
+          "description": "The semantic colour: accent for the primary action, secondary for a neutral one, and success, warning or danger for what the action does."
+        },
+        {
+          "name": "variant",
+          "type": "solid | outline | ghost",
+          "defaultValue": "outline",
+          "appliesTo": "ToggleButton",
+          "description": "How the tone is painted: solid, outline or ghost."
+        },
+        {
+          "name": "size",
+          "type": "sm | md | lg",
+          "defaultValue": "md",
+          "appliesTo": "ToggleButton",
+          "description": "The step of the control scale. Each step reads the --slotted-control-* tokens, so the density of the theme sets the height."
+        },
+        {
+          "name": "start",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "ToggleButton",
+          "description": "Content before the label, such as an icon. It mirrors in a right-to-left document."
+        },
+        {
+          "name": "end",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "ToggleButton",
+          "description": "Content after the label, such as an icon. It mirrors in a right-to-left document."
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ToggleButton",
+          "description": "Fills the inline size of the container."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ToggleButton",
+          "description": "Refuses the action and marks the control unavailable. On its own, it sets the native disabled attribute, which also removes the control from the tab sequence."
+        },
+        {
+          "name": "focusableWhenDisabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ToggleButton",
+          "description": "Keeps a disabled control in the tab sequence: aria-disabled replaces the native attribute, and activation is still refused."
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ToggleButton",
+          "description": "Refuses activation, keeps focus, and shows a progress indicator named by messages.loading."
+        },
+        {
+          "name": "loadingDelay",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "ToggleButton",
+          "description": "Milliseconds before the indicator appears. Activation is refused from the start of the wait."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<ButtonMessages>",
+          "defaultValue": "—",
+          "appliesTo": "ToggleButton",
+          "description": "Overrides for the strings of the active locale, key by key. loading names the progress indicator."
+        },
+        {
+          "name": "render",
+          "type": "(rootProps) => ReactElement",
+          "defaultValue": "—",
+          "appliesTo": "ToggleButton",
+          "description": "Renders the root through another element. The function receives every root prop and must pass all of them on."
+        },
+        {
+          "name": "pressed",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "ToggleButton",
+          "description": "The pressed state, controlled. Passing it makes you the owner of the value."
+        },
+        {
+          "name": "defaultPressed",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "ToggleButton",
+          "description": "The initial pressed state when the button owns it, read once."
+        },
+        {
+          "name": "onPressedChange",
+          "type": "(pressed, request) => void",
+          "defaultValue": "—",
+          "appliesTo": "ToggleButton",
+          "description": "Called with the requested value and the request: value, previous value, reason (pointer or keyboard), event and cancel()."
+        },
+        {
+          "name": "type",
+          "type": "button | submit | reset",
+          "defaultValue": "button",
+          "appliesTo": "ToggleButton",
+          "description": "The native button type. Set submit only for a button that submits its form."
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "ToggleButton renders a native button with aria-pressed, so it is announced as a toggle button and activates on Space and Enter.",
+        "Keep the label the same in both states: \"Mute\" stays \"Mute\" and the state is announced beside it. When the label has to change, use a Button.",
+        "The change request carries a reason. A native button fires the same click for a pointer, Space and Enter; the reason is pointer when the click reports a click count and keyboard when it reports none.",
+        "Calling preventDefault in onClick refuses the activation, and the pressed state does not change.",
+        "Use Checkbox, not ToggleButton, for a value a form submits.",
+        "A toggle that saves to a server can set loading while the request runs. Activation is refused during the wait, so the button keeps the state it had until loading ends."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-font-weight",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-letter-spacing",
+    "--slotted-control-line-height",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-instant",
+    "--slotted-duration-loop",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-line-height-sm",
+    "--slotted-radius-full",
+    "--slotted-space-2",
+    "--slotted-target-min",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-on-solid",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-accent-solid-active",
+    "--slotted-tone-accent-solid-hover",
+    "--slotted-tone-accent-subtle-active",
+    "--slotted-tone-accent-subtle-hover",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-on-solid",
+    "--slotted-tone-danger-solid",
+    "--slotted-tone-danger-solid-active",
+    "--slotted-tone-danger-solid-hover",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-on-solid",
+    "--slotted-tone-secondary-solid",
+    "--slotted-tone-secondary-solid-active",
+    "--slotted-tone-secondary-solid-hover",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-tone-secondary-text",
+    "--slotted-tone-success-on-solid",
+    "--slotted-tone-success-solid",
+    "--slotted-tone-success-solid-active",
+    "--slotted-tone-success-solid-hover",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-on-solid",
+    "--slotted-tone-warning-solid",
+    "--slotted-tone-warning-solid-active",
+    "--slotted-tone-warning-solid-hover",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "react-button-basic",
+      "title": "An action",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Save } from 'lucide-react';\n\n<Button start={<Save aria-hidden=\"true\" />}>Save changes</Button>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-button-loading",
+      "title": "Waiting for the action to finish",
+      "note": null,
+      "language": "tsx",
+      "source": "<Button\n  loading={saving}\n  loadingDelay={300}\n  messages={{ loading: 'Saving' }}\n  onClick={save}\n  start={<Save aria-hidden=\"true\" />}\n>\n  Save changes\n</Button>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-button-defaults",
+      "title": "Every action in the application, decided once",
+      "note": null,
+      "language": "tsx",
+      "source": "<ButtonDefaultsProvider size=\"sm\">\n  <Toolbar />\n</ButtonDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-button-emphasis",
+      "title": "One primary action per region",
+      "note": null,
+      "language": "tsx",
+      "source": "<Inline gap={4}>\n  <Button>Publish</Button>\n  <Button tone=\"secondary\" variant=\"outline\">\n    Save draft\n  </Button>\n  <Button tone=\"secondary\" variant=\"ghost\">\n    Discard\n  </Button>\n</Inline>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-button-link-native",
+      "title": "Navigating",
+      "note": null,
+      "language": "tsx",
+      "source": "<ButtonLink href=\"/settings\">Open settings</ButtonLink>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-button-link-router",
+      "title": "Navigation the router owns",
+      "note": null,
+      "language": "tsx",
+      "source": "<ButtonLink variant=\"outline\" render={(props) => <RouterLink to=\"/settings\" {...props} />}>\n  Open settings\n</ButtonLink>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-icon-button-basic",
+      "title": "A named icon-only action",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Trash2 } from 'lucide-react';\n\n<IconButton aria-label=\"Delete invoice\" tone=\"danger\">\n  <Trash2 aria-hidden=\"true\" />\n</IconButton>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-icon-button-toggle",
+      "title": "An icon toggle in a toolbar",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Bold } from 'lucide-react';\n\n<IconButton\n  aria-label=\"Bold\"\n  pressed={bold}\n  onPressedChange={(bold) => setBold(bold)}\n  tone=\"secondary\"\n>\n  <Bold aria-hidden=\"true\" />\n</IconButton>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-toggle-button-uncontrolled",
+      "title": "A toggle that owns its own state",
+      "note": null,
+      "language": "tsx",
+      "source": "<ToggleButton defaultPressed>Pin</ToggleButton>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "react-toggle-button-controlled",
+      "title": "A toggle the consumer owns, with the reason",
+      "note": null,
+      "language": "tsx",
+      "source": "<ToggleButton\n  pressed={pinned}\n  onPressedChange={(pinned, request) => {\n    if (request.reason === 'keyboard') announce(pinned);\n    setPinned(pinned);\n  }}\n>\n  Pin\n</ToggleButton>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "basic",
+      "title": "basic.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Button } from '@slotted/react/button';\n\nexport default function ButtonBasic() {\n  return <Button onClick={() => console.log('saved')}>Save changes</Button>;\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "confirm-delete",
+      "title": "confirm-delete.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\n\nimport { Button } from '@slotted/react/button';\nimport {\n  AlertDialog,\n  AlertDialogAction,\n  AlertDialogCancel,\n  AlertDialogIcon,\n  DialogContent,\n  DialogDescription,\n  DialogFooter,\n  DialogHeader,\n  DialogTitle,\n  DialogTrigger,\n} from '@slotted/react/dialog';\nimport { Glyph } from '@slotted/react/icon';\nimport { Inline } from '@slotted/react/inline';\nimport { Text } from '@slotted/react/typography';\n\nexport default function ButtonConfirmDelete() {\n  const [open, setOpen] = useState(false);\n  const [deleted, setDeleted] = useState(false);\n\n  return (\n    <Inline align=\"center\" gap={2}>\n      <AlertDialog onOpenChange={setOpen} open={open}>\n        <DialogTrigger\n          render={(props) => (\n            <Button\n              {...props}\n              disabled={deleted}\n              focusableWhenDisabled\n              start={<Glyph name=\"trash\" />}\n              tone=\"danger\"\n              variant=\"outline\"\n            >\n              Delete supplier\n            </Button>\n          )}\n        />\n        <DialogContent>\n          <DialogHeader>\n            <AlertDialogIcon />\n            <DialogTitle>Delete Northwind Traders?</DialogTitle>\n            <DialogDescription>\n              The supplier and its 18 open purchase orders are removed for everyone. This cannot be\n              undone.\n            </DialogDescription>\n          </DialogHeader>\n          <DialogFooter>\n            <AlertDialogCancel\n              render={(props) => (\n                <Button {...props} tone=\"secondary\" variant=\"outline\">\n                  Keep supplier\n                </Button>\n              )}\n            />\n            <AlertDialogAction\n              onClick={() => setDeleted(true)}\n              render={(props) => (\n                <Button {...props} tone=\"danger\">\n                  Delete supplier\n                </Button>\n              )}\n            />\n          </DialogFooter>\n        </DialogContent>\n      </AlertDialog>\n      {deleted ? (\n        <>\n          <Text size=\"sm\" tone=\"muted\">\n            Northwind Traders was deleted.\n          </Text>\n          <Button onClick={() => setDeleted(false)} size=\"sm\" tone=\"secondary\" variant=\"ghost\">\n            Undo\n          </Button>\n        </>\n      ) : null}\n    </Inline>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Button, ButtonDefaultsProvider } from '@slotted/react/button';\nimport { Glyph } from '@slotted/react/icon';\nimport { Inline } from '@slotted/react/inline';\n\nexport default function ButtonDefaults() {\n  return (\n    <ButtonDefaultsProvider size=\"sm\" tone=\"secondary\" variant=\"outline\">\n      <Inline gap={2}>\n        <Button start={<Glyph name=\"funnel\" />}>Filter</Button>\n        <Button>Columns</Button>\n        <Button>Export</Button>\n        <Button start={<Glyph name=\"plus\" />} tone=\"accent\" variant=\"solid\">\n          New order\n        </Button>\n      </Inline>\n    </ButtonDefaultsProvider>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "disabled",
+      "title": "disabled.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useId } from 'react';\n\nimport { Button } from '@slotted/react/button';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { Text } from '@slotted/react/typography';\n\nexport default function ButtonDisabled() {\n  const hintId = useId();\n\n  return (\n    <Stack gap={2}>\n      <Inline gap={2}>\n        <Button disabled tone=\"secondary\" variant=\"outline\">\n          Export\n        </Button>\n        <Button aria-describedby={hintId} disabled focusableWhenDisabled>\n          Submit for approval\n        </Button>\n      </Inline>\n      <Text id={hintId} size=\"sm\" tone=\"muted\">\n        Add at least one line item before submitting.\n      </Text>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "full-width",
+      "title": "full-width.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Button } from '@slotted/react/button';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function ButtonFullWidth() {\n  return (\n    <Stack gap={2}>\n      <Button fullWidth>Pay $1,240.00</Button>\n      <Button fullWidth tone=\"secondary\" variant=\"outline\">\n        Pay by bank transfer\n      </Button>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "group",
+      "title": "group.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Button, IconButton } from '@slotted/react/button';\nimport { ButtonGroup } from '@slotted/react/button-group';\nimport { Glyph } from '@slotted/react/icon';\n\nexport default function ButtonGroupExample() {\n  return (\n    <ButtonGroup aria-label=\"Invoice actions\" tone=\"secondary\" variant=\"outline\">\n      <Button>Edit</Button>\n      <Button>Duplicate</Button>\n      <Button>Send</Button>\n      <IconButton aria-label=\"More invoice actions\">\n        <Glyph name=\"ellipsis\" />\n      </IconButton>\n    </ButtonGroup>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "icon-button",
+      "title": "icon-button.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { IconButton } from '@slotted/react/button';\nimport { Glyph } from '@slotted/react/icon';\nimport { Inline } from '@slotted/react/inline';\n\nexport default function ButtonIconButton() {\n  return (\n    <Inline align=\"center\" gap={2}>\n      <IconButton aria-label=\"Copy invoice number\">\n        <Glyph name=\"copy\" />\n      </IconButton>\n      <IconButton aria-label=\"Refresh balances\" variant=\"outline\">\n        <Glyph name=\"rotate-ccw\" />\n      </IconButton>\n      <IconButton aria-label=\"Delete draft\" tone=\"danger\">\n        <Glyph name=\"trash\" />\n      </IconButton>\n      <IconButton aria-label=\"Add note\" shape=\"circle\" tone=\"accent\" variant=\"solid\">\n        <Glyph name=\"plus\" />\n      </IconButton>\n    </Inline>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "icons",
+      "title": "icons.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Button } from '@slotted/react/button';\nimport { Glyph } from '@slotted/react/icon';\nimport { Inline } from '@slotted/react/inline';\n\nexport default function ButtonIcons() {\n  return (\n    <Inline gap={2}>\n      <Button start={<Glyph name=\"plus\" />}>New order</Button>\n      <Button start={<Glyph name=\"upload\" />} tone=\"secondary\" variant=\"outline\">\n        Import CSV\n      </Button>\n      <Button end={<Glyph name=\"chevron-right\" />} tone=\"secondary\" variant=\"ghost\">\n        Continue to payment\n      </Button>\n    </Inline>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "link",
+      "title": "link.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { ButtonLink } from '@slotted/react/button';\nimport { Glyph } from '@slotted/react/icon';\nimport { Inline } from '@slotted/react/inline';\n\nexport default function ButtonLinkExample() {\n  return (\n    <Inline gap={2}>\n      <ButtonLink end={<Glyph name=\"chevron-right\" />} href=\"/invoices/INV-2041\">\n        View invoice\n      </ButtonLink>\n      <ButtonLink disabled href=\"/statements/2026-09.pdf\" tone=\"secondary\" variant=\"outline\">\n        Download statement\n      </ButtonLink>\n    </Inline>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "loading",
+      "title": "loading.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\n\nimport { Button } from '@slotted/react/button';\nimport { Glyph } from '@slotted/react/icon';\nimport { Inline } from '@slotted/react/inline';\n\nexport default function ButtonLoading() {\n  const [syncing, setSyncing] = useState(false);\n  const [sending, setSending] = useState(false);\n\n  const sync = () => {\n    setSyncing(true);\n    setTimeout(() => setSyncing(false), 2000);\n  };\n  const send = () => {\n    setSending(true);\n    setTimeout(() => setSending(false), 2000);\n  };\n\n  return (\n    <Inline gap={2}>\n      <Button\n        loading={syncing}\n        messages={{ loading: 'Syncing' }}\n        onClick={sync}\n        start={<Glyph name=\"rotate-ccw\" />}\n        tone=\"secondary\"\n        variant=\"outline\"\n      >\n        Sync inventory\n      </Button>\n      <Button loading={sending} loadingDelay={300} messages={{ loading: 'Sending' }} onClick={send}>\n        Send invoice\n      </Button>\n    </Inline>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "sizes",
+      "title": "sizes.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Button } from '@slotted/react/button';\nimport { Inline } from '@slotted/react/inline';\n\nexport default function ButtonSizes() {\n  return (\n    <Inline align=\"center\" gap={2}>\n      <Button size=\"sm\">Add line item</Button>\n      <Button size=\"md\">Add line item</Button>\n      <Button size=\"lg\">Add line item</Button>\n    </Inline>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "toggle",
+      "title": "toggle.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\n\nimport { IconButton, ToggleButton } from '@slotted/react/button';\nimport { Glyph } from '@slotted/react/icon';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { Text } from '@slotted/react/typography';\n\nexport default function ButtonToggle() {\n  const [autoRefresh, setAutoRefresh] = useState(true);\n\n  return (\n    <Stack gap={2}>\n      <Inline align=\"center\" gap={2}>\n        <ToggleButton onPressedChange={(pressed) => setAutoRefresh(pressed)} pressed={autoRefresh}>\n          Auto-refresh\n        </ToggleButton>\n        <ToggleButton defaultPressed start={<Glyph name=\"pin\" />}>\n          Pin to dashboard\n        </ToggleButton>\n        <IconButton aria-label=\"Mark as priority\" defaultPressed={false}>\n          <Glyph name=\"star\" />\n        </IconButton>\n      </Inline>\n      <Text size=\"sm\" tone=\"muted\">\n        {autoRefresh ? 'Balances refresh every 30 seconds.' : 'Balances refresh on demand.'}\n      </Text>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "tones",
+      "title": "tones.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Button } from '@slotted/react/button';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function ButtonTones() {\n  return (\n    <Stack gap={3}>\n      <Inline gap={2}>\n        <Button>Create order</Button>\n        <Button tone=\"secondary\">Export</Button>\n        <Button tone=\"success\">Approve</Button>\n        <Button tone=\"warning\">Hold shipment</Button>\n        <Button tone=\"danger\">Void invoice</Button>\n      </Inline>\n      <Inline gap={2}>\n        <Button variant=\"outline\">Create order</Button>\n        <Button tone=\"secondary\" variant=\"outline\">\n          Export\n        </Button>\n        <Button tone=\"success\" variant=\"outline\">\n          Approve\n        </Button>\n        <Button tone=\"warning\" variant=\"outline\">\n          Hold shipment\n        </Button>\n        <Button tone=\"danger\" variant=\"outline\">\n          Void invoice\n        </Button>\n      </Inline>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "toolbar",
+      "title": "toolbar.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useId } from 'react';\n\nimport { Button, IconButton } from '@slotted/react/button';\nimport { Glyph } from '@slotted/react/icon';\nimport { Toolbar, ToolbarSeparator, ToolbarSpacer } from '@slotted/react/toolbar';\nimport { Text } from '@slotted/react/typography';\n\nexport default function ButtonToolbar() {\n  const reasonId = useId();\n\n  return (\n    <Toolbar aria-label=\"Order SO-1187\">\n      <Button start={<Glyph name=\"file-text\" />} tone=\"secondary\" variant=\"ghost\">\n        Packing slip\n      </Button>\n      <Button tone=\"secondary\" variant=\"ghost\">\n        Duplicate\n      </Button>\n      <ToolbarSeparator />\n      <IconButton aria-label=\"Copy order number\">\n        <Glyph name=\"copy\" />\n      </IconButton>\n      <IconButton\n        aria-describedby={reasonId}\n        aria-label=\"Delete order\"\n        disabled\n        focusableWhenDisabled\n        tone=\"danger\"\n      >\n        <Glyph name=\"trash\" />\n      </IconButton>\n      <ToolbarSpacer />\n      <Text id={reasonId} size=\"sm\" tone=\"muted\">\n        Shipped orders cannot be deleted.\n      </Text>\n    </Toolbar>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "variants",
+      "title": "variants.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Button } from '@slotted/react/button';\nimport { Inline } from '@slotted/react/inline';\n\nexport default function ButtonVariants() {\n  return (\n    <Inline gap={2}>\n      <Button>Publish invoice</Button>\n      <Button tone=\"secondary\" variant=\"outline\">\n        Save draft\n      </Button>\n      <Button tone=\"secondary\" variant=\"ghost\">\n        Discard\n      </Button>\n    </Inline>\n  );\n}\n",
+      "verdict": "example"
+    }
+  ]
+}