@tenphi/glaze 0.15.0 → 0.16.0

package/docs/api.md

@@ -115,14 +115,14 @@ Flat token map grouped by scheme variant.
 
 ```ts
 theme.tokens()
-// → { light: { surface: 'okhsl(...)' }, dark: { surface: 'okhsl(...)' } }
+// → { light: { surface: 'oklch(...)' }, dark: { surface: 'oklch(...)' } }
 ```
 
 `GlazeJsonOptions`:
 
 | Option | Default | Description |
 |---|---|---|
-| `format` | `'okhsl'` | Output color format. One of `'okhsl' \| 'rgb' \| 'hsl' \| 'oklch'`. |
+| `format` | `'oklch'` | Output color format. One of `'rgb' \| 'hsl' \| 'oklch'`. `'okhsl'` and `'okhst'` throw — use `tasty()` for those. |
 | `modes` | `{ dark: true, highContrast: false }` (or global config) | Which scheme variants to include. |
 
 ### `theme.tasty(options?)`
@@ -141,10 +141,12 @@ theme.tasty()
 
 | Option | Default | Description |
 |---|---|---|
-| `format` | `'okhsl'` | Output color format. |
+| `format` | `'okhsl'` | Output color format. `'okhsl'` and `'okhst'` are supported here (Tasty-only spaces). |
 | `modes` | global config | Which scheme variants to include. |
 | `states.dark` | `'@dark'` (or global config) | State alias for dark mode tokens. |
 | `states.highContrast` | `'@high-contrast'` (or global config) | State alias for high-contrast tokens. |
