@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/shape-section.json

@@ -54,7 +54,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "Section 3 — the geometry and type knobs, which belong to the *density* axis rather than to the theme.",
+  "summary": "Section 3 of the configurator — geometry and type, which belong to the density axis rather than the theme.",
   "examples": [
     {
       "title": "Usage",
@@ -62,9 +62,17 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/shape-section",
   "mdUrl": "/docs/components/shape-section.md",
   "jsonUrl": "/r/components/shape-section.json",
-  "todo": true
+  "whenToUse": [
+    "Inside `ThemeConfigurator`, for radius, type and the published `--cue-density` escape hatch."
+  ],
+  "whenNotToUse": [
+    "Theme colour work. That is `ColorsSection`."
+  ],
+  "commonMistakes": [
+    "Expecting a multiplier to flatten the ladder. Both are crossed with the density ladder when written, so nudging the radius keeps `ultra-compact` tighter than `large`."
+  ]
 }

package/manifest/components/shared-conversation.json

@@ -87,10 +87,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/shared-conversation",
   "mdUrl": "/docs/components/shared-conversation.md",
   "jsonUrl": "/r/components/shared-conversation.json",
+  "whenToUse": [
+    "The landing view for a shared link: who shared it, when, and the turns as they stood."
+  ],
+  "whenNotToUse": [
+    "A transcript the reader can add to in place. The turns are read only, and `onContinue` forks rather than appends."
+  ],
+  "commonMistakes": [
+    "Computing `sharedAt` inside. It is pre-formatted — `2 days ago`.",
+    "Wiring `onContinue` to write back into the shared thread. It forks the transcript into the reader's own."
+  ],
   "specimens": [
     {
       "title": "SharedConversation",
@@ -102,6 +112,5 @@
       "note": "A read-only transcript somebody sent you, with the one action a reader ever wants: pick it up yourself. The header says who shared it and when, because a published thread with no attribution is a screenshot. Turns render verbatim — this is somebody else's conversation, and it is not the place to start interpreting markdown.",
       "interaction": "continuing forks the transcript into the reader's own thread rather than joining the original, which is why the action is offered and not implied by clicking a turn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sheet.json

@@ -182,7 +182,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A modal panel that slides in from an edge: an inspector, a filter drawer, a details pane too wide for a popover.",
+  "summary": "A modal panel that slides in from an edge: an inspector, a filter drawer, a details pane.",
   "examples": [
     {
       "title": "Usage",
@@ -190,10 +190,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sheet",
   "mdUrl": "/docs/components/sheet.md",
   "jsonUrl": "/r/components/sheet.json",
+  "whenToUse": [
+    "Content that is a *side channel* to the page rather than an interruption of it.",
+    "A pane too wide for a popover but not worth a route."
+  ],
+  "whenNotToUse": [
+    "A task that must be finished before anything else. That is a `Dialog`.",
+    "Touch-first, swipe-dismissable panels. Use `Drawer`."
+  ],
+  "commonMistakes": [
+    "Using it for a question. A sheet is a place to work; an interruption belongs in a dialog."
+  ],
   "specimens": [
     {
       "title": "Sheet",
@@ -205,6 +216,5 @@
       "note": "A dialog anchored to an edge. Three sides, each with its own translate transition.",
       "interaction": "the transition is driven by Base UI's data attributes and CSS, and switches off under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/shimmer-label.json

@@ -41,10 +41,20 @@
   ],
   "summary": "A label that sweeps while something is still happening.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/shimmer-label",
   "mdUrl": "/docs/components/shimmer-label.md",
   "jsonUrl": "/r/components/shimmer-label.json",
+  "whenToUse": [
+    "A live label that should read as still-working, with `active` turned off when it settles."
+  ],
+  "whenNotToUse": [
+    "A page that does not load `@cueplusplus/ui/elements.css`. The sweep and its keyframes are declared there, and without it the label simply sits still."
+  ],
+  "commonMistakes": [
+    "Treating the sweep as the signal. It also does not run under `prefers-reduced-motion`, so the words have to say what is happening on their own.",
+    "Leaving `active` alone when the work finishes. It defaults to `true`, so the label keeps sweeping until you set it false."
+  ],
   "specimens": [
     {
       "title": "ShimmerLabel",
@@ -56,6 +66,5 @@
       "note": "A band of full-strength ink travelling through a muted label, clipped to the glyphs. It is the family's one ambient animation and it means exactly one thing: this is happening now. A reader who asked for less motion gets the muted label and no sweep at all.",
       "interaction": "none. It is text, and it stays selectable text."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sidebar.json

@@ -217,7 +217,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "The console's navigation column: sections of items, a scroller of its own, and a rail that collapses the whole thing to icons.",
+  "summary": "The console's navigation column: sections of items, its own scroller, and a rail that collapses it to icons.",
   "examples": [
     {
       "title": "Usage",
@@ -225,10 +225,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sidebar",
   "mdUrl": "/docs/components/sidebar.md",
   "jsonUrl": "/r/components/sidebar.json",
+  "whenToUse": [
+    "The primary navigation of a console that has more destinations than a bar can hold.",
+    "Anywhere the column must survive a narrow viewport by collapsing to a rail rather than disappearing."
+  ],
+  "whenNotToUse": [
+    "The site's top level. That is a bar question; a column answers what is inside one section.",
+    "A panel of controls. Use a panel — a sidebar is navigation."
+  ],
+  "commonMistakes": [
+    "Giving it the page's scroller instead of its own, so the nav scrolls away with the content.",
+    "Concatenating every section into one column, which buries the section the reader came for under the others."
+  ],
   "specimens": [
     {
       "title": "Sidebar",
@@ -240,6 +252,5 @@
       "note": "Sections of items and a 4px rail that collapses the column to icons. The label goes `sr-only` while collapsed rather than being unmounted, because an icon-only button with no name is a WCAG 4.1.2 failure.",
       "interaction": "the rail is invisible until hovered, and is a real button with an `aria-expanded` state."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/signal-edge.json

@@ -26,7 +26,7 @@
     "--cue-ok",
     "--cue-warn"
   ],
-  "summary": "A wire between two nodes, drawn as three paths.",
+  "summary": "A wire between two nodes, drawn as three paths: the wire, the hit path, and the pulse.",
   "examples": [
     {
       "title": "Usage",
@@ -34,10 +34,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/signal-edge",
   "mdUrl": "/docs/components/signal-edge.md",
   "jsonUrl": "/r/components/signal-edge.json",
+  "whenToUse": [
+    "Any edge on a signal graph.",
+    "Live signal: the pulse overlay draws only while `data.live`."
+  ],
+  "whenNotToUse": [
+    "A plain connector with no state. React Flow's own edge is enough."
+  ],
+  "commonMistakes": [
+    "Dropping the hit path to save a path. It is sixteen invisible pixels because nobody can click 1.6px."
+  ],
   "specimens": [
     {
       "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
@@ -51,6 +61,5 @@
       "note": "The hook returns the `--xy-*` token map plus stable `edgeTypes` and `defaultEdgeOptions` identities. Every part also publishes the map on its own root, so the group is correct before flow.css is imported and correct again after.",
       "interaction": "the controls capsule is an overlay surface; a live wire animates its dash overlay and stops under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/skeleton.json

@@ -18,7 +18,7 @@
     "--cue-radius-control",
     "--cue-surface-2"
   ],
-  "summary": "A loading placeholder block.",
+  "summary": "A loading placeholder block. It carries no intrinsic size — give it the shape of what is arriving.",
   "examples": [
     {
       "title": "Usage",
@@ -26,10 +26,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/skeleton",
   "mdUrl": "/docs/components/skeleton.md",
   "jsonUrl": "/r/components/skeleton.json",
+  "whenToUse": [
+    "Content whose layout you already know, so the page does not jump when it lands: a row of cells, an avatar and two lines of text.",
+    "Waits long enough to notice but short enough that a spinner would feel heavier than the content itself."
+  ],
+  "whenNotToUse": [
+    "An indeterminate wait with no known shape. Use `Spinner`.",
+    "An empty result. Nothing is arriving, so say so — a skeleton promises content that never comes."
+  ],
+  "commonMistakes": [
+    "Rendering one with no `className`. It has no size of its own and collapses to nothing.",
+    "Sizing it differently from the real content, which turns the skeleton into the layout shift it exists to prevent.",
+    "Adding your own `aria-label`. It is `aria-hidden` on purpose — the surrounding live region should say 'loading', not a fleet of empty boxes."
+  ],
   "specimens": [
     {
       "title": "Skeleton",
@@ -41,6 +54,5 @@
       "note": "The shape of content that has not arrived. Sized by the caller, because only the caller knows the shape.",
       "interaction": "the shimmer stills under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/skill-icon.json

@@ -17,10 +17,20 @@
   "tokensUsed": [],
   "summary": "A skill: the thing every other container in this set holds.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/skill-icon",
   "mdUrl": "/docs/components/skill-icon.md",
   "jsonUrl": "/r/components/skill-icon.json",
+  "whenToUse": [
+    "Marking a capability an agent gains — in a catalogue row, a stack, a search result."
+  ],
+  "whenNotToUse": [
+    "The file a skill travels in. That is an implementation detail, not the thing.",
+    "A container of skills. Use `FolderIcon`, `StackIcon` or `CatalogueIcon`."
+  ],
+  "commonMistakes": [
+    "Substituting a page or document glyph, which makes the catalogue look like a folder of documents rather than a list of things an agent can now do."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +51,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/slider.json

@@ -86,10 +86,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/slider",
   "mdUrl": "/docs/components/slider.md",
   "jsonUrl": "/r/components/slider.json",
+  "whenToUse": [
+    "A value judged by feel against its range — intensity, a fade time, a threshold.",
+    "Anywhere the shape of the range matters as much as the number."
+  ],
+  "whenNotToUse": [
+    "A number that must be exact. Use `NumberField`; a 2px rail is a readout first and a grab target second.",
+    "A value with no meaningful minimum or maximum."
+  ],
+  "commonMistakes": [
+    "Writing every `onValueChange` into undo history. `onCommit` is the important half of this API — it is what lets a whole drag coalesce into one undo entry instead of hundreds.",
+    "Adding a separate number readout instead of `showValue`."
+  ],
   "specimens": [
     {
       "title": "Slider / RangeSlider",
@@ -101,6 +113,5 @@
       "note": "One thumb or two. `onCommit` fires once at the end of a drag, which is the undo-coalescing contract the consoles need.",
       "interaction": "the thumb grows while dragging; arrow keys step, Page Up and Page Down jump."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sources.json

@@ -77,10 +77,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sources",
   "mdUrl": "/docs/components/sources.md",
   "jsonUrl": "/r/components/sources.json",
+  "whenToUse": [
+    "Citations under an answer, out of the way until the reader wants them."
+  ],
+  "whenNotToUse": [
+    "A component expected to own its own disclosure. `open` and `onOpenChange` are both required."
+  ],
+  "commonMistakes": [
+    "Passing `open` and no `onOpenChange`, or the reverse. Both are required and the pill does not toggle itself.",
+    "Rendering the source cards separately and using this only for the pill. The cards are the expanded state of the same component."
+  ],
   "specimens": [
     {
       "title": "Sources",
@@ -92,6 +102,5 @@
       "note": "Citations folded into a pill until somebody wants them. Collapsed it is a count — four sources, no argument; open it is a scannable grid of cards, one per site, each lifting a pixel under the pointer. The count is the whole affordance: it says provenance exists without spending a paragraph on it.",
       "interaction": "the pill is the trigger and takes cue's focus ring; the chevron turns with the panel, which animates its own height through Base UI rather than a max-height guess."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/sparkline.json

@@ -61,7 +61,7 @@
     "--cue-danger",
     "--cue-warn"
   ],
-  "summary": "A tiny unlabelled trace: \"is this climbing, or did it just reset?\".",
+  "summary": "A tiny unlabelled trace: 'is this climbing, or did it just reset?'",
   "examples": [
     {
       "title": "Usage",
@@ -69,10 +69,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/sparkline",
   "mdUrl": "/docs/components/sparkline.md",
   "jsonUrl": "/r/components/sparkline.json",
+  "whenToUse": [
+    "Direction and shape beside a number that already carries the magnitude.",
+    "A dense row or tile where a real chart would not fit and would not be read."
+  ],
+  "whenNotToUse": [
+    "A value the reader must quantify. It answers nothing but shape — the numbers belong to the `Stat` or the row above it.",
+    "A series with a meaningful ceiling other than 100."
+  ],
+  "commonMistakes": [
+    "Auto-scaling it to its own range. The scale is always 0–100 on purpose: a trace scaled to itself makes a flat 3% look identical to a flat 95%, which is the exact misreading a sparkline exists to prevent."
+  ],
   "specimens": [
     {
       "title": "Sparkline",
@@ -84,6 +95,5 @@
       "note": "A trend at row height, drawn as one path with no axes and no tooltip. When it needs either, reach for UsageChart.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/speaker-identity.json

@@ -46,10 +46,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/speaker-identity",
   "mdUrl": "/docs/components/speaker-identity.md",
   "jsonUrl": "/r/components/speaker-identity.json",
+  "whenToUse": [
+    "A transcript with more than two participants — several models, several agents — where each turn has to name who produced it."
+  ],
+  "whenNotToUse": [
+    "A plain user-and-assistant exchange, where naming every turn is noise."
+  ],
+  "commonMistakes": [
+    "Passing turns out of order. The prop is turns in order, each naming its own speaker, and the component derives nothing else."
+  ],
   "specimens": [
     {
       "title": "SpeakerIdentity",
@@ -61,6 +70,5 @@
       "note": "Who is talking, once a thread holds more than a user and one model. Four kinds — you, the agent, a subagent it delegated to, and a tool that answered — with the subagent's badge rounded so a delegated turn reads as delegated at a glance. `detail` is the second fact the name needs: which model spoke, or how long the tool took.",
       "interaction": "none. It is a transcript, not a control; the badges are the only thing distinguishing four voices that would otherwise be four paragraphs."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/spec-sheet.json

@@ -65,7 +65,7 @@
     "--cue-text-body",
     "--cue-text-ui"
   ],
-  "summary": "The most common structured answer after a table: one object, labeled.",
+  "summary": "The most common structured answer after a table: one object, labelled.",
   "examples": [
     {
       "title": "Usage",
@@ -73,10 +73,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/spec-sheet",
   "mdUrl": "/docs/components/spec-sheet.md",
   "jsonUrl": "/r/components/spec-sheet.json",
+  "whenToUse": [
+    "One object's attributes as an answer — a model, a SKU, a version — with `subtitle` carrying the identifier."
+  ],
+  "whenNotToUse": [
+    "Several objects compared side by side. This is one object, as label and value pairs."
+  ],
+  "commonMistakes": [
+    "Passing raw numbers and expecting formatting. Values are pre-formatted and right-aligned on tabular figures.",
+    "Slicing `rows` to what has landed. `visibleCount` is that, and `rows` is the whole sheet."
+  ],
   "specimens": [
     {
       "title": "SpecSheet",
@@ -88,6 +98,5 @@
       "note": "One object, labelled — the commonest structured answer after a table. Labels sit in mono on the leading edge and values in tabular figures on the trailing one, so a column of numbers lines up even though nothing here is a table. `emphasis` promotes the one row that answers the question.",
       "interaction": "none. `visibleCount` is what makes it arrive a row at a time instead of appearing whole."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/spectrum-visualizer.json

@@ -127,10 +127,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/spectrum-visualizer",
   "mdUrl": "/docs/components/spectrum-visualizer.md",
   "jsonUrl": "/r/components/spectrum-visualizer.json",
+  "whenToUse": [
+    "Any live audio analyser."
+  ],
+  "whenNotToUse": [
+    "A waveform or a level meter — a spectrum answers frequency, not amplitude over time."
+  ],
+  "commonMistakes": [
+    "Passing a colour per band. Colours are deliberately off the caller's hands: the original API asked for one and defaulted to `#00FF00` when it did not get one, which is how an audio tool ends up with two different greens for the same band in two different panels."
+  ],
   "specimens": [
     {
       "title": "SpectrumVisualizer",
@@ -142,6 +151,5 @@
       "note": "Bars or line, with band colours taken from the /charts ramps. Those are literals on purpose: a listener who has learnt `bass is red` must not relearn it because the console switched accent.",
       "interaction": "a selection dims the bands outside it rather than hiding them; thresholds are dashed rules per band."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/spinner.json

@@ -43,7 +43,7 @@
     "--cue-icon-md",
     "--cue-icon-sm"
   ],
-  "summary": "An indeterminate progress ring, drawn in CSS only — no SVG, no animation library, one element.",
+  "summary": "An indeterminate progress ring, drawn in CSS only — one element, no SVG, no animation library.",
   "examples": [
     {
       "title": "Usage",
@@ -51,10 +51,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/spinner",
   "mdUrl": "/docs/components/spinner.md",
   "jsonUrl": "/r/components/spinner.json",
+  "whenToUse": [
+    "A wait whose length and shape you cannot predict: a request in flight, a job whose progress is not reported.",
+    "Inside another control. It inks with `currentColor`, so a spinner in a `danger` button is red without being told."
+  ],
+  "whenNotToUse": [
+    "A wait with known structure. Use `Skeleton`, which holds the layout as well as the attention.",
+    "Progress you can actually measure. A ring that spins forever tells a reader less than a bar that moves."
+  ],
+  "commonMistakes": [
+    "Colouring it directly instead of letting it inherit. `currentColor` is the whole reason it works in every context.",
+    "Overriding `label` with something the surrounding live region already says, which announces the wait twice.",
+    "Assuming reduced motion hides it. The rotation stops and the ring stays as a static arc — the wait is still visible."
+  ],
   "specimens": [
     {
       "title": "Spinner",
@@ -66,6 +79,5 @@
       "note": "Two sizes. Carries a visually hidden label so a screen reader is told the wait, not left with a spinning div.",
       "interaction": "stills under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stack-icon.json

@@ -17,10 +17,20 @@
   "tokensUsed": [],
   "summary": "One person's stack: the set of things they have actually installed.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stack-icon",
   "mdUrl": "/docs/components/stack-icon.md",
   "jsonUrl": "/r/components/stack-icon.json",
+  "whenToUse": [
+    "An accumulation — where the order things went in is part of what it is."
+  ],
+  "whenNotToUse": [
+    "A container things are filed into. Use `FolderIcon`.",
+    "Every stack at once. Use `StacksMatrixIcon`."
+  ],
+  "commonMistakes": [
+    "Drawing it as a box. The plates seen edge-on are the layers idiom, and a stack is an accumulation rather than a container."
+  ],
   "specimens": [
     {
       "title": "The container icon set",
@@ -41,6 +51,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/stack.json

@@ -123,10 +123,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stack",
   "mdUrl": "/docs/components/stack.md",
   "jsonUrl": "/r/components/stack.json",
+  "whenToUse": [
+    "Any run of siblings that needs consistent spacing — which is almost every layout in the system.",
+    "Anywhere spacing should track density: `gap={4}` is 8px at normal and 6px at ultra-compact without touching the markup."
+  ],
+  "whenNotToUse": [
+    "Two-dimensional layout. Use `Grid`.",
+    "A single child. The wrapper buys nothing."
+  ],
+  "commonMistakes": [
+    "Writing `flex gap-2` by hand instead. That is the exact opt-out this exists to prevent — it pins the spacing to a pixel value and stops tracking the density ladder.",
+    "Reaching for `gap` values outside the ladder, which reintroduces the per-call-site guess."
+  ],
   "specimens": [
     {
       "title": "Stack",
@@ -138,6 +150,5 @@
       "note": "Flex with the gap taken from a rung of the density ladder, never a length. That is what makes a layout tighten with the rest of the console.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/stacks-matrix-icon.json

@@ -17,10 +17,19 @@
   "tokensUsed": [],
   "summary": "Every stack at once, one column each: who has what, read across.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stacks-matrix-icon",
   "mdUrl": "/docs/components/stacks-matrix-icon.md",
   "jsonUrl": "/r/components/stacks-matrix-icon.json",
+  "whenToUse": [
+    "A two-axis question — 'which of these does that person not have'."
+  ],
+  "whenNotToUse": [
+    "One stack. Use `StackIcon`."
+  ],
+  "commonMistakes": [
+    "Drawing more plates instead. The head rule and the name column are what make it a matrix rather than a grid, and the question it answers has two axes."
+  ],
   "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/stat.json

@@ -91,10 +91,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/stat",
   "mdUrl": "/docs/components/stat.md",
   "jsonUrl": "/r/components/stat.json",
+  "whenToUse": [
+    "A reading that deserves its own tile, in a row that scans as a list of captions with values underneath.",
+    "Numbers that change in place — the value is `tabular-nums` mono, so a ticking figure does not shuffle the layout."
+  ],
+  "whenNotToUse": [
+    "A table of numbers. Use a data table; a wall of tiles is harder to compare than a column.",
+    "A trend. Pair it with `Sparkline`, which answers direction, not magnitude."
+  ],
+  "commonMistakes": [
+    "Tinting the caption as well as the value. Only the value takes the tone — tinting both turns a red tile into an alarm rather than a reading.",
+    "Leading with the number. It reads label-first on purpose."
+  ],
   "specimens": [
     {
       "title": "Stat",
@@ -106,6 +118,5 @@
       "note": "A label, a figure and a detail line. Figures are mono `tabular-nums`, so a changing digit never shifts the column.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }