@cueplusplus/ui 0.16.0 → 0.17.0

package/dist/primitives/chip.js

@@ -1,6 +1,10 @@
 "use client";
 import { cn } from "../lib/cn.js";
+import { FOCUS_RING } from "../system/_focus-ring.js";
 import { cva } from "../lib/cva.js";
+import { CHIP_CASE, CHIP_EDGE, CHIP_FILL, CHIP_HEIGHT, CHIP_PAD, CHIP_RADIUS, CHIP_SIZE, CHIP_SIZE_MICRO, CHIP_TRACKING, CHIP_TRACKING_TAG } from "../system/_style-chip.js";
+import { LABEL_FACE } from "../system/_style-label-face.js";
+import { LABEL_WEIGHT } from "../system/_style-label-weight.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/primitives/chip.tsx
@@ -27,26 +31,34 @@ import { jsx } from "react/jsx-runtime";
 * page rather than a container. The rim is therefore a compound of tone and
 * variant, exactly as the fill is.
 *
+* **The recipe reads the style set** (spec 2026-09-26-looks-fidelity §3.6,
+* `system/_style-chip.ts`): the six tones' fill and rim are
+* `color-mix(in oklab, var(--cue-<tone>) var(--cue-style-chip-fill, 10%), transparent)`
+* and the same with `--cue-style-chip-edge` at `35%` — exactly `bg-<tone>/10`
+* and `border-<tone>/35` under no set, and a set's own shares inside one. The
+* case, tracking, radius, size and weight read `--cue-style-chip-case`,
+* `-tracking`, `-radius`, `-size` and `--cue-style-label-weight` the same way.
+*
 * @example
 * <span className={chipVariants({ tone: "danger", variant: "outline" })}>fault</span>
 * @example
 * <span className={chipVariants({ variant: "tag" })}>mcp</span>
 */
