@cube-dev/ui-kit 0.162.0 → 0.164.0

package/docs/components/layout/Board.md

@@ -61,13 +61,15 @@ clipped by an ancestor's `overflow: hidden`.
 - **`compact`** `'vertical' | 'horizontal' | 'free' | null` (default: `'vertical'`) — Compaction behavior. `'vertical'`/`'horizontal'` reflow widgets to remove gaps; `'free'` places each widget exactly where dropped and never pushes its neighbours (blocked from occupied cells unless `allowOverlap`); `null` disables compaction but still resolves collisions the legacy react-grid-layout way.
 - **`allowOverlap`** `boolean` (default: `false`) — Allow widgets to overlap (stack). In `'free'` mode this is what distinguishes stacking from blocking a drop onto an occupied cell.
 - **`preventCollision`** `boolean` (default: `false`) — Block movement into occupied cells instead of pushing.
+- **`collisionMode`** `'revert' | 'downscale' | 'swap'` (default: `'revert'`) — How to resolve a drop the grid would otherwise refuse. Only applies where a collision *blocks* a move — `compact="free"` (which prevents collisions) or an explicit `preventCollision` — and never under `allowOverlap`, where nothing is blocked. `'revert'` snaps the widget back. `'downscale'` shrinks it into the free space at the drop cell, growing rightward and downward, floored at its `minW`/`minH` (below that it reverts). `'swap'` trades places with **one** widget — the one the drop covers most — which takes the cell the drag began at, each keeping as much of its own size as fits there (so a widget displaced next to a neighbour may shrink). It never displaces more than that one widget. A drop straddling two widgets trades with one of them rather than refusing, so the swap never blinks away as you sweep across a boundary; ties go to the widget earlier in reading order. Dragging back retraces the original arrangement exactly. It falls back to `'downscale'`, then `'revert'`. No mode ever *grows* a widget: a drag only ever preserves or reduces size. Applies to single-widget drags. Arrow keys honour it too but never resize anything — each press is a gesture of its own, so a press that shrank a widget would have nothing to restore from, and only an exchange that fits outright is allowed. A multi-widget selection still only moves where it fits outright, and a resize is still blocked by a collision.
 - **`isDraggable`** `boolean` (default: `true`) — Enable dragging for all widgets.
 - **`isResizable`** `boolean` (default: `true`) — Enable resizing for all widgets.
 - **`isDroppable`** `boolean` (default: `true`) — Whether the board accepts widgets dropped from other boards.
 - **`resizeHandles`** `ResizeHandleAxis[]` (default: `['se']`) — Which resize handles to show. Corner handles (`ne`/`nw`/`se`/`sw`) show an angle grip; edge handles (`n`/`s`/`e`/`w`) show a dotted grip. Both are revealed on hover/focus/resize. A single edge (e.g. `['e']` or `['s']`) gives a horizontally- or vertically-only resizable widget.
+- **`resizeGripPlacement`** `'inside' | 'corner'` (default: `'inside'`) — Where the corner grips sit. `'inside'` tucks each one into the widget box; `'corner'` centres it on the widget's corner, so it lines up with a control centred on the opposite corner. Only affects corner handles — a dotted edge grip always stays inside. A corner-placed grip is drawn *outside* the widget (a widget clips its own content, which would otherwise cut the grip in half), so it needs the board to have at least half a grip's worth of `containerPadding` to show in full against the board's edge. Its hit-zone moves out with it and overhangs by the same half-grip, so the whole visible grip is grabbable and hovering it keeps it revealed — the trade is a ~5px band just outside each corner where a press starts a resize rather than a marquee. Can be overridden per widget.
 - **`dragCancel`** `string` — CSS selector for elements that must not start a pointer drag (e.g. form controls inside a widget: `"input,textarea,button,a,.no-drag"`). Does not affect keyboard moves — those only run when the widget host itself is focused. Can be overridden per widget.
 - **`dragHandle`** `string` — CSS selector for the only elements from which a pointer drag may start. Can be overridden per widget.
-- **`showGridLines`** `boolean | 'drag'` (default: `false`) — Show grid lines behind the widgets. `true` always, `'drag'` only while a widget is being dragged or resized. A nested board that does not set this inherits an enabled ancestor's grid lines, showing its own while a drag is in progress.
+- **`showGridLines`** `boolean | 'drag' | 'any-drag'` (default: `false`) — Show grid lines behind the widgets. `true` always; `false` never; `'drag'` only while *this* board is part of the active gesture — it owns the drag (as its source, or as the board the widget is currently over) or one of its own widgets is being resized; `'any-drag'` while any drag is in flight anywhere under a shared `Board.Provider`, so every board advertises itself as somewhere the widget could land. Under one `Board.Provider`, `'drag'` keeps boards a widget cannot land in quiet, and `'any-drag'` is the opt-in for the noisier, more informative version. A nested board that does not set this inherits an enabled ancestor's setting, at the ancestor's own scope.
 - **`isAligned`** `boolean` (default: `false`) — Align a nested board with its ancestor `Board`'s layout. Only takes effect when the board is nested inside another `Board`'s widget. When set, every cell matches the parent's cell size exactly: the board inherits the parent's column pitch (deriving its own column count from its measured width so cells stay parent-sized as the container is resized) and uses the parent's row height verbatim. It never shrinks rows to fit — pair it with an `isAutoHeight` container so the widget grows to fit its rows at that height. `cols`/`rowHeight` then act as fallbacks used only until the parent metrics resolve.
 - **`selectionMode`** `'none' | 'single' | 'multiple'` (default: `'none'`) — Whether widgets can be selected, and how many at a time. `'multiple'` also enables the marquee and rigid group movement.
 - **`selectedKeys`** `string[]` — Controlled selection. Keys are layout item ids (`LayoutItem.i`).
@@ -89,6 +91,7 @@ clipped by an ancestor's `overflow: hidden`.
 - **`isDraggable`** `boolean` — Disable dragging for this widget.
 - **`isResizable`** `boolean` — Disable resizing for this widget.
 - **`resizeHandles`** `ResizeHandleAxis[]` — Override the board's handles.
+- **`resizeGripPlacement`** `'inside' | 'corner'` — Override the board's grip placement.
 - **`minW`** `number` — Minimum width in grid columns. Used when the layout item omits `minW`; the resize handle stops here.
 - **`maxW`** `number` — Maximum width in grid columns. Used when the layout item omits `maxW`.
 - **`minH`** `number` — Minimum height in grid rows. Used when the layout item omits `minH`.
@@ -237,7 +240,22 @@ Bound resizing with per-widget `minW`/`maxW` (columns) and `minH`/`maxH` (rows).
 
 ### Grid lines
 
-Show grid lines behind the widgets while dragging or resizing (or always).
+Show grid lines behind the widgets while dragging or resizing (or always). With
+several boards under one `Board.Provider`, `'drag'` lights up only the board the
+drag belongs to; `'any-drag'` lights up all of them.
+
+### Corner resize grip
+
+Centre the resize grip on the widget's corner with `resizeGripPlacement="corner"`,
+so it lines up with a control centred on the opposite corner.
+
+### Resolving a blocked drop
+
+On a free grid a drop onto occupied cells is refused. `collisionMode` resolves it
+instead: `'downscale'` shrinks the widget into whatever room is at the drop cell,
+`'swap'` trades places with the widget already there. Neither ever grows a widget.
+One board per mode below — drag the wide widget onto the row below in the first,
+and drop a widget onto one of its neighbours in the second.
 
 ### Card widgets
 

package/docs/components/other/NoDataIcon.md

@@ -0,0 +1,48 @@
+# NoDataIcon
+
+The empty isometric crate — the kit's "nothing here yet" illustration.
+
+It is an **illustration, not a member of the icon set**, which is why it lives in `Other/` rather than under `Content/Icons`. It is still built on `Icon`, so it sizes and accepts style props exactly like one.
+
+## When to Use
+
+- An empty table, list, or card grid — "No invoices yet", "No deployments yet"
+- A full-page empty state, paired with a short line of copy
+- Anywhere `LoadingAnimation` would sit if the same view were still loading
+
+## Sizing
+
+`size` maps onto `font-size` and drives both axes; the artwork is square.
+
+```jsx
+<NoDataIcon size="8x" />
+```
+
+Unlike a glyph icon, the drawing is full-bleed in its viewBox rather than inset in a 24×24 grid, so it is meant for illustration sizes — `size="8x"` (64px) and up. At icon sizes it will read as noticeably heavier than the glyphs around it.
+
+## Colour
+
+Not a `currentColor` glyph, so it **ignores `color`**. The three faces come from the shared isometric cube-face tokens (`#loading-face-1` … `#loading-face-3`) that [`LoadingAnimation`](../status/LoadingAnimation.md) also draws from, so an empty table and a loading table read as the same object lit the same way.
+
+That ramp is positioned by a WCAG floor against `#surface`, so each face keeps the same separation from the page in light, dark, and high contrast, and follows a re-seeded brand hue as a tint rather than as a colour. Recolouring one face and not the others would break the shading, which is why there is no prop for it.
+
+## Properties
+
+- **`size`** `Styles['fontSize']` — Icon size; drives both axes
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+### Style Properties
+
+Accepts the same style props as `Icon` — outer, base, and color style props.
+
+## Examples
+
+```jsx
+<Flow gap="1x" placeItems="center">
+  <NoDataIcon size="8x" />
+  <Paragraph>No invoices yet.</Paragraph>
+</Flow>
+```

package/docs/components/overlays/DialogTrigger.md

@@ -36,6 +36,7 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`targetRef`** — The ref of the element the Dialog should visually attach itself to
 - **`styles`** — The style map for the overlay
 - **`shouldCloseOnInteractOutside`** — Function to determine if overlay should close on outside interaction
