@cueplusplus/ui 0.13.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/flow-graph.json

@@ -0,0 +1,86 @@
+{
+  "name": "FlowGraph",
+  "slug": "flow-graph",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Work as a graph rather than a list: branches that fan out and rejoin.",
+  "props": [
+    {
+      "name": "nodes",
+      "type": "readonly FlowNode[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Every node with its grid position. Layout is explicit; the element runs no solver.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.flow-nodes"
+      }
+    },
+    {
+      "name": "edges",
+      "type": "readonly FlowEdge[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Connections by node id. An edge dims until both of its ends are visible.",
+      "control": {
+        "kind": "array",
+        "fixture": "agents.flow-edges"
+      }
+    },
+    {
+      "name": "visibleCount",
+      "type": "number",
+      "required": true,
+      "defaultValue": null,
+      "description": "How many nodes have been reached so far.",
+      "control": {
+        "kind": "number"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<\n  ComponentProps<\"div\">,\n  \"children\" | \"nodes\" | \"edges\" | \"visibleCount\"\n> & {\n  /** Every node with its grid position. Layout is explicit; the element runs no solver. */\n  nodes: readonly FlowNode[];\n  /** Connections by node id. An edge dims until both of its ends are visible. */\n  edges: readonly FlowEdge[];\n  /** How many nodes have been reached so far. */\n  visibleCount: number;\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-fg",
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-radius-overlay",
+    "--cue-radius-surface",
+    "--cue-stream",
+    "--cue-surface-1",
+    "--cue-text-ui"
+  ],
+  "summary": "Work as a graph rather than a list: branches that fan out and rejoin.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { FlowGraph } from \"@cueplusplus/ui/elements\";\n\n<FlowGraph nodes={nodes} edges={edges} visibleCount={nodes.length} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/flow-graph",
+  "mdUrl": "/docs/components/flow-graph.md",
+  "jsonUrl": "/r/components/flow-graph.json",
+  "specimens": [
+    {
+      "title": "FlowGraph",
+      "group": "elements-agents",
+      "components": [
+        "FlowGraph"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"partway\" wide>\n    <FlowGraph nodes={FLOW_NODES} edges={FLOW_EDGES} visibleCount={4} />\n  </Specimen>\n  <Specimen label=\"the whole graph\" wide>\n    <FlowGraph\n      nodes={FLOW_NODES.map((node) => ({ ...node, state: \"done\" as const }))}\n      edges={FLOW_EDGES}\n      visibleCount={FLOW_NODES.length}\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Work as a graph rather than a list, for the runs that fan out and rejoin — here the two trusses are patched in parallel and the render waits for both. Layout is explicit: every node carries its own column and row and the element runs no solver, which is what keeps a re-render from rearranging a diagram somebody was reading.",
+      "interaction": "none. `visibleCount` is what makes the graph arrive a node at a time, and an edge stays dim until both of its ends have been reached."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/folder-icon.json

@@ -0,0 +1,46 @@
+{
+  "name": "FolderIcon",
+  "slug": "folder-icon",
+  "group": "icons",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": false,
+  "description": "A folder somebody made: a shelf of bookmarks, filed by hand.\n\nThe tab is the whole glyph. A plain rounded box in this library is a panel,\na card or a dialog, and the one thing a folder has to say is that a person\nput these here on purpose rather than a query having returned them.",
+  "props": [],
+  "typeReferences": [
+    "React.SVGProps<SVGSVGElement>"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [],
+  "summary": "A folder somebody made: a shelf of bookmarks, filed by hand.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/folder-icon",
+  "mdUrl": "/docs/components/folder-icon.md",
+  "jsonUrl": "/r/components/folder-icon.json",
+  "specimens": [
+    {
+      "title": "The container icon set",
+      "group": "icons",
+      "components": [
+        "CatalogueIcon",
+        "StackIcon",
+        "StacksMatrixIcon",
+        "AudienceIcon",
+        "ChannelReleasedIcon",
+        "ChannelBetaIcon",
+        "FolderIcon",
+        "McpServerIcon",
+        "CliToolIcon",
+        "SkillIcon"
+      ],
+      "code": "<Specimens>\n  {CONTAINERS.map(([label, name, Icon]) => (\n    <Specimen key={name} label={label}>\n      <Icon className=\"size-icon-md text-fg\" />\n    </Specimen>\n  ))}\n</Specimens>\n<Specimens>\n  <Specimen label=\"icon-sm\">\n    <SkillIcon className=\"size-icon-sm text-fg\" />\n  </Specimen>\n  <Specimen label=\"icon-md\">\n    <SkillIcon className=\"size-icon-md text-fg\" />\n  </Specimen>\n  <Specimen label=\"inherited\">\n    <SkillIcon className=\"size-icon-md\" />\n  </Specimen>\n  <Specimen label=\"muted\">\n    <SkillIcon className=\"size-icon-md text-fg-muted\" />\n  </Specimen>\n  <Specimen label=\"accent\">\n    <SkillIcon className=\"size-icon-md text-accent\" />\n  </Specimen>\n  <Specimen label=\"danger\">\n    <SkillIcon className=\"size-icon-md text-danger\" />\n  </Specimen>\n</Specimens>\n<Specimens>\n  <Specimen label=\"in a row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg-muted\">\n      <ChannelReleasedIcon className=\"size-icon-md shrink-0\" />\n      Our skills · released\n    </span>\n  </Specimen>\n  <Specimen label=\"current row\" wide>\n    <span className=\"inline-flex items-center gap-(--cue-space-2) font-mono text-(length:--cue-text-ui) text-fg\">\n      <ChannelBetaIcon className=\"size-icon-md shrink-0\" />\n      Our skills · beta\n    </span>\n  </Specimen>\n</Specimens>",
+      "note": "One grid and one weight across all ten, at size-icon-md — the size a navigation row draws them at. Each is a plain <svg> that takes every SVG prop.",
+      "interaction": "none. They are decorative by default: aria-hidden, announced by nothing, because the row they mark already carries its name."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/footer.json

@@ -0,0 +1,133 @@
+{
+  "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\nUnder the skin this **is** `Band`'s recipe — `separation=\"rule\"`, spent\nthrough `bandClasses` rather than through `<Band>` itself, because `Band`\nrenders a `<section>` and this has to render the `<footer>` that makes it the\n`contentinfo` landmark. The two dimensions that recipe carries are the\nrhythm and the rule, and both are the style axis's now, the same as any other\nband: see `separation`'s table on `Band` for what each `[data-style]` set\nmakes them paint. With no set active nothing changes from what this component\nalways rendered. It does **not** reach `Band`'s other two style-owned\nspends — the ground and the reading measure — because `separation` is the\nliteral `\"rule\"` here and `width` is a `ContainerWidth`; `_band.ts`'s\ndocblock says why that is a fact about the published manifest and not only\nabout the markup.\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.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "narrow",
+          "wide",
+          "broad",
+          "full"
+        ]
+      }
+    },
+    {
+      "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.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "columnClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the centred column inside the landmark.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "children",
+      "type": "ReactNode",
+      "required": false,
+      "defaultValue": null,
+      "description": "The footer's body — normally a `Grid` of `Stack`s of `Link`s.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [
+    "React.ComponentPropsWithoutRef<\"footer\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-band-rule",
+    "--cue-band-y",
+    "--cue-border",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-space-3",
+    "--cue-space-5",
+    "--cue-space-6",
+    "--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/frac.json

@@ -0,0 +1,68 @@
+{
+  "name": "Frac",
+  "slug": "frac",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A fraction inside an expression — numerator, rule, denominator — set inline and\naligned to the middle.",
+  "props": [
+    {
+      "name": "over",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Numerator.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    },
+    {
+      "name": "under",
+      "type": "ReactNode",
+      "required": true,
+      "defaultValue": null,
+      "description": "Denominator.",
+      "control": {
+        "kind": "node",
+        "fixture": "children.text"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border-strong",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-radius-overlay",
+    "--cue-text-emphasis"
+  ],
+  "summary": "A fraction inside an expression — numerator, rule, denominator — set inline and aligned to the middle.",
+  "examples": [],
+  "status": "todo-docs",
+  "url": "/docs/components/frac",
+  "mdUrl": "/docs/components/frac.md",
+  "jsonUrl": "/r/components/frac.json",
+  "specimens": [
+    {
+      "title": "MathBlock",
+      "group": "elements-knowledge",
+      "components": [
+        "MathBlock",
+        "Frac",
+        "Sub",
+        "Sup"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"worked through\" wide>\n    <MathBlock label=\"illuminance at the deck\" steps={MATH} visibleSteps={3} />\n  </Specimen>\n  <Specimen label=\"first step only\" wide>\n    <MathBlock steps={MATH} visibleSteps={1} />\n  </Specimen>\n</Specimens>",
+      "note": "Maths with the working shown, a step at a time. The expressions are nodes rather than a string, so there is no parser and no KaTeX in the bundle — `Frac` stacks a numerator over a rule, `Sup` and `Sub` set an index upright inside the serif italic, and anything else is text.",
+      "interaction": "none. Each step's note says what justified it, which is what turns three lines of algebra into an explanation."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/frames.json

@@ -0,0 +1,210 @@
+{
+  "name": "Frames",
+  "slug": "frames",
+  "group": "layout",
+  "importPath": "@cueplusplus/ui",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "A design canvas: frames side by side, each holding one axis of one component.\n\n`Frames.Root` is the canvas — short, wide, scrollable sideways, focusable,\nand pannable with the pointer. `Frames.Item` is one captioned cell, and it is\nused **inside a `Preview`** rather than inside the Root. The two are apart\nbecause that is how they are used, and a props-only API cannot say it.\n\n**The canvas knows nothing about its children.** It does not count them, does\nnot index them and does not select one; `hint` is where a caller puts what it\nknows. A canvas that knew its frames would be a manifest API, and this is a\nslot API.",
+  "props": [],
+  "typeReferences": [],
+  "subcomponents": [
+    "Root",
+    "Item"
+  ],
+  "parts": [
+    {
+      "name": "Root",
+      "usage": "Frames.Root",
+      "description": "The canvas: a short, wide, focusable scroll region that holds frames.\n\n**It knows nothing about its children.** It does not count them, index them\nor select one — a canvas that knew its frames would be a manifest API, and\nthis is a slot API. `hint` is where a caller puts the count it knows and this\ndoes not.",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "defaultValue": null,
+          "description": "The frames. Anything — this never inspects them.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": true,
+          "defaultValue": null,
+          "description": "The canvas's accessible name — \"Button frames\". Required: the canvas is a\nfocusable scroll region, and a scroll region with no name is one a screen\nreader announces as nothing.",
+          "control": {
+            "kind": "string"
+          }
+        },
+        {
+          "name": "height",
+          "type": "\"short\" | \"tall\"",
+          "required": false,
+          "defaultValue": "short",
+          "description": "`\"short\"` is 18.5rem, `\"tall\"` 27rem. A CSS length in `style` overrides both.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "short",
+              "tall"
+            ]
+          }
+        },
+        {
+          "name": "ground",
+          "type": "\"none\" | \"plain\" | \"dots\"",
+          "required": false,
+          "defaultValue": "dots",
+          "description": "The canvas ground. Defaults to `\"dots\"`.",
+          "control": {
+            "kind": "enum",
+            "members": [
+              "none",
+              "plain",
+              "dots"
+            ]
+          }
+        },
+        {
+          "name": "hint",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The line in the bottom-right corner — \"drag to pan · 8 frames\". Unset, none is drawn.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "pan",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "true",
+          "description": "Drag-to-pan with the pointer. Defaults to `true`. A drag that starts on a\ncontrol is never a pan, so a frame's own controls stay usable — and \"on a\ncontrol\" counts the control's own contents: the words inside a\n`role=\"menuitem\"` row, the icon inside a `button`. A drag inside a\nrole-bearing box that is not itself a control — a `role=\"group\"` frame, a\n`role=\"region\"` — still pans, because a frame is such a box and a board is\nmostly frames. Only the primary button drags; `false` binds no pointer\nlistener at all; and the keyboard scrolls the canvas either way.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "Omit<React.ComponentPropsWithoutRef<\"div\">, \"children\">"
+      ]
+    },
+    {
+      "name": "Item",
+      "usage": "Frames.Item",
+      "description": "One captioned cell of a frame.\n\n**It is used inside a `Preview`, not inside `Frames.Root`** — that is the\nwhole reason this is a compound rather than a props API: the canvas holds\nframes, a frame holds a stage, and the stage holds these. `Frames.Root` never\nlooks for one.\n\n**A stage does not arrange them, and the caller does.** A stage is a centred\ngrid in both presentations, so two items left to it stack; the row every\nexample here draws is `<div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">`,\nand `items-end` is what lines the captions up when the specimens are\ndifferent heights.",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "defaultValue": null,
+          "description": "The specimen.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "caption",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "The line under it. Hidden — not removed — when the frame sets `captions={false}`.",
+          "control": {
+            "kind": "node",
+            "fixture": "children.text"
+          }
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": "false",
+          "description": "Draws the selection outline the frame gives the item a reader is inspecting.",
+          "control": {
+            "kind": "boolean"
+          }
+        }
+      ],
+      "typeReferences": [
+        "React.ComponentPropsWithoutRef<\"div\">"
+      ]
+    }
+  ],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-border",
+    "--cue-fg-subtle",
+    "--cue-font-mono",
+    "--cue-hair-strong",
+    "--cue-radius-control",
+    "--cue-radius-surface",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-6",
+    "--cue-space-8",
+    "--cue-surface-1",
+    "--cue-text-micro"
+  ],
+  "summary": "A design canvas: frames side by side, each holding one axis of one component. Short, wide, scrollable sideways, focusable, and pannable with the pointer.",
+  "examples": [
+    {
+      "title": "A short board that pans",
+      "code": "<Frames.Root label=\"Button frames\" hint=\"drag to pan · 2 frames\">\n  <Preview presentation=\"frame\" label=\"Tone\" count={2}>\n    <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n      <Frames.Item caption=\"accent\">\n        <Button variant=\"primary\">Take cue</Button>\n      </Frames.Item>\n      <Frames.Item caption=\"default\">\n        <Button>Take cue</Button>\n      </Frames.Item>\n    </div>\n  </Preview>\n</Frames.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "Tall, flat, and still",
+      "code": "<Frames.Root label=\"Grid frames\" height=\"tall\" ground=\"plain\" pan={false}>\n  <Preview presentation=\"frame\" label=\"Columns\" count={3} captions={false}>\n    …\n  </Preview>\n</Frames.Root>",
+      "language": "tsx"
+    },
+    {
+      "title": "Usage",
+      "code": "<Frames.Root label=\"Button frames\" hint=\"drag to pan · 3 frames\">\n  <Preview presentation=\"frame\" label=\"Tone\" count={3} name={<ToneMenu />}>\n    <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n      <Frames.Item caption=\"accent\"><Button tone=\"accent\">Take cue</Button></Frames.Item>\n      <Frames.Item caption=\"ok\"><Button tone=\"ok\">Take cue</Button></Frames.Item>\n      <Frames.Item caption=\"warn\"><Button tone=\"warn\">Take cue</Button></Frames.Item>\n    </div>\n  </Preview>\n</Frames.Root>",
+      "language": "tsx"
+    }
+  ],
+  "status": "stable",
+  "url": "/docs/components/frames",
+  "mdUrl": "/docs/components/frames.md",
+  "jsonUrl": "/r/components/frames.json",
+  "whenToUse": [
+    "Showing a component's axes at once — one frame per axis, each with its own name row and its own settings — instead of one preview a reader has to re-configure.",
+    "Any short, wide board of specimens a reader scans rather than reads: a theme sheet, a size ladder, a state matrix.",
+    "Beside `Preview presentation=\"frame\"`, which is what a frame on this canvas is."
+  ],
+  "whenNotToUse": [
+    "Laying components out in a page. That is `Grid` or `Bento`; a canvas is a viewport that scrolls, and everything in it is off-screen by design.",
+    "A board a reader zooms. This does not zoom, and it will not: a transformed subtree breaks every popover anchored inside it.",
+    "Scrolling down. The canvas is `overflow-y: hidden` on purpose — it is short and wide, not a second page."
+  ],
+  "commonMistakes": [
+    "Putting `Frames.Item` inside `Frames.Root`. The item belongs on a frame's stage — `Frames.Root` holds frames, and a frame is a `Preview`.",
+    "Expecting a frame to arrange its items. A stage is a centred grid in both presentations, so two items stack; put them in a row yourself — the row is `<div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">`, and every example here uses exactly that one.",
+    "Leaving `label` off, or repeating the page's heading in it. The canvas is a focusable scroll region, and its name is what a screen reader announces when a reader tabs into it.",
+    "Expecting the canvas to count its frames. It never inspects its children — pass the count yourself, in `hint`.",
+    "Expecting a long `caption` to wrap or to ellipsise on its own. A cell does not shrink, so a caption longer than its specimen widens the cell instead, and the wrapping row it sits in wraps a cell sooner — the `truncate` on the caption has no narrower box to fire in. Bound the cell yourself when a caption can run long: `<Frames.Item className=\"max-w-[12rem]\" caption=\"…\">`.",
+    "Reading `captions={false}` as a way to take a caption out of the page. It is visual only — the caption goes to `opacity: 0` and stops taking pointer events, keeping its box so nothing re-flows and keeping its place in the accessibility tree, so a screen reader still reads it. Delete the `caption` prop if the words should not be there at all."
+  ],
+  "specimens": [
+    {
+      "title": "Frames",
+      "group": "layout",
+      "components": [
+        "Frames"
+      ],
+      "code": "<Frames.Root\n  label=\"Button frames\"\n  hint=\"drag to pan · 2 frames\"\n  className=\"w-full\"\n>\n  <Preview\n    label=\"Button tone\"\n    presentation=\"frame\"\n    count={3}\n    tools={<Chip variant=\"outline\">tone</Chip>}\n  >\n    <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n      <Frames.Item caption=\"accent\" selected>\n        <Button variant=\"primary\">Take cue</Button>\n      </Frames.Item>\n      <Frames.Item caption=\"default\">\n        <Button>Take cue</Button>\n      </Frames.Item>\n      <Frames.Item caption=\"subtle\">\n        <Button variant=\"ghost\">Take cue</Button>\n      </Frames.Item>\n    </div>\n  </Preview>\n  <Preview label=\"Button density\" presentation=\"frame\" count={2} captions={false}>\n    <div className=\"flex flex-wrap items-end gap-(--cue-space-6)\">\n      <Frames.Item caption=\"compact\">\n        <Button size=\"sm\">Go</Button>\n      </Frames.Item>\n      <Frames.Item caption=\"normal\">\n        <Button>Go</Button>\n      </Frames.Item>\n    </div>\n  </Preview>\n</Frames.Root>",
+      "note": "A design canvas: frames side by side, each holding one axis of one component. The canvas is a focusable scroll region; a frame is a `Preview` in its `frame` presentation, with its name row above the stage and four crosshairs at the corners; an item is one captioned cell on that stage.",
+      "interaction": "the canvas scrolls sideways: click it and Left and Right step one rung of the space ladder, PageUp and PageDown a viewport, Home and End the two ends. Dragging it pans it — except a drag that starts on a control, which stays a click. `pan={false}` turns the dragging off and leaves the keyboard."
+    }
+  ]
+}