@cueplusplus/ui 0.16.0 → 0.18.0

package/dist/system/_style-switch.js

@@ -0,0 +1,26 @@
+//#region src/system/_style-switch.ts
+/**
+* The switch's thumb (round 6, spec §11, lane R6.T: `style-switch-thumb`,
+* `style-switch-disabled-thumb`).
+*
+* stripe.com's thumb is white in every state (`--hds-color-input-icon-onSolid`),
+* and its disabled thumb is its quiet border ink (`--hds-color-input-icon-disabled`,
+* #d4dee9). Ours was `fg-muted` at rest and `accent-fg` when checked. The one
+* name serves both states, each falling back to what it drew (T146); the
+* disabled thumb reads its own, falling back to the resting state's value.
+*
+* @internal Not part of the public API.
+*/
+const SWITCH_THUMB = "bg-[color:var(--cue-style-switch-thumb,var(--cue-fg-muted))]";
+/** The checked thumb: the same name, falling back to `accent-fg`. */
+const SWITCH_THUMB_CHECKED = "data-[checked]:bg-[color:var(--cue-style-switch-thumb,var(--cue-accent-fg))]";
+/** The disabled thumb, unchecked and checked, each falling back through the thumb's own name to what it drew. */
+const SWITCH_THUMB_DISABLED = "data-[disabled]:bg-[color:var(--cue-style-switch-disabled-thumb,var(--cue-style-switch-thumb,var(--cue-fg-muted)))] data-[disabled]:data-[checked]:bg-[color:var(--cue-style-switch-disabled-thumb,var(--cue-style-switch-thumb,var(--cue-accent-fg)))]";
+/**
+* The switch track's rim (round 6, spec §11, lane R6.P: `style-switch-edge`),
+* falling back to the `border` it drew at rest and the `border-strong` on hover.
+* coss.com/ui's unchecked track draws no rim (P180.track-edge).
+*/
+const SWITCH_EDGE = "border-[color:var(--cue-style-switch-edge,var(--cue-border))] hover:border-[color:var(--cue-style-switch-edge,var(--cue-border-strong))]";
+//#endregion
+export { SWITCH_EDGE, SWITCH_THUMB, SWITCH_THUMB_CHECKED, SWITCH_THUMB_DISABLED };

package/dist/system/_style-tab-hover.js

@@ -0,0 +1,15 @@
+//#region src/system/_style-tab-hover.ts
+/**
+* An idle tab's hover ink (round 6, spec §11, lane R6.P: `style-tab-hover-ink`),
+* falling back to the `fg` it drew. coss.com/ui's idle tabs keep their muted ink
+* under the pointer (P182.hover).
+*
+* **Optional** (spec §3.0): each name is declared by `porcelain` alone and each
+* reader falls back to what the component drew. Its own module for docgen's
+* reason: one component's tokens per file.
+*
+* @internal Not part of the public API.
+*/
+const TAB_HOVER_INK = "hover:text-[color:var(--cue-style-tab-hover-ink,var(--cue-fg))]";
+//#endregion
+export { TAB_HOVER_INK };

package/dist/system/_style-tab.js

