@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/chart-container.json

@@ -0,0 +1,111 @@
+{
+  "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."
+    },
+    {
+      "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."
+    },
+    {
+      "name": "aspect",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Width-to-height ratio, letting the plot size itself from its column instead."
+    },
+    {
+      "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."
+    },
+    {
+      "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}."
+    },
+    {
+      "name": "debounce",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Throttle for the resize observer, in ms. Defaults to none."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-info"
+  ],
+  "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,72 @@
+{
+  "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."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "What the ramp encodes. Required: it is the strip's accessible name."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "8",
+      "description": "Strip height in px at the 16px root, emitted as `rem`. Defaults to `8`."
+    }
+  ],
+  "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,65 @@
+{
+  "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."
+    },
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the colour stands for. Omit for a bare chip."
+    }
+  ],
+  "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
+}

package/manifest/components/chart-tooltip-content.json

@@ -0,0 +1,114 @@
+{
+  "name": "ChartTooltipContent",
+  "slug": "chart-tooltip-content",
+  "group": "charts",
+  "importPath": "@cueplusplus/ui/charts",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The tooltip surface: an overlay, styled like every other overlay.\n\nA chart tooltip *is* a floating surface, so it gets exactly what a Popover\ngets — `surface-2` fill, the overlay rim, one soft shadow — from\n`_surface.ts` rather than from a second, chart-only recipe that would drift.\nWhat it adds is the reading discipline the rest of the system uses for\nnumbers: mono, tabular figures, values right-aligned so a column of them lines\nup under the pointer.\n\nReturns `null` when the pointer is off the plot or the payload is empty,\nbecause recharts keeps the content mounted between hovers.\n\n`formatter` and `labelFormatter` may equally be set on the `<Tooltip>` itself:\nrecharts forwards its own configuration into cloned content, so both spellings\nland here. Everything else in that configuration is dropped rather than\nrendered — see {@link domProps} — which also means a handler passed to this\ncomponent does not reach the surface. Nothing would fire on it anyway: the\ntooltip is drawn under the pointer, not in its path.",
+  "props": [
+    {
+      "name": "active",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Whether the pointer is on the plot. Recharts supplies this."
+    },
+    {
+      "name": "payload",
+      "type": "readonly ChartTooltipEntry[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "One entry per series at the hovered index. Recharts supplies this."
+    },
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The hovered category — the x value. Recharts supplies this."
+    },
+    {
+      "name": "hideLabel",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Drop the label line, for a chart whose x axis needs no restating."
+    },
+    {
+      "name": "hideIndicator",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Drop the per-row colour chips, for a single-series chart."
+    },
+    {
+      "name": "labelFormatter",
+      "type": "((label: ReactNode, payload: readonly ChartTooltipEntry[]) => ReactNode)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Format the label line."
+    },
+    {
+      "name": "formatter",
+      "type": "((value: string | number | readonly (string | number)[], name: ReactNode, entry: ChartTooltipEntry, index: number) => ReactNode)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Format one row's value. Return the unit too if you want to own it."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\" | \"content\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-bg",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The tooltip surface: an overlay, styled like every other overlay.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Tooltip cursor={chartTooltipCursor} content={<ChartTooltipContent />} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/chart-tooltip-content",
+  "mdUrl": "/docs/components/chart-tooltip-content.md",
+  "jsonUrl": "/r/components/chart-tooltip-content.json",
+  "specimens": [
+    {
+      "title": "ChartTooltipContent",
+      "group": "charts",
+      "components": [
+        "ChartTooltipContent"
+      ],
+      "code": "<div className=\"w-fit\">\n  <ChartTooltipContent\n    active\n    label=\"19:30\"\n    payload={[\n      { name: \"output\", value: 68, color: \"var(--cue-accent)\", unit: \"%\" },\n      { name: \"dropped\", value: 3, color: \"var(--cue-danger)\", unit: \"%\" },\n    ]}\n  />\n</div>",
+      "note": "The tooltip surface on its own, so a chart drawn from raw recharts parts can still wear it. Shown here mounted rather than hovered.",
+      "interaction": "in a chart it is positioned by recharts; the styling is the same either way."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/checkbox-group.json

@@ -0,0 +1,68 @@
+{
+  "name": "CheckboxGroup",
+  "slug": "checkbox-group",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Shared state for a set of {@link Checkbox}es: one `value` array in, one out.\n\nGive it an accessible name (`aria-label`, or a {@link FieldLabel } inside a\n{@link Field }) — a group of checkboxes with no name is a list of unrelated\ntoggles as far as a screen reader is concerned.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the vertical stack defaults."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseCheckboxGroup.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-sunken",
+    "--cue-text-ui"
+  ],
+  "summary": "Shared state for a set of {@link Checkbox}es: one `value` array in, one out.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<CheckboxGroup aria-label=\"Attributes\" value={attrs} onValueChange={setAttrs}>\n  <Checkbox value=\"pan\" label=\"Pan\" />\n  <Checkbox value=\"tilt\" label=\"Tilt\" />\n</CheckboxGroup>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/checkbox-group",
+  "mdUrl": "/docs/components/checkbox-group.md",
+  "jsonUrl": "/r/components/checkbox-group.json",
+  "specimens": [
+    {
+      "title": "Checkbox / CheckboxGroup",
+      "group": "forms",
+      "components": [
+        "Checkbox",
+        "CheckboxGroup"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Specimens>\n    <Specimen label=\"checked\">\n      <Checkbox label=\"Art-Net\" defaultChecked />\n    </Specimen>\n    <Specimen label=\"unchecked\">\n      <Checkbox label=\"sACN\" />\n    </Specimen>\n    <Specimen label=\"indeterminate\">\n      <Checkbox label=\"All protocols\" indeterminate />\n    </Specimen>\n    <Specimen label=\"disabled\">\n      <Checkbox label=\"Timecode\" disabled />\n    </Specimen>\n    <Specimen label=\"sm\">\n      <Checkbox label=\"Small\" size=\"sm\" defaultChecked />\n    </Specimen>\n  </Specimens>\n  <CheckboxGroup\n    aria-label=\"Output protocols\"\n    defaultValue={[\"artnet\"]}\n    className=\"flex flex-col gap-(--cue-space-3)\"\n  >\n    <Checkbox name=\"artnet\" label=\"Art-Net\" />\n    <Checkbox name=\"sacn\" label=\"sACN\" />\n    <Checkbox name=\"osc\" label=\"OSC\" />\n  </CheckboxGroup>\n</div>",
+      "note": "Two sizes and a real indeterminate state, wired as a parent of its group.",
+      "interaction": "Space toggles; the group's parent box drives and reflects its children."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/checkbox.json

@@ -0,0 +1,93 @@
+{
+  "name": "Checkbox",
+  "slug": "checkbox",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A square, two- or three-state checkbox.\n\nSized from the density *icon* tokens rather than the control ladder: a\ncheckbox is a glyph, not a control chassis, and at ultra-compact density a\ncontrol-height box would dwarf the row it sits in. Checked fills with the\naccent and inks the tick in `accent-fg`, so it reads on every theme without\nper-theme branching.",
+  "props": [
+    {
+      "name": "label",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Inline label rendered beside the box and wrapped with it in a `<label>`, so\nthe text is both the accessible name and part of the hit target. Omit it and\npass `aria-label`, or let a {@link Field } name the control instead."
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the box defaults."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the density icon ladder for the box. Defaults to `\"md\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseCheckbox.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-icon-md",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-sunken",
+    "--cue-text-ui"
+  ],
+  "summary": "A square, two- or three-state box, sized from the density icon tokens.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Checkbox label=\"Enable notifications\" defaultChecked />\n<Checkbox aria-label=\"Select row\" size=\"sm\" checked={selected} onCheckedChange={setSelected} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/checkbox",
+  "mdUrl": "/docs/components/checkbox.md",
+  "jsonUrl": "/r/components/checkbox.json",
+  "whenToUse": [
+    "Boolean values in a form, and row selection in a table.",
+    "Several related values at once. Wrap them in `CheckboxGroup`, which owns one array."
+  ],
+  "whenNotToUse": [
+    "State that applies immediately. Use `Switch`.",
+    "One value out of several. Use `RadioGroup`."
+  ],
+  "commonMistakes": [
+    "Leaving a `CheckboxGroup` without an accessible name, which turns it into a pile of unrelated toggles for a screen reader.",
+    "Using the indeterminate state as a third value. It means \"some of the children are checked\", nothing else."
+  ],
+  "specimens": [
+    {
+      "title": "Checkbox / CheckboxGroup",
+      "group": "forms",
+      "components": [
+        "Checkbox",
+        "CheckboxGroup"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Specimens>\n    <Specimen label=\"checked\">\n      <Checkbox label=\"Art-Net\" defaultChecked />\n    </Specimen>\n    <Specimen label=\"unchecked\">\n      <Checkbox label=\"sACN\" />\n    </Specimen>\n    <Specimen label=\"indeterminate\">\n      <Checkbox label=\"All protocols\" indeterminate />\n    </Specimen>\n    <Specimen label=\"disabled\">\n      <Checkbox label=\"Timecode\" disabled />\n    </Specimen>\n    <Specimen label=\"sm\">\n      <Checkbox label=\"Small\" size=\"sm\" defaultChecked />\n    </Specimen>\n  </Specimens>\n  <CheckboxGroup\n    aria-label=\"Output protocols\"\n    defaultValue={[\"artnet\"]}\n    className=\"flex flex-col gap-(--cue-space-3)\"\n  >\n    <Checkbox name=\"artnet\" label=\"Art-Net\" />\n    <Checkbox name=\"sacn\" label=\"sACN\" />\n    <Checkbox name=\"osc\" label=\"OSC\" />\n  </CheckboxGroup>\n</div>",
+      "note": "Two sizes and a real indeterminate state, wired as a parent of its group.",
+      "interaction": "Space toggles; the group's parent box drives and reflects its children."
+    }
+  ]
+}

package/manifest/components/chip.json

@@ -0,0 +1,132 @@
+{
+  "name": "Chip",
+  "slug": "chip",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A compact status/label pill: mono, uppercase, wide-tracked, one line tall.\n\n`tone` uses the shared status vocabulary (`ok | busy | warn | danger | info`)\nplus `neutral` and `accent`, so a chip, a `StatusDot` and a `Meter` always\nagree on what \"warn\" looks like.",
+  "props": [
+    {
+      "name": "interactive",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "Render as a `<button>` with hover feedback instead of a static `<span>`.\nUse for filter pills and other clickable tags; leave off for pure labels."
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Disable the interactive form. Ignored when `interactive` is not set."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Chip content — normally one or two words, or a short count."
+    },
+    {
+      "name": "tone",
+      "type": "\"accent\" | \"danger\" | \"busy\" | \"neutral\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "neutral",
+      "description": ""
+    },
+    {
+      "name": "variant",
+      "type": "\"outline\" | \"tinted\"",
+      "required": false,
+      "defaultValue": "tinted",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "React.HTMLAttributes<HTMLElement>",
+    "VariantProps<typeof chipVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "tone": [
+      "neutral",
+      "accent",
+      "ok",
+      "busy",
+      "warn",
+      "danger",
+      "info"
+    ],
+    "variant": [
+      "tinted",
+      "outline"
+    ],
+    "interactive": [
+      "true",
+      "false"
+    ]
+  },
+  "defaultVariants": {
+    "tone": "neutral",
+    "variant": "tinted",
+    "interactive": "false"
+  },
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-busy",
+    "--cue-chip-h",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-2",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "The status pill: tinted fill, hairline rim, full-strength text.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Chip tone=\"ok\">online</Chip>\n<Chip tone=\"accent\" variant=\"outline\" interactive onClick={toggle}>dimmer</Chip>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/chip",
+  "mdUrl": "/docs/components/chip.md",
+  "jsonUrl": "/r/components/chip.json",
+  "whenToUse": [
+    "A state, a tag or a short count sitting beside the thing it describes.",
+    "Filter pills, with `interactive` for the button semantics."
+  ],
+  "whenNotToUse": [
+    "A single live state where a dot carries it. Use `StatusDot`.",
+    "A message the user has to read and act on. Use `Toast` or `FieldError`.",
+    "Anything that runs something. Use `Button`."
+  ],
+  "commonMistakes": [
+    "Writing a sentence in a chip. One or two words, or a count.",
+    "Picking a tone for decoration. Tones are the status vocabulary shared with `StatusDot`, `Meter` and `Toast`."
+  ],
+  "specimens": [
+    {
+      "title": "Chip",
+      "group": "primitives",
+      "components": [
+        "Chip"
+      ],
+      "code": "<Specimens>\n  {CHIP_TONES.map((tone) => (\n    <Specimen key={tone} label={tone}>\n      <Chip tone={tone}>{tone}</Chip>\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  {CHIP_TONES.map((tone) => (\n    <Specimen key={tone} label={`${tone} outline`}>\n      <Chip tone={tone} variant=\"outline\">\n        {tone}\n      </Chip>\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"interactive\">\n    <Chip tone=\"accent\" interactive>\n      Universe 1\n    </Chip>\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <Chip tone=\"accent\" interactive disabled>\n      Universe 9\n    </Chip>\n  </Specimen>\n</Specimens>",
+      "note": "The tinted-chip recipe: a tone tint at low alpha, tone ink, tone border. Seven tones, two variants.",
+      "interaction": "static by default; pass `interactive` and it takes a hover ground and a focus ring."
+    }
+  ]
+}