-const chipVariants = cva("inline-flex h-chip select-none items-center justify-center gap-(--cue-space-2) whitespace-nowrap rounded-(--radius-control) border font-mono leading-none uppercase outline-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-1 focus-visible:outline-accent", {
+const chipVariants = cva(`inline-flex ${CHIP_HEIGHT} select-none items-center justify-center gap-(--cue-space-2) whitespace-nowrap ${CHIP_RADIUS} border ${LABEL_FACE} ${LABEL_WEIGHT} leading-none ${CHIP_CASE} outline-none ${FOCUS_RING}`, {
 	variants: {
 		tone: {
 			neutral: "text-fg-muted",
-			accent: "border-accent/35 text-accent",
-			ok: "border-ok/35 text-ok",
-			busy: "border-busy/35 text-busy",
-			warn: "border-warn/35 text-warn",
-			danger: "border-danger/35 text-danger",
-			info: "border-info/35 text-info"
+			accent: `${CHIP_EDGE.accent} text-accent`,
+			ok: `${CHIP_EDGE.ok} text-ok`,
+			busy: `${CHIP_EDGE.busy} text-busy`,
+			warn: `${CHIP_EDGE.warn} text-warn`,
+			danger: `${CHIP_EDGE.danger} text-danger`,
+			info: `${CHIP_EDGE.info} text-info`
 		},
 		variant: {
-			tinted: "px-(--cue-space-3) text-(length:--cue-text-label) tracking-(--cue-tracking-caps)",
-			outline: "bg-transparent px-(--cue-space-3) text-(length:--cue-text-label) tracking-(--cue-tracking-caps)",
-			tag: "bg-transparent px-(--cue-space-2) text-(length:--cue-text-micro) tracking-[0.06em]"
+			tinted: `${CHIP_PAD} ${CHIP_SIZE} ${CHIP_TRACKING}`,
+			outline: `bg-transparent ${CHIP_PAD} ${CHIP_SIZE} ${CHIP_TRACKING}`,
+			tag: `bg-transparent px-(--cue-space-2) ${CHIP_SIZE_MICRO} ${CHIP_TRACKING_TAG}`
 		},
 		interactive: {
 			true: "cursor-pointer disabled:pointer-events-none disabled:opacity-40",
@@ -72,32 +84,32 @@ const chipVariants = cva("inline-flex h-chip select-none items-center justify-ce
 		{
 			tone: "accent",
 			variant: "tinted",
-			class: "bg-accent/10"
+			class: CHIP_FILL.accent
 		},
 		{
 			tone: "ok",
 			variant: "tinted",
-			class: "bg-ok/10"
+			class: CHIP_FILL.ok
 		},
 		{
 			tone: "busy",
 			variant: "tinted",
-			class: "bg-busy/10"
+			class: CHIP_FILL.busy
 		},
 		{
 			tone: "warn",
 			variant: "tinted",
-			class: "bg-warn/10"
+			class: CHIP_FILL.warn
 		},
 		{
 			tone: "danger",
 			variant: "tinted",
-			class: "bg-danger/10"
+			class: CHIP_FILL.danger
 		},
 		{
 			tone: "info",
 			variant: "tinted",
-			class: "bg-info/10"
+			class: CHIP_FILL.info
 		},
 		{
 			tone: "neutral",
@@ -191,7 +203,17 @@ const chipVariants = cva("inline-flex h-chip select-none items-center justify-ce
 	}
 });
 /**
-* A compact status/label pill: mono, uppercase, wide-tracked, one line tall.
+* A compact status/label pill: mono, uppercase, wide-tracked, one line tall —
+* by default, the style set's choice inside one.
+*
+* A chip speaks in the label voice: it reads the label face
+* (`--cue-style-label-face`) and its own case (`--cue-style-chip-case`, which
+* falls back to the label case), so under a sans, sentence-case Look its text
+* is sans and sentence case like the captions around it. This reverses the
+* earlier ruling that a tag's text is the value being shown and stays mono
+* (spec 2026-09-26-looks-fidelity F-15): under a sans Look a mono uppercase
+* chip was the most visible console voice left on the page. A consumer that
+* wants a chip mono under every set passes `className="font-mono uppercase"`.
 *
 * `tone` uses the shared status vocabulary (`ok | busy | warn | danger | info`)
 * plus `neutral` and `accent`, so a chip, a `StatusDot` and a `Meter` always

package/dist/primitives/kbd.d.ts

@@ -9,6 +9,12 @@ type KbdProps = React.ComponentPropsWithoutRef<"kbd">;
  * chip height so a `Kbd` and a `Chip` line up on the same row, and set in the
  * micro type step because shortcut hints are reference material, not content.
  *
+ * A key label is a control's voice, so it wears the control face
+ * (`--cue-style-control-face`, mono by default) rather than a fixed mono
+ * (spec 2026-09-26-looks-fidelity F-16), and a style set can move its rim
+ * (`--cue-style-kbd-edge`), its size (`--cue-style-chip-size`, shared with the
+ * chip it sits beside) and its weight (`--cue-style-label-weight`).
+ *
  * @example
  * <span>Press <Kbd>⌘</Kbd><Kbd>K</Kbd> to search</span>
  */

package/dist/primitives/kbd.js

@@ -1,4 +1,7 @@
 import { cn } from "../lib/cn.js";
+import { CONTROL_FACE } from "../system/_style-control-face.js";
+import { LABEL_WEIGHT } from "../system/_style-label-weight.js";
+import { KBD_BOX, KBD_EDGE, KBD_SIZE } from "../system/_style-kbd.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/primitives/kbd.tsx
@@ -9,13 +12,19 @@ import { jsx } from "react/jsx-runtime";
 * chip height so a `Kbd` and a `Chip` line up on the same row, and set in the
 * micro type step because shortcut hints are reference material, not content.
 *
+* A key label is a control's voice, so it wears the control face
+* (`--cue-style-control-face`, mono by default) rather than a fixed mono
+* (spec 2026-09-26-looks-fidelity F-16), and a style set can move its rim
+* (`--cue-style-kbd-edge`), its size (`--cue-style-chip-size`, shared with the
+* chip it sits beside) and its weight (`--cue-style-label-weight`).
+*
 * @example
 * <span>Press <Kbd>⌘</Kbd><Kbd>K</Kbd> to search</span>
 */
 const Kbd = React.forwardRef(function Kbd({ className, children, ...elementProps }, ref) {
 	return /* @__PURE__ */ jsx("kbd", {
 		ref,
-		className: cn("inline-flex h-chip min-w-chip select-none items-center justify-center rounded-(--radius-control) border border-border bg-surface-2 px-(--cue-space-2) font-mono text-(length:--cue-text-micro) leading-none text-fg-muted", className),
+		className: cn(`inline-flex ${KBD_BOX} select-none items-center justify-center border bg-surface-2 text-fg-muted`, KBD_EDGE, CONTROL_FACE, KBD_SIZE, "leading-none", LABEL_WEIGHT, className),
 		...elementProps,
 		children
 	});

package/dist/primitives/skeleton.js

@@ -19,7 +19,7 @@ const Skeleton = React.forwardRef(function Skeleton({ className, ...elementProps
 	return /* @__PURE__ */ jsx("div", {
 		ref,
 		"aria-hidden": "true",
-		className: cn("animate-pulse rounded-(--radius-control) bg-surface-2 motion-reduce:animate-none", className),
+		className: cn("animate-pulse rounded-control bg-surface-2 motion-reduce:animate-none", className),
 		...elementProps
 	});
 });

package/dist/system/_focus-ring-field.js

@@ -0,0 +1,29 @@
+//#region src/system/_focus-ring-field.ts
+/**
+* `FOCUS_RING_INSET` (`_focus-ring.ts`) with its offset read from the style set: the
+* recessed field chassis's ring (`forms/_chassis.ts`), and nothing else.
+*
+* Plan V.2, T25: Tender's field ring sits flush on the rim (`0px`) where every
+* other site of the inset shape keeps its `-1px`, so the offset is a name of
+* its own — `style-field-focus-offset`, falling back to the `-1px`
+* `FOCUS_RING_INSET` draws — and not `style-focus-offset`, which is the
+* button chassis's (kiln pulls that to `-1px`, and a field that followed it
+* would move with the buttons). `FOCUS_RING_INSET` keeps its fixed offset
+* for its ten other consumers.
+*
+* Its own module, not a constant in `_focus-ring.ts`: docgen attributes a
+* token to a component by the file its class string lives in, and every
+* focusable component imports that module.
+*
+* @internal Not part of the public API.
+*/
+const FOCUS_RING_FIELD = "focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)]";
+/**
+* `FOCUS_RING_GROUP_INSET` with {@link FOCUS_RING_FIELD}'s offset: the
+* grouped field's ring reads `style-field-focus-offset` as the field it wraps
+* does (plan V.2, T25), so a grouped field and a plain one keep one focus
+* geometry under every Look.
+*/
+const FOCUS_RING_GROUP_FIELD = "has-focus-visible:outline-solid has-focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] has-focus-visible:outline-(--cue-focus) has-focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)]";
+//#endregion
+export { FOCUS_RING_FIELD, FOCUS_RING_GROUP_FIELD };

package/dist/system/_focus-ring.js

@@ -0,0 +1,125 @@
+//#region src/system/_focus-ring.ts
+/**
+* The one focus ring this library draws, in one place.
+*
+* Spec 2026-09-26-looks-fidelity §3.12 (F-9). Before this module existed, 80
+* files each spelt out `focus-visible:outline-2 focus-visible:outline-solid
+* focus-visible:outline-offset-<n> focus-visible:outline-accent` by hand — a
+* fixed 2px ring in the theme's **brand** colour. That is the wrong role:
+* `--cue-accent` is not contrast-gated as an indicator, `--cue-focus` is (WCAG
+* 1.4.11, advisory 3:1 on five grounds — `forms/_chassis.ts` carries the long
+* form), and three shipped presets (hivehub.light, luma.light, venu.light)
+* already had to split the two apart because the accent alone reads under
+* 3:1 there. Every site but `forms/_chassis.ts` kept pointing at the
+* un-gated role anyway, which is the defect this module closes.
+*
+* **This is a deliberate, library-wide colour change**, not a no-op: the
+* ring's colour moves wherever a theme's `focus` differs from its `accent` —
+* graphite and kiln and porcelain in both modes, tender dark, and hivehub,
+* luma and venu in light (ten of the thirty theme blocks this system ships).
+* `tests/browser/form-focus.spec.ts` and `form-focus-theme-blocks.spec.ts`
+* measure the ring's resolved colour against `--cue-focus` in every one of
+* the thirty.
+*
+* **Width is a style-set knob, colour is not.** `--cue-style-focus-width`
+* lets a Look draw a heavier ring (tender: 3px) without a second module; no
+* style name touches the ink, because the ink's job is the contrast floor,
+* not the Look's voice. The fallback is `--cue-focus-ring`, the frozen 2px
+* this system drew before any style set existed.
+*
+* **Offset is not one of the constants below.** Every site but the button
+* chassis keeps the exact offset it already painted — `FOCUS_RING` (1px,
+* floating clear of the edge), `FOCUS_RING_INSET` (-1px, flush with it),
+* `FOCUS_RING_INSET_2` (-2px, flush one rung further in) and
+* `FOCUS_RING_OFFSET_2` (2px, floating two clear) between them cover every
+* offset this library drew before this file existed but one: `buttonChassis`
+* reads `--cue-style-focus-offset` directly (kiln pulls it to -1px), so
+* `FOCUS_RING_PAINT` — the width-and-colour half with no offset of its own —
+* is exported for that one call site to finish.
+*
+* **Every export is a complete, literal string, not built from parts at
+* runtime.** A first draft of this file built each one from a shared
+* `ring(modifier, offset)` helper — the exact same characters, byte for byte,
+* as what is written out below. It compiled, every jsdom suite that reads
+* class strings off a render stayed green, and every rendered `className`
+* carried the right text — and in a real browser the ring's `outline-offset`
+* computed `0px` on all eighty sites regardless of which constant they used.
+* `@tailwindcss/oxide` finds a utility by scanning source *text* for a
+* complete candidate, and never evaluates the template literal that would
+* assemble `"focus-visible" + ":" + "-outline-offset-1"` at runtime — so a
+* class no file spells out in one contiguous string is a class the compiler
+* never generates, however many test suites confirm the DOM carries its
+* name. `tests/browser/form-focus.spec.ts` is what caught it, on a full
+* `pnpm test:browser` run rather than on any file run alone, which is the
+* argument for never letting this module drift back to the helper.
+*
+* **Its own module**, for the reason `_paint-glow.ts` gives at length:
+* `@repo/docgen` attributes a token to a component by the file its class
+* string lives in, following only `_`-prefixed imports. One ring, spent from
+* one file, so a component that draws it is credited with reading
+* `--cue-focus` and not with reading nothing.
+*
+* `outline-solid` is load-bearing in every export below, not decoration: in
+* Tailwind v4 an outline's *style* is a separate custom property from its
+* width, `outline-none` (the resting state every one of these sites also
+* carries) sets that property to `none`, and only `<modifier>:outline-solid`
+* restores it at ring time. `buttonChassis`'s own note says why at more
+* length; `test/focus-ring.test.ts` is what keeps it paired here.
+*
+* @internal Not part of the public API.
+*/
+/**
+* The ring's width and colour, with no offset of its own.
+*
+* Exported only for `primitives/button.tsx`, whose offset is itself a
+* style-set knob (`--cue-style-focus-offset`) rather than one of the four
+* fixed shapes below. Every other site imports one of those instead.
+*/
+const FOCUS_RING_PAINT = "focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus)";
+/**
+* A ring floating one pixel clear of the control's own edge
+* (`outline-offset-1`).
+*
+* The shape most of this system's non-recessed controls drew already —
+* `Button`'s siblings that do not ride `buttonChassis` itself, `Chip`,
+* `Tabs`' own trigger, `AppBar.Link` and the rest of the plain chrome.
+*/
+const FOCUS_RING = "focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:outline-offset-1";
+/**
+* A ring pulled back flush with the control's own edge, one pixel in
+* (`-outline-offset-1`).
+*
+* The recessed-chassis shape: an outline at this offset spans from one pixel
+* inside the border box to one pixel outside it, so it covers the rim it is
+* drawn over instead of floating clear of it — `forms/_chassis.ts`'s long
+* comment is the argument in full, and that file's own ring is exactly this
+* constant.
+*/
+const FOCUS_RING_INSET = "focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:-outline-offset-1";
+/**
+* A ring pulled back two pixels (`-outline-offset-2`) — for a control whose
+* own rim sits one ring further in than {@link FOCUS_RING_INSET}'s, such as
+* `SegmentedControl`'s pressed item inside its track.
+*/
+const FOCUS_RING_INSET_2 = "focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:-outline-offset-2";
+/**
+* A ring floating two pixels clear (`outline-offset-2`) — the wider-gap
+* counterpart to {@link FOCUS_RING} for a control with more room around it,
+* such as a `Tabs` list item or a card-level link.
+*/
+const FOCUS_RING_OFFSET_2 = "focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:outline-offset-2";
+/**
+* The one ring in this module drawn from a `data-*` attribute instead of a
+* pseudo-class, floating two pixels clear (`outline-offset-2`).
+*
+* `color/_thumb.ts`'s draggable colour puck sits on Base UI's `ColorArea` and
+* `ColorSlider`, which stamp `data-focus-visible` on the thumb rather than
+* leaving `:focus-visible` to match it directly — so the thumb reads it as
+* `data-[focus-visible]:`, the one modifier spelling this module exists to
+* unify away from and cannot: `test/focus-ring.test.ts`'s WCAG guard has to
+* see this exact string too, which is why it is spelled out here rather than
+* composed at the call site.
+*/
+const FOCUS_RING_DATA_OFFSET_2 = "data-[focus-visible]:outline-solid data-[focus-visible]:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] data-[focus-visible]:outline-(--cue-focus) data-[focus-visible]:outline-offset-2";
+//#endregion
+export { FOCUS_RING, FOCUS_RING_DATA_OFFSET_2, FOCUS_RING_INSET, FOCUS_RING_INSET_2, FOCUS_RING_OFFSET_2, FOCUS_RING_PAINT };

package/dist/system/_paint-glow.js

@@ -22,11 +22,30 @@
 * the elevation rungs and the stroke recipe carry theirs.
 *
 * **Nothing wearing this may also carry a `shadow-` literal**: `twMerge` keeps
-* one of two `shadow-` utilities on the same element. `buttonTones` carries none
-* on any tone, which is what makes the adoption additive.
+* one of two `shadow-` utilities on the same element. The two tones that wear a
+* halo, `primary` and `danger`, carry no other, which is what makes the
+* adoption additive. The `outline` tone does carry one — `REST_SHADE_CLASS`,
+* the resting shade (fidelity plan R3) — so it must not also take
+* `GLOW_CLASSES`: one of the two would be dropped in silence. A halo there
+* would compose both into one `shadow-[…]` list instead.
 *
 * @internal Not part of the public API.
 */
 const GLOW_CLASSES = "shadow-[0_0_var(--cue-paint-glow-blur)_var(--cue-paint-glow-ink,transparent),0_0_var(--cue-paint-glow-blur-far)_var(--cue-paint-glow-ink,transparent)] hover:shadow-[0_0_var(--cue-paint-glow-blur)_var(--cue-paint-glow-ink-hover,transparent),0_0_var(--cue-paint-glow-blur-far)_var(--cue-paint-glow-ink-hover,transparent)]";
+/**
+* The danger variant of {@link GLOW_CLASSES} (spec §3.10, P0.6): the same two
+* offsetless stops, at the same two blur radii, tinted by the danger tone's
+* own ink — `paint-danger-glow-ink` — rather than by the halo's. One ink, not
+* a rest/hover pair: no pack authors a danger-glow HOVER ink, so `buttonTones`'
+* `danger` reads one value at both states, exactly as it reads `bg-danger`
+* without a separate hover fill.
+*
+* `transparent` by default, on every shipped pack but glaze, which is what
+* keeps this additive: `buttonTones.danger` carries no `shadow-` literal
+* today, so adopting this changes nothing until a pack tints the ink.
+*
+* @internal Not part of the public API.
+*/
+const GLOW_DANGER_CLASSES = "shadow-[0_0_var(--cue-paint-glow-blur)_var(--cue-paint-danger-glow-ink,transparent),0_0_var(--cue-paint-glow-blur-far)_var(--cue-paint-danger-glow-ink,transparent)]";
 //#endregion
-export { GLOW_CLASSES };
+export { GLOW_CLASSES, GLOW_DANGER_CLASSES };

package/dist/system/_paint-rest-shade.js

@@ -0,0 +1,32 @@
+//#region src/system/_paint-rest-shade.ts
+/**
+* {@link REST_SHADE} as a utility of its own, for a site that has no shadow
+* list to compose it into: the recessed input chassis (`forms/_chassis.ts`,
+* whose stroke recipe paints a border and a ground and no shadow), the
+* outline button tone and the checkbox box (fidelity plan R3).
+*
+* **Spelt out, character for character**, rather than built from
+* `REST_SHADE` with its spaces turned to underscores: `@tailwindcss/oxide`
+* finds a utility by scanning source text for a complete candidate and never
+* evaluates a template literal, so a class assembled at runtime is a class no
+* stylesheet contains (`_focus-ring.ts` records the time that shipped).
+* `test/system/style-controls.test.tsx` holds the two spellings together.
+*
+* **Labelled `shadow:`**, which Tailwind compiles exactly as it compiles the
+* unlabelled value. The label is for `twMerge`, which knows a shadow only by
+* two plain lengths after the `[` — this value's second is a `calc()` — and
+* without the label files the class as a shadow COLOUR: a caller's
+* `className="shadow-lg"` would then survive beside it rather than replace
+* it, and a caller's `shadow-red-500` would delete it. Labelled, a caller's
+* shadow replaces it and a caller's shadow colour tints it, as with any
+* Tailwind shadow.
+*
+* **A site that already carries a `shadow-` utility must not take this**:
+* `twMerge` keeps one of two `shadow-` utilities on the same element. It
+* composes `REST_SHADE` into its own list instead.
+*
+* @internal Not part of the public API.
+*/
+const REST_SHADE_CLASS = "shadow-[shadow:0_calc(2px*var(--cue-paint-shadow-scale))_calc(4px*var(--cue-paint-shadow-scale))_var(--cue-paint-rest-shade,transparent)]";
+//#endregion
+export { REST_SHADE_CLASS };

package/dist/system/_paint-rim.js

@@ -12,9 +12,12 @@
 * entirely and repaints outlines in the user's own highlight colour, so a ring
 * drawn as a shadow vanishes for exactly the people who most need it — and a
 * form control's ring is a focus indicator. `forms/chassis.test.ts` asserts
-* `controlSurface` contains no `shadow` at all, and it is right to.
-* §22's inventory lists `_chassis.ts:101` as a rim site; it is wrong, and the
-* guard predates it.
+* that the one shadow `controlSurface` carries is the resting shade
+* (`REST_SHADE_CLASS`, fidelity plan R3) and that nothing else in it is a
+* shadow or a ring, and it is right to: the shade is decorative and
+* unconditional, no part of the focus indicator, so losing it to
+* `forced-colors` loses nothing a person needs. §22's inventory lists
+* `_chassis.ts:101` as a rim site; it is wrong, and the guard predates it.
 *
 * A panel's or a card's rim is decorative, so the same loss is cosmetic there.
 *
@@ -34,8 +37,23 @@
 * At the defaults `--cue-paint-rim-width` is `0px` and the ink is
 * `transparent`, so the ring is a no-op twice over.
 *
+* **The resting shade rides in the same list** (spec 2026-09-26-looks-fidelity
+* §3.10, `paint-rest-shade`; plan R5). A card and a panel are the two surfaces
+* that spend this ring, and they are two of `REST_SHADE`'s readers: a pack that
+* sets them down on the page with a one-stop contact shadow (glaze, rows P21
+* and P25) tints `--cue-paint-rest-shade`, and every other pack leaves it
+* `transparent`. It is composed here, as the second layer of this one utility,
+* and not beside it, for the reason above — `twMerge` keeps one of two
+* `shadow-` utilities. It is spelt out rather than interpolated from
+* `_paint-rest-shade.ts`, because Tailwind scans the shipped `dist/` for whole
+* class strings and a template literal is not one; `test/system/
+* paint-rim-pattern.test.ts` holds the two spellings to each other. A
+* transparent layer paints nothing, so under every pack but a tinted one this
+* is still the ring alone (`tests/browser/paint-elevation-noop.spec.ts`, by
+* pixels, under all ten).
+*
 * @internal Not part of the public API.
 */
-const RIM_INSET = "shadow-[inset_0_0_0_var(--cue-paint-rim-width)_var(--cue-paint-rim-ink,transparent)]";
+const RIM_INSET = "shadow-[inset_0_0_0_var(--cue-paint-rim-width)_var(--cue-paint-rim-ink,transparent),0_calc(2px*var(--cue-paint-shadow-scale))_calc(4px*var(--cue-paint-shadow-scale))_var(--cue-paint-rest-shade,transparent)]";
 //#endregion
 export { RIM_INSET };

package/dist/system/_paint-stroke-surface-1.js

@@ -14,6 +14,6 @@
 *
 * @internal Not part of the public API.
 */
-const STROKE_SURFACE_1 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-surface-1),var(--cue-surface-1)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box]";
+const STROKE_SURFACE_1 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-surface-1),var(--cue-surface-1)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-raised-from,var(--cue-paint-stroke-from,var(--cue-border))),var(--cue-paint-stroke-raised-to,var(--cue-paint-stroke-to,var(--cue-border))))] bg-origin-border [background-clip:padding-box,border-box]";
 //#endregion
 export { STROKE_SURFACE_1 };

package/dist/system/_paint-stroke-surface-2.js

@@ -17,11 +17,24 @@
 * theme did not choose for them. Caught by the manifest, which showed 22
 * components losing `--cue-border-overlay` the moment this fill was adopted.
 *
+* **Round 2 (spec §3.10, P0.6): the stroke stops read the overlay's own ink,
+* `paint-stroke-overlay-from`/`-to`, not `paint-stroke-from`/`-to` any more.**
+* Every shipped pack still restates its stroke pair here too — `none`'s pair
+* is `var(--cue-border-overlay)`, closing F-10's gap (under `none`, an overlay's
+* edge used to differ from what a page with no pack draws) — so the fallback
+* stays load-bearing only for a THIRD-PARTY pack that has not yet declared the
+* two new names.
+*
+* **The fill reads `style-overlay-ground` (spec §3.11), not a bare
+* `--cue-surface-2` literal.** A style set may pick one of five opaque grounds
+* for an overlay's fill, the same way `band-ground` works one axis over; no
+* set does yet, so the fallback keeps this a no-op everywhere.
+*
 * The recipe itself, and why its off state is a flat gradient rather than
 * `none`, is documented once in `./_paint`.
 *
 * @internal Not part of the public API.
 */
-const STROKE_SURFACE_2 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-surface-2),var(--cue-surface-2)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border-overlay)),var(--cue-paint-stroke-to,var(--cue-border-overlay)))] bg-origin-border [background-clip:padding-box,border-box]";
+const STROKE_SURFACE_2 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-overlay-ground,var(--cue-surface-2)),var(--cue-style-overlay-ground,var(--cue-surface-2))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-overlay-from,var(--cue-border-overlay)),var(--cue-paint-stroke-overlay-to,var(--cue-border-overlay)))] bg-origin-border [background-clip:padding-box,border-box]";
 //#endregion
 export { STROKE_SURFACE_2 };

