@cueplusplus/ui 0.1.0 → 0.3.0

package/manifest/components/flow-controls.json

@@ -0,0 +1,50 @@
+{
+  "name": "FlowControls",
+  "slug": "flow-controls",
+  "group": "flow",
+  "importPath": "@cueplusplus/ui/flow",
+  "peerDependencies": [
+    "@xyflow/react"
+  ],
+  "clientOnly": true,
+  "description": "The zoom / fit / lock capsule, restyled as an overlay surface.\n\nShape is inline for the same reason the colours are: `border-radius` and\n`overflow` have no `--xy-*` hook, and the library's own rule would otherwise\nwin. `overflow: hidden` is what makes the first and last buttons take the\ncapsule's corners instead of squaring them off.",
+  "props": [],
+  "typeReferences": [
+    "React.ComponentProps<typeof Controls>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-overlay",
+    "--cue-radius-overlay"
+  ],
+  "summary": "The zoom / fit / lock capsule, restyled as an overlay surface.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<ReactFlow …><FlowControls /></ReactFlow>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/flow-controls",
+  "mdUrl": "/docs/components/flow-controls.md",
+  "jsonUrl": "/r/components/flow-controls.json",
+  "specimens": [
+    {
+      "title": "useFlowTheme / FlowControls / FlowBackground / SignalEdge",
+      "group": "flow",
+      "components": [
+        "FlowControls",
+        "FlowBackground",
+        "SignalEdge"
+      ],
+      "code": "<div className=\"h-[24rem] w-full overflow-hidden rounded-(--radius-surface) border border-border\">\n  <ReactFlow\n    nodes={NODES}\n    edges={EDGES}\n    nodeTypes={NODE_TYPES}\n    edgeTypes={theme.edgeTypes}\n    defaultEdgeOptions={theme.defaultEdgeOptions}\n    colorMode={theme.colorMode}\n    style={theme.style}\n    fitView\n    proOptions={{ hideAttribution: true }}\n  >\n    <FlowBackground />\n    <FlowControls />\n  </ReactFlow>\n</div>",
+      "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/footer.json

@@ -0,0 +1,112 @@
+{
+  "name": "Footer",
+  "slug": "footer",
+  "group": "chrome",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The `contentinfo` landmark at the bottom of a document: a hairline, a\nmeasure, and room for whatever a page ends with.\n\nDeliberately **not** a link-list component. A \"complex footer\" in this system\nis `Grid` + `Stack` + `Link` inside this one — components that already exist\nand already carry the density ladder — and a `Grid` with `minItemWidth` fills\nthe row with as many columns as fit, so the footer is responsive without a\nbreakpoint and without a prop for how many columns to draw. What is left over\nis what a footer actually needs and nothing else has: the landmark, the rule\nthat separates it from the page, the measure that lines it up with the page,\nand the second rule above the fine print.\n\nThe band is full-bleed and the column inside it is centred, which is why the\nhairline runs edge to edge while the links stop at the measure. The column is\nset in the bar's register — mono, at the UI size — because a footer is\nfurniture. It paints no ground of its own: a footer is the end of the page,\nnot a bar, and the seam is the hairline. Give it `className=\"bg-surface-1\"`\nwhere a distinct band is wanted.\n\nInside `AppShell` this is a child of `AppShell.Scroller`, at the end of the\ncontent column — so it scrolls with the page and its full bleed is the\ncontent column's width, not the window's. A footer placed *beside* the\nnavigation column instead (after `AppShell.Body`) runs under the navigation\nand reads as chrome it is not. It coexists with `StatusBar`, which is the\nopposite object: a strip of the frame, always on screen, never scrolled.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "width",
+      "type": "\"narrow\" | \"wide\" | \"broad\" | \"full\"",
+      "required": false,
+      "defaultValue": "broad",
+      "description": "Which measure the footer's column takes. Defaults to `\"broad\"`.\n\nThe same four rungs `Container` and `PageShell` offer, so a footer lines up\nwith the page above it by naming the same width — `broad` rather than\n`narrow` by default because a footer is usually the widest thing on a page,\nand a row of columns inside a 42rem reading measure is four squeezed lists."
+    },
+    {
+      "name": "meta",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The fine print, under a hairline of its own: copyright, a licence, a build\nnumber.\n\nA slot rather than a component, because that row is a sentence and a couple\nof links — but it is a *separated* sentence, and hand-rolling the rule and\nthe space above it in every app is exactly the kind of repetition this\ncomponent exists to end."
+    },
+    {
+      "name": "columnClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the centred column inside the landmark."
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The footer's body — normally a `Grid` of `Stack`s of `Link`s."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"footer\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-space-6",
+    "--cue-space-7",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "The contentinfo landmark at the bottom of a document: a full-bleed hairline, a centred measure, and a fine-print row under a rule of its own.",
+  "examples": [
+    {
+      "title": "A complex footer is components you already have",
+      "code": "<Footer\n  width=\"broad\"\n  meta={\n    <>\n      <span>© 2026 CUE++</span>\n      <Link href=\"/legal\">Legal</Link>\n    </>\n  }\n>\n  <Grid minItemWidth=\"12rem\" gap={5}>\n    <Stack gap={2}>\n      <Eyebrow>Docs</Eyebrow>\n      <Link href=\"/docs\">Getting started</Link>\n      <Link href=\"/docs/theming\">Theming</Link>\n    </Stack>\n    <Stack gap={2}>\n      <Eyebrow>Surfaces</Eyebrow>\n      <Link href=\"/kitchen-sink\">Kitchen sink</Link>\n      <Link href=\"/gallery\">Gallery</Link>\n    </Stack>\n  </Grid>\n</Footer>",
+      "language": "tsx"
+    },
+    {
+      "title": "Wiring it once",
+      "code": "<div className=\"flex min-h-dvh flex-col\">\n  <SiteHeader />\n  <main className=\"min-w-0 flex-1\">{children}</main>\n  <SiteFooter />\n</div>",
+      "language": "tsx"
+    },
+    {
+      "title": "Inside `AppShell`: the content column, never the frame",
+      "code": "<AppShell.Content>\n  <AppShell.Scroller padded={false} className=\"flex flex-col\">\n    <div className=\"flex-1\">{children}</div>\n    <Footer meta={…}>…</Footer>\n  </AppShell.Scroller>\n</AppShell.Content>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Footer meta={<><span>© 2026 CUE++</span><Link href=\"/legal\">Legal</Link></>}>\n  <Grid minItemWidth=\"12rem\" gap={5}>\n    <Stack gap={2}>\n      <Eyebrow>Docs</Eyebrow>\n      <Link href=\"/docs\">Getting started</Link>\n      <Link href=\"/docs/theming\">Theming</Link>\n    </Stack>\n    <Stack gap={2}>\n      <Eyebrow>Surfaces</Eyebrow>\n      <Link href=\"/kitchen-sink\">Kitchen sink</Link>\n    </Stack>\n  </Grid>\n</Footer>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/footer",
+  "mdUrl": "/docs/components/footer.md",
+  "jsonUrl": "/r/components/footer.json",
+  "whenToUse": [
+    "The end of any document that scrolls: a site, a documentation page, a marketing page, the signed-out half of a console.",
+    "Whenever a page ends with a hand-rolled `<footer>` carrying its own `border-t`, its own `max-w-*` and its own gutters. Those three are the component.",
+    "As the frame for a complex footer — a row of link columns, a status line, a licence — with `Grid` and `Stack` doing the layout inside it."
+  ],
+  "whenNotToUse": [
+    "As the bottom strip of a console. That is `StatusBar`: one chrome rung tall, always on screen, tone-inked readouts. A footer scrolls away, and should. The two can coexist — see below.",
+    "As a sibling of the navigation column. Inside a shell a footer belongs to the content scroller; one placed beside `AppShell.Sidebar`, or after `AppShell.Body`, stretches under the navigation and pretends to be part of the frame.",
+    "As a place to put a link list component. There isn't one, and there does not need to be — see below."
+  ],
+  "commonMistakes": [
+    "Reaching for a column count. Use `Grid` with `minItemWidth`: it fills the row with as many columns as fit, so the footer is responsive with no breakpoint and no prop for how many columns to draw.",
+    "Setting a width that disagrees with the page above it. `Footer` takes the same four measures as `Container` and `PageShell` — name the same rung and the columns line up with the content.",
+    "Hand-rolling the fine-print rule. That is what `meta` is: it draws the hairline and the space above it so every app does not.",
+    "Painting a ground on it by reflex. A footer is the end of the page, not a bar; the seam is the hairline. Pass `className=\"bg-surface-1\"` only when a distinct band is actually wanted."
+  ],
+  "specimens": [
+    {
+      "title": "Footer",
+      "group": "chrome",
+      "components": [
+        "Footer"
+      ],
+      "code": "<div className=\"w-full overflow-hidden rounded-(--radius-surface) border border-border bg-bg\">\n  <Footer\n    width=\"wide\"\n    meta={\n      <>\n        <span>© 2026 CUE++</span>\n        <Link href=\"#legal\">Legal</Link>\n      </>\n    }\n  >\n    <Grid minItemWidth=\"9rem\" gap={5}>\n      <Stack gap={2}>\n        <Eyebrow>Docs</Eyebrow>\n        <Link href=\"#getting-started\">Getting started</Link>\n        <Link href=\"#theming\">Theming</Link>\n      </Stack>\n      <Stack gap={2}>\n        <Eyebrow>Surfaces</Eyebrow>\n        <Link href=\"#kitchen-sink\">Kitchen sink</Link>\n        <Link href=\"#gallery\">Gallery</Link>\n      </Stack>\n      <Stack gap={2}>\n        <Eyebrow>Elsewhere</Eyebrow>\n        <Link external href=\"https://skills.cueplusplus.com\">\n          Skills\n        </Link>\n      </Stack>\n    </Grid>\n  </Footer>\n</div>",
+      "note": "The contentinfo landmark: a full-bleed hairline, a centred measure off the same ladder Container and PageShell use, and a fine-print row under a rule of its own. The columns are Grid + Stack + Link — there is no link-list component here, because none is needed.",
+      "interaction": "none; the links inside are ordinary links."
+    }
+  ]
+}

package/manifest/components/grid.json

@@ -0,0 +1,81 @@
+{
+  "name": "Grid",
+  "slug": "grid",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "Two-dimensional layout: equal columns, or as many as fit.\n\nSame bargain as `Stack` — the gap is a rung of the density ladder rather than\na hand-picked pixel value, so a card grid tightens with the rest of the\nconsole when the user asks for ultra-compact.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "cols",
+      "type": "4 | 1 | 2 | 3 | 5 | 6",
+      "required": false,
+      "defaultValue": "1",
+      "description": "How many equal columns. Defaults to `1`. Ignored when `minItemWidth` is set."
+    },
+    {
+      "name": "gap",
+      "type": "0 | 4 | 8 | 1 | 2 | 3 | 5 | 6 | 7",
+      "required": false,
+      "defaultValue": "4",
+      "description": "Which rung of the density space ladder to spend between cells. Defaults to `4`."
+    },
+    {
+      "name": "minItemWidth",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Fill the row with as many columns of at least this width as fit, instead of\na fixed count. Any CSS length (`\"12rem\"`, `\"200px\"`).\n\nPrefer this over a column count wherever the content has a natural minimum\nmeasure — it is responsive without a single breakpoint."
+    },
+    {
+      "name": "align",
+      "type": "\"center\" | \"end\" | \"baseline\" | \"start\" | \"stretch\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Cross-axis alignment of the cells."
+    },
+    {
+      "name": "justify",
+      "type": "\"center\" | \"end\" | \"start\" | \"between\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Main-axis distribution of the tracks."
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"div\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-grid-min"
+  ],
+  "summary": "Two-dimensional layout: equal columns, or as many as fit.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<Grid cols={3} gap={5}>{cards}</Grid>\n<Grid minItemWidth=\"14rem\" gap={4}>{cards}</Grid>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/grid",
+  "mdUrl": "/docs/components/grid.md",
+  "jsonUrl": "/r/components/grid.json",
+  "specimens": [
+    {
+      "title": "Grid",
+      "group": "layout",
+      "components": [
+        "Grid"
+      ],
+      "code": "<div className=\"flex w-full flex-col gap-(--cue-space-5)\">\n  <Grid cols={4} gap={3}>\n    {[\"1\", \"2\", \"3\", \"4\"].map((cell) => (\n      <Panel\n        key={cell}\n        className=\"p-(--cue-space-4) text-center font-mono text-(length:--cue-text-label) text-fg-subtle\"\n      >\n        {cell}\n      </Panel>\n    ))}\n  </Grid>\n  <Grid minItemWidth=\"12rem\" gap={3}>\n    {[\"auto\", \"fit\", \"from\", \"12rem\"].map((cell) => (\n      <Panel\n        key={cell}\n        className=\"p-(--cue-space-4) text-center font-mono text-(length:--cue-text-label) text-fg-subtle\"\n      >\n        {cell}\n      </Panel>\n    ))}\n  </Grid>\n</div>",
+      "note": "Fixed columns, or auto-fit from a minimum item width.",
+      "interaction": "none."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/group-bar.json

@@ -0,0 +1,102 @@
+{
+  "name": "GroupBar",
+  "slug": "group-bar",
+  "group": "instruments",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "The distribution strip: one flex cell per group, weighted by its value.\n\nA stacked bar with no axis and no numbers — the shape *is* the reading. Three\nrules keep it honest:\n\n1. **Empty groups get no cell.** A minimum width is what makes a two-pixel\n   sliver visible, and a minimum width on a zero would draw a group that is\n   not there.\n2. **The percentages add to 100.** Shares are rounded by largest remainder,\n   so the legend never sums to 99 and never to 101.\n3. **Colour is never the only channel.** The strip is a `role=\"img\"` whose\n   accessible name spells the whole distribution out (WCAG 1.4.1); the legend\n   repeats it in text when there is room for one.\n\nThe cells are divided by the same 1px seam as `SeamList`, so a distribution\nstrip and a seam list sitting in the same panel share one hairline language.\n\nStatic markup — no `\"use client\"`.",
+  "props": [
+    {
+      "name": "items",
+      "type": "readonly GroupBarItem[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "The slices, in display order."
+    },
+    {
+      "name": "height",
+      "type": "number",
+      "required": false,
+      "defaultValue": "6",
+      "description": "Strip height in px at the 16px root, emitted as `rem`. Defaults to `6`."
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "What the distribution is *of*. Required in practice — it names the graphic."
+    },
+    {
+      "name": "legend",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": "false",
+      "description": "List the slices with their shares underneath the strip."
+    },
+    {
+      "name": "formatShare",
+      "type": "((share: number, item: GroupBarItem) => string)",
+      "required": false,
+      "defaultValue": "(share) => `${share}%`",
+      "description": "Format one share for the summary and the legend. Defaults to `\"42%\"`."
+    },
+    {
+      "name": "emptyLabel",
+      "type": "string",
+      "required": false,
+      "defaultValue": "no data",
+      "description": "What to say when every slice is empty. Defaults to `\"no data\"`."
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-busy",
+    "--cue-danger",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-info",
+    "--cue-ok",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-text-label",
+    "--cue-warn"
+  ],
+  "summary": "The distribution strip: one flex cell per group, weighted by its value.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<GroupBar\n  label=\"Universe load\"\n  items={[\n    { label: \"dimmers\", value: 212, tone: \"accent\" },\n    { label: \"movers\", value: 96, tone: \"info\" },\n    { label: \"free\", value: 204 },\n  ]}\n  legend\n/>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/group-bar",
+  "mdUrl": "/docs/components/group-bar.md",
+  "jsonUrl": "/r/components/group-bar.json",
+  "specimens": [
+    {
+      "title": "GroupBar",
+      "group": "instruments",
+      "components": [
+        "GroupBar"
+      ],
+      "code": "<div className=\"flex w-full max-w-[36rem] flex-col gap-(--cue-space-5)\">\n  <GroupBar items={GROUP_ITEMS} label=\"Channel allocation by group\" />\n  <GroupBar items={[]} label=\"Empty allocation\" emptyLabel={COPY.empty.title} />\n</div>",
+      "note": "The distribution strip: one flex cell per item, coloured by tone, with a legend that names each share.",
+      "interaction": "none. It is a picture of a breakdown, and the legend is the text version of it."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/hover-card.json

@@ -0,0 +1,151 @@
+{
+  "name": "HoverCard",
+  "slug": "hover-card",
+  "group": "overlays",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A richer preview than a tooltip, revealed by hovering a link or a name: the\nfixture behind a profile string, the operator behind an initial.\n\nWraps Base UI's `PreviewCard`, which is the right primitive precisely because\nit is *not* a tooltip: the card is reachable — the pointer can travel into it\nand interact — and its content is not announced as the trigger's description.\n\nHover is the only way in, so the content here must always be a *convenience*.\nAnything a keyboard or touch user genuinely needs belongs in a `Popover`\n(a real trigger) or an `InfoTip` (a focusable badge).",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Trigger",
+    "Content"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "HoverCard.Root",
+      "description": "Groups the parts of a hover card and owns its open state. Renders no element.",
+      "props": [
+        {
+          "name": "closeOnWheel",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Close the card when the viewport moves under it — a wheel anywhere outside\nthe popup, or a window resize. Defaults to `true`, for the same reason as\n`Popover`: an anchored popup is placed from its trigger's rect, and a canvas\nthat pans by CSS transform fires no `scroll` event."
+        }
+      ],
+      "typeReferences": [
+        "BasePreviewCard.Root.Props"
+      ]
+    },
+    {
+      "name": "Trigger",
+      "usage": "HoverCard.Trigger",
+      "description": "The thing being previewed — an `<a>` by default, because the pattern this\ncomponent exists for is \"what is behind this link\".\n\nDeliberately unstyled: a hover card must never change how the underlying link\nor name looks, or the page grows a second kind of underline.\n\nThe hover intent lives here rather than on the root, because Base UI supports\nseveral triggers sharing one card: `delay` (600ms) is how long the pointer\nmust rest, `closeDelay` (300ms) how long it may wander off before the card\ngoes.",
+      "props": [],
+      "typeReferences": [
+        "BasePreviewCard.Trigger.Props"
+      ]
+    },
+    {
+      "name": "Content",
+      "usage": "HoverCard.Content",
+      "description": "The card's portal, positioner and popup.\n\nPortalled through {@link useCuePortalProps}, so the surface renders at the\ncaller's theme and density. The hover intent — open delay, close delay, the\nsafe triangle between trigger and popup — is Base UI's.",
+      "props": [
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the popup surface."
+        },
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\"",
+          "required": false,
+          "defaultValue": null,
+          "description": "Alignment along that side. Defaults to `\"center\"`."
+        },
+        {
+          "name": "keepMounted",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Keep the popup mounted while closed."
+        },
+        {
+          "name": "positionerClassName",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Extra classes for the positioner that places the popup."
+        },
+        {
+          "name": "sideOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": "4",
+          "description": "Gap in px between trigger and popup. Defaults to `4`."
+        },
+        {
+          "name": "side",
+          "type": "\"left\" | \"right\" | \"top\" | \"bottom\" | \"inline-end\" | \"inline-start\"",
+          "required": false,
+          "defaultValue": null,
+          "description": "Preferred side of the trigger. Defaults to `\"bottom\"`."
+        },
+        {
+          "name": "alignOffset",
+          "type": "number | OffsetFunction",
+          "required": false,
+          "defaultValue": null,
+          "description": "Nudge along the alignment axis, in px."
+        }
+      ],
+      "typeReferences": [
+        "Omit<BasePreviewCard.Popup.Props, \"className\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent-soft",
+    "--cue-border",
+    "--cue-border-overlay",
+    "--cue-control-sm",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-radius-overlay",
+    "--cue-scrim",
+    "--cue-space-1",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-surface-2",
+    "--cue-text-emphasis",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A richer preview than a tooltip, revealed by hovering a link or a name: the fixture behind a profile string, the operator behind an initial.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<HoverCard.Root>\n  <HoverCard.Trigger href=\"/fixtures/mac-aura\">MAC Aura XIP</HoverCard.Trigger>\n  <HoverCard.Content>\n    <Stat label=\"Channels\" value=\"21\" />\n  </HoverCard.Content>\n</HoverCard.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/hover-card",
+  "mdUrl": "/docs/components/hover-card.md",
+  "jsonUrl": "/r/components/hover-card.json",
+  "specimens": [
+    {
+      "title": "HoverCard",
+      "group": "overlays",
+      "components": [
+        "HoverCard"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"default\">\n    <HoverCard.Root>\n      <HoverCard.Trigger href=\"#front-wash\">Front wash</HoverCard.Trigger>\n      <HoverCard.Content className=\"w-[18rem]\">\n        <div className=\"flex flex-col gap-(--cue-space-2)\">\n          <span className=\"font-mono text-(length:--cue-text-emphasis) text-fg\">\n            Front wash\n          </span>\n          <span className=\"font-mono text-(length:--cue-text-ui) text-fg-muted\">\n            6 × Source Four 26°, universe 1, channels 1 to 48.\n          </span>\n          <StatusDot tone=\"ok\" label=\"Patched\" />\n        </div>\n      </HoverCard.Content>\n    </HoverCard.Root>\n  </Specimen>\n</Specimens>",
+      "note": "A preview card: richer than a tooltip, and never the only way to reach the information.",
+      "interaction": "opens on hover after a delay and on focus; the card itself is hoverable, so a link inside it is reachable."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/icon-button.json

@@ -0,0 +1,88 @@
+{
+  "name": "IconButton",
+  "slug": "icon-button",
+  "group": "primitives",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A square, icon-only button for toolbars, row affordances and panel headers.\n\nDefaults to the `ghost` variant: in a dense console most icon buttons should\nbe invisible until hovered, speaking through text colour rather than a rim.",
+  "props": [
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": true,
+      "defaultValue": null,
+      "description": "Required. An icon-only control has no text to name it, so the label is not\noptional — the type makes forgetting it a compile error."
+    },
+    {
+      "name": "icon",
+      "type": "ElementType<any, keyof IntrinsicElements>",
+      "required": true,
+      "defaultValue": null,
+      "description": "The icon component to render (e.g. a lucide icon). Rendered `aria-hidden`\nand sized to the density icon token."
+    },
+    {
+      "name": "render",
+      "type": "RenderProp<Record<string, unknown>>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Replace the rendered element (Base UI render prop)."
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": "md",
+      "description": ""
+    }
+  ],
+  "typeReferences": [
+    "Omit<React.ComponentPropsWithoutRef<\"button\">, \"children\">",
+    "VariantProps<typeof iconButtonVariants>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "defaultVariants": {
+    "variant": "ghost",
+    "size": "md"
+  },
+  "tokensUsed": [
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-icon-md",
+    "--cue-icon-sm"
+  ],
+  "summary": "A square, icon-only button for toolbars, row affordances and panel headers.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<IconButton aria-label=\"Close panel\" icon={X} />\n<IconButton aria-label=\"Delete cue\" icon={Trash} variant=\"danger-outline\" size=\"sm\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/icon-button",
+  "mdUrl": "/docs/components/icon-button.md",
+  "jsonUrl": "/r/components/icon-button.json",
+  "specimens": [
+    {
+      "title": "IconButton",
+      "group": "primitives",
+      "components": [
+        "IconButton"
+      ],
+      "code": "<Specimens>\n  {BUTTON_VARIANTS.map((variant) => (\n    <Specimen key={variant} label={variant}>\n      <IconButton aria-label={`Play, ${variant}`} icon={Play} variant={variant} />\n    </Specimen>\n  ))}\n  <Specimen label=\"disabled\">\n    <IconButton aria-label=\"Delete cue\" icon={Trash2} disabled />\n  </Specimen>\n  {SIZES.map((size) => (\n    <Specimen key={size} label={`size ${size}`}>\n      <IconButton aria-label={`Pause, ${size}`} icon={Pause} size={size} />\n    </Specimen>\n  ))}\n</Specimens>",
+      "note": "A square button with a required accessible name. There is no unlabelled variant.",
+      "interaction": "same ring as Button; the hit target stays at the control height even when the glyph shrinks."
+    }
+  ],
+  "todo": true
+}