@cueplusplus/ui 0.13.0

package/manifest/components/stacks-matrix-icon.json

@@ -0,0 +1,46 @@
+{
+  "name": "StacksMatrixIcon",
+  "slug": "stacks-matrix-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Every stack at once, one column each: who has what, read across.\n\nA table rather than more plates. The head rule and the name column are what\nmake it a matrix instead of a grid — the question it answers is \"which of\nthese does that person not have\", and that is a question with two axes.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "Every stack at once, one column each: who has what, read across.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/stacks-matrix-icon",
+  "mdUrl": "/docs/components/stacks-matrix-icon.md",
+  "jsonUrl": "/r/components/stacks-matrix-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
+      "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/stat.json

@@ -0,0 +1,111 @@
+{
+  "name": "Stat",
+  "slug": "stat",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "One number, named: the console's KPI tile.\n\nReads label-first (micro, uppercase, tracked) so a row of tiles scans as a\nlist of captions with the readings underneath, and the value is set in\n`tabular-nums` mono so a changing number does not shuffle the layout under\nthe reader.\n\nOnly the value takes the tone. Tinting the caption too would make a red tile\nwhere the intent is a red *number* — the label is not the alarm.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "What is being measured. Rendered as a micro uppercase caption.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "value",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The reading itself — the one thing the eye should land on.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "detail",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional second line: a delta, a window, a unit.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "tone",
+      "type": "\"danger\" | \"accent\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "neutral",
+      "description": "Tints the value only. Defaults to `\"neutral\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "danger",
+          "accent",
+          "busy",
+          "neutral",
+          "ok",
+          "warn",
+          "info"
+        ]
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-title",
+    "--cue-warn"
+  ],
+  "summary": "One number, named: the console's KPI tile.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Stat label=\"Universes\" value=\"512\" />\n<Stat label=\"Dropped frames\" value=\"12\" detail=\"last hour\" tone=\"danger\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/stat",
+  "mdUrl": "/docs/components/stat.md",
+  "jsonUrl": "/r/components/stat.json",
+  "specimens": [
+    {
+      "title": "Stat",
+      "group": "instruments",
+      "components": [
+        "Stat"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-4) sm:grid-cols-2 lg:grid-cols-4\">\n  <Stat label=\"Universes\" value=\"4\" detail=\"of 8 patched\" />\n  <Stat label=\"Latency\" value=\"7 ms\" detail=\"art-net\" tone=\"ok\" />\n  <Stat label=\"Dropped\" value=\"0.4%\" detail=\"last hour\" tone=\"warn\" />\n  <Stat label=\"Faults\" value=\"2\" detail=\"since 18:00\" tone=\"danger\" />\n</div>",
+      "note": "A label, a figure and a detail line. Figures are mono `tabular-nums`, so a changing digit never shifts the column.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/status-bar.json

@@ -0,0 +1,233 @@
+{
+  "name": "StatusBar",
+  "slug": "status-bar",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The quiet strip along the bottom of a window.\n\nThe smallest type in the system in the subtlest ink: a status bar is read\nwhen you go looking for it and ignored otherwise, so it must never compete\nwith the work above it. Height comes from `--cue-chrome-statusbar`, and the\nbar clips rather than wrapping — one rung of the frame, always, whatever it\nis asked to hold.\n\nItems come in two kinds and the difference is deliberate. A plain\n`StatusBar.Item` is a **reading**: a `<div>`, inert by construction, with no\nhover, no focus and nothing to click — which is what most of a status bar is.\n`interactive` (or a `render`) makes one a **control**, and only then does it\ngrow the button chassis, the full-height hover fill and the inset focus ring.\n`StatusBar.Group` fuses adjacent items into one segmented control.\n\nNot a live region — a status bar changes constantly (frame counters, DMX\noutput), and announcing every change would make the app unusable with a\nscreen reader. Put anything that genuinely must be announced in a `Toast`.\n\nStatic markup — no `\"use client\"`. A bar of readings renders on the server\nand ships no JavaScript at all; the interactive item is the one part that\ncrosses the boundary, and it crosses it alone (`./_status-bar-item.tsx`).",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [
+    "Item",
+    "Group"
+  ],
+  "parts": [
+    {
+      "name": "Item",
+      "usage": "StatusBar.Item",
+      "description": "One reading in the bar: a mode, a count, a connection state — or, given\n`interactive`, one control in it.",
+      "props": [
+        {
+          "name": "tone",
+          "type": "\"accent\" | \"danger\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
+          "required": false,
+          "defaultValue": "neutral",
+          "description": "Ink for this item. Defaults to the bar's own subtle grey.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "accent",
+              "danger",
+              "busy",
+              "neutral",
+              "ok",
+              "warn",
+              "info"
+            ]
+          }
+        },
+        {
+          "name": "push",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Start the trailing cluster here: pushes this item and everything after it\nto the far edge. Cheaper and more robust than a spacer element, which a\ncaller has to remember to keep in the right place.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "icon",
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Optional leading icon (e.g. a lucide icon), drawn `aria-hidden`.",
+          "control": {
+            "kind": "opaque",
+            "fixture": "icon.play"
+          }
+        },
+        {
+          "name": "interactive",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Make the item a real control: a `<button type=\"button\">` with hover, press\nand keyboard-focus feedback. Defaults to `false`.\n\nA native button, not a `<div>` with an `onClick` — keyboard order is DOM\norder, `Enter` and `Space` work because the platform makes them work, and\nassistive technology is told what the thing is by the element rather than\nby a role attribute that has to be kept honest by hand.\n\n**An icon-only interactive item needs an `aria-label`.** There is no text\nfor a screen reader to read and the icon is drawn `aria-hidden`, so without\none the control announces as \"button\" and nothing else.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "prominence",
+          "type": "\"quiet\" | \"filled\"",
+          "required": false,
+          "defaultValue": "quiet",
+          "description": "How loudly the item states itself. Defaults to `\"quiet\"`.\n\n`quiet` is a reading: tone ink on the bar's own ground. `filled` is a chip\n— a full-height tone wash behind tone ink — for the small set of states\nthat earn a colour of their own: a warning, an error, the remote you are\nattached to. It is loud deliberately, and a bar of five filled items is a\nbar nobody reads.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "quiet",
+              "filled"
+            ]
+          }
+        },
+        {
+          "name": "render",
+          "type": "RenderProp<Record<string, unknown>>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Replace the rendered element (Base UI render prop) — `render={<a href=\"…\" />}`\nfor a status item that navigates.\n\nImplies {@link StatusBarItemProps.interactive}: whatever is rendered gets\nthe control chassis, because an element a reader can click has to look like\none whether it is a button or a link.",
+          "control": {
+            "kind": "opaque"
+          }
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Grey the control out, take it out of the pointer's reach and announce it as\ndisabled. Defaults to `false`. Ignored by a static item, which is a reading\nand not a control.\n\nHonoured whatever {@link StatusBarItemProps.render} renders, but by two\nroutes: the `disabled` attribute where it means something — the default\n`<button>`, a form control, a component that takes a `disabled` prop of its\nown — and `aria-disabled` plus `data-disabled` everywhere, which is all an\nanchor gets. There is no such thing as a disabled link; a link that should\nnot be followed should not be a link, and this states the intent rather\nthan pretending to enforce it.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    },
+    {
+      "name": "Group",
+      "usage": "StatusBar.Group",
+      "description": "Items that belong to each other, one pixel apart.\n\nThe bar spaces its readings at `--cue-space-4` because they are unrelated\nfacts. A branch name and its ahead/behind count are not unrelated facts; they\nare one control that happens to have two halves, and the gap between them is\nwhat says so. This is VS Code's `compact` mechanic — the seam collapses, and\nhovering either half grounds both while the half under the cursor goes one\nrung further — expressed as a wrapper rather than as an id-reference between\ntwo items, because a design system's items do not have ids to point at.\n\nA `role=\"group\"` rather than nothing: the members are announced as a set, and\nthe DOM order they are announced in is the order they are read in. Give it an\n`aria-label` when the members only make sense together.",
+      "props": [
+        {
+          "name": "push",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Start the trailing cluster at this group: pushes it and everything after it\nto the far edge, exactly as `push` does on a single item.",
+          "control": {
+            "kind": "boolean"
+          }
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "What the cluster is called. Optional, and worth giving whenever the members\nonly make sense together — \"Repository\", \"Connection\" — because a `group`\nwith no name is a landmark a screen reader reads straight past.",
+          "control": {
+            "kind": "string"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-busy",
+    "--cue-chrome-statusbar",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-pad-row-x",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-surface-3",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "The quiet strip along the bottom of a window: readings by default, controls where the reading is worth clicking.",
+  "examples": [
+    {
+      "title": "Readings and controls",
+      "code": "<StatusBar>\n  <StatusBar.Item icon={Plug} tone=\"ok\">Art-Net connected</StatusBar.Item>\n  <StatusBar.Item push>512 channels</StatusBar.Item>\n</StatusBar>",
+      "language": "tsx"
+    },
+    {
+      "title": "Readings and controls",
+      "code": "<StatusBar.Item interactive icon={GitBranch} onClick={openBranchPicker}>act-2</StatusBar.Item>\n<StatusBar.Item render={<a href=\"/runs/42\" />}>run 42</StatusBar.Item>",
+      "language": "tsx"
+    },
+    {
+      "title": "`push`, and the two clusters",
+      "code": "<StatusBar>\n  <StatusBar.Item>universe 1</StatusBar.Item>\n  <StatusBar.Item tone=\"ok\">44 Hz</StatusBar.Item>\n  <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n  <StatusBar.Item tone=\"info\">art-net</StatusBar.Item>\n</StatusBar>",
+      "language": "tsx"
+    },
+    {
+      "title": "Groups: items that belong to each other",
+      "code": "<StatusBar.Group aria-label=\"Show file\">\n  <StatusBar.Item interactive icon={GitBranch}>act-2</StatusBar.Item>\n  <StatusBar.Item interactive icon={ArrowUp}>2</StatusBar.Item>\n</StatusBar.Group>",
+      "language": "tsx"
+    },
+    {
+      "title": "`prominence`, and how rarely to reach for it",
+      "code": "<StatusBar.Item prominence=\"filled\" tone=\"danger\" icon={TriangleAlert}>3 faults</StatusBar.Item>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<StatusBar>\n  <StatusBar.Item icon={Plug} tone=\"ok\">Art-Net connected</StatusBar.Item>\n  <StatusBar.Item push>512 channels</StatusBar.Item>\n</StatusBar>\n// The VS Code shape: a clickable cluster left, a loud state right.\n<StatusBar>\n  <StatusBar.Group aria-label=\"Repository\">\n    <StatusBar.Item interactive icon={GitBranch}>main</StatusBar.Item>\n    <StatusBar.Item interactive icon={ArrowUp}>2</StatusBar.Item>\n  </StatusBar.Group>\n  <StatusBar.Item push interactive prominence=\"filled\" tone=\"danger\">3 faults</StatusBar.Item>\n</StatusBar>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/status-bar",
+  "mdUrl": "/docs/components/status-bar.md",
+  "jsonUrl": "/r/components/status-bar.json",
+  "whenToUse": [
+    "Ambient state a reader goes looking for rather than is interrupted by: a connection, a frame rate, a cursor position, a branch name.",
+    "A state that is also a destination. `interactive` makes an item a real button, `render={<a href=\"…\" />}` makes it a link, and `StatusBar.Group` fuses two of them into one control."
+  ],
+  "whenNotToUse": [
+    "Anything that must be noticed. A status bar is deliberately the quietest thing on screen and nothing in it is announced — urgent messages are `Toast`'s job.",
+    "A row of actions. That is `Toolbar`, which is sized for controls and has the keyboard model to match.",
+    "The end of a document — an address, fine print, a sitemap. That is `Footer`, which scrolls away with the content; the bar is part of the frame and never leaves the screen."
+  ],
+  "commonMistakes": [
+    "Making every item interactive. Most of a status bar is a reading, and a bar where everything lights up under the pointer is a bar where nothing means anything.",
+    "Filling more than one or two items. `prominence=\"filled\"` is the loudest thing the bar can do; a bar of five filled chips is a bar nobody reads.",
+    "An icon-only interactive item with no `aria-label`. The icon is drawn `aria-hidden`, so the control announces as \"button\" and nothing else.",
+    "Wrapping related items in a plain `<div>` to close the gap. `StatusBar.Group` closes the seam *and* neutralises the interactive item's negative margin, which a bare div does not.",
+    "Reaching for `aria-live` to make a reading announce itself. The bar changes constantly, and a live region here makes the app unusable with a screen reader.",
+    "Fixing the height with `h-6` instead of letting `--cue-chrome-statusbar` set it, which stops tracking density."
+  ],
+  "specimens": [
+    {
+      "title": "StatusBar",
+      "group": "chrome",
+      "components": [
+        "StatusBar"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n    <StatusBar>\n      <StatusBar.Item>universe 1</StatusBar.Item>\n      <StatusBar.Item tone=\"ok\">44 Hz</StatusBar.Item>\n      <StatusBar.Item tone=\"warn\">2 conflicts</StatusBar.Item>\n      <StatusBar.Item push>10.0.0.42</StatusBar.Item>\n      <StatusBar.Item tone=\"info\">art-net</StatusBar.Item>\n    </StatusBar>\n  </div>\n\n  <div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n    <StatusBar>\n      <StatusBar.Group aria-label=\"Show file\">\n        <StatusBar.Item interactive icon={GitBranch}>\n          act-2\n        </StatusBar.Item>\n        <StatusBar.Item interactive icon={ArrowUp}>\n          2\n        </StatusBar.Item>\n      </StatusBar.Group>\n      <StatusBar.Item interactive tone=\"ok\">\n        44 Hz\n      </StatusBar.Item>\n      <StatusBar.Item interactive icon={Radio} aria-label=\"Art-Net output\" />\n      <StatusBar.Item push interactive prominence=\"filled\" tone=\"warn\" icon={TriangleAlert}>\n        2 conflicts\n      </StatusBar.Item>\n    </StatusBar>\n  </div>\n</div>",
+      "note": "The bottom strip: tone-inked items, and a `push` item that takes the remaining space. Drawn twice — the readings-only bar it has always been, and the VS Code shape beneath it, where some of the items are controls: a compact Group whose two halves read as one, an icon-only control that carries its name in aria-label, and a filled item for the one state that has earned a colour.",
+      "interaction": "the plain items are inert by construction — no hover, no focus, nothing to click. The controls take a full-height fill on hover and a darker one while pressed, Tab reaches them in DOM order and Enter fires them, and the focus ring is drawn inside the item so it never paints across the bar. Hovering either half of the Group grounds both, and the half under the pointer goes one rung further."
+    }
+  ]
+}

package/manifest/components/status-dot.json

@@ -0,0 +1,97 @@
+{
+  "name": "StatusDot",
+  "slug": "status-dot",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A 6px state dot — the densest possible status indicator.\n\nColour alone never carries meaning here: the dot is `aria-hidden` and the\ncomponent always emits an `sr-only` label inside a `role=\"status\"` wrapper,\nso the state is announced as well as shown (WCAG 1.4.1).\n\nThe wrapper is `relative` for that label's sake and no other reason.\n`.sr-only` is `position: absolute`; without a positioned ancestor its\ncontaining block is the initial one, so its scrollable overflow lands on\n`<html>` rather than on whatever scroller it is nested in. One dot is\nharmless and a table of two thousand rows is a document several thousand\npixels taller than anything visible on it.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "tone",
+      "type": "\"danger\" | \"idle\" | \"busy\" | \"ok\" | \"warn\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which state to paint. `idle` renders a hollow ring.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "danger",
+          "idle",
+          "busy",
+          "ok",
+          "warn"
+        ]
+      }
+    },
+    {
+      "name": "pulse",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Pulse the dot to signal live activity. Automatically stilled under\n`prefers-reduced-motion`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "size",
+      "type": "number",
+      "required": false,
+      "defaultValue": "6",
+      "description": "Diameter in px at the default 16px root font size. Emitted as `rem`, so it\nscales with browser zoom and the user's font size. Defaults to `6`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Screen-reader text. Defaults to the tone name, which is usually the honest\nanswer; pass something specific when the surrounding row does not say it.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-warn"
+  ],
+  "summary": "A 6px state dot — the densest possible status indicator.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<StatusDot tone=\"ok\" />\n<StatusDot tone=\"busy\" pulse label=\"Rendering preview\" size={8} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/status-dot",
+  "mdUrl": "/docs/components/status-dot.md",
+  "jsonUrl": "/r/components/status-dot.json",
+  "specimens": [
+    {
+      "title": "StatusDot",
+      "group": "primitives",
+      "components": [
+        "StatusDot"
+      ],
+      "code": "<Specimens>\n  {STATUS_TONES.map((tone) => (\n    <Specimen key={tone} label={tone}>\n      <StatusDot tone={tone} label={tone} />\n    </Specimen>\n  ))}\n  <Specimen label=\"pulse\">\n    <StatusDot tone=\"busy\" pulse label=\"Cueing\" />\n  </Specimen>\n  <Specimen label=\"size 10\">\n    <StatusDot tone=\"ok\" size={10} label=\"Online\" />\n  </Specimen>\n</Specimens>",
+      "note": "Five states, and the pulse that means work is in flight. The label is the accessible name, not decoration.",
+      "interaction": "none. A dot is a readout."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/stepper.json

@@ -0,0 +1,107 @@
+{
+  "name": "Stepper",
+  "slug": "stepper",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The step trail: `1 target · 2 preview · 3 apply`.\n\nDeliberately a line of mono text rather than the usual row of numbered discs\njoined by rules. A stepper drawn as circles-and-lines is 60px tall and says\nexactly as much as one line of 9px type — and in a console that vertical\nspace belongs to the thing being configured, not to the wizard chrome around\nit. Only the numbers carry the accent, so the trail reads as one sentence\nwith the position marked, which is what a progress indicator is for.\n\nForward steps are never buttons: a step you have not reached is not a place\nyou can go, and offering it as a control is a promise the flow cannot keep.",
+  "props": [
+    {
+      "name": "steps",
+      "type": "readonly StepperStep[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The steps, in order.",
+      "control": {
+        "kind": "array",
+        "fixture": "layout.patch-steps"
+      }
+    },
+    {
+      "name": "current",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The `id` of the step in progress. An unknown id leaves every step upcoming.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "onStepChange",
+      "type": "((id: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the `id` of a step the user asked to go back to. Passing it\nturns the finished steps into buttons; leaving it off keeps the trail\nstatic, which is the honest rendering when the earlier steps cannot be\nrevisited.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "separator",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "·",
+      "description": "What sits between steps. Defaults to `\"·\"`.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Progress",
+      "description": "The nav's accessible name. Defaults to `\"Progress\"`.",
+      "control": {
+        "kind": "string"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"nav\">, \"children\" | \"onChange\">"
+  ],
+  "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-space-3",
+    "--cue-text-label"
+  ],
+  "summary": "The step trail: `1 target · 2 preview · 3 apply`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Stepper steps={[{ id: \"target\", label: \"target\" }, { id: \"preview\", label: \"preview\" }]} current=\"preview\" />\n<Stepper steps={steps} current={step} onStepChange={setStep} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/stepper",
+  "mdUrl": "/docs/components/stepper.md",
+  "jsonUrl": "/r/components/stepper.json",
+  "specimens": [
+    {
+      "title": "Stepper",
+      "group": "layout",
+      "components": [
+        "Stepper"
+      ],
+      "code": "<Stepper steps={STEPS} current={step} onStepChange={setStep} />",
+      "note": "The step trail: `1 target · 2 preview · 3 apply`, with reached steps tinted rather than filled.",
+      "interaction": "a reached step is a button; an upcoming one is not."
+    }
+  ],
+  "todo": true
+}