@cueplusplus/ui 0.2.0 → 0.5.0

package/manifest/components/error-state.json

@@ -0,0 +1,80 @@
+{
+  "name": "ErrorState",
+  "slug": "error-state",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A quiet failure banner with a retry path, not a modal in your face.",
+  "props": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Primary failure headline shown in the banner."
+    },
+    {
+      "name": "detail",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Supporting detail under the title explaining what went wrong."
+    },
+    {
+      "name": "retrying",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "When true the banner swaps to a spinning Retrying status instead of the error."
+    },
+    {
+      "name": "onRetry",
+      "type": "() => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when the retry control is pressed."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"role\"\n>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-radius-overlay",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A quiet failure banner with a retry path, not a modal in your face.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { ErrorState } from \"@cueplusplus/ui/elements\";\n\n<ErrorState\n  title=\"Request failed\"\n  detail=\"The model timed out.\"\n  retrying={false}\n  onRetry={() => {}}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/error-state",
+  "mdUrl": "/docs/components/error-state.md",
+  "jsonUrl": "/r/components/error-state.json",
+  "specimens": [
+    {
+      "title": "ErrorState",
+      "group": "elements-agents",
+      "components": [
+        "ErrorState"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"failed\" wide>\n    <ErrorState\n      title=\"The desk refused the patch\"\n      detail=\"Universe 3 is not enabled on this show file. Enable it on the desk, or patch into universes 1 and 2.\"\n      retrying={false}\n      onRetry={() => undefined}\n    />\n  </Specimen>\n  <Specimen label=\"retrying\" wide>\n    <ErrorState\n      title=\"The desk refused the patch\"\n      detail=\"Universe 3 is not enabled on this show file.\"\n      retrying\n      onRetry={() => undefined}\n    />\n  </Specimen>\n</Specimens>",
+      "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

@@ -0,0 +1,84 @@
+{
+  "name": "ExportDialog",
+  "slug": "export-dialog",
+  "group": "configurator",
+  "importPath": "@cueplusplus/ui/configurator",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The export dialog: CSS, DTCG tokens, a `createTheme()` call and a shadcn\n`registry:theme` item.\n\nAll four are generated from the overrides the panel is applying, so the CSS\none is *literally* the stylesheet on the page. Nothing here re-derives a\nvalue.",
+  "props": [
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Whether the dialog is showing."
+    },
+    {
+      "name": "onOpenChange",
+      "type": "(open: boolean) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called when it should open or close."
+    },
+    {
+      "name": "overrides",
+      "type": "ThemeOverrides",
+      "required": true,
+      "defaultValue": null,
+      "description": "The overrides to export."
+    },
+    {
+      "name": "scope",
+      "type": "ThemeScope",
+      "required": true,
+      "defaultValue": null,
+      "description": "The theme and mode they were made in."
+    },
+    {
+      "name": "defaultFormat",
+      "type": "\"css\" | \"dtcg\" | \"create-theme\" | \"registry\"",
+      "required": false,
+      "defaultValue": "css",
+      "description": "Format shown first. Defaults to `\"css\"`."
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-density",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-font-pairing-mono",
+    "--cue-font-sans",
+    "--cue-font-scale",
+    "--cue-font-theme-mono",
+    "--cue-radius-control",
+    "--cue-radius-scale",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-sunken",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The export dialog: CSS, DTCG tokens, a `createTheme()` call and a shadcn `registry:theme` item.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ExportDialog open={open} onOpenChange={setOpen} overrides={overrides} scope={scope} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/export-dialog",
+  "mdUrl": "/docs/components/export-dialog.md",
+  "jsonUrl": "/r/components/export-dialog.json",
+  "todo": true
+}

package/manifest/components/eyebrow.json

@@ -0,0 +1,56 @@
+{
+  "name": "Eyebrow",
+  "slug": "eyebrow",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The small accent kicker that sits above a title: `// PATCH`.\n\nMono, uppercase and widely tracked, in the theme's accent — the one place\nwhere the accent is used for pure typography rather than for a control. The\nslashes are marked `aria-hidden` and `select-none`, so a screen reader reads\n\"patch\" and a copy-paste of the page does not carry punctuation that was only\never decoration.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "slashes",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "true",
+      "description": "Print the `//` motif ahead of the label. Defaults to `true` — the slashes\nare the brand mark of this system, and an eyebrow without them is just\nsmall uppercase text. Pass `false` for a plain kicker."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"span\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-text-label"
+  ],
+  "summary": "The small accent kicker that sits above a title: `// PATCH`.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Eyebrow>Patch</Eyebrow>\n<Eyebrow slashes={false}>Beta</Eyebrow>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/eyebrow",
+  "mdUrl": "/docs/components/eyebrow.md",
+  "jsonUrl": "/r/components/eyebrow.json",
+  "specimens": [
+    {
+      "title": "Eyebrow",
+      "group": "chrome",
+      "components": [
+        "Eyebrow"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <Eyebrow>smoke matrix</Eyebrow>\n  </Specimen>\n  <Specimen label=\"no slashes\">\n    <Eyebrow slashes={false}>smoke matrix</Eyebrow>\n  </Specimen>\n</Specimens>",
+      "note": "The `//` motif from the brand site, in mono micro.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/feedback-dialog.json

@@ -0,0 +1,107 @@
+{
+  "name": "FeedbackDialog",
+  "slug": "feedback-dialog",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [
+    "lucide-react"
+  ],
+  "clientOnly": true,
+  "description": "A thumbs-down that asks why, so the signal arrives with a reason attached.",
+  "props": [
+    {
+      "name": "reasons",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The reason chips offered. Keep them short enough to scan in one line."
+    },
+    {
+      "name": "selected",
+      "type": "readonly string[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Which reasons are currently picked. More than one is allowed."
+    },
+    {
+      "name": "note",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Free-text detail, always optional."
+    },
+    {
+      "name": "sent",
+      "type": "boolean",
+      "required": true,
+      "defaultValue": null,
+      "description": "Replaces the whole form with an acknowledgement once the report is filed."
+    },
+    {
+      "name": "onToggleReason",
+      "type": "((reason: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when a reason chip is picked or unpicked."
+    },
+    {
+      "name": "onNoteChange",
+      "type": "((note: string) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called as the free-text note is typed."
+    },
+    {
+      "name": "onSubmit",
+      "type": "(() => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the report is sent."
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  | \"children\"\n  | \"reasons\"\n  | \"selected\"\n  | \"note\"\n  | \"sent\"\n  | \"onToggleReason\"\n  | \"onNoteChange\"\n  | \"onSubmit\"\n> & {\n  /** The reason chips offered. Keep them short enough to scan in one line. */\n  reasons: readonly string[];\n  /** Which reasons are currently picked. More than one is allowed. */\n  selected: readonly string[];\n  /** Free-text detail, always optional. */\n  note: string;\n  /** Replaces the whole form with an acknowledgement once the report is filed. */\n  sent: boolean;\n  /** Called when a reason chip is picked or unpicked. */\n  onToggleReason?: (reason: string) => void;\n  /** Called as the free-text note is typed. */\n  onNoteChange?: (note: string) => void;\n  /** Called when the report is sent. */\n  onSubmit?: () => void;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-ok",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-surface-1",
+    "--cue-text-body",
+    "--cue-text-ui"
+  ],
+  "summary": "A thumbs-down that asks why, so the signal arrives with a reason attached.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { FeedbackDialog } from \"@cueplusplus/ui/elements\";\n\n<FeedbackDialog\n  reasons={[\"Not factual\", \"Too long\"]}\n  selected={selected}\n  note={note}\n  sent={sent}\n  onToggleReason={toggle}\n  onNoteChange={setNote}\n  onSubmit={send}\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/feedback-dialog",
+  "mdUrl": "/docs/components/feedback-dialog.md",
+  "jsonUrl": "/r/components/feedback-dialog.json",
+  "specimens": [
+    {
+      "title": "FeedbackDialog",
+      "group": "elements-composer",
+      "components": [
+        "FeedbackDialog"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"collecting\" wide>\n    <FeedbackDialog\n      reasons={[\"Wrong universe\", \"Bad addressing\", \"Too slow\", \"Touched the desk\"]}\n      selected={reasons}\n      note={note}\n      sent={sent}\n      onToggleReason={(reason) =>\n        setReasons((current) =>\n          current.includes(reason)\n            ? current.filter((item) => item !== reason)\n            : [...current, reason],\n        )\n      }\n      onNoteChange={setNote}\n      onSubmit={() => setSent(true)}\n    />\n  </Specimen>\n  <Specimen label=\"sent\" wide>\n    <FeedbackDialog\n      reasons={[\"Wrong universe\", \"Bad addressing\"]}\n      selected={[\"Wrong universe\"]}\n      note=\"\"\n      sent\n    />\n  </Specimen>\n</Specimens>",
+      "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

@@ -0,0 +1,63 @@
+{
+  "name": "FieldDescription",
+  "slug": "field-description",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Quiet helper text under a control, published to assistive tech as the\ncontrol's `aria-describedby` target.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the helper-text defaults."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseField.Description.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "Quiet helper text under a control, published to assistive tech as the control's `aria-describedby` target.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FieldDescription>1–512</FieldDescription>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/field-description",
+  "mdUrl": "/docs/components/field-description.md",
+  "jsonUrl": "/r/components/field-description.json",
+  "specimens": [
+    {
+      "title": "Field / FieldLabel / FieldDescription / FieldError",
+      "group": "forms",
+      "components": [
+        "Field",
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Field name=\"cue\">\n    <FieldLabel>Cue name</FieldLabel>\n    <Input placeholder=\"e.g. Blackout\" />\n    <FieldDescription>Shown in the cue list.</FieldDescription>\n  </Field>\n  <Field name=\"universe\" invalid>\n    <FieldLabel>Universe</FieldLabel>\n    <Input defaultValue=\"9\" />\n    <FieldError issues={INVALID_ISSUE} />\n  </Field>\n  <Field name=\"locked\" disabled>\n    <FieldLabel>Locked</FieldLabel>\n    <Input defaultValue=\"Read-only\" />\n    <FieldDescription>Set by the show file.</FieldDescription>\n  </Field>\n</div>",
+      "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

@@ -0,0 +1,77 @@
+{
+  "name": "FieldError",
+  "slug": "field-error",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The error line under a control.\n\nTwo ways to drive it, and they are mutually exclusive by design:\npass `issues` from a Standard Schema parse (`schema.safeParse(x).issues`) and\nthe component owns visibility, or pass `match` + `children` and let Base UI\nkey off the native `ValidityState`.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the danger-text defaults."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Message to show when driving visibility from `match` instead of `issues`."
+    },
+    {
+      "name": "issues",
+      "type": "readonly FieldIssue[]",
+      "required": false,
+      "defaultValue": null,
+      "description": "Standard Schema issues for this field. When supplied, the component shows\nexactly these messages and stops consulting native `ValidityState`: an\nempty array renders nothing, one issue renders inline, several render as a\nlist. Leave it `undefined` to fall back to `match` + `children`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseField.Error.Props, \"className\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The error line under a control.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FieldError issues={result.issues} />\n<FieldError match=\"valueMissing\">Please name the cue</FieldError>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/field-error",
+  "mdUrl": "/docs/components/field-error.md",
+  "jsonUrl": "/r/components/field-error.json",
+  "specimens": [
+    {
+      "title": "Field / FieldLabel / FieldDescription / FieldError",
+      "group": "forms",
+      "components": [
+        "Field",
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Field name=\"cue\">\n    <FieldLabel>Cue name</FieldLabel>\n    <Input placeholder=\"e.g. Blackout\" />\n    <FieldDescription>Shown in the cue list.</FieldDescription>\n  </Field>\n  <Field name=\"universe\" invalid>\n    <FieldLabel>Universe</FieldLabel>\n    <Input defaultValue=\"9\" />\n    <FieldError issues={INVALID_ISSUE} />\n  </Field>\n  <Field name=\"locked\" disabled>\n    <FieldLabel>Locked</FieldLabel>\n    <Input defaultValue=\"Read-only\" />\n    <FieldDescription>Set by the show file.</FieldDescription>\n  </Field>\n</div>",
+      "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

@@ -0,0 +1,63 @@
+{
+  "name": "FieldLabel",
+  "slug": "field-label",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The name of a field: mono, uppercase, tracked out, one rung below body text.\n\nRenders a real `<label>` wired to the field's control, so clicking it focuses\n(or toggles) that control.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the label typography."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseField.Label.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The name of a field: mono, uppercase, tracked out, one rung below body text.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<FieldLabel>Universe</FieldLabel>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/field-label",
+  "mdUrl": "/docs/components/field-label.md",
+  "jsonUrl": "/r/components/field-label.json",
+  "specimens": [
+    {
+      "title": "Field / FieldLabel / FieldDescription / FieldError",
+      "group": "forms",
+      "components": [
+        "Field",
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Field name=\"cue\">\n    <FieldLabel>Cue name</FieldLabel>\n    <Input placeholder=\"e.g. Blackout\" />\n    <FieldDescription>Shown in the cue list.</FieldDescription>\n  </Field>\n  <Field name=\"universe\" invalid>\n    <FieldLabel>Universe</FieldLabel>\n    <Input defaultValue=\"9\" />\n    <FieldError issues={INVALID_ISSUE} />\n  </Field>\n  <Field name=\"locked\" disabled>\n    <FieldLabel>Locked</FieldLabel>\n    <Input defaultValue=\"Read-only\" />\n    <FieldDescription>Set by the show file.</FieldDescription>\n  </Field>\n</div>",
+      "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.json

@@ -0,0 +1,79 @@
+{
+  "name": "Field",
+  "slug": "field",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The labelling and validation wrapper every form control belongs in.\n\nWraps Base UI's `Field.Root`, which generates the ids that tie\n{@link FieldLabel}, {@link FieldDescription} and {@link FieldError} to the\ncontrol inside it — so `<FieldLabel>Cue name</FieldLabel>` names an\n{@link Input } with no `htmlFor`/`id` bookkeeping from the caller. Base UI also\nstamps `data-invalid` / `data-disabled` down the subtree, which is what the\nchassis' danger rim keys off.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the vertical stack defaults."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseField.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-text-label",
+    "--cue-text-micro"
+  ],
+  "summary": "The label, description and validation wrapper a form control belongs in.",
+  "examples": [
+    {
+      "title": "A field with validation",
+      "code": "<Field name=\"cue\">\n  <FieldLabel>Cue name</FieldLabel>\n  <Input placeholder=\"e.g. Blackout\" />\n  <FieldDescription>Shown in the cue list.</FieldDescription>\n  <FieldError issues={result.issues} />\n</Field>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Field name=\"cue\">\n  <FieldLabel>Cue name</FieldLabel>\n  <Input placeholder=\"e.g. Blackout\" />\n  <FieldDescription>Shown in the cue list.</FieldDescription>\n  <FieldError issues={result.issues} />\n</Field>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/field",
+  "mdUrl": "/docs/components/field.md",
+  "jsonUrl": "/r/components/field.json",
+  "whenToUse": [
+    "Any control that needs a visible label, helper text, or validation output.",
+    "Rendering Standard Schema issues (Zod, Valibot, ArkType) through `FieldError`."
+  ],
+  "whenNotToUse": [
+    "A control in a table row or a toolbar, where the column heading is already the label. Give the control an `aria-label` instead.",
+    "Grouping controls that share one value. Use `CheckboxGroup` or `RadioGroup`, which own the value and the group name."
+  ],
+  "commonMistakes": [
+    "Writing `htmlFor` and `id` by hand. `Field` generates them, and hand-written ids collide as soon as the form repeats.",
+    "Putting two controls in one `Field`, which points the generated description at the wrong one."
+  ],
+  "specimens": [
+    {
+      "title": "Field / FieldLabel / FieldDescription / FieldError",
+      "group": "forms",
+      "components": [
+        "Field",
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-3\">\n  <Field name=\"cue\">\n    <FieldLabel>Cue name</FieldLabel>\n    <Input placeholder=\"e.g. Blackout\" />\n    <FieldDescription>Shown in the cue list.</FieldDescription>\n  </Field>\n  <Field name=\"universe\" invalid>\n    <FieldLabel>Universe</FieldLabel>\n    <Input defaultValue=\"9\" />\n    <FieldError issues={INVALID_ISSUE} />\n  </Field>\n  <Field name=\"locked\" disabled>\n    <FieldLabel>Locked</FieldLabel>\n    <Input defaultValue=\"Read-only\" />\n    <FieldDescription>Set by the show file.</FieldDescription>\n  </Field>\n</div>",
+      "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."
+    }
+  ]
+}