@cueplusplus/ui 0.13.0 → 0.14.1

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
+  ]
 }

package/manifest/components/checkpoint-history.json

@@ -71,10 +71,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/checkpoint-history",
   "mdUrl": "/docs/components/checkpoint-history.md",
   "jsonUrl": "/r/components/checkpoint-history.json",
+  "whenToUse": [
+    "A run with restore points, where the user needs to see what returning to one would give back."
+  ],
+  "whenNotToUse": [
+    "A plain event log with nothing to restore to.",
+    "Choosing between possible futures. These are points already behind the run, listed oldest first."
+  ],
+  "commonMistakes": [
+    "Passing `checkpoints` newest first. They are expected oldest first.",
+    "Leaving `currentId` stale after a restore. Everything after it dims, because restoring would discard it."
+  ],
   "specimens": [
     {
       "title": "CheckpointHistory",
@@ -86,6 +97,5 @@
       "note": "Points the run can be put back to, oldest first, each with what a fallback would cost in files. Everything after the current point dims, because restoring would discard it — the list is the undo stack drawn as a place rather than a count.",
       "interaction": "each row carries a labelled restore button (`Restore to …`), so the control is named even though it draws as a glyph."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/clamp.json

@@ -105,10 +105,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/clamp",
   "mdUrl": "/docs/components/clamp.md",
   "jsonUrl": "/r/components/clamp.json",
+  "whenToUse": [
+    "Anything a transcript truncates: command output, a pasted file, a reasoning trace, a quoted message.",
+    "Anywhere the cut must look the same everywhere — the alternative is five slightly different cuts."
+  ],
+  "whenNotToUse": [
+    "Content short enough to show. A fade over nothing is chrome."
+  ],
+  "commonMistakes": [
+    "Painting a gradient of the surface colour over the content instead. The fade is a **mask**, so it needs no idea of what is behind it — the overlay version is the one that hard-codes a colour and breaks in light mode."
+  ],
   "specimens": [
     {
       "title": "Clamp",
@@ -120,6 +130,5 @@
       "note": "The truncation trio as one element: a height, a dissolve of a fixed number of pixels at the cut, and a way back. The fixed depth is the part worth copying — ten pixels of dissolve is the same cut over a two-line row and a forty-line one, which is why the reference's five different truncations read as one idea. The fade is a mask rather than a gradient of the surface colour, which is the bug the reference shipped: its diff variant hard-codes a dark grey and smears on a light theme. A mask fades the content itself, so it has no colour to get wrong in any theme, either mode, or inside the island.",
       "interaction": "the reveal is always present and always focusable; hover and focus decide only how loudly it is drawn, and Show less is never dimmed at all. That is the one place this does not copy the reference, whose Show more chip appears on hover only and is unreachable for anyone not holding a pointer. The height and the fade are published as custom properties on the root, and the mask is written in terms of them, so a height overridden in a stylesheet moves the dissolve with it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/cli-tool-icon.json

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "A CLI tool in the registry: a thing that runs in a terminal.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/cli-tool-icon",
   "mdUrl": "/docs/components/cli-tool-icon.md",
   "jsonUrl": "/r/components/cli-tool-icon.json",
+  "whenToUse": [
+    "A catalogue row for something invoked from a shell."
+  ],
+  "whenNotToUse": [
+    "A running service. Use `McpServerIcon`."
+  ],
+  "commonMistakes": [
+    "Using a bare chevron. A chevron is a disclosure everywhere else in this library, and a navigation row that appeared to expand and then navigated instead is a worse failure than a slightly busier glyph at 10px."
+  ],
   "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/code-diff.json

@@ -84,10 +84,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/code-diff",
   "mdUrl": "/docs/components/code-diff.md",
   "jsonUrl": "/r/components/code-diff.json",
+  "whenToUse": [
+    "One file's unified diff inside a transcript, with its path and counts in the header.",
+    "A diff that should replay its entrance animation when the turn changes, by moving `cycle`."
+  ],
+  "whenNotToUse": [
+    "A change spanning many files. This is one file, one `lines` array of context, added and removed.",
+    "A side-by-side comparison. `lines` is a single unified list."
+  ],
+  "commonMistakes": [
+    "Deriving `additions` and `deletions` from `lines` and expecting them to agree. They are separate props and the header prints what you pass.",
+    "Holding `cycle` constant and wondering why the entrance animation never replays. It is an identity key that remounts the body."
+  ],
   "specimens": [
     {
       "title": "CodeDiff",
@@ -99,6 +111,5 @@
       "note": "A unified diff sized for a chat column: added and removed rows carry both a gutter mark and a tint, so the diff survives being read in greyscale. Rows animate in on `cycle`, which is an identity rather than a trigger.",
       "interaction": "none. Scrolls sideways rather than wrapping, because a wrapped diff line is a lie about the file."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/code-runner.json

@@ -104,10 +104,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/code-runner",
   "mdUrl": "/docs/components/code-runner.md",
   "jsonUrl": "/r/components/code-runner.json",
+  "whenToUse": [
+    "Executable code in a transcript, with its output attached to it rather than in a second block.",
+    "A settled run, where `durationMs` prints how long it took."
+  ],
+  "whenNotToUse": [
+    "Code that is only there to be read. The run control is the point of the element."
+  ],
+  "commonMistakes": [
+    "Passing highlighted markup to `code`. It is rendered as plain mono; wrap it yourself for highlighting.",
+    "Using `state=\"idle\"` for a finished run that produced nothing. idle hides the output pane entirely."
+  ],
   "specimens": [
     {
       "title": "CodeRunner",
@@ -119,6 +130,5 @@
       "note": "A snippet with a run button and the output it produced attached underneath, rather than in a console somewhere else. `idle` hides the output pane entirely — an empty black box is not a result — `error` tints what came back in the danger hue, and the duration prints once it settles.",
       "interaction": "the run control is a labelled icon button (`Run this snippet`); while running it spins and the output arrives a line at a time."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/collapsible.json

@@ -113,10 +113,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/collapsible",
   "mdUrl": "/docs/components/collapsible.md",
   "jsonUrl": "/r/components/collapsible.json",
+  "whenToUse": [
+    "A single section of a page that peers with the sections around it.",
+    "Anywhere it should look identical to a member of an `Accordion`, because it wears the same summary-row skin."
+  ],
+  "whenNotToUse": [
+    "Several sections. Use `Accordion`, which coordinates which are open.",
+    "Advanced fields inside a form. Use `Disclosure` — this is a peer section, that is an annotation on the form."
+  ],
+  "commonMistakes": [
+    "Using it for the 'advanced' idiom. The summary row is the tell: it announces a section where the form wanted a footnote."
+  ],
   "specimens": [
     {
       "title": "Collapsible",
@@ -128,6 +139,5 @@
       "note": "One panel, one trigger, no grouping rules.",
       "interaction": "same height animation as the accordion panel."
     }
-  ],
-  "todo": true
+  ]
 }