@@ -0,0 +1,71 @@
+//#region src/system/_style-tab.ts
+/**
+* The `Tabs` list's rule and track, and the active tab: its underline, and its
+* ground, ink, weight and shadow when a Look raises it as a segment.
+*
+* Spec 2026-09-26-looks-fidelity §3.8 (plan R4). The list hung its tabs off a
+* 1px `border-b`, and the active tab laid an accent `::after` over it. A Look
+* that draws its tabs as a segmented track (kiln, porcelain) has neither, and
+* `style-tab-rule` and `style-tab-underline` take them away.
+*
+* **The fallbacks are the classes they replace**: `border-b` is 1px wide, and
+* the underline was the accent, `var(--cue-accent)`. The width utility keeps
+* `border-b`'s solid style, so it replaces it whole.
+*
+* **The list is the track.** `Tabs` has no frame, so the list reads
+* `style-segment-track` and `style-segment-inset`, and falls back to what it
+* had: no ground and no padding (`transparent`, `0px`). Its corners are
+* square, and stay so: a radius on the list would curl the ends of its 1px
+* rule under every set. A Look that draws its tabs on a track (kiln,
+* porcelain) takes the rule away and owes the track its corners; spec §3.8
+* leaves how to the Look lanes.
+*
+* **The active tab**, raised as a segment by a Look that draws its tabs on a
+* track: its ground, ink, weight, edge and resting shade, read through the
+* segment names (`_style-segment.ts` tells the family's story). The ink
+* replaced `data-[active]:text-accent` and keeps that class's standing. The
+* ground falls back to none (`transparent`, spec §3.8): a tab is marked by its
+* underline. The ground, the weight (`400`, inherited and computed under every
+* shipped set) and the shadow (a `transparent` inset edge and the paint axis's
+* resting shade, one list written out for the reason
+* `_style-segmented-control.ts` gives) are declarations the tab had in no
+* state, so they are written `[:where(&[data-active])]:` — the active state at
+* zero specificity — and a caller's `className="font-medium bg-surface-2
+* shadow-sm"` still applies to the active tab as to the others.
+*
+* **Its own module**, for the docgen reason `_style-nav-voice.ts` gives:
+* `SegmentedControl` shares `_style-segment.ts` with the tabs, and reads
+* none of these.
+*
+* @internal Not part of the public API.
+*/
+/** The list behind the tabs, which is the track: its ground and its inset. */
+const TAB_TRACK = "bg-[color:var(--cue-style-segment-track,transparent)] p-[var(--cue-style-segment-inset,0px)] rounded-[var(--cue-style-tab-radius,0px)]";
+/**
+* A tab's corners and its resting weight (plan V.2, P41).
+*
+* Under a set that names `style-tab-radius` the list above is a rounded track
+* and every tab a pill inside it, rounded on all four corners at the track's
+* radius less the inset, as a pressed segment nests inside its frame. Under a
+* set that does not, a tab keeps the `rounded-t-control` it drew: its top two
+* corners at the control corner, its bottom two square on the list's rule.
+* Both are one expression per edge, so neither needs a class the other lacks:
+*
+* - top: `tab-radius`, else the control corner **plus** the inset, less the
+*   inset — which is the control corner exactly, whether or not the set names
+*   an inset (Porcelain names one, 2px, before it names a tab radius);
+* - bottom: `tab-radius`, else the inset, less the inset — `0px`.
+*
+* The weight is the segment weight on every tab, not only the active one —
+* Porcelain's idle tabs are 500 too — falling back to 400. A caller's
+* `font-*` class on a tab replaces it through `tailwind-merge`.
+*/
+const TAB_SHAPE = "rounded-t-[calc(var(--cue-style-tab-radius,calc(var(--cue-radius-control)*var(--cue-radius-scale)+var(--cue-style-segment-inset,0px)))-var(--cue-style-segment-inset,0px))] rounded-b-[calc(var(--cue-style-tab-radius,var(--cue-style-segment-inset,0px))-var(--cue-style-segment-inset,0px))] font-[number:var(--cue-style-segment-weight,400)]";
+/** The list's bottom rule, as a width. */
+const TAB_RULE = "border-b-[length:var(--cue-style-tab-rule,1px)]";
+/** The active tab's underline ink, on its `::after`. */
+const TAB_UNDERLINE = "data-[active]:after:bg-[color:var(--cue-style-tab-underline,var(--cue-accent))]";
+/** The `Tabs` active tab. Its ground falls back to none: a tab is marked by its underline. */
+const TAB_ACTIVE = "[:where(&[data-active])]:bg-[color:var(--cue-style-segment-ground,transparent)] data-[active]:text-[color:var(--cue-style-segment-ink,var(--cue-accent))] [:where(&[data-active])]:font-[number:var(--cue-style-segment-weight,400)] [:where(&[data-active])]:shadow-[inset_0_0_0_var(--cue-border-width)_var(--cue-style-segment-edge,transparent),0_calc(2px*var(--cue-paint-shadow-scale))_calc(4px*var(--cue-paint-shadow-scale))_var(--cue-paint-rest-shade,transparent)]";
+//#endregion
+export { TAB_ACTIVE, TAB_RULE, TAB_SHAPE, TAB_TRACK, TAB_UNDERLINE };

