@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/sparkline.json

@@ -0,0 +1,76 @@
+{
+  "name": "Sparkline",
+  "slug": "sparkline",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A tiny unlabelled trace: \"is this climbing, or did it just reset?\".\n\nDeliberately answers nothing else — the numbers belong to the `Stat` or the\nrow above it. Two rules make it trustworthy at 72×14:\n\n1. **The scale is always 0–100.** A trace auto-scaled to its own range makes\n   a flat 3% look identical to a flat 95%, which is the exact misreading a\n   sparkline is supposed to prevent.\n2. **The stroke tone comes from the last value**, not from the shape, so the\n   colour agrees with the `Chip` or `Meter` sitting next to it.\n\nUnder two points there is no line to draw, so it renders an empty box of the\nsame size rather than nothing: a row of sparklines keeps its column even\nwhile some series are still filling up.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "values",
+      "type": "readonly number[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The series, as percentages. Clamped to 0–100; never rescaled."
+    },
+    {
+      "name": "width",
+      "type": "number",
+      "required": false,
+      "defaultValue": "72",
+      "description": "Box width in px at the 16px root, emitted as `rem`. Defaults to `72`."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "14",
+      "description": "Box height in px at the 16px root, emitted as `rem`. Defaults to `14`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "The accessible name. Defaults to a sentence naming the latest value, which\nis the only number a trace this small can honestly report."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.SVGProps<SVGSVGElement>, \"values\" | \"width\" | \"height\" | \"children\" | \"ref\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-danger",
+    "--cue-warn"
+  ],
+  "summary": "A tiny unlabelled trace: \"is this climbing, or did it just reset?\".",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Sparkline values={[12, 18, 30, 44, 61, 58, 72]} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/sparkline",
+  "mdUrl": "/docs/components/sparkline.md",
+  "jsonUrl": "/r/components/sparkline.json",
+  "specimens": [
+    {
+      "title": "Sparkline",
+      "group": "instruments",
+      "components": [
+        "Sparkline"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <Sparkline values={[...TREND]} label=\"Output trend\" />\n  </Specimen>\n  <Specimen label=\"wide\">\n    <Sparkline values={[...TREND]} width={220} height={32} label=\"Output trend, wide\" />\n  </Specimen>\n  <Specimen label=\"flat\">\n    <Sparkline values={[40, 40, 40, 40, 40]} label=\"Flat\" />\n  </Specimen>\n</Specimens>",
+      "note": "A trend at row height, drawn as one path with no axes and no tooltip. When it needs either, reach for UsageChart.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/spectrum-visualizer.json

@@ -0,0 +1,115 @@
+{
+  "name": "SpectrumVisualizer",
+  "slug": "spectrum-visualizer",
+  "group": "midi",
+  "importPath": "@cueplusplus/ui/midi",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The FFT, drawn: one bar per frequency band, or one line across all of them.\n\nPorted from ableton-sync's analyser, with the colours taken off the caller's\nhands. The original asked for a `color` per band and defaulted to `#00FF00`\nwhen it did not get one, which is how an audio tool ends up with two\ndifferent greens for the same band in two different panels. Here the bands\n*are* the ramp — the same `BANDS_7`/`BANDS_10`/`BANDS_16`/`BANDS_31` the\n`/charts` subpath publishes — so bass is the same red in the analyser, in the\nlegend and in any chart of the same data.\n\nThose ramps are deliberately theme-independent (see `charts/ramps.tsx`): a\nlistener who has learnt \"bass is red\" must not have to relearn it because the\nconsole switched to a different accent. Everything *around* the data — the\ngrid, the line trace — does read tokens, and is resolved at paint time so a\ntheme switch needs no subscription.\n\nSelection dims rather than hides. A band that vanished when deselected would\nchange the shape of the spectrum, and the shape is the reading.",
+  "props": [
+    {
+      "name": "levels",
+      "type": "readonly number[] | Float32Array<ArrayBufferLike>",
+      "required": true,
+      "defaultValue": null,
+      "description": "One level per band, `0`–`1`, in the ramp's own order.\n\nPositional rather than keyed by band id: an FFT hands back an array forty\ntimes a second, and building a lookup per frame to match it up is work for\nno information."
+    },
+    {
+      "name": "ramp",
+      "type": "readonly FrequencyBand[] | \"bands-7\" | \"bands-10\" | \"bands-16\" | \"bands-31\"",
+      "required": false,
+      "defaultValue": "bands-7",
+      "description": "The bands: a ramp from `/charts` by name, or a band list. Defaults to `\"bands-7\"`."
+    },
+    {
+      "name": "mode",
+      "type": "\"line\" | \"bars\"",
+      "required": false,
+      "defaultValue": "bars",
+      "description": "Bars or a line trace. Defaults to `\"bars\"`."
+    },
+    {
+      "name": "thresholds",
+      "type": "number | readonly number[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Trigger levels to rule, one per band or one for all of them."
+    },
+    {
+      "name": "selected",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Band ids to keep bright. Empty or absent means every band is bright."
+    },
+    {
+      "name": "sensitivity",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "Display gain applied to every level before drawing. Defaults to `1`."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "96",
+      "description": "Graph height in px at the 16px root, emitted as `rem`. Defaults to `96`."
+    },
+    {
+      "name": "labels",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "List the band names under the graph. Defaults to `true`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Spectrum",
+      "description": "What is being analysed. Defaults to `\"Spectrum\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-data-ground",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-text-micro"
+  ],
+  "summary": "The FFT, drawn: one bar per frequency band, or one line across all of them.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<SpectrumVisualizer levels={fft} ramp=\"bands-31\" thresholds={0.7} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/spectrum-visualizer",
+  "mdUrl": "/docs/components/spectrum-visualizer.md",
+  "jsonUrl": "/r/components/spectrum-visualizer.json",
+  "specimens": [
+    {
+      "title": "SpectrumVisualizer",
+      "group": "midi",
+      "components": [
+        "SpectrumVisualizer"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-5)\">\n  <SpectrumVisualizer levels={LEVELS} height={140} label=\"Seven-band analyser\" />\n  <SpectrumVisualizer\n    levels={LEVELS}\n    mode=\"line\"\n    thresholds={0.5}\n    height={120}\n    label=\"Seven-band analyser, line mode\"\n  />\n  <SpectrumVisualizer\n    levels={LEVELS_31}\n    ramp=\"bands-31\"\n    selected={[\"sub\", \"bass\"]}\n    labels={false}\n    height={120}\n    label=\"31-band analyser, bass selected\"\n  />\n</div>",
+      "note": "Bars or line, with band colours taken from the /charts ramps. Those are literals on purpose: a listener who has learnt `bass is red` must not relearn it because the console switched accent.",
+      "interaction": "a selection dims the bands outside it rather than hiding them; thresholds are dashed rules per band."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/spinner.json

@@ -0,0 +1,61 @@
+{
+  "name": "Spinner",
+  "slug": "spinner",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "An indeterminate progress ring, drawn in CSS only — no SVG, no animation\nlibrary, one element.\n\nThe ring is a conic gradient masked to a hairline annulus, inked with\n`currentColor`, so it inherits whatever text colour surrounds it (a spinner\ninside a `danger` button is red without being told). Under\n`prefers-reduced-motion` the rotation stops and the ring stays as a static\narc rather than disappearing.",
+  "props": [
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the density icon ladder to draw at. Defaults to `\"md\"`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Loading",
+      "description": "Accessible label announced while the spinner is on screen. Defaults to `\"Loading\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "An indeterminate progress ring, drawn in CSS only — no SVG, no animation library, one element.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Spinner size=\"sm\" />\n<Button disabled><Spinner /> Rendering…</Button>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/spinner",
+  "mdUrl": "/docs/components/spinner.md",
+  "jsonUrl": "/r/components/spinner.json",
+  "specimens": [
+    {
+      "title": "Spinner",
+      "group": "primitives",
+      "components": [
+        "Spinner"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"sm\">\n    <Spinner size=\"sm\" />\n  </Specimen>\n  <Specimen label=\"md\">\n    <Spinner />\n  </Specimen>\n  <Specimen label=\"labelled\">\n    <Spinner label=\"Reading show file\" />\n  </Specimen>\n</Specimens>",
+      "note": "Two sizes. Carries a visually hidden label so a screen reader is told the wait, not left with a spinning div.",
+      "interaction": "stills under prefers-reduced-motion."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/stack.json

@@ -0,0 +1,96 @@
+{
+  "name": "Stack",
+  "slug": "stack",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "One-dimensional layout: the flex row or column, with the gap tokenised.\n\nExists so that spacing between siblings is a density decision rather than a\nper-call-site guess. A `Stack gap={4}` is 8px at normal density and 6px at\nultra-compact without touching the markup, which is the whole point of the\ndensity system — and something `flex gap-2` written by hand quietly opts out\nof.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "direction",
+      "type": "\"row\" | \"column\"",
+      "required": false,
+      "defaultValue": "column",
+      "description": "`\"column\"` (default) or `\"row\"`."
+    },
+    {
+      "name": "gap",
+      "type": "0 | 4 | 8 | 1 | 2 | 3 | 5 | 6 | 7",
+      "required": false,
+      "defaultValue": "4",
+      "description": "Which rung of the density space ladder to spend between children. Defaults to `4`."
+    },
+    {
+      "name": "align",
+      "type": "\"center\" | \"end\" | \"baseline\" | \"start\" | \"stretch\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Cross-axis alignment. Omit to inherit the flex default (`stretch`)."
+    },
+    {
+      "name": "justify",
+      "type": "\"center\" | \"end\" | \"start\" | \"between\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Main-axis distribution. Omit to inherit the flex default (`start`)."
+    },
+    {
+      "name": "wrap",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Let a row wrap onto more lines."
+    },
+    {
+      "name": "inline",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Lay out as `inline-flex`, so the stack sits in a line of text."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-space-",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-space-6",
+    "--cue-space-7",
+    "--cue-space-8"
+  ],
+  "summary": "One-dimensional layout: the flex row or column, with the gap tokenised.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Stack gap={5}><Panel /><Panel /></Stack>\n<Stack direction=\"row\" gap={2} align=\"center\"><StatusDot tone=\"ok\" />Online</Stack>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/stack",
+  "mdUrl": "/docs/components/stack.md",
+  "jsonUrl": "/r/components/stack.json",
+  "specimens": [
+    {
+      "title": "Stack",
+      "group": "layout",
+      "components": [
+        "Stack"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"row, gap 3\">\n    <Stack direction=\"row\" gap={3}>\n      <Chip>one</Chip>\n      <Chip>two</Chip>\n      <Chip>three</Chip>\n    </Stack>\n  </Specimen>\n  <Specimen label=\"column, gap 5\">\n    <Stack gap={5}>\n      <Chip>one</Chip>\n      <Chip>two</Chip>\n    </Stack>\n  </Specimen>\n  <Specimen label=\"row, between\">\n    <Stack direction=\"row\" justify=\"between\" className=\"w-[14rem]\">\n      <Chip>left</Chip>\n      <Chip>right</Chip>\n    </Stack>\n  </Specimen>\n</Specimens>",
+      "note": "Flex with the gap taken from a rung of the density ladder, never a length. That is what makes a layout tighten with the rest of the console.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/stat.json

@@ -0,0 +1,87 @@
+{
+  "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."
+    },
+    {
+      "name": "value",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "The reading itself — the one thing the eye should land on."
+    },
+    {
+      "name": "detail",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Optional second line: a delta, a window, a unit."
+    },
+    {
+      "name": "tone",
+      "type": "\"accent\" | \"danger\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "neutral",
+      "description": "Tints the value only. Defaults to `\"neutral\"`."
+    }
+  ],
+  "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,58 @@
+{
+  "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`.\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\"`.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-busy",
+    "--cue-chrome-statusbar",
+    "--cue-danger",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-pad-row-x",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-surface-1",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "The quiet strip along the bottom of a window.",
+  "examples": [
+    {
+      "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>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/status-bar",
+  "mdUrl": "/docs/components/status-bar.md",
+  "jsonUrl": "/r/components/status-bar.json",
+  "specimens": [
+    {
+      "title": "StatusBar",
+      "group": "chrome",
+      "components": [
+        "StatusBar"
+      ],
+      "code": "<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>",
+      "note": "The bottom strip: tone-inked items, and a `push` item that takes the remaining space.",
+      "interaction": "none by default; items are plain readouts."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/status-dot.json

@@ -0,0 +1,78 @@
+{
+  "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": "\"idle\" | \"danger\" | \"busy\" | \"ok\" | \"warn\"",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which state to paint. `idle` renders a hollow ring."
+    },
+    {
+      "name": "pulse",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Pulse the dot to signal live activity. Automatically stilled under\n`prefers-reduced-motion`."
+    },
+    {
+      "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`."
+    },
+    {
+      "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."
+    }
+  ],
+  "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,89 @@
+{
+  "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."
+    },
+    {
+      "name": "current",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The `id` of the step in progress. An unknown id leaves every step upcoming."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "separator",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "·",
+      "description": "What sits between steps. Defaults to `\"·\"`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Progress",
+      "description": "The nav's accessible name. Defaults to `\"Progress\"`."
+    }
+  ],
+  "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
+}