@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/node-handle.json

@@ -0,0 +1,69 @@
+{
+  "name": "NodeHandle",
+  "slug": "node-handle",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [
+    "@xyflow/react"
+  ],
+  "clientOnly": true,
+  "description": "A connection point on a node, drawn as a pin rather than a dot.\n\nEverything visual is **inline style, not a class**, and that is deliberate:\n`.react-flow__handle` sets `background-color`, `border` and `width`/`height`\nfrom the library's own unlayered stylesheet, while Tailwind's utilities live in\na cascade layer — and any layered rule loses to an unlayered one of the same\nspecificity, whatever order the files load in. An inline declaration is the\nonly paint that reliably wins, which is also how the port did it.\n\nThe pin is ringed in `--cue-bg` rather than in the card's own surface, so it\nreads as lifted off the edge it straddles no matter which surface rung the\nnode is on.",
+  "props": [
+    {
+      "name": "tone",
+      "type": "\"accent\" | \"danger\" | \"busy\" | \"muted\" | \"ok\" | \"warn\" | \"info\"",
+      "required": false,
+      "defaultValue": "accent",
+      "description": "What the connection carries. Defaults to `\"accent\"`."
+    },
+    {
+      "name": "size",
+      "type": "number",
+      "required": false,
+      "defaultValue": "9",
+      "description": "Diameter in px at the 16px root, emitted as `rem`. Defaults to `9`."
+    }
+  ],
+  "typeReferences": [
+    "HandleProps"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-bg",
+    "--cue-border-strong",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-warn"
+  ],
+  "summary": "A connection point on a node, drawn as a pin rather than a dot.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<NodeHandle type=\"source\" position={Position.Right} id=\"u1\" />\n<NodeHandle type=\"target\" position={Position.Left} id=\"in\" tone=\"muted\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/node-handle",
+  "mdUrl": "/docs/components/node-handle.md",
+  "jsonUrl": "/r/components/node-handle.json",
+  "specimens": [
+    {
+      "title": "NodeHandle",
+      "group": "flow",
+      "components": [
+        "NodeHandle"
+      ],
+      "code": "<div className=\"h-[9rem] w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <ReactFlow\n    nodes={TONE_NODES}\n    edges={[]}\n    nodeTypes={NODE_TYPES}\n    colorMode={theme.colorMode}\n    style={theme.style}\n    nodesDraggable={false}\n    panOnDrag={false}\n    zoomOnScroll={false}\n    proOptions={{ hideAttribution: true }}\n  />\n</div>",
+      "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

@@ -0,0 +1,107 @@
+{
+  "name": "NumberField",
+  "slug": "number-field",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A numeric control with explicit − / + affordances and no native spinners.\n\nNative `<input type=\"number\">` spinners are unusable at console density — a\npair of 4px arrows that only appear on hover — so this is a text input with\n`inputMode=\"numeric\"` flanked by real buttons, which is also what makes it\ntouch-usable. Arrow keys step, Shift steps by `largeStep`, Alt by `smallStep`,\nand values typed out of range are clamped to `min`/`max` on blur.\n\nThe group owns the rim; the input and both buttons render bare inside it, so\nthe whole cluster reads as one field and focus feedback moves to\n`focus-within`.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes, merged over the group chassis."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the text control, when no {@link FieldLabel } names it."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Placeholder shown while the field is empty."
+    },
+    {
+      "name": "decrementLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Decrease",
+      "description": "Accessible name for the decrement button. Defaults to `\"Decrease\"`."
+    },
+    {
+      "name": "incrementLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Increase",
+      "description": "Accessible name for the increment button. Defaults to `\"Increase\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseNumberField.Root.Props, \"className\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-surface-2",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A numeric control with explicit − / + affordances and no native spinners.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<NumberField aria-label=\"Fade time\" defaultValue={3} min={0} max={600} step={0.5} />\n<Field><FieldLabel>Universe</FieldLabel><NumberField min={1} max={512} /></Field>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/number-field",
+  "mdUrl": "/docs/components/number-field.md",
+  "jsonUrl": "/r/components/number-field.json",
+  "specimens": [
+    {
+      "title": "NumberField",
+      "group": "forms",
+      "components": [
+        "NumberField"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <NumberField aria-label=\"Fade time\" defaultValue={3} min={0} max={600} step={0.5} />\n  </Specimen>\n  <Specimen label=\"sm\">\n    <NumberField aria-label=\"Fade time, small\" defaultValue={3} size=\"sm\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <NumberField aria-label=\"Fade time, disabled\" defaultValue={3} disabled />\n  </Specimen>\n</Specimens>",
+      "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/otp-field.json

@@ -0,0 +1,128 @@
+{
+  "name": "OTPField",
+  "slug": "otp-field",
+  "group": "forms",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A one-time code, one character per box.\n\nThe boxes are not decoration: they tell the user how long the code is before\nthey start typing, which is the whole reason this pattern beats a plain text\ninput. Paste, arrow keys, Backspace across slot boundaries and the\n`one-time-code` autofill hint all come from Base UI.\n\nSlots ride the recessed chassis — sunken fill, hairline rim — so a code field\nreads as \"type here\" like every other input in the system, just squared off.",
+  "props": [
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the row."
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id of the first slot. Generated when omitted, so the hidden label can target it."
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the field. Names the group *and*, through a visually\nhidden `<label>`, the first slot — the ARIA pattern for a code field. Leave\nit off inside a {@link Field }, which supplies a real label."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": "Rung of the control ladder. Defaults to `\"md\"`."
+    },
+    {
+      "name": "separator",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": "–",
+      "description": "What sits between groups. Defaults to `\"–\"`. Always `aria-hidden`."
+    },
+    {
+      "name": "length",
+      "type": "number",
+      "required": false,
+      "defaultValue": "6",
+      "description": "How many characters the code has. Defaults to `6`."
+    },
+    {
+      "name": "groupSize",
+      "type": "number",
+      "required": false,
+      "defaultValue": null,
+      "description": "Insert a separator after every `groupSize` slots — `groupSize={3}` renders a\nsix-character code as `123 456`, which is how people read one off a screen."
+    },
+    {
+      "name": "slotLabel",
+      "type": "((index: number, length: number) => string)",
+      "required": false,
+      "defaultValue": "(index, total) => `Character ${index + 1} of ${total}`",
+      "description": "Accessible name for slot `index` (1-based here, since slot 0 is named by the\nfield label) of `length`. Defaults to\n``(index, length) => `Character ${index + 1} of ${length}` ``."
+    },
+    {
+      "name": "slotClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for every slot."
+    }
+  ],
+  "typeReferences": [
+    "Omit<BaseOTPField.Root.Props, \"className\" | \"children\" | \"length\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A one-time code, one character per box.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<OTPField aria-label=\"Verification code\" onValueComplete={submit} />\n<OTPField aria-label=\"Recovery code\" length={8} groupSize={4} validationType=\"alphanumeric\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/otp-field",
+  "mdUrl": "/docs/components/otp-field.md",
+  "jsonUrl": "/r/components/otp-field.json",
+  "specimens": [
+    {
+      "title": "OTPField",
+      "group": "forms",
+      "components": [
+        "OTPField"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"empty\">\n    <OTPField aria-label=\"Pairing code\" />\n  </Specimen>\n  <Specimen label=\"filled\">\n    <OTPField aria-label=\"Pairing code, filled\" defaultValue=\"428170\" />\n  </Specimen>\n  <Specimen label=\"4 digits, sm\">\n    <OTPField aria-label=\"Short code\" length={4} groupSize={4} size=\"sm\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <OTPField aria-label=\"Code, disabled\" defaultValue=\"428170\" disabled />\n  </Specimen>\n</Specimens>",
+      "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

@@ -0,0 +1,96 @@
+{
+  "name": "PageShell",
+  "slug": "page-shell",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A centred content column with a standard page header.\n\nThe header is emitted only when something fills it, so a shell used purely\nfor its measure adds no empty box and no stray vertical rhythm.\n\nRenders a plain `<div>` rather than a `<main>`: a page can hold more than one\nshell (a split view), and only one element per document may be `<main>`. Wrap\nit yourself where the semantics apply.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "width",
+      "type": "\"narrow\" | \"wide\" | \"broad\" | \"full\"",
+      "required": false,
+      "defaultValue": "narrow",
+      "description": "Which measure the content column takes. Defaults to `\"narrow\"`."
+    },
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The page heading. Rendered as the `<h1>`."
+    },
+    {
+      "name": "subtitle",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "One supporting line under the title."
+    },
+    {
+      "name": "eyebrow",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accent kicker above the title — normally an `<Eyebrow>`."
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Page-level actions, aligned with the title."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The page body."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-font-mono",
+    "--cue-space-2",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-space-7",
+    "--cue-text-title",
+    "--cue-text-ui"
+  ],
+  "summary": "A centred content column with a standard page header.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PageShell title=\"Patch\" subtitle=\"512 channels\" eyebrow={<Eyebrow>Console</Eyebrow>}>\n  <Panel>…</Panel>\n</PageShell>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/page-shell",
+  "mdUrl": "/docs/components/page-shell.md",
+  "jsonUrl": "/r/components/page-shell.json",
+  "specimens": [
+    {
+      "title": "PageShell",
+      "group": "chrome",
+      "components": [
+        "PageShell"
+      ],
+      "code": "<div className=\"w-full rounded-(--radius-surface) border border-border bg-bg py-(--cue-space-5)\">\n  <PageShell\n    width=\"narrow\"\n    eyebrow={<Eyebrow>show file</Eyebrow>}\n    title=\"Ada, act 2\"\n    subtitle=\"12 cues, 48 fixtures, 4 universes.\"\n    actions={<Button variant=\"primary\">Save</Button>}\n  >\n    <Panel className=\"p-(--cue-space-5) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      Page body.\n    </Panel>\n  </PageShell>\n</div>",
+      "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

@@ -0,0 +1,92 @@
+{
+  "name": "Pagination",
+  "slug": "pagination",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "The pager: previous, a window of page numbers, next.\n\nRenders nothing at all when there is a single page — a control offering no\nchoice is chrome that says \"there is more here\" when there is not.\n\nEvery page number is a real button with a spoken name (\"Page 3\"), because the\nbare numeral is meaningless read aloud out of context; the ellipses are\n`aria-hidden` for the same reason breadcrumb separators are.",
+  "props": [
+    {
+      "name": "page",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "The current page, 1-based."
+    },
+    {
+      "name": "pageCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many pages there are in total."
+    },
+    {
+      "name": "onPageChange",
+      "type": "(page: number) => void",
+      "required": true,
+      "defaultValue": null,
+      "description": "Called with the page a control asked for. Always within `1..pageCount`."
+    },
+    {
+      "name": "siblingCount",
+      "type": "number",
+      "required": false,
+      "defaultValue": "1",
+      "description": "How many pages to show either side of the current one. Defaults to `1`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Pagination",
+      "description": "The nav's accessible name. Defaults to `\"Pagination\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"nav\">, \"onChange\" | \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-soft",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-surface-2",
+    "--cue-text-ui"
+  ],
+  "summary": "The pager: previous, a window of page numbers, next.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Pagination page={page} pageCount={12} onPageChange={setPage} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/pagination",
+  "mdUrl": "/docs/components/pagination.md",
+  "jsonUrl": "/r/components/pagination.json",
+  "specimens": [
+    {
+      "title": "Pagination",
+      "group": "layout",
+      "components": [
+        "Pagination"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-4)\">\n  <Pagination page={page} pageCount={12} onPageChange={setPage} />\n  <Pagination page={1} pageCount={3} onPageChange={() => {}} />\n</div>",
+      "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

@@ -0,0 +1,77 @@
+{
+  "name": "PanelHeader",
+  "slug": "panel-header",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The top bar of a {@link Panel}: title left, actions right, hairline under.\n\nPadded with the density row tokens rather than its own values, so the header\nlines up horizontally with the rows beneath it at every density level.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "title",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The header's label. Rendered one type rung above body text — the panel's\nown name, not a page heading."
+    },
+    {
+      "name": "actions",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Right-hand slot: the controls that act on the whole panel (a menu, a\nrefresh button, a count chip)."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra content in the leading cluster, after the title."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"title\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-font-mono",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-text-emphasis"
+  ],
+  "summary": "The top bar of a {@link Panel}: title left, actions right, hairline under.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<PanelHeader title=\"Universes\" actions={<Chip tone=\"ok\">live</Chip>} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/panel-header",
+  "mdUrl": "/docs/components/panel-header.md",
+  "jsonUrl": "/r/components/panel-header.json",
+  "specimens": [
+    {
+      "title": "Panel / PanelHeader",
+      "group": "chrome",
+      "components": [
+        "Panel",
+        "PanelHeader"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel>\n    <PanelHeader title=\"Output\" actions={<Chip tone=\"ok\">live</Chip>} />\n    {CUES.slice(0, 3).map((cue) => (\n      <Row key={cue.id}>\n        <span className=\"w-[2rem] shrink-0 font-mono tabular-nums\">{cue.id}</span>\n        <span className=\"flex-1 truncate\">{cue.label}</span>\n        <span className=\"font-mono tabular-nums text-fg-muted\">{cue.time}</span>\n      </Row>\n    ))}\n  </Panel>\n  <Panel className=\"p-(--cue-space-5)\">\n    <PanelHeader>\n      <Eyebrow>free-form header</Eyebrow>\n    </PanelHeader>\n    <p className=\"pt-(--cue-space-4) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      A panel with body padding instead of rows, for prose and forms.\n    </p>\n  </Panel>\n</div>",
+      "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/panel.json

@@ -0,0 +1,71 @@
+{
+  "name": "Panel",
+  "slug": "panel",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The universal container: one hairline rim, one raised surface, one radius.\n\nEverything in a console lives in a panel — a cue list, a patch table, a\nsettings group — so the shape is defined once here rather than re-typed as\nfour utilities at every call site. `overflow-hidden` is part of the recipe,\nnot an extra: it clips the first and last `Row`'s square edges back to the\npanel's radius, which is what makes a stack of hairline rows read as one\nobject.\n\nDeliberately flat: no shadow. In this system only a floating surface (a\ndialog, a menu, a toast) is allowed one — see `overlays/_surface.ts`.\n\nStatic markup — no `\"use client\"`.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-font-mono",
+    "--cue-pad-row-x",
+    "--cue-pad-row-y",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-surface-1",
+    "--cue-text-emphasis"
+  ],
+  "summary": "The universal container: one hairline rim, one raised surface, one radius.",
+  "examples": [
+    {
+      "title": "A panel of rows",
+      "code": "<Panel>\n  <PanelHeader title=\"Cue stack\" actions={<Chip tone=\"ok\">live</Chip>} />\n  <Row interactive>Cue 1 — house up</Row>\n  <Row interactive>Cue 2 — blackout</Row>\n</Panel>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Panel>\n  <PanelHeader title=\"Cue stack\" actions={<IconButton aria-label=\"Add\" icon={Plus} />} />\n  <Row>Cue 1</Row>\n  <Row>Cue 2</Row>\n</Panel>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/panel",
+  "mdUrl": "/docs/components/panel.md",
+  "jsonUrl": "/r/components/panel.json",
+  "whenToUse": [
+    "Any grouped region of a console: a cue list, a table, a settings block.",
+    "As the parent of a `Row` stack, whose square corners it clips back to the panel radius."
+  ],
+  "whenNotToUse": [
+    "Page-level structure. Use `PageShell` for a titled page, `Container` for a width bound.",
+    "Anything that floats. Menus, dialogs and toasts wear the overlay surface, which owns the only shadows in the system."
+  ],
+  "commonMistakes": [
+    "Adding a shadow. A panel is flat by design; a shadow here reads as a bug in the theme.",
+    "Padding the panel and then padding its rows, which doubles the gutter the row tokens already set."
+  ],
+  "specimens": [
+    {
+      "title": "Panel / PanelHeader",
+      "group": "chrome",
+      "components": [
+        "Panel",
+        "PanelHeader"
+      ],
+      "code": "<div className=\"grid w-full gap-(--cue-space-5) lg:grid-cols-2\">\n  <Panel>\n    <PanelHeader title=\"Output\" actions={<Chip tone=\"ok\">live</Chip>} />\n    {CUES.slice(0, 3).map((cue) => (\n      <Row key={cue.id}>\n        <span className=\"w-[2rem] shrink-0 font-mono tabular-nums\">{cue.id}</span>\n        <span className=\"flex-1 truncate\">{cue.label}</span>\n        <span className=\"font-mono tabular-nums text-fg-muted\">{cue.time}</span>\n      </Row>\n    ))}\n  </Panel>\n  <Panel className=\"p-(--cue-space-5)\">\n    <PanelHeader>\n      <Eyebrow>free-form header</Eyebrow>\n    </PanelHeader>\n    <p className=\"pt-(--cue-space-4) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      A panel with body padding instead of rows, for prose and forms.\n    </p>\n  </Panel>\n</div>",
+      "note": "The universal container: one hairline rim, no shadow, and a header that owns its own rule.",
+      "interaction": "none. A panel is a box."
+    }
+  ]
+}