@cueplusplus/ui 0.11.1 → 0.12.0

package/dist/layout/preview.js

@@ -4,6 +4,7 @@ import { useIsomorphicLayoutEffect } from "../system/use-isomorphic-layout-effec
 import { AmbientThemeContext, DensityContext } from "../system/density.js";
 import { OverridesContext } from "../system/overrides.js";
 import { ThemeContext } from "../system/theme-provider.js";
+import { GROUND_CLASSES } from "./_ground.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/layout/preview.tsx
@@ -20,16 +21,29 @@ const BIG_STEP = 64;
 const ROOT_CLASS = "relative flex min-w-0 flex-col rounded-(--radius-surface) border border-border bg-surface-1 text-fg";
 const BENCH_CLASS = "relative flex min-w-0 flex-1 overflow-auto rounded-t-(--radius-surface)";
 /**
-* The stage: centred, dotted in the stage's own `--cue-hair-strong`, and at
-* least three top rungs of the space ladder tall so a preview reserves its room
-* before its specimen arrives. Static literals, because Tailwind scans text.
+* The stage: centred, grounded, and at least three top rungs of the space
+* ladder tall so a preview reserves its room before its specimen arrives.
+* Static literals, because Tailwind scans text.
 *
 * Centred **safely** (`place-items: safe center`): a specimen wider than the
 * stage starts at the stage's edge and overflows at its end, where the bench
 * scrolls to it. Plain `center` split the overflow across both sides, and the
 * left half sat before the scroll origin, where nothing reaches it.
+*
+* **Three pieces rather than one literal, and the seam is where the ground
+* goes.** `cn` preserves the order it is given, so a ground appended after the
+* padding would emit the dot grid in a different place from the one every
+* caller's markup has today — and `/`'s seventeen bare Previews and the group
+* pages' 325 tooled ones are both measured to the byte. Head, ground, tail, in
+* that order, is today's string.
 */