package/dist/system/_style-text-focus.js

@@ -0,0 +1,26 @@
+import { FOCUS_RING_PAINT } from "./_focus-ring.js";
+//#region src/system/_style-text-focus.ts
+/**
+* The focus ring of a text control — a link, and a disclosure's trigger —
+* with its offset read from the style set (round 6, spec §11, lane R6.T:
+* `style-text-focus-offset`).
+*
+* `_focus-ring.ts`'s fixed shapes are the ring every other site draws; these
+* two compose its width and colour ({@link FOCUS_RING_PAINT}) with an offset
+* a Look may move, as the button chassis does with `style-focus-offset`. Each
+* falls back to the fixed shape it replaces: the disclosure's two pixels in
+* (`FOCUS_RING_INSET_2`, because sections sit inside `overflow-hidden` panels)
+* and the link's two pixels clear (`FOCUS_RING_OFFSET_2`). stripe.com draws
+* both rings 3px clear (`--hds-focus-outline-offset` on `.hds-link` and on the
+* accordion's summary), so tender sets `3px` (T128, T144).
+*
+* A name of its own, not `style-focus-offset`: the source draws its buttons'
+* rings at another offset (`--hds-focus-outline-button-offset`, T50).
+*
+* @internal Not part of the public API.
+*/
+const COLLAPSE_FOCUS_RING = `${FOCUS_RING_PAINT} focus-visible:outline-offset-[var(--cue-style-text-focus-offset,-2px)]`;
+/** A link's focus ring: as {@link COLLAPSE_FOCUS_RING}, falling back to two pixels clear. */
+const LINK_FOCUS_RING = `${FOCUS_RING_PAINT} focus-visible:outline-offset-[var(--cue-style-text-focus-offset,2px)]`;
+//#endregion
+export { COLLAPSE_FOCUS_RING, LINK_FOCUS_RING };

package/dist/system/_style-textarea.js

@@ -0,0 +1,21 @@
+//#region src/system/_style-textarea.ts
+/**
+* A textarea's leading and block padding (plan V.2, P139):
+* `style-input-leading`, falling back to the `leading-ui` it drew, and the
+* `space-3` rung times `style-textarea-pad`, `1` under a set that has none.
+* Porcelain's textarea sets 1.45 and 5.5px.
+*
+* The padding is a name of its own and not `style-control-pad`, the button's
+* inline proportion: Tender, Zine and Kiln declare that one (1.5, 1.625,
+* 0.75), and a textarea that read it would move in every one of them where
+* no row measured it.
+*
+* **Optional** (spec §3.0). Its own module for docgen's reason.
+*
+* @internal Not part of the public API.
+*/
+const TEXTAREA_LEADING = "leading-[var(--cue-style-input-leading,var(--cue-leading-ui))]";
+/** @see TEXTAREA_LEADING */
+const TEXTAREA_PAD_Y = "py-[calc(var(--cue-space-3)*var(--cue-style-textarea-pad,1))]";
+//#endregion
+export { TEXTAREA_LEADING, TEXTAREA_PAD_Y };

package/dist/system/_style-title.js

@@ -0,0 +1,37 @@
+//#region src/system/_style-title.ts
+/**
+* The title voice: a `Card`, `Panel` or `Bento` tile's name — mono,
+* `text-emphasis`, weight 500, in `fg`, until a style set says otherwise.
+*
+* Spec 2026-09-26-looks-fidelity §3.3 (and §3.1 for the ink and the variation),
+* plan R1. `CardTitle`, `PanelHeader`'s title and `Bento.Tile`'s title each
+* spelt `font-mono text-(length:--cue-text-emphasis) font-medium text-fg`, so a
+* Look could not move a card's name without a per-call-site class — and every
+* Look the fidelity round measured draws it differently (Tender 26px at 300,
+* Kiln 32px at 400, Porcelain 16px at 700, three of the four in sans).
+*
+* | property                | reads                     | fallback (the class it replaced) |
+* |-------------------------|---------------------------|----------------------------------|
+* | font-family             | `style-title-face`        | `var(--cue-font-mono)` (`font-mono`) |
+* | font-size               | `style-title-size`        | `var(--cue-text-emphasis)` |
+* | font-weight             | `style-title-weight`      | `500` (`font-medium`) |
+* | letter-spacing          | `style-title-tracking`    | `normal` |
+* | line-height             | `style-title-leading`     | `inherit` |
+* | font-variation-settings | `style-display-variation` | `normal` |
+* | color                   | `style-heading-ink`       | `var(--cue-fg)` (`text-fg`) |
+*
+* **Every name is optional** (spec §3.0), declared on no `:root` and left at the
+* shared `[data-style]` reset by every shipped set, so each `var()` resolves its
+* fallback at the title — what the old classes computed there.
+*
+* An overlay's title shares the face, the weight, the ink and the variation but
+* not the size, the tracking or the leading, so it is `_style-overlay-title.ts`
+* and not an import of this: docgen would publish every name in this file as a
+* token of every overlay. `_style-page-title.ts` says why the weight is
+* `font-[number:…]` and why the size comes before the leading.
+*
+* @internal Not part of the public API.
+*/
+const TITLE_VOICE = "font-[family-name:var(--cue-style-title-face,var(--cue-font-mono))] text-[length:var(--cue-style-title-size,var(--cue-text-emphasis))] font-[number:var(--cue-style-title-weight,500)] tracking-[var(--cue-style-title-tracking,normal)] leading-[var(--cue-style-title-leading,inherit)] [font-variation-settings:var(--cue-style-title-variation,var(--cue-style-display-variation,normal))] text-[color:var(--cue-style-heading-ink,var(--cue-fg))]";
+//#endregion
+export { TITLE_VOICE };

package/dist/system/_style-toast.js

@@ -0,0 +1,22 @@
+//#region src/system/_style-toast.ts
+/**
+* A toast's padding and width (round 6, spec §11, lane R6.P: `style-toast-pad-y`,
+* `style-toast-pad-x`, `style-toast-width`), falling back to the `space-3` block
+* and `space-4` inline-start padding and the 20rem viewport it drew; the
+* inline-end padding keeps its room for the close button. coss.com/ui pads its
+* toast 12px by 14px and sets it 360px wide (P184.pad, P184.pad-inline,
+* P184.width).
+*
+* **Optional** (spec §3.0): each name is declared by `porcelain` alone and each
+* reader falls back to what the component drew. Its own module for docgen's
+* reason: one component's tokens per file.
+*
+* @internal Not part of the public API.
+*/
+const TOAST_PAD_Y = "py-[var(--cue-style-toast-pad-y,var(--cue-space-3))]";
+/** @see TOAST_PAD_Y */
+const TOAST_PAD_X = "pl-[var(--cue-style-toast-pad-x,var(--cue-space-4))]";
+/** @see TOAST_PAD_Y */
+const TOAST_WIDTH = "w-[var(--cue-style-toast-width,20rem)]";
+//#endregion
+export { TOAST_PAD_X, TOAST_PAD_Y, TOAST_WIDTH };

package/dist/system/_style-toggle.js