+- **`shouldRestoreFocus`** `boolean` (default: `true`) — Whether focus returns to the trigger when the dialog closes. Only needed for a surface that claims focus *later* than the restore (async load, entry animation); an action that focuses the surface it opens is already left alone — see [Focus Management](#best-practices)
 
 ### Base Properties
 
@@ -52,7 +53,7 @@ These properties allow direct style application without using the `styles` prop:
 - **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
 - **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
 - **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
-- **Flow:** `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
 ## Variants
 
@@ -186,7 +187,7 @@ function ControlledDialog() {
    </DialogTrigger>
    ```
 
-3. **Focus Management**: Always ensure focus returns properly after dialog closes
+3. **Focus Management**: Closing the dialog returns focus to the trigger, unless the action that closed it already moved focus somewhere else — an action that opens a panel or another dialog just focuses that surface, and the trigger leaves it alone. A single `focus()` from a mount effect is enough; no retry loop is needed. Reach for `shouldRestoreFocus={false}` only when the opened surface claims focus *later* than the restore (after an async load or an entry animation), where the trigger would otherwise take focus first and flash.
 4. **Mobile Considerations**: Use appropriate mobile types for better UX
 5. **Dismissible**: Make modal dialogs dismissible unless absolutely necessary
 

package/docs/components/status/LoadingAnimation.md

@@ -36,3 +36,15 @@ These properties allow direct style application without using the `styles` prop:
 
 <LoadingAnimation size="large" />
 ```
+
+## Colors
+
+The cube's three faces come from the shared isometric-cube tokens
+(`#loading-face-1` … `#loading-face-3`), a near-neutral ramp positioned by a WCAG
+floor against `#surface`. Each face therefore keeps the same separation from the
+page in light, dark, and high contrast, and follows a re-seeded brand hue as a
+tint rather than as a color. There is no `color` prop to override — recolouring
+one face and not the others would break the shading.
+
+[`NoDataIcon`](../other/NoDataIcon.md) draws its empty crate from the same
+three tokens, so a loading table and an empty table read as the same object.

package/docs/glaze/api.md

@@ -411,9 +411,9 @@ promotion for that color.
 
 ## Manual contrast level
 
-`contrastLevel` turns contrast from a two-tier switch into a `0–100` slider.
-It is a config field, so it works globally, per theme, per token, and through
-`extend()`:
+`contrastLevel` puts the normal end of the two-tier contrast model on a `0–100`
+slider. It is a config field, so it works globally, per theme, per token, and
+through `extend()`:
 
 ```ts
 glaze.configure({ contrastLevel: 60 });
@@ -421,12 +421,17 @@ const theme = glaze(280, 80, { contrastLevel: 60 });
 glaze.color('#26fcb2', { contrastLevel: 60 });
 ```
 
-| Value            | Meaning                                                              |
-| ---------------- | -------------------------------------------------------------------- |
-| `'auto'`         | Default. The two-tier model: normal variants plus a high-contrast tier. |
-| `0`              | Normal contrast, with **no** high-contrast tier.                      |
-| `100`            | The high-contrast scheme as the only scheme.                          |
-| anything between | Resolved *at* that level.                                            |
+The level moves the **normal** variants — `light` and `dark` — along that slider.
+It says nothing about high contrast: `lightContrast` / `darkContrast` stay the
+true high-contrast resolution at every level, and
+[`modes.highContrast`](#output-modes) alone decides whether they are emitted.
+
+| Value            | Meaning                                                                    |
+| ---------------- | -------------------------------------------------------------------------- |
+| `'auto'`         | Default. The normal variants take the authored normal entries as-is.        |
+| `0`              | The same thing, reached through the slider — output-identical to `'auto'`.  |
+| `100`            | The normal variants *are* the high-contrast ones, so the tier is dropped.   |
+| anything between | The normal variants are resolved *at* that level.                          |
 
 Levels `0` and `100` reproduce the classic `light` / `dark` and
 `lightContrast` / `darkContrast` output **bit for bit**.
@@ -446,6 +451,9 @@ The interpolated values are then fed through the ordinary resolve, so a
 contrast floor at any level is **solved**, not approximated, and `autoFlip`
 decides once per level.
 
+These feed the two **normal** passes only. The high-contrast passes bypass the
+level entirely, so the tier resolves exactly as it does in `'auto'` mode.
+
 Everything that does not vary by high contrast today — hue, saturation,
 `darkDesaturation`, `opacity`, `pastel` — is unaffected by the level.
 
@@ -495,24 +503,35 @@ directly.
 
 ### High-contrast output
 
-A manual level already carries the contrast preference, so there is no second
-tier to emit:
-
-- `resolve()` still returns four variants, but `lightContrast` / `darkContrast`
-  **mirror** `light` / `dark`.
-- A **global** level turns high-contrast output off outright, so
-  `tokens()` / `tasty()` / `json()` / `dtcg()` / `dtcgResolver()` / `tailwind()`
-  emit no high-contrast tier. `modes.highContrast` goes inert — it reads as
-  "emit a separate high-contrast set *when* contrast is automatic" — so leaving
-  `highContrast: true` set in a build config while a user switches their
-  preference from auto to manual is fine, and silent.
+The level and the high-contrast tier are independent, and they compose: the
+slider raises the baseline, and a `prefers-contrast: more` block still escalates
+on top of whatever baseline the user has chosen.
+
+- `resolve()` returns four variants at every level. `lightContrast` /
+  `darkContrast` are the **true** high-contrast resolution — bit-identical to
+  what `'auto'` resolves for those slots, at any level.
+- [`modes.highContrast`](#output-modes) alone decides whether the tier is
+  emitted, exactly as in `'auto'` mode. A level does not turn it off.
 - `css()` always returns four strings and ignores `modes`, so its
-  `lightContrast` / `darkContrast` strings repeat the normal declarations —
-  an existing `@media (prefers-contrast: more)` block keeps matching the base
-  block as the level changes, with nothing to rewire.
+  `lightContrast` / `darkContrast` strings now carry genuinely escalated values
+  at a mid level, where they previously repeated the normal declarations. An
+  existing `@media (prefers-contrast: more)` block starts doing real work.
 - A level on a **single theme or token** does not change which modes are
-  emitted. Sibling themes in a palette keep their real high-contrast tier, and
-  the manual one reports its own resolved values there.
+  emitted — `modes` is global-only, and a palette must not have one sibling
+  collapse the shared token structure.
+
+| `contrastLevel`   | `modes.highContrast: false` (default) | `modes.highContrast: true`               |
+| ----------------- | ------------------------------------- | ---------------------------------------- |
+| `'auto'` / `0`    | `light`, `dark`                       | + `lightContrast`, `darkContrast`        |
+| `1`–`99`          | `light`, `dark` at the level          | + the tier, unchanged by the level       |
+| `100` (global)    | `light`, `dark` = the HC values       | same — the tier is dropped as a duplicate |
+
+That last row is the one exception. At level 100 the normal variants *are* the
+high-contrast ones, so a separate tier would be an exact duplicate: a global
+level of 100 emits a single light/dark set, and even an explicit
+`modes: { highContrast: true }` on the call is suppressed, because it has nothing
+different left to ask for. A level of 100 on a single theme or token still
+reports into the tier, with values equal to its own normal ones.
 
 ### Driving it at runtime
 
@@ -526,8 +545,9 @@ slider.oninput = () => {
 };
 ```
 
-Because a manual level skips the two high-contrast passes, a manual resolve is
-also half the work of an `'auto'` one.
+A manual resolve runs the same four passes as an `'auto'` one. Only level 100
+skips the two high-contrast passes, because the normal ones already produced
+those values.
 
 ### Clearing it, exporting it, base links
 
@@ -540,7 +560,9 @@ also half the work of an `'auto'` one.
   matches how `modes` and `states` are treated.
 - **Set the level globally, or on both sides of a base link.** A per-token level
   on a dependent but not on its base anchors the two at different levels — the
-  same caveat as a per-instance `lightTone` override.
+  same caveat as a per-instance `lightTone` override. It is visible in the
+  high-contrast tier too, since a dependent's high-contrast variant reads its
+  base's high-contrast slots (and at level 100, the base's mirrored normal ones).
 
 `resolveContrastForLevel(spec, level, polarity?)` is exported for advanced use;
 see [Contrast solver](#contrast-solver).
@@ -559,8 +581,9 @@ type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 
 | Field        | Type                            | Description                                                                                                                                                                                                                                                                        |
 | ------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tone`       | `HCPair<ToneValue>`             | Number = absolute (0–100). `'+N'`/`'-N'` = a signed **tone delta** from the base (requires `base`). `'max'`/`'min'` = forced to the scheme's tone extreme (no `base`). Optional HC pair `[normal, hc]`.                                                                            |
-| `saturation` | `number`                        | Saturation factor applied to the seed saturation (0–1). Default: `1`.                                                                                                                                                                                                              |
+| `from`       | `GlazeColorValue`               | Seed this color from a literal value (hex, `rgb()`, `hsl()`, `okhsl()`, `okhst()`, `oklch()`, or a value object). Supplies `hue`, `tone`, and an **absolute** saturation — the one way a theme color escapes the seed ceiling. Light/normal-contrast reproduces it exactly. See [`from`](#from-a-literal-color).             |
+| `tone`       | `HCPair<ToneValue>`             | Number = absolute (0–100). `'+N'`/`'-N'` = a signed **tone delta** from the base (requires `base`). `'max'`/`'min'` = forced to the scheme's tone extreme (no `base`). Optional HC pair `[normal, hc]`. Defaults to the tone of `from`.                                             |
+| `saturation` | `number`                        | Saturation factor applied to the seed saturation (0–1). Default: `1`. With `from`, setting it overrides the color's absolute saturation and reverts to a factor of the seed.                                                                                                       |
 | `hue`        | `number \| RelativeValue`       | Number = absolute (0–360). String (`'+N'`/`'-N'`) = relative to the **theme seed hue** (never to a base color).                                                                                                                                                                    |
 | `darkHue`    | `number \| RelativeValue`       | Dark-scheme hue. Number = absolute (0–360). String = relative to the **theme dark seed hue**. Falls back to `hue`. See [Dark seed](#dark-seed-darkhue--darksaturation).                                                                                                            |
 | `darkSaturation` | `number`                    | Dark-scheme saturation factor (0–1) over the dark seed saturation. Falls back to `saturation`. When set, the global `darkDesaturation` reduction is **not** applied on top.                                                                                                        |
@@ -573,6 +596,61 @@ type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 | `role`       | `RoleInput`                     | Semantic role against `base` (`'text'` / `'surface'` / `'border'` or an alias). Fixes APCA contrast polarity. Resolved via: explicit `role` → name inference → opposite of the base's role → `'text'`. See [Roles](#roles).                                                        |
 | `inherit`    | `boolean`                       | Whether this color is inherited by child themes via `extend()`. Default: `true`. Set to `false` to make the color local to the current theme.                                                                                                                                      |
 
+#### `from` (a literal color)
+
+Most of Glaze answers the question "design me a palette". `from` answers the
+other one: **"honor this color."** White-label products, multi-tenant branding
+and imported design tokens all arrive with a value already chosen, and it is a
+contract rather than a starting point.
+
+```ts
+const theme = glaze(280, 80);
+
+theme.colors({
+  surface: { tone: 100, saturation: 0.12 },
+  brand: { from: '#2f5bff', base: 'surface', contrast: 3 },
+});
+```
+
+It accepts the same values as [`glaze.color()`](#input-forms) and supplies three
+things at once: `hue`, `tone`, and — uniquely among theme colors — an
+**absolute saturation**.
+
+That last one is the point. Every other color's `saturation` is a 0–1 factor of
+the theme seed, so the seed is a ceiling: without `from`, the only way to place
+a color more saturated than its theme is to re-seed the whole theme, dragging
+every sibling along. A `from` color carries its own chroma and is unaffected by
+the seed:
+
+```ts
+// Identical output at every seed saturation — the color is the color.
+for (const seed of [5, 50, 100]) {
+  glaze(280, seed).colors({ brand: { from: '#2f5bff' } }); // → #2f5bff
+}
+```
+
+**What "exactly" covers.** The **light, normal-contrast** variant reproduces the
+value (a local `lightTone: false`, the same default the value-shorthand form of
+`glaze.color()` applies). Dark and high contrast adapt as usual. That asymmetry
+is deliberate: those are the variants a reader reaches for when the normal one
+does not work for them, so readability outranks fidelity there — and a color
+pinned across all four would just be a worse `mode: 'static'`.
+
+A `contrast` floor still applies in every scheme and is still a floor, not a
+target: a value that already clears it is emitted untouched, and one that misses
+moves only as far as the floor. Because the floor is solved per scheme, which
+scheme comes out exact depends on the color — a light brand cannot clear 3:1 on
+a white page but clears it easily on a dark one.
+
+Sibling fields win over what the value supplied, so `{ from: '#2f5bff', hue: 300 }`
+keeps the saturation and tone and rotates the hue. Note that a `saturation`
+written alongside `from` reverts to its usual meaning — a factor of the seed,
+not of the color.
+
+A `from` color needs no `base` and no `tone`: it is placed absolutely, so it
+stands as a root on its own. Add `base` + `contrast` when it has to stay legible
+against something.
+
 #### Tone values
 
 `tone` (0–100) replaces authored OKHSL lightness with a contrast-shaped axis.
@@ -599,7 +677,7 @@ delta is kept and clamped on the authored side.
 
 **Extreme tone** (`'max'` / `'min'`) forces the color to the scheme's tone extreme without a contrast hack or a magic number. `'max'` resolves to author tone 100 and `'min'` to 0. Without a `base`, both flow through scheme mapping like an absolute tone, so under `mode: 'auto'` they invert in dark (`'max'` is lightest in light, darkest in dark). Use `mode: 'static'` to pin the same extreme across schemes, or `mode: 'fixed'` to keep the same end without inverting. No `base` required.
 
-**Extreme tone with a `base`** keeps the pair's contrast across schemes. The tone windows are asymmetric by default (`lightTone: [10, 100]`, `darkTone: [15, 95]`), so re-mapping the extreme through the dark window would squeeze the base-to-extreme span and cost contrast. Instead Glaze measures the tone shift the light scheme applied between the base and the extreme, then replays it against the base's resolved dark tone — mirrored under `mode: 'auto'` (both ends invert), same-signed under `'fixed'`. The result is clamped to `[0, 100]` only, so it may cross the `darkTone` window edge; that is intentional, since the author asked for the extreme. When the shift does not fit above or below the dark base, the color pins at tone 100 / 0. `mode: 'static'` is unaffected, and high-contrast variants already use the full range.
+**Extreme tone with a `base`** keeps the pair's contrast across schemes. The tone windows are asymmetric by default (`lightTone: [10, 100]`, `darkTone: [15, 95]`), so re-mapping the extreme through the dark window would squeeze the base-to-extreme span and cost contrast. Instead Glaze measures the tone shift the light scheme applied between the base and the extreme, then replays it against the base's resolved dark tone — mirrored under `mode: 'auto'` (both ends invert), same-signed under `'fixed'`. The result is clamped to `[0, 100]` only, so it may cross the `darkTone` window edge; that is intentional, since the author asked for the extreme. When the shift does not fit above or below the dark base, the color pins at tone 100 / 0. `mode: 'static'` is unaffected. High-contrast variants follow the same rule, but since their window is already the full range the replay reproduces the plain mapping unless the base itself sits asymmetrically across schemes.
 
 ```ts
 theme.colors({
@@ -1711,11 +1789,11 @@ boundaries, not the tone transfer.
 | `states.dark`         | `'@media(prefers-color-scheme: dark)'` | State alias for dark mode tokens ([Tasty](https://tasty.style) export). Defaults to a media query so tokens react to the OS preference without registering custom states.                                                                                                                                                                                                                                                                        |
 | `states.highContrast` | `'@media(prefers-contrast: more)'`     | State alias for HC tokens ([Tasty](https://tasty.style) export).                                                                                                                                                                                                                                                                                                                                                                                 |
 | `modes.dark`          | `true`                                 | Include dark variants in exports.                                                                                                                                                                                                                                                                                                                                                                                         |
-| `modes.highContrast`  | `false`                                | Include HC variants. Inert while a global [`contrastLevel`](#manual-contrast-level) is set — a manual level has no separate HC tier, so this reads as "emit HC variants when contrast is automatic".                                                                                                                                                                                                                                                                                   |
+| `modes.highContrast`  | `false`                                | Include HC variants. Independent of [`contrastLevel`](#manual-contrast-level) — the level positions the normal variants while these stay the true HC resolution. A global level of `100` is the exception: the tier would duplicate the normal set, so it is dropped.                                                                                                                                                                                                                                                                                   |
 | `shadowTuning`        | `undefined`                            | Default tuning for all shadow colors. Per-color tuning merges field-by-field.                                                                                                                                                                                                                                                                                                                                             |
 | `autoFlip`            | `true`                                 | Default for each color's `autoFlip`. When solving `contrast` (or applying a relative `tone` that overshoots `[0, 100]`), allow crossing to the opposite side instead of clamping. With `false`, only the requested direction is considered; unmet contrasts pin the tone to that direction's extreme (and emit a warning) and overshooting offsets clamp to the boundary. Override per color via [`autoFlip`](#autoflip). |
 | `inferRole`           | `true`                                 | Infer each color's [`role`](#roles) from its name when no explicit `role` is set. Set to `false` to opt out of name-based inference (the base-opposite and foreground-default fallbacks still apply).                                                                                                                                                                                                                     |
-| `contrastLevel`       | `'auto'`                               | Manual contrast level, `0`–`100`, replacing the two-tier high-contrast model with a slider. `0` reproduces the normal output and `100` the high-contrast output, bit for bit. See [Manual contrast level](#manual-contrast-level).                                                                                                                                                                                          |
+| `contrastLevel`       | `'auto'`                               | Manual contrast level, `0`–`100`, putting the **normal** variants on a slider between themselves and the high-contrast ones. `0` reproduces the normal output and `100` the high-contrast output, bit for bit. The HC tier is unaffected. See [Manual contrast level](#manual-contrast-level).                                                                                                                                                                                          |
 
 | Method                    | Description                                                                         |
 | ------------------------- | ----------------------------------------------------------------------------------- |
@@ -1723,7 +1801,7 @@ boundaries, not the tone transfer.
 | `glaze.getConfig()`       | Snapshot the current resolved config (shallow copy).                                |
 | `glaze.resetConfig()`     | Reset to defaults (also bumps the version counter).                                 |
 
-Themes and standalone color tokens keep a sparse local `GlazeConfigOverride` and merge the live global at resolve time for omitted fields. Authoring `.export(override?)` freezes the effective merge at call time; restored instances pin that freeze. `pastel` is instance-only (theme/token override or per-color) — not set via `configure()`. `contrastLevel` is the one field the freeze treats as a live preference: only an instance-authored level is written to the snapshot ([why](#two-rules-worth-knowing)).
+Themes and standalone color tokens keep a sparse local `GlazeConfigOverride` and merge the live global at resolve time for omitted fields. Authoring `.export(override?)` freezes the effective merge at call time; restored instances pin that freeze. `pastel` is instance-only (theme/token override or per-color) — not set via `configure()`. `contrastLevel` is the one field the freeze treats as a live preference: only an instance-authored level is written to the snapshot ([why](#clearing-it-exporting-it-base-links)).
 
 ---
 
@@ -1745,9 +1823,10 @@ palette.tokens({ modes: { dark: true, highContrast: true } });
 
 Resolution priority (highest first):
 
-1. A global [`contrastLevel`](#manual-contrast-level) — pins
-   `highContrast: false`, since a manual level leaves no separate high-contrast
-   tier to emit. `highContrast` is inert while it is set.
+1. A global [`contrastLevel`](#manual-contrast-level) of `100` — pins
+   `highContrast: false`, since the normal variants already *are* the
+   high-contrast ones and the tier would duplicate them. Any other level leaves
+   `highContrast` alone.
 2. Per-call `modes` option on `tokens` / `tasty` / `json`.
 3. `glaze.configure({ modes })` — global config.
 4. Built-in default: `{ dark: true, highContrast: false }`.
@@ -1817,7 +1896,7 @@ import {
 | Function                              | Description                                                              |
 | ------------------------------------- | ------------------------------------------------------------------------ |
 | `okhslToLinearSrgb(h, s, l)`          | OKHSL (h: 0–360, s/l: 0–1) → linear sRGB tuple.                          |
-| `okhslToSrgb(h, s, l)`                | OKHSL → gamma-encoded sRGB tuple (0–1 per channel).                      |
+| `okhslToSrgb(h, s, l)`                | OKHSL (h: 0–360, s/l: 0–1) → gamma-encoded sRGB tuple (0–1 per channel). |
 | `okhslToOklab([h, s, l])`             | OKHSL → OKLab `[L, a, b]`.                                               |
 | `oklabToOkhsl([L, a, b])`             | OKLab → OKHSL.                                                           |
 | `srgbToOkhsl([r, g, b])`              | Gamma sRGB (0–1) → OKHSL.                                                |
@@ -1830,15 +1909,44 @@ import {
 
 ### Format writers
 
+Every writer takes `h` on 0–360 and `s` / `l` / `t` on **0–1** — the scale every
+conversion above *returns*, and the scale `resolve()` stores in a
+`ResolvedColorVariant`. The percentages are an output detail: the writers scale
+by 100 themselves where the CSS syntax asks for one. (The one thing on a
+different scale is the pair of tone transfers below, `toTone` / `fromTone`,
+which speak the 0–100 tone axis the authoring API takes.)
+
 ```ts
-import { formatOkhsl, formatRgb, formatHsl, formatOklch } from '@tenphi/glaze';
+import {
+  formatOkhsl,
+  formatOkhst,
+  formatRgb,
+  formatHsl,
+  formatOklch,
+} from '@tenphi/glaze';
 
-formatOkhsl(280, 60, 95); // 'okhsl(280 60% 95%)'
-formatRgb(280, 60, 95); // 'rgb(244 240 250)'
-formatHsl(280, 60, 95); // 'hsl(280 60% 95%)'
-formatOklch(280, 60, 95); // 'oklch(0.95 ... 280)'
+formatOkhsl(280, 0.6, 0.95); // 'okhsl(280 60% 95%)'
+formatOkhst(280, 0.6, 0.95); // 'okhst(280 60% 95%)'
+formatRgb(280, 0.6, 0.95); // 'rgb(238.45 239.95 251.1)'
+formatHsl(280, 0.6, 0.95); // 'hsl(232.92 61.87% 95.99%)'
+formatOklch(280, 0.6, 0.95); // 'oklch(0.9571 0.015 280)'
 ```
 
+So a producer composes with a writer directly, with nothing to rescale in
+between:
+
+```ts
+const v = glaze.color('#7A4DBF').resolve().light;
+const { h, s, l } = variantToOkhsl(v);
+
+formatOkhst(v.h, v.s, v.t); // 'okhst(298.52 70.41% 45.02%)'
+formatOkhsl(h, s, l); // 'okhsl(298.52 70.41% 45.27%)'
+formatRgb(h, s, l); // 'rgb(122 77 191)'
+```
+
+A value above 1 can only be pre-2.0 percentage-scale input, so the writers
+`console.warn` about it once per writer rather than emit a wrong color quietly.
+
 To attach an alpha component, use `glaze.format(variant, format)` on a `ResolvedColorVariant` (which carries the `alpha` channel) instead of these raw writers.
 
 ### OKHST tone utilities
@@ -1858,12 +1966,12 @@ import {
 
 | Function                                    | Description                                                               |
 | ------------------------------------------- | ------------------------------------------------------------------------- |
-| `toTone(l, eps?)`                           | OKHSL lightness (0–1) → tone (0–100). Defaults to `REF_EPS`.              |
-| `fromTone(t, eps?)`                         | Tone (0–100) → OKHSL lightness (0–1). Inverse of `toTone`.                |
+| `toTone(l, eps?)`                           | OKHSL lightness (0–1) → tone (**0–100**, the authoring scale — divide by 100 for `formatOkhst`). Defaults to `REF_EPS`. |
+| `fromTone(t, eps?)`                         | Tone (**0–100**) → OKHSL lightness (0–1). Inverse of `toTone`.            |
 | `toneFromY(y, eps?)` / `yFromTone(t, eps?)` | Same transfer in luminance space (0–1).                                   |
 | `okhstToOkhsl({ h, s, t })`                 | OKHST → OKHSL (`{ h, s, l }`).                                            |
 | `okhslToOkhst({ h, s, l })`                 | OKHSL → OKHST (`{ h, s, t }`).                                            |
-| `variantToOkhsl(variant)`                   | `ResolvedColorVariant` (stores `t`) → `{ h, s, l, alpha }` for rendering. |
+| `variantToOkhsl(variant)`                   | `ResolvedColorVariant` (stores `t`) → `{ h, s, l }` for rendering (`alpha` stays on the variant). |
 | `REF_EPS`                                   | Reference epsilon (`0.05`) for the canonical tone axis.                   |
 
 `ResolvedColorVariant` stores `{ h, s, t, alpha }` (tone, not lightness). Use
@@ -1908,6 +2016,6 @@ Exported constants: `APCA_PRESETS`, `APCA_HC_ENHANCEMENT` (`15`, the Enhanced Le
 | `maxIterations`    | `18`                 | Max binary-search iterations per branch.                                                                                                                                                               |
 | `initialDirection` | higher-contrast side | Direction to search first (`'lighter'` or `'darker'`).                                                                                                                                                 |
 | `flip`             | `false`              | When `true`, try the opposite direction if the initial one doesn't meet the target. When `false`, only the initial direction is searched — unmet contrasts pin the result to that direction's extreme. |
-| `preferInitial`    | `false`              | With `flip` on and **both** directions meeting the target, keep `initialDirection` instead of taking whichever result lands nearer `preferredTone`. Makes the chosen side independent of the target — what [`contrastLevel`](#manual-contrast-level) uses to keep a color on one side of its base across the ramp. The flip fallback is unaffected. |
+| `preferInitial`    | `false`              | With `flip` on and **both** directions meeting the target, keep `initialDirection` instead of taking whichever result lands nearer `preferredTone`. Makes the chosen side independent of the target — what [`contrastLevel`](#manual-contrast-level) uses to keep a color on one side of its base across the ramp (on the normal passes only; the high-contrast ones never probe). The flip fallback is unaffected. |
 
 Result: `{ tone, contrast, met, branch: 'lighter' | 'darker' | 'preferred', flipped? }`. `flipped: true` indicates the initial direction failed and the opposite direction satisfied the target.

package/docs/glaze/methodology.md

@@ -642,24 +642,26 @@ In HC variants, Glaze bypasses the normal tone window and uses the full
 `[0, 100]` range. Edge tones can reach the edge; contrast floors have more room
 to solve.
 
-### A slider instead of a tier
+### A slider through the tier
 
 The two-tier model assumes contrast is a binary OS preference. When contrast is
 instead a setting *your users* control, set
-[`contrastLevel`](api.md#manual-contrast-level) to a number and the HC tier
-becomes a `0–100` ramp: level `0` is your normal palette, `100` is the HC
-palette you already authored, and everything between is resolved at that level.
+[`contrastLevel`](api.md#manual-contrast-level) to a number and your **normal**
+palette slides along a `0–100` ramp: level `0` is the palette you authored, `100`
+is the HC palette you authored, and everything between is resolved at that level.
 
 The authoring work is the same — the HC pairs above are what the slider ramps
-toward, so a palette tuned for high contrast needs no new fields. Two
-consequences worth planning for:
-
-- The separate HC tier stops being emitted, so wire the level itself into your
-  build or runtime rather than a `prefers-contrast: more` block. Existing
-  media-query wiring keeps working; it just receives the same values as the base
-  block.
-- `contrastLevel: 0` is a useful state in its own right: normal contrast with no
-  HC tier at all, for products that ship the slider but default it off.
+toward, so a palette tuned for high contrast needs no new fields. Two things
+worth planning for:
+
+- The slider and the tier compose. The HC tier keeps resolving at full contrast
+  regardless of the level, so wire the level into your build or runtime *and*
+  keep your `prefers-contrast: more` block: a user who has raised the slider and
+  asked their OS for more contrast still gets the escalation on top. The one
+  exception is level `100`, where the two coincide and the tier is dropped as a
+  duplicate.
+- `contrastLevel: 0` is the natural rest position for a slider you ship but
+  default off — it reproduces the `'auto'` output bit for bit.
 
 ## Checklist
 

package/docs/glaze/migration.md

@@ -12,6 +12,7 @@ If you're starting from scratch, see [methodology.md](methodology.md) first —
 - [Wiring exports into the app](#wiring-exports-into-the-app)
 - [Prefix map strategies](#prefix-map-strategies)
 - [Migrating an existing color system](#migrating-from-an-existing-color-system)
+- [Upgrading Glaze](#upgrading-glaze)
 - [Common pitfalls](#common-pitfalls)
 
 ## Choosing an export
@@ -296,6 +297,40 @@ Glaze gives you light/dark/HC for free, but only the light mode is matched again
 
 After migration, mark every default-only token (borders, shadows, disabled chip, code highlighting, etc.) `inherit: false`. Colored sibling themes only need the accent + tinted-surface chain — flagging the rest cuts the emitted token set per theme dramatically.
 
+## Upgrading Glaze
+
+### 2.0 — `format*` takes 0–1
+
+The `format*` writers (`formatOkhsl`, `formatOkhst`, `formatRgb`, `formatHsl`,
+`formatOklch`) used to take `s` / `l` / `t` on a 0–100 percentage scale while
+everything that *produces* those values — `resolve()`, `variantToOkhsl`,
+`srgbToOkhsl`, `oklabToOkhsl`, `okhslToSrgb` — returns them on 0–1. Composing
+the two, which is the obvious thing to do, was off by 100x and failed silently:
+`0.7` is a legal percentage, so you got a valid CSS string naming the wrong
+(near-black) color.
+
+The writers now take the 0–1 factors, so the whole library speaks one scale.
+Drop the `* 100`:
+
+```diff
+- formatOkhsl(v.h, v.s * 100, l * 100);
++ formatOkhsl(v.h, v.s, l);
+
+- formatOkhst(v.h, v.s * 100, v.t * 100);
++ formatOkhst(v.h, v.s, v.t);
+```
+
+Nothing else moves: `h` was always 0–360, `alpha` was always 0–1, and every
+export method (`css()` / `tokens()` / `json()` / `tasty()` / `dtcg()` /
+`tailwind()` / `glaze.format()`) emits the same colors — they were compensating
+internally. Dropping the redundant `×100 ÷100` round-trip shifts float noise by
+an ULP, which shows up nowhere except the (meaningless) hue term of a
+fully-desaturated `hsl()` string.
+
+A leftover `* 100` is not silent any more: a value above 1 cannot be a factor,
+so the writers `console.warn` once per writer and you get an obviously-broken
+`7040.68%` instead of a plausible wrong color.
+
 ## Common pitfalls
 
 | Symptom                                                                        | Cause                                                                                                                                   | Fix                                                                                                                                                                                                        |
@@ -307,6 +342,7 @@ After migration, mark every default-only token (borders, shadows, disabled chip,
 | A relative `tone` like `'+48'` lands on the _wrong_ (darker) side of its base. | Overshooting offsets now mirror to the other side of the base by default (`autoFlip` inherits `autoFlip`).                              | Set `autoFlip: false` on the color to clamp to the boundary instead, or use `tone: 'max'`/`'min'` to force the extreme.                                                                                    |
 | `palette.tokens()` emits unexpected unprefixed names.                          | A `primary` was set on the palette (or per-call) and is duplicating the theme's tokens without prefix.                                  | Pass `primary: false` to disable for that export, or rename `glaze.palette(themes, { primary })`.                                                                                                          |
 | `console.warn: token "foo" collides with theme "bar"`.                         | Two themes resolved to the same output key under your prefix config.                                                                    | Adjust the prefix map so each token is unique, or accept the first-write-wins behavior.                                                                                                                    |
+| `console.warn: formatOkhsl() got a value above 1`.                             | Pre-2.0 percentage-scale input to a `format*` writer (a leftover `* 100`).                                                              | Pass the 0–1 factors the converters return — see [2.0 — `format*` takes 0–1](#20--format-takes-01).                                                                                                        |
 | `console.warn: color "X" cannot meet contrast`.                                | The requested contrast target is physically unreachable for the color's hue/saturation against its base.                                | Lower the floor, change the base, or accept the closest passing variant. Use the `name` override on standalone colors to make the warning identifiable.                                                    |
 
 ## See also

package/docs/glaze/okhst.md

@@ -98,6 +98,10 @@ hi(f) = hi + (100 - hi) * f
 `[15, 95] → [0, 100]`. The render `eps` is not interpolated, and a `false` window
 is already the full range and therefore level-invariant.
 
+This continuous form applies to the normal variants only. High-contrast variants
+are already at the full range, so the level does not widen them further — the
+bypass above is what makes the high-contrast tier level-independent.
+
 ## Scheme adaptation
 
 Each regular color has an adaptation `mode`:

package/docs/tasty/ai-agents.md

@@ -70,6 +70,9 @@ The last row goes the other way — longhands over the shorthand — because `fl
 - ❌ `#f5f5f5`, `rgb(0 0 0)`, `oklch(…)`, `okhsl(…)`, `red` → ✅ `#surface` (add the token to the config if it doesn't exist).
 - ❌ `var(--gap)` → ✅ `$gap` · ❌ `$accent-color` → ✅ `#accent` · ❌ `transparent` → ✅ `#clear` · ❌ `currentColor` → ✅ `#current`.
 - A `$name` must be declared as a `'$name': value` key in the same styles object, or in the config.
+- Names are case-sensitive and start lowercase — `$myVar` → `--myVar`; a leading capital folds (`$Foo` → `--foo`). Prefer kebab-case.
+- A `$name` reference is untyped: it fills the first free slot in a shorthand (`border: '1bw $my-style'` → the line style). Write colors as `#name`; `$name-color` is a fallback for pointing at a raw CSS custom property that holds a color.
+- `preset` and `transition` take token *names*, not values, so a `$name` cannot stand in for one (it warns in dev and is ignored).
 
 ### Units