@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/autocomplete.json

@@ -0,0 +1,197 @@
+{
+  "name": "Autocomplete",
+  "slug": "autocomplete",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A text field that suggests as you type — and accepts what you typed anyway.\n\nThe counterpart to {@link Combobox }: there the list *is* the set of legal\nvalues, here it is only a shortcut. Anything the user types survives blur, so\nthis is the right control for a name, a search term or a host — anywhere the\nsuggestions are a convenience rather than a constraint.\n\nSuggestions are plain strings for the same reason: an autocomplete has no\nseparate value/label axis, because the label *is* the value.\n\nThe popup is portalled through {@link useCuePortalProps}, so it carries the\ncaller's `data-theme` / `data-density` / `data-mode`.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The suggestions, filtered against what is typed."
+    },
+    {
+      "name": "value",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Current text. Use with `onValueChange` for a controlled field."
+    },
+    {
+      "name": "defaultValue",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial text for an uncontrolled field."
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Fired on every keystroke and when a suggestion is picked."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Shown while the field is empty."
+    },
+    {
+      "name": "emptyMessage",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "No matches",
+      "description": "Shown in place of the list when the query matches nothing."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "autoHighlight",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Highlight the first match automatically so Enter accepts it."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Prevent opening and grey the field out."
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Require text before the owning form submits."
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Name for the input, when the field is part of a form."
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id forwarded to the input."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the input, when no {@link FieldLabel } names it."
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id of the element naming the input."
+    },
+    {
+      "name": "clearLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Clear",
+      "description": "Accessible name for the clear button. Defaults to `\"Clear\"`."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the field."
+    },
+    {
+      "name": "popupClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the popup surface."
+    },
+    {
+      "name": "sideOffset",
+      "type": "number",
+      "required": false,
+      "defaultValue": "4",
+      "description": "Distance in px between the field and the popup. Defaults to `4`."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-chip-h",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A text field that suggests as you type — and accepts what you typed anyway.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Autocomplete aria-label=\"Cue name\" items={recentCues} onValueChange={setName} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/autocomplete",
+  "mdUrl": "/docs/components/autocomplete.md",
+  "jsonUrl": "/r/components/autocomplete.json",
+  "specimens": [
+    {
+      "title": "Autocomplete",
+      "group": "forms",
+      "components": [
+        "Autocomplete"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Autocomplete aria-label=\"Protocol\" items={PROTOCOLS} placeholder=\"Protocol\" />\n  <Autocomplete\n    aria-label=\"Protocol, highlighted\"\n    items={PROTOCOLS}\n    defaultValue=\"Art\"\n    autoHighlight\n  />\n  <Autocomplete aria-label=\"Protocol, disabled\" items={PROTOCOLS} defaultValue=\"OSC\" disabled />\n</div>",
+      "note": "Suggestions over free text: the field keeps whatever was typed, and the list only offers.",
+      "interaction": "the list opens on input, not on focus; `autoHighlight` pre-selects the first match."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/avatar-group.json

@@ -0,0 +1,72 @@
+{
+  "name": "AvatarGroup",
+  "slug": "avatar-group",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "An overlapping stack of {@link Avatar}s with a `+N` overflow chip.\n\nEach item after the first is pulled left by a negative inline-start margin\nand ringed in the page background colour, which is what reads as \"stacked\"\nrather than \"crowded\". Logical margins, so the stack flips correctly in RTL.",
+  "props": [
+    {
+      "name": "max",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Show at most this many avatars; the rest collapse into a `+N` chip. Omit for no limit."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Size of the `+N` overflow chip. Match it to the avatars you pass in. Defaults to `\"md\"`."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "An overlapping stack of {@link Avatar}s with a `+N` overflow chip.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<AvatarGroup max={3}>\n  {users.map((u) => <Avatar key={u.id} alt={u.name} src={u.avatar} />)}\n</AvatarGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/avatar-group",
+  "mdUrl": "/docs/components/avatar-group.md",
+  "jsonUrl": "/r/components/avatar-group.json",
+  "specimens": [
+    {
+      "title": "AvatarGroup",
+      "group": "primitives",
+      "components": [
+        "AvatarGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <AvatarGroup>\n      <Avatar fallback=\"CR\" />\n      <Avatar fallback=\"JM\" />\n      <Avatar fallback=\"AP\" />\n    </AvatarGroup>\n  </Specimen>\n  <Specimen label=\"max 2\">\n    <AvatarGroup max={2}>\n      <Avatar fallback=\"CR\" />\n      <Avatar fallback=\"JM\" />\n      <Avatar fallback=\"AP\" />\n      <Avatar fallback=\"LS\" />\n    </AvatarGroup>\n  </Specimen>\n</Specimens>",
+      "note": "Overlapping faces with an overflow count.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/avatar.json

@@ -0,0 +1,95 @@
+{
+  "name": "Avatar",
+  "slug": "avatar",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A round user/entity avatar sized off the density control ladder, so it lines\nup with the buttons and inputs on the same row.\n\nWraps Base UI's `Avatar`, which owns the image-loading state machine: the\nfallback shows immediately, is replaced when the image decodes, and comes\nback if the image errors.",
+  "props": [
+    {
+      "name": "src",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Image URL. Omit to go straight to the fallback."
+    },
+    {
+      "name": "alt",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Alt text for the image, and the name the default initials are derived from."
+    },
+    {
+      "name": "fallback",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What to show while the image loads or after it fails. Defaults to initials from `alt`."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">",
+    "VariantProps<typeof avatarVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "size": "md"
+  },
+  "tokensUsed": [
+    "--cue-bg",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "A round user/entity avatar sized off the density control ladder, so it lines up with the buttons and inputs on the same row.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Avatar alt=\"Ada Lovelace\" src=\"/ada.png\" />\n<Avatar alt=\"Ada Lovelace\" size=\"sm\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/avatar",
+  "mdUrl": "/docs/components/avatar.md",
+  "jsonUrl": "/r/components/avatar.json",
+  "specimens": [
+    {
+      "title": "Avatar",
+      "group": "primitives",
+      "components": [
+        "Avatar"
+      ],
+      "code": "<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={size}>\n      <Avatar size={size} fallback=\"CR\" />\n    </Specimen>\n  ))}\n  <Specimen label=\"image\">\n    <Avatar\n      src=\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' fill='%23888'/%3E%3C/svg%3E\"\n      alt=\"Operator portrait\"\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Initials fall back when there is no image; the ring is drawn in the background colour so a pile reads as separate faces.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/breadcrumb.json

@@ -0,0 +1,74 @@
+{
+  "name": "Breadcrumb",
+  "slug": "breadcrumb",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Where you are, and how to get back.\n\nThe last crumb is never a link: it is the page you are on, marked\n`aria-current=\"page\"` and set in full-strength ink so the trail has one\nvisible end. Separators are `aria-hidden` — a screen reader announcing\n\"console slash patch slash universe 1\" is reading punctuation, not structure.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly BreadcrumbItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The trail, root first. The last entry is the current page."
+    },
+    {
+      "name": "separator",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "/",
+      "description": "What sits between crumbs. Defaults to `\"/\"`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Breadcrumb",
+      "description": "The nav's accessible name. Defaults to `\"Breadcrumb\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"nav\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "Where you are, and how to get back.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Breadcrumb items={[{ label: \"Console\", href: \"/\" }, { label: \"Patch\" }]} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/breadcrumb",
+  "mdUrl": "/docs/components/breadcrumb.md",
+  "jsonUrl": "/r/components/breadcrumb.json",
+  "specimens": [
+    {
+      "title": "Breadcrumb",
+      "group": "layout",
+      "components": [
+        "Breadcrumb"
+      ],
+      "code": "<Breadcrumb items={CRUMBS} />",
+      "note": "Where you are, with `aria-hidden` punctuation between the crumbs and the last one marked current.",
+      "interaction": "every crumb but the last is a link; the last is plain text."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/button-group.json

@@ -0,0 +1,74 @@
+{
+  "name": "ButtonGroup",
+  "slug": "button-group",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Several related actions drawn as one control.\n\nPurely presentational: it owns no state and imposes no roving focus, because\nits members are *actions*, each independently reachable by Tab. When the\nmembers represent a **choice** rather than actions, use {@link ToggleGroup }\n(several or none) or `SegmentedControl` (exactly one) — those carry the\npressed-state ARIA a group of plain buttons must not fake.\n\nThe children keep their own variants, so a `secondary`/`primary` pair reads as\n\"and here is the one you probably want\" without any extra API.",
+  "props": [
+    {
+      "name": "orientation",
+      "type": "\"horizontal\" | \"vertical\"",
+      "required": false,
+      "defaultValue": "horizontal",
+      "description": "Which way the children run. Defaults to `\"horizontal\"`."
+    },
+    {
+      "name": "attached",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Join the children into one control (shared rims, outer corners only).\nDefaults to `true`; pass `false` for a merely-adjacent row of buttons that\nshould still be announced as one group."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the cluster. A group of buttons with no name is a group\nof buttons; with one it is \"Blend mode\"."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The buttons — {@link Button }, {@link IconButton } or anything button-shaped."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-space-2"
+  ],
+  "summary": "Several related actions drawn as one control.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ButtonGroup aria-label=\"Blend mode\">\n  <Button>HTP</Button>\n  <Button variant=\"primary\">LTP</Button>\n</ButtonGroup>\n<ButtonGroup aria-label=\"Zoom\" orientation=\"vertical\">\n  <IconButton aria-label=\"Zoom in\" icon={Plus} variant=\"outline\" />\n  <IconButton aria-label=\"Zoom out\" icon={Minus} variant=\"outline\" />\n</ButtonGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/button-group",
+  "mdUrl": "/docs/components/button-group.md",
+  "jsonUrl": "/r/components/button-group.json",
+  "specimens": [
+    {
+      "title": "ButtonGroup",
+      "group": "forms",
+      "components": [
+        "ButtonGroup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"attached\">\n    <ButtonGroup>\n      <Button>Patch</Button>\n      <Button>Unpatch</Button>\n      <Button>Swap</Button>\n    </ButtonGroup>\n  </Specimen>\n  <Specimen label=\"spaced\">\n    <ButtonGroup attached={false}>\n      <Button>Patch</Button>\n      <Button variant=\"primary\">Apply</Button>\n    </ButtonGroup>\n  </Specimen>\n  <Specimen label=\"vertical\">\n    <ButtonGroup orientation=\"vertical\">\n      <Button>Up</Button>\n      <Button>Down</Button>\n    </ButtonGroup>\n  </Specimen>\n</Specimens>",
+      "note": "Buttons welded into one control, horizontally or vertically.",
+      "interaction": "each button keeps its own focus ring; only the outer corners are rounded."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/button.json

@@ -0,0 +1,125 @@
+{
+  "name": "Button",
+  "slug": "button",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The system's primary action control.\n\nA real `<button>` by default, restyled entirely from tokens: height comes\nfrom the density control ladder, colour from the theme's accent/surface ramp.\nThe focus ring is an `outline`, never a `box-shadow`, so it survives inside\n`overflow: hidden` panels.",
+  "props": [
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop). Accepts an element —\n`render={<a href=\"/x\" />}` — or a function returning one. When set, the\ndefault `type=\"button\"` is dropped so non-button elements stay valid."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional leading icon component (e.g. a lucide icon). Rendered\n`aria-hidden` and sized to the density icon token, so it tracks the density\nlevel without the caller passing a pixel size."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": ""
+    },
+    {
+      "name": "variant",
+      "type": "\"danger\" | \"ghost\" | \"secondary\" | \"primary\" | \"outline\" | \"danger-outline\"",
+      "required": false,
+      "defaultValue": "secondary",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"button\">",
+    "VariantProps<typeof buttonVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "variant": [
+      "primary",
+      "secondary",
+      "ghost",
+      "outline",
+      "danger",
+      "danger-outline"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "variant": "secondary",
+    "size": "md"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-accent-hover",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-space-6",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-ui"
+  ],
+  "summary": "The action control: six variants across three density-sized heights.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Button variant=\"primary\" size=\"sm\" icon={Play}>Run cue</Button>\n// Compose with a router link instead of a <button>:\n<Button render={<Link href=\"/patch\" />}>Patch</Button>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/button",
+  "mdUrl": "/docs/components/button.md",
+  "jsonUrl": "/r/components/button.json",
+  "whenToUse": [
+    "An action that happens on this page: submit, run, open a dialog.",
+    "Something that must look like a button but render as something else. Pass `render={<Link href=\"/patch\" />}`."
+  ],
+  "whenNotToUse": [
+    "Navigation that should behave like a link (middle-click, copy address). Use `Link`.",
+    "An icon-only control. Use `IconButton`, which requires the `aria-label` a bare icon needs.",
+    "A destructive action that should be confirmed where it stands. Use `TwoStepButton`."
+  ],
+  "commonMistakes": [
+    "Reaching for `variant=\"primary\"` on every button. One primary per view; `secondary` is the default for a reason.",
+    "Styling a Base UI trigger directly instead of passing `render={<Button />}`, which drops the variant classes into a tailwind-merge tie-break.",
+    "Fixing the height with `h-8 px-3` instead of `size`, which stops tracking density."
+  ],
+  "specimens": [
+    {
+      "title": "Button",
+      "group": "primitives",
+      "components": [
+        "Button"
+      ],
+      "code": "<Specimens>\n  {BUTTON_VARIANTS.map((variant) => (\n    <Specimen key={variant} label={variant}>\n      <Button variant={variant}>Go</Button>\n    </Specimen>\n  ))}\n  <Specimen label=\"disabled\">\n    <Button disabled>Go</Button>\n  </Specimen>\n  <Specimen label=\"with icon\">\n    <Button variant=\"primary\" icon={Play}>\n      Go\n    </Button>\n  </Specimen>\n  <Specimen label=\"loading\">\n    <Button disabled>\n      <Spinner size=\"sm\" /> Patching\n    </Button>\n  </Specimen>\n</Specimens>\n<Specimens>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={`size ${size}`}>\n      <Button size={size}>Go</Button>\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "Six variants, three sizes. The accent ink is theme-controlled, so `primary` is never a hardcoded white on blue.",
+      "interaction": "hover darkens the fill (or tints the ground, for the quiet variants); keyboard focus draws a 2px accent ring outside the border, so the border-colour convention and the ring never fight."
+    }
+  ]
+}