@@ -0,0 +1,50 @@
+//#region src/system/_style-toggle.ts
+/**
+* `Toggle` — and so `ToggleGroup`'s items — at rest and pressed (round 6, spec
+* §11, lane R6.T: `style-toggle-edge`, `style-toggle-ink`,
+* `style-toggle-pressed-ground`, `style-toggle-pressed-edge`).
+*
+* stripe.com's select tiles (`.hds-select-tile`, one of N options drawn as
+* tiles) stand in its field edge at rest (`--hds-color-input-border-default`)
+* with its field text ink (`--hds-color-input-text-solid`), and a selected
+* tile fills with a 12% lilac and edges in its brand-400 (T155). Ours drew a
+* transparent edge in `fg-muted`, and `accent-soft` with no edge when
+* pressed. Each reader falls back to the class it replaced.
+*
+* @internal Not part of the public API.
+*/
+const TOGGLE_EDGE = "border-[color:var(--cue-style-toggle-edge,transparent)]";
+/** A toggle's resting ink. */
+const TOGGLE_INK = "text-[color:var(--cue-style-toggle-ink,var(--cue-fg-muted))]";
+/** A pressed toggle's ground. */
+const TOGGLE_PRESSED_GROUND = "data-[pressed]:bg-[color:var(--cue-style-toggle-pressed-ground,var(--cue-accent-soft))]";
+/** A pressed toggle's edge. */
+const TOGGLE_PRESSED_EDGE = "data-[pressed]:border-[color:var(--cue-style-toggle-pressed-edge,transparent)]";
+/**
+* A pressed toggle's ink (round 6, spec §11, lane R6.K: `style-toggle-pressed-ink`),
+* falling back to the `accent` it drew. replit.com's pressed filter pill is
+* white on an ink fill (K148).
+*/
+const TOGGLE_PRESSED_INK = "data-[pressed]:text-[color:var(--cue-style-toggle-pressed-ink,var(--cue-accent))]";
+/**
+* The hover state (lanes R6.T and R6.K: `style-toggle-hover-edge`, `-hover-ground`,
+* `-hover-ink`). replit.com's filter pills hover by darkening their edge alone
+* (#d8d5cf to #a8a49d), keeping a transparent ground and their resting ink,
+* where ours filled `surface-2` and inked `fg` (K148). Each falls back to what
+* the toggle drew under the pointer: its resting edge (through `style-toggle-edge`),
+* `surface-2` and `fg`.
+*/
+const TOGGLE_HOVER_EDGE = "hover:border-[color:var(--cue-style-toggle-hover-edge,var(--cue-style-toggle-edge,transparent))]";
+/** @see TOGGLE_HOVER_EDGE */
+const TOGGLE_HOVER_GROUND = "hover:bg-[color:var(--cue-style-toggle-hover-ground,var(--cue-surface-2))]";
+/** @see TOGGLE_HOVER_EDGE */
+const TOGGLE_HOVER_INK = "hover:text-[color:var(--cue-style-toggle-hover-ink,var(--cue-fg))]";
+/**
+* A disabled toggle's ink and edge, through the disabled names every control reads
+* (`style-disabled-ink`, `style-disabled-edge`), each falling back to the toggle's own resting value;
+* the fade reads `style-disabled-opacity` as the other controls' does. stripe.com's disabled tile
+* pales its ink and draws its disabled border (T155.disabled, T155.disabled-edge).
+*/
+const TOGGLE_DISABLED = "data-[disabled]:text-[color:var(--cue-style-disabled-ink,var(--cue-style-toggle-ink,var(--cue-fg-muted)))] data-[disabled]:border-[color:var(--cue-style-disabled-edge,var(--cue-style-toggle-edge,transparent))]";
+//#endregion
+export { TOGGLE_DISABLED, TOGGLE_EDGE, TOGGLE_HOVER_EDGE, TOGGLE_HOVER_GROUND, TOGGLE_HOVER_INK, TOGGLE_INK, TOGGLE_PRESSED_EDGE, TOGGLE_PRESSED_GROUND, TOGGLE_PRESSED_INK };

package/dist/system/_style-toolbar.js

@@ -0,0 +1,23 @@
+//#region src/system/_style-toolbar.ts
+/**
+* The toolbar as a framed bar (round 6, spec §11, lane R6.P): its rim on the sides
+* it did not draw (`style-toolbar-rim`, a width, falling back to `0px`, so the
+* bar keeps only its bottom rule) and the rim's ink (`style-toolbar-edge`,
+* falling back to `border`); its corner, padding, height and gap
+* (`style-toolbar-radius`, `-pad`, `-height`, `-gap`), falling back to the
+* square, inline-padded, `chrome-toolbar`-tall strip it drew; and a separator's
+* height (`style-toolbar-separator-height`), falling back to `60%`. coss.com/ui
+* draws its toolbar as a 14px-rounded bar in a 1px rim, 4px in, its groups 8px
+* apart and its separators 20px tall (P185).
+*
+* **Optional** (spec §3.0): each name is declared by `porcelain` alone and each
+* reader falls back to what the component drew. Its own module for docgen's
+* reason: one component's tokens per file.
+*
+* @internal Not part of the public API.
+*/
+const TOOLBAR_FRAME = "border-t-[length:var(--cue-style-toolbar-rim,0px)] border-x-[length:var(--cue-style-toolbar-rim,0px)] border-[color:var(--cue-style-toolbar-edge,var(--cue-border))] rounded-[var(--cue-style-toolbar-radius,0px)] p-[var(--cue-style-toolbar-pad,0_var(--cue-pad-row-x))] h-[var(--cue-style-toolbar-height,var(--cue-chrome-toolbar))] gap-[var(--cue-style-toolbar-gap,var(--cue-space-2))]";
+/** @see TOOLBAR_FRAME */
+const TOOLBAR_SEPARATOR_HEIGHT = "data-[orientation=vertical]:h-[var(--cue-style-toolbar-separator-height,60%)]";
+//#endregion
+export { TOOLBAR_FRAME, TOOLBAR_SEPARATOR_HEIGHT };

package/dist/system/_style-tooltip.js

@@ -0,0 +1,46 @@
+//#region src/system/_style-tooltip.ts
+/**
+* A tooltip's size and padding (plan V.2, P129): the help size, falling back
+* to the `text-label` rung the tooltip drew, and `style-tooltip-pad`, one or
+* two rem lengths, falling back to the `space-2` block and `space-3` inline
+* padding it drew. Porcelain's tooltip is 12px type, 4px by 8px in. Its
+* leading is the body leading (`_style-body-leading.ts`).
+*
+* **Optional** (spec §3.0). Its own module for docgen's reason.
+*
+* @internal Not part of the public API.
+*/
+const TOOLTIP_SIZE = "text-[length:var(--cue-style-help-size,var(--cue-text-label))]";
+/** @see TOOLTIP_SIZE */
+const TOOLTIP_PAD = "p-[var(--cue-style-tooltip-pad,var(--cue-space-2)_var(--cue-space-3))]";
+/**
+* The tooltip's tracking (round 6, spec §11, lane R6.T: `style-tooltip-tracking`),
+* falling back to the `inherit` it drew (no tracking class of its own).
+* stripe.com's tooltip sets 0.2px on its 15px text, 0.0133em (T131).
+*/
+const TOOLTIP_TRACKING = "tracking-[var(--cue-style-tooltip-tracking,inherit)]";
+/**
+* The tooltip's corner (round 6, spec §11, lane R6.T: `style-tooltip-radius`), falling back to the
+* overlay corner it drew. stripe.com's overlays take three corners — its dialog 16px, its select
+* popover 4px (which `radius-overlay` follows), its tooltip 8px (T131.radius) — and the dialog already
+* has `style-dialog-radius`. Scaled by `radius-scale` as the dialog's is: `rounded-overlay` is
+* `calc(var(--cue-radius-overlay) * var(--cue-radius-scale))`, and a reader without the scale drew
+* 6px where the tooltip drew 4.5px at ultra-compact (the closing pass's adversarial review).
+*/
+const TOOLTIP_RADIUS = "rounded-[calc(var(--cue-style-tooltip-radius,var(--cue-radius-overlay))*var(--cue-radius-scale))]";
+/**
+* The tooltip's face (round 6, spec §11, lane R6.Z: `style-tooltip-face`),
+* falling back through the control face to the mono it drew. greptile.com's
+* seat tooltip is Space Mono beside its DM Sans buttons (Z115).
+*/
+const TOOLTIP_FACE = "font-[family-name:var(--cue-style-tooltip-face,var(--cue-style-control-face,var(--cue-font-mono)))]";
+/** The tooltip's ink (`style-tooltip-ink`), falling back to the `fg` it drew; greptile.com's is slate (Z115). */
+const TOOLTIP_INK = "text-[color:var(--cue-style-tooltip-ink,var(--cue-fg))]";
+/**
+* The tooltip's leading (`style-tooltip-leading`), falling back through the
+* body leading to the `leading-ui` it drew (`BODY_LEADING`). greptile.com's
+* tooltip sets a 20px line on 10px type (Z115).
+*/
+const TOOLTIP_LEADING = "leading-[var(--cue-style-tooltip-leading,var(--cue-style-body-leading,var(--cue-leading-ui)))]";
+//#endregion
+export { TOOLTIP_FACE, TOOLTIP_INK, TOOLTIP_LEADING, TOOLTIP_PAD, TOOLTIP_RADIUS, TOOLTIP_SIZE, TOOLTIP_TRACKING };