-const STAGE_CLASS = "grid h-full w-full min-h-[calc(var(--cue-space-8)*3)] place-items-center-safe bg-surface-1 bg-[radial-gradient(circle,var(--cue-hair-strong)_1px,transparent_1.3px)] bg-[length:14px_14px] p-(--cue-space-6) text-fg";
+const STAGE_HEAD = "grid h-full w-full min-h-[calc(var(--cue-space-8)*3)] place-items-center-safe";
+const STAGE_TAIL = "p-(--cue-space-6) text-fg";
+/** Which ground a presentation paints when the caller names none (spec §4.1). */
+const DEFAULT_GROUND = {
+	panel: "dots",
+	frame: "none"
+};
 const TOOLS_CLASS = "absolute top-(--cue-space-2) right-(--cue-space-2) z-10 flex items-center gap-px rounded-(--radius-control) border border-border bg-surface-2 p-px";
 /**
 * The room the tools take, kept clear on the stage — only when there are tools.
@@ -52,6 +66,79 @@ const TOOLS_CLASS = "absolute top-(--cue-space-2) right-(--cue-space-2) z-10 fle
 const TOOLS_RESERVE_BENCH = "[--preview-tools-clear:calc(var(--cue-space-2)*2+var(--cue-control-sm)+4px)]";
 const TOOLS_RESERVE_STAGE = "pt-(--preview-tools-clear)";
 const FOOTER_CLASS = "flex min-w-0 items-center gap-(--cue-space-2) border-t border-border px-(--cue-space-4) py-(--cue-space-2)";
+/**
+* A frame's root: no card, no border, no fill. The frame is a thing on a
+* canvas, and the canvas is what paints. `shrink-0` because a canvas is a flex
+* row that scrolls, and a frame that shrank to fit would defeat the scrolling.
+*/
+const FRAME_ROOT_CLASS = "relative flex min-w-0 shrink-0 flex-col gap-(--cue-space-2) text-fg";
+/**
+* A frame's footer: the same row as a panel's, without the rule across the top
+* or the card's horizontal padding — there is no card for either to belong to.
+*/
+const FRAME_FOOTER_CLASS = "flex min-w-0 items-center gap-(--cue-space-2) text-(length:--cue-text-micro) text-fg-subtle";
+/** The row above a frame's stage: the name (or its control), the count, and the tools. */
+const FRAME_LABEL_CLASS = "flex min-w-0 items-center gap-(--cue-space-2) text-(length:--cue-text-label) text-fg-muted";
+/** The name when the caller passed no control for it — the frame's `label`, as text. */
+const FRAME_NAME_CLASS = "min-w-0 truncate font-mono text-(length:--cue-text-label) text-fg";
+/** The count beside it: quieter, and never allowed to shrink the name's truncation away. */
+const FRAME_COUNT_CLASS = "shrink-0 font-mono text-(length:--cue-text-micro) text-fg-subtle";
+/**
+* A frame's tools: pushed to the row's end, and carrying none of the panel's
+* overlay chrome. A frame's stage is transparent, so a toolbar drawn over it
+* would float on the canvas ground with nothing behind it (spec §4.1 Decision 2).
+*/
+const FRAME_TOOLS_CLASS = "ml-auto flex shrink-0 items-center gap-px";
+/**
+* The box that holds the bench and the four marks.
+*
+* One more element than the spec's Decision 3 priced, and it is not avoidable.
+* The bench is `overflow-auto`: a mark positioned inside it is clipped at the
+* padding box and scrolls with the content. The frame's root is no good either
+* — its first child is the label row, so the root's top-left corner is the
+* label's and not the stage's. So the frame gets one `relative` box whose
+* borders are exactly the stage's, and the marks hang off that.
+*/
+const FRAME_BOX_CLASS = "relative flex min-w-0 flex-col";
+/**
+* Captions off, as properties the item reads rather than a prop each item takes.
+*
+* A reader turns captions off for a whole frame from its settings popover,
+* never for one item — so the switch is on the frame and the item obeys it
+* through inheritance.
+*
+* **`opacity: 0`, and deliberately not `visibility: hidden`.** §4.1 Decision 4
+* refuses "removing a hidden caption from the accessibility tree", and
+* `visibility: hidden` does exactly that — a browser drops such a node as
+* surely as it drops a `display: none` one. Zero opacity keeps the box, so
+* nothing re-flows, *and* keeps the caption announced, which is what the
+* refusal is for: the caption is what names the specimen for a reader who
+* cannot see the difference between two of them.
+*
+* **Two properties, declared together here so the pair is never half-applied.**
+* Custom properties are untyped text: `opacity` wants a number and
+* `pointer-events` wants a keyword, so one property cannot carry both. The
+* second is what stops an unpainted caption being clicked, or a drag across the
+* stage selecting words nobody can see.
+*/
+const CAPTIONS_OFF = "[--preview-captions:0] [--preview-captions-pe:none]";
+/**
+* One corner mark: an 11×11 box with a one-pixel cross drawn as two linear
+* gradients — a vertical hairline and a horizontal one — so the mark is a
+* background and not four more elements.
+*
+* Not a border and not an SVG. A border would have to be on the stage, and the
+* stage is the theme island: a frame's chrome that moved with a stage theme is
+* the one thing ruling 7 forbids.
+*/
+const CROSS_CLASS = "pointer-events-none absolute z-10 size-[11px] bg-[linear-gradient(var(--cue-fg-subtle),var(--cue-fg-subtle)),linear-gradient(var(--cue-fg-subtle),var(--cue-fg-subtle))] bg-[length:1px_11px,11px_1px] bg-[position:center,center] bg-no-repeat";
+/** The four corners, each half outside the box so the cross straddles the corner. */
+const CROSS_CORNERS = [
+	"-top-[5px] -left-[5px]",
+	"-top-[5px] -right-[5px]",
+	"-bottom-[5px] -left-[5px]",
+	"-bottom-[5px] -right-[5px]"
+];
 const GRIP_FOCUS = "touch-none outline-none hover:bg-(--cue-border-strong) focus-visible:bg-accent";
 const GRIP_X_CLASS = `absolute top-0 right-0 z-10 h-full w-(--cue-space-2) cursor-col-resize ${GRIP_FOCUS}`;
 const GRIP_Y_CLASS = `absolute bottom-0 left-0 z-10 h-(--cue-space-2) w-full cursor-row-resize ${GRIP_FOCUS}`;