package/dist/system/_paint-texture.js

@@ -33,8 +33,11 @@
 * already decided. Found in review.
 *
 * **Nothing else in the library may take this pseudo-element on the same
-* element.** §6.5 note 2 is about that, and it is why the host was checked
-* before adopting: neither `Band` nor `AppShell` uses `::before` today.
+* element.** §6.5 note 2 is about that, and it is why each host is checked
+* before adopting: neither `Band` nor `AppShell.Root` used `::before` for
+* anything else at the point each one took this class string (spec 2026-09-26
+* R-14 added the second host, so a pack's texture also covers the page ground
+* a console shell paints and not only `<Band separation="ground">`).
 *
 * **No ink here, so no fallback rule to keep.** Every name this spends is a
 * declared pack name with a `:root` default — `texture` is `none`,

package/dist/system/_style-app-bar.js

@@ -0,0 +1,65 @@
+//#region src/system/_style-app-bar.ts
+/**
+* What `AppBar` reads from the style set beyond the navigation voice: the
+* bar's height, its rule's ink and line style, and its inline inset, and a
+* link's padding, hover ground, hover ink and muted ink.
+*
+* Spec 2026-09-26-looks-fidelity §3.7, §3.8, §3.11 and §10.4 (plan R4 and its
+* Graphite addition). The site header serves every Look, so a Look's taller
+* bar (tender, zine, kiln, porcelain), its lighter or absent rule (zine,
+* kiln), its wider inset (graphite) or its padded, tinted links (zine,
+* porcelain) cannot be a class on the header: it would move Classic too
+* (F-18). Each is a style-set name read here.
+*
+* **Every fallback is the class it replaced, spelt out**, for the reason
+* `_style-control-face.ts` gives, so under no set and under every set that
+* declines a name the bar renders exactly what it did:
+*
+* - `h-(--cue-chrome-toolbar)`, `border-border` and `px-(--cue-space-5)` on
+*   the bar;
+* - no padding and no ground on a link (`0`, `transparent`) — the link keeps
+*   `Link`'s own `rounded-control`, which a padded, tinted link now shows;
+* - `hover:text-accent`, which `AppBar.Link` inherited from `Link`, read here
+*   through `style-hover-ink` as spec §3.7 names this reader;
+* - `text-fg-muted` for the `muted` register, read through `style-quiet-ink`
+*   (spec §3.7: `fg-muted` for AppBar.Link `muted`).
+*
+* **The hover ground yields to a caller's own ground.** It is the one
+* declaration here the link never had: `Link` sets no background in any state,
+* so `<AppBar.Link className="bg-surface-2">` kept its ground under the pointer.
+* A plain `hover:bg-[…]` is `(0,2,0)` and would paint over it; this is written
+* `[@media(hover:hover)]:[:where(&:hover)]:`, which is `hover:` — the same
+* media query, the same state — at zero specificity, so any class a caller
+* passes for the ground still wins, hovered or not. The hover INK replaced
+* `Link`'s own `hover:text-accent` and keeps its standing, as that did.
+*
+* `style-appbar-inset` entered the contract in the fidelity plan's L5.1:
+* `graphite` declares it (40px, 24px on a phone; G38), and under every other
+* set the bar renders its fallback.
+*
+* **The rule's line style fills Tailwind's own slot** (`style-chrome-rule-style`,
+* round 5 of plan V.2: `zine` dashes it, Z17). The bar's `border-b` writes
+* `border-bottom-style: var(--tw-border-style)`, a slot Tailwind registers as
+* `@property` with `inherits: false` and `initial-value: solid` — which is the
+* solid rule the bar always drew. Filling that slot keeps the one declaration,
+* for the reason `_paint-glass.ts` fills `--tw-backdrop-blur`: a raw
+* `[border-bottom-style:…]` would be a second, competing declaration, and
+* Tailwind emits it after `border-dashed`, so it would beat a caller's own
+* `border-dotted`. Through the slot a caller's style class still wins, because
+* it writes `border-style` itself, after `border-b`. The fallback is the
+* slot's own initial value, and `test/system/style-navigation.test.tsx` asks
+* the compiler for both the slot and that value rather than remembering them.
+*
+* **Its own module**, for the docgen reason `_style-nav-voice.ts` gives: only
+* `AppBar` reads these names, so only `AppBar` is credited with them.
+*
+* @internal Not part of the public API.
+*/
+/** The bar itself: height, bottom rule's ink and line style, and inline inset. */
+const APP_BAR_CHROME = "h-[var(--cue-style-appbar-height,var(--cue-chrome-toolbar))] border-[color:var(--cue-style-chrome-rule,var(--cue-border))] [--tw-border-style:var(--cue-style-chrome-rule-style,solid)] px-[var(--cue-style-appbar-inset,var(--cue-space-5))]";
+/** One link's box and hover: padding, hover ground, hover ink. */
+const APP_BAR_LINK = "p-[var(--cue-style-nav-pad,0)] [@media(hover:hover)]:[:where(&:hover)]:bg-[color:var(--cue-style-nav-hover-ground,transparent)] hover:text-[color:var(--cue-style-hover-ink,var(--cue-accent))]";
+/** The `muted` register's ink. */
+const APP_BAR_QUIET_INK = "text-[color:var(--cue-style-quiet-ink,var(--cue-fg-muted))]";
+//#endregion
+export { APP_BAR_CHROME, APP_BAR_LINK, APP_BAR_QUIET_INK };

