--- language: "en" title: "API Reference" canonical: "https://glaze.tenphi.me/api/" source: "docs/api.md" version: "2.0.1" index: true --- # API Reference Full reference for every public method, option, and type exported by `@tenphi/glaze`. Organized for lookup, not for reading top-to-bottom — see [methodology.md](/methodology) for a guided walkthrough of how to use these primitives to build a real palette. ## Contents * [Theme creation](#theme-creation) * [Theme methods](#theme-methods) * [DTCG](#themedtcgoptions) * [DTCG Resolver-Module](#themedtcgresolveroptions) * [Tailwind CSS](#themetailwindoptions) * [High-contrast pairs](#high-contrast-pairs) * [Manual contrast level](#manual-contrast-level) * [Color definitions](#color-definitions) * [Dark seed](#dark-seed-darkhue--darksaturation) * [Standalone color tokens](#standalone-color-tokens) * [Shadows](#shadows) * [Mix colors](#mix-colors) * [Palette](#palette) * [Output formats](#output-formats) * [Hue channel splitting](#hue-channel-splitting-splithue) * [Adaptation modes](#adaptation-modes) * [Light / dark scheme mapping](#light--dark-scheme-mapping) * [Configuration](#configuration) * [Output modes](#output-modes) * [Validation](#validation) * [Color math utilities](#color-math-utilities) *** ## Theme creation | Method | Description | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `glaze(hue, saturation?, config?)` | Create a theme from hue (0–360) and saturation (0–100). Optional `config` overrides the global config for this theme. | | `glaze({ hue, saturation, darkHue?, darkSaturation? }, config?)` | Create a theme from an options object, with optional per-theme config override. `darkHue` / `darkSaturation` seed the dark schemes — see [Dark seed](#dark-seed-darkhue--darksaturation). | | `glaze.themeFrom(data)` | Create a theme from a `theme.export()` snapshot (`kind: 'theme'`). | | `glaze.from(data)` | Compat alias for `glaze.themeFrom`. | | `glaze.fromHex(hex)` | Create a theme from a hex color (`#rgb` or `#rrggbb`). Extracts hue and saturation. | | `glaze.fromRgb(r, g, b)` | Create a theme from RGB values (0–255). Extracts hue and saturation. | | `glaze.paletteFrom(data)` | Create a palette from a `palette.export()` snapshot (`kind: 'palette'`). | | `glaze.colorFrom(data)` | Create a color token from a `token.export()` snapshot (`kind: 'color'`). | | `glaze.isThemeExport(data)` | Type guard for theme authoring snapshots. | | `glaze.isColorTokenExport(data)` | Type guard for color-token authoring snapshots. | | `glaze.isPaletteExport(data)` | Type guard for palette authoring snapshots. | ```ts const a = glaze(280, 80); const b = glaze({ hue: 280, saturation: 80 }); const bDark = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 }); const c = glaze.fromHex('#7a4dbf'); const d = glaze.fromRgb(122, 77, 191); const e = glaze.themeFrom(a.export()); // Per-theme config override: const rawTheme = glaze(280, 80, { lightTone: false, darkTone: false }); ``` Authoring restore triad (parallel to `.export()` on each instance): | Export | Restore | | ------------------ | --------------------- | | `theme.export()` | `glaze.themeFrom()` | | `token.export()` | `glaze.colorFrom()` | | `palette.export()` | `glaze.paletteFrom()` | Every snapshot includes `kind` + `version` (`GLAZE_EXPORT_VERSION`, currently `1`). Legacy snapshots without those fields still restore. Wrong `kind`, or a `version` outside `1..=GLAZE_EXPORT_VERSION`, throws. The optional `config` parameter is a `GlazeConfigOverride` — see [Per-instance config override](#per-instance-config-override). *** ## Theme methods A `GlazeTheme` exposes: | Method | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------- | | `theme.hue` (readonly) | The hue seed (0–360). | | `theme.saturation` (readonly) | The saturation seed (0–100). | | `theme.darkHue` (readonly) | The dark-scheme hue seed (0–360), or `undefined` when `hue` is reused. | | `theme.darkSaturation` (readonly) | The dark-scheme saturation seed (0–100), or `undefined` when `saturation` is reused. | | `theme.colors(defs)` | Add/replace colors (additive merge — adds new, overwrites existing by name, doesn't remove others). | | `theme.color(name)` | Get a color definition by name. | | `theme.color(name, def)` | Set a single color definition. | | `theme.remove(name \| names[])` | Remove one or more color definitions. | | `theme.has(name)` | Check if a color is defined. | | `theme.list()` | List all defined color names. | | `theme.reset()` | Clear all color definitions. | | `theme.export(override?)` | Export the theme configuration as a JSON-safe object (optional config override at export time). | | `theme.extend(options)` | Create a child theme inheriting all color definitions (see [`extend`](#themeextendoptions) below). | | `theme.resolve()` | Resolve all colors and return a `Map`. | | `theme.tokens(options?)` | Export as a flat token map grouped by scheme variant. | | `theme.tasty(options?)` | Export as [Tasty](https://tasty.style) style-to-state bindings. | | `theme.json(options?)` | Export as plain JSON. | | `theme.css(options?)` | Export as CSS custom property declarations. | | `theme.dtcg(options?)` | Export one W3C DTCG token tree per scheme. | | `theme.dtcgResolver(options?)` | Export one DTCG Resolver-Module document containing every scheme. | | `theme.tailwind(options?)` | Export a Tailwind CSS v4 theme and scheme overrides. | ### `theme.colors(defs)` ```ts theme.colors({ surface: { tone: 97 } }); theme.colors({ text: { tone: 30 } }); // Both 'surface' and 'text' are now defined. ``` ### `theme.color(name) / theme.color(name, def)` ```ts theme.color('surface', { tone: 97, saturation: 0.75 }); // set const def = theme.color('surface'); // get ``` ### `theme.extend(options)` Creates a new theme inheriting all color definitions, optionally replacing the hue / saturation seed, color overrides, and config: ```ts const danger = primary.extend({ hue: 23, colors: { 'accent-fill': { tone: 48, mode: 'fixed' } }, }); // Inherit parent's config override and widen the dark window further: const highSat = base.extend({ config: { darkTone: [10, 100] } }); ``` `GlazeExtendOptions`: | Field | Type | Description | | ---------------- | --------------------- | -------------------------------------------------------------------------------------------- | | `hue` | `number` | Replace the hue seed. Defaults to the parent's hue. | | `saturation` | `number` | Replace the saturation seed. Defaults to the parent's saturation. | | `darkHue` | `number` | Replace the dark hue seed. Defaults to the parent's `darkHue`. | | `darkSaturation` | `number` | Replace the dark saturation seed. Defaults to the parent's `darkSaturation`. | | `colors` | `ColorMap` | Per-theme overrides (additive merge over the inherited map). | | `config` | `GlazeConfigOverride` | Config override for the child. Shallow-merged with the parent's override — child fields win. | Colors marked with `inherit: false` on the parent are **not** copied into the child. ### `theme.resolve()` Resolves the dependency graph and returns a `Map`. Export methods call it automatically; use it directly for tests, diagnostics, or a custom output pipeline. ```ts const resolved = theme.resolve(); const surface = resolved.get('surface'); // surface?.light.t is canonical tone on 0–1. ``` ### `theme.tokens(options?)` Flat token map grouped by scheme variant. ```ts theme.tokens(); // → { light: { surface: 'oklch(...)' }, dark: { surface: 'oklch(...)' } } ``` `GlazeJsonOptions`: | Option | Default | Description | | -------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `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?)` Style-to-state bindings for the [Tasty](https://tasty.style) style system. Uses `#name` color token keys and state aliases. By default the dark and high-contrast variants are keyed by media-query states (`'@media(prefers-color-scheme: dark)'`, `'@media(prefers-contrast: more)'`) so tokens work without registering custom states. ```ts theme.tasty(); // → { // '#surface': { '': 'oklch(...)', '@media(prefers-color-scheme: dark)': 'oklch(...)' }, // ... // } ``` `GlazeTokenOptions`: | Option | Default | Description | | --------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `format` | `'oklch'` | Output color format. `'okhsl'` and `'okhst'` are also supported here ([Tasty](https://tasty.style)-only spaces). | | `modes` | global config | Which scheme variants to include. | | `states.dark` | `'@media(prefers-color-scheme: dark)'` (or global config) | State alias for dark mode tokens. | | `states.highContrast` | `'@media(prefers-contrast: more)'` (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 ` & ` (e.g. `'@media(prefers-color-scheme: dark) & @media(prefers-contrast: more)'`). ### `theme.json(options?)` Per-color JSON map. ```ts theme.json(); // → { // surface: { light: 'oklch(...)', dark: 'oklch(...)' }, // text: { light: 'oklch(...)', dark: 'oklch(...)' }, // } ``` Same options as `tokens()`. ### `theme.css(options?)` CSS custom property declaration strings, grouped by scheme variant. ```ts theme.css(); // → { // light: '--surface-color: oklch(...);\n--text-color: oklch(...);', // dark: '--surface-color: oklch(...);\n--text-color: oklch(...);', // lightContrast: '...', // darkContrast: '...', // } ``` `GlazeCssOptions`: | Option | Default | Description | | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `format` | `'oklch'` | Output color format. One of `'rgb' \| 'hsl' \| 'oklch'`. `'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 `--` (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(override?)` ```ts const snapshot = theme.export(); // → { // kind: 'theme', // version: 1, // hue: 280, // saturation: 80, // colors: { surface: { ... }, ... }, // config: { lightTone: {...}, darkTone: {...}, pastel: false, ... }, // } const restored = glaze.themeFrom(snapshot); ``` Returns a deep-cloned, JSON-safe authoring snapshot (definitions + frozen effective config — not resolved color strings). Freezes `getConfig() ∪ instance local ∪ override` at call time. Restored themes pin that freeze as their local override. Distinct from `theme.json()`, which emits resolved color strings. *** ## High-contrast pairs `HCPair` means either one value used in both ordinary and high-contrast schemes, or an explicit `[normal, highContrast]` pair: ```ts type HCPair = T | [T, T]; ``` It is used by `tone`, `contrast`, shadow `intensity`, and mix `value`: ```ts tone: '-8'; // -8 in normal and HC tone: ['-8', '-16']; // -8 normal, -16 HC contrast: { apca: 'content'; } // preset with automatic HC enhancement contrast: { apca: ['content', 'body']; } // explicit normal/HC targets ``` For `contrast`, the pair may wrap the whole spec or live inside the selected metric. An explicit HC value disables automatic APCA enhancement or WCAG preset promotion for that color. *** ## Manual contrast level `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 }); const theme = glaze(280, 80, { contrastLevel: 60 }); glaze.color('#26fcb2', { contrastLevel: 60 }); ``` 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**. ### What the level interpolates Exactly the three things that make a high-contrast variant differ from its normal counterpart: | Mechanism | At level `L` | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | Authored `HCPair`s — `tone`, `contrast`, shadow `intensity`, mix `value` | the two ends are interpolated | | The tone-window bypass | each endpoint moves toward the full range: light `10→0`, dark `15→0 / 95→100` | | Contrast escalation — `AA → AAA`, APCA `+15 Lc` | the two numeric targets are interpolated (`AA` at level 50 solves for 5.75) | 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. ### Un-interpolable tone pairs switch at 50 Two ends of different kinds have no midpoint, because blending them would change *which* resolution rule applies partway up the ramp. These switch from the normal entry to the high-contrast one at level 50: ```ts tone: [50, 'max']; // absolute vs. extreme tone: [50, '+20']; // absolute vs. relative tone: ['max', 'min']; // opposite extremes ``` Same-kind pairs (`[30, 20]`, `['-6', '-12']`, `{ wcag: [4.5, 7] }`, `[{ apca: 60 }, { apca: 90 }]`) interpolate smoothly. A `contrast` pair may **not** switch metric — `[4.5, { apca: 75 }]` throws. A WCAG ratio and an APCA Lc are different scales, so no target exists between them, and even in `'auto'` mode the two variants would be incomparable. Pair values inside one metric instead: `{ wcag: [4.5, 7] }` or `{ apca: [60, 90] }`. ### A color never swaps sides mid-slider [`autoFlip`](#autoflip) decides per solve, and its tie-break — when both directions meet the floor, take the one nearer the authored tone — depends on the target. Along a ramp of targets that criterion shifts, so a naive implementation lets a color leap across its own base as the slider moves. Under a manual level the side is instead decided once, from the nearer endpoint's target, and preferred at every level in that half of the ramp. Consequences: * A color whose two ends land on the same side of its base **never** changes side, at any level. * A color whose ends genuinely disagree — no single side can satisfy both its normal and its high-contrast floor — changes side exactly once, at level 50, the same place un-interpolable tone pairs switch. * Flipping is not disabled, only re-ordered, so a side that physically cannot reach the requested contrast still falls back to the opposite one. The floor is met at every level. The underlying solver option is `preferInitial` on [`findToneForContrast`](#contrast-solver), should you need the same behavior directly. ### High-contrast output 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 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 — `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 `configure()` bumps the config version, which invalidates every theme and token cache, so a slider only needs to re-export: ```ts slider.oninput = () => { glaze.configure({ contrastLevel: slider.valueAsNumber }); apply(theme.css()); }; ``` 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 * **`configure()` never clears a field by omission.** Pass `'auto'` explicitly to leave manual mode — globally, or on one theme of a palette. * **`.export()` freezes only an *authored* level.** A level set on the instance (or passed to `.export()`) is authored intent and is written to the snapshot; a level merely inherited from the global config is a live user preference and is left out, so a restored theme still follows the current slider. This 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. 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). *** ## Color definitions `ColorDef` is a discriminated union: ```ts type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef; ``` ### `RegularColorDef` | Field | Type | Description | | ---------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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` | 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. | | `base` | `string` | Name of another color in the same theme — makes this a *dependent* color. | | `contrast` | `HCPair` | Contrast floor against `base`. Requires `base`. See [`contrast`](#contrast-floor). | | `mode` | `'auto' \| 'fixed' \| 'static'` | Adaptation mode. Default: `'auto'`. See [Adaptation modes](#adaptation-modes). | | `autoFlip` | `boolean` | Flip out-of-bounds results (relative `tone` overshoot / unmet `contrast`) to the opposite side instead of clamping. Default: the global `autoFlip` (`true`). See [`autoFlip`](#autoflip). | | `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 per-theme / per-token `pastel` override 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. | #### `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. Equal tone differences give equal WCAG contrast for neutrals; chromatic results can drift in measured luminance. See [OKHST in Glaze](/okhst). To port old `lightness` values, see [migration.md](/migration). | Form | Example | Meaning | | ------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Number (absolute) | `tone: 45` | Absolute tone 0–100. | | String (tone delta) | `tone: '-52'` | Signed difference from the base color's resolved tone (requires `base`). | | Extreme | `tone: 'max'` / `'min'` | Force to the scheme's highest (`'max'` = 100) or lowest (`'min'` = 0) tone. With a `base`, the light-scheme shift is replayed in dark. No `base` needed. | | HC pair | `tone: ['-7', '-20']` | `[normal, high-contrast]`. A single value applies to both. | **Absolute tone** on a dependent color (`base` set) positions the color independently. In dark mode it is tone-mapped (inverted + windowed) on its own. The `contrast` solver acts as a safety net. **A tone delta** applies a signed difference to the base color's resolved tone. It gives an exact contrast step for neutrals and a stable visual progression for chromatic colors. In dark mode with `mode: 'auto'`, it is anchored to the base's per-scheme tone. If `base + delta` falls outside `[0, 100]`, the result is clamped to the boundary, or — with `autoFlip` (default on) — mirrored to the other side of the base. If the mirrored target is also out of range, the original 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. 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({ bg: { tone: 60 }, fg: { base: 'bg', tone: 'max' }, }); // light: bg 62.0, fg 100.0 — shift +38.0, contrast 3.18:1 // dark: bg 43.9, fg 5.9 — shift -38.0, contrast 3.18:1 ``` A dependent color with `base` but no `tone` inherits the base's tone (equivalent to a delta of 0). #### `autoFlip` `autoFlip` governs what happens when a result would fall outside its valid range: * **Relative `tone` overshoot:** when `base ± delta` exceeds `[0, 100]`, `autoFlip` mirrors the delta to the other side of the base (e.g. `'+30'` becomes `'-30'`) instead of clamping to the boundary. If the mirrored target is also outside `[0, 100]`, the original delta is kept and clamped on the authored side. * **`contrast` direction:** when the requested tone direction can't meet the floor, `autoFlip` lets the solver try the opposite side (the same behavior as the global `autoFlip`). `autoFlip` defaults to the global `autoFlip` (`true`). Set `autoFlip: false` on a color to clamp instead of mirror — useful when you want a relative offset to stay on the authored side of the base, or to keep an unmet contrast pinned to one direction's extreme. #### `contrast` (floor) ```ts type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large'; type ContrastSpec = | number // bare WCAG ratio | ContrastPreset // named WCAG preset | { wcag: HCPair } | { apca: HCPair }; // APCA Lc target ``` | Preset | WCAG ratio | | ------------- | ---------- | | `'AA-large'` | 3 | | `'AA'` | 4.5 | | `'AAA-large'` | 4.5 | | `'AAA'` | 7 | A bare number or preset means **WCAG**. Use `{ wcag }` / `{ apca }` to pick the metric explicitly. The `[normal, highContrast]` pair may live at the outer level (`[4.5, 7]`, `[{ wcag: 4.5 }, { wcag: 7 }]`) or inside the metric (`{ wcag: [4.5, 7] }`, `{ apca: [45, 60] }`). ```ts contrast: 4.5; // WCAG 4.5 contrast: 'AAA'; // WCAG 7 contrast: { wcag: 6; } // WCAG 6 contrast: { wcag: [4.5, 7]; } // WCAG 4.5 normal / 7 high-contrast (explicit) contrast: { apca: 60; } // APCA Lc 60 normal / 75 high-contrast (auto) contrast: { apca: [45, 60]; } // APCA Lc 45 normal / 60 high-contrast (explicit) contrast: { apca: 'content'; } // APCA preset -> Lc 60 normal / 75 high-contrast (auto) contrast: { apca: ['content', 'body']; } // Lc 60 normal / 75 high-contrast (explicit) ``` **WCAG HC auto-promotion:** a bare WCAG preset (no `[normal, hc]` pair at either the outer `contrast` or inner `wcag` level) is automatically promoted to its spec-defined "Enhanced" successor in high-contrast mode — `AA` → `AAA` (4.5 → 7) and `AA-large` → `AAA-large` (3 → 4.5), per WCAG SC 1.4.3 → 1.4.6. `AAA` and `AAA-large` are already the top WCAG tier and are left unchanged; bare numeric targets have no successor tier and are also left unchanged. An explicit HC value via either pair overrides and skips the promotion. **APCA Enhanced Level (HC auto-boost):** a bare APCA scalar (no `[normal, hc]` pair at either the outer `contrast` or inner `apca` level) is automatically boosted by **+15 Lc** in high-contrast mode, the APCA analog of WCAG's AAA-over-AA step. On by default; an explicit HC value via either pair overrides it and skips the boost. The enhanced target is clamped to 106 Lc. For large/bold text (where APCA caps contrast at Lc 90 to avoid glare), pass an explicit HC pair to hold that ceiling. 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). The floor is applied independently per scheme. If the preferred `tone` already satisfies it, the tone is kept; otherwise the solver uses the tone-shaped scale for a closed-form WCAG seed and fast search 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 [`autoFlip`](#autoflip) (which defaults to the global `autoFlip`). Set `glaze.configure({ autoFlip: false })` — or `autoFlip: 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. **Full tone spectrum in HC mode:** in high-contrast variants the `lightTone` and `darkTone` window constraints are bypassed entirely (the window is forced to `[0, 100]`). Colors can reach the full range, maximizing perceivable contrast. **Chromatic drift (verification):** tone is contrast-uniform for grays. A chromatic swatch at a given tone shares its OKHSL lightness with the equivalent gray but drifts in real luminance, so a contrast-floored color may land slightly under its gray-tone expectation. Glaze measures the resolved result against the base and emits a deduped advisory `console.warn` when it drifts below the target. See [Contrast verification](/okhst#contrast-verification). #### Per-color hue override ```ts const theme = glaze(280, 80); theme.colors({ surface: { tone: 97 }, gradientEnd: { tone: 90, hue: '+20' }, // 280 + 20 = 300 warning: { tone: 60, hue: 40 }, // absolute }); ``` Relative hue is always relative to the **theme seed hue**, not to a base color. #### Dark seed (`darkHue` / `darkSaturation`) Tone inverts automatically between light and dark, but hue and saturation do not — by default every scheme reuses the one seed, with dark getting a flat `darkDesaturation` haircut. When a palette needs a genuinely different chroma in dark (a cooler accent, a calmer surface tint), author a second seed: ```ts const theme = glaze({ hue: 280, saturation: 80, darkHue: 268, // dark schemes seed from 268 instead of 280 darkSaturation: 65, // and from 65 instead of 80 }); ``` Individual colors can override either channel for dark on their own: ```ts theme.colors({ surface: { tone: 97 }, accent: { tone: 55, hue: '+20', darkHue: '+35' }, warning: { tone: 60, saturation: 0.9, darkSaturation: 0.6 }, }); ``` Both apply to the `dark` **and** `darkContrast` variants. The rules: | Rule | Behavior | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Units | Seed-level `darkSaturation` is `0–100` (like `saturation` on the theme). Def-level `darkSaturation` is a `0–1` factor (like `saturation` on a color def). | | Fallback | `darkHue` falls back to `hue`, `darkSaturation` to `saturation`, and the def falls back to the seed. Omitting everything reproduces the previous behavior exactly. | | Relative hue | `darkHue: '+N'` anchors to the theme's **dark** seed hue. A plain `hue: '+N'` with no `darkHue` also re-anchors to the dark seed, so a whole palette rotates together. | | Absolute hue | An absolute `hue` (no `darkHue`) is used verbatim in dark — absolute means absolute in every scheme. | | `darkDesaturation` | Bypassed as soon as any explicit dark saturation is authored, at either level. The value you write is the value you get. | | `mode: 'static'` | Ignores both. A static color is pinned to one hue and saturation across every scheme. | | Shadows and mixes | Have no channels of their own — they derive hue and saturation from their `bg` / `fg` / `target`, so they inherit dark overrides automatically. | With [`splitHue`](#hue-channel-splitting-splithue), a dark seed makes the hue custom properties scheme-dependent; Glaze re-declares them in the dark block automatically. #### Per-color `pastel` `pastel: true` on a single color def overrides the per-theme / per-token `pastel` override 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 theme/token `pastel` override (default `false`) — 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 | | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `'shadow'` | Discriminator. | | `bg` | `string` | Background color name — must reference a non-shadow color in the same theme. | | `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` | 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. ### `MixColorDef` | Field | Type | Description | | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `'mix'` | Discriminator. | | `base` | `string` | "From" color name. | | `target` | `string` | "To" color name. | | `value` | `HCPair` | Mix ratio 0–100 (0 = pure base, 100 = pure target). In `'transparent'` blend, this becomes the target's opacity. Supports HC pairs. | | `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` | 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. *** ## Standalone color tokens `glaze.color()` creates a single color token without a full theme. ```ts // arg1: the color (four shapes — see below) // arg2: optional config override (GlazeConfigOverride — see below) glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride): GlazeColorToken; ``` ### Input forms `glaze.color()` accepts **four input shapes**, discriminated by structure: | Shape | Example | Notes | | ---------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- | | **Bare string** | `'#26fcb2'` | Hex or CSS color function (`rgb()`, `hsl()`, `okhsl()`, `okhst()`, `oklch()`). | | **Value object** | `{ h: 152, s: 0.95, l: 0.74 }` | OKHSL, OKHST (`{ h, s, t }`), `{ r, g, b }` (sRGB 0–255), or `{ l, c, h }` (OKLCh). | | **`{ from, ...overrides }`** | `{ from: '#1a1a2e', base: bg, contrast: 'AA' }` | Value + color overrides in one object. | | **Structured** | `{ hue: 152, saturation: 95, tone: 74 }` | Full theme-style token (hue/saturation in 0–100, tone in 0–100). | `GlazeColorValue` (bare string or value-object forms) accepts: | Form | Example | Notes | | ------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Hex | `'#26fcb2'`, `'#26fcb2ff'`, `'#abc'` | 3, 6, or 8 digits. Alpha is dropped with a `console.warn` — use `opacity` instead. | | `rgb()` | `'rgb(38 252 178)'`, `'rgb(38 252 178 / 0.8)'` | Modern space syntax. Alpha dropped with warning. | | `hsl()` | `'hsl(152 97% 57%)'` | Modern space syntax. Alpha dropped with warning. | | `okhsl()` | `'okhsl(152 95% 74%)'` | Glaze's own emit format. Alpha dropped with warning. | | `okhst()` | `'okhst(152 95% 70%)'` | OKHST tone input (third value is tone 0–100). Not native CSS; it can also be serialized by [Tasty](https://tasty.style) exports. Alpha dropped with warning. | | `oklch()` | `'oklch(0.85 0.18 152)'` | Glaze's own emit format. Alpha dropped with warning. | | `OkhslColor` object | `{ h: 152, s: 0.95, l: 0.74 }` | OKHSL shape (h: 0–360, s/l: 0–1). Passing 0–100 for `s`/`l` throws with a hint to use the structured form. | | `OkhstColor` object | `{ h: 152, s: 0.95, t: 0.70 }` | Direct OKHST input shape (h: 0–360, s/t: 0–1). The `t` key disambiguates it from `{ h, s, l }`. | | `RgbColor` object | `{ r: 38, g: 252, b: 178 }` | sRGB 0–255. RGB tuple `[r, g, b]` is not supported — use this object form. | | `OklchColor` object | `{ l: 0.85, c: 0.18, h: 152 }` | OKLCh (L/C: 0–1, H: degrees), same semantics as `oklch()` strings. | `GlazeColorInput` (structured form) is `{ hue, saturation, tone, ... }`: | Field | Type | Description | | ---------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `hue` | `number` | 0–360. | | `saturation` | `number` | 0–100. | | `tone` | `HCPair` | 0–100 (contrast-shaped) or `'max'`/`'min'`, optional HC pair. | | `saturationFactor` | `number` | Multiplier on the seed (0–1). Default: `1`. | | `darkHue` | `number \| RelativeValue` | Dark-scheme hue. Absolute (0–360) or `'+N'`/`'-N'` relative to the dark seed hue (which defaults to `hue`). Falls back to `hue`. | | `darkSaturation` | `number` | Dark-scheme seed saturation (0–100). Falls back to `saturation`. | | `darkSaturationFactor` | `number` | Dark-scheme multiplier on the dark seed (0–1). Falls back to `saturationFactor`. | | `mode` | `AdaptationMode` | Default: `'auto'`. | | `autoFlip` | `boolean` | Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. | | `opacity` | `number` | Fixed alpha 0–1. | | `base` | `GlazeColorToken \| GlazeColorValue` | Optional dependency. See [Pairing colors](#pairing-colors). | | `contrast` | `HCPair` | Contrast floor against `base` (WCAG or APCA). Without `base`, anchored to the literal seed. | | `pastel` | `boolean` | Per-color `pastel` override. Falls through to the per-theme / per-token `pastel` override 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 }`: | Field | Notes | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `from` | **Required.** The source color value — same forms as `GlazeColorValue`. | | `hue` | Number (absolute 0–360) or `'+N'`/`'-N'` (relative to seed, never to `base`). | | `saturation` | Override seed saturation (0–100). | | `tone` | Number (absolute 0–100), `'+N'`/`'-N'`, or `'max'`/`'min'`. Without `base`, relative anchors to the seed; with `base`, anchors to `base`'s tone per scheme. | | `saturationFactor` | Multiplier on the seed (0–1). | | `darkHue` | Dark-scheme hue: absolute (0–360) or `'+N'`/`'-N'` relative to the dark seed hue. Falls back to `hue`. | | `darkSaturation` | Dark-scheme seed saturation (0–100). Falls back to `saturation`. | | `darkSaturationFactor` | Dark-scheme multiplier on the dark seed (0–1). Falls back to `saturationFactor`. | | `mode` | `'auto'` (default) / `'fixed'` / `'static'`. | | `autoFlip` | Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. | | `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 per-theme / per-token `pastel` override 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. ### Defaults Every input form defaults to `mode: 'auto'` so the resolved token adapts between light and dark like an ordinary theme color. Tokens store a **sparse local** config override; omitted fields fall through to the live global at resolve time (same as themes). Authoring `.export(override?)` freezes `getConfig() ∪ local ∪ override` at call time. * **Value-shorthand** (bare strings, value objects, and `{ from, ...overrides }`): * Light variant preserves the input tone exactly (`lightTone: false` as a local default). * Other omitted fields track the live global config. * **Structured input** (`{ hue, saturation, tone, ... }`): * Omitted tone windows and other fields track the live global config (same as a theme color). * `pastel` is instance-only — set via the config override or per-color `pastel`, not `glaze.configure()`. ```ts // Bare string — adapts automatically glaze.color('#26fcb2'); // Value-object — same behavior glaze.color({ h: 152, s: 0.95, l: 0.74 }); // OKHST value-object — tone axis glaze.color({ h: 152, s: 0.95, t: 0.7 }); // From form — value + color overrides glaze.color({ from: '#1a1a2e', hue: '+20', contrast: 'AA' }); // Structured form — explicit hue/saturation/tone (0–100) glaze.color({ hue: 152, saturation: 95, tone: 74 }); ``` ### Token methods A `GlazeColorToken` exposes: | Method | Description | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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](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-`). Same options as `theme.tailwind()` plus `name`. | | `token.export(override?)` | JSON-safe snapshot — freezes effective config at call time; pass to `glaze.colorFrom(...)` to rehydrate. Optional `override` merges over the instance local (and nested `base` exports). | ### Per-instance config override The optional `config` argument (`GlazeConfigOverride`) overrides resolve-relevant fields for a token or theme. A tone window can be `[lo, hi]`, `{ lo, hi, eps }`, or `false` (full range). Both themes and standalone tokens keep a sparse local override — omitted fields (except instance-only `pastel`) fall through to the live global at resolve time. `GlazeConfigOverride`: | Field | Default (from global / fixed) | Description | | ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lightTone` | `[10, 100]` | Light tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` (disable clamping). | | `darkTone` | `[15, 95]` | Dark tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` (disable clamping). | | `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). | | `autoFlip` | `true` | Default for each color's `autoFlip`: when solving `contrast` (or applying a relative `tone` that overshoots), allow crossing to the opposite side instead of clamping. | | `pastel` | `false` (instance-only) | Theme/token-level pastel default for colors that omit per-color `pastel`. Not available on `glaze.configure()`. | | `inferRole` | `true` | Infer color `role` from the name when unset. | | `shadowTuning` | `undefined` | Default shadow tuning (meaningful for themes; harmless on color tokens). | Config overrides apply to both `glaze.color()` tokens and `glaze()` themes: ```ts // Standalone color — preserve raw tone in both schemes glaze.color('#26fcb2', { darkTone: false }); // Restore the #000 → white dark flip (full dark range) glaze.color('#000000', { lightTone: false, darkTone: [15, 100], }); // Structured form with config override glaze.color({ hue: 152, saturation: 95, tone: 74 }, { darkTone: false, pastel: true }); // Theme with config override const rawTheme = glaze(280, 80, { lightTone: false, pastel: true }); ``` See [Theme config override](#theme-config-override). ### Theme config override When a theme is created with a `GlazeConfigOverride`, the override is **merged over the live global config at resolve time**. This means: * Fields you overrode are fixed — `glaze.configure()` can't change them for this theme. * Fields you didn't override still react to later `glaze.configure()` calls. ```ts const t = glaze(280, 80, { lightTone: [0, 50] }); t.colors({ text: { tone: 50, saturation: 1 } }); // text.light lands inside the [0, 50] window — always, regardless of // global lightTone changes. // text.dark.s reacts to glaze.configure({ darkDesaturation }) since it's not overridden. ``` `extend` inherits the parent's override and shallow-merges the child's: ```ts const child = t.extend({ config: { darkTone: false } }); // child: lightTone { lo: 0, hi: 50 } (inherited) + darkTone: false (added) ``` `theme.export(override?)` freezes `getConfig() ∪ instance local ∪ override` at call time. Restoring via `glaze.themeFrom(data)` (or the compat alias `glaze.from`) pins that freeze as the restored theme's local override — matching standalone color-token behavior. ### `glaze.colorFrom(data)` Inverse of `token.export()`. The exported snapshot includes the original input, all overrides (with any `base` token recursively serialized), and the effective config freeze from export time — so later `glaze.configure()` calls don't change rehydrated tokens. ```ts const text = glaze.color({ from: '#1a1a1a', contrast: 'AA' }); const data = text.export(); const restored = glaze.colorFrom(data); // restored.resolve() === text.resolve() byte-for-byte ``` Both value-form and structured-form tokens round-trip. ### Pairing colors Set `base` to anchor a standalone color to another standalone color or raw value. The contrast solver and relative `tone` offsets switch their anchor from the literal seed to the base's resolved variant per scheme — so the same text color automatically lands at AA against its background in light, dark, and high-contrast modes. ```ts const bg = glaze.color('#1a1a2e'); // Text guaranteed AA against `bg` in every scheme. const text = glaze.color({ from: '#ffffff', base: bg, contrast: 'AA' }); // Border 8 tone units lighter than `bg` in each scheme. const border = glaze.color({ from: '#000000', base: bg, tone: '+8', mode: 'fixed', }); // Raw-value base — Glaze auto-wraps it via `glaze.color(value)`. const text2 = glaze.color({ from: '#ffffff', base: '#1a1a2e', contrast: 'AA' }); ``` Behavior with `base`: * `contrast` is solved per scheme against `base`'s resolved variant (light / dark / lightContrast / darkContrast). * Relative `tone: '+N'` / `'-N'` is anchored to `base`'s tone per scheme (matches theme behavior). * Relative `hue: '+N'` / `'-N'` still anchors to the **seed** (the value passed to `glaze.color()`), not the base. * `mode` works as a per-pair knob. * The base token's `.resolve()` is called lazily on the first resolve of the dependent and the result is captured by reference; later mutations to the base don't apply. * **Structured bases are resolved at full range for linking math**: when a value/`from` color links to a base created via the structured form, the contrast/tone anchor uses the raw input tone (not the windowed output). This ensures the anchor matches what you intended, not what the light window remapped it to. The base's own `.resolve()` output is unaffected. * When the contrast target is physically unreachable, `glaze` emits a single `console.warn` per `(name, scheme, target)` triple and returns the closest passing variant. Use the `name` override to make the warning identifiable. Chains compose: ```ts const bg = glaze.color('#000000'); const surface = glaze.color({ from: '#222222', base: bg, contrast: 'AAA' }); const text = glaze.color({ from: '#ffffff', base: surface, contrast: 'AA' }); ``` ### `name` is a debug label The `name` override appears in `console.warn` / Error messages but **does not** change output keys (`.token()`, `.tasty()`, `.json()`, `.css()` still use `''`, `light`, etc.). The CSS variable name comes from `css({ name })`, not from the override. *** ## Shadows ### Defining shadow colors in a theme ```ts theme.colors({ surface: { tone: 95 }, text: { base: 'surface', tone: '-52', contrast: 'AAA' }, 'shadow-sm': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 5 }, 'shadow-md': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 10 }, 'shadow-lg': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 20 }, }); ``` Shadow colors are included in all output methods (`tokens()`, `tasty()`, `css()`, `json()`) alongside regular colors and emit an alpha component: ``` 'oklch(0.15 0.009 282 / 0.1)' 'rgb(34 28 42 / 0.1)' ``` ### How shadows work 1. **Contrast weight** — when `fg` is provided, shadow strength scales with `|l_bg − l_fg|`. Dark text on a light background produces a strong shadow; near-background-lightness elements produce barely visible shadows. 2. **Pigment color** — hue blended between fg and bg, low saturation, dark lightness. 3. **Alpha** — computed via a `tanh` curve that saturates smoothly toward `alphaMax` (default `1.0`), ensuring well-separated shadow levels even on dark backgrounds. Omit `fg` for an achromatic shadow at full user-specified intensity: ```ts theme.colors({ 'drop-shadow': { type: 'shadow', bg: 'surface', intensity: 12 }, }); ``` `intensity` supports `[normal, highContrast]` pairs: ```ts 'shadow-card': { type: 'shadow', bg: 'surface', fg: 'text', intensity: [10, 20] }, ``` ### `ShadowTuning` Fine-tune behavior per-color or globally via `glaze.configure({ shadowTuning })`. Per-color `tuning` is merged field-by-field with the global one. | Parameter | Default | Description | | ------------------ | -------------- | ------------------------------------------------------------------------------------- | | `saturationFactor` | `0.18` | Fraction of fg saturation kept in pigment. | | `maxSaturation` | `0.25` | Upper clamp on pigment saturation. | | `lightnessFactor` | `0.25` | Multiplier for bg lightness → pigment lightness. | | `lightnessBounds` | `[0.05, 0.20]` | Clamp range for pigment lightness. | | `minGapTarget` | `0.05` | Target minimum gap between pigment and bg lightness. | | `alphaMax` | `1.0` | Asymptotic maximum alpha. | | `bgHueBlend` | `0.2` | Blend weight pulling pigment hue toward bg hue. `0` = pure fg hue, `1` = pure bg hue. | ```ts theme.colors({ 'shadow-soft': { type: 'shadow', bg: 'surface', intensity: 10, tuning: { alphaMax: 0.3, saturationFactor: 0.1 }, }, }); glaze.configure({ shadowTuning: { alphaMax: 0.5, bgHueBlend: 0.3 }, }); ``` ### Standalone shadow computation `glaze.shadow(input)` computes a shadow outside of a theme. `bg` and `fg` accept any `GlazeColorValue`: ```ts const v = glaze.shadow({ bg: '#f0eef5', fg: '#1a1a2e', intensity: 10, }); // → { h: 280, s: 0.14, l: 0.2, alpha: 0.1 } const css = glaze.format(v, 'oklch'); // → 'oklch(0.15 0.014 280 / 0.1)' ``` `GlazeShadowInput`: | Field | Type | Description | | ----------- | ----------------- | ------------------------------------------------------------------------------ | | `bg` | `GlazeColorValue` | Background. Any `GlazeColorValue` form. Alpha components dropped with warning. | | `fg` | `GlazeColorValue` | Optional foreground. Same forms as `bg`. | | `intensity` | `number` | 0–100. | | `tuning` | `ShadowTuning` | Optional. | ### Fixed opacity (regular colors) For a simple fixed-alpha color (no shadow algorithm), use `opacity` on a regular color: ```ts theme.colors({ overlay: { tone: 0, opacity: 0.5 }, }); // → 'oklch(0 0 0 / 0.5)' ``` *** ## Mix colors ### Opaque mix Produces a solid color by interpolating between `base` and `target`: ```ts theme.colors({ surface: { tone: 95 }, accent: { tone: 30 }, tint: { type: 'mix', base: 'surface', target: 'accent', value: 30 }, }); ``` * `value: 0` = pure base, `value: 100` = pure target. * Result has alpha = 1. * Adapts to light/dark/HC schemes automatically via the resolved base and target. ### Transparent mix Produces the target color with controlled opacity — useful for hover overlays: ```ts theme.colors({ surface: { tone: 95 }, black: { tone: 0, saturation: 0 }, hover: { type: 'mix', base: 'surface', target: 'black', value: 8, blend: 'transparent', }, }); // hover → black with alpha = 0.08 ``` The output color has `h`, `s`, `l` from the target and `alpha = value / 100`. ### Blend space (opaque only) | `space` | Behavior | Best for | | ------------------- | ----------------------------------------- | -------------------------------------------------------- | | `'okhsl'` (default) | Perceptually uniform OKHSL interpolation. | Design token derivation. | | `'srgb'` | Linear sRGB channel interpolation. | Matching browser compositing of CSS color-mix / overlay. | Transparent blending always composites in linear sRGB (matches browser alpha compositing). ### Contrast solving on mixes Mix colors support the same `contrast` prop as regular colors. The solver adjusts the mix ratio (opaque) or opacity (transparent) to meet the WCAG target: ```ts 'tint': { type: 'mix', base: 'surface', target: 'accent', value: 10, contrast: 'AA', }, 'overlay': { type: 'mix', base: 'surface', target: 'accent', value: 5, blend: 'transparent', contrast: 3, }, ``` Both `value` and `contrast` support `[normal, highContrast]` pairs. ### Achromatic colors When mixing with achromatic colors (saturation near zero, e.g. white or black) in `okhsl` space, the hue comes from whichever color has saturation. Matches CSS `color-mix()` "missing component" behavior. For purely achromatic mixes prefer `space: 'srgb'` where hue is irrelevant. ### Mix chaining Mix colors can reference other mix colors: ```ts theme.colors({ white: { tone: 100, saturation: 0 }, black: { tone: 0, saturation: 0 }, gray: { type: 'mix', base: 'white', target: 'black', value: 50, space: 'srgb', }, lightGray: { type: 'mix', base: 'white', target: 'gray', value: 50, space: 'srgb', }, }); ``` Mix colors **cannot** reference shadow colors (same restriction as regular dependent colors). *** ## Palette `glaze.palette(themes, options?)` composes multiple themes into a single token namespace. ```ts const palette = glaze.palette({ primary, danger, success, warning }); const palette = glaze.palette( { primary, danger, success }, { primary: 'primary' }, ); ``` `GlazePaletteOptions`: | Option | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `primary` | Name of the primary theme. The primary's tokens are duplicated **without** prefix in all exports, providing convenient short aliases alongside the prefixed versions. Throws if the name doesn't match any theme. | A `GlazePalette` exposes: | Method | Description | | -------------------------------- | ------------------------------------------------------------------------------------------------- | | `palette.list()` | Theme names in insertion order. | | `palette.primary` | Primary theme name, if set. | | `palette.theme(name)` | Get a live theme instance by name. | | `palette.themes()` | Shallow copy of the theme map (same instances the palette holds). | | `palette.export(override?)` | Authoring snapshot — restorable via `glaze.paletteFrom()`. Optional override forwarded to themes. | | `palette.tokens(options?)` | Flat token map grouped by scheme variant. | | `palette.tasty(options?)` | [Tasty](https://tasty.style) style-to-state bindings. | | `palette.json(options?)` | Per-theme **resolved** color JSON (not restorable as authoring config). | | `palette.css(options?)` | CSS custom property declaration strings. | | `palette.dtcg(options?)` | Per-scheme W3C DTCG token trees. | | `palette.dtcgResolver(options?)` | One DTCG Resolver-Module document for every scheme. | | `palette.tailwind(options?)` | One Tailwind CSS v4 theme with scheme overrides. | ### `palette.export(override?)` / `glaze.paletteFrom()` ```ts const snapshot = palette.export(); // → { // kind: 'palette', // version: 1, // primary: 'brand', // themes: { brand: { kind: 'theme', ... }, danger: { ... } }, // } const restored = glaze.paletteFrom(JSON.parse(JSON.stringify(snapshot))); const brand = restored.theme('brand')!; ``` Optional `override` is forwarded to each nested `theme.export(override)`. Config snapshot vs resolved output: use `export()` / `paletteFrom()` to persist and restore the authoring graph (themes, color defs, relations). Use `json()` / `tokens()` / `css()` / … to emit resolved color strings for apps and design tools. ### `GlazePaletteExportOptions` Shared by `tokens`, `tasty`, and `css`: | Option | Default | Description | | --------- | ------------------------------ | -------------------------------------------------------------------------------------------- | | `prefix` | `true` (= `"-"`) | `false` disables prefixing. Or pass a custom map: `{ primary: 'brand-', danger: 'error-' }`. | | `primary` | inherits from palette creation | `string` to override, `false` to disable for this call. | Each export method also accepts its own format/options shape: | Method | Additional options | | -------------------------------- | ----------------------------------------- | | `palette.tokens(options?)` | `format`, `modes` | | `palette.tasty(options?)` | `format`, `modes`, `states` | | `palette.css(options?)` | `format`, `suffix` | | `palette.dtcg(options?)` | `colorSpace`, `modes` | | `palette.dtcgResolver(options?)` | `colorSpace`, `modes`, resolver names | | `palette.tailwind(options?)` | `format`, `modes`, selectors, `namespace` | `palette.css()` does not accept `modes`; it always returns all four CSS strings (`light`, `dark`, `lightContrast`, `darkContrast`). ### Prefix behavior By default all palette tokens are prefixed: ```ts palette.tokens(); // → { // light: { 'primary-surface': 'oklch(...)', 'danger-surface': 'oklch(...)' }, // dark: { 'primary-surface': 'oklch(...)', 'danger-surface': 'oklch(...)' }, // } ``` Custom map (any theme not listed falls back to `"-"`): ```ts palette.tokens({ prefix: { primary: 'brand-', danger: 'error-' } }); ``` Disable prefixing: ```ts palette.tokens({ prefix: false }); ``` ### Collision detection When two themes produce the same output key (via `prefix: false`, custom prefix maps, or primary unprefixed aliases), the **first-written value wins** and a `console.warn` is emitted: ``` glaze: token "surface" from theme "b" collides with theme "a" — skipping. ``` ### Primary theme aliases The primary theme's tokens are duplicated without prefix: ```ts const palette = glaze.palette( { primary, danger, success }, { primary: 'primary' }, ); palette.tokens(); // → { // light: { // 'primary-surface': 'oklch(...)', // 'danger-surface': 'oklch(...)', // 'success-surface': 'oklch(...)', // 'surface': 'oklch(...)', // unprefixed alias // }, // } ``` Override per-export: ```ts palette.tokens({ primary: 'danger' }); palette.tokens({ primary: false }); ``` The primary alias works alongside any prefix mode — when using a custom map, primary tokens are still duplicated without prefix: ```ts palette.tokens({ prefix: { primary: 'p-', danger: 'd-' } }); // → 'p-surface' + 'surface' (alias) + 'd-surface' ``` ### `palette.json()` JSON export groups by theme name (no prefix needed): ```ts palette.json(); // → { // primary: { surface: { light: 'oklch(...)', dark: 'oklch(...)' } }, // danger: { surface: { light: 'oklch(...)', dark: 'oklch(...)' } }, // } ``` ### `palette.css()` ```ts const css = palette.css(); const stylesheet = ` :root { ${css.light} } @media (prefers-color-scheme: dark) { :root { ${css.dark} } } `; ``` `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 Control the color format with the `format` option on any export method: | Format | Output (alpha = 1) | Output (alpha < 1) | Notes | | ------------------------------------------ | ------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------- | | `'oklch'` (default for CSS-string exports) | `oklch(L C H)` | `oklch(L C H / A)` | OKLab-based LCH. Native CSS. Required for `splitHue`. | | `'rgb'` | `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. | | `'okhsl'` | `okhsl(H S% L%)` | `okhsl(H S% L% / A)` | Glaze's native format, not a CSS function. **[Tasty](https://tasty.style)-only** (`tasty()`, `token()`, `.tasty()`). | | `'okhst'` | `okhst(H S% T%)` | `okhst(H S% T% / A)` | OKHST tone axis. **[Tasty](https://tasty.style)-only** — same restriction as `okhsl`. | ```ts theme.tokens(); // 'oklch(0.965 0.0123 280)' (default) theme.tokens({ format: 'rgb' }); // 'rgb(244 240 250)' theme.tasty(); // 'oklch(0.965 0.0123 280)' (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 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](https://tasty.style) 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` on the theme/token override 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. **Dark hues:** hue vars are scheme-independent unless the theme or a color authors a [dark hue](#dark-seed-darkhue--darksaturation). When one does, the whole hue set is re-declared in the dark block (and in the Tasty dark state, gated by `modes.dark`): ```css /* glaze({ hue: 240, saturation: 18, darkHue: 200 }) */ :root { --brand-hue: 240; --accent-hue: calc(var(--brand-hue) + 20); } /* dark */ --brand-hue: 200; --accent-hue: calc(var(--brand-hue) + 20); ``` `--accent-hue` repeats verbatim on purpose: a custom property substitutes `var()` at computed-value time on the element that declares it, so it has to be re-declared to pick up the new `--brand-hue`. Colors with `mode: 'static'` are pinned to an absolute hue instead, so they don't drift with the dark seed. **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. *** ## Adaptation modes `mode` controls how a color adapts across schemes: | Mode | Behavior | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `'auto'` (default) | Full adaptation. Dark uses **dark tone inversion** (`100 − t`) and then remaps into the dark tone window. High-contrast uses the full range. | | `'fixed'` | Color stays recognizable. Tone is *mapped* (not inverted) into the dark window. Use for brand buttons, CTAs, status banners. | | `'static'` | No adaptation. Same tone in every scheme. | ### How relative tone adapts **`auto`** — the offset is anchored to the base's per-scheme tone: ``` Light: surface tone=97, text tone='-52' → tone 45 (dark text on light bg) Dark: surface inverts to a low tone; the '-52' offset re-anchors to the base's light tone and maps into the dark window (light text on dark bg) ``` **`fixed`** — tone is mapped (not inverted), relative sign preserved: ``` Light: accent-fill tone=52, accent-text tone='+20' → lighter than the fill Dark: accent-fill maps into the dark window, sign preserved ``` Offsets that would push past `[0, 100]` clamp to the boundary, or — with `autoFlip` (default on) — mirror to the other side of the base. If the mirror also overshoots, the original side is kept and clamped. Set `autoFlip: false` to keep the authored side and clamp instead. **`static`** — no adaptation, same tone in every scheme. *** ## Light / dark scheme mapping The mapping is a single tone pipeline; there is no Möbius curve. See [Scheme adaptation](/okhst#scheme-adaptation) for the product-level model and the [canonical OKHST specification](https://github.com/tenphi/okhst) for the transfer math. ### Light scheme An authored tone (0–100) is remapped into the `lightTone` **tone window**. The window's `lo`/`hi` are OKHSL-lightness boundaries (0–100); authored tone is positioned within the corresponding tone interval and converted to final OKHSL lightness. `static` mode and HC variants use the full range. ``` window = lightTone // default [10, 100] finalTone = remap(authorTone, window) finalL = fromTone(finalTone) // OKHSL lightness ``` ### Dark scheme **`auto`** — invert the tone, then remap into the dark window: ``` window = darkTone // default [15, 95] inverted = 100 - authorTone finalTone = remap(inverted, window) ``` The inversion preserves authored tone spacing without a fitted curve. This is exactly contrast-even for neutrals and approximate for chromatic colors. The ordinary light/dark asymmetry lives in the two windows' `(lo, hi, eps)` values (`eps` defaults to the reference `0.05`). **`fixed`** — remap into the dark window without inversion: ``` finalTone = remap(authorTone, darkTone) ``` In high-contrast variants both windows are bypassed (forced to the full `[0, 100]` range): `auto` still inverts, `fixed`/`static` do not. ### Dark scheme — saturation `darkDesaturation` reduces saturation for all colors in dark scheme: ```ts S_dark = S_light * (1 - darkDesaturation); // default: 0.1 ``` `static` mode skips desaturation. *** ## Configuration ```ts glaze.configure({ lightTone: [10, 100], // [lo, hi]; or { lo, hi, eps } / false to disable clamping darkTone: [15, 95], // [lo, hi]; or { lo, hi, eps } / false to disable clamping darkDesaturation: 0.1, states: { dark: '@media(prefers-color-scheme: dark)', highContrast: '@media(prefers-contrast: more)', }, modes: { dark: true, highContrast: false, }, shadowTuning: { alphaMax: 0.6, bgHueBlend: 0.2, }, contrastLevel: 'auto', // or 0–100 for a manual contrast slider }); ``` A `ToneWindow` is `[lo, hi]` (OKHSL-lightness boundaries, reference eps — the common form), `{ lo, hi, eps }` (advanced: explicit per-scheme render eps), or `false` for the full range `[0, 100]` at the reference eps. `false` removes the boundaries, not the tone transfer. `GlazeConfig`: | Field | Default | Description | | --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lightTone` | `[10, 100]` | Light scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC; widened continuously by [`contrastLevel`](#manual-contrast-level). | | `darkTone` | `[15, 95]` | Dark scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC; widened continuously by [`contrastLevel`](#manual-contrast-level). | | `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). | | `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. 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`, 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 | | ------------------------- | ----------------------------------------------------------------------------------- | | `glaze.configure(config)` | Merge into the global config. Bumps a config version that invalidates theme caches. | | `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](#clearing-it-exporting-it-base-links)). *** ## Output modes Control which scheme variants appear in `tokens()` / `tasty()` / `json()` exports: ```ts // Light only palette.tokens({ modes: { dark: false, highContrast: false } }); // Light + dark (default) palette.tokens({ modes: { highContrast: false } }); // All four variants palette.tokens({ modes: { dark: true, highContrast: true } }); // → { light, dark, lightContrast, darkContrast } ``` Resolution priority (highest first): 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 }`. *** ## Validation Invalid definitions throw before resolution when Glaze cannot produce a well-defined dependency graph. Recoverable numeric bounds are clamped. A physically unreachable contrast floor or a potentially misleading contrast/opacity combination emits `console.warn` and returns the closest available result. | Condition | Behavior | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `contrast` without `base` in a **theme** color | Validation error | | `contrast` pair switching metric (`[4.5, { apca: 75 }]`) | Validation error — a WCAG ratio and an APCA Lc are different scales | | Relative `tone` without `base` in a **theme** color | Validation error | | `contrast` without `base` in `glaze.color()` | Anchors against the literal seed (no error) | | Relative `tone` without `base` in `glaze.color()` | Anchors against the literal seed (no error) | | Relative `tone` overshoots `[0, 100]` | Mirror to the other side of the base (`autoFlip` on, default), or clamp to the boundary (`autoFlip` off). If the mirror also overshoots, clamp on the authored side. | | `tone` resolves outside 0–100 | Clamp silently | | `'max'` / `'min'` without `base` | Allowed — resolves to the scheme's tone extreme (root color) | | `saturation` outside 0–1 | Clamp silently | | Circular `base` references | Validation error | | `base` references non-existent name | Validation error | | Shadow `bg` references non-existent color | Validation error | | Shadow `fg` references non-existent color | Validation error | | Shadow `bg` references another shadow color | Validation error | | Shadow `fg` references another shadow color | Validation error | | Regular color `base` references a shadow color | Validation error | | Shadow `intensity` outside 0–100 | Clamp silently | | `contrast` + `opacity` combined | `console.warn` | | Mix `base` references non-existent color | Validation error | | Mix `target` references non-existent color | Validation error | | Mix `base` references a shadow color | Validation error | | Mix `target` references a shadow color | Validation error | | Mix `value` outside 0–100 | Clamp silently | | Circular references involving mix colors | Validation error | | Contrast target physically unreachable | `console.warn` (deduped per `(name, scheme, target)`); closest passing variant returned | *** ## Color math utilities For advanced use, Glaze re-exports its internal color math. ### Conversions ```ts import { okhslToLinearSrgb, okhslToSrgb, okhslToOklab, oklabToOkhsl, srgbToOkhsl, hslToSrgb, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, contrastRatioFromLuminance, gamutClampedLuminance, } from '@tenphi/glaze'; ``` | Function | Description | | ------------------------------------- | ------------------------------------------------------------------------ | | `okhslToLinearSrgb(h, s, l)` | OKHSL (h: 0–360, s/l: 0–1) → linear sRGB tuple. | | `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. | | `hslToSrgb(h, s, l)` | CSS HSL → sRGB tuple. | | `parseHex(hex)` | Parse `#rgb` / `#rrggbb` to sRGB tuple. Returns `null` on invalid input. | | `parseHexAlpha(hex)` | Parse `#rgb` / `#rrggbb` / `#rrggbbaa`; returns `[r, g, b, a?]`. | | `relativeLuminanceFromLinearRgb(rgb)` | WCAG relative luminance from linear sRGB. | | `contrastRatioFromLuminance(yA, yB)` | WCAG contrast ratio from two luminances. | | `gamutClampedLuminance(linearRgb)` | Relative luminance with channel clamping for out-of-gamut colors. | ### 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, formatOkhst, formatRgb, formatHsl, formatOklch, } from '@tenphi/glaze'; 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 ```ts import { toTone, fromTone, toneFromY, yFromTone, okhstToOkhsl, okhslToOkhst, variantToOkhsl, REF_EPS, } from '@tenphi/glaze'; ``` | Function | Description | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `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 }` 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 `variantToOkhsl(variant).l` to recover OKHSL lightness. See [OKHST in Glaze](/okhst) for the model. ### Contrast solver ```ts import { findToneForContrast, findValueForMixContrast, resolveContrastForMode, resolveContrastForLevel, resolveMinContrast, apcaContrast, } from '@tenphi/glaze'; ``` | Function | Description | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `findToneForContrast(opts)` | Binary-search for the tone (0–1) that meets a contrast floor (WCAG or APCA) against a base color. Returns `{ tone, contrast, met, branch, flipped? }`. | | `findValueForMixContrast(opts)` | Same, but searches for a mix `value` (0–1) that meets a contrast floor between a base and a target. | | `resolveContrastForMode(spec, isHC, polarity?, outerExplicitHC?)` | Resolves a `ContrastSpec` to `{ metric: 'wcag' \| 'apca', target }` for the requested mode (picks the normal or HC entry of any pair). In HC, applies the metric's auto-enhancement unless `outerExplicitHC` is set or the inner metric pair carries an explicit HC value: APCA +15 Lc (clamped to 106); WCAG AA → AAA / AA-large → AAA-large (AAA-family and bare numbers unchanged). | | `resolveContrastForLevel(spec, level, polarity?)` | Resolves a `ContrastSpec` — including its outer `[normal, highContrast]` pair — at a [manual contrast level](#manual-contrast-level) (0–100), interpolating the two numeric targets. Levels 0 / 100 delegate verbatim to `resolveContrastForMode`; a WCAG-vs-APCA metric switch across the pair has no midpoint and switches at 50. | | `resolveMinContrast(value)` | Resolves a `MinContrast` (WCAG preset or number) to a numeric ratio. | | `apcaContrast(yText, yBg)` | APCA Lc magnitude (0–106) for two relative luminances. | Exported constants: `APCA_PRESETS`, `APCA_HC_ENHANCEMENT` (`15`, the Enhanced Level delta), `APCA_MAX_LC` (`106`). `findToneForContrast` options: | Option | Default | Description | | ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hue` | — | Candidate hue (0–360). | | `saturation` | — | Candidate saturation (0–1). | | `preferredTone` | — | Preferred candidate tone (0–1). Kept if it already meets the target. | | `baseLinearRgb` | — | Base color as linear sRGB tuple. | | `contrast` | — | `ResolvedContrast` (`{ metric, target }`). | | `toneRange` | `[0, 1]` | Search bounds in tone. | | `epsilon` | `1e-4` | Convergence threshold. | | `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 (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.