@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/message-list.json

@@ -101,10 +101,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-list",
   "mdUrl": "/docs/components/message-list.md",
   "jsonUrl": "/r/components/message-list.json",
+  "whenToUse": [
+    "Any streaming transcript.",
+    "Anywhere the reader must be able to scroll back mid-stream without being yanked forward."
+  ],
+  "whenNotToUse": [
+    "A static conversation. A `Stack` of `Message`s is enough."
+  ],
+  "commonMistakes": [
+    "Treating following as a scroll position rather than a mode. It is a mode: pinned to the bottom it follows, and scrolling up hands control back and offers a 'jump to latest' pill — because a stream that yanks the viewport mid-sentence is the single most common reason people stop reading a chat."
+  ],
   "specimens": [
     {
       "title": "MessageList",
@@ -116,6 +126,5 @@
       "note": "A stick-to-bottom scroller. Scroll away and it offers to jump back to the latest rather than yanking you there.",
       "interaction": "the jump control is a button, and it appears only once you have actually scrolled off the tail."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-pair.json

@@ -87,10 +87,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-pair",
   "mdUrl": "/docs/components/message-pair.md",
   "jsonUrl": "/r/components/message-pair.json",
+  "whenToUse": [
+    "A single exchange rendered as one unit — a preview tile, a demo, a bench frame — where the reply arrives word by word."
+  ],
+  "whenNotToUse": [
+    "A transcript of many turns. This is one pair, and the assistant side is a `words` array with a `visibleWords` counter rather than children you compose."
+  ],
+  "commonMistakes": [
+    "Leaving `streaming` true once `visibleWords` reaches the end, so a settled reply keeps its newest words tinted blue.",
+    "Restyling the user bubble away with classes instead of `variant=\"flat\"`, which renders it as plain right-aligned text."
+  ],
   "specimens": [
     {
       "title": "MessagePair",
@@ -102,6 +112,5 @@
       "note": "A whole turn in one element: what was asked, and the answer streaming under it with its actions waiting on hover. The two variants are the two house styles for a user turn — a bubble, or right-aligned text with no chrome at all.",
       "interaction": "the action row is invisible until the turn is hovered *or* focused, which is what keeps a keyboard from losing it. Both buttons are named."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-queue.json

@@ -65,10 +65,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-queue",
   "mdUrl": "/docs/components/message-queue.md",
   "jsonUrl": "/r/components/message-queue.json",
+  "whenToUse": [
+    "Showing what will send once the current run finishes, with the in-flight turn above the queue."
+  ],
+  "whenNotToUse": [
+    "A queue with nothing running. `running` is required, and the component is built around a turn in flight.",
+    "A queue whose entries should be rewritten or jumped before they send. The only thing this offers is `onCancel`."
+  ],
+  "commonMistakes": [
+    "Re-sorting `queued` before passing it. The order is the order the turns will drain in.",
+    "Wiring `onCancel` to stop the run. It removes a queued turn before it ever sends; the turn shown above is not cancellable from here."
+  ],
   "specimens": [
     {
       "title": "MessageQueue",
@@ -80,6 +91,5 @@
       "note": "What you typed while the last run was still out. The turn in flight pings at the top; everything behind it is numbered, cancellable and explicitly told when it will go. A queue that did not say 'sends when this finishes' would look like a list of failures.",
       "interaction": "each row's × is a named button — the message text is in the label, so five rows do not all read as 'Remove'."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message-timing.json

@@ -49,10 +49,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message-timing",
   "mdUrl": "/docs/components/message-timing.md",
   "jsonUrl": "/r/components/message-timing.json",
+  "whenToUse": [
+    "Under a finished turn, where the reader should be able to see what it cost.",
+    "During a stream: show fewer stats and set `streaming`, which tints the values while they are still moving."
+  ],
+  "whenNotToUse": [
+    "Raw numbers. `stats` are label and value pairs, pre-formatted — there is no rounding, no unit and no currency here."
+  ],
+  "commonMistakes": [
+    "Passing the full set of stats while the turn is still streaming. The intended shape is fewer during, the full set once it settles.",
+    "Leaving `streaming` on after the turn lands, so settled values stay tinted as if they were still moving."
+  ],
   "specimens": [
     {
       "title": "MessageTiming",
@@ -64,6 +75,5 @@
       "note": "What the turn cost, in the footer where a reader can ignore it. The values are strings the caller already formatted; while the turn is still streaming they sit in the live hue and settle into ink when it lands, so the row doubles as a state.",
       "interaction": "none. It is four label/value pairs in mono, tabular so the numbers do not jitter as they update."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/message.json

@@ -129,10 +129,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/message",
   "mdUrl": "/docs/components/message.md",
   "jsonUrl": "/r/components/message.json",
+  "whenToUse": [
+    "Any transcript turn — a user's, an agent's, a tool's.",
+    "Anywhere authorship, timestamp and pending state should be drawn consistently."
+  ],
+  "whenNotToUse": [
+    "A delegated sub-run. Use `DelegationCard`, which folds it."
+  ],
+  "commonMistakes": [
+    "Expecting it to render markdown. Content is React nodes, verbatim, on purpose: model output is untrusted text, and a component that quietly parsed it would make every consumer one prompt away from an injection. Pass your own renderer and own that decision."
+  ],
   "specimens": [
     {
       "title": "Message",
@@ -144,6 +154,5 @@
       "note": "Three roles. The bubble radii are asymmetric and mirrored by role, and the author line is mono micro. Nothing here parses markdown: model output is an untrusted string, and a component that rendered it as markup would make every consumer one prompt away from an injection.",
       "interaction": "none. A message is a record."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/mobile-composer.json

@@ -143,10 +143,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/mobile-composer",
   "mdUrl": "/docs/components/mobile-composer.md",
   "jsonUrl": "/r/components/mobile-composer.json",
+  "whenToUse": [
+    "A composer on a phone — the field is 16px so iOS does not zoom on focus, and the quick actions scroll horizontally above it.",
+    "A run in flight: `running` swaps send for stop and suppresses Return-to-send."
+  ],
+  "whenNotToUse": [
+    "A desktop composer. The layout carries a home-indicator inset and collapses its quick actions when the keyboard is up."
+  ],
+  "commonMistakes": [
+    "Passing `actions` without `onAction`. The chips render disabled, because `actions` is required and the row would otherwise be inert — the same is true of `onAttach` and its control.",
+    "Guessing at the keyboard from the viewport instead of driving `keyboardOpen` from `onFocus`, which is the callback given for exactly that.",
+    "Leaving `running` false during a run, so Return still sends and the stop control never appears."
+  ],
   "specimens": [
     {
       "title": "MobileComposer",
@@ -158,6 +170,5 @@
       "note": "The same composer on a phone: a bottom sheet with thumb-sized targets, quick actions scrolling above the field, and a 16px input so iOS does not zoom when it takes focus. `keyboardOpen` is the whole layout switch — the quick actions and the home-indicator inset both belong to the state where the keyboard is down.",
       "interaction": "send becomes stop while a run is in flight, and Return stops sending — a second send during a stream is almost always a mistake, so the element refuses it rather than queueing it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/model-picker.json

@@ -67,10 +67,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/model-picker",
   "mdUrl": "/docs/components/model-picker.md",
   "jsonUrl": "/r/components/model-picker.json",
+  "whenToUse": [
+    "A picker over every model on offer, where price and capability are part of the choice."
+  ],
+  "whenNotToUse": [
+    "Two or three models in a settings row. This is the full list, and a family of one is a heading over a single row."
+  ],
+  "commonMistakes": [
+    "Grouping or sorting `models` by family before passing them. Families are derived from the entries and keep their first-seen order, so the order you pass is the order you get.",
+    "Passing `selectedId` without `onSelect` on a picker meant to change the model — the id alone only marks which one is active."
+  ],
   "specimens": [
     {
       "title": "ModelPicker",
@@ -82,6 +92,5 @@
       "note": "The full list rather than the rail: grouped by family, priced, and carrying what each one can actually do. This is the screen `ComposerModelTrigger` is a shortcut to, and the split is the point — the toolbar menu is for switching between models you already chose between, and this is where that choosing happens.",
       "interaction": "each row is `aria-pressed`, which is the honest role for a control that stays chosen rather than performing an action once."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/multi-select.json

@@ -227,7 +227,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "Several values out of a known set, each shown as a removable chip.",
+  "summary": "Several values out of a known set, each shown as a removable chip inside the field.",
   "examples": [
     {
       "title": "Usage",
@@ -235,10 +235,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/multi-select",
   "mdUrl": "/docs/components/multi-select.md",
   "jsonUrl": "/r/components/multi-select.json",
+  "whenToUse": [
+    "A selection the user needs to see in full: assignees, fixtures, channels.",
+    "Anywhere the size of the selection is information. Nine trusses render nine chips tall, so the field is honest about how much has been chosen."
+  ],
+  "whenNotToUse": [
+    "Values the product cannot enumerate. Use `TagsInput`, which commits whatever is typed.",
+    "Exactly one value. Use `Select` or `Combobox`.",
+    "A set small enough to show at once. A `CheckboxGroup` shows every option without an open-close cycle."
+  ],
+  "commonMistakes": [
+    "Giving the field a fixed height. It takes `min-h-control-*` on purpose; a fixed height reintroduces the hidden overflow the chips exist to avoid.",
+    "Collapsing the chips behind a `+6 more`. That hides the selection the user came to check."
+  ],
   "specimens": [
     {
       "title": "MultiSelect",
@@ -250,6 +263,5 @@
       "note": "Several values in one control, rendered as removable chips.",
       "interaction": "each chip's remove button has its own accessible name; Backspace removes the last one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/musical-time-input.json

@@ -121,10 +121,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/musical-time-input",
   "mdUrl": "/docs/components/musical-time-input.md",
   "jsonUrl": "/r/components/musical-time-input.json",
+  "whenToUse": [
+    "Any position or length in musical time."
+  ],
+  "whenNotToUse": [
+    "Wall-clock time. Use a time field."
+  ],
+  "commonMistakes": [
+    "Using a `NumberField` instead. That asks for 4.25 and means 'bar 2, beat 1, one sixteenth in' — a conversion the musician has to do in their head every time. Three segments, each stepping in its own musical unit, does it instead."
+  ],
   "specimens": [
     {
       "title": "MusicalTimeInput",
@@ -136,6 +145,5 @@
       "note": "`bars.beats.sixteenths` as three segments, time-signature aware, with the total-beats readout beside it.",
       "interaction": "arrow keys and the scroll wheel step the segment under the caret; Tab moves between segments and overflow carries into the next one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/navigation-menu.json

@@ -249,10 +249,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/navigation-menu",
   "mdUrl": "/docs/components/navigation-menu.md",
   "jsonUrl": "/r/components/navigation-menu.json",
+  "whenToUse": [
+    "A site header whose sections each hold several destinations.",
+    "Anywhere hover intent, a shared resizing popup and the landmark should come from the primitive rather than be rebuilt."
+  ],
+  "whenNotToUse": [
+    "Commands. Use a menu — this is navigation, and its rows are links.",
+    "A console's primary navigation. Use `Sidebar` or `AppBar`."
+  ],
+  "commonMistakes": [
+    "Giving it `role=\"menu\"`. A navigation menu is not a menu: that role tells a screen reader to expect commands and swallows the browser's own link affordances."
+  ],
   "specimens": [
     {
       "title": "NavigationMenu",
@@ -264,6 +275,5 @@
       "note": "A menu bar whose panels are portalled through the stamping contract, so they keep the theme and density of the island they were opened from.",
       "interaction": "hover opens after a short delay; Escape closes and returns focus to the trigger."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/node-card.json

@@ -124,10 +124,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/node-card",
   "mdUrl": "/docs/components/node-card.md",
   "jsonUrl": "/r/components/node-card.json",
+  "whenToUse": [
+    "Any React Flow node that should look like the rest of the console."
+  ],
+  "whenNotToUse": [
+    "A card in normal layout. Use `Card`."
+  ],
+  "commonMistakes": [
+    "Giving it a border. It is framed with an **outline** on purpose: React Flow is told a node's height up front, and a 1px border on each side makes the box 2px taller than the number the layout used — which is how node stacks end up overlapping by a hairline that grows with the stack."
+  ],
   "specimens": [
     {
       "title": "NodeCard",
@@ -139,6 +148,5 @@
       "note": "Framed with an outline rather than a border, so a node's rendered height is exactly the height the layout was told. The frame colour is the state: selected is `fg`, input is `info`, output and live are accent, idle is `fg-subtle`.",
       "interaction": "the expand toggle is a real button; the frame colour changes with `state`, never with hover alone."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/node-handle.json

@@ -64,10 +64,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/node-handle",
   "mdUrl": "/docs/components/node-handle.md",
   "jsonUrl": "/r/components/node-handle.json",
+  "whenToUse": [
+    "Every source and target on a `NodeCard`."
+  ],
+  "whenNotToUse": [
+    "Decoration. A handle advertises a connection that can be made."
+  ],
+  "commonMistakes": [
+    "Restyling it with classes. Everything visual is inline style deliberately: `.react-flow__handle` sets background, border and size from the library's own *unlayered* stylesheet, and any layered Tailwind utility loses to an unlayered rule of the same specificity."
+  ],
   "specimens": [
     {
       "title": "NodeHandle",
@@ -79,6 +88,5 @@
       "note": "A 9px connection pin in the system's tones, painted with inline `var(--cue-*)` references. That is deliberate: the library's own stylesheet is unlayered while Tailwind's utilities are layered, and a layered rule loses to an unlayered one of equal specificity whatever the import order. Shown on a node, because a handle only exists inside a canvas.",
       "interaction": "the hit area is larger than the dot; the pin resolves its colour from the live custom properties, so a theme switch repaints it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/number-field.json

@@ -111,10 +111,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/number-field",
   "mdUrl": "/docs/components/number-field.md",
   "jsonUrl": "/r/components/number-field.json",
+  "whenToUse": [
+    "Any number a user types or nudges at console density: a channel, a count, an offset.",
+    "Touch. Real buttons are hittable; native spinners are a pair of 4px arrows that only appear on hover."
+  ],
+  "whenNotToUse": [
+    "A value best chosen by feel across a range. Use `Slider`, or `ScrubInput` for a drag-to-change readout.",
+    "A code or an identifier that merely looks numeric. Use `Input` — stepping a serial number is meaningless."
+  ],
+  "commonMistakes": [
+    "Reaching for `<input type=\"number\">` for the spinners. They are unusable here, which is the reason this exists.",
+    "Validating range only on submit. Values typed out of range are clamped to `min`/`max` on blur, so the field has already moved.",
+    "Forgetting the modifier steps: Shift uses `largeStep`, Alt uses `smallStep`."
+  ],
   "specimens": [
     {
       "title": "NumberField",
@@ -126,6 +139,5 @@
       "note": "Stepper buttons on the chassis, with tabular figures so a changing digit does not shift the column.",
       "interaction": "arrow keys step, shift-arrow steps by ten, the scroll wheel is deliberately inert."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/number-ticker.json

@@ -47,10 +47,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/number-ticker",
   "mdUrl": "/docs/components/number-ticker.md",
   "jsonUrl": "/r/components/number-ticker.json",
+  "whenToUse": [
+    "A live count that moves while a run goes: tokens per second, rows read, files touched."
+  ],
+  "whenNotToUse": [
+    "A value that does not change. The whole effect is the digits rolling as `value` moves."
+  ],
+  "commonMistakes": [
+    "Passing a pre-formatted string. `value` is a number, and the digits are what roll.",
+    "Leaving the caption vague. `label` is required and is the mono line that says what the number counts."
+  ],
   "specimens": [
     {
       "title": "NumberTicker",
@@ -62,6 +72,5 @@
       "note": "A count that rolls rather than jumps: each digit is a column of ten sliding into place, so 47 to 48 moves one wheel and leaves the other alone. The whole figure is announced once as text, which is what keeps ten rolling columns from being read out as ten numbers.",
       "interaction": "none. The columns translate on a long ease and stop moving entirely under reduced motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/onboarding.json

@@ -80,10 +80,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/onboarding",
   "mdUrl": "/docs/components/onboarding.md",
   "jsonUrl": "/r/components/onboarding.json",
+  "whenToUse": [
+    "The first run of an assistant, where a reader needs to know what it is for before they type."
+  ],
+  "whenNotToUse": [
+    "A long tour. Three steps is usually the limit before it is skipped, and the final step's action reads Start instead of Next."
+  ],
+  "commonMistakes": [
+    "Leaving `onSkip` off. Always offer the way out — without it the only path is through every step.",
+    "Treating `index` as internal state. It is the caller's, and the last step is detected from it."
+  ],
   "specimens": [
     {
       "title": "Onboarding",
@@ -95,6 +105,5 @@
       "note": "First run: three moves that teach what this assistant is actually for, each with a prompt you could send verbatim. Showing beats describing, which is why every step carries an example rather than a screenshot. The dots are the progress and the final step's action reads `Start` instead of `Next`, so the end of the tour is visible from the second step.",
       "interaction": "skip is always offered and always in the same place — a tour with no way out is a modal wearing a card."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/otp-field.json

@@ -143,10 +143,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/otp-field",
   "mdUrl": "/docs/components/otp-field.md",
   "jsonUrl": "/r/components/otp-field.json",
+  "whenToUse": [
+    "A fixed-length code the user copies from somewhere else. The boxes say how long it is before they start typing.",
+    "Anywhere `one-time-code` autofill should work — paste, arrow keys and Backspace across slots all come from Base UI."
+  ],
+  "whenNotToUse": [
+    "A code of unknown or variable length. Use `Input`; empty boxes promise a length you cannot keep.",
+    "A password. Use `PasswordInput` — these slots are unmasked by design."
+  ],
+  "commonMistakes": [
+    "Rebuilding slot navigation by hand. Backspace across a slot boundary and paste-into-the-middle are the two cases that are always wrong in a hand-rolled version.",
+    "Setting `groupSize` without `separator`, so a grouped code reads as one run of digits."
+  ],
   "specimens": [
     {
       "title": "OTPField",
@@ -158,6 +170,5 @@
       "note": "Six slots in two groups. One value, six boxes: paste fills all of them.",
       "interaction": "Backspace walks back through the slots; arrow keys move without deleting."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/page-shell.json

@@ -101,7 +101,7 @@
     "--cue-text-title",
     "--cue-text-ui"
   ],
-  "summary": "A centred content column with a standard page header.",
+  "summary": "A centred content column with a standard page header, emitted only when something fills it.",
   "examples": [
     {
       "title": "Usage",
@@ -109,10 +109,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/page-shell",
   "mdUrl": "/docs/components/page-shell.md",
   "jsonUrl": "/r/components/page-shell.json",
+  "whenToUse": [
+    "A route that wants the measure and a title in one place.",
+    "A shell used purely for its measure — pass no header props and it adds no empty box and no stray rhythm."
+  ],
+  "whenNotToUse": [
+    "A page that already has a `TitleBar` or its own heading. Use `Container`."
+  ],
+  "commonMistakes": [
+    "Assuming it is the page's `<main>`. It renders a plain `<div>` on purpose — a split view holds more than one shell, and only one element per document may be `<main>`. Wrap it yourself where the semantics apply.",
+    "Passing an empty `title` to get the spacing. The header is conditional; an empty string still fills it."
+  ],
   "specimens": [
     {
       "title": "PageShell",
@@ -124,6 +135,5 @@
       "note": "The page measure: eyebrow, title, subtitle, actions and a body at one of four widths — 42rem, 54rem, 84rem, or uncapped.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/pagination.json

@@ -88,10 +88,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/pagination",
   "mdUrl": "/docs/components/pagination.md",
   "jsonUrl": "/r/components/pagination.json",
+  "whenToUse": [
+    "A result set the user needs to move through by position, and to jump within.",
+    "Anywhere `pageCount` may be one: it renders nothing then, on purpose."
+  ],
+  "whenNotToUse": [
+    "A stream with no end. Use infinite scroll or a load-more control.",
+    "A set small enough to show at once."
+  ],
+  "commonMistakes": [
+    "Hiding it yourself when there is one page. It already renders nothing — a control offering no choice says 'there is more here' when there is not.",
+    "Rebuilding the numbers as bare numerals. Every page number is a real button with a spoken name ('Page 3'), because the numeral alone is meaningless read aloud."
+  ],
   "specimens": [
     {
       "title": "Pagination",
@@ -103,6 +115,5 @@
       "note": "A windowed pager with gaps, generated by the exported `paginationRange`.",
       "interaction": "the current page is accent-soft and carries `aria-current`; the ends disable rather than disappear."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/panel-header.json

@@ -60,7 +60,7 @@
     "--cue-surface-1",
     "--cue-text-emphasis"
   ],
-  "summary": "The top bar of a {@link Panel}: title left, actions right, hairline under.",
+  "summary": "The top bar of a panel: title left, actions right, hairline under.",
   "examples": [
     {
       "title": "Usage",
@@ -68,10 +68,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/panel-header",
   "mdUrl": "/docs/components/panel-header.md",
   "jsonUrl": "/r/components/panel-header.json",
+  "whenToUse": [
+    "Any panel that needs a name, controls, or both.",
+    "Anywhere the header must line up horizontally with the rows beneath it — it uses the density row tokens, not its own values."
+  ],
+  "whenNotToUse": [
+    "A group heading inside a panel. Use `SectionHeader`.",
+    "The window bar. Use `TitleBar`."
+  ],
+  "commonMistakes": [
+    "Padding it with hand-picked values, which breaks the horizontal alignment with the rows at every density but the one it was tuned for."
+  ],
   "specimens": [
     {
       "title": "Panel / PanelHeader",
@@ -84,6 +95,5 @@
       "note": "The universal container: one hairline rim, no shadow, and a header that owns its own rule.",
       "interaction": "none. A panel is a box."
     }
-  ],
-  "todo": true
+  ]
 }