@cueplusplus/ui 0.13.0 → 0.14.1

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

package/manifest/components/field-error.json

@@ -56,7 +56,7 @@
     "--cue-text-label",
     "--cue-text-micro"
   ],
-  "summary": "The error line under a control.",
+  "summary": "The error line under a control. Driven by Standard Schema issues, or by native validity.",
   "examples": [
     {
       "title": "Usage",
@@ -64,10 +64,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/field-error",
   "mdUrl": "/docs/components/field-error.md",
   "jsonUrl": "/r/components/field-error.json",
+  "whenToUse": [
+    "Showing a parse failure: pass `issues` from `schema.safeParse(x).issues` and the component owns visibility.",
+    "Keying off the browser's own `ValidityState`: pass `match` plus `children`."
+  ],
+  "whenNotToUse": [
+    "A permanent constraint. That is `FieldDescription`; an error should appear only when something is wrong.",
+    "A form-level failure. This belongs to one control."
+  ],
+  "commonMistakes": [
+    "Passing both `issues` and `match`. They are mutually exclusive by design — pick the source of truth.",
+    "Rendering it conditionally yourself when using `issues`. The component already decides when to show; wrapping it in your own guard fights it."
+  ],
   "specimens": [
     {
       "title": "Field / FieldLabel / FieldDescription / FieldError",
@@ -82,6 +94,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
+  ]
 }

package/manifest/components/field-label.json

@@ -35,7 +35,7 @@
     "--cue-text-label",
     "--cue-text-micro"
   ],
-  "summary": "The name of a field: mono, uppercase, tracked out, one rung below body text.",
+  "summary": "The name of a field: a real `<label>`, wired to its control.",
   "examples": [
     {
       "title": "Usage",
@@ -43,10 +43,22 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/field-label",
   "mdUrl": "/docs/components/field-label.md",
   "jsonUrl": "/r/components/field-label.json",
+  "whenToUse": [
+    "Every control inside a `Field`. Clicking the label focuses — or toggles — the control it names.",
+    "Anywhere a visible name is wanted instead of an `aria-label`, which is the better default because sighted users need the name too."
+  ],
+  "whenNotToUse": [
+    "Helper text. Use `FieldDescription`, which becomes the `aria-describedby` target.",
+    "An error. Use `FieldError`."
+  ],
+  "commonMistakes": [
+    "Using a `<div>` styled to look like a label, which breaks click-to-focus and leaves the control unnamed.",
+    "Labelling a group of controls with one of these. A `RadioGroup` or `CheckboxGroup` needs a group name, not a label pointing at one member."
+  ],
   "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
+  ]
 }

package/manifest/components/file-tree.json

@@ -76,10 +76,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/file-tree",
   "mdUrl": "/docs/components/file-tree.md",
   "jsonUrl": "/r/components/file-tree.json",
+  "whenToUse": [
+    "The full set of files a run changed, with per-file churn and a total across them.",
+    "A live run where files land one at a time, by raising `visibleCount`."
+  ],
+  "whenNotToUse": [
+    "One file's line-by-line change."
+  ],
+  "commonMistakes": [
+    "Passing nested `children` arrays. `nodes` is a flat list in display order and nesting comes from each node's depth.",
+    "Rendering the whole tree at once during a live run. `visibleCount` is what you raise as the run touches more files."
+  ],
   "specimens": [
     {
       "title": "FileTree",
@@ -91,6 +102,5 @@
       "note": "Everything a run touched, with the churn per file. The list is flat and the nesting is `depth`, which is what lets a row appear the moment the agent reports it rather than after its folder is complete.",
       "interaction": "rows highlight on hover to keep the eye on one line; nothing here is clickable, because the tree reports rather than navigates."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/file-upload.json

@@ -176,7 +176,7 @@
     "--cue-text-label",
     "--cue-text-ui"
   ],
-  "summary": "A drop zone with a file list under it.",
+  "summary": "A drop zone with a file list under it — and the zone is a real button.",
   "examples": [
     {
       "title": "Usage",
@@ -184,10 +184,21 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/file-upload",
   "mdUrl": "/docs/components/file-upload.md",
   "jsonUrl": "/r/components/file-upload.json",
+  "whenToUse": [
+    "Any upload. Dropping is the mouse affordance; pressing Enter on the focused zone opens the file dialog.",
+    "Uploads with rules: `accept`, `maxSize` and `maxFiles` are enforced before `onFilesAccepted`."
+  ],
+  "whenNotToUse": [
+    "A single file chosen rarely, where a plain button reads better than a target."
+  ],
+  "commonMistakes": [
+    "Rebuilding it as a `<div>` with a drop handler. A zone that only accepts drops is unusable without a pointer (WCAG 2.1.1), and it is the single most common defect in hand-rolled uploaders.",
+    "Handling only `onFilesAccepted`. Rejections are where the user learns the rule — `onFilesRejected` is not optional in practice."
+  ],
   "specimens": [
     {
       "title": "FileUpload",
@@ -199,6 +210,5 @@
       "note": "A drop zone that is also a button, so a keyboard can reach it. Rejections say which rule they broke.",
       "interaction": "the zone lights on drag-over; Enter or Space opens the file dialog."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/flow-background.json

@@ -28,10 +28,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/flow-background",
   "mdUrl": "/docs/components/flow-background.md",
   "jsonUrl": "/r/components/flow-background.json",
+  "whenToUse": [
+    "Behind any flow canvas."
+  ],
+  "whenNotToUse": [
+    "Outside React Flow."
+  ],
+  "commonMistakes": [
+    "Passing `color`. Leave it unset — it writes `--xy-background-pattern-color-props`, which outranks the theme map, so passing a colour is how you opt *out* of theming rather than how you theme it."
+  ],
   "specimens": [
     {
       "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
@@ -45,6 +54,5 @@
       "note": "The hook returns the `--xy-*` token map plus stable `edgeTypes` and `defaultEdgeOptions` identities. Every part also publishes the map on its own root, so the group is correct before flow.css is imported and correct again after.",
       "interaction": "the controls capsule is an overlay surface; a live wire animates its dash overlay and stops under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }

package/manifest/components/flow-controls.json

@@ -28,10 +28,19 @@
       "language": "tsx"
     }
   ],
-  "status": "todo-docs",
+  "status": "stable",
   "url": "/docs/components/flow-controls",
   "mdUrl": "/docs/components/flow-controls.md",
   "jsonUrl": "/r/components/flow-controls.json",
+  "whenToUse": [
+    "On any flow canvas the user pans and zooms."
+  ],
+  "whenNotToUse": [
+    "As a general toolbar. Use `Toolbar`."
+  ],
+  "commonMistakes": [
+    "Moving the shape rules into a class. `border-radius` and `overflow` have no `--xy-*` hook, so the library's own rule would win — and `overflow: hidden` is what makes the first and last buttons take the capsule's corners instead of squaring them off."
+  ],
   "specimens": [
     {
       "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
@@ -45,6 +54,5 @@
       "note": "The hook returns the `--xy-*` token map plus stable `edgeTypes` and `defaultEdgeOptions` identities. Every part also publishes the map on its own root, so the group is correct before flow.css is imported and correct again after.",
       "interaction": "the controls capsule is an overlay surface; a live wire animates its dash overlay and stops under prefers-reduced-motion."
     }
-  ],
-  "todo": true
+  ]
 }