@@ -357,9 +444,18 @@ function Grips({ label, options, size }) {
 	] });
 }
 /**
-* A frame for one component: a stage that is its own theme island, a slot for
+* A card for one component: a stage that is its own theme island, a slot for
 * tools at the top right, and a footer.
 *
+* **Two presentations, one stage.** `"panel"`, the default and what every
+* existing caller gets, is that card: a border, a fill, a dot grid under the
+* specimen, and the tools floating over the stage's top right. `"frame"` is a
+* design-canvas frame — no card, no border, no fill; the name, the count and
+* the tools sit in a row *above* the stage rather than over it, four crosshairs
+* mark the stage's outer corners, and the stage paints nothing by default, so
+* whatever canvas the frame sits on shows through. Everything below holds in
+* both.
+*
 * **The stage is the island; the chrome is not.** `theme`, `mode`, `density`
 * and `font` land on the stage element only, and the stage republishes the
 * theme and density contexts so an overlay opened on it follows it. The tools,
@@ -375,7 +471,7 @@ function Grips({ label, options, size }) {
 * that is under `maxWidth`. Not `Resizable`, which is split panes on an
 * optional peer.
 *
-* Props, not a compound: one stage and two slots, each saying what it is.
+* Props, not a compound: one stage and its slots, each saying what it is.
 *
 * @example
 * <Preview label="Button preview" tools={<IconButton aria-label="Configure Button" icon={Wrench} />}>
@@ -385,8 +481,12 @@ function Grips({ label, options, size }) {
 * <Preview label="Chip preview" theme="terminal" density="compact" resizable>
 *   <Chip tone="accent">Standby</Chip>
 * </Preview>
+* @example
+* <Preview label="Button" presentation="frame" count={3}>
+*   <Button variant="primary">Take cue</Button>
+* </Preview>
 */
