@cueplusplus/ui 0.13.0 → 0.14.1

package/manifest/components/avatar-group.json

@@ -55,7 +55,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "An overlapping stack of {@link Avatar}s with a `+N` overflow chip.",
+  "summary": "An overlapping stack of avatars with a `+N` overflow chip.",
   "examples": [
     {
       "title": "Usage",
@@ -63,10 +63,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/avatar-group",
   "mdUrl": "/docs/components/avatar-group.md",
   "jsonUrl": "/r/components/avatar-group.json",
+  "whenToUse": [
+    "Several participants where the count matters more than any one face: attendees, reviewers, a thread's contributors.",
+    "A fixed-width slot. `max` caps the faces and collapses the rest into `+N`, so the stack cannot grow past what you budgeted."
+  ],
+  "whenNotToUse": [
+    "One person. Use `Avatar` — the overlap ring is a visual cost with nothing to overlap.",
+    "A list people need to read or act on. A stack is a summary; give them a real list."
+  ],
+  "commonMistakes": [
+    "Setting `size` here and a different `size` on the `Avatar`s passed in. This prop sizes only the `+N` chip; match it to the avatars yourself.",
+    "Expecting `max` to default to something. Omit it and every avatar renders, however many arrive."
+  ],
   "specimens": [
     {
       "title": "AvatarGroup",
@@ -78,6 +90,5 @@
       "note": "Overlapping faces with an overflow count.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/avatar.json

@@ -85,7 +85,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "A round user/entity avatar sized off the density control ladder, so it lines up with the buttons and inputs on the same row.",
+  "summary": "A round user or entity avatar, sized off the density control ladder so it lines up with the buttons beside it.",
   "examples": [
     {
       "title": "Usage",
@@ -93,10 +93,23 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/avatar",
   "mdUrl": "/docs/components/avatar.md",
   "jsonUrl": "/r/components/avatar.json",
+  "whenToUse": [
+    "Identifying a person or an entity beside their name: a message author, an assignee, an audit row.",
+    "A slot that must hold something even when there is no image. `fallback` shows immediately and returns if the image errors, so the row never reflows."
+  ],
+  "whenNotToUse": [
+    "Several people at once. Use `AvatarGroup`, which handles the overlap and the `+N` overflow.",
+    "A state or a category rather than an identity. Use `StatusDot` or `Chip`."
+  ],
+  "commonMistakes": [
+    "Leaving `alt` empty. It is both the image's alt text and the source of the default initials, so an empty one costs the fallback as well as the screen reader.",
+    "Sizing with `className=\"h-8 w-8\"` instead of `size`, which stops the avatar tracking density and breaks its alignment with the controls on its row.",
+    "Assuming a missing `src` is an error case. Omit it deliberately and the fallback is the whole design."
+  ],
   "specimens": [
     {
       "title": "Avatar",
@@ -108,6 +121,5 @@
       "note": "Initials fall back when there is no image; the ring is drawn in the background colour so a pile reads as separate faces.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/background-inbox.json

@@ -59,10 +59,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/background-inbox",
   "mdUrl": "/docs/components/background-inbox.md",
   "jsonUrl": "/r/components/background-inbox.json",
+  "whenToUse": [
+    "Detached runs that finished away from the thread and now need pulling back into it.",
+    "A header count of what is ready, which is what needs the user rather than what is still in flight."
+  ],
+  "whenNotToUse": [
+    "A run happening in the thread you are already looking at.",
+    "A list where every row should be pressable. Running rows are not clickable."
+  ],
+  "commonMistakes": [
+    "Expecting the header to count everything. It counts what is ready, deliberately, not what is running.",
+    "Omitting `onCollect`, which leaves finished runs with no way back into the thread."
+  ],
   "specimens": [
     {
       "title": "BackgroundInbox",
@@ -74,6 +86,5 @@
       "note": "Work that left the conversation and is still going somewhere else. The header counts what is *ready* rather than what is in flight, because ready is the half that needs a person; a running row is not clickable at all, so there is nothing to press before there is something to collect.",
       "interaction": "a ready or failed row is a button and takes cue's focus ring; a running one is `disabled`, which is what makes the spinner mean wait rather than try again."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/band.json

@@ -76,7 +76,7 @@
     "--cue-border",
     "--cue-measure-prose"
   ],
-  "summary": "A full-bleed horizontal section: the page's rhythm, its separation, and a column at the measure.",
+  "summary": "A full-bleed horizontal section: a rule to the window's edge, a column at the measure.",
   "examples": [
     {
       "title": "Usage",
@@ -84,10 +84,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/band",
   "mdUrl": "/docs/components/band.md",
   "jsonUrl": "/r/components/band.json",
+  "whenToUse": [
+    "A page section that needs separation running edge to edge while its words stop at the reading measure.",
+    "Anywhere the page's vertical rhythm should come from one recipe rather than a per-section guess."
+  ],
+  "whenNotToUse": [
+    "Content inside an existing column. Use `Container` or `Stack`; a band inside a measure has no edge to reach.",
+    "A footer. Use `Footer`, which is built on this — the recipe exists once, and reimplementing it forks it."
+  ],
+  "commonMistakes": [
+    "Putting the separation on the inner column, which stops the rule at the measure and leaves the page looking unfinished at both margins."
+  ],
   "specimens": [
     {
       "title": "Band",
@@ -99,6 +110,5 @@
       "note": "A page's horizontal section: the rhythm, the separation and the column, all three off the style axis. Four separations — a rule, a ground, a full bleed with no column, and rhythm alone. Under no style set this is exactly what Footer draws above its links.",
       "interaction": "none; what changes it is the [data-style] attribute above it, not a pointer."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/breadcrumb.json

@@ -65,10 +65,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/breadcrumb",
   "mdUrl": "/docs/components/breadcrumb.md",
   "jsonUrl": "/r/components/breadcrumb.json",
+  "whenToUse": [
+    "A route nested deep enough that the path is not obvious from the page itself.",
+    "Anywhere the trail should have one visible end: the last crumb is the page you are on, never a link."
+  ],
+  "whenNotToUse": [
+    "A flat site, where every crumb but the last is the same one link.",
+    "A sequence of steps. Use `Stepper` — a breadcrumb is a location, not a progress."
+  ],
+  "commonMistakes": [
+    "Making the last crumb a link to the current page. It carries `aria-current=\"page\"` and full-strength ink precisely because it is not one.",
+    "Giving the separators text a screen reader will read. They are `aria-hidden`: announcing 'console slash patch slash universe 1' reads punctuation, not structure."
+  ],
   "specimens": [
     {
       "title": "Breadcrumb",
@@ -80,6 +92,5 @@
       "note": "Where you are, with `aria-hidden` punctuation between the crumbs and the last one marked current.",
       "interaction": "every crumb but the last is a link; the last is plain text."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/button-group.json

@@ -71,10 +71,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/button-group",
   "mdUrl": "/docs/components/button-group.md",
   "jsonUrl": "/r/components/button-group.json",
+  "whenToUse": [
+    "Actions that belong together: save and save-as, run and run-to-here.",
+    "Anywhere the shared rim is presentational only — each member stays independently reachable by Tab."
+  ],
+  "whenNotToUse": [
+    "A choice rather than actions. Use `ToggleGroup` (several or none) or `SegmentedControl` (exactly one), which carry the pressed-state ARIA a row of plain buttons must not fake."
+  ],
+  "commonMistakes": [
+    "Expecting roving focus. It owns no state and imposes none, because its members are actions.",
+    "Using it to show which option is selected, which is the case it explicitly does not handle."
+  ],
   "specimens": [
     {
       "title": "ButtonGroup",
@@ -86,6 +97,5 @@
       "note": "Buttons welded into one control, horizontally or vertically.",
       "interaction": "each button keeps its own focus ring; only the outer corners are rounded."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/calendar.json

@@ -37,7 +37,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "A month grid, on react-day-picker v10.",
+  "summary": "A month grid, on react-day-picker.",
   "examples": [
     {
       "title": "Usage",
@@ -45,10 +45,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/calendar",
   "mdUrl": "/docs/components/calendar.md",
   "jsonUrl": "/r/components/calendar.json",
+  "whenToUse": [
+    "Picking a day from a month the user wants to see — a schedule, a show date.",
+    "Inline, where a popover would be an extra click."
+  ],
+  "whenNotToUse": [
+    "A date the user already knows. Use `DateField`: typing `08172026` beats three clicks.",
+    "A range. Use `DateRangePicker`."
+  ],
+  "commonMistakes": [
+    "Re-deriving behaviour when upgrading. Selection modes, keyboard navigation, the ARIA grid wiring and the date maths are the library's; this layer supplies the token skin and nothing else.",
+    "Replacing a `classNames` slot rather than adding to it. Caller slots merge *over* the defaults."
+  ],
   "specimens": [
     {
       "title": "Calendar",
@@ -60,6 +72,5 @@
       "note": "react-day-picker's month grid, restyled from tokens. Speaks plain `Date`, because that is what a show file holds.",
       "interaction": "arrow keys walk the grid, Page Up and Page Down change month; the selected day is accent-soft, today is ringed."
     }
-  ],
-  "todo": true
+  ]
 }

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

@@ -40,10 +40,21 @@
   ],
   "summary": "The document's text, scrolling on its own, with a caret while it is still being written.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-body",
   "mdUrl": "/docs/components/canvas-split-body.md",
   "jsonUrl": "/r/components/canvas-split-body.json",
+  "whenToUse": [
+    "The scrolling text of the document half, under its header.",
+    "A document still streaming, where `writing` trails a caret after the last line."
+  ],
+  "whenNotToUse": [
+    "The document's title, version or save state, which sit in the header above it."
+  ],
+  "commonMistakes": [
+    "Leaving `writing` true after the last line has landed, so a finished document keeps a caret at the end of it.",
+    "Adding your own scroll container around it. It scrolls on its own."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -61,6 +72,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-document.json

@@ -29,10 +29,19 @@
   ],
   "summary": "The document half of the split: the header, and the body under it.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-document",
   "mdUrl": "/docs/components/canvas-split-document.md",
   "jsonUrl": "/r/components/canvas-split-document.json",
+  "whenToUse": [
+    "Wrapping the header and the body so the document sits opposite the conversation rail."
+  ],
+  "whenNotToUse": [
+    "Anything on the conversation side of the split."
+  ],
+  "commonMistakes": [
+    "Making it the scroll container. The body scrolls on its own beneath the header."
+  ],
   "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-header.json

@@ -71,10 +71,21 @@
   ],
   "summary": "What the document is, which version this is, and whether it has been written down yet — with copy and close beside them.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-header",
   "mdUrl": "/docs/components/canvas-split-header.md",
   "jsonUrl": "/r/components/canvas-split-header.json",
+  "whenToUse": [
+    "Naming the document on screen and stating which revision is showing.",
+    "Giving the canvas a dismiss path, through `onClose`."
+  ],
+  "whenNotToUse": [
+    "Document text, which belongs in the body under it."
+  ],
+  "commonMistakes": [
+    "Rendering your own saved indicator. `saved` already swaps the status between editing and saved.",
+    "Passing `version` as a string. It is a number — which revision is on screen."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -92,6 +103,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-line.json

@@ -40,10 +40,21 @@
   ],
   "summary": "One line of the document, arriving as it is written.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-line",
   "mdUrl": "/docs/components/canvas-split-line.md",
   "jsonUrl": "/r/components/canvas-split-line.json",
+  "whenToUse": [
+    "Each line of a streamed document, so lines arrive one at a time rather than as one block.",
+    "A section title inside the document, with `heading`."
+  ],
+  "whenNotToUse": [
+    "A block of prose you want reflowed as one unit. This is one line."
+  ],
+  "commonMistakes": [
+    "Styling a line to look like a heading by hand instead of setting `heading`, which is what sets it apart.",
+    "Pushing a whole block of text through one line, which loses the line-by-line arrival the element exists for."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -61,6 +72,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-message.json

@@ -44,10 +44,21 @@
   ],
   "summary": "One turn inside the rail — a filled bubble for the person, plain text for the model.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/canvas-split-message",
   "mdUrl": "/docs/components/canvas-split-message.md",
   "jsonUrl": "/r/components/canvas-split-message.json",
+  "whenToUse": [
+    "Each conversation turn in the narrowed rail beside the document.",
+    "Styling turns from outside, using the `data-speaker` attribute it emits."
+  ],
+  "whenNotToUse": [
+    "Content on the document side of the split."
+  ],
+  "commonMistakes": [
+    "Looking for a `role` prop. It is deliberately called `speaker` so the ARIA attribute stays yours to set.",
+    "Drawing your own bubble around a user turn. `speaker=\"user\"` already sits right in a bubble, and assistant turns run flush left."
+  ],
   "specimens": [
     {
       "title": "CanvasSplit",
@@ -65,6 +76,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-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
+  ]
 }