@cueplusplus/ui 0.13.0 → 0.14.1

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

package/manifest/components/password-input.json

@@ -143,7 +143,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A masked text field with a reveal control.",
+  "summary": "A masked text field with a reveal control that says what it does and which way it is.",
   "examples": [
     {
       "title": "Usage",
@@ -151,10 +151,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/password-input",
   "mdUrl": "/docs/components/password-input.md",
   "jsonUrl": "/r/components/password-input.json",
+  "whenToUse": [
+    "Any secret the user types and may need to check: a password, a token, a passphrase.",
+    "Anywhere a reveal is a genuine kindness — long generated secrets typed by hand."
+  ],
+  "whenNotToUse": [
+    "A secret that should never be shown. Pass `showReveal={false}`, or do not render one at all.",
+    "A config value that may reference an environment variable. Use `EnvVarInput`."
+  ],
+  "commonMistakes": [
+    "Replacing the reveal with a bare icon or a checkbox. It is a toggle button carrying `aria-pressed`, which is the one attribute that announces both what it does and its current state.",
+    "Painting the characters out with CSS instead of switching `type`. A password manager and the browser both key off the real type."
+  ],
   "specimens": [
     {
       "title": "PasswordInput",
@@ -166,6 +178,5 @@
       "note": "Input plus a reveal toggle carrying `aria-pressed`, so the state is spoken rather than implied by an icon swap.",
       "interaction": "the toggle is in the tab order after the field."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/permission-grant.json

@@ -95,10 +95,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/permission-grant",
   "mdUrl": "/docs/components/permission-grant.md",
   "jsonUrl": "/r/components/permission-grant.json",
+  "whenToUse": [
+    "A capability request from a named requester — filesystem access, network reach — where the answer outlives this one call.",
+    "The settled outcome: `scope` takes `session`, `always` or `denied` and the card shows what was decided rather than disappearing."
+  ],
+  "whenNotToUse": [
+    "A grant whose limits you cannot state. `reach` is required, and it is meant to carry what the grant does not cover as well as what it does."
+  ],
+  "commonMistakes": [
+    "Writing `reach` as a list of what is allowed only. Write the limits in too — that is what makes it a reach rather than a feature list.",
+    "Naming `capability` after the action rather than the capability. The point of this card, against a per-call approval, is that it grants a capability."
+  ],
   "specimens": [
     {
       "title": "PermissionGrant",
@@ -110,6 +121,5 @@
       "note": "The other half of the loop: granting a capability rather than approving one action. The reach is a list the caller writes, and the limits belong in it, because a grant a reader cannot bound is a grant they cannot give.",
       "interaction": "the three answers are Deny, this session and Always. Answer any card and it settles into the scope you chose."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/permission-scopes.json

@@ -164,10 +164,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/permission-scopes",
   "mdUrl": "/docs/components/permission-scopes.md",
   "jsonUrl": "/r/components/permission-scopes.json",
+  "whenToUse": [
+    "The approval card for one tool call, where a standing grant would write a rule and the reader deserves to be told which file it lands in.",
+    "A product with nowhere to persist a grant: omit `scopes` and the card asks, offering only once and no."
+  ],
+  "whenNotToUse": [
+    "As an overlay. There is no settled state — an answered permission is not a card any more, and every product that modelled approval as an overlay got the bug where the next message hides the answer."
+  ],
+  "commonMistakes": [
+    "Passing `onAlwaysAllow` without `scopes`. No scopes means no always-allow answer: a permanent grant that cannot say where it is saved is not one this element will offer.",
+    "Shortening or eliding a long rule before passing it. The label wraps instead, because a cut lands on the part that says how much is being granted — and `and 3 more` is a count, not an account.",
+    "Expecting `1`, `2` and `3` to answer from anywhere. The handler is the card's own `onKeyDown`, nothing is bound to the document, and the card never takes focus itself — a card that arrives mid-sentence and starts answering keystrokes is the bug the reference's 500ms delay exists to prevent."
+  ],
   "specimens": [
     {
       "title": "PermissionScopes",
@@ -179,6 +191,5 @@
       "note": "The one control in an agent UI whose label has to be computed, because what it grants is different every time it appears. `Yes, allow Bash(cue patch:*) for this project (just you)` is written from the rules it would add and the reach it would add them to, and the sentence under it names the file — permanently, not on hover. Nothing is shortened: the reference elides a long rule and strips the `:*` off a prefix rule, and both cuts land on the part that says how far the grant reaches, so this one wraps instead. When there are more rules than the sentence can name, every one of them is listed underneath, because `and 3 more` is a count and a count is not an account. The last card is what that costs: one directory of seventy-seven characters that a line breaker reads as a single word — it would take a hyphen if the name had one, and an underscored path has none — so the sentence breaks mid-path rather than running out of the card. It is also the card where the sentence is the whole account, since a grant naming one directory draws no rule list under it. The card after it moves the long word to the other two caller strings that can carry one — the subject beside the question, and the destination naming the file the grant is written into — and draws the destination both ways: the top card cycles it, so it is a button sized to its own text, and the bottom card has one destination and draws a span. Cycle the top one onto the project and the sentence breaks mid-path instead of leaving the card, which is the whole point of drawing where a permission is saved rather than hiding it behind a hover.",
       "interaction": "tab into the card and the numbers work — 1, 2, 3 fire whichever answers are rendered, built from the same list that drew them, and Escape denies. They are the card's own keys, not the document's: nothing here answers a digit typed into a composer somewhere above it, and a console that wants them to answer from anywhere routes them there itself. Press the dotted line to move the grant to another destination and watch the answer above it change with it: there is one resolved scope behind the label, the sentence and the callback, so they cannot disagree about what is being granted."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/piano-keyboard.json

@@ -129,10 +129,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/piano-keyboard",
   "mdUrl": "/docs/components/piano-keyboard.md",
   "jsonUrl": "/r/components/piano-keyboard.json",
+  "whenToUse": [
+    "Choosing a note range, where the keyboard itself is the clearest scale."
+  ],
+  "whenNotToUse": [
+    "A numeric range with no musical meaning. Use `Slider`."
+  ],
+  "commonMistakes": [
+    "Treating it as a display. It is a range control — the markers are draggable and the edges are arrow-key operable."
+  ],
   "specimens": [
     {
       "title": "PianoKeyboard",
@@ -144,6 +153,5 @@
       "note": "Exact key geometry from the shared layout module, in-range tinting, and draggable start and end markers.",
       "interaction": "each marker is a `role=slider` that announces the note it sits on, so the drag is a fast path rather than the only path."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/preset-section.json

@@ -64,7 +64,7 @@
     "--cue-text-micro",
     "--cue-text-ui"
   ],
-  "summary": "Section 1 — the four choices that are not token edits at all.",
+  "summary": "Section 1 of the configurator — the four choices that are not token edits at all.",
   "examples": [
     {
       "title": "Usage",
@@ -72,9 +72,17 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/preset-section",
   "mdUrl": "/docs/components/preset-section.md",
   "jsonUrl": "/r/components/preset-section.json",
-  "todo": true
+  "whenToUse": [
+    "Inside `ThemeConfigurator`. Preset, mode and density are *provider* state: picking one restamps the document and every portal under it."
+  ],
+  "whenNotToUse": [
+    "On its own. It edits the configurator's model, not yours."
+  ],
+  "commonMistakes": [
+    "Filing these with the colours. They are not token edits, which is why they live in their own section."
+  ]
 }

package/manifest/components/progress.json

@@ -94,10 +94,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/progress",
   "mdUrl": "/docs/components/progress.md",
   "jsonUrl": "/r/components/progress.json",
+  "whenToUse": [
+    "Work whose completion you can actually measure.",
+    "Work whose length you cannot: pass `value={null}` and the fill collapses to an indeterminate state."
+  ],
+  "whenNotToUse": [
+    "A short wait with no structure. Use `Spinner`.",
+    "Content arriving whose shape you know. Use `Skeleton`, which holds the layout too."
+  ],
+  "commonMistakes": [
+    "Easing the width transition. It is 120ms linear on purpose — a progress bar that eases is lying about its rate.",
+    "Faking determinate progress by animating to 90% and waiting. That is an indeterminate state wearing a number."
+  ],
   "specimens": [
     {
       "title": "Progress",
@@ -109,6 +121,5 @@
       "note": "Determinate and indeterminate, with an optional printed value.",
       "interaction": "the indeterminate track stills under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }