@cueplusplus/ui 0.13.0

package/manifest/components/channel-beta-icon.json

@@ -0,0 +1,46 @@
+{
+  "name": "ChannelBetaIcon",
+  "slug": "channel-beta-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The beta channel: the same things, one merge earlier.\n\nThe released ring at half fill. Half rather than empty because a beta is not\nan absence of a release — it is a release that has not finished happening,\nand an empty ring would have read as \"nothing here yet\".",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "The beta channel: the same things, one merge earlier.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/channel-beta-icon",
+  "mdUrl": "/docs/components/channel-beta-icon.md",
+  "jsonUrl": "/r/components/channel-beta-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/channel-matrix.json

@@ -0,0 +1,239 @@
+{
+  "name": "ChannelMatrix",
+  "slug": "channel-matrix",
+  "group": "dmx",
+  "importPath": "@cueplusplus/ui/dmx",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The channel-by-channel view: 512 addressed cells, repainted imperatively.\n\nPorted from dmxhub's bridge debugger. The interesting part is not the grid —\nit is what happens between frames. Five hundred and twelve React elements\nre-rendered forty times a second is a locked tab, so this component renders\nthe grid *once* and then never re-renders it: an animation loop reads the\nbuffer, diffs each slot against a previous-value cache, and writes only the\ncells whose level actually moved. A typical lighting state changes a handful\nof channels per frame, so a typical frame touches a handful of nodes.\n\nThat is also why `data` is read through a ref rather than through props: a\ndecoder that writes into one buffer forever is the cheapest thing it can do,\nand this component is built to be pointed at exactly that.\n\nTwo things it keeps from the port, and one it fixes:\n\n- **Two ramps.** Grey answers \"how bright\", the status ramp answers \"which\n  ones are hot\". Both are lookup tables, built once per theme (see `_ramp.ts`).\n- **Overview and drill-in.** Thirty-two universes as thumbnails, drawn through\n  one 32×16 offscreen canvas and scaled up unsmoothed; clicking one opens it.\n- **It stops.** The original left `requestAnimationFrame` running forever. Here\n  the loop is off under `prefers-reduced-motion` and off when `live` is\n  `false`; a new `data` reference still repaints, so a paused stream is never\n  a stale grid.",
+  "props": [
+    {
+      "name": "data",
+      "type": "Uint8Array<ArrayBufferLike>",
+      "required": false,
+      "defaultValue": null,
+      "description": "The frame buffer: `universes × 512` bytes, universe 0 first.\n\nRead on every animation frame rather than on every render, so mutating it\nin place is the intended usage — that is what makes a 40 Hz stream cost one\n`requestAnimationFrame` instead of one React render per packet. The one\nthing that does not follow an in-place write is the accessible summary,\nwhich is computed in render and so refreshes when a new reference arrives.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "universes",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "How many universes the buffer holds. Defaults to `1`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "universe",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Selected universe, 0-based. Use with `onUniverseChange` for a controlled widget.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "defaultUniverse",
+      "type": "number",
+      "required": false,
+      "defaultValue": "0",
+      "description": "Initially selected universe for an uncontrolled widget. Defaults to `0`.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "onUniverseChange",
+      "type": "((universe: number) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the universe a drill-in selected.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "mode",
+      "type": "\"detail\" | \"overview\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Current view. Use with `onModeChange` for a controlled widget.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "detail",
+          "overview"
+        ]
+      }
+    },
+    {
+      "name": "defaultMode",
+      "type": "\"detail\" | \"overview\"",
+      "required": false,
+      "defaultValue": "detail",
+      "description": "Initial view for an uncontrolled widget. Defaults to `\"detail\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "detail",
+          "overview"
+        ]
+      }
+    },
+    {
+      "name": "onModeChange",
+      "type": "((mode: ChannelMatrixMode) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the view changes, including on a drill-in.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "ramp",
+      "type": "\"value\" | \"mono\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Cell colouring. Use with `onRampChange` for a controlled widget.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "value",
+          "mono"
+        ]
+      }
+    },
+    {
+      "name": "defaultRamp",
+      "type": "\"value\" | \"mono\"",
+      "required": false,
+      "defaultValue": "mono",
+      "description": "Initial cell colouring for an uncontrolled widget. Defaults to `\"mono\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "value",
+          "mono"
+        ]
+      }
+    },
+    {
+      "name": "onRampChange",
+      "type": "((ramp: \"value\" | \"mono\") => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the colouring changes.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "live",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Whether frames are still arriving. Defaults to `true`; `false` stops the repaint loop.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "controls",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Show the view and colouring buttons. Defaults to `true`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What this output is. Defaults to `\"DMX output\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "formatUniverse",
+      "type": "((universe: number) => string)",
+      "required": false,
+      "defaultValue": "(value) => `Universe ${value}`",
+      "description": "Name a universe for its button and card. Defaults to `\"Universe 3\"` / `U03`.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-data-ground",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-leading-ui",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-micro",
+    "--cue-text-ui"
+  ],
+  "summary": "The channel-by-channel view: 512 addressed cells, repainted imperatively.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ChannelMatrix label=\"Output\" data={buffer} universes={32} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/channel-matrix",
+  "mdUrl": "/docs/components/channel-matrix.md",
+  "jsonUrl": "/r/components/channel-matrix.json",
+  "specimens": [
+    {
+      "title": "ChannelMatrix",
+      "group": "dmx",
+      "components": [
+        "ChannelMatrix"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-5)\">\n  <ChannelMatrix data={data} universes={4} label=\"Universe 1 channels\" />\n  <ChannelMatrix\n    data={data}\n    universes={4}\n    defaultMode=\"overview\"\n    defaultRamp=\"value\"\n    label=\"All universes, value ramp\"\n  />\n  <ChannelMatrix data={data} controls={false} label=\"Universe 1 channels, no controls\" />\n</div>",
+      "note": "A 32×16 grid repainted inside an animation frame against a previous-value cache, with the colour ramps precomputed to a Uint8Array. Two ramps, and an overview mode that drills into one universe.",
+      "interaction": "the controls switch universe, mode and ramp; the grid itself reports its occupancy in words."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/channel-released-icon.json

@@ -0,0 +1,46 @@
+{
+  "name": "ChannelReleasedIcon",
+  "slug": "channel-released-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The released channel: what a colleague gets when they install without asking\nfor anything in particular.\n\nA ring filled solid. Its pair, {@link ChannelBetaIcon}, is the same ring\nfilled halfway — the two are one mark told twice, so a reader never has to\nlearn which of two unrelated pictures means \"finished\".",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "The released channel: what a colleague gets when they install without asking for anything in particular.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/channel-released-icon",
+  "mdUrl": "/docs/components/channel-released-icon.md",
+  "jsonUrl": "/r/components/channel-released-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/chart-container.json

@@ -0,0 +1,127 @@
+{
+  "name": "ChartContainer",
+  "slug": "chart-container",
+  "group": "charts",
+  "importPath": "@cueplusplus/ui/charts",
+  "peerDependencies": [
+    "recharts"
+  ],
+  "clientOnly": true,
+  "description": "The box every chart in this system sits in.\n\nIt does three things, and deliberately not a fourth:\n\n1. **It publishes the palette as custom properties.** `--chart-1`…`--chart-N`\n   carry `var(--cue-accent)`, `var(--cue-info)` and the rest *by reference*,\n   so a series written `<Line stroke={chartToneVar(0)} />` re-hues on a theme\n   switch with no re-render, no context and no effect. Resolving the palette in\n   JavaScript would have made the chart a subscriber to the theme; this way it\n   is simply painted in it.\n2. **It re-inks recharts' chrome.** {@link chartChromeClasses} restyles the\n   grid, axes and ticks from tokens through the SVG's own class names, so\n   every axis is themed whether or not somebody remembered to configure it.\n3. **It measures.** `ResponsiveContainer` is the only reliable way to give a\n   recharts chart a pixel size, and it needs a box with a real height — which\n   is what `height` (or `aspect`) sets, in `rem` so the plot scales with the\n   root font size like everything else.\n\nWhat it does not do is wrap or re-export recharts' chart components. A chart is\na composition, and hiding `LineChart`/`XAxis`/`Tooltip` behind a props object\nwould mean re-implementing a charting library's API surface one prop at a time.",
+  "props": [
+    {
+      "name": "children",
+      "type": "ReactElement<unknown, string | JSXElementConstructor<any>>",
+      "required": true,
+      "defaultValue": null,
+      "description": "The chart. Exactly one element — recharts' container takes a single child.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "200",
+      "description": "Plot height in px at the 16px root. Defaults to `200`. Ignored when `aspect` is set.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "aspect",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Width-to-height ratio, letting the plot size itself from its column instead.",
+      "control": {
+        "kind": "number"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the chart shows. Given, the box becomes a named `figure`; a shape is\nnot self-describing, so name the series.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "tones",
+      "type": "readonly string[]",
+      "required": false,
+      "defaultValue": "[\n  ...CHART_TONE_TOKENS.map(tokenRef),\n  ...CHART_EXTENDED_TONES,\n]",
+      "description": "The series palette, published as `--chart-1`…`--chart-N`. Defaults to\n{@link CHART_TONES}.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "debounce",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Throttle for the resize observer, in ms. Defaults to none.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "The box every chart in this system sits in.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ChartContainer label=\"Requests per minute\" height={220}>\n  <LineChart data={series}>\n    <CartesianGrid vertical={false} />\n    <XAxis dataKey=\"t\" />\n    <Tooltip cursor={chartTooltipCursor} content={<ChartTooltipContent />} />\n    <Line dataKey=\"requests\" stroke={chartToneVar(0)} dot={false} />\n  </LineChart>\n</ChartContainer>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chart-container",
+  "mdUrl": "/docs/components/chart-container.md",
+  "jsonUrl": "/r/components/chart-container.json",
+  "specimens": [
+    {
+      "title": "ChartContainer — line",
+      "group": "charts",
+      "components": [
+        "ChartContainer"
+      ],
+      "code": "<Panel className=\"w-full p-(--cue-space-4)\">\n  <PanelHeader title=\"Output level\" />\n  <ChartContainer height={220} label=\"Output level over the last six hours\">\n    <LineChart data={SERIES}>\n      <CartesianGrid />\n      <XAxis dataKey=\"hour\" />\n      <YAxis domain={[0, 100]} />\n      <Tooltip content={<ChartTooltipContent />} />\n      <Legend />\n      <Line dataKey=\"output\" stroke={chartToneVar(0)} dot={false} strokeWidth={2} />\n      <Line dataKey=\"dropped\" stroke={chartToneVar(4)} dot={false} strokeWidth={2} />\n    </LineChart>\n  </ChartContainer>\n</Panel>",
+      "note": "The measured box. It publishes the palette as `--chart-N` custom properties and re-inks recharts' own SVG chrome from tokens: grid at 45% of the border colour, axis text in mono at the label size.",
+      "interaction": "the tooltip follows the cursor and uses the overlay surface conventions, so a chart tooltip and a popover agree on what floats."
+    },
+    {
+      "title": "ChartContainer — bar",
+      "group": "charts",
+      "components": [
+        "ChartContainer"
+      ],
+      "code": "<Panel className=\"w-full p-(--cue-space-4)\">\n  <PanelHeader title=\"Channels per universe\" />\n  <ChartContainer height={200} label=\"Channels used per universe\">\n    <BarChart data={UNIVERSES}>\n      <CartesianGrid />\n      <XAxis dataKey=\"universe\" />\n      <YAxis />\n      <Tooltip content={<ChartTooltipContent />} />\n      <Bar dataKey=\"channels\" fill={chartToneVar(1)} />\n    </BarChart>\n  </ChartContainer>\n</Panel>",
+      "note": "The same container with a different mark. Nothing about the theme layer is chart-type specific.",
+      "interaction": "same tooltip and cursor treatment."
+    },
+    {
+      "title": "ChartContainer — area",
+      "group": "charts",
+      "components": [
+        "ChartContainer"
+      ],
+      "code": "<Panel className=\"w-full p-(--cue-space-4)\">\n  <PanelHeader title=\"Dropped frames\" />\n  <ChartContainer\n    height={180}\n    label=\"Dropped frames over the last six hours\"\n    tones={[\"var(--cue-warn)\", \"var(--cue-danger)\"]}\n  >\n    <AreaChart data={SERIES}>\n      <CartesianGrid />\n      <XAxis dataKey=\"hour\" />\n      <YAxis />\n      <Tooltip content={<ChartTooltipContent hideIndicator />} />\n      <Area dataKey=\"dropped\" stroke={chartToneVar(0)} fill={chartToneVar(0)} fillOpacity={0.2} />\n    </AreaChart>\n  </ChartContainer>\n</Panel>",
+      "note": "An area with an explicit tone list, which overrides the default palette for this chart only.",
+      "interaction": "none beyond the tooltip."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chart-ramp.json

@@ -0,0 +1,82 @@
+{
+  "name": "ChartRamp",
+  "slug": "chart-ramp",
+  "group": "charts",
+  "importPath": "@cueplusplus/ui/charts",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A ramp drawn as a strip: equal cells, no gaps, in order.\n\nEqual cells rather than a CSS gradient, because a ramp *is* discrete — a\ngradient would show steps the data cannot address, and would quietly disagree\nwith the same ramp used to fill bars. No seams either, for the same reason the\ncells are equal: a seam reads as a category boundary, and a sequential scale\nhas none.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "colors",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The ramp, in order. Any CSS colours.",
+      "control": {
+        "kind": "array",
+        "fixture": "agent.transcript"
+      }
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the ramp encodes. Required: it is the strip's accessible name.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "8",
+      "description": "Strip height in px at the 16px root, emitted as `rem`. Defaults to `8`.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "A ramp drawn as a strip: equal cells, no gaps, in order.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ChartRamp label=\"Density\" colors={accentRamp()} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chart-ramp",
+  "mdUrl": "/docs/components/chart-ramp.md",
+  "jsonUrl": "/r/components/chart-ramp.json",
+  "specimens": [
+    {
+      "title": "RAMPS / accentRamp()",
+      "group": "charts",
+      "components": [
+        "ChartRamp"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  {RAMP_NAMES.map((name) => (\n    <ChartRamp\n      key={name}\n      label={name}\n      colors={RAMPS[name].map((band) => band.color)}\n    />\n  ))}\n  {ramp.length === 0 ? null : <ChartRamp label=\"accent, 9 steps\" colors={ramp} />}\n</div>",
+      "note": "Ordered scales rather than categorical ones: four ported frequency ramps that never re-hue (a listener who has learnt `bass is red` must not relearn it), and one sequential ramp derived from the live accent.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/chart-swatch.json

@@ -0,0 +1,72 @@
+{
+  "name": "ChartSwatch",
+  "slug": "chart-swatch",
+  "group": "charts",
+  "importPath": "@cueplusplus/ui/charts",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "One colour and what it means: the atom a chart legend is built from.\n\nThe chip is `aria-hidden` and the label is plain text, so the meaning survives\nwithout colour vision (WCAG 1.4.1). A swatch with no label is decoration and\nannounces nothing at all, which is the honest reading of a colour with no\ncaption.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "color",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "The colour to show. Any CSS colour, including a `var()` reference.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the colour stands for. Omit for a bare chip.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"span\">, \"children\" | \"color\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "One colour and what it means: the atom a chart legend is built from.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "{BANDS_7.map((band) => <ChartSwatch key={band.id} color={band.color} label={band.label} />)}",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chart-swatch",
+  "mdUrl": "/docs/components/chart-swatch.md",
+  "jsonUrl": "/r/components/chart-swatch.json",
+  "specimens": [
+    {
+      "title": "chartTones() / ChartSwatch",
+      "group": "charts",
+      "components": [
+        "ChartSwatch"
+      ],
+      "code": "<Panel className=\"flex w-full flex-wrap gap-(--cue-space-4) p-(--cue-space-4)\">\n  {CHART_TONE_TOKENS.map((token, index) => (\n    <ChartSwatch key={token} color={chartToneVar(index)} label={token} />\n  ))}\n  {Array.from({ length: 9 }, (_, index) => (\n    <ChartSwatch\n      key={`extended-${index}`}\n      color={chartToneVar(CHART_TONE_TOKENS.length + index)}\n      label={`hue ${index + 1}`}\n    />\n  ))}\n</Panel>",
+      "note": "The categorical palette: the theme's six status colours first, then nine generated oklch hues at fixed lightness and chroma for when six run out. Resolved at render, so switching theme reharmonises every chart on the page without a subscription.",
+      "interaction": "none. A swatch is a readout."
+    }
+  ],
+  "todo": true
+}