package/dist/system/_style-band.js

@@ -0,0 +1,57 @@
+//#region src/system/_style-band.ts
+/**
+* The two `Band`-only readers of the band's proportions: the broad column's
+* measure, and the rhythm's two halves.
+*
+* **Why neither is in `chrome/_band.ts`.** `Footer` spends that file's
+* `bandClasses("rule")` too, and `@repo/docgen` reads a `_`-prefixed module
+* whole and publishes every `--cue-*` in it as a token each importer paints.
+* `Footer` cannot render either reader below — its `width` is a
+* `ContainerWidth` whose `broad` goes straight to `Container`, and the docs site
+* renders it on every page, where Graphite's 160/80 halves would have moved
+* every footer on a surface the fidelity round never measured (spec §10.4). So
+* they live here, imported by `band.tsx` alone.
+*
+* @internal Not part of the public API.
+*/
+/**
+* The `width="broad"` column's measure — spec §3.11, `style-band-width` (T38).
+*
+* `--cue-measure-broad` stays `:root`-only (a set that moved it would move
+* every `Container` and `PageShell` at the broad rung); the band column reads a
+* name of its own instead, a rem length from 40 to 100rem.
+*
+* **The fallback is the old class, spelt out.** `Container`'s broad rung is
+* `max-w-(--cue-measure-broad)`, and this computes the same `max-width` when
+* `--cue-style-band-width` is unset, which it is under no set and under every
+* shipped set today.
+*
+* @internal
+*/
+const BAND_BROAD_WIDTH = "max-w-[var(--cue-style-band-width,var(--cue-measure-broad))]";
+/**
+* The rhythm's halves — spec §10.4, `band-y-top` and `band-y-bottom` (G46).
+*
+* `--cue-band-y` is one symmetric value, and Graphite's source draws every band
+* 160px above and 80px below (88/32 on a phone), which no value of it reaches.
+* The halves keep `band-y`'s spelling rather than the `style-` prefix: they are
+* its halves (the paint-axis spec's §9.1 named them so).
+*
+* **Composed after `bandClasses(separation)`, and both stay in the class
+* list.** `tailwind-merge` drops an earlier `py-` only for a later `py-`, so
+* `bandClasses`'s `py-(--cue-band-y)` survives beside these; they win by
+* Tailwind 4's property order, which emits `padding-block` before
+* `padding-top` and `padding-bottom`. A consumer's later `py-0`
+* (`home-band.tsx`) drops these two as well, so a band that zeroes its rhythm
+* still does.
+*
+* **The fallback is the old value, spelt out.** Each half falls back to
+* `var(--cue-band-y)`, which is what `py-(--cue-band-y)` drew on that side. The
+* two names enter the contract with Graphite's round (plan L5.1); until then no
+* set declares them, and each half renders `band-y`.
+*
+* @internal
+*/
+const BAND_Y_HALVES = "pt-[var(--cue-band-y-top,var(--cue-band-y))] pb-[var(--cue-band-y-bottom,var(--cue-band-y))]";
+//#endregion
+export { BAND_BROAD_WIDTH, BAND_Y_HALVES };

package/dist/system/_style-body-leading.js

@@ -0,0 +1,21 @@
+//#region src/system/_style-body-leading.ts
+/**
+* Body copy's leading where a component sets it itself: an overlay's
+* description, a field's help and a tooltip (plan V.2, P42, P48, P129).
+* Porcelain's body copy sits on a 1.38 leading at every size.
+*
+* | constant               | reads                | fallback                 |
+* |------------------------|----------------------|--------------------------|
+* | `BODY_LEADING`         | `style-body-leading` | `var(--cue-leading-ui)`  |
+* | `BODY_LEADING_INHERIT` | `style-body-leading` | `inherit`                |
+*
+* **Optional** (spec §3.0). Its own module for docgen's reason
+* (`_style-body-size.ts`).
+*
+* @internal Not part of the public API.
+*/
+const BODY_LEADING = "leading-[var(--cue-style-body-leading,var(--cue-leading-ui))]";
+/** @see BODY_LEADING — for a site that set none and inherited its box's. */
+const BODY_LEADING_INHERIT = "leading-[var(--cue-style-body-leading,inherit)]";
+//#endregion
+export { BODY_LEADING, BODY_LEADING_INHERIT };