@cube-dev/ui-kit 0.149.1 → 0.150.0

package/docs/glaze/migration.md

@@ -1,25 +1,44 @@
 # Migration & Integration
 
-How to plug a Glaze palette into an existing app — exporting tokens in the right shape, mapping prefixes to the names your components already consume, and migrating off a legacy color system without breaking layout, dark-mode wiring, or muscle-memory tokens.
+How to move an existing CSS, design-token, or application color system to
+Glaze, then export the resulting palette in the shape your app and design tools
+consume.
 
-If you're starting from scratch, see [methodology.md](methodology.md) first — that's about *designing* the palette. This doc is about *consuming* it.
+If you're starting from scratch, see [methodology.md](methodology.md) first — that's about _designing_ the palette. This doc is about _consuming_ it.
+
+## Contents
+
+- [Choosing an export](#choosing-an-export)
+- [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)
+- [Common pitfalls](#common-pitfalls)
 
 ## Choosing an export
 
-Glaze emits the same resolved colors in four shapes. Pick one based on your renderer.
+Glaze has two layers of “export”:
+
+1. **Authoring snapshots** — `theme.export(override?)` / `token.export(override?)` / `palette.export(override?)`, restored with `glaze.themeFrom` / `colorFrom` / `paletteFrom`. These carry definitions, relations, and a config freeze taken at export time (`kind` + `version`). Live instances keep only a sparse local override; omitted global fields track `configure()` until export.
+2. **Resolved output** — the seven shapes below. These are color strings / design-token documents for apps and tools, **not** restorable as authoring config.
+
+Glaze emits the same resolved colors in seven shapes. Pick one based on your
+renderer or tooling.
 
-| Method | Output shape | Use it for |
-|---|---|---|
-| `palette.tasty(options?)` | `{ '#name': { '': value, '@dark': value, '@hc': value } }` | The [Tasty](https://tasty.style/docs) style system. Single object, state aliases keyed inside each token. |
-| `palette.tokens(options?)` | `{ light: { name: value }, dark: { name: value }, ... }` | Most CSS-in-JS systems. Per-variant flat maps, easy to feed into a `:root { ... }` selector via your framework's globals. |
-| `palette.css(options?)` | `{ light: '--name-color: rgb(...);', dark: '...', ... }` | Framework-free CSS / static stylesheets. Variant-grouped CSS custom property strings ready to wrap in `:root` and `prefers-color-scheme` queries. |
-| `palette.json(options?)` | `{ themeName: { name: { light, dark, ... } } }` | Tooling, JSON pipelines, design-token exporters (Style Dictionary, etc.). |
+| Method                           | Output shape                                                                                                       | Use it for                                                                                                                                                                        |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `palette.tasty(options?)`        | `{ '#name': { '': value, '@media(prefers-color-scheme: dark)': value, '@media(prefers-contrast: more)': value } }` | The [Tasty](https://tasty.style) style system. Single object, state aliases keyed inside each token.                                                                         |
+| `palette.tokens(options?)`       | `{ light: { name: value }, dark: { name: value }, ... }`                                                           | Most CSS-in-JS systems. Per-variant flat maps, easy to feed into a `:root { ... }` selector via your framework's globals.                                                         |
+| `palette.css(options?)`          | `{ light: '--name-color: rgb(...);', dark: '...', ... }`                                                           | Framework-free CSS / static stylesheets. Variant-grouped CSS custom property strings ready to wrap in `:root` and `prefers-color-scheme` queries.                                 |
+| `palette.json(options?)`         | `{ themeName: { name: { light, dark, ... } } }`                                                                    | Tooling, JSON pipelines.                                                                                                                                                          |
+| `palette.dtcg(options?)`         | `{ light: { name: { $type, $value } }, dark: { ... }, ... }`                                                       | W3C [DTCG 2025.10](https://www.designtokens.org/) `.tokens.json` — Figma, Tokens Studio, Style Dictionary, Terrazzo, Penpot. One document per scheme.                             |
+| `palette.dtcgResolver(options?)` | `{ version, sets, modifiers, resolutionOrder }`                                                                    | W3C DTCG **Resolver-Module** — a single document describing every scheme variant as `sets` + a `scheme` modifier with a context per variant. For resolver tools such as Dispersa. |
+| `palette.tailwind(options?)`     | `'@theme { --color-*: ... } .dark { ... } ...'`                                                                    | Tailwind CSS v4. A single ready-to-paste `@theme` block plus dark / high-contrast overrides.                                                                                      |
 
-All four accept `format` (`'okhsl' \| 'rgb' \| 'hsl' \| 'oklch'`). `tokens()`, `tasty()`, and `json()` also accept `modes` (`{ dark, highContrast }`). `css()` always returns all four strings (`light`, `dark`, `lightContrast`, `darkContrast`). See [api.md → Palette](api.md#palette) for full options.
+`tasty()`, `tokens()`, `json()`, `dtcg()`, `dtcgResolver()`, and `tailwind()` accept `modes` (`{ dark, highContrast }`). `css()` always returns all four strings (`light`, `dark`, `lightContrast`, `darkContrast`). CSS-string exports accept `format` and default to `'oklch'` (`tokens`/`json`/`css`/`tailwind`/`tasty`; `'rgb'` and `'hsl'` also available). `'okhsl'` and `'okhst'` are supported only on [Tasty](https://tasty.style)-shaped exports (`tasty()`, standalone `token()` / `.tasty()`). `dtcg()` and `dtcgResolver()` ignore `format` and use `colorSpace` instead (`'srgb'` default, `'oklch'` opt-in). See [api.md → Palette](api.md#palette) for full options.
 
 ## Wiring exports into the app
 
-### Tasty
+### [Tasty](https://tasty.style)
 
 Spread the result of `palette.tasty()` into a global style call:
 
@@ -28,7 +47,9 @@ import type { Styles } from '@tenphi/tasty';
 import { useGlobalStyles } from '@tenphi/tasty';
 import { tastyStatic } from '@tenphi/tasty/static';
 
-export const PALETTE_TOKENS = palette.tasty({ /* prefix map */ }) as Styles;
+export const PALETTE_TOKENS = palette.tasty({
+  /* prefix map */
+}) as Styles;
 
 // In your root component:
 useGlobalStyles('body', PALETTE_TOKENS);
@@ -37,11 +58,14 @@ useGlobalStyles('body', PALETTE_TOKENS);
 tastyStatic('body', PALETTE_TOKENS);
 ```
 
-For the `@dark` / `@hc` state aliases to do anything, your app needs to register what those states *mean*:
+By default the dark / high-contrast variants are keyed by media-query states — `'@media(prefers-color-scheme: dark)'` and `'@media(prefers-contrast: more)'` — so the tokens react to the OS preference out of the box, with no extra [Tasty](https://tasty.style) setup.
+
+If you'd rather drive the schemes from custom aliases (e.g. a manual toggle that also falls back to the OS preference), set your own [`glaze.configure({ states })`](api.md#configuration) and register what those states _mean_:
 
 ```ts
 import { setGlobalPredefinedStates } from '@tenphi/tasty';
 
+// glaze.configure({ states: { dark: '@dark', highContrast: '@hc' } });
 setGlobalPredefinedStates({
   '@dark':
     '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
@@ -52,7 +76,7 @@ setGlobalPredefinedStates({
 
 The state names here must match the `states` you set in [`glaze.configure({ states })`](api.md#configuration).
 
-You can also register the tokens as a Tasty recipe instead of spreading them globally:
+You can also register the tokens as a [Tasty](https://tasty.style) recipe instead of spreading them globally:
 
 ```ts
 import { configure, tasty } from '@tenphi/tasty';
@@ -81,27 +105,65 @@ const stylesheet = `
 Each property name is `--<prefix><name>-color` by default. Override the suffix:
 
 ```ts
-palette.css({ suffix: '' });           // → '--surface: rgb(...);'
-palette.css({ format: 'oklch' });      // → '--surface-color: oklch(...);'
+palette.css({ suffix: '' }); // → '--surface: rgb(...);'
+palette.css({ format: 'oklch' }); // → '--surface-color: oklch(...);'
 ```
 
 ### Framework-agnostic JSON
 
 ```ts
 const data = palette.json();
-// → { primary: { surface: { light: 'okhsl(...)', dark: 'okhsl(...)' } }, ... }
+// → { primary: { surface: { light: 'oklch(...)', dark: 'oklch(...)' } }, ... }
 ```
 
 Feed into your tooling pipeline. Each color is grouped by theme name, then by token name, then by variant — no prefix logic to undo.
 
+### W3C DTCG (`.tokens.json`)
+
+```ts
+import { writeFileSync } from 'node:fs';
+const dtcg = palette.dtcg();
+
+writeFileSync('tokens.light.tokens.json', JSON.stringify(dtcg.light, null, 2));
+if (dtcg.dark) {
+  writeFileSync('tokens.dark.tokens.json', JSON.stringify(dtcg.dark, null, 2));
+}
+```
+
+Each document is a spec-conformant token tree. One file per scheme is the most tool-compatible convention — Style Dictionary treats them as themes, Tokens Studio as sets, and Figma as variable modes. Use `colorSpace: 'oklch'` for wide-gamut, Glaze-native values (no `hex`); the default `'srgb'` emits components plus a `hex` hint that every reader understands. Feed the files straight into Style Dictionary v4+, Tokens Studio, or any DTCG-compatible tool — no Glaze-specific transform needed.
+
+### W3C DTCG Resolver-Module (single document)
+
+When you want **one file** describing every scheme variant — for a resolver tool such as [Dispersa](https://github.com/dispersa-core/dispersa) — use `dtcgResolver()` instead of `dtcg()`:
+
+```ts
+import { writeFileSync } from 'node:fs';
+const resolver = palette.dtcgResolver({ modes: { highContrast: true } });
+
+writeFileSync('resolver.json', JSON.stringify(resolver, null, 2));
+```
+
+The document places the light tokens in `sets.base.sources[0]` (the default context) and emits a single `scheme` modifier with a context per variant (`light` / `dark` / `lightContrast` / `darkContrast`). Each non-default context holds that variant's exact resolved tokens — Glaze resolves `darkContrast` independently, so the four-context shape keeps every value correct (two independent modifiers would compose additively and produce wrong dark + high-contrast values). Rename the set, modifier, or contexts via `setName` / `modifierName` / `contextNames` if your resolver expects different labels. Prefer `dtcg()` when you need maximum per-file tool compatibility; prefer `dtcgResolver()` when a resolver tool consumes the document for you.
+
+### Tailwind CSS v4
+
+```ts
+const css = palette.tailwind();
+// Write to your CSS entry, or paste into a `@import "tailwindcss"` stylesheet:
+// @theme { --color-primary-surface: oklch(...); ... }
+// .dark { --color-primary-surface: oklch(...); ... }
+```
+
+The `--color-*` namespace makes every color available as `bg-*` / `text-*` / `border-*`. Drive dark mode from the OS preference instead of a class with `darkSelector: '@media (prefers-color-scheme: dark)'` (it nests `:root` automatically). High-contrast overrides land under `.high-contrast` and `.dark.high-contrast` by default; both are omitted unless `modes.highContrast` is enabled.
+
 ## Prefix map strategies
 
-`palette.tokens()` / `tasty()` / `css()` accept a `prefix` option:
+`palette.tokens()` / `tasty()` / `css()` / `dtcg()` / `tailwind()` accept a `prefix` option:
 
-| Value | Result |
-|---|---|
-| `true` (default) | Every theme prefixes its tokens with `<themeName>-`. |
-| `false` | No prefixes. Colliding keys produce a `console.warn`; first-write wins. |
+| Value                    | Result                                                                     |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `true` (default)         | Every theme prefixes its tokens with `<themeName>-`.                       |
+| `false`                  | No prefixes. Colliding keys produce a `console.warn`; first-write wins.    |
 | `Record<string, string>` | Per-theme prefix overrides. Themes not listed fall back to `<themeName>-`. |
 
 The most common production pattern: **default theme unprefixed, every other theme prefixed with its name**:
@@ -112,15 +174,20 @@ palette.tasty({
     default: '',
     primary: 'primary-',
     success: 'success-',
-    danger:  'danger-',
+    danger: 'danger-',
     warning: 'warning-',
-    note:    'note-',
+    note: 'note-',
   },
 });
 ```
 
 This makes neutral tokens consume as `#surface`, `#border`, `#disabled-surface` (no theme namespace) while status colors live under `#danger-surface`, `#success-accent-text`, etc.
 
+This explicit map is usually clearer for a neutral `default` theme. The
+separate `primary` palette option below solves a different namespace problem:
+it duplicates one named theme without a prefix while retaining that theme's
+prefixed tokens.
+
 ### Alias themes for legacy names
 
 Two aliases for the same theme instance produce identical token values under different prefixes — useful when you want to support a legacy token name without duplicating definitions:
@@ -129,7 +196,7 @@ Two aliases for the same theme instance produce identical token values under dif
 const palette = glaze.palette({
   default: defaultTheme,
   primary: primaryTheme,
-  purple:  primaryTheme,    // legacy alias — same theme, different prefix
+  purple: primaryTheme, // legacy alias — same theme, different prefix
   // ...
 });
 
@@ -137,7 +204,7 @@ palette.tasty({
   prefix: {
     default: '',
     primary: 'primary-',
-    purple:  'purple-',     // emits #purple-surface alongside #primary-surface
+    purple: 'purple-', // emits #purple-surface alongside #primary-surface
   },
 });
 ```
@@ -146,13 +213,10 @@ Both `#primary-surface` and `#purple-surface` resolve to the exact same color. D
 
 ### `primary` (the unprefixed alias)
 
-`glaze.palette(themes, { primary })` and the per-export `primary` option duplicate one theme's tokens *without* prefix on top of any prefix map. Equivalent to listing that theme twice with different prefixes; useful when the "primary" theme is conceptually distinct from `default` and you want both sets of unprefixed tokens.
+`glaze.palette(themes, { primary })` and the per-export `primary` option duplicate one theme's tokens _without_ prefix on top of any prefix map. Equivalent to listing that theme twice with different prefixes; useful when the "primary" theme is conceptually distinct from `default` and you want both sets of unprefixed tokens.
 
 ```ts
-const palette = glaze.palette(
-  { brand, accent },
-  { primary: 'brand' },
-);
+const palette = glaze.palette({ brand, accent }, { primary: 'brand' });
 palette.tokens();
 // → { light: { 'brand-surface': '...', 'surface': '...', 'accent-surface': '...' } }
 ```
@@ -176,16 +240,19 @@ Walk your current color system and bucket every token into one of these categori
 - **Shadows / overlays** — elevation, scrims.
 - **One-off colors** — syntax highlighting, charts, illustrations.
 
-Each bucket maps cleanly to one of the patterns in [methodology.md](methodology.md). The bucket determines the *shape* of the Glaze definition (root vs dependent, `mode: 'auto'` vs `'fixed'`, contrast-floor vs absolute lightness), not the value.
+Each bucket maps cleanly to one of the patterns in [methodology.md](methodology.md). The bucket determines the _shape_ of the Glaze definition (root vs dependent, `mode: 'auto'` vs `'fixed'`, contrast-floor vs absolute tone), not the value.
 
 ### 2. Reproduce the existing values
 
-Pick a Glaze definition shape that lands the new color *close to* the legacy hex in light mode. The methodology doc explains the shape per bucket; the API doc covers the levers (`lightness`, `saturation`, `contrast`, `mode`, `hue`).
+Pick a Glaze definition shape that lands the new color _close to_ the legacy hex in light mode. The methodology doc explains the shape per bucket; the API doc covers the levers (`tone`, `saturation`, `contrast`, `mode`, `hue`).
 
 Two tactics that make matching easier:
 
-- **Anchor strong text at the edge** instead of solving for `'AAA'`. The contrast solver stops at the floor (cr=7), which usually leaves text noticeably softer than a legacy hex like `#1a1a1a`. An absolute `lightness: 2` (or wherever the legacy token sits in OKHSL) preserves the look.
-- **Use numeric `contrast` ratios** for soft / accent / disabled tokens. Presets give you the WCAG floor and nothing more — for matching a designed palette you usually want a specific perceived weight, not the floor.
+- **Anchor strong text at the edge** instead of solving for `'AAA'`. The contrast solver stops at the floor (cr=7), which usually leaves text noticeably softer than a legacy hex like `#1a1a1a`. An absolute `tone: 2` (or wherever the legacy token sits) preserves the look.
+- **Match the metric the old system actually used.** Numeric WCAG ratios are
+  useful when reproducing a measured legacy ratio. For new content roles,
+  prefer the APCA presets from the methodology. For low-stakes spacing, use a
+  tone delta instead of inventing a contrast target.
 
 ### 3. Keep the old token names
 
@@ -196,9 +263,19 @@ Use a custom `prefix` map (and theme aliases if needed) so the names your compon
 // New: define them in Glaze, map the prefix so they emit unchanged.
 
 defaultTheme.colors({
-  dark:      { base: 'surface', lightness: 2,  saturation: 0.475 },
-  'dark-02': { base: 'surface', lightness: '-1', saturation: 0.375, contrast: [9, 11]   },
-  'dark-03': { base: 'surface', lightness: '-1', saturation: 0.24,  contrast: [4.5, 5.5] },
+  dark: { base: 'surface', tone: 2, saturation: 0.475 },
+  'dark-02': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 0.375,
+    contrast: [9, 11],
+  },
+  'dark-03': {
+    base: 'surface',
+    tone: '-1',
+    saturation: 0.24,
+    contrast: [4.5, 5.5],
+  },
 });
 
 palette.tasty({ prefix: { default: '' } });
@@ -211,8 +288,8 @@ Once consumers are off the legacy names, rename the Glaze tokens to match your c
 
 Glaze gives you light/dark/HC for free, but only the light mode is matched against the legacy palette. Before promoting the migration:
 
-- Spot-check every surface, text, accent, and disabled pair in dark mode. The Möbius dark inversion plus per-color `mode` choices may produce results that *look right* in light but feel off in dark (typical fix: switch a brand color to `mode: 'fixed'`, or anchor a foreground to `surface` instead of the brand fill — see [methodology.md](methodology.md)).
-- If the legacy system had no high-contrast mode, audit the HC variants Glaze emits. Anywhere the resolved cr is too low or the color blows out, add an HC pair (`lightness: ['-7', '-20']`, `contrast: [4.5, 7]`, etc.).
+- Spot-check every surface, text, accent, and disabled pair in dark mode. The tone inversion plus per-color `mode` choices may produce results that _look right_ in light but feel off in dark (typical fix: switch a brand color to `mode: 'fixed'`, or anchor a foreground to `surface` instead of the brand fill — see [methodology.md](methodology.md)).
+- If the legacy system had no high-contrast mode, audit the HC variants Glaze emits. Anywhere the resolved cr is too low or the color blows out, add an HC pair (`tone: ['-7', '-20']`, `contrast: [4.5, 7]`, etc.).
 - Run real screens, not just the token grid. The interaction of multiple Glaze tokens against each other (text on chip, hover bg vs. fill, disabled label on disabled chip) is where mismatches show up.
 
 ### 5. Trim what `extend()` doesn't need
@@ -221,15 +298,16 @@ After migration, mark every default-only token (borders, shadows, disabled chip,
 
 ## Common pitfalls
 
-| Symptom | Cause | Fix |
-|---|---|---|
-| Disabled state stops looking disabled in dark mode. | Alpha-tinted overlay on `surface-text` (which inverts), giving asymmetric perceived contrast. | Replace with a `mode: 'auto'` color anchored to `surface` with a numeric `contrast` (see [methodology.md → Disabled chip](methodology.md#disabled-chip-contrast-driven-for-scheme-symmetry)). |
-| Brand color flips to its complement in dark mode. | Default `mode: 'auto'` runs the Möbius inversion. | Set `mode: 'fixed'` so the lightness is mapped (not inverted). |
-| Brand text washes out against the dark surface. | Foreground was anchored to `accent-surface` (the brand fill), so contrast was only enforced against that fill — not the actual surface. | Anchor `accent-text` etc. to `surface` with `mode: 'auto'`. |
-| Tokens look right in light, broken in HC. | The HC pass bypasses the lightness window — solver runs over the full `[0, 100]` range. | Add explicit `[normal, hc]` pairs to `lightness` / `contrast` for the affected tokens. |
-| `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: 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. |
+| Symptom                                                                        | Cause                                                                                                                                   | Fix                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Disabled state stops looking disabled in dark mode.                            | Alpha-tinted overlay on `surface-text` (which inverts), giving asymmetric perceived contrast.                                           | Replace it with an adaptive color anchored to `surface`; use a tone delta for visual spacing or a contrast floor when required. See [Chips and disabled states](methodology.md#chips-and-disabled-states). |
+| Brand color flips to its complement in dark mode.                              | Default `mode: 'auto'` inverts the tone.                                                                                                | Set `mode: 'fixed'` so the tone is remapped (not inverted).                                                                                                                                                |
+| Brand text washes out against the dark surface.                                | Foreground was anchored to `accent-surface` (the brand fill), so contrast was only enforced against that fill — not the actual surface. | Anchor `accent-text` etc. to `surface` with `mode: 'auto'`.                                                                                                                                                |
+| Tokens look right in light, broken in HC.                                      | The HC pass bypasses the tone window — solver runs over the full `[0, 100]` range.                                                      | Add explicit `[normal, hc]` pairs to `tone` / `contrast` for the affected tokens.                                                                                                                          |
+| 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: 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

@@ -0,0 +1,190 @@
+# OKHST in Glaze
+
+Glaze uses [OKHST](https://github.com/tenphi/okhst), an OKHSL-derived color
+space with a tone axis for stable palette authoring. This page explains how
+Glaze applies the model. The standalone repository is the canonical
+specification for the transfer functions, derivation, and color-model
+invariants.
+
+For practical palette design, continue to [methodology.md](methodology.md). For
+every related option and utility, see [api.md](api.md).
+
+## What tone means
+
+OKHST keeps OKHSL hue and saturation and replaces authored lightness with
+**tone**:
+
+| Space | Coordinates | Third coordinate     |
+| ----- | ----------- | -------------------- |
+| OKHSL | `h, s, l`   | Perceptual lightness |
+| OKHST | `h, s, t`   | Contrast-shaped tone |
+
+Tone uses a `0–100` authoring scale. Its primary invariant is:
+
+> The same tone maps to the same OKHSL lightness for every hue and saturation.
+
+For neutral colors, equal tone differences produce equal WCAG contrast ratios.
+For chromatic colors, they remain a useful progression but are not exact:
+hue, saturation, and gamut mapping can change the final sRGB luminance.
+
+This distinction informs two authoring rules:
+
+- Use **tone deltas** for visual spacing within ramps and related UI colors.
+- Use `contrast` when a rendered color must meet a measured WCAG or APCA floor.
+
+## Tone vocabulary
+
+### Absolute tone
+
+A numeric `tone` places a color independently on the `0–100` authoring scale:
+
+```ts
+surface: {
+  tone: 97;
+}
+```
+
+`'max'` and `'min'` select the corresponding end of the active scheme. With a
+`base`, they instead preserve their distance from that base across schemes —
+see [Scheme adaptation](#scheme-adaptation).
+
+### Tone delta
+
+A **tone delta** is the signed difference between a dependent color and its
+base. It is authored as a string:
+
+```ts
+border: { base: 'surface', tone: '-8' }
+```
+
+Here, `-8` is the tone delta. The base is resolved separately for every scheme,
+then the delta is applied to that resolved base. This keeps related colors
+visually ordered across light, dark, and high-contrast variants.
+
+### Tone window
+
+A **tone window** is the scheme-specific render range configured by
+`lightTone` or `darkTone`:
+
+```ts
+glaze.configure({
+  lightTone: [10, 100],
+  darkTone: [15, 95],
+});
+```
+
+In Glaze, `lo` and `hi` are OKHSL-lightness boundaries. Authored tone is
+positioned within the corresponding tone interval, then converted back to
+OKHSL lightness for rendering. The object form adds an advanced render
+curvature:
+
+```ts
+lightTone: { lo: 10, hi: 100, eps: 0.05 }
+```
+
+Pass `false` to use the full range. High-contrast variants always bypass the
+ordinary boundaries and use the full range.
+
+## Scheme adaptation
+
+Each regular color has an adaptation `mode`:
+
+| Mode       | Light scheme                   | Dark scheme                                                          |
+| ---------- | ------------------------------ | -------------------------------------------------------------------- |
+| `'auto'`   | Map into the light tone window | Apply dark tone inversion (`100 - t`), then map into the dark window |
+| `'fixed'`  | Map into the light tone window | Map into the dark window without inversion                           |
+| `'static'` | Keep the authored tone         | Keep the authored tone                                               |
+
+Use `auto` for surfaces and foregrounds that should exchange light/dark
+positions. Use `fixed` for brand fills and inverse surfaces that should stay on
+the same side of the scale. Reserve `static` for colors that must not adapt.
+
+**Dark tone inversion** is different from `autoFlip`. Inversion is normal
+scheme adaptation controlled by `mode`. `autoFlip` handles a different local
+problem: it may reverse an overshooting tone delta or let the contrast solver
+try the opposite side of a base.
+
+The regular pipeline is:
+
+```text
+authored tone
+  -> choose the color's adaptation mode
+  -> invert for dark + auto
+  -> map through the active tone window
+  -> store canonical tone
+  -> convert to OKHSL at the rendering edge
+```
+
+Dark schemes also apply `darkDesaturation` unless the color is `static`.
+
+**Hue and saturation are authoring inputs, not part of the tone transfer.** The
+tone axis is the only channel OKHST adapts across schemes; `h` and `s` pass
+through verbatim, with `darkDesaturation` as the one automatic adjustment.
+A theme (or a single color) can seed a different hue and saturation for the
+dark schemes via `darkHue` / `darkSaturation` — see
+[api.md](api.md#dark-seed-darkhue--darksaturation). Those pick the `h` and `s`
+that enter the pipeline above; they never change how tone is transferred.
+Authoring a dark saturation replaces the `darkDesaturation` step rather than
+stacking with it, and `static` colors ignore both.
+
+**Extremes with a base** take a different dark path. Because the light and dark
+windows are asymmetric, running an extreme through the dark window compresses
+the span between it and its base, which lowers contrast. For a color with both
+`base` and `tone: 'max'` / `'min'`, Glaze measures the tone shift the light
+scheme produced between the two, then replays it against the base's resolved
+dark tone (mirrored under `auto`, same-signed under `fixed`). Only `[0, 100]`
+clamping applies, so such a color may render past the `darkTone` boundary.
+
+## Reference and render epsilon
+
+`REF_EPS = 0.05` defines Glaze's canonical tone scale. It is used for OKHST
+input, stored resolved tone, tone deltas, and contrast search.
+
+An object tone window may supply another `eps` as a scheme-specific rendering
+control. Glaze still converts the result back to the reference scale so tone
+deltas and contrast calculations remain comparable between schemes. Most
+palettes should use the default.
+
+## Contrast verification
+
+Tone provides an efficient starting point for contrast solving, but Glaze does
+not assume a chromatic tone has the neutral color's luminance. For a color with
+`base` and `contrast`, Glaze:
+
+1. resolves both colors for the active scheme;
+2. measures the requested WCAG ratio or APCA Lc;
+3. searches tone when the requested position misses the floor; and
+4. warns when the target is physically unreachable or rendered chroma drifts
+   below the expected result.
+
+`contrast` is therefore a floor, not a replacement for tone relationships.
+Detailed presets, HC promotion, polarity, and role inference are documented
+under [`contrast`](api.md#contrast-floor) and [roles](api.md#roles).
+
+## Input and output
+
+Glaze accepts OKHST through:
+
+```ts
+glaze.color('okhst(152 95% 70%)');
+glaze.color({ h: 152, s: 0.95, t: 0.7 });
+glaze.color({ hue: 152, saturation: 95, tone: 70 });
+```
+
+There is no native CSS `okhst()` function. Native exports use `oklch`, `rgb`,
+or `hsl`. [Tasty](https://tasty.style) integrations may request `format: 'okhst'` because it can
+consume Glaze's custom serialization:
+
+```ts
+theme.tasty({ format: 'okhst' });
+```
+
+## Bringing existing colors into Glaze
+
+When moving raw CSS colors or design tokens into Glaze, use `fromHex()`,
+`fromRgb()`, or `glaze.color()` to preserve the source color while you establish
+theme seeds and semantic relationships. Then replace one-off values with roots,
+tone deltas, and contrast floors as appropriate.
+
+See [migration.md](migration.md#migrating-from-an-existing-color-system) for
+the implementation workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.149.1",
+  "version": "0.150.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -48,7 +48,7 @@
     "@react-types/shared": "^3.32.1",
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
-    "@tenphi/glaze": "0.13.0",
+    "@tenphi/glaze": "1.2.0",
     "@tenphi/tasty": "2.11.0",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",