@cueplusplus/ui 0.15.0 → 0.17.0

package/dist/layout/breadcrumb.js

@@ -1,4 +1,8 @@
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_OFFSET_2 } from "../system/_focus-ring.js";
+import { CONTROL_FACE } from "../system/_style-control-face.js";
+import { BODY_SIZE_LABEL } from "../system/_style-body-size.js";
+import { HELP_INK } from "../system/_style-help-ink.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/layout/breadcrumb.tsx
@@ -6,7 +10,7 @@ import { jsx, jsxs } from "react/jsx-runtime";
 * A crumb that goes somewhere. Muted until hovered, never underlined — the
 * trail is navigation furniture and should not read as body-copy links.
 */
-const CRUMB_LINK_CLASSES = "cursor-pointer rounded-(--radius-control) border-0 bg-transparent p-0 font-mono text-(length:--cue-text-label) text-fg-muted no-underline transition-colors duration-150 outline-none hover:text-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent";
+const CRUMB_LINK_CLASSES = `cursor-pointer rounded-control border-0 bg-transparent p-0 ${CONTROL_FACE} ${BODY_SIZE_LABEL} text-fg-muted no-underline transition-colors duration-150 outline-none hover:text-accent ${FOCUS_RING_OFFSET_2}`;
 /**
 * Where you are, and how to get back.
 *
@@ -28,13 +32,13 @@ const Breadcrumb = React.forwardRef(function Breadcrumb({ className, items, sepa
 		className: cn("min-w-0", className),
 		...elementProps,
 		children: /* @__PURE__ */ jsx("ol", {
-			className: "m-0 flex list-none flex-wrap items-center gap-(--cue-space-2) p-0 font-mono text-(length:--cue-text-label) text-fg-muted",
+			className: cn(`m-0 flex list-none flex-wrap items-center gap-(--cue-space-2) p-0 ${BODY_SIZE_LABEL} text-fg-muted`, CONTROL_FACE),
 			children: items.map((item, index) => {
 				const last = index === items.length - 1;
 				return /* @__PURE__ */ jsxs(React.Fragment, { children: [index === 0 ? null : /* @__PURE__ */ jsx("li", {
 					"data-slot": "breadcrumb-separator",
 					"aria-hidden": "true",
-					className: "text-fg-subtle select-none",
+					className: `${HELP_INK} select-none`,
 					children: separator
 				}), /* @__PURE__ */ jsx("li", {
 					"data-slot": "breadcrumb-item",

package/dist/layout/card.js

@@ -1,4 +1,12 @@
 import { cn } from "../lib/cn.js";
+import { BODY_VOICE } from "../system/_style-body.js";
+import { BODY_SIZE } from "../system/_style-body-size.js";
+import { RIM_INSET } from "../system/_paint-rim.js";
+import { TITLE_VOICE } from "../system/_style-title.js";
+import { SEAM_INK, SEAM_RIM } from "../system/_style-seam.js";
+import { STROKE_SURFACE_1 } from "../system/_paint-stroke-surface-1.js";
+import { CARD_PAD, CARD_PAD_BOTTOM, CARD_PAD_SEAM_BOTTOM, CARD_PAD_SEAM_TOP, CARD_PAD_TOP, CARD_PAD_X } from "../system/_style-card-pad.js";
+import { DESCRIPTION_LEADING, DESCRIPTION_TRACKING } from "../system/_style-description.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 /**
@@ -19,7 +27,7 @@ const Card = {
 			ref,
 			"data-slot": "card",
 			"data-seam": seam ? "" : void 0,
-			className: cn("group/card flex flex-col overflow-hidden rounded-(--radius-surface) border border-border", seam ? "gap-px bg-border" : "bg-surface-1", className),
+			className: cn("group/card flex flex-col overflow-hidden rounded-surface", seam ? `border ${SEAM_RIM} gap-px ${SEAM_INK}` : `${STROKE_SURFACE_1} ${RIM_INSET}`, className),
 			...elementProps
 		});
 	}),
@@ -27,7 +35,7 @@ const Card = {
 		return /* @__PURE__ */ jsxs("div", {
 			ref,
 			"data-slot": "card-header",
-			className: cn("flex items-start justify-between gap-(--cue-space-4) bg-surface-1 px-(--cue-space-5) pt-(--cue-space-5) pb-0 group-data-[seam]/card:pb-(--cue-space-5)", className),
+			className: cn(`flex items-start justify-between gap-(--cue-space-4) bg-surface-1 ${CARD_PAD_X} ${CARD_PAD_TOP} pb-0 ${CARD_PAD_SEAM_BOTTOM}`, className),
 			...elementProps,
 			children: [/* @__PURE__ */ jsx("div", {
 				className: "flex min-w-0 flex-col gap-(--cue-space-1)",
@@ -43,7 +51,7 @@ const Card = {
 		return /* @__PURE__ */ jsx("h3", {
 			ref,
 			"data-slot": "card-title",
-			className: cn("font-mono text-(length:--cue-text-emphasis) font-medium text-fg", className),
+			className: cn(TITLE_VOICE, className),
 			...elementProps
 		});
 	}),
@@ -51,7 +59,7 @@ const Card = {
 		return /* @__PURE__ */ jsx("p", {
 			ref,
 			"data-slot": "card-description",
-			className: cn("font-mono text-(length:--cue-text-ui) leading-(--cue-leading-ui) text-fg-muted", className),
+			className: cn(`${BODY_VOICE} ${BODY_SIZE} ${DESCRIPTION_LEADING} ${DESCRIPTION_TRACKING} text-fg-muted`, className),
 			...elementProps
 		});
 	}),
@@ -59,7 +67,7 @@ const Card = {
 		return /* @__PURE__ */ jsx("div", {
 			ref,
 			"data-slot": "card-content",
-			className: cn("bg-surface-1 p-(--cue-space-5)", className),
+			className: cn(`bg-surface-1 ${CARD_PAD}`, className),
 			...elementProps
 		});
 	}),
@@ -67,7 +75,7 @@ const Card = {
 		return /* @__PURE__ */ jsx("div", {
 			ref,
 			"data-slot": "card-footer",
-			className: cn("flex items-center justify-end gap-(--cue-space-3) bg-surface-1 px-(--cue-space-5) pt-0 pb-(--cue-space-5) group-data-[seam]/card:pt-(--cue-space-5)", className),
+			className: cn(`flex items-center justify-end gap-(--cue-space-3) bg-surface-1 ${CARD_PAD_X} pt-0 ${CARD_PAD_BOTTOM} ${CARD_PAD_SEAM_TOP}`, className),
 			...elementProps
 		});
 	})

package/dist/layout/carousel.js

@@ -1,5 +1,6 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_OFFSET_2 } from "../system/_focus-ring.js";
 import { IconButton } from "../primitives/icon-button.js";
 import { ChevronLeftGlyph, ChevronRightGlyph } from "./_glyphs.js";
 import * as React from "react";
@@ -118,7 +119,7 @@ const Carousel = {
 						scrollNext();
 					}
 				},
-				className: cn("relative outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent", className),
+				className: cn(`relative outline-none ${FOCUS_RING_OFFSET_2}`, className),
 				...elementProps,
 				children
 			})
@@ -202,7 +203,7 @@ const Carousel = {
 				"aria-label": dotLabel(index),
 				"aria-current": index === selectedIndex ? "true" : void 0,
 				onClick: () => scrollTo(index),
-				className: cn("size-[0.25rem] cursor-pointer rounded-full border-0 p-0 transition-colors duration-150 outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent motion-reduce:transition-none", index === selectedIndex ? "bg-accent" : "bg-border-strong")
+				className: cn(`size-[0.25rem] cursor-pointer rounded-full border-0 p-0 transition-colors duration-150 outline-none ${FOCUS_RING_OFFSET_2} motion-reduce:transition-none`, index === selectedIndex ? "bg-accent" : "bg-border-strong")
 			}, index))
 		});
 	})

package/dist/layout/collapsible.js

@@ -1,5 +1,9 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_OFFSET_2 } from "../system/_focus-ring.js";
+import { LABEL_FACE } from "../system/_style-label-face.js";
+import { LABEL_CASE } from "../system/_style-label-case.js";
+import { LABEL_TRACKING } from "../system/_style-label-tracking.js";
 import { collapseCaretClasses, collapseLabelClasses, collapsePanelBodyClasses, collapseTriggerClasses, collapsiblePanelClasses } from "./_collapse.js";
 import { ChevronRightGlyph } from "./_glyphs.js";
 import * as React from "react";
@@ -94,7 +98,7 @@ const Disclosure = React.forwardRef(function Disclosure({ className, label = "ad
 		children: [/* @__PURE__ */ jsxs(Collapsible.Trigger, {
 			ref,
 			"data-slot": "disclosure-trigger",
-			className: cn("group/disclosure inline-flex cursor-pointer items-center gap-(--cue-space-2) self-start border-0 bg-transparent p-0 py-(--cue-space-2) font-mono text-(length:--cue-text-label) tracking-(--cue-tracking-caps) text-fg-subtle uppercase transition-colors duration-150 outline-none select-none hover:text-fg-muted focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent", className),
+			className: cn(`group/disclosure inline-flex cursor-pointer items-center gap-(--cue-space-2) self-start border-0 bg-transparent p-0 py-(--cue-space-2) text-(length:--cue-text-label) text-fg-subtle transition-colors duration-150 outline-none select-none hover:text-fg-muted ${FOCUS_RING_OFFSET_2}`, LABEL_FACE, LABEL_TRACKING, LABEL_CASE, className),
 			...elementProps,
 			children: [
 				/* @__PURE__ */ jsx("span", {

package/dist/layout/container.js

@@ -1,4 +1,5 @@
 import { cn } from "../lib/cn.js";
+import { GUTTER } from "../system/_style-gutter.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/layout/container.tsx
@@ -35,7 +36,7 @@ const Container = React.forwardRef(function Container({ className, width = "narr
 	return /* @__PURE__ */ jsx("div", {
 		ref,
 		"data-slot": "container",
-		className: cn("mx-auto w-full", WIDTHS[width], padded ? "px-(--cue-space-6)" : null, className),
+		className: cn("mx-auto w-full", WIDTHS[width], padded ? GUTTER : null, className),
 		...elementProps
 	});
 });

package/dist/layout/description-list.js

@@ -1,4 +1,7 @@
 import { cn } from "../lib/cn.js";
+import { LABEL_FACE } from "../system/_style-label-face.js";
+import { LABEL_CASE } from "../system/_style-label-case.js";
+import { LABEL_TRACKING } from "../system/_style-label-tracking.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/layout/description-list.tsx
@@ -20,7 +23,7 @@ const DescriptionList = {
 		return /* @__PURE__ */ jsx("dt", {
 			ref,
 			"data-slot": "description-list-term",
-			className: cn("font-mono text-(length:--cue-text-label) tracking-(--cue-tracking-caps) text-fg-subtle uppercase", className),
+			className: cn("text-(length:--cue-text-label) text-fg-subtle", LABEL_FACE, LABEL_TRACKING, LABEL_CASE, className),
 			...elementProps
 		});
 	}),

package/dist/layout/frames.js

@@ -1,6 +1,12 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_INSET_2 } from "../system/_focus-ring.js";
+import { LABEL_INK_SUBTLE } from "../system/_style-label-ink.js";
+import { LABEL_FACE } from "../system/_style-label-face.js";
+import { LABEL_TRACKING_INHERIT } from "../system/_style-label-tracking.js";
+import { LABEL_SIZE_MICRO } from "../system/_style-label-size.js";
 import { GROUND_CLASSES } from "./_ground.js";
+import { CAPTION_CASE } from "../system/_style-caption.js";
 import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/layout/frames.tsx
@@ -105,7 +111,7 @@ const HEIGHT_CLASSES = {
 * scroller fills stays where a reader left it. The ground is on the box for the
 * same reason — a board's grid does not move with its art.
 */
-const ROOT_CLASS = "relative min-w-0 overflow-hidden rounded-(--radius-surface) border border-border";
+const ROOT_CLASS = "relative min-w-0 overflow-hidden rounded-surface border border-border";
 /**
 * The scroller: a row of frames, sideways only, with a rung of the space
 * ladder's top between them.
@@ -117,7 +123,7 @@ const ROOT_CLASS = "relative min-w-0 overflow-hidden rounded-(--radius-surface)
 * there is no frame loop here for `reduced-motion.test.ts` to find, and there
 * must not be.
 */
-const CANVAS_CLASS = "flex h-full min-w-0 items-start gap-(--cue-space-8) overflow-x-auto overflow-y-hidden scroll-smooth p-(--cue-space-6) outline-none motion-reduce:scroll-auto focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent";
+const CANVAS_CLASS = `flex h-full min-w-0 items-start gap-(--cue-space-8) overflow-x-auto overflow-y-hidden scroll-smooth p-(--cue-space-6) outline-none motion-reduce:scroll-auto ${FOCUS_RING_INSET_2}`;
 /**
 * The column: the same frames, stacked, sized by what they hold.
 *
@@ -127,7 +133,7 @@ const CANVAS_CLASS = "flex h-full min-w-0 items-start gap-(--cue-space-8) overfl
 * It keeps the focus ring and the keyboard handler: the region is still
 * focusable, and arrow keys still scroll it, they just scroll the page.
 */
-const COLUMN_CLASS = "flex min-w-0 flex-col gap-(--cue-space-6) p-(--cue-space-6) outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent";
+const COLUMN_CLASS = `flex min-w-0 flex-col gap-(--cue-space-6) p-(--cue-space-6) outline-none ${FOCUS_RING_INSET_2}`;
 /** A column is sized by its contents, so the box must not hold a height. */
 const COLUMN_ROOT_CLASS = "h-auto";
 /** The affordance, and only where there is something to afford. */
@@ -237,7 +243,7 @@ const FramesRoot = React.forwardRef(function FramesRoot({ children, label, heigh
 	});
 });
 /** One cell: the specimen, and the line under it. */
-const ITEM_CLASS = "flex min-w-0 shrink-0 flex-col items-center gap-(--cue-space-2) rounded-(--radius-control) p-(--cue-space-2)";
+const ITEM_CLASS = "flex min-w-0 shrink-0 flex-col items-center gap-(--cue-space-2) rounded-control p-(--cue-space-2)";
 /** The one a reader is inspecting. An outline and not a border: a border would move the cell. */
 const ITEM_SELECTED_CLASS = "outline-2 outline-solid -outline-offset-1 outline-accent";
 const ITEM_BODY_CLASS = "flex min-w-0 items-center justify-center";
@@ -262,7 +268,7 @@ const ITEM_BODY_CLASS = "flex min-w-0 items-center justify-center";
 * behaves like any other line, rather than inheriting the empty string and
 * vanishing.
 */
-const ITEM_CAPTION_CLASS = "min-w-0 truncate text-center font-mono text-(length:--cue-text-micro) text-fg-subtle [opacity:var(--preview-captions,1)] [pointer-events:var(--preview-captions-pe,auto)]";
+const ITEM_CAPTION_CLASS = `min-w-0 truncate text-center ${LABEL_FACE} ${CAPTION_CASE} ${LABEL_TRACKING_INHERIT} ${LABEL_SIZE_MICRO} ${LABEL_INK_SUBTLE} [opacity:var(--preview-captions,1)] [pointer-events:var(--preview-captions-pe,auto)]`;
 /**
 * A design canvas: frames side by side, each holding one axis of one component.
 *

package/dist/layout/item.js

@@ -1,4 +1,5 @@
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING } from "../system/_focus-ring.js";
 import { cva } from "../lib/cva.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -15,7 +16,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 * @example
 * <div className={itemVariants({ variant: "outline" })} />
 */
-const itemVariants = cva("flex w-full items-center gap-(--cue-space-4) rounded-(--radius-control) px-(--cue-pad-row-x) py-(--cue-pad-row-y) text-left font-mono text-(length:--cue-text-ui) text-fg", {
+const itemVariants = cva("flex w-full items-center gap-(--cue-space-4) rounded-control px-(--cue-pad-row-x) py-(--cue-pad-row-y) text-left font-mono text-(length:--cue-text-ui) text-fg", {
 	variants: {
 		variant: {
 			plain: "",
@@ -23,7 +24,7 @@ const itemVariants = cva("flex w-full items-center gap-(--cue-space-4) rounded-(
 			soft: "bg-surface-2"
 		},
 		interactive: {
-			true: "cursor-pointer transition-colors duration-150 outline-none hover:bg-surface-2 focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent disabled:pointer-events-none disabled:opacity-40",
+			true: `cursor-pointer transition-colors duration-150 outline-none hover:bg-surface-2 ${FOCUS_RING} disabled:pointer-events-none disabled:opacity-40`,
 			false: ""
 		}
 	},

package/dist/layout/link.d.ts

@@ -13,6 +13,22 @@ import { useRender } from "@base-ui/react/use-render";
  * alone would fail WCAG 1.4.1 — and it offsets the rule by 4px so descenders
  * are not struck through.
  *
+ * The ink, the rule's colour and offset, the weight and the hover ink are the
+ * style set's to change (spec §3.7): each reads a `style-link-*` name, or
+ * `style-hover-ink`, with what this recipe drew before as its fallback —
+ * `_style-link.ts` lists them. The `underline` variant's ink falls back
+ * through every link's, so a set that inks all links inks prose links too.
+ *
+ * **Each variant carries its own ink, and the base carries none.** The two
+ * inks are two `text-[color:…]` utilities, and `linkVariants()` is exported to
+ * be spread onto an anchor without `cn()`: were the plain ink in the base and
+ * the prose ink in the variant, an underlined link would carry both, and which
+ * one painted would be decided by the order Tailwind happened to emit them in.
+ * The same holds for a class a caller concatenates onto it: it does not replace
+ * the recipe's own, and the offset reader is emitted after every numeric
+ * `underline-offset-*`. Merge with `tailwind-merge`, or pass `className` to
+ * `Link`, which merges, to override one.
+ *
  * @example
  * <a className={linkVariants({ variant: "underline" })} href="/docs">Docs</a>
  */

package/dist/layout/link.js

@@ -1,6 +1,9 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_OFFSET_2 } from "../system/_focus-ring.js";
+import { CONTROL_FACE } from "../system/_style-control-face.js";
 import { cva } from "../lib/cva.js";
+import { HOVER_INK, INLINE_LINK_INK, LINK_INK, LINK_OFFSET, LINK_RULE, LINK_WEIGHT } from "../system/_style-link.js";
 import * as React from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useRender } from "@base-ui/react/use-render";
@@ -16,13 +19,29 @@ import { useRender } from "@base-ui/react/use-render";
 * alone would fail WCAG 1.4.1 — and it offsets the rule by 4px so descenders
 * are not struck through.
 *
+* The ink, the rule's colour and offset, the weight and the hover ink are the
+* style set's to change (spec §3.7): each reads a `style-link-*` name, or
+* `style-hover-ink`, with what this recipe drew before as its fallback —
+* `_style-link.ts` lists them. The `underline` variant's ink falls back
+* through every link's, so a set that inks all links inks prose links too.
+*
+* **Each variant carries its own ink, and the base carries none.** The two
+* inks are two `text-[color:…]` utilities, and `linkVariants()` is exported to
+* be spread onto an anchor without `cn()`: were the plain ink in the base and
+* the prose ink in the variant, an underlined link would carry both, and which
+* one painted would be decided by the order Tailwind happened to emit them in.
+* The same holds for a class a caller concatenates onto it: it does not replace
+* the recipe's own, and the offset reader is emitted after every numeric
+* `underline-offset-*`. Merge with `tailwind-merge`, or pass `className` to
+* `Link`, which merges, to override one.
+*
 * @example
 * <a className={linkVariants({ variant: "underline" })} href="/docs">Docs</a>
 */
-const linkVariants = cva("cursor-pointer rounded-(--radius-control) font-mono text-fg transition-colors duration-150 outline-none hover:text-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent", {
+const linkVariants = cva(`cursor-pointer rounded-control ${CONTROL_FACE} ${LINK_WEIGHT} transition-colors duration-150 outline-none ${HOVER_INK} ${FOCUS_RING_OFFSET_2}`, {
 	variants: { variant: {
-		plain: "no-underline",
-		underline: "underline decoration-border underline-offset-4 hover:decoration-accent"
+		plain: `no-underline ${LINK_INK}`,
+		underline: `underline ${INLINE_LINK_INK} ${LINK_RULE} ${LINK_OFFSET} hover:decoration-[color:var(--cue-style-hover-ink,var(--cue-accent))]`
 	} },
 	defaultVariants: { variant: "plain" }
 });

package/dist/layout/pagination.js

@@ -1,5 +1,6 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING_INSET } from "../system/_focus-ring.js";
 import { IconButton } from "../primitives/icon-button.js";
 import { ChevronLeftGlyph, ChevronRightGlyph } from "./_glyphs.js";
 import * as React from "react";
@@ -62,7 +63,7 @@ function paginationRange(page, pageCount, siblingCount = 1) {
 * with `accent-soft` when it is the page you are on — never a solid accent
 * fill, which at console density reads as a second, louder button.
 */
-const PAGE_BUTTON_CLASSES = "inline-flex h-control-sm min-w-control-sm cursor-pointer items-center justify-center rounded-(--radius-control) border-0 bg-transparent px-(--cue-space-2) font-mono text-(length:--cue-text-ui) tabular-nums text-fg-muted transition-colors duration-150 outline-none select-none hover:bg-surface-2 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-accent";
+const PAGE_BUTTON_CLASSES = `inline-flex h-control-sm min-w-control-sm cursor-pointer items-center justify-center rounded-control border-0 bg-transparent px-(--cue-space-2) font-mono text-(length:--cue-text-ui) tabular-nums text-fg-muted transition-colors duration-150 outline-none select-none hover:bg-surface-2 hover:text-fg ${FOCUS_RING_INSET}`;
 /**
 * The pager: previous, a window of page numbers, next.
 *

package/dist/layout/preview.d.ts

@@ -55,15 +55,29 @@ interface PreviewProps extends Omit<React.ComponentPropsWithoutRef<"div">, "chil
   mode?: Mode;
   /** A rung of the density ladder for the stage only, as a `<Density>` island would set it. */
   density?: Density$1;
-  /** A font pairing for the stage only, as `data-font`. Portals still follow the root's pairing. */
+  /**
+   * A font pairing for the stage only, stamped as `data-font` and republished to
+   * React, so an overlay opened on the stage wears the stage's pairing rather
+   * than the page's, and `useTheme().font` read on the stage reports it. The
+   * stage also takes `font-sans` when a pairing is named: `data-font` re-declares
+   * the family's custom properties, but `font-family` inherits as an already
+   * computed value, so unclassed text on the stage would otherwise keep the
+   * family it resolved above it. Unset, the stage inherits and adds neither.
+   */
   font?: FontName;
   /**
-   * A style set for the stage only: `console`, `editorial` or `marketing`.
+   * A style set for the stage only: `console`, `editorial`, `marketing` or
+   * `graphite`.
    *
    * Unset, the stage inherits and **no attribute is emitted at all** — the same
-   * rule the other four follow here. Unlike `theme`, naming one loads nothing
-   * and needs nothing: the three sets are emitted by `@cueplusplus/tokens` into
-   * the stylesheet every consumer already imports, so a stage is scoped to
+   * rule the other four follow here — unless the stage names a `theme`, a `mode`
+   * or a `font`. Then it restates the set in force around it, because a set's
+   * block declares values that read those axes (its seam ink and band rule
+   * read the theme, its control and display faces read the pairing) and a
+   * custom property resolves where it is declared: restated, they resolve
+   * against the stage. Unlike `theme`, naming one loads nothing and needs
+   * nothing: every set is emitted by `@cueplusplus/tokens` into the stylesheet
+   * every consumer already imports, so a stage is scoped to
    * `[data-style="<name>"]` and the block is on the page by construction.
    *
    * The set is republished to React as well as stamped, so a popover opened on
@@ -72,15 +86,18 @@ interface PreviewProps extends Omit<React.ComponentPropsWithoutRef<"div">, "chil
    */
   styleSet?: StyleSet;
   /**
-   * A look pack for the stage: the finish its surfaces wear.
+   * A paint pack for the stage: the finish its surfaces wear.
    *
    * Stamped as `data-paint` on the stage element, and republished to React for
    * the same reason `styleSet` is — a popover opened on the stage mounts on
    * `<body>` and inherits nothing from the stage's DOM, so it has to be told.
    *
-   * Absent means inherit. `none` is a value that opts OUT of an ambient pack,
-   * which is what a stage uses to show a component unpainted inside a page that
-   * is not.
+   * Absent means inherit — and a stage that names a `theme`, a `mode` or a
+   * `font` restates the pack in force around it, so the pack's strokes and
+   * inks, which are the theme's colours mixed, resolve against the stage's
+   * theme rather than the page's. `none` is a value that opts OUT of an ambient
+   * pack, which is what a stage uses to show a component unpainted inside a
+   * page that is not.
    */
   paint?: Paint;
   /**
@@ -151,12 +168,15 @@ interface PreviewProps extends Omit<React.ComponentPropsWithoutRef<"div">, "chil
  *
  * **The stage is the island; the chrome is not.** `theme`, `mode`, `density`,
  * `font` and `styleSet` land on the stage element only, and the stage
- * republishes the theme, density and style-set contexts so an overlay opened on
- * it follows it. The tools, the footer, the grips and anything they open stay
+ * republishes the theme (pairing included), density and style-set contexts so
+ * an overlay opened on it follows it. The tools, the footer, the grips and anything they open stay
  * in the scope around the Preview — a `terminal` preview's own controls do not
  * turn cyan. With none of the five set, the stage carries no attribute and
  * costs what a `<div>` costs. A stage `theme` with no `mode` repeats the page's
- * mode beside it.
+ * mode beside it, a stage `theme` or `mode` with no `density` the page's rung,
+ * and a stage `theme`, `mode` or `font` restates the page's
+ * style set and paint pack beside it, so their theme-reading values resolve
+ * against the stage.
  *
  * **`resizable` is handles of its own**, both axes by default: an edge grip per
  * axis that is a keyboard-operable `separator` valued in pixels, and a corner