@cueplusplus/ui 0.14.0 → 0.14.1

package/manifest/components/drawer.json

@@ -176,7 +176,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A swipe-dismissable edge panel — the touch-first cousin of {@link Sheet }.",
+  "summary": "A swipe-dismissable edge panel — the touch-first cousin of `Sheet`.",
   "examples": [
     {
       "title": "Usage",
@@ -184,10 +184,20 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/drawer",
   "mdUrl": "/docs/components/drawer.md",
   "jsonUrl": "/r/components/drawer.json",
+  "whenToUse": [
+    "Touch surfaces, where dragging a panel away is the natural dismissal.",
+    "Stacked panels: nested-drawer stacking comes from the primitive."
+  ],
+  "whenNotToUse": [
+    "Pointer-first consoles. Use `Sheet`."
+  ],
+  "commonMistakes": [
+    "Setting the edge and the gesture separately. `swipeDirection` picks both together on purpose, so a drawer can never be dragged in a direction that does not dismiss it."
+  ],
   "specimens": [
     {
       "title": "Drawer",
@@ -199,6 +209,5 @@
       "note": "The touch-first sheet: a grab handle and a swipe direction.",
       "interaction": "drag the handle to dismiss; on a pointer device it behaves as an ordinary sheet."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/edit-message.json

@@ -111,10 +111,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/edit-message",
   "mdUrl": "/docs/components/edit-message.md",
   "jsonUrl": "/r/components/edit-message.json",
+  "whenToUse": [
+    "Editing a message already in the transcript, where the cost — the replies after it — should be stated before sending.",
+    "A turn that reads as a plain bubble until it is clicked, with `onStartEdit` opening the composer."
+  ],
+  "whenNotToUse": [
+    "Composing a new message. This swaps between a resting bubble and an edit composer for a turn that already exists."
+  ],
+  "commonMistakes": [
+    "Expecting `onCancel` to put the old text back. Restore the original yourself.",
+    "Passing `discardedReplies={0}` while replies exist. The warning hides at zero, which silently removes the one thing the element is for."
+  ],
   "specimens": [
     {
       "title": "EditMessage",
@@ -126,6 +137,5 @@
       "note": "Rewriting a turn you already sent, told up front what it throws away. The count is the point: editing the third message of a thread discards everything after it, and a control that hid that would be a data-loss trap wearing a pencil icon.",
       "interaction": "resting, the whole bubble is the button that starts an edit. Editing, the textarea is labelled and takes cue's focus ring; Send leads and Cancel is a ghost."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-command-palette.json

@@ -102,10 +102,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-command-palette",
   "mdUrl": "/docs/components/elements-command-palette.md",
   "jsonUrl": "/r/components/elements-command-palette.json",
+  "whenToUse": [
+    "A keystroke-away list of every runnable command in the app.",
+    "A list where the arrow keys and Enter should already work, because the element owns the key handling."
+  ],
+  "whenNotToUse": [
+    "A menu whose grouping you want to control. Groups are derived from the entries and keep first-seen order."
+  ],
+  "commonMistakes": [
+    "Adding your own arrow-key and Enter handling. The element owns the key handling and reports where it landed through `onActiveChange`.",
+    "Treating `activeId` as the element's own state. It stays yours to hold; the element only reports the move."
+  ],
   "specimens": [
     {
       "title": "ElementsCommandPalette",
@@ -117,6 +128,5 @@
       "note": "Everything the console can do, one keystroke away and grouped by where it acts. The element owns the arrow keys and reports where they landed, so the highlighted row stays the caller's state — and `aria-activedescendant` moves the highlight without moving focus, which is what keeps typing and walking the list the same gesture. Groups are derived from the commands and keep first-seen order, so the palette cannot be re-ordered by accident.",
       "interaction": "the input is a combobox over a listbox; arrows walk, Enter runs, and a query that filters the active row out drops the descendant reference rather than pointing at nothing."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-composer.json

@@ -45,10 +45,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-composer",
   "mdUrl": "/docs/components/elements-composer.md",
   "jsonUrl": "/r/components/elements-composer.json",
+  "whenToUse": [
+    "A full message input that needs attachments, slash commands, mentions, a model picker, voice and context usage together.",
+    "A composer that has to show how much of the context window is gone alongside the input itself."
+  ],
+  "whenNotToUse": [
+    "A screen that only needs the shape of a composer rather than a working one."
+  ],
+  "commonMistakes": [
+    "Putting `ComposerInput` outside `ComposerBar`. The bar is the surface the input, the attachments and the toolbar sit on.",
+    "Hanging controls straight off `ComposerToolbar`. They go in `ComposerActions` clusters, one at each end."
+  ],
   "specimens": [
     {
       "title": "ElementsComposer / ComposerBar / ComposerInput / ComposerToolbar",
@@ -66,6 +77,5 @@
       "note": "The composer assembled from its parts, which is the only way it exists — there is no root that configures it. `ElementsComposer` positions, `ComposerBar` is the paper, and everything between the input and the send button is a facet you either compose in or leave out, so a composer with no attachments carries no attachment code. `ComposerSend` is dim while the input is empty and becomes a stop square while the model is streaming; it is the same button either way, because there is never a moment when both are wanted.",
       "interaction": "`ComposerAttachButton` disables itself when no handler is given rather than rendering a control that does nothing. The send button is labelled by state — `Send message` or `Stop generating` — so the swap is announced and not just drawn."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-data-table.json

@@ -55,10 +55,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-data-table",
   "mdUrl": "/docs/components/elements-data-table.md",
   "jsonUrl": "/r/components/elements-data-table.json",
+  "whenToUse": [
+    "A short comparison the model produced as part of an answer — model name, context window and cost."
+  ],
+  "whenNotToUse": [
+    "A sortable, paginated dataset. `rows` is a small `ModelUsage[]` shaped for an answer."
+  ],
+  "commonMistakes": [
+    "Holding `cycle` constant and expecting the row entrance to replay. It is an identity key that remounts the body."
+  ],
   "specimens": [
     {
       "title": "ElementsDataTable",
@@ -70,6 +79,5 @@
       "note": "A small table the model can answer with directly — three columns, no sorting, no virtualisation, no header menu. It is `ElementsDataTable` because the package already sells a real one at `@cueplusplus/ui/instruments`: that one is a data grid, this one is a paragraph shaped like a grid, and the rename keeps a consumer from reaching for the wrong one.",
       "interaction": "none. `cycle` remounts the body, so a new answer's rows stagger in rather than mutating in place."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elements-timeline.json

@@ -57,10 +57,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elements-timeline",
   "mdUrl": "/docs/components/elements-timeline.md",
   "jsonUrl": "/r/components/elements-timeline.json",
+  "whenToUse": [
+    "Past and scheduled events shown together on one axis.",
+    "A run where the scheduled events should be visible before they resolve, with `visibleCount` moving as they do."
+  ],
+  "whenNotToUse": [
+    "Work that branches and rejoins rather than running along a single axis."
+  ],
+  "commonMistakes": [
+    "Passing only the resolved events. `events` holds past and scheduled together, and `visibleCount` says how many have resolved.",
+    "Ordering by resolution rather than chronologically. The events are expected in chronological order."
+  ],
   "specimens": [
     {
       "title": "ElementsTimeline",
@@ -72,6 +83,5 @@
       "note": "Events on one axis, with what already happened and what is still coming in the same list — `past`, `now` and `future` are one union, so a schedule and a history are the same component. It publishes as `ElementsTimeline` because cue already sells a `Timeline`; the spec asked for `ToolTimeline`, which turned out to be the next bench's name.",
       "interaction": "none. The now marker is the only one that pulses, and it holds still for a reader who asked for less motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/elicitation-form.json

@@ -110,10 +110,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/elicitation-form",
   "mdUrl": "/docs/components/elicitation-form.md",
   "jsonUrl": "/r/components/elicitation-form.json",
+  "whenToUse": [
+    "A server that stopped part-way through a tool call and needs fields filled before it can continue."
+  ],
+  "whenNotToUse": [
+    "A form of your own design. `fields` is the schema the server sent, already resolved to display values.",
+    "A request for permission to run something rather than for data."
+  ],
+  "commonMistakes": [
+    "Leaving `state=\"request\"` after the user answered. Accepted and declined swap the action row for the outcome.",
+    "Rewriting `message` in your own voice. It is why the input is needed, in the server's words."
+  ],
   "specimens": [
     {
       "title": "ElicitationForm",
@@ -125,6 +136,5 @@
       "note": "A server pausing mid-tool-call to ask for the fields it still needs — MCP's elicitation, drawn. The fields arrive already resolved to display values, so the element renders a schema without ever having parsed one, and `state` swaps the two buttons for the outcome the moment the user answers. Declining is a first-class answer here, not a dismissal.",
       "interaction": "each field's control is chosen by its `kind` — a value chip, a row of options, or a switch — and the required ones are marked on the label rather than announced only on failure."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state-composer.json

@@ -47,10 +47,19 @@
   ],
   "summary": "A composer-shaped invitation under the suggestions.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state-composer",
   "mdUrl": "/docs/components/empty-state-composer.md",
   "jsonUrl": "/r/components/empty-state-composer.json",
+  "whenToUse": [
+    "The blank-thread screen whose real composer lives somewhere else."
+  ],
+  "whenNotToUse": [
+    "A working input. It is a display rather than one — `placeholder` is a string and send takes a handler."
+  ],
+  "commonMistakes": [
+    "Omitting `onSend` and expecting a live control. Without a handler the send control renders disabled."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -66,6 +75,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state-greeting.json

@@ -25,10 +25,19 @@
   ],
   "summary": "The one line at the top of a blank thread.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state-greeting",
   "mdUrl": "/docs/components/empty-state-greeting.md",
   "jsonUrl": "/r/components/empty-state-greeting.json",
+  "whenToUse": [
+    "The single opening line on an empty thread."
+  ],
+  "whenNotToUse": [
+    "A second line of copy beneath it. This is the one a screen reader lands on."
+  ],
+  "commonMistakes": [
+    "Wrapping it in a heading of your own, which nests a heading inside a heading."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -44,6 +53,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state-suggestion.json

@@ -36,10 +36,19 @@
   ],
   "summary": "One thing worth asking, as a pill.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state-suggestion",
   "mdUrl": "/docs/components/empty-state-suggestion.md",
   "jsonUrl": "/r/components/empty-state-suggestion.json",
+  "whenToUse": [
+    "Each starter prompt offered on a blank thread."
+  ],
+  "whenNotToUse": [
+    "A standing control. It is a suggestion pill for the blank-thread screen."
+  ],
+  "commonMistakes": [
+    "Omitting `index`. It staggers the entrance so the pills arrive left to right rather than all at once."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -55,6 +64,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state-suggestions.json

@@ -25,10 +25,19 @@
   ],
   "summary": "The row the suggestion pills wrap in.",
   "examples": [],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state-suggestions",
   "mdUrl": "/docs/components/empty-state-suggestions.md",
   "jsonUrl": "/r/components/empty-state-suggestions.json",
+  "whenToUse": [
+    "Holding the suggestion pills so they wrap as one row."
+  ],
+  "whenNotToUse": [
+    "Anything other than the suggestion pills."
+  ],
+  "commonMistakes": [
+    "Laying the pills out with a flex row of your own, which drops the wrapping the element already provides."
+  ],
   "specimens": [
     {
       "title": "ChatEmptyState",
@@ -44,6 +53,5 @@
       "note": "The first screen, composed rather than configured: a greeting, some ways in, and a composer-shaped invitation. `EmptyStateComposer` is a display and not a working input — the placeholder is a string and send takes a handler — for the screen whose real composer is somewhere else. The suggestions stagger their entrance from `index`, so the row arrives left to right instead of all at once. Named `ChatEmptyState` because cue already publishes a layout `EmptyState`.",
       "interaction": "each suggestion is a button with cue's focus ring; the greeting is an `h2`, so a screen reader lands on the sentence rather than the pills."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/empty-state.json

@@ -83,7 +83,7 @@
     "--cue-text-emphasis",
     "--cue-text-ui"
   ],
-  "summary": "The \"there is nothing here\" panel body.",
+  "summary": "The 'there is nothing here' panel body — a report, not an alarm.",
   "examples": [
     {
       "title": "Usage",
@@ -91,10 +91,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/empty-state",
   "mdUrl": "/docs/components/empty-state.md",
   "jsonUrl": "/r/components/empty-state.json",
+  "whenToUse": [
+    "A list, table or panel with no rows, where the reader needs to know why and what to do next.",
+    "Anywhere an action would help: `action` is the slot for the one thing that fills the emptiness."
+  ],
+  "whenNotToUse": [
+    "An error. Emptiness is a state; a failure needs its own tone and a way to retry.",
+    "Loading. Use `Skeleton` or `Spinner` — an empty state says nothing is coming."
+  ],
+  "commonMistakes": [
+    "Colouring it to draw attention. It uses the muted ramp throughout and takes its emphasis from position; an alarming empty state reports a problem that is not there.",
+    "Putting the meaning in the icon. The icon is decorative — the title carries it, so a screen reader hears one sentence instead of a shrug."
+  ],
   "specimens": [
     {
       "title": "EmptyState",
@@ -106,6 +118,5 @@
       "note": "The standard empty copy, from lib/samples.tsx. Same words everywhere in the app.",
       "interaction": "the action is an ordinary Button and behaves like one."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/end-of-turn-summary.json

@@ -69,10 +69,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/end-of-turn-summary",
   "mdUrl": "/docs/components/end-of-turn-summary.md",
   "jsonUrl": "/r/components/end-of-turn-summary.json",
+  "whenToUse": [
+    "The closing line of a turn, saying what it came to.",
+    "A turn whose result is not a diff at all, using `label` to replace the built line: `2 cues written`, `Nothing to change`."
+  ],
+  "whenNotToUse": [
+    "Anywhere you want review, keep or reject buttons. It is a rollup, not a control — those belong to a bar above the composer that acts on the whole run.",
+    "A turn that read files and wrote nothing but which you want reported as two zeroes. It says `No files changed` and stops."
+  ],
+  "commonMistakes": [
+    "Adding per-turn action buttons beside it. A per-turn row with those buttons on it is a row that can be pressed after the next turn has already changed the same files.",
+    "Passing `additions={0}` and `deletions={0}` to force the counts out. The counts are drawn only when there are some."
+  ],
   "specimens": [
     {
       "title": "EndOfTurnSummary",
@@ -84,6 +96,5 @@
       "note": "What the turn came to, in one line. A rollup and not a control: review, keep and reject act on the whole run and belong above the composer, where they cannot be pressed after the next turn has already changed the same files. The + and − are CodeDiff's glyphs, so one transcript never shows two conventions for the same number, and a turn that changed nothing says so instead of saying it with two zeroes.",
       "interaction": "none. It is a sentence with two tinted numbers in it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/env-var-input.json

@@ -166,7 +166,7 @@
     "--cue-text-ui",
     "--cue-warn"
   ],
-  "summary": "A config value that may be a literal *or* a reference to an environment variable — and looks unmistakably different in each case.",
+  "summary": "A config value that may be a literal or an `env(NAME)` reference — and looks unmistakably different in each case.",
   "examples": [
     {
       "title": "Usage",
@@ -174,10 +174,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/env-var-input",
   "mdUrl": "/docs/components/env-var-input.md",
   "jsonUrl": "/r/components/env-var-input.json",
+  "whenToUse": [
+    "Any config screen where some values are secrets and some name where a secret comes from.",
+    "Anywhere the difference decides whether a value is safe to screenshot, commit or paste into a ticket."
+  ],
+  "whenNotToUse": [
+    "A secret typed directly with no indirection. Use `PasswordInput`.",
+    "Ordinary configuration with no environment indirection. Use `Input`."
+  ],
+  "commonMistakes": [
+    "Rendering references as ordinary text. The warn-toned pill is the entire point: a screen of identical text boxes gives no way to tell the key from the pointer to the key.",
+    "Treating `secret` as encryption. It masks a literal on screen; it does nothing to how the value is stored or sent."
+  ],
   "specimens": [
     {
       "title": "EnvVarInput",
@@ -189,6 +201,5 @@
       "note": "A literal value and an `env(NAME)` reference are different things, so they do not look the same: the reference swaps to an amber token pill.",
       "interaction": "the mode switch is a button; typing `env(` in the field is enough to flip it."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/error-state.json

@@ -73,10 +73,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/error-state",
   "mdUrl": "/docs/components/error-state.md",
   "jsonUrl": "/r/components/error-state.json",
+  "whenToUse": [
+    "A failed request inside a surface, where the retry should sit with the failure rather than interrupt."
+  ],
+  "whenNotToUse": [
+    "A failure with nothing to try again. `onRetry` is required.",
+    "A decision that must block everything until it is answered. This is deliberately not a modal."
+  ],
+  "commonMistakes": [
+    "Rendering your own spinner while retrying. `retrying` swaps the banner to a spinning Retrying status instead of the error.",
+    "Putting the whole message in `title`. `detail` is the supporting line that explains what went wrong."
+  ],
   "specimens": [
     {
       "title": "ErrorState",
@@ -88,6 +99,5 @@
       "note": "A failure banner, not a modal: it sits in the flow where the answer would have been, says what broke and what to do, and leaves the rest of the page alone. Retrying is a different element entirely rather than a disabled button — `role='alert'` while it is a failure, `role='status'` while it is trying again, which is the difference between interrupting a screen reader and not.",
       "interaction": "Retry is a named button that tints on hover. The retrying state has no control at all, because there is nothing to press while it works."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/export-dialog.json

@@ -93,9 +93,17 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/export-dialog",
   "mdUrl": "/docs/components/export-dialog.md",
   "jsonUrl": "/r/components/export-dialog.json",
-  "todo": true
+  "whenToUse": [
+    "Handing a tuned theme to code, in whichever of the four shapes the consumer needs."
+  ],
+  "whenNotToUse": [
+    "Exporting anything but the configurator's overrides. All four outputs are generated from them."
+  ],
+  "commonMistakes": [
+    "Re-deriving a value before export. Nothing here re-derives: the CSS output is literally the stylesheet on the page, which is what makes it trustworthy."
+  ]
 }

package/manifest/components/eyebrow.json

@@ -31,7 +31,7 @@
     "--cue-space-2",
     "--cue-text-label"
   ],
-  "summary": "The small accent kicker that sits above a title: `// PATCH`.",
+  "summary": "The small accent kicker above a title: `// PATCH`.",
   "examples": [
     {
       "title": "Usage",
@@ -39,10 +39,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/eyebrow",
   "mdUrl": "/docs/components/eyebrow.md",
   "jsonUrl": "/r/components/eyebrow.json",
+  "whenToUse": [
+    "Naming the category a title belongs to, where the title alone would not say it.",
+    "Anywhere the accent should carry pure typography — this is the one place the system spends it that way."
+  ],
+  "whenNotToUse": [
+    "A status. Use `Chip`, which carries the tone vocabulary.",
+    "A second heading. An eyebrow is a kicker, not a level in the outline."
+  ],
+  "commonMistakes": [
+    "Typing the slashes into the text. They are `aria-hidden` and `select-none` for a reason — a screen reader should read \"patch\", and a copy-paste of the page should not carry punctuation that was only ever decoration."
+  ],
   "specimens": [
     {
       "title": "Eyebrow",
@@ -54,6 +65,5 @@
       "note": "The `//` motif from the brand site, in mono micro.",
       "interaction": "none."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/feedback-dialog.json

@@ -113,10 +113,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/feedback-dialog",
   "mdUrl": "/docs/components/feedback-dialog.md",
   "jsonUrl": "/r/components/feedback-dialog.json",
+  "whenToUse": [
+    "Collecting the reason behind a negative rating, with optional free text alongside it."
+  ],
+  "whenNotToUse": [
+    "A single-choice survey. More than one reason may be picked at once."
+  ],
+  "commonMistakes": [
+    "Writing long reason strings. Keep them short enough to scan in one line.",
+    "Rendering your own thank-you. `sent` replaces the whole form with an acknowledgement once the report is filed.",
+    "Requiring `note` before submit. The free-text detail is always optional."
+  ],
   "specimens": [
     {
       "title": "FeedbackDialog",
@@ -128,6 +139,5 @@
       "note": "A thumbs-down that asks why, so the signal arrives with a reason attached. The reasons are chips rather than a select because more than one is usually true, and the note is marked optional in the header — a feedback form that demands prose collects nothing. Sending replaces the whole form with an acknowledgement.",
       "interaction": "each chip is `aria-pressed`. The acknowledgement lives in a `status` live region mounted from the start and empty until it is not — a region created together with its text is the case a screen reader is free to miss."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/field-description.json

@@ -35,7 +35,7 @@
     "--cue-text-label",
     "--cue-text-micro"
   ],
-  "summary": "Quiet helper text under a control, published to assistive tech as the control's `aria-describedby` target.",
+  "summary": "Quiet helper text under a control, published as the control's `aria-describedby` target.",
   "examples": [
     {
       "title": "Usage",
@@ -43,10 +43,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/field-description",
   "mdUrl": "/docs/components/field-description.md",
   "jsonUrl": "/r/components/field-description.json",
+  "whenToUse": [
+    "A constraint or a consequence the label cannot carry: the format expected, what the value affects.",
+    "Text that should be read out after the control's name rather than as part of it."
+  ],
+  "whenNotToUse": [
+    "An error. Use `FieldError` — a description is permanent and an error is a state.",
+    "A whole paragraph. If it needs that much, the field needs a different design."
+  ],
+  "commonMistakes": [
+    "Putting the requirement only here and not in validation, so a screen reader hears the rule but nothing enforces it.",
+    "Repeating the label in other words, which makes every field announce twice."
+  ],
   "specimens": [
     {
       "title": "Field / FieldLabel / FieldDescription / FieldError",
@@ -61,6 +73,5 @@
       "note": "The labelling wrapper. Base UI generates the ids, so the label names the control with no htmlFor bookkeeping, and `invalid` stamps the whole subtree.",
       "interaction": "clicking the label focuses the control; the error line is announced when it appears."
     }
-  ],
-  "todo": true
+  ]
 }