package/dist/system/density.d.ts

@@ -1,3 +1,4 @@
+import "./published.js";
 import * as React from "react";
 import { Paint, StyleSet } from "@cueplusplus/tokens";
 import { Density as Density$1 } from "@cueplusplus/theme-base";
@@ -9,7 +10,7 @@ interface DensityProps {
    */
   density: Density$1;
   /**
-   * A look pack for this subtree.
+   * A paint pack for this subtree.
    *
    * Optional, and **absent means inherit**, exactly as `styleSet` is: an island
    * that names none stamps no `data-paint` and passes the ambient pack straight
@@ -18,7 +19,8 @@ interface DensityProps {
    */
   paint?: Paint;
   /**
-   * A style set for this subtree: `console`, `editorial` or `marketing`.
+   * A style set for this subtree: `console`, `editorial`, `marketing` or
+   * `graphite`.
    *
    * Optional, and **absent means inherit** — an island that names none stamps no
    * `data-style` and passes the ambient set straight through, exactly as a bare
@@ -27,7 +29,7 @@ interface DensityProps {
    *
    * - `console` inside a page that is not console. That is the whole job of the
    *   default set: it restates the `:root` defaults, so a subtree stamped with
-   *   it renders the ordinary look inside an editorial or marketing page.
+   *   it renders the ordinary look inside a page under any other set.
    * - Moving the band rhythm with the rung. `--cue-band-y` is
    *   `calc(var(--cue-space-7) * 2)` declared on the `[data-style]` element, and
    *   a custom property's `var()` references are substituted where they are
@@ -35,6 +37,13 @@ interface DensityProps {
    *   the rhythm already resolved above it. Restating the set here re-resolves
    *   it against this island's rung, which is how a denser island gets a
    *   proportionally tighter band instead of the outer one's.
+   *
+   * The library restates the set for you where an island changes what a set's
+   * values read besides the rung — the theme's inks, the pairing's faces: a
+   * nested `ThemeProvider` that names a theme or a mode, and a `Preview` stage
+   * with a theme, a mode or a pairing, stamp the set and the pack in force
+   * beside it. This island changes only the rung, so it does not, and the
+   * rhythm above stays the opt-in the second bullet describes.
    */
   styleSet?: StyleSet;
   /** Subtree that should render at `density`. */
@@ -58,7 +67,7 @@ interface DensityProps {
  * omitted where there is none. It is read by nothing this island does —
  * theme and mode are deliberately *not* re-scoped here; density was for a long
  * time the only axis an island could override (spec §6), and a named
- * `styleSet` is the second and last — it exists so a theme's own
+ * `styleSet` and a named `paint` are the other two — it exists so a theme's own
  * generated CSS can address exactly this island regardless of how many
  * *other* themed providers sit between it and the one it belongs to. A CSS
  * ancestor selector can only ask "does some ancestor carry theme `x`", never
@@ -70,7 +79,8 @@ interface DensityProps {
  * is how the axis inherits: custom properties inherit down the DOM, so an island
  * that stamped the ambient set would be restating an answer it already had, and
  * an island that stamped a *default* set would silently re-point the rhythm of
- * every page that nested one.
+ * every page that nested one. `data-paint` joins them on exactly those terms
+ * when a `paint` is named.
  *
  * @example
  * <Density density="ultra-compact">