@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/canvas-split-thread.json

@@ -29,10 +29,19 @@
   ],
   "summary": "The conversation, narrowed to a rail beside the document.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-thread",
   "mdUrl": "/docs/components/canvas-split-thread.md",
   "jsonUrl": "/r/components/canvas-split-thread.json",
+  "whenToUse": [
+    "Holding the turns while the document is written, so the turn that asked for the artifact stays in view."
+  ],
+  "whenNotToUse": [
+    "A full-width transcript. This is the narrowed rail, not the main conversation surface."
+  ],
+  "commonMistakes": [
+    "Freezing its scroll while the document streams. It keeps scrolling, which is what keeps the requesting turn visible."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -50,6 +59,5 @@
       "note": "The thread steps aside and the document takes the room. Seven parts: the split itself, a narrowed conversation rail, and a document half with its own header, body and lines — still being written while you read it, which is what the caret at the end of the body is for. On a narrow viewport the two halves stack instead of shrinking.",
       "interaction": "copy and close are named buttons and disable themselves without a handler. `saved` is the only state the header animates, and it swaps a word for a check rather than moving anything."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/canvas-split.json

@@ -35,10 +35,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split",
   "mdUrl": "/docs/components/canvas-split.md",
   "jsonUrl": "/r/components/canvas-split.json",
+  "whenToUse": [
+    "A generated document long enough to deserve its own column beside a narrowed conversation.",
+    "A document that keeps being written while the person reads it."
+  ],
+  "whenNotToUse": [
+    "A short artifact that belongs inline in the transcript."
+  ],
+  "commonMistakes": [
+    "Putting the header inside `CanvasSplitBody`. `CanvasSplitHeader` and `CanvasSplitBody` are siblings inside `CanvasSplitDocument`.",
+    "Rendering turns outside `CanvasSplitThread`, which is the rail the conversation narrows into beside the document."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -56,6 +67,5 @@
       "note": "The thread steps aside and the document takes the room. Seven parts: the split itself, a narrowed conversation rail, and a document half with its own header, body and lines — still being written while you read it, which is what the caret at the end of the body is for. On a narrow viewport the two halves stack instead of shrinking.",
       "interaction": "copy and close are named buttons and disable themselves without a handler. `saved` is the only state the header animates, and it swaps a word for a check rather than moving anything."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/card.json

@@ -132,10 +132,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/card",
   "mdUrl": "/docs/components/card.md",
   "jsonUrl": "/r/components/card.json",
+  "whenToUse": [
+    "One coherent object that deserves its own ground and edge.",
+    "Anywhere the root may later switch to the seam idiom — every section paints its own `surface-1`, so the parts need not know."
+  ],
+  "whenNotToUse": [
+    "Every block on the page. Border, fill and radius each say 'separate object'; stamping them everywhere flattens the hierarchy they exist to create.",
+    "A list row. Use `Item`, or `Row` inside a hairline table."
+  ],
+  "commonMistakes": [
+    "Nesting cards, which gives two competing grounds and no hierarchy.",
+    "Repainting a section's ground by hand instead of letting it paint its own, which is what breaks the seam switch."
+  ],
   "specimens": [
     {
       "title": "Card",
@@ -147,6 +159,5 @@
       "note": "A panel with body padding and a title family. `seam` swaps the hairline separation for the 1px-gap idiom.",
       "interaction": "none by default; wrap the header in a button if the card is a link."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/carousel.json

@@ -222,10 +222,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/carousel",
   "mdUrl": "/docs/components/carousel.md",
   "jsonUrl": "/r/components/carousel.json",
+  "whenToUse": [
+    "Peer items in a horizontal run the user browses rather than compares — screenshots, presets, a gallery."
+  ],
+  "whenNotToUse": [
+    "Content the user must not miss. Anything off-screen in a carousel is content most readers never see.",
+    "Two or three items that would fit side by side. Use `Grid`."
+  ],
+  "commonMistakes": [
+    "Importing it from the core barrel. `embla-carousel-react` is an **optional peer** — import from `@cueplusplus/ui/layout/carousel` so an app that ships no carousel never installs one."
+  ],
   "specimens": [
     {
       "title": "Carousel",
@@ -237,6 +247,5 @@
       "note": "Embla, wearing the tokens. An optional peer, so it ships from @cueplusplus/ui/layout/carousel rather than the core barrel.",
       "interaction": "drag or use the two controls; the dots are buttons and each says which slide it goes to."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/catalogue-icon.json

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "The catalogue itself: everything there is, before anything has been narrowed.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/catalogue-icon",
   "mdUrl": "/docs/components/catalogue-icon.md",
   "jsonUrl": "/r/components/catalogue-icon.json",
+  "whenToUse": [
+    "The row that *undoes* a filter — 'all of it'."
+  ],
+  "whenNotToUse": [
+    "A filtered view or a curated set. Use `FolderIcon`."
+  ],
+  "commonMistakes": [
+    "Using a list glyph, which promises an ordering the row does not have. The 2×2 of one repeated tile says 'all of it' is a shape, not a sequence."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +50,5 @@
       "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-beta-icon.json

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "The beta channel: the same things, one merge earlier.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/channel-beta-icon",
   "mdUrl": "/docs/components/channel-beta-icon.md",
   "jsonUrl": "/r/components/channel-beta-icon.json",
+  "whenToUse": [
+    "Marking a pre-release channel beside its released pair."
+  ],
+  "whenNotToUse": [
+    "An empty or unpopulated channel."
+  ],
+  "commonMistakes": [
+    "Drawing the ring empty. Half rather than empty because a beta is not an absence of a release — it is a release that has not finished happening, and an empty ring reads as 'nothing here yet'."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +50,5 @@
       "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

@@ -219,10 +219,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/channel-matrix",
   "mdUrl": "/docs/components/channel-matrix.md",
   "jsonUrl": "/r/components/channel-matrix.json",
+  "whenToUse": [
+    "Inspecting individual channels while a universe is running."
+  ],
+  "whenNotToUse": [
+    "An overview. Use `DmxBar`."
+  ],
+  "commonMistakes": [
+    "Rendering the cells from React state. Five hundred and twelve elements re-rendered forty times a second is a locked tab — the grid renders once and never re-renders, and an animation loop repaints it."
+  ],
   "specimens": [
     {
       "title": "ChannelMatrix",
@@ -234,6 +243,5 @@
       "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

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "The released channel: what a colleague gets when they install without asking for anything in particular.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/channel-released-icon",
   "mdUrl": "/docs/components/channel-released-icon.md",
   "jsonUrl": "/r/components/channel-released-icon.json",
+  "whenToUse": [
+    "Marking the default, finished channel."
+  ],
+  "whenNotToUse": [
+    "A pre-release. Use `ChannelBetaIcon`, which is the same ring filled halfway."
+  ],
+  "commonMistakes": [
+    "Pairing it with an unrelated glyph for beta. The two are one mark told twice, so a reader never has to learn which of two pictures means 'finished'."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +50,5 @@
       "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

@@ -87,10 +87,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chart-container",
   "mdUrl": "/docs/components/chart-container.md",
   "jsonUrl": "/r/components/chart-container.json",
+  "whenToUse": [
+    "Around any chart, so the palette arrives as `--chart-1`…`--chart-N` custom properties."
+  ],
+  "whenNotToUse": [
+    "Around a `Sparkline` or `UsageChart`, which draw themselves and need no palette."
+  ],
+  "commonMistakes": [
+    "Hard-coding chart colours. The properties carry `var(--cue-accent)`, `var(--cue-info)` and the rest *by reference*, so a theme change reaches the chart without the chart knowing."
+  ],
   "specimens": [
     {
       "title": "ChartContainer — line",
@@ -122,6 +131,5 @@
       "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

@@ -62,10 +62,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chart-ramp",
   "mdUrl": "/docs/components/chart-ramp.md",
   "jsonUrl": "/r/components/chart-ramp.json",
+  "whenToUse": [
+    "Showing a sequential scale beside the chart that uses it."
+  ],
+  "whenNotToUse": [
+    "A categorical legend. Use `ChartSwatch` per category."
+  ],
+  "commonMistakes": [
+    "Drawing it as a CSS gradient. A ramp *is* discrete — a gradient shows steps the data cannot address and quietly disagrees with the same ramp filling the bars.",
+    "Adding seams between cells, which read as category boundaries in a scale that has none."
+  ],
   "specimens": [
     {
       "title": "RAMPS / accentRamp()",
@@ -77,6 +87,5 @@
       "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

@@ -52,10 +52,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chart-swatch",
   "mdUrl": "/docs/components/chart-swatch.md",
   "jsonUrl": "/r/components/chart-swatch.json",
+  "whenToUse": [
+    "Every entry in a legend."
+  ],
+  "whenNotToUse": [
+    "A continuous scale. Use `ChartRamp`."
+  ],
+  "commonMistakes": [
+    "Rendering it without a label. The chip is `aria-hidden` and the label is the meaning — a swatch with no label is decoration and announces nothing, which is the honest reading of a colour with no caption (WCAG 1.4.1)."
+  ],
   "specimens": [
     {
       "title": "chartTones() / ChartSwatch",
@@ -67,6 +76,5 @@
       "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

@@ -112,7 +112,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "The tooltip surface: an overlay, styled like every other overlay.",
+  "summary": "The chart tooltip surface: an overlay, styled like every other overlay.",
   "examples": [
     {
       "title": "Usage",
@@ -120,10 +120,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chart-tooltip-content",
   "mdUrl": "/docs/components/chart-tooltip-content.md",
   "jsonUrl": "/r/components/chart-tooltip-content.json",
+  "whenToUse": [
+    "Inside a chart's tooltip, so it gets what a popover gets — `surface-2`, the overlay rim, one soft shadow."
+  ],
+  "whenNotToUse": [
+    "Outside a chart. Use `Tooltip` or `Popover`."
+  ],
+  "commonMistakes": [
+    "Writing a chart-only surface recipe, which is a second source of truth that drifts from `_surface.ts`."
+  ],
   "specimens": [
     {
       "title": "ChartTooltipContent",
@@ -135,6 +144,5 @@
       "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/chart.json

@@ -97,10 +97,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chart",
   "mdUrl": "/docs/components/chart.md",
   "jsonUrl": "/r/components/chart.json",
+  "whenToUse": [
+    "A series that arrives over time, where `visibleCount` walks forward as points land.",
+    "A headline figure with a change against the previous window beside the marks."
+  ],
+  "whenNotToUse": [
+    "A series whose numbers still need formatting. The chart never formats numbers itself — `value` and `delta` are pre-formatted strings.",
+    "A dataset with no natural last point. The last point stays emphasised in all three variants."
+  ],
+  "commonMistakes": [
+    "Passing only the points that have arrived. Pass the whole series in `points` and move `visibleCount`, because the scale is computed from all of it so the axis does not jump while streaming.",
+    "Expecting `delta` to be coloured by your own sign logic. It renders green unless it starts with a minus sign."
+  ],
   "specimens": [
     {
       "title": "Chart",
@@ -112,6 +124,5 @@
       "note": "One series, three ways, on one scale: an area, a bare line, or bars with the newest one lit. It draws its own SVG at a fixed viewBox and stretches — there is no charting library under this, which is the point of it being an element rather than an instrument.",
       "interaction": "none, and it is not a substitute for the charts group: no axes, no legend, no tooltip. The `<svg>` carries role='img' and a label built from the figure beside it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/chat-empty-state.json

@@ -31,10 +31,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chat-empty-state",
   "mdUrl": "/docs/components/chat-empty-state.md",
   "jsonUrl": "/r/components/chat-empty-state.json",
+  "whenToUse": [
+    "A thread with no messages yet, where the greeting, the suggestions and a composer are the whole screen.",
+    "A row of starter pills that should arrive in order, which `EmptyStateSuggestion` staggers from its `index`."
+  ],
+  "whenNotToUse": [
+    "A thread that already has turns in it."
+  ],
+  "commonMistakes": [
+    "Scattering the suggestion pills outside `EmptyStateSuggestions`, which is the row they belong in.",
+    "Expecting `EmptyStateComposer` to hold text. It takes a `placeholder` string and an `onSend` handler."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -50,6 +61,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/chat-panel-assistant-message.json

@@ -27,10 +27,19 @@
   ],
   "summary": "One message from the model: plain text on the leading edge, no bubble.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chat-panel-assistant-message",
   "mdUrl": "/docs/components/chat-panel-assistant-message.md",
   "jsonUrl": "/r/components/chat-panel-assistant-message.json",
+  "whenToUse": [
+    "Model turns in a panel transcript."
+  ],
+  "whenNotToUse": [
+    "A turn from the person, which is drawn as a filled bubble on the trailing edge instead."
+  ],
+  "commonMistakes": [
+    "Wrapping it in a bubble to match the user's turns. The asymmetry is the point: the model's text runs plain on the leading edge."
+  ],
   "specimens": [
     {
       "title": "ChatPanel",
@@ -47,6 +56,5 @@
       "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
       "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/chat-panel-composer.json

@@ -49,10 +49,19 @@
   ],
   "summary": "The panel's composer row.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chat-panel-composer",
   "mdUrl": "/docs/components/chat-panel-composer.md",
   "jsonUrl": "/r/components/chat-panel-composer.json",
+  "whenToUse": [
+    "The input row at the foot of a panel, when the screen needs the shape of a composer rather than a live one."
+  ],
+  "whenNotToUse": [
+    "A working input. It is a display of a composer — `placeholder` is a string, not a value."
+  ],
+  "commonMistakes": [
+    "Omitting `onSend` and expecting a live control. Without a handler the send control renders disabled."
+  ],
   "specimens": [
     {
       "title": "ChatPanel",
@@ -69,6 +78,5 @@
       "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
       "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/chat-panel-messages.json

@@ -27,10 +27,19 @@
   ],
   "summary": "The scrolling transcript inside a `ChatPanel`.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chat-panel-messages",
   "mdUrl": "/docs/components/chat-panel-messages.md",
   "jsonUrl": "/r/components/chat-panel-messages.json",
+  "whenToUse": [
+    "Holding the turns of a panel conversation."
+  ],
+  "whenNotToUse": [
+    "Content outside a `ChatPanel`. It is that frame's transcript slot."
+  ],
+  "commonMistakes": [
+    "Adding your own top alignment or spacer. It is bottom-aligned, so a short conversation sits on the composer rather than floating at the top of the panel."
+  ],
   "specimens": [
     {
       "title": "ChatPanel",
@@ -47,6 +56,5 @@
       "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
       "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/chat-panel-typing.json

@@ -27,10 +27,19 @@
   ],
   "summary": "The three-dot rest state, for the gap between sending and the first token.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chat-panel-typing",
   "mdUrl": "/docs/components/chat-panel-typing.md",
   "jsonUrl": "/r/components/chat-panel-typing.json",
+  "whenToUse": [
+    "The pause after a message is sent and before the first token arrives."
+  ],
+  "whenNotToUse": [
+    "Any wait that outlasts that gap. It is a rest state, not a progress indicator."
+  ],
+  "commonMistakes": [
+    "Leaving it mounted once tokens are streaming, which shows the model as still silent while it is already replying."
+  ],
   "specimens": [
     {
       "title": "ChatPanel",
@@ -47,6 +56,5 @@
       "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
       "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/chat-panel-user-message.json

@@ -27,10 +27,19 @@
   ],
   "summary": "One message from the person, drawn as a filled bubble on the trailing edge.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chat-panel-user-message",
   "mdUrl": "/docs/components/chat-panel-user-message.md",
   "jsonUrl": "/r/components/chat-panel-user-message.json",
+  "whenToUse": [
+    "Turns from the person in a panel transcript."
+  ],
+  "whenNotToUse": [
+    "A model turn, which runs as plain text on the leading edge rather than in a bubble."
+  ],
+  "commonMistakes": [
+    "Overriding the alignment to match the model's turns. The trailing edge and the fill are what tell the two apart at a glance."
+  ],
   "specimens": [
     {
       "title": "ChatPanel",
@@ -47,6 +56,5 @@
       "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
       "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/chat-panel.json

@@ -33,10 +33,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/chat-panel",
   "mdUrl": "/docs/components/chat-panel.md",
   "jsonUrl": "/r/components/chat-panel.json",
+  "whenToUse": [
+    "A compact chat surface that needs a transcript and a composer in one frame.",
+    "A transcript where the pause before the first token has a rest state of its own, via `ChatPanelTyping`."
+  ],
+  "whenNotToUse": [
+    "A single message on its own. The panel is the frame around the transcript and the composer, not a message wrapper."
+  ],
+  "commonMistakes": [
+    "Rendering turns directly inside `ChatPanel`. They go in `ChatPanelMessages`.",
+    "Leaving `ChatPanelTyping` mounted once tokens arrive — it stands for the pause before the reply, not the reply."
+  ],
   "specimens": [
     {
       "title": "ChatPanel",
@@ -53,6 +64,5 @@
       "note": "The six parts working together, which is what the whole family is for. The person's turn is a filled bubble on the trailing edge, the model's is plain text on the leading one, and the transcript is bottom-aligned so a short conversation sits on the composer rather than floating.",
       "interaction": "the send control is the only live thing here; use it and the reply is replaced by the three-dot pause, then comes back."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/checkbox-group.json

@@ -41,7 +41,7 @@
     "--cue-sunken",
     "--cue-text-ui"
   ],
-  "summary": "Shared state for a set of {@link Checkbox}es: one `value` array in, one out.",
+  "summary": "Shared state for a set of checkboxes: one `value` array in, one out.",
   "examples": [
     {
       "title": "Usage",
@@ -49,10 +49,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/checkbox-group",
   "mdUrl": "/docs/components/checkbox-group.md",
   "jsonUrl": "/r/components/checkbox-group.json",
+  "whenToUse": [
+    "Any number of options, including none — filters, permissions, capabilities.",
+    "Anywhere the selected set should be read and written as one array rather than N booleans."
+  ],
+  "whenNotToUse": [
+    "Exactly one answer. Use `RadioGroup`.",
+    "A single independent toggle. Use `Checkbox`, or `Switch` for a setting."
+  ],
+  "commonMistakes": [
+    "Leaving it unnamed. A group of checkboxes with no accessible name is a list of unrelated toggles as far as a screen reader is concerned.",
+    "Keeping a separate boolean per option beside the group's array, which gives two sources of truth that drift."
+  ],
   "specimens": [
     {
       "title": "Checkbox / CheckboxGroup",
@@ -65,6 +77,5 @@
       "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
+  ]
 }