-const Preview = React.forwardRef(function Preview({ children, label, theme, mode, density, font, resizable, tools, footer, className, ...elementProps }, ref) {
+const Preview = React.forwardRef(function Preview({ children, label, theme, mode, density, font, resizable, tools, footer, presentation = "panel", name, count, ground, captions = true, className, ...elementProps }, ref) {
 	const outer = React.useContext(ThemeContext);
 	const bench = React.useRef(null);
 	const given = resolveResize(resizable);
@@ -399,10 +499,11 @@ const Preview = React.forwardRef(function Preview({ children, label, theme, mode
 		density,
 		font
 	}, outer);
+	const framed = presentation === "frame";
 	const stage = /* @__PURE__ */ jsx("div", {
 		"data-slot": "preview-stage",
 		...attributes,
-		className: cn(STAGE_CLASS, options !== null && "flex-1", tools !== void 0 && TOOLS_RESERVE_STAGE),
+		className: cn(STAGE_HEAD, GROUND_CLASSES[ground ?? DEFAULT_GROUND[presentation]], STAGE_TAIL, options !== null && "flex-1", !framed && tools !== void 0 && TOOLS_RESERVE_STAGE, !captions && CAPTIONS_OFF),
 		style: size.height === null ? void 0 : { minHeight: 0 },
 		children: /* @__PURE__ */ jsx(StageScope, {
 			theme,
@@ -411,6 +512,75 @@ const Preview = React.forwardRef(function Preview({ children, label, theme, mode
 			children
 		})
 	});
+	const benched = /* @__PURE__ */ jsx("div", {
+		ref: bench,
+		"data-slot": "preview-bench",
+		className: cn(BENCH_CLASS, footer === void 0 && "rounded-b-(--radius-surface)", !framed && tools !== void 0 && TOOLS_RESERVE_BENCH),
+		children: options === null ? stage : /* @__PURE__ */ jsxs("div", {
+			ref: size.sizer,
+			"data-slot": "preview-sizer",
+			className: cn("relative flex flex-col", size.width === null && "w-full"),
+			style: {
+				width: size.width === null ? void 0 : `${size.shownWidth}px`,
+				height: size.height === null ? void 0 : `${size.shownHeight}px`,
+				minWidth: `${options.minWidth}px`,
+				maxWidth: `${options.maxWidth}px`,
+				minHeight: `${options.minHeight}px`,
+				maxHeight: `${options.maxHeight}px`
+			},
+			children: [stage, /* @__PURE__ */ jsx(Grips, {
+				label,
+				options,
+				size
+			})]
+		})
+	});
+	if (framed) return /* @__PURE__ */ jsxs("div", {
+		...elementProps,
+		ref,
+		role: "group",
+		"aria-label": label,
+		"data-slot": "preview",
+		"data-presentation": "frame",
+		className: cn(FRAME_ROOT_CLASS, options !== null && "w-full", className),
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				"data-slot": "preview-frame-label",
+				className: FRAME_LABEL_CLASS,
+				children: [
+					name === void 0 ? /* @__PURE__ */ jsx("span", {
+						"data-slot": "preview-name",
+						className: FRAME_NAME_CLASS,
+						children: label
+					}) : name,
+					count === void 0 ? null : /* @__PURE__ */ jsx("span", {
+						"data-slot": "preview-count",
+						className: FRAME_COUNT_CLASS,
+						children: count
+					}),
+					tools === void 0 ? null : /* @__PURE__ */ jsx("div", {
+						"data-slot": "preview-tools",
+						className: FRAME_TOOLS_CLASS,
+						children: tools
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				"data-slot": "preview-frame",
+				className: FRAME_BOX_CLASS,
+				children: [benched, CROSS_CORNERS.map((corner) => /* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					"data-slot": "preview-crosshair",
+					className: cn(CROSS_CLASS, corner)
+				}, corner))]
+			}),
+			footer === void 0 ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "preview-footer",
+				className: FRAME_FOOTER_CLASS,
+				children: footer
+			})
+		]
+	});
 	return /* @__PURE__ */ jsxs("div", {
 		...elementProps,
 		ref,
@@ -419,29 +589,7 @@ const Preview = React.forwardRef(function Preview({ children, label, theme, mode
 		"data-slot": "preview",
 		className: cn(ROOT_CLASS, options !== null && "w-full", className),
 		children: [
-			/* @__PURE__ */ jsx("div", {
-				ref: bench,
-				"data-slot": "preview-bench",
-				className: cn(BENCH_CLASS, footer === void 0 && "rounded-b-(--radius-surface)", tools !== void 0 && TOOLS_RESERVE_BENCH),
-				children: options === null ? stage : /* @__PURE__ */ jsxs("div", {
-					ref: size.sizer,
-					"data-slot": "preview-sizer",
-					className: cn("relative flex flex-col", size.width === null && "w-full"),
-					style: {
-						width: size.width === null ? void 0 : `${size.shownWidth}px`,
-						height: size.height === null ? void 0 : `${size.shownHeight}px`,
-						minWidth: `${options.minWidth}px`,
-						maxWidth: `${options.maxWidth}px`,
-						minHeight: `${options.minHeight}px`,
-						maxHeight: `${options.maxHeight}px`
-					},
-					children: [stage, /* @__PURE__ */ jsx(Grips, {
-						label,
-						options,
-						size
-					})]
-				})
-			}),
+			benched,
 			tools === void 0 ? null : /* @__PURE__ */ jsx("div", {
 				"data-slot": "preview-tools",
 				className: TOOLS_CLASS,

package/dist/overlays/drawer.js

@@ -104,7 +104,7 @@ const Drawer$1 = {
 					children: [grabHandle ? /* @__PURE__ */ jsx("div", {
 						"data-slot": "drawer-grab-handle",
 						"aria-hidden": "true",
-						className: cn("shrink-0 rounded-(--radius-full) bg-border-strong", vertical ? "mx-auto my-(--cue-space-2) h-1 w-9" : "my-auto mx-(--cue-space-2) h-9 w-1")
+						className: cn("shrink-0 rounded-full bg-border-strong", vertical ? "mx-auto my-(--cue-space-2) h-1 w-9" : "my-auto mx-(--cue-space-2) h-9 w-1")
 					}) : null, /* @__PURE__ */ jsx(Drawer.Content, {
 						"data-slot": "drawer-content",
 						className: "flex min-h-0 flex-1 flex-col gap-(--cue-space-4) p-(--cue-space-6)",

package/dist/primitives/chip.d.ts

@@ -30,7 +30,7 @@ import * as React from "react";
  * <span className={chipVariants({ variant: "tag" })}>mcp</span>
  */
 declare const chipVariants: (props?: ({
-  tone?: "info" | "warn" | "danger" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
+  tone?: "danger" | "info" | "warn" | "accent" | "ok" | "busy" | "neutral" | null | undefined;
   variant?: "outline" | "tinted" | "tag" | null | undefined;
   interactive?: boolean | null | undefined;
 } & ClassProp) | undefined) => string;

package/manifest/components/bento.json

@@ -254,7 +254,7 @@
     "--cue-surface-1",
     "--cue-surface-2",
     "--cue-text-emphasis",
-    "--cue-text-meta"
+    "--cue-text-micro"
   ],
   "summary": "The unequal grid: tiles of different sizes on one set of tracks, from a closed set of spans.",
   "examples": [

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