+| `splitHue` | `false` | Emit hue as a separate custom property (`#name-hue` token + `var()` in `oklch` values). Requires `format: 'oklch'` and every color to be pastel. |
+| `name` | `'theme'` | Base name for the theme-level hue var (`#theme-hue` / `--theme-hue`). Palette export auto-derives this from the theme name. |
 | `prefix` | (palette only) | See [Palette](#palette). |
 
 When both `dark` and `highContrast` modes are enabled, dark high-contrast variants are emitted under the combined key `<dark> & <highContrast>` (e.g. `'@dark & @high-contrast'`).
@@ -156,8 +158,8 @@ Per-color JSON map.
 ```ts
 theme.json()
 // → {
-//   surface: { light: 'okhsl(...)', dark: 'okhsl(...)' },
-//   text:    { light: 'okhsl(...)', dark: 'okhsl(...)' },
+//   surface: { light: 'oklch(...)', dark: 'oklch(...)' },
+//   text:    { light: 'oklch(...)', dark: 'oklch(...)' },
 // }
 ```
 
@@ -181,11 +183,137 @@ theme.css();
 
 | Option | Default | Description |
 |---|---|---|
-| `format` | `'rgb'` | Output color format. |
+| `format` | `'rgb'` | Output color format. `'okhsl'` and `'okhst'` throw — use `tasty()` for those. |
 | `suffix` | `'-color'` | Suffix appended to each CSS property name. Pass `''` for bare property names. |
+| `splitHue` | `false` | Emit hue as a separate `--*-hue` custom property referenced via `var()` in `oklch` color values. Requires `format: 'oklch'` and every color to be pastel. Shadow/mix colors stay inline (blended hue; they do not follow `--hue` rotation). |
+| `name` | `'theme'` | Base name for the theme-level hue var (`--theme-hue`). Palette export auto-derives this from the theme name. |
 
 `GlazeCssResult` always contains all four keys (`light`, `dark`, `lightContrast`, `darkContrast`); empty if no colors are defined for that variant.
 
+### `theme.dtcg(options?)`
+
+W3C [Design Tokens Format Module (2025.10)](https://www.designtokens.org/) documents — the vendor-neutral JSON format consumed by Figma, Tokens Studio, Style Dictionary v4+, Terrazzo, Penpot, and every DTCG-compatible tool. Returns one spec-conformant token tree per scheme variant.
+
+```ts
+theme.dtcg()
+// → {
+//   light: {
+//     surface: {
+//       $type: 'color',
+//       $value: { colorSpace: 'srgb', components: [0.96, 0.94, 0.98], hex: '#f5f0fa' },
+//     },
+//   },
+//   dark: {
+//     surface: {
+//       $type: 'color',
+//       $value: { colorSpace: 'srgb', components: [0.16, 0.14, 0.2], hex: '#292333' },
+//     },
+//   },
+// }
+```
+
+Write each document to its own `.tokens.json` file — one file per scheme is the most tool-compatible convention (one per Style Dictionary theme / Tokens Studio set / Figma variable mode).
+
+`GlazeDtcgOptions`:
+
+| Option | Default | Description |
+|---|---|---|
+| `colorSpace` | `'srgb'` | Color space for `$value`. `'srgb'` emits gamma sRGB `components` (0–1) plus a `hex` hint — universally understood. `'oklch'` emits `[L, C, H]` components with no hex — Glaze-native, wide-gamut. |
+| `modes` | global config | Which scheme variants to include. `light` is always present. |
+
+`alpha` is included on `$value` only when the color's opacity is below 1. `$type` is always `'color'`.
+
+### `theme.dtcgResolver(options?)`
+
+A single W3C [DTCG Resolver-Module](https://www.designtokens.org/) document describing **every scheme variant in one file** — an alternative to `dtcg()`'s per-scheme files for tools that resolve sets + modifiers (e.g. Dispersa). The light document becomes `sets.base.sources[0]` (the default context); each other variant becomes a context override on a single `scheme` modifier.
+
+```ts
+theme.dtcgResolver({ modes: { highContrast: true } })
+// → {
+//   version: '2025.10',
+//   sets: {
+//     base: {
+//       sources: [
+//         {
+//           surface: {
+//             $type: 'color',
+//             $value: { colorSpace: 'srgb', components: [0.96, 0.94, 0.98], hex: '#f5f0fa' },
+//           },
+//         },
+//       ],
+//     },
+//   },
+//   modifiers: {
+//     scheme: {
+//       default: 'light',
+//       contexts: {
+//         light: [],
+//         dark: [
+//           {
+//             surface: {
+//               $type: 'color',
+//               $value: { colorSpace: 'srgb', components: [0.16, 0.14, 0.2], hex: '#292333' },
+//             },
+//           },
+//         ],
+//         lightContrast: [ /* … */ ],
+//         darkContrast: [ /* … */ ],
+//       },
+//     },
+//   },
+//   resolutionOrder: [
+//     { $ref: '#/sets/base' },
+//     { $ref: '#/modifiers/scheme' },
+//   ],
+// }
+```
+
+**Why one modifier with four contexts.** Glaze resolves `darkContrast` independently — it is not `dark` + `lightContrast` layered. The resolver model composes modifiers additively (last in `resolutionOrder` wins on conflict), so two independent modifiers (`scheme` × `contrast`) would produce wrong values for the dark + high-contrast permutation. One `scheme` modifier with a context per variant keeps every resolved value exact. Choose `dtcgResolver()` when you want single-file theming and feed it to a resolver tool; choose `dtcg()` for maximum per-file tool compatibility.
+
+`GlazeDtcgResolverOptions` (extends `GlazeDtcgOptions`, so `modes` and `colorSpace` pass through):
+
+| Option | Default | Description |
+|---|---|---|
+| `colorSpace` | `'srgb'` | Same as `dtcg()` — flows through to every source and context. |
+| `modes` | global config | Which scheme variants to emit as contexts. `light` is always present (the default); absent variants are omitted. |
+| `setName` | `'base'` | Name of the single set holding the default (light) token tree. |
+| `modifierName` | `'scheme'` | Name of the modifier describing the scheme axis. |
+| `contextNames` | identity | Override the four context names (`light` / `dark` / `lightContrast` / `darkContrast`) — e.g. `{ dark: 'night' }`. |
+| `version` | `'2025.10'` | Resolver document version. |
+
+### `theme.tailwind(options?)`
+
+A Tailwind CSS v4 `@theme` block (light baseline) plus dark / high-contrast overrides under configurable selectors. Returns a single ready-to-paste CSS string. The `--color-*` namespace auto-generates `bg-*` / `text-*` / `border-*` utilities.
+
+```css
+@theme {
+  --color-surface: oklch(0.96 0.01 280);
+  --color-text: oklch(0.3 0.05 280);
+}
+.dark {
+  --color-surface: oklch(0.16 0.01 280);
+  --color-text: oklch(0.85 0.05 280);
+}
+.high-contrast {
+  --color-surface: oklch(0.98 0.01 280);
+  --color-text: oklch(0.1 0.05 280);
+}
+.dark.high-contrast {
+  --color-surface: oklch(0.05 0.01 280);
+  --color-text: oklch(0.95 0.05 280);
+}
+```
+
+`GlazeTailwindOptions`:
+
+| Option | Default | Description |
+|---|---|---|
+| `format` | `'oklch'` | Output color format for the values. |
+| `namespace` | `'color-'` | CSS custom property namespace, forming `--<namespace><name>` (e.g. `--color-surface`). Named `namespace` to avoid clashing with the palette theme-prefix option. |
+| `darkSelector` | `'.dark'` | Selector wrapping the dark overrides. Pass an at-rule like `'@media (prefers-color-scheme: dark)'` to drive dark mode from the OS preference (it nests `:root` automatically). |
+| `highContrastSelector` | `'.high-contrast'` | Selector wrapping the light high-contrast overrides. The combined dark + high-contrast block uses `${darkSelector}${highContrastSelector}` (e.g. `.dark.high-contrast`). |
+| `modes` | global config | Which scheme variants to include. The `@theme` block (light) is always emitted when colors exist. |
+
 ### `theme.export()`
 
 ```ts
@@ -219,6 +347,8 @@ type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 | `mode` | `'auto' \| 'fixed' \| 'static'` | Adaptation mode. Default: `'auto'`. See [Adaptation modes](#adaptation-modes). |
 | `flip` | `boolean` | Flip out-of-bounds results (relative `tone` overshoot / unmet `contrast`) to the opposite side instead of clamping. Default: the global `autoFlip` (`true`). See [`flip`](#flip). |
 | `opacity` | `number` | Fixed alpha 0–1. Output includes alpha in the CSS value. Combining with `contrast` is not recommended (a `console.warn` is emitted). |
+| `pastel` | `boolean` | Per-color override for the hue-independent "safe" chroma limit used in OKHSL↔sRGB conversions (luminance, contrast solving, output formatting). Falls through to the global / per-theme `pastel` config when omitted. Default: unset. See [Per-color `pastel`](#per-color-pastel). |
+| `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. |
 
 #### Tone values
@@ -276,8 +406,15 @@ contrast: { wcag: 6 }          // WCAG 6
 contrast: { wcag: [4.5, 7] }   // WCAG 4.5 normal / 7 high-contrast
 contrast: { apca: 60 }         // APCA Lc 60
 contrast: { apca: [45, 60] }   // APCA Lc 45 normal / 60 high-contrast
+contrast: { apca: 'content' }  // APCA preset -> Lc 60
+contrast: { apca: ['content', 'body'] } // Lc 60 normal / 75 high-contrast
 ```
 
+APCA preset keywords (Bronze Simple Mode conformance levels, role-independent):
+`'preferred'` (Lc 90), `'body'` (75), `'content'` (60, ~AA), `'large'` (45, ~3:1),
+`'non-text'` (30), `'min'` (15, point of invisibility). See
+[`docs/okhst.md`](okhst.md) §APCA.
+
 The floor is applied independently per scheme — if the `tone` already satisfies it the tone is kept, otherwise the solver searches in tone (contrast-uniform → a closed-form WCAG seed and fast convergence) until the target is met.
 
 By default, the solver crosses to the opposite side of the base color when the requested tone direction cannot satisfy the floor. This is controlled per-color by [`flip`](#flip) (which defaults to the global `autoFlip`). Set `glaze.configure({ autoFlip: false })` — or `flip: false` on a single color — to keep strict directionality: unmet colors pin to that direction's 0 or 100 tone extreme instead of falling back to the original requested value.
@@ -299,6 +436,68 @@ theme.colors({
 
 Relative hue is always relative to the **theme seed hue**, not to a base color.
 
+#### Per-color `pastel`
+
+`pastel: true` on a single color def overrides the global / per-theme `pastel` config for that color only. It toggles the hue-independent "safe" chroma limit used in every OKHSL↔sRGB conversion that touches this color: luminance calculations during contrast solving, gamut clamping during sRGB blend / mix edges, and output formatting. The effective flag is carried on the resolved variant (`ResolvedColorVariant.pastel`) so formatting matches the gamut mapping applied during resolution.
+
+```ts
+const theme = glaze(280, 80);
+theme.colors({
+  plain: { tone: 50, saturation: 1 },
+  soft:  { tone: 50, saturation: 1, pastel: true },
+});
+// theme.resolve().get('soft')!.light.pastel === true
+// theme.css().light contains different rgb() triples for `--plain` and `--soft`
+```
+
+Omit the field to inherit the global / per-theme `pastel` config — useful for keeping the default behavior while opting a single accent into the pastel gamut.
+
+The flag is part of the def object, so `extend()` copies it through to child themes alongside the rest of the def. Override it again on the child to flip a single color back:
+
+```ts
+const parent = glaze(280, 80);
+parent.colors({ soft: { tone: 50, saturation: 1, pastel: true } });
+
+const child = parent.extend({
+  colors: { soft: { tone: 50, saturation: 1, pastel: false } },
+});
+// child.resolve().get('soft')!.light.pastel === false
+```
+
+> **Note:** Per-color `pastel` is also supported on `ShadowColorDef` and `MixColorDef` (see the tables above). For shadows the math itself happens in OKHSL space, so the flag mainly controls the gamut-mapped output formatting and any luminance verification for that variant.
+>
+> Standalone `glaze.color()` tokens accept the same `pastel` field on both the structured (`GlazeColorInput`) and value-shorthand (`GlazeColorOverrides`) forms, and it survives the `export()` / `glaze.colorFrom()` round-trip.
+
+#### Roles
+
+A color's `role` describes how it is used against its `base` and fixes **APCA contrast polarity** — which side is the foreground vs the background. APCA is asymmetric (`|apca(a,b)| ≠ |apca(b,a)|`), so the role picks the correct argument order; WCAG is symmetric and unaffected.
+
+| Role | Polarity | Use | Aliases (name inference) |
+|---|---|---|---|
+| `'text'` | fg | Text / icons / foreground content | `text`, `fg`, `foreground`, `content`, `ink`, `label`, `stroke` |
+| `'border'` | fg | Non-text spot elements (borders, dividers, outlines) | `border`, `divider`, `outline`, `separator`, `hairline`, `rule` |
+| `'surface'` | bg | Backgrounds / fills | `surface`, `bg`, `background`, `fill`, `canvas`, `paper`, `layer` |
+
+Resolution chain (per color):
+
+1. Explicit `role` (normalized from an alias) wins.
+2. Else, when `inferRole` is enabled (default), infer from the color name — the **last** recognized token wins (`button-text` → `text`, `input-bg` → `surface`, `card-outline` → `border`).
+3. Else, the opposite of the base's role (a `surface` base ⇒ this is `text`).
+4. Else, `'text'` (foreground) — i.e. the base is treated as the background.
+
+```ts
+const theme = glaze(280, 60);
+theme.colors({
+  surface: { tone: 90 },
+  text:    { base: 'surface', contrast: { apca: 'content' } }, // inferred text
+  border:  { base: 'surface', tone: '-10' },                   // inferred border
+});
+// role fixes APCA polarity; set `pastel: true` explicitly if a border
+// needs the hue-independent safe chroma limit.
+```
+
+Disable name inference with `glaze.configure({ inferRole: false })` (the base-opposite and foreground-default fallbacks still apply).
+
 ### `ShadowColorDef`
 
 | Field | Type | Description |
@@ -308,6 +507,7 @@ Relative hue is always relative to the **theme seed hue**, not to a base color.
 | `fg` | `string` | Optional foreground color name for tinting and intensity modulation. Must reference a non-shadow color. Omit for an achromatic shadow at full user-specified intensity. |
 | `intensity` | `HCPair<number>` | Shadow intensity, 0–100. Supports HC pairs. |
 | `tuning` | `ShadowTuning` | Per-color tuning overrides. Merged field-by-field with the global `shadowTuning`. |
+| `pastel` | `boolean` | Per-color `pastel` override. See [Per-color `pastel`](#per-color-pastel). |
 | `inherit` | `boolean` | Inheritance flag, default `true`. |
 
 See [Shadows](#shadows) below for the algorithm and tuning details.
@@ -323,6 +523,8 @@ See [Shadows](#shadows) below for the algorithm and tuning details.
 | `blend` | `'opaque' \| 'transparent'` | Default `'opaque'`. |
 | `space` | `'okhsl' \| 'srgb'` | Interpolation space for opaque blending. Default `'okhsl'`. Ignored for `'transparent'` (always composites in linear sRGB). |
 | `contrast` | `HCPair<ContrastSpec>` | Optional contrast floor against `base` (WCAG or APCA — see [`contrast`](#contrast-floor)). The solver adjusts the mix ratio (opaque) or opacity (transparent). |
+| `pastel` | `boolean` | Per-color `pastel` override. See [Per-color `pastel`](#per-color-pastel). |
+| `role` | `RoleInput` | Semantic role of the mixed result against `base`. Same semantics as `RegularColorDef.role` (see [Roles](#roles)). |
 | `inherit` | `boolean` | Inheritance flag, default `true`. |
 
 See [Mix colors](#mix-colors) below.
@@ -378,6 +580,8 @@ glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?:
 | `opacity` | `number` | Fixed alpha 0–1. |
 | `base` | `GlazeColorToken \| GlazeColorValue` | Optional dependency. See [Pairing colors](#pairing-colors). |
 | `contrast` | `HCPair<ContrastSpec>` | Contrast floor against `base` (WCAG or APCA). Without `base`, anchored to the literal seed. |
+| `pastel` | `boolean` | Per-color `pastel` override. Falls through to the global / per-theme `pastel` config when omitted. See [Per-color `pastel`](#per-color-pastel). |
+| `role` | `RoleInput` | Semantic role against `base` / the seed (see [Roles](#roles)). Fixes APCA polarity. |
 | `name` | `string` | Debug label for warnings; doesn't change output keys. Reserved names (`'value'`, `'seed'`, `'externalBase'`) are rejected. |
 
 `GlazeFromInput` (from form) is `{ from: GlazeColorValue, ...colorOverrides }`:
@@ -394,6 +598,8 @@ glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?:
 | `contrast` | Contrast floor (WCAG or APCA). Without `base`, anchored to the literal seed; with `base`, solved per scheme. |
 | `base` | `GlazeColorToken` or raw `GlazeColorValue`. See [Pairing colors](#pairing-colors). |
 | `opacity` | Fixed alpha 0–1. Combining with `contrast` is not recommended — `console.warn` is emitted. |
+| `pastel` | Per-color `pastel` override. Falls through to the global / per-theme `pastel` config when omitted. See [Per-color `pastel`](#per-color-pastel). |
+| `role` | Semantic role against `base` / the seed (see [Roles](#roles)). Fixes APCA polarity. |
 | `name` | Debug label only — surfaces in warnings/errors. Does not change output keys. |
 
 Named CSS colors (`'red'`, `'blueviolet'`) are not supported.
@@ -434,9 +640,12 @@ A `GlazeColorToken` exposes:
 |---|---|
 | `token.resolve()` | Resolve as a `ResolvedColor` (light/dark/lightContrast/darkContrast variants). |
 | `token.token(options?)` | Flat token map (no color-name key). Options: `format`, `modes`, `states`. |
-| `token.tasty(options?)` | Tasty state map (no color-name key). Same options as `token.token`. |
+| `token.tasty(options?)` | [Tasty](https://tasty.style) state map (no color-name key). Same options as `token.token`. |
 | `token.json(options?)` | JSON map (no color-name key). Options: `format`, `modes`. |
 | `token.css({ name, format?, suffix? })` | CSS custom property declarations grouped by scheme variant. `name` is **required** and becomes the variable identifier (`'brand'` → `--brand-color`). Defaults: `format: 'rgb'`, `suffix: '-color'` (matches `theme.css`). |
+| `token.dtcg(options?)` | DTCG color tokens, one per scheme variant (no color-name key). Each entry is a full `{ $type: 'color', $value }` token. Options: `colorSpace` (`'srgb'` \| `'oklch'`), `modes`. |
+| `token.dtcgResolver({ name, ... })` | A single DTCG Resolver-Module document for this color, keyed by `name` across all scheme variants. `name` is **required**. Same options as `theme.dtcgResolver()` plus `name`. |
+| `token.tailwind({ name, ... })` | Tailwind v4 `@theme` block + dark / high-contrast overrides for this color. `name` is **required** (forms `--color-<name>`). Same options as `theme.tailwind()` plus `name`. |
 | `token.export()` | JSON-safe snapshot — pass to `glaze.colorFrom(...)` to rehydrate. |
 
 ### Per-instance config override
@@ -885,6 +1094,56 @@ const stylesheet = `
 `palette.css()` accepts the same `GlazeCssOptions` as `theme.css()` plus `GlazePaletteExportOptions`.
 It does not accept `modes`; all four result fields are always returned.
 
+### `palette.dtcg()`
+
+DTCG export for a palette. Prefix defaults to `true` and the palette-level `primary` is honored (the primary theme's tokens are duplicated without prefix as aliases).
+
+```ts
+palette.dtcg()
+// → {
+//   light: {
+//     'primary-surface': { $type: 'color', $value: { ... } },
+//     'surface':         { $type: 'color', $value: { ... } },  // unprefixed alias
+//     'danger-surface':  { $type: 'color', $value: { ... } },
+//   },
+//   dark: { ... },
+// }
+```
+
+Accepts `GlazeDtcgOptions` plus `GlazePaletteExportOptions`.
+
+### `palette.dtcgResolver()`
+
+Resolver-Module export for a palette. Same as `theme.dtcgResolver()` but merges every theme (with prefix / `primary` aliasing) into the single `sets.base` source and each `scheme` context. Prefix defaults to `true`; the palette-level `primary` is honored.
+
+```ts
+palette.dtcgResolver()
+// → {
+//   version: '2025.10',
+//   sets: { base: { sources: [ { 'primary-surface': {…}, 'surface': {…}, 'danger-surface': {…} } ] } },
+//   modifiers: { scheme: { default: 'light', contexts: { light: [], dark: [ {…} ] } } },
+//   resolutionOrder: [ { $ref: '#/sets/base' }, { $ref: '#/modifiers/scheme' } ],
+// }
+```
+
+Accepts `GlazeDtcgResolverOptions` plus `GlazePaletteExportOptions`.
+
+### `palette.tailwind()`
+
+Tailwind export for a palette. All themes are merged into a single `@theme` block (plus dark / high-contrast overrides), so each color is reachable as a Tailwind utility. Prefix defaults to `true`.
+
+```ts
+const css = palette.tailwind();
+// @theme {
+//   --color-primary-surface: oklch(...);
+//   --color-surface: oklch(...);          /* unprefixed alias */
+//   --color-danger-surface: oklch(...);
+// }
+// .dark { ... }
+```
+
+Accepts `GlazeTailwindOptions` plus `GlazePaletteExportOptions`. The palette `prefix` option (theme prefixing) is separate from `GlazeTailwindOptions.namespace` (the `--color-*` CSS namespace).
+
 ---
 
 ## Output formats
@@ -893,21 +1152,40 @@ Control the color format with the `format` option on any export method:
 
 | Format | Output (alpha = 1) | Output (alpha < 1) | Notes |
 |---|---|---|---|
-| `'okhsl'` (default for tokens/tasty/json) | `okhsl(H S% L%)` | `okhsl(H S% L% / A)` | Glaze's native format, not a CSS function. |
-| `'rgb'` (default for css) | `rgb(R G B)` | `rgb(R G B / A)` | Rounded integers, modern space syntax. |
+| `'okhsl'` (default for `tasty()`) | `okhsl(H S% L%)` | `okhsl(H S% L% / A)` | Glaze's native format, not a CSS function. **Tasty-only** (`tasty()`, `token()`, `.tasty()`). |
+| `'okhst'` | `okhst(H S% T%)` | `okhst(H S% T% / A)` | OKHST tone axis. **Tasty-only** — same restriction as `okhsl`. |
+| `'oklch'` (default for `tokens()` / `json()`) | `oklch(L C H)` | `oklch(L C H / A)` | OKLab-based LCH. Native CSS. Required for `splitHue`. |
+| `'rgb'` (default for `css()`) | `rgb(R G B)` | `rgb(R G B / A)` | Rounded integers, modern space syntax. |
 | `'hsl'` | `hsl(H S% L%)` | `hsl(H S% L% / A)` | Modern space syntax. |
-| `'oklch'` | `oklch(L C H)` | `oklch(L C H / A)` | OKLab-based LCH. |
 
 ```ts
-theme.tokens();                    // 'okhsl(280 60% 97%)'
+theme.tokens();                    // 'oklch(0.965 0.0123 280)'  (default)
 theme.tokens({ format: 'rgb' });   // 'rgb(244 240 250)'
-theme.tokens({ format: 'hsl' });   // 'hsl(270.5 45.2% 95.8%)'
-theme.tokens({ format: 'oklch' }); // 'oklch(0.965 0.0123 280)'
+theme.tasty();                     // 'okhsl(280 60% 97%)'       (default)
+theme.tasty({ format: 'okhst' });  // 'okhst(280 60% 97%)'
 ```
 
 All numeric output strips trailing zeros for cleaner CSS (e.g. `95` not `95.0`).
 
-The `format` option works on every export: `theme.tokens()`, `theme.tasty()`, `theme.json()`, `theme.css()`, the same on `palette`, and on `token.token()` / `.tasty()` / `.json()` / `.css()`.
+The `format` option works on CSS-string exports: `theme.tokens()`, `theme.tasty()`, `theme.json()`, `theme.css()`, `theme.tailwind()`, the same on `palette`, and on `token.token()` / `.tasty()` / `.json()` / `.css()` / `.tailwind()`. **`okhsl` and `okhst` throw on non-Tasty exports** (`tokens`, `json`, `css`, `tailwind`) — they are not native CSS color spaces.
+
+### Hue channel splitting (`splitHue`)
+
+On `theme.css()`, `theme.tasty()`, `palette.css()`, `palette.tasty()`, and standalone `color.css()` with `format: 'oklch'`, set `splitHue: true` to emit hue as its own custom property so consumers can re-skin at runtime:
+
+```css
+/* theme.css({ format: 'oklch', splitHue: true, name: 'brand' }) */
+--brand-hue: 240;
+--accent-hue: calc(var(--brand-hue) + 20);
+--surface-color: oklch(0.52 0.06 var(--brand-hue));
+--accent-color: oklch(0.62 0.03 var(--accent-hue));
+```
+
+**Requirements:** every exported color must be pastel (`pastel: true` globally or per-color). Pastel mode bounds chroma by the hue-independent safe chroma at each lightness, so emitted `C` stays in sRGB for any rotated hue. Non-pastel palettes throw rather than emit values that would clip under rotation.
+
+**Limitations:** `oklch` only (native CSS `var()` in the hue slot). Shadow and mix colors stay inline (blended hue). Standalone `.token()` / `.tasty()` do not support `splitHue` (return shape cannot carry the `#name-hue` declaration).
+
+`theme.dtcg()` / `theme.dtcgResolver()` / `palette.dtcg()` / `palette.dtcgResolver()` ignore `format` — DTCG emits structured `$value` objects, not CSS strings. Use the `colorSpace` option (`'srgb'` or `'oklch'`) to pick the color representation instead.
 
 ---
 
@@ -1027,6 +1305,8 @@ A `ToneWindow` is `[lo, hi]` (OKHSL-lightness endpoints, reference eps — the c
 | `modes.highContrast` | `false` | Include HC variants. |
 | `shadowTuning` | `undefined` | Default tuning for all shadow colors. Per-color tuning merges field-by-field. |
 | `autoFlip` | `true` | Default for each color's `flip`. 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 [`flip`](#flip). |
+| `pastel` | `false` | Hue-independent "safe" chroma limit across all colors so scaling saturation never exceeds the sRGB boundary at any hue for the given lightness. Override per color via [`pastel`](#per-color-pastel). |
+| `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). |
 
 | Method | Description |
 |---|---|