@cueplusplus/ui 0.15.0 → 0.17.0

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-elevation.js

@@ -0,0 +1,9 @@
+//#region src/system/_paint-elevation.ts
+/**
+* An overlay. Its default MUST render `0 8px 24px rgba(0,0,0,0.4)` — the literal
+* at four call sites — which is why `--cue-paint-shade-far` is the one
+* non-transparent shadow ink. Measured pixel-identical to it.
+*/
+const ELEVATION_2 = "shadow-[0_0_0_var(--cue-paint-rim-width)_var(--cue-paint-shade-hairline,transparent),0_calc(2px*var(--cue-paint-shadow-scale))_calc(6px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-near,transparent),0_calc(8px*var(--cue-paint-shadow-scale))_calc(24px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-far,rgba(0,0,0,0.4)),inset_0_1px_0_0_var(--cue-paint-sheen-ink,transparent)]";
+//#endregion
+export { ELEVATION_2 };

package/dist/system/_paint-glass.js

@@ -0,0 +1,46 @@
+//#region src/system/_paint-glass.ts
+/**
+* Translucency, with the opaque twin every glass rule needs.
+*
+* **Why this writes `--tw-backdrop-blur` instead of `backdrop-filter`.** Spec
+* §13.5, decided on measurements. Tailwind composes every backdrop utility into
+* ONE declaration — `backdrop-filter: var(--tw-backdrop-blur,)
+* var(--tw-backdrop-brightness,) …` — so a raw `[backdrop-filter:var(…)]` here
+* is a second, competing declaration. Measured: a consumer passing
+* `backdrop-brightness-50` through `className` then computes
+* `brightness(0.5)` and **no blur at all**. The glass does not narrow, it
+* disappears, silently.
+*
+* Filling Tailwind's own slot keeps the composition: the default computes
+* `blur(8px)`, a consumer's brightness composes onto it, and a pack's
+* `blur(12px) saturate(1.4)` survives whole — which a length-valued
+* `backdrop-blur-(--name)` could not express at all.
+*
+* **`backdrop-saturate-100` is there to make the composed declaration exist**,
+* and the choice of utility is load-bearing. Filling a slot paints nothing
+* unless something emits the `backdrop-filter` that reads the slots, and only a
+* backdrop utility emits it. `backdrop-blur-none` would have done that — and it
+* writes `--tw-backdrop-blur` itself, so whichever of the two came later in the
+* stylesheet won: measured, with `blur-none` last the glass computes `none` and
+* disappears. `backdrop-saturate-100` writes a different slot, so the two cannot
+* race, and `saturate(1)` is the identity filter.
+*
+* **The cost is naming an internal, and it is pinned rather than accepted.**
+* `test/system/paint-glass.test.ts` asks the Tailwind compiler what
+* `backdrop-blur` emits and asserts the variable name against that answer, so a
+* rename fails loudly instead of the glass quietly ceasing to compose.
+*
+* **The fill is an explicit `background-color`, not `bg-(--name)`.** The
+* shorthand has nowhere to put the `var()` fallback an ink requires, and an ink
+* spent without one leaves the declaration invalid and CSS drops it in silence.
+*
+* **The `@supports` twin is not decoration.** A browser without
+* `backdrop-filter` paints the translucent fill over whatever is behind it and
+* the bar becomes unreadable; the fallback ink is the opaque surface it would
+* have had.
+*
+* @internal Not part of the public API.
+*/
+const GLASS_CLASSES = "[--tw-backdrop-blur:var(--cue-paint-glass-filter,blur(8px))] backdrop-saturate-100 [background-color:var(--cue-paint-glass-ink,color-mix(in_oklch,var(--cue-surface-1)_95%,transparent))] [@supports_not_(backdrop-filter:blur(0px))]:[background-color:var(--cue-paint-glass-fallback-ink,var(--cue-surface-1))]";
+//#endregion
+export { GLASS_CLASSES };

package/dist/system/_paint-glow.js

@@ -0,0 +1,51 @@
+//#region src/system/_paint-glow.ts
+/**
+* The halo: two offsetless stops at rest, two more on hover.
+*
+* **Offsetless is the rule that keeps this name from being `elevation` twice.**
+* A drop shadow has a y-offset and reads as light from above; a halo has none
+* and reads as the element emitting. The build refuses a glow value with an
+* offset for that reason, with a positive control that must throw.
+*
+* **A separate rest and hover ink, not a `calc()` on one.** The corpus doubles
+* the alpha on hover — railway `0.25`→`0.50`, aceternity `0.2`→`0.4` — and one
+* site's three-layer white halo exists *only* on hover. A single ink with a
+* multiplier cannot express the last of those at all.
+*
+* **Its own module**, because `@repo/docgen` attributes a token by the file its
+* class string lives in, including through a type-only import. One device per
+* file; the two ways that bit are recorded in `_paint-elevation.ts`.
+*
+* **Every ink carries its default as a `var()` fallback**, without exception: an
+* ink is declared in no stylesheet, so a spend without one leaves the whole
+* `box-shadow` invalid and CSS drops it in silence — measured, and the reason
+* 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. 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, GLOW_DANGER_CLASSES };

package/dist/system/_paint-ground-pattern.js

@@ -0,0 +1,30 @@
+//#region src/system/_paint-ground-pattern.ts
+/**
+* A repeating pattern on a page-level ground.
+*
+* **Distinct from a texture, and the difference is the layer.** A texture is
+* noise on a pseudo-element *over* the host (`_paint-texture.ts`); a ground
+* pattern is a repeating geometry painted as the host's own `background-image`,
+* beneath its content and beside its `background-color`. A page can carry both:
+* a hatch under a grain.
+*
+* **It sets `background-image`, so a host that paints its own image cannot take
+* it.** The two adopting surfaces paint a `background-color` only.
+*
+* **Its own module**, because `@repo/docgen` attributes a token by the file its
+* class string lives in, including through a type-only import.
+*
+* **The ink is spent by the pack's own image, not here.** A pattern is a whole
+* CSS `<image>` a pack writes, and `--cue-paint-ground-pattern-ink` is the name
+* that image references — which is why §4 documents these four image slots as
+* freezing their ink at the element the pack block sits on, and why they are
+* page-level devices where that costs nothing measurable.
+*
+* At the default `--cue-paint-ground-pattern` is `none`, so the host paints
+* exactly what it painted before.
+*
+* @internal Not part of the public API.
+*/
+const GROUND_PATTERN_CLASSES = "bg-[image:var(--cue-paint-ground-pattern)] bg-[length:var(--cue-paint-ground-pattern-size)]";
+//#endregion
+export { GROUND_PATTERN_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

@@ -0,0 +1,59 @@
+//#region src/system/_paint-rim.ts
+/**
+* An inset ring on a surface that carries no shadow of its own.
+*
+* **A ring, not a border.** It is drawn as an inset `box-shadow`, outside the
+* box model, so it costs no layout and sits inside the surface's radius. That
+* is what lets a pack put a hairline of light on a panel without moving a
+* single pixel of content.
+*
+* **NOT the recessed control chassis**, and that is an accessibility rule
+* rather than a preference. `forced-colors: active` discards `box-shadow`
+* 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
+* 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.
+*
+* **Nothing already carrying a `shadow-` utility may take this**, because
+* `twMerge` keeps one of two on the same element. The three adopting surfaces
+* were checked and carry none; an elevated surface gets its ring as the
+* hairline *layer* of `ELEVATION_*` instead, which is what that layer is for.
+*
+* **Its own module**, because `@repo/docgen` attributes a token by the file its
+* class string lives in, including through a type-only import.
+*
+* **The ink carries its default as a `var()` fallback**: an ink is declared in
+* no stylesheet, so a spend without one leaves the whole `box-shadow` invalid
+* and CSS drops it in silence — measured twice in earlier slices, once costing
+* an element its border and its fill together.
+*
+* 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),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-sunken.js

@@ -0,0 +1,19 @@
+//#region src/system/_paint-stroke-sunken.ts
+/**
+* The gradient-stroke recipe for a recessed control — the `--cue-sunken` fill.
+*
+* **One fill per module, and that is the point of the file.** `@repo/docgen`
+* attributes a token to a component by the FILE the class string lives in, so a
+* single `_paint.ts` holding all three fills gave every adopting component all
+* three tokens: `card.json` claimed `--cue-sunken` and `--cue-surface-2`, which
+* `Card` does not paint. Measured on the first manifest regeneration of Slice 2;
+* the spec's own risk register predicted it and named this split as the remedy.
+*
+* 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_SUNKEN = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-sunken),var(--cue-sunken)),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]";
+//#endregion
+export { STROKE_SUNKEN };

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

@@ -0,0 +1,19 @@
+//#region src/system/_paint-stroke-surface-1.ts
+/**
+* The gradient-stroke recipe for a card or panel — the `--cue-surface-1` fill.
+*
+* **One fill per module, and that is the point of the file.** `@repo/docgen`
+* attributes a token to a component by the FILE the class string lives in, so a
+* single `_paint.ts` holding all three fills gave every adopting component all
+* three tokens: `card.json` claimed `--cue-sunken` and `--cue-surface-2`, which
+* `Card` does not paint. Measured on the first manifest regeneration of Slice 2;
+* the spec's own risk register predicted it and named this split as the remedy.
+*
+* 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_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

@@ -0,0 +1,40 @@
+//#region src/system/_paint-stroke-surface-2.ts
+/**
+* The gradient-stroke recipe for an overlay — the `--cue-surface-2` fill.
+*
+* **One fill per module, and that is the point of the file.** `@repo/docgen`
+* attributes a token to a component by the FILE the class string lives in, so a
+* single `_paint.ts` holding all three fills gave every adopting component all
+* three tokens: `card.json` claimed `--cue-sunken` and `--cue-surface-2`, which
+* `Card` does not paint. Measured on the first manifest regeneration of Slice 2;
+* the spec's own risk register predicted it and named this split as the remedy.
+*
+* **Its stops fall back to `--cue-border-overlay`, not `--cue-border`**, and
+* that is the one place the three fills differ. An overlay has always drawn its
+* rim in `border-overlay`: a distinct token that some themes — venu — match to
+* the surface deliberately so the rim vanishes. Falling back to `--cue-border`
+* here would repaint every dialog, menu, popover and toast in a colour the
+* 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-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

@@ -0,0 +1,56 @@
+//#region src/system/_paint-texture.ts
+/**
+* A grain or pattern overlay, riding a pseudo-element.
+*
+* **Why `::before` and not the element's own background.** A texture sits *over*
+* whatever the host already paints — a band's ground, a shell's fill — and a
+* component's `background-image` is not free to take. The overlay is
+* `pointer-events-none` and `inset-0`, so it covers the host exactly and
+* intercepts nothing.
+*
+* **Its own module**, because `@repo/docgen` attributes a token by the file its
+* class string lives in, including through a type-only import. One device per
+* file; the two ways that bit are recorded in `_paint-elevation.ts`.
+*
+* **`isolate` and `before:-z-10` together, and neither works alone.** An
+* absolutely-positioned `::before` paints ABOVE its host's in-flow content, so
+* without them the texture covers the band's own text — measured, the white
+* text's brightest pixel drops 255 to 204 under a 60% overlay. `-z-10` alone
+* does not fix it: with no stacking context on the host the pseudo-element
+* falls behind the band's own background and the texture becomes invisible
+* entirely (measured: the ground pixel does not move). `isolate` gives the host
+* a stacking context, and inside one a negative-z child paints above the
+* background and below the content — which is exactly the layer a texture wants.
+* Found in review; the first gate could not see it because its test band had no
+* content in it.
+*
+* **The mask carries its `-webkit-` prefix**, which is the library's
+* convention rather than a guess: `elements/clamp.tsx:223` and
+* `chrome/_edge-scroller.tsx:73` are the only other mask users here and both
+* prefix it. Measured for completeness — Playwright's WebKit honours the
+* unprefixed property, identically to Chromium — so this is for the Safari
+* versions that engine is not, and it matches what the two existing sites
+* 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 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`,
+* `texture-size` `auto`, `texture-opacity` `1`, `texture-blend` `normal`, and
+* `fade` (Slice 7's) `none`. Measured: at those defaults the overlay renders
+* identically to the same host with no pseudo-element at all.
+*
+* **The token layer ships no binary.** `--cue-paint-texture` takes a `data:`
+* URI a pack file holds inline, or an absolute `https://` URL a consumer's own
+* CDN serves — `PAINT_VALUES` enforces exactly those two and says why.
+*
+* @internal Not part of the public API.
+*/
+const TEXTURE_CLASSES = "relative isolate before:pointer-events-none before:absolute before:inset-0 before:-z-10 before:content-[''] before:bg-[image:var(--cue-paint-texture)] before:bg-[length:var(--cue-paint-texture-size)] before:opacity-(--cue-paint-texture-opacity) before:[mix-blend-mode:var(--cue-paint-texture-blend)] before:[mask-image:var(--cue-paint-fade)] before:[-webkit-mask-image:var(--cue-paint-fade)]";
+//#endregion
+export { TEXTURE_CLASSES };

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 };