@tenphi/glaze 0.0.0-snapshot.7f7cab2 → 0.0.0-snapshot.875bb2f
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -1094
- package/dist/index.cjs +3145 -939
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1163 -104
- package/dist/index.d.mts +1163 -104
- package/dist/index.mjs +3114 -939
- package/dist/index.mjs.map +1 -1
- package/docs/api.md +1679 -0
- package/docs/methodology.md +636 -0
- package/docs/migration.md +315 -0
- package/docs/okhst.md +170 -0
- package/package.json +9 -9
package/docs/api.md
ADDED
|
@@ -0,0 +1,1679 @@
|
|
|
1
|
+
# API Reference
|
|
2
|
+
|
|
3
|
+
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.md) for a guided walkthrough of how to use these primitives to build a real palette.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- [Theme creation](#theme-creation)
|
|
8
|
+
- [Theme methods](#theme-methods)
|
|
9
|
+
- [DTCG](#themedtcgoptions)
|
|
10
|
+
- [DTCG Resolver-Module](#themedtcgresolveroptions)
|
|
11
|
+
- [Tailwind CSS](#themetailwindoptions)
|
|
12
|
+
- [High-contrast pairs](#high-contrast-pairs)
|
|
13
|
+
- [Color definitions](#color-definitions)
|
|
14
|
+
- [Standalone color tokens](#standalone-color-tokens)
|
|
15
|
+
- [Shadows](#shadows)
|
|
16
|
+
- [Mix colors](#mix-colors)
|
|
17
|
+
- [Palette](#palette)
|
|
18
|
+
- [Output formats](#output-formats)
|
|
19
|
+
- [Hue channel splitting](#hue-channel-splitting-splithue)
|
|
20
|
+
- [Adaptation modes](#adaptation-modes)
|
|
21
|
+
- [Light / dark scheme mapping](#light--dark-scheme-mapping)
|
|
22
|
+
- [Configuration](#configuration)
|
|
23
|
+
- [Output modes](#output-modes)
|
|
24
|
+
- [Validation](#validation)
|
|
25
|
+
- [Color math utilities](#color-math-utilities)
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Theme creation
|
|
30
|
+
|
|
31
|
+
| Method | Description |
|
|
32
|
+
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| `glaze(hue, saturation?, config?)` | Create a theme from hue (0–360) and saturation (0–100). Optional `config` overrides the global config for this theme. |
|
|
34
|
+
| `glaze({ hue, saturation }, config?)` | Create a theme from an options object, with optional per-theme config override. |
|
|
35
|
+
| `glaze.themeFrom(data)` | Create a theme from a `theme.export()` snapshot (`kind: 'theme'`). |
|
|
36
|
+
| `glaze.from(data)` | Compat alias for `glaze.themeFrom`. |
|
|
37
|
+
| `glaze.fromHex(hex)` | Create a theme from a hex color (`#rgb` or `#rrggbb`). Extracts hue and saturation. |
|
|
38
|
+
| `glaze.fromRgb(r, g, b)` | Create a theme from RGB values (0–255). Extracts hue and saturation. |
|
|
39
|
+
| `glaze.paletteFrom(data)` | Create a palette from a `palette.export()` snapshot (`kind: 'palette'`). |
|
|
40
|
+
| `glaze.colorFrom(data)` | Create a color token from a `token.export()` snapshot (`kind: 'color'`). |
|
|
41
|
+
| `glaze.isThemeExport(data)` | Type guard for theme authoring snapshots. |
|
|
42
|
+
| `glaze.isColorTokenExport(data)` | Type guard for color-token authoring snapshots. |
|
|
43
|
+
| `glaze.isPaletteExport(data)` | Type guard for palette authoring snapshots. |
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
const a = glaze(280, 80);
|
|
47
|
+
const b = glaze({ hue: 280, saturation: 80 });
|
|
48
|
+
const c = glaze.fromHex('#7a4dbf');
|
|
49
|
+
const d = glaze.fromRgb(122, 77, 191);
|
|
50
|
+
const e = glaze.themeFrom(a.export());
|
|
51
|
+
|
|
52
|
+
// Per-theme config override:
|
|
53
|
+
const rawTheme = glaze(280, 80, { lightTone: false, darkTone: false });
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Authoring restore triad (parallel to `.export()` on each instance):
|
|
57
|
+
|
|
58
|
+
| Export | Restore |
|
|
59
|
+
| ------ | ------- |
|
|
60
|
+
| `theme.export()` | `glaze.themeFrom()` |
|
|
61
|
+
| `token.export()` | `glaze.colorFrom()` |
|
|
62
|
+
| `palette.export()` | `glaze.paletteFrom()` |
|
|
63
|
+
|
|
64
|
+
Every snapshot includes `kind` + `version` (`GLAZE_EXPORT_VERSION`, currently `1`). Legacy snapshots without those fields still restore. Wrong `kind` or a future `version` throws.
|
|
65
|
+
|
|
66
|
+
The optional `config` parameter is a `GlazeConfigOverride` — see [Per-instance config override](#per-instance-config-override).
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Theme methods
|
|
71
|
+
|
|
72
|
+
A `GlazeTheme` exposes:
|
|
73
|
+
|
|
74
|
+
| Method | Description |
|
|
75
|
+
| ------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
76
|
+
| `theme.hue` (readonly) | The hue seed (0–360). |
|
|
77
|
+
| `theme.saturation` (readonly) | The saturation seed (0–100). |
|
|
78
|
+
| `theme.colors(defs)` | Add/replace colors (additive merge — adds new, overwrites existing by name, doesn't remove others). |
|
|
79
|
+
| `theme.color(name)` | Get a color definition by name. |
|
|
80
|
+
| `theme.color(name, def)` | Set a single color definition. |
|
|
81
|
+
| `theme.remove(name \| names[])` | Remove one or more color definitions. |
|
|
82
|
+
| `theme.has(name)` | Check if a color is defined. |
|
|
83
|
+
| `theme.list()` | List all defined color names. |
|
|
84
|
+
| `theme.reset()` | Clear all color definitions. |
|
|
85
|
+
| `theme.export()` | Export the theme configuration as a JSON-safe object. |
|
|
86
|
+
| `theme.extend(options)` | Create a child theme inheriting all color definitions (see [`extend`](#themeextendoptions) below). |
|
|
87
|
+
| `theme.resolve()` | Resolve all colors and return a `Map<string, ResolvedColor>`. |
|
|
88
|
+
| `theme.tokens(options?)` | Export as a flat token map grouped by scheme variant. |
|
|
89
|
+
| `theme.tasty(options?)` | Export as [Tasty](https://tasty.style) style-to-state bindings. |
|
|
90
|
+
| `theme.json(options?)` | Export as plain JSON. |
|
|
91
|
+
| `theme.css(options?)` | Export as CSS custom property declarations. |
|
|
92
|
+
| `theme.dtcg(options?)` | Export one W3C DTCG token tree per scheme. |
|
|
93
|
+
| `theme.dtcgResolver(options?)` | Export one DTCG Resolver-Module document containing every scheme. |
|
|
94
|
+
| `theme.tailwind(options?)` | Export a Tailwind CSS v4 theme and scheme overrides. |
|
|
95
|
+
|
|
96
|
+
### `theme.colors(defs)`
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
theme.colors({ surface: { tone: 97 } });
|
|
100
|
+
theme.colors({ text: { tone: 30 } });
|
|
101
|
+
// Both 'surface' and 'text' are now defined.
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### `theme.color(name) / theme.color(name, def)`
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
theme.color('surface', { tone: 97, saturation: 0.75 }); // set
|
|
108
|
+
const def = theme.color('surface'); // get
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### `theme.extend(options)`
|
|
112
|
+
|
|
113
|
+
Creates a new theme inheriting all color definitions, optionally replacing the hue / saturation seed, color overrides, and config:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
const danger = primary.extend({
|
|
117
|
+
hue: 23,
|
|
118
|
+
colors: { 'accent-fill': { tone: 48, mode: 'fixed' } },
|
|
119
|
+
});
|
|
120
|
+
|
|
121
|
+
// Inherit parent's config override and widen the dark window further:
|
|
122
|
+
const highSat = base.extend({ config: { darkTone: [10, 100] } });
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`GlazeExtendOptions`:
|
|
126
|
+
|
|
127
|
+
| Field | Type | Description |
|
|
128
|
+
| ------------ | --------------------- | -------------------------------------------------------------------------------------------- |
|
|
129
|
+
| `hue` | `number` | Replace the hue seed. Defaults to the parent's hue. |
|
|
130
|
+
| `saturation` | `number` | Replace the saturation seed. Defaults to the parent's saturation. |
|
|
131
|
+
| `colors` | `ColorMap` | Per-theme overrides (additive merge over the inherited map). |
|
|
132
|
+
| `config` | `GlazeConfigOverride` | Config override for the child. Shallow-merged with the parent's override — child fields win. |
|
|
133
|
+
|
|
134
|
+
Colors marked with `inherit: false` on the parent are **not** copied into the child.
|
|
135
|
+
|
|
136
|
+
### `theme.resolve()`
|
|
137
|
+
|
|
138
|
+
Resolves the dependency graph and returns a
|
|
139
|
+
`Map<string, ResolvedColor>`. Export methods call it automatically; use it
|
|
140
|
+
directly for tests, diagnostics, or a custom output pipeline.
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
const resolved = theme.resolve();
|
|
144
|
+
const surface = resolved.get('surface');
|
|
145
|
+
// surface?.light.t is canonical tone on 0–1.
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### `theme.tokens(options?)`
|
|
149
|
+
|
|
150
|
+
Flat token map grouped by scheme variant.
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
theme.tokens();
|
|
154
|
+
// → { light: { surface: 'oklch(...)' }, dark: { surface: 'oklch(...)' } }
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`GlazeJsonOptions`:
|
|
158
|
+
|
|
159
|
+
| Option | Default | Description |
|
|
160
|
+
| -------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
161
|
+
| `format` | `'oklch'` | Output color format. One of `'rgb' \| 'hsl' \| 'oklch'`. `'okhsl'` and `'okhst'` throw — use `tasty()` for those. |
|
|
162
|
+
| `modes` | `{ dark: true, highContrast: false }` (or global config) | Which scheme variants to include. |
|
|
163
|
+
|
|
164
|
+
### `theme.tasty(options?)`
|
|
165
|
+
|
|
166
|
+
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.
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
theme.tasty();
|
|
170
|
+
// → {
|
|
171
|
+
// '#surface': { '': 'oklch(...)', '@media(prefers-color-scheme: dark)': 'oklch(...)' },
|
|
172
|
+
// ...
|
|
173
|
+
// }
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
`GlazeTokenOptions`:
|
|
177
|
+
|
|
178
|
+
| Option | Default | Description |
|
|
179
|
+
| --------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
180
|
+
| `format` | `'oklch'` | Output color format. `'okhsl'` and `'okhst'` are also supported here ([Tasty](https://tasty.style)-only spaces). |
|
|
181
|
+
| `modes` | global config | Which scheme variants to include. |
|
|
182
|
+
| `states.dark` | `'@media(prefers-color-scheme: dark)'` (or global config) | State alias for dark mode tokens. |
|
|
183
|
+
| `states.highContrast` | `'@media(prefers-contrast: more)'` (or global config) | State alias for high-contrast tokens. |
|
|
184
|
+
| `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. |
|
|
185
|
+
| `name` | `'theme'` | Base name for the theme-level hue var (`$theme-hue` / `--theme-hue`). Palette export auto-derives this from the theme name. |
|
|
186
|
+
| `prefix` | (palette only) | See [Palette](#palette). |
|
|
187
|
+
|
|
188
|
+
When both `dark` and `highContrast` modes are enabled, dark high-contrast variants are emitted under the combined key `<dark> & <highContrast>` (e.g. `'@media(prefers-color-scheme: dark) & @media(prefers-contrast: more)'`).
|
|
189
|
+
|
|
190
|
+
### `theme.json(options?)`
|
|
191
|
+
|
|
192
|
+
Per-color JSON map.
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
theme.json();
|
|
196
|
+
// → {
|
|
197
|
+
// surface: { light: 'oklch(...)', dark: 'oklch(...)' },
|
|
198
|
+
// text: { light: 'oklch(...)', dark: 'oklch(...)' },
|
|
199
|
+
// }
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Same options as `tokens()`.
|
|
203
|
+
|
|
204
|
+
### `theme.css(options?)`
|
|
205
|
+
|
|
206
|
+
CSS custom property declaration strings, grouped by scheme variant.
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
theme.css();
|
|
210
|
+
// → {
|
|
211
|
+
// light: '--surface-color: oklch(...);\n--text-color: oklch(...);',
|
|
212
|
+
// dark: '--surface-color: oklch(...);\n--text-color: oklch(...);',
|
|
213
|
+
// lightContrast: '...',
|
|
214
|
+
// darkContrast: '...',
|
|
215
|
+
// }
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`GlazeCssOptions`:
|
|
219
|
+
|
|
220
|
+
| Option | Default | Description |
|
|
221
|
+
| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
|
+
| `format` | `'oklch'` | Output color format. One of `'rgb' \| 'hsl' \| 'oklch'`. `'okhsl'` and `'okhst'` throw — use `tasty()` for those. |
|
|
223
|
+
| `suffix` | `'-color'` | Suffix appended to each CSS property name. Pass `''` for bare property names. |
|
|
224
|
+
| `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). |
|
|
225
|
+
| `name` | `'theme'` | Base name for the theme-level hue var (`--theme-hue`). Palette export auto-derives this from the theme name. |
|
|
226
|
+
|
|
227
|
+
`GlazeCssResult` always contains all four keys (`light`, `dark`, `lightContrast`, `darkContrast`); empty if no colors are defined for that variant.
|
|
228
|
+
|
|
229
|
+
### `theme.dtcg(options?)`
|
|
230
|
+
|
|
231
|
+
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.
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
theme.dtcg();
|
|
235
|
+
// → {
|
|
236
|
+
// light: {
|
|
237
|
+
// surface: {
|
|
238
|
+
// $type: 'color',
|
|
239
|
+
// $value: { colorSpace: 'srgb', components: [0.96, 0.94, 0.98], hex: '#f5f0fa' },
|
|
240
|
+
// },
|
|
241
|
+
// },
|
|
242
|
+
// dark: {
|
|
243
|
+
// surface: {
|
|
244
|
+
// $type: 'color',
|
|
245
|
+
// $value: { colorSpace: 'srgb', components: [0.16, 0.14, 0.2], hex: '#292333' },
|
|
246
|
+
// },
|
|
247
|
+
// },
|
|
248
|
+
// }
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
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).
|
|
252
|
+
|
|
253
|
+
`GlazeDtcgOptions`:
|
|
254
|
+
|
|
255
|
+
| Option | Default | Description |
|
|
256
|
+
| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
257
|
+
| `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. |
|
|
258
|
+
| `modes` | global config | Which scheme variants to include. `light` is always present. |
|
|
259
|
+
|
|
260
|
+
`alpha` is included on `$value` only when the color's opacity is below 1. `$type` is always `'color'`.
|
|
261
|
+
|
|
262
|
+
### `theme.dtcgResolver(options?)`
|
|
263
|
+
|
|
264
|
+
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.
|
|
265
|
+
|
|
266
|
+
```ts
|
|
267
|
+
theme.dtcgResolver({ modes: { highContrast: true } });
|
|
268
|
+
// → {
|
|
269
|
+
// version: '2025.10',
|
|
270
|
+
// sets: {
|
|
271
|
+
// base: {
|
|
272
|
+
// sources: [
|
|
273
|
+
// {
|
|
274
|
+
// surface: {
|
|
275
|
+
// $type: 'color',
|
|
276
|
+
// $value: { colorSpace: 'srgb', components: [0.96, 0.94, 0.98], hex: '#f5f0fa' },
|
|
277
|
+
// },
|
|
278
|
+
// },
|
|
279
|
+
// ],
|
|
280
|
+
// },
|
|
281
|
+
// },
|
|
282
|
+
// modifiers: {
|
|
283
|
+
// scheme: {
|
|
284
|
+
// default: 'light',
|
|
285
|
+
// contexts: {
|
|
286
|
+
// light: [],
|
|
287
|
+
// dark: [
|
|
288
|
+
// {
|
|
289
|
+
// surface: {
|
|
290
|
+
// $type: 'color',
|
|
291
|
+
// $value: { colorSpace: 'srgb', components: [0.16, 0.14, 0.2], hex: '#292333' },
|
|
292
|
+
// },
|
|
293
|
+
// },
|
|
294
|
+
// ],
|
|
295
|
+
// lightContrast: [ /* … */ ],
|
|
296
|
+
// darkContrast: [ /* … */ ],
|
|
297
|
+
// },
|
|
298
|
+
// },
|
|
299
|
+
// },
|
|
300
|
+
// resolutionOrder: [
|
|
301
|
+
// { $ref: '#/sets/base' },
|
|
302
|
+
// { $ref: '#/modifiers/scheme' },
|
|
303
|
+
// ],
|
|
304
|
+
// }
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
**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.
|
|
308
|
+
|
|
309
|
+
`GlazeDtcgResolverOptions` (extends `GlazeDtcgOptions`, so `modes` and `colorSpace` pass through):
|
|
310
|
+
|
|
311
|
+
| Option | Default | Description |
|
|
312
|
+
| -------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
313
|
+
| `colorSpace` | `'srgb'` | Same as `dtcg()` — flows through to every source and context. |
|
|
314
|
+
| `modes` | global config | Which scheme variants to emit as contexts. `light` is always present (the default); absent variants are omitted. |
|
|
315
|
+
| `setName` | `'base'` | Name of the single set holding the default (light) token tree. |
|
|
316
|
+
| `modifierName` | `'scheme'` | Name of the modifier describing the scheme axis. |
|
|
317
|
+
| `contextNames` | identity | Override the four context names (`light` / `dark` / `lightContrast` / `darkContrast`) — e.g. `{ dark: 'night' }`. |
|
|
318
|
+
| `version` | `'2025.10'` | Resolver document version. |
|
|
319
|
+
|
|
320
|
+
### `theme.tailwind(options?)`
|
|
321
|
+
|
|
322
|
+
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.
|
|
323
|
+
|
|
324
|
+
```css
|
|
325
|
+
@theme {
|
|
326
|
+
--color-surface: oklch(0.96 0.01 280);
|
|
327
|
+
--color-text: oklch(0.3 0.05 280);
|
|
328
|
+
}
|
|
329
|
+
.dark {
|
|
330
|
+
--color-surface: oklch(0.16 0.01 280);
|
|
331
|
+
--color-text: oklch(0.85 0.05 280);
|
|
332
|
+
}
|
|
333
|
+
.high-contrast {
|
|
334
|
+
--color-surface: oklch(0.98 0.01 280);
|
|
335
|
+
--color-text: oklch(0.1 0.05 280);
|
|
336
|
+
}
|
|
337
|
+
.dark.high-contrast {
|
|
338
|
+
--color-surface: oklch(0.05 0.01 280);
|
|
339
|
+
--color-text: oklch(0.95 0.05 280);
|
|
340
|
+
}
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
`GlazeTailwindOptions`:
|
|
344
|
+
|
|
345
|
+
| Option | Default | Description |
|
|
346
|
+
| ---------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
347
|
+
| `format` | `'oklch'` | Output color format for the values. |
|
|
348
|
+
| `namespace` | `'color-'` | CSS custom property namespace, forming `--<namespace><name>` (e.g. `--color-surface`). Named `namespace` to avoid clashing with the palette theme-prefix option. |
|
|
349
|
+
| `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). |
|
|
350
|
+
| `highContrastSelector` | `'.high-contrast'` | Selector wrapping the light high-contrast overrides. The combined dark + high-contrast block uses `${darkSelector}${highContrastSelector}` (e.g. `.dark.high-contrast`). |
|
|
351
|
+
| `modes` | global config | Which scheme variants to include. The `@theme` block (light) is always emitted when colors exist. |
|
|
352
|
+
|
|
353
|
+
### `theme.export()`
|
|
354
|
+
|
|
355
|
+
```ts
|
|
356
|
+
const snapshot = theme.export();
|
|
357
|
+
// → {
|
|
358
|
+
// kind: 'theme',
|
|
359
|
+
// version: 1,
|
|
360
|
+
// hue: 280,
|
|
361
|
+
// saturation: 80,
|
|
362
|
+
// colors: { surface: { ... }, ... },
|
|
363
|
+
// config: { lightTone: {...}, darkTone: {...}, pastel: false, ... },
|
|
364
|
+
// }
|
|
365
|
+
|
|
366
|
+
const restored = glaze.themeFrom(snapshot);
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
Returns a deep-cloned, JSON-safe authoring snapshot (definitions + frozen
|
|
370
|
+
effective config — not resolved color strings). Restored themes ignore later
|
|
371
|
+
`glaze.configure()` for snapshotted fields. Distinct from `theme.json()`, which
|
|
372
|
+
emits resolved color strings.
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
## High-contrast pairs
|
|
377
|
+
|
|
378
|
+
`HCPair<T>` means either one value used in both ordinary and high-contrast
|
|
379
|
+
schemes, or an explicit `[normal, highContrast]` pair:
|
|
380
|
+
|
|
381
|
+
```ts
|
|
382
|
+
type HCPair<T> = T | [T, T];
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
It is used by `tone`, `contrast`, shadow `intensity`, and mix `value`:
|
|
386
|
+
|
|
387
|
+
```ts
|
|
388
|
+
tone: '-8'; // -8 in normal and HC
|
|
389
|
+
tone: ['-8', '-16']; // -8 normal, -16 HC
|
|
390
|
+
contrast: {
|
|
391
|
+
apca: 'content';
|
|
392
|
+
} // preset with automatic HC enhancement
|
|
393
|
+
contrast: {
|
|
394
|
+
apca: ['content', 'body'];
|
|
395
|
+
} // explicit normal/HC targets
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
For `contrast`, the pair may wrap the whole spec or live inside the selected
|
|
399
|
+
metric. An explicit HC value disables automatic APCA enhancement or WCAG preset
|
|
400
|
+
promotion for that color.
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## Color definitions
|
|
405
|
+
|
|
406
|
+
`ColorDef` is a discriminated union:
|
|
407
|
+
|
|
408
|
+
```ts
|
|
409
|
+
type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
### `RegularColorDef`
|
|
413
|
+
|
|
414
|
+
| Field | Type | Description |
|
|
415
|
+
| ------------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
416
|
+
| `tone` | `HCPair<ToneValue>` | Number = absolute (0–100). `'+N'`/`'-N'` = a signed **tone delta** from the base (requires `base`). `'max'`/`'min'` = forced to the scheme's tone extreme (no `base`). Optional HC pair `[normal, hc]`. |
|
|
417
|
+
| `saturation` | `number` | Saturation factor applied to the seed saturation (0–1). Default: `1`. |
|
|
418
|
+
| `hue` | `number \| RelativeValue` | Number = absolute (0–360). String (`'+N'`/`'-N'`) = relative to the **theme seed hue** (never to a base color). |
|
|
419
|
+
| `base` | `string` | Name of another color in the same theme — makes this a _dependent_ color. |
|
|
420
|
+
| `contrast` | `HCPair<ContrastSpec>` | Contrast floor against `base`. Requires `base`. See [`contrast`](#contrast-floor). |
|
|
421
|
+
| `mode` | `'auto' \| 'fixed' \| 'static'` | Adaptation mode. Default: `'auto'`. See [Adaptation modes](#adaptation-modes). |
|
|
422
|
+
| `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). |
|
|
423
|
+
| `opacity` | `number` | Fixed alpha 0–1. Output includes alpha in the CSS value. Combining with `contrast` is not recommended (a `console.warn` is emitted). |
|
|
424
|
+
| `pastel` | `boolean` | Per-color override for the hue-independent "safe" chroma limit used in OKHSL↔sRGB conversions (luminance, contrast solving, output formatting). Falls through to the global / per-theme `pastel` config when omitted. Default: unset. See [Per-color `pastel`](#per-color-pastel). |
|
|
425
|
+
| `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). |
|
|
426
|
+
| `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. |
|
|
427
|
+
|
|
428
|
+
#### Tone values
|
|
429
|
+
|
|
430
|
+
`tone` (0–100) replaces authored OKHSL lightness with a contrast-shaped axis.
|
|
431
|
+
Equal tone differences give equal WCAG contrast for neutrals; chromatic results
|
|
432
|
+
can drift in measured luminance. See [OKHST in Glaze](okhst.md). To port old
|
|
433
|
+
`lightness` values, see [migration.md](migration.md).
|
|
434
|
+
|
|
435
|
+
| Form | Example | Meaning |
|
|
436
|
+
| ------------------- | ----------------------- | --------------------------------------------------------------------------------------------- |
|
|
437
|
+
| Number (absolute) | `tone: 45` | Absolute tone 0–100. |
|
|
438
|
+
| String (tone delta) | `tone: '-52'` | Signed difference from the base color's resolved tone (requires `base`). |
|
|
439
|
+
| Extreme | `tone: 'max'` / `'min'` | Force to the scheme's highest (`'max'` = 100) or lowest (`'min'` = 0) tone. No `base` needed. |
|
|
440
|
+
| HC pair | `tone: ['-7', '-20']` | `[normal, high-contrast]`. A single value applies to both. |
|
|
441
|
+
|
|
442
|
+
**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.
|
|
443
|
+
|
|
444
|
+
**A tone delta** applies a signed difference to the base color's resolved tone.
|
|
445
|
+
It gives an exact contrast step for neutrals and a stable visual progression for
|
|
446
|
+
chromatic colors. In dark mode with `mode: 'auto'`, it is anchored to the
|
|
447
|
+
base's per-scheme tone. If `base + delta` falls outside `[0, 100]`, the result
|
|
448
|
+
is clamped to the boundary, or — with `autoFlip` (default on) — mirrored to the
|
|
449
|
+
other side of the base.
|
|
450
|
+
|
|
451
|
+
**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; 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.
|
|
452
|
+
|
|
453
|
+
A dependent color with `base` but no `tone` inherits the base's tone (equivalent to a delta of 0).
|
|
454
|
+
|
|
455
|
+
#### `autoFlip`
|
|
456
|
+
|
|
457
|
+
`autoFlip` governs what happens when a result would fall outside its valid range:
|
|
458
|
+
|
|
459
|
+
- **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.
|
|
460
|
+
- **`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`).
|
|
461
|
+
|
|
462
|
+
`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.
|
|
463
|
+
|
|
464
|
+
#### `contrast` (floor)
|
|
465
|
+
|
|
466
|
+
```ts
|
|
467
|
+
type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
|
|
468
|
+
type ContrastSpec =
|
|
469
|
+
| number // bare WCAG ratio
|
|
470
|
+
| ContrastPreset // named WCAG preset
|
|
471
|
+
| { wcag: HCPair<number | ContrastPreset> }
|
|
472
|
+
| { apca: HCPair<number> }; // APCA Lc target
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
| Preset | WCAG ratio |
|
|
476
|
+
| ------------- | ---------- |
|
|
477
|
+
| `'AA-large'` | 3 |
|
|
478
|
+
| `'AA'` | 4.5 |
|
|
479
|
+
| `'AAA-large'` | 4.5 |
|
|
480
|
+
| `'AAA'` | 7 |
|
|
481
|
+
|
|
482
|
+
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] }`).
|
|
483
|
+
|
|
484
|
+
```ts
|
|
485
|
+
contrast: 4.5; // WCAG 4.5
|
|
486
|
+
contrast: 'AAA'; // WCAG 7
|
|
487
|
+
contrast: {
|
|
488
|
+
wcag: 6;
|
|
489
|
+
} // WCAG 6
|
|
490
|
+
contrast: {
|
|
491
|
+
wcag: [4.5, 7];
|
|
492
|
+
} // WCAG 4.5 normal / 7 high-contrast (explicit)
|
|
493
|
+
contrast: {
|
|
494
|
+
apca: 60;
|
|
495
|
+
} // APCA Lc 60 normal / 75 high-contrast (auto)
|
|
496
|
+
contrast: {
|
|
497
|
+
apca: [45, 60];
|
|
498
|
+
} // APCA Lc 45 normal / 60 high-contrast (explicit)
|
|
499
|
+
contrast: {
|
|
500
|
+
apca: 'content';
|
|
501
|
+
} // APCA preset -> Lc 60 normal / 75 high-contrast (auto)
|
|
502
|
+
contrast: {
|
|
503
|
+
apca: ['content', 'body'];
|
|
504
|
+
} // Lc 60 normal / 75 high-contrast (explicit)
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
**WCAG HC auto-promotion:** a bare WCAG preset (no `[normal, hc]` pair at either
|
|
508
|
+
the outer `contrast` or inner `wcag` level) is automatically promoted to its
|
|
509
|
+
spec-defined "Enhanced" successor in high-contrast mode — `AA` → `AAA` (4.5 → 7)
|
|
510
|
+
and `AA-large` → `AAA-large` (3 → 4.5), per WCAG SC 1.4.3 → 1.4.6. `AAA` and
|
|
511
|
+
`AAA-large` are already the top WCAG tier and are left unchanged; bare numeric
|
|
512
|
+
targets have no successor tier and are also left unchanged. An explicit HC value
|
|
513
|
+
via either pair overrides and skips the promotion.
|
|
514
|
+
|
|
515
|
+
**APCA Enhanced Level (HC auto-boost):** a bare APCA scalar (no `[normal, hc]`
|
|
516
|
+
pair at either the outer `contrast` or inner `apca` level) is automatically
|
|
517
|
+
boosted by **+15 Lc** in high-contrast mode, the APCA analog of WCAG's
|
|
518
|
+
AAA-over-AA step. On by default; an explicit HC value via either pair
|
|
519
|
+
overrides it and skips the boost. The enhanced target is clamped to 106 Lc.
|
|
520
|
+
For large/bold text (where APCA caps contrast at Lc 90 to avoid glare), pass
|
|
521
|
+
an explicit HC pair to hold that ceiling.
|
|
522
|
+
|
|
523
|
+
APCA preset keywords (Bronze Simple Mode conformance levels, role-independent):
|
|
524
|
+
`'preferred'` (Lc 90), `'body'` (75), `'content'` (60, ~AA), `'large'` (45, ~3:1),
|
|
525
|
+
`'non-text'` (30), `'min'` (15, point of invisibility).
|
|
526
|
+
|
|
527
|
+
The floor is applied independently per scheme. If the preferred `tone` already
|
|
528
|
+
satisfies it, the tone is kept; otherwise the solver uses the tone-shaped scale
|
|
529
|
+
for a closed-form WCAG seed and fast search until the target is met.
|
|
530
|
+
|
|
531
|
+
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.
|
|
532
|
+
|
|
533
|
+
**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.
|
|
534
|
+
|
|
535
|
+
**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.md#contrast-verification).
|
|
536
|
+
|
|
537
|
+
#### Per-color hue override
|
|
538
|
+
|
|
539
|
+
```ts
|
|
540
|
+
const theme = glaze(280, 80);
|
|
541
|
+
theme.colors({
|
|
542
|
+
surface: { tone: 97 },
|
|
543
|
+
gradientEnd: { tone: 90, hue: '+20' }, // 280 + 20 = 300
|
|
544
|
+
warning: { tone: 60, hue: 40 }, // absolute
|
|
545
|
+
});
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
Relative hue is always relative to the **theme seed hue**, not to a base color.
|
|
549
|
+
|
|
550
|
+
#### Per-color `pastel`
|
|
551
|
+
|
|
552
|
+
`pastel: true` on a single color def overrides the global / per-theme `pastel` config for that color only. It toggles the hue-independent "safe" chroma limit used in every OKHSL↔sRGB conversion that touches this color: luminance calculations during contrast solving, gamut clamping during sRGB blend / mix edges, and output formatting. The effective flag is carried on the resolved variant (`ResolvedColorVariant.pastel`) so formatting matches the gamut mapping applied during resolution.
|
|
553
|
+
|
|
554
|
+
```ts
|
|
555
|
+
const theme = glaze(280, 80);
|
|
556
|
+
theme.colors({
|
|
557
|
+
plain: { tone: 50, saturation: 1 },
|
|
558
|
+
soft: { tone: 50, saturation: 1, pastel: true },
|
|
559
|
+
});
|
|
560
|
+
// theme.resolve().get('soft')!.light.pastel === true
|
|
561
|
+
// theme.css().light contains different rgb() triples for `--plain` and `--soft`
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
Omit the field to inherit the global / per-theme `pastel` config — useful for keeping the default behavior while opting a single accent into the pastel gamut.
|
|
565
|
+
|
|
566
|
+
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:
|
|
567
|
+
|
|
568
|
+
```ts
|
|
569
|
+
const parent = glaze(280, 80);
|
|
570
|
+
parent.colors({ soft: { tone: 50, saturation: 1, pastel: true } });
|
|
571
|
+
|
|
572
|
+
const child = parent.extend({
|
|
573
|
+
colors: { soft: { tone: 50, saturation: 1, pastel: false } },
|
|
574
|
+
});
|
|
575
|
+
// child.resolve().get('soft')!.light.pastel === false
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
> **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.
|
|
579
|
+
>
|
|
580
|
+
> 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.
|
|
581
|
+
|
|
582
|
+
#### Roles
|
|
583
|
+
|
|
584
|
+
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.
|
|
585
|
+
|
|
586
|
+
| Role | Polarity | Use | Aliases (name inference) |
|
|
587
|
+
| ----------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
|
|
588
|
+
| `'text'` | fg | Text / icons / foreground content | `text`, `fg`, `foreground`, `content`, `ink`, `label`, `stroke` |
|
|
589
|
+
| `'border'` | fg | Non-text spot elements (borders, dividers, outlines) | `border`, `divider`, `outline`, `separator`, `hairline`, `rule` |
|
|
590
|
+
| `'surface'` | bg | Backgrounds / fills | `surface`, `bg`, `background`, `fill`, `canvas`, `paper`, `layer` |
|
|
591
|
+
|
|
592
|
+
Resolution chain (per color):
|
|
593
|
+
|
|
594
|
+
1. Explicit `role` (normalized from an alias) wins.
|
|
595
|
+
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`).
|
|
596
|
+
3. Else, the opposite of the base's role (a `surface` base ⇒ this is `text`).
|
|
597
|
+
4. Else, `'text'` (foreground) — i.e. the base is treated as the background.
|
|
598
|
+
|
|
599
|
+
```ts
|
|
600
|
+
const theme = glaze(280, 60);
|
|
601
|
+
theme.colors({
|
|
602
|
+
surface: { tone: 90 },
|
|
603
|
+
text: { base: 'surface', contrast: { apca: 'content' } }, // inferred text
|
|
604
|
+
border: { base: 'surface', tone: '-10' }, // inferred border
|
|
605
|
+
});
|
|
606
|
+
// role fixes APCA polarity; set `pastel: true` explicitly if a border
|
|
607
|
+
// needs the hue-independent safe chroma limit.
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
Disable name inference with `glaze.configure({ inferRole: false })` (the base-opposite and foreground-default fallbacks still apply).
|
|
611
|
+
|
|
612
|
+
### `ShadowColorDef`
|
|
613
|
+
|
|
614
|
+
| Field | Type | Description |
|
|
615
|
+
| ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
616
|
+
| `type` | `'shadow'` | Discriminator. |
|
|
617
|
+
| `bg` | `string` | Background color name — must reference a non-shadow color in the same theme. |
|
|
618
|
+
| `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. |
|
|
619
|
+
| `intensity` | `HCPair<number>` | Shadow intensity, 0–100. Supports HC pairs. |
|
|
620
|
+
| `tuning` | `ShadowTuning` | Per-color tuning overrides. Merged field-by-field with the global `shadowTuning`. |
|
|
621
|
+
| `pastel` | `boolean` | Per-color `pastel` override. See [Per-color `pastel`](#per-color-pastel). |
|
|
622
|
+
| `inherit` | `boolean` | Inheritance flag, default `true`. |
|
|
623
|
+
|
|
624
|
+
See [Shadows](#shadows) below for the algorithm and tuning details.
|
|
625
|
+
|
|
626
|
+
### `MixColorDef`
|
|
627
|
+
|
|
628
|
+
| Field | Type | Description |
|
|
629
|
+
| ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
630
|
+
| `type` | `'mix'` | Discriminator. |
|
|
631
|
+
| `base` | `string` | "From" color name. |
|
|
632
|
+
| `target` | `string` | "To" color name. |
|
|
633
|
+
| `value` | `HCPair<number>` | Mix ratio 0–100 (0 = pure base, 100 = pure target). In `'transparent'` blend, this becomes the target's opacity. Supports HC pairs. |
|
|
634
|
+
| `blend` | `'opaque' \| 'transparent'` | Default `'opaque'`. |
|
|
635
|
+
| `space` | `'okhsl' \| 'srgb'` | Interpolation space for opaque blending. Default `'okhsl'`. Ignored for `'transparent'` (always composites in linear sRGB). |
|
|
636
|
+
| `contrast` | `HCPair<ContrastSpec>` | Optional contrast floor against `base` (WCAG or APCA — see [`contrast`](#contrast-floor)). The solver adjusts the mix ratio (opaque) or opacity (transparent). |
|
|
637
|
+
| `pastel` | `boolean` | Per-color `pastel` override. See [Per-color `pastel`](#per-color-pastel). |
|
|
638
|
+
| `role` | `RoleInput` | Semantic role of the mixed result against `base`. Same semantics as `RegularColorDef.role` (see [Roles](#roles)). |
|
|
639
|
+
| `inherit` | `boolean` | Inheritance flag, default `true`. |
|
|
640
|
+
|
|
641
|
+
See [Mix colors](#mix-colors) below.
|
|
642
|
+
|
|
643
|
+
---
|
|
644
|
+
|
|
645
|
+
## Standalone color tokens
|
|
646
|
+
|
|
647
|
+
`glaze.color()` creates a single color token without a full theme.
|
|
648
|
+
|
|
649
|
+
```ts
|
|
650
|
+
// arg1: the color (four shapes — see below)
|
|
651
|
+
// arg2: optional config override (GlazeConfigOverride — see below)
|
|
652
|
+
glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride): GlazeColorToken;
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
### Input forms
|
|
656
|
+
|
|
657
|
+
`glaze.color()` accepts **four input shapes**, discriminated by structure:
|
|
658
|
+
|
|
659
|
+
| Shape | Example | Notes |
|
|
660
|
+
| ---------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
661
|
+
| **Bare string** | `'#26fcb2'` | Hex or CSS color function (`rgb()`, `hsl()`, `okhsl()`, `okhst()`, `oklch()`). |
|
|
662
|
+
| **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). |
|
|
663
|
+
| **`{ from, ...overrides }`** | `{ from: '#1a1a2e', base: bg, contrast: 'AA' }` | Value + color overrides in one object. |
|
|
664
|
+
| **Structured** | `{ hue: 152, saturation: 95, tone: 74 }` | Full theme-style token (hue/saturation in 0–100, tone in 0–100). |
|
|
665
|
+
|
|
666
|
+
`GlazeColorValue` (bare string or value-object forms) accepts:
|
|
667
|
+
|
|
668
|
+
| Form | Example | Notes |
|
|
669
|
+
| ------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
670
|
+
| Hex | `'#26fcb2'`, `'#26fcb2ff'`, `'#abc'` | 3, 6, or 8 digits. Alpha is dropped with a `console.warn` — use `opacity` instead. |
|
|
671
|
+
| `rgb()` | `'rgb(38 252 178)'`, `'rgb(38 252 178 / 0.8)'` | Modern space syntax. Alpha dropped with warning. |
|
|
672
|
+
| `hsl()` | `'hsl(152 97% 57%)'` | Modern space syntax. Alpha dropped with warning. |
|
|
673
|
+
| `okhsl()` | `'okhsl(152 95% 74%)'` | Glaze's own emit format. Alpha dropped with warning. |
|
|
674
|
+
| `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. |
|
|
675
|
+
| `oklch()` | `'oklch(0.85 0.18 152)'` | Glaze's own emit format. Alpha dropped with warning. |
|
|
676
|
+
| `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. |
|
|
677
|
+
| `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 }`. |
|
|
678
|
+
| `RgbColor` object | `{ r: 38, g: 252, b: 178 }` | sRGB 0–255. RGB tuple `[r, g, b]` is not supported — use this object form. |
|
|
679
|
+
| `OklchColor` object | `{ l: 0.85, c: 0.18, h: 152 }` | OKLCh (L/C: 0–1, H: degrees), same semantics as `oklch()` strings. |
|
|
680
|
+
|
|
681
|
+
`GlazeColorInput` (structured form) is `{ hue, saturation, tone, ... }`:
|
|
682
|
+
|
|
683
|
+
| Field | Type | Description |
|
|
684
|
+
| ------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
685
|
+
| `hue` | `number` | 0–360. |
|
|
686
|
+
| `saturation` | `number` | 0–100. |
|
|
687
|
+
| `tone` | `HCPair<number \| ExtremeValue>` | 0–100 (contrast-shaped) or `'max'`/`'min'`, optional HC pair. |
|
|
688
|
+
| `saturationFactor` | `number` | Multiplier on the seed (0–1). Default: `1`. |
|
|
689
|
+
| `mode` | `AdaptationMode` | Default: `'auto'`. |
|
|
690
|
+
| `autoFlip` | `boolean` | Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. |
|
|
691
|
+
| `opacity` | `number` | Fixed alpha 0–1. |
|
|
692
|
+
| `base` | `GlazeColorToken \| GlazeColorValue` | Optional dependency. See [Pairing colors](#pairing-colors). |
|
|
693
|
+
| `contrast` | `HCPair<ContrastSpec>` | Contrast floor against `base` (WCAG or APCA). Without `base`, anchored to the literal seed. |
|
|
694
|
+
| `pastel` | `boolean` | Per-color `pastel` override. Falls through to the global / per-theme `pastel` config when omitted. See [Per-color `pastel`](#per-color-pastel). |
|
|
695
|
+
| `role` | `RoleInput` | Semantic role against `base` / the seed (see [Roles](#roles)). Fixes APCA polarity. |
|
|
696
|
+
| `name` | `string` | Debug label for warnings; doesn't change output keys. Reserved names (`'value'`, `'seed'`, `'externalBase'`) are rejected. |
|
|
697
|
+
|
|
698
|
+
`GlazeFromInput` (from form) is `{ from: GlazeColorValue, ...colorOverrides }`:
|
|
699
|
+
|
|
700
|
+
| Field | Notes |
|
|
701
|
+
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
702
|
+
| `from` | **Required.** The source color value — same forms as `GlazeColorValue`. |
|
|
703
|
+
| `hue` | Number (absolute 0–360) or `'+N'`/`'-N'` (relative to seed, never to `base`). |
|
|
704
|
+
| `saturation` | Override seed saturation (0–100). |
|
|
705
|
+
| `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. |
|
|
706
|
+
| `saturationFactor` | Multiplier on the seed (0–1). |
|
|
707
|
+
| `mode` | `'auto'` (default) / `'fixed'` / `'static'`. |
|
|
708
|
+
| `autoFlip` | Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. |
|
|
709
|
+
| `contrast` | Contrast floor (WCAG or APCA). Without `base`, anchored to the literal seed; with `base`, solved per scheme. |
|
|
710
|
+
| `base` | `GlazeColorToken` or raw `GlazeColorValue`. See [Pairing colors](#pairing-colors). |
|
|
711
|
+
| `opacity` | Fixed alpha 0–1. Combining with `contrast` is not recommended — `console.warn` is emitted. |
|
|
712
|
+
| `pastel` | Per-color `pastel` override. Falls through to the global / per-theme `pastel` config when omitted. See [Per-color `pastel`](#per-color-pastel). |
|
|
713
|
+
| `role` | Semantic role against `base` / the seed (see [Roles](#roles)). Fixes APCA polarity. |
|
|
714
|
+
| `name` | Debug label only — surfaces in warnings/errors. Does not change output keys. |
|
|
715
|
+
|
|
716
|
+
Named CSS colors (`'red'`, `'blueviolet'`) are not supported.
|
|
717
|
+
|
|
718
|
+
### Defaults
|
|
719
|
+
|
|
720
|
+
Every input form defaults to `mode: 'auto'` so the resolved token adapts between light and dark like an ordinary theme color. The config snapshot taken at create time differs by input form:
|
|
721
|
+
|
|
722
|
+
- **Value-shorthand** (bare strings, value objects, and `{ from, ...overrides }`):
|
|
723
|
+
- Light variant preserves the input tone exactly (`lightTone: false`).
|
|
724
|
+
- All other config fields (`darkTone`, `darkDesaturation`, `autoFlip`) snapshot from `globalConfig` at create time.
|
|
725
|
+
- **Structured input** (`{ hue, saturation, tone, ... }`):
|
|
726
|
+
- Both tone windows snapshot from `globalConfig` at create time (same as a theme color).
|
|
727
|
+
- All fields are **snapshotted at color-creation time** — later `glaze.configure()` calls don't retroactively change existing tokens.
|
|
728
|
+
|
|
729
|
+
```ts
|
|
730
|
+
// Bare string — adapts automatically
|
|
731
|
+
glaze.color('#26fcb2');
|
|
732
|
+
|
|
733
|
+
// Value-object — same behavior
|
|
734
|
+
glaze.color({ h: 152, s: 0.95, l: 0.74 });
|
|
735
|
+
|
|
736
|
+
// OKHST value-object — tone axis
|
|
737
|
+
glaze.color({ h: 152, s: 0.95, t: 0.7 });
|
|
738
|
+
|
|
739
|
+
// From form — value + color overrides
|
|
740
|
+
glaze.color({ from: '#1a1a2e', hue: '+20', contrast: 'AA' });
|
|
741
|
+
|
|
742
|
+
// Structured form — explicit hue/saturation/tone (0–100)
|
|
743
|
+
glaze.color({ hue: 152, saturation: 95, tone: 74 });
|
|
744
|
+
```
|
|
745
|
+
|
|
746
|
+
### Token methods
|
|
747
|
+
|
|
748
|
+
A `GlazeColorToken` exposes:
|
|
749
|
+
|
|
750
|
+
| Method | Description |
|
|
751
|
+
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
752
|
+
| `token.resolve()` | Resolve as a `ResolvedColor` (light/dark/lightContrast/darkContrast variants). |
|
|
753
|
+
| `token.token(options?)` | Flat token map (no color-name key). Options: `format`, `modes`, `states`. |
|
|
754
|
+
| `token.tasty(options?)` | [Tasty](https://tasty.style) state map (no color-name key). Same options as `token.token`. |
|
|
755
|
+
| `token.json(options?)` | JSON map (no color-name key). Options: `format`, `modes`. |
|
|
756
|
+
| `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`). |
|
|
757
|
+
| `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`. |
|
|
758
|
+
| `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`. |
|
|
759
|
+
| `token.tailwind({ name, ... })` | Tailwind v4 `@theme` block + dark / high-contrast overrides for this color. `name` is **required** (forms `--color-<name>`). Same options as `theme.tailwind()` plus `name`. |
|
|
760
|
+
| `token.export()` | JSON-safe snapshot — pass to `glaze.colorFrom(...)` to rehydrate. |
|
|
761
|
+
|
|
762
|
+
### Per-instance config override
|
|
763
|
+
|
|
764
|
+
The optional `config` argument (`GlazeConfigOverride`) overrides
|
|
765
|
+
resolve-relevant global fields for a token or theme. A tone window can be
|
|
766
|
+
`[lo, hi]`, `{ lo, hi, eps }`, or `false` (full range). Standalone tokens
|
|
767
|
+
snapshot omitted fields at creation; themes continue reading omitted fields
|
|
768
|
+
from the live global config at resolve time.
|
|
769
|
+
|
|
770
|
+
`GlazeConfigOverride`:
|
|
771
|
+
|
|
772
|
+
| Field | Default (from global) | Description |
|
|
773
|
+
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
774
|
+
| `lightTone` | `[10, 100]` | Light tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` (disable clamping). |
|
|
775
|
+
| `darkTone` | `[15, 95]` | Dark tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` (disable clamping). |
|
|
776
|
+
| `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). |
|
|
777
|
+
| `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. |
|
|
778
|
+
| `shadowTuning` | `undefined` | Default shadow tuning (meaningful for themes; harmless on color tokens). |
|
|
779
|
+
|
|
780
|
+
Config overrides apply to both `glaze.color()` tokens and `glaze()` themes:
|
|
781
|
+
|
|
782
|
+
```ts
|
|
783
|
+
// Standalone color — preserve raw tone in both schemes
|
|
784
|
+
glaze.color('#26fcb2', { darkTone: false });
|
|
785
|
+
|
|
786
|
+
// Restore the #000 → white dark flip (full dark range)
|
|
787
|
+
glaze.color('#000000', {
|
|
788
|
+
lightTone: false,
|
|
789
|
+
darkTone: [15, 100],
|
|
790
|
+
});
|
|
791
|
+
|
|
792
|
+
// Structured form with config override
|
|
793
|
+
glaze.color({ hue: 152, saturation: 95, tone: 74 }, { darkTone: false });
|
|
794
|
+
|
|
795
|
+
// Theme with config override
|
|
796
|
+
const rawTheme = glaze(280, 80, { lightTone: false });
|
|
797
|
+
```
|
|
798
|
+
|
|
799
|
+
Standalone color tokens snapshot their effective override at creation time
|
|
800
|
+
(including `pastel` and `inferRole`). Live themes behave differently: overridden
|
|
801
|
+
fields stay fixed, while fields omitted from the override are read from the live
|
|
802
|
+
global config at resolve time. See [Theme config override](#theme-config-override).
|
|
803
|
+
|
|
804
|
+
### Theme config override
|
|
805
|
+
|
|
806
|
+
When a theme is created with a `GlazeConfigOverride`, the override is **merged over the live global config at resolve time**. This means:
|
|
807
|
+
|
|
808
|
+
- Fields you overrode are fixed — `glaze.configure()` can't change them for this theme.
|
|
809
|
+
- Fields you didn't override still react to later `glaze.configure()` calls.
|
|
810
|
+
|
|
811
|
+
```ts
|
|
812
|
+
const t = glaze(280, 80, { lightTone: [0, 50] });
|
|
813
|
+
t.colors({ text: { tone: 50, saturation: 1 } });
|
|
814
|
+
// text.light lands inside the [0, 50] window — always, regardless of
|
|
815
|
+
// global lightTone changes.
|
|
816
|
+
// text.dark.s reacts to glaze.configure({ darkDesaturation }) since it's not overridden.
|
|
817
|
+
```
|
|
818
|
+
|
|
819
|
+
`extend` inherits the parent's override and shallow-merges the child's:
|
|
820
|
+
|
|
821
|
+
```ts
|
|
822
|
+
const child = t.extend({ config: { darkTone: false } });
|
|
823
|
+
// child: lightTone { lo: 0, hi: 50 } (inherited) + darkTone: false (added)
|
|
824
|
+
```
|
|
825
|
+
|
|
826
|
+
`theme.export()` always writes a **full effective** `config` freeze. Restoring
|
|
827
|
+
via `glaze.themeFrom(data)` (or the compat alias `glaze.from`) pins those fields
|
|
828
|
+
so later `configure()` calls no longer affect the restored theme — matching
|
|
829
|
+
standalone color-token behavior.
|
|
830
|
+
|
|
831
|
+
### `glaze.colorFrom(data)`
|
|
832
|
+
|
|
833
|
+
Inverse of `token.export()`. The exported snapshot includes the original input, all overrides (with any `base` token recursively serialized), and the full effective config — so later `glaze.configure()` calls don't change rehydrated tokens.
|
|
834
|
+
|
|
835
|
+
```ts
|
|
836
|
+
const text = glaze.color({ from: '#1a1a1a', contrast: 'AA' });
|
|
837
|
+
const data = text.export();
|
|
838
|
+
const restored = glaze.colorFrom(data);
|
|
839
|
+
// restored.resolve() === text.resolve() byte-for-byte
|
|
840
|
+
```
|
|
841
|
+
|
|
842
|
+
Both value-form and structured-form tokens round-trip.
|
|
843
|
+
|
|
844
|
+
### Pairing colors
|
|
845
|
+
|
|
846
|
+
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.
|
|
847
|
+
|
|
848
|
+
```ts
|
|
849
|
+
const bg = glaze.color('#1a1a2e');
|
|
850
|
+
|
|
851
|
+
// Text guaranteed AA against `bg` in every scheme.
|
|
852
|
+
const text = glaze.color({ from: '#ffffff', base: bg, contrast: 'AA' });
|
|
853
|
+
|
|
854
|
+
// Border 8 tone units lighter than `bg` in each scheme.
|
|
855
|
+
const border = glaze.color({
|
|
856
|
+
from: '#000000',
|
|
857
|
+
base: bg,
|
|
858
|
+
tone: '+8',
|
|
859
|
+
mode: 'fixed',
|
|
860
|
+
});
|
|
861
|
+
|
|
862
|
+
// Raw-value base — Glaze auto-wraps it via `glaze.color(value)`.
|
|
863
|
+
const text2 = glaze.color({ from: '#ffffff', base: '#1a1a2e', contrast: 'AA' });
|
|
864
|
+
```
|
|
865
|
+
|
|
866
|
+
Behavior with `base`:
|
|
867
|
+
|
|
868
|
+
- `contrast` is solved per scheme against `base`'s resolved variant (light / dark / lightContrast / darkContrast).
|
|
869
|
+
- Relative `tone: '+N'` / `'-N'` is anchored to `base`'s tone per scheme (matches theme behavior).
|
|
870
|
+
- Relative `hue: '+N'` / `'-N'` still anchors to the **seed** (the value passed to `glaze.color()`), not the base.
|
|
871
|
+
- `mode` works as a per-pair knob.
|
|
872
|
+
- 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.
|
|
873
|
+
- **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.
|
|
874
|
+
- 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.
|
|
875
|
+
|
|
876
|
+
Chains compose:
|
|
877
|
+
|
|
878
|
+
```ts
|
|
879
|
+
const bg = glaze.color('#000000');
|
|
880
|
+
const surface = glaze.color({ from: '#222222', base: bg, contrast: 'AAA' });
|
|
881
|
+
const text = glaze.color({ from: '#ffffff', base: surface, contrast: 'AA' });
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
### `name` is a debug label
|
|
885
|
+
|
|
886
|
+
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.
|
|
887
|
+
|
|
888
|
+
---
|
|
889
|
+
|
|
890
|
+
## Shadows
|
|
891
|
+
|
|
892
|
+
### Defining shadow colors in a theme
|
|
893
|
+
|
|
894
|
+
```ts
|
|
895
|
+
theme.colors({
|
|
896
|
+
surface: { tone: 95 },
|
|
897
|
+
text: { base: 'surface', tone: '-52', contrast: 'AAA' },
|
|
898
|
+
|
|
899
|
+
'shadow-sm': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 5 },
|
|
900
|
+
'shadow-md': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 10 },
|
|
901
|
+
'shadow-lg': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 20 },
|
|
902
|
+
});
|
|
903
|
+
```
|
|
904
|
+
|
|
905
|
+
Shadow colors are included in all output methods (`tokens()`, `tasty()`, `css()`, `json()`) alongside regular colors and emit an alpha component:
|
|
906
|
+
|
|
907
|
+
```
|
|
908
|
+
'oklch(0.15 0.009 282 / 0.1)'
|
|
909
|
+
'rgb(34 28 42 / 0.1)'
|
|
910
|
+
```
|
|
911
|
+
|
|
912
|
+
### How shadows work
|
|
913
|
+
|
|
914
|
+
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.
|
|
915
|
+
2. **Pigment color** — hue blended between fg and bg, low saturation, dark lightness.
|
|
916
|
+
3. **Alpha** — computed via a `tanh` curve that saturates smoothly toward `alphaMax` (default `1.0`), ensuring well-separated shadow levels even on dark backgrounds.
|
|
917
|
+
|
|
918
|
+
Omit `fg` for an achromatic shadow at full user-specified intensity:
|
|
919
|
+
|
|
920
|
+
```ts
|
|
921
|
+
theme.colors({
|
|
922
|
+
'drop-shadow': { type: 'shadow', bg: 'surface', intensity: 12 },
|
|
923
|
+
});
|
|
924
|
+
```
|
|
925
|
+
|
|
926
|
+
`intensity` supports `[normal, highContrast]` pairs:
|
|
927
|
+
|
|
928
|
+
```ts
|
|
929
|
+
'shadow-card': { type: 'shadow', bg: 'surface', fg: 'text', intensity: [10, 20] },
|
|
930
|
+
```
|
|
931
|
+
|
|
932
|
+
### `ShadowTuning`
|
|
933
|
+
|
|
934
|
+
Fine-tune behavior per-color or globally via `glaze.configure({ shadowTuning })`. Per-color `tuning` is merged field-by-field with the global one.
|
|
935
|
+
|
|
936
|
+
| Parameter | Default | Description |
|
|
937
|
+
| ------------------ | -------------- | ------------------------------------------------------------------------------------- |
|
|
938
|
+
| `saturationFactor` | `0.18` | Fraction of fg saturation kept in pigment. |
|
|
939
|
+
| `maxSaturation` | `0.25` | Upper clamp on pigment saturation. |
|
|
940
|
+
| `lightnessFactor` | `0.25` | Multiplier for bg lightness → pigment lightness. |
|
|
941
|
+
| `lightnessBounds` | `[0.05, 0.20]` | Clamp range for pigment lightness. |
|
|
942
|
+
| `minGapTarget` | `0.05` | Target minimum gap between pigment and bg lightness. |
|
|
943
|
+
| `alphaMax` | `1.0` | Asymptotic maximum alpha. |
|
|
944
|
+
| `bgHueBlend` | `0.2` | Blend weight pulling pigment hue toward bg hue. `0` = pure fg hue, `1` = pure bg hue. |
|
|
945
|
+
|
|
946
|
+
```ts
|
|
947
|
+
theme.colors({
|
|
948
|
+
'shadow-soft': {
|
|
949
|
+
type: 'shadow',
|
|
950
|
+
bg: 'surface',
|
|
951
|
+
intensity: 10,
|
|
952
|
+
tuning: { alphaMax: 0.3, saturationFactor: 0.1 },
|
|
953
|
+
},
|
|
954
|
+
});
|
|
955
|
+
|
|
956
|
+
glaze.configure({
|
|
957
|
+
shadowTuning: { alphaMax: 0.5, bgHueBlend: 0.3 },
|
|
958
|
+
});
|
|
959
|
+
```
|
|
960
|
+
|
|
961
|
+
### Standalone shadow computation
|
|
962
|
+
|
|
963
|
+
`glaze.shadow(input)` computes a shadow outside of a theme. `bg` and `fg` accept any `GlazeColorValue`:
|
|
964
|
+
|
|
965
|
+
```ts
|
|
966
|
+
const v = glaze.shadow({
|
|
967
|
+
bg: '#f0eef5',
|
|
968
|
+
fg: '#1a1a2e',
|
|
969
|
+
intensity: 10,
|
|
970
|
+
});
|
|
971
|
+
// → { h: 280, s: 0.14, l: 0.2, alpha: 0.1 }
|
|
972
|
+
|
|
973
|
+
const css = glaze.format(v, 'oklch');
|
|
974
|
+
// → 'oklch(0.15 0.014 280 / 0.1)'
|
|
975
|
+
```
|
|
976
|
+
|
|
977
|
+
`GlazeShadowInput`:
|
|
978
|
+
|
|
979
|
+
| Field | Type | Description |
|
|
980
|
+
| ----------- | ----------------- | ------------------------------------------------------------------------------ |
|
|
981
|
+
| `bg` | `GlazeColorValue` | Background. Any `GlazeColorValue` form. Alpha components dropped with warning. |
|
|
982
|
+
| `fg` | `GlazeColorValue` | Optional foreground. Same forms as `bg`. |
|
|
983
|
+
| `intensity` | `number` | 0–100. |
|
|
984
|
+
| `tuning` | `ShadowTuning` | Optional. |
|
|
985
|
+
|
|
986
|
+
### Fixed opacity (regular colors)
|
|
987
|
+
|
|
988
|
+
For a simple fixed-alpha color (no shadow algorithm), use `opacity` on a regular color:
|
|
989
|
+
|
|
990
|
+
```ts
|
|
991
|
+
theme.colors({
|
|
992
|
+
overlay: { tone: 0, opacity: 0.5 },
|
|
993
|
+
});
|
|
994
|
+
// → 'oklch(0 0 0 / 0.5)'
|
|
995
|
+
```
|
|
996
|
+
|
|
997
|
+
---
|
|
998
|
+
|
|
999
|
+
## Mix colors
|
|
1000
|
+
|
|
1001
|
+
### Opaque mix
|
|
1002
|
+
|
|
1003
|
+
Produces a solid color by interpolating between `base` and `target`:
|
|
1004
|
+
|
|
1005
|
+
```ts
|
|
1006
|
+
theme.colors({
|
|
1007
|
+
surface: { tone: 95 },
|
|
1008
|
+
accent: { tone: 30 },
|
|
1009
|
+
tint: { type: 'mix', base: 'surface', target: 'accent', value: 30 },
|
|
1010
|
+
});
|
|
1011
|
+
```
|
|
1012
|
+
|
|
1013
|
+
- `value: 0` = pure base, `value: 100` = pure target.
|
|
1014
|
+
- Result has alpha = 1.
|
|
1015
|
+
- Adapts to light/dark/HC schemes automatically via the resolved base and target.
|
|
1016
|
+
|
|
1017
|
+
### Transparent mix
|
|
1018
|
+
|
|
1019
|
+
Produces the target color with controlled opacity — useful for hover overlays:
|
|
1020
|
+
|
|
1021
|
+
```ts
|
|
1022
|
+
theme.colors({
|
|
1023
|
+
surface: { tone: 95 },
|
|
1024
|
+
black: { tone: 0, saturation: 0 },
|
|
1025
|
+
hover: {
|
|
1026
|
+
type: 'mix',
|
|
1027
|
+
base: 'surface',
|
|
1028
|
+
target: 'black',
|
|
1029
|
+
value: 8,
|
|
1030
|
+
blend: 'transparent',
|
|
1031
|
+
},
|
|
1032
|
+
});
|
|
1033
|
+
// hover → black with alpha = 0.08
|
|
1034
|
+
```
|
|
1035
|
+
|
|
1036
|
+
The output color has `h`, `s`, `l` from the target and `alpha = value / 100`.
|
|
1037
|
+
|
|
1038
|
+
### Blend space (opaque only)
|
|
1039
|
+
|
|
1040
|
+
| `space` | Behavior | Best for |
|
|
1041
|
+
| ------------------- | ----------------------------------------- | -------------------------------------------------------- |
|
|
1042
|
+
| `'okhsl'` (default) | Perceptually uniform OKHSL interpolation. | Design token derivation. |
|
|
1043
|
+
| `'srgb'` | Linear sRGB channel interpolation. | Matching browser compositing of CSS color-mix / overlay. |
|
|
1044
|
+
|
|
1045
|
+
Transparent blending always composites in linear sRGB (matches browser alpha compositing).
|
|
1046
|
+
|
|
1047
|
+
### Contrast solving on mixes
|
|
1048
|
+
|
|
1049
|
+
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:
|
|
1050
|
+
|
|
1051
|
+
```ts
|
|
1052
|
+
'tint': {
|
|
1053
|
+
type: 'mix', base: 'surface', target: 'accent',
|
|
1054
|
+
value: 10, contrast: 'AA',
|
|
1055
|
+
},
|
|
1056
|
+
'overlay': {
|
|
1057
|
+
type: 'mix', base: 'surface', target: 'accent',
|
|
1058
|
+
value: 5, blend: 'transparent', contrast: 3,
|
|
1059
|
+
},
|
|
1060
|
+
```
|
|
1061
|
+
|
|
1062
|
+
Both `value` and `contrast` support `[normal, highContrast]` pairs.
|
|
1063
|
+
|
|
1064
|
+
### Achromatic colors
|
|
1065
|
+
|
|
1066
|
+
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.
|
|
1067
|
+
|
|
1068
|
+
### Mix chaining
|
|
1069
|
+
|
|
1070
|
+
Mix colors can reference other mix colors:
|
|
1071
|
+
|
|
1072
|
+
```ts
|
|
1073
|
+
theme.colors({
|
|
1074
|
+
white: { tone: 100, saturation: 0 },
|
|
1075
|
+
black: { tone: 0, saturation: 0 },
|
|
1076
|
+
gray: {
|
|
1077
|
+
type: 'mix',
|
|
1078
|
+
base: 'white',
|
|
1079
|
+
target: 'black',
|
|
1080
|
+
value: 50,
|
|
1081
|
+
space: 'srgb',
|
|
1082
|
+
},
|
|
1083
|
+
lightGray: {
|
|
1084
|
+
type: 'mix',
|
|
1085
|
+
base: 'white',
|
|
1086
|
+
target: 'gray',
|
|
1087
|
+
value: 50,
|
|
1088
|
+
space: 'srgb',
|
|
1089
|
+
},
|
|
1090
|
+
});
|
|
1091
|
+
```
|
|
1092
|
+
|
|
1093
|
+
Mix colors **cannot** reference shadow colors (same restriction as regular dependent colors).
|
|
1094
|
+
|
|
1095
|
+
---
|
|
1096
|
+
|
|
1097
|
+
## Palette
|
|
1098
|
+
|
|
1099
|
+
`glaze.palette(themes, options?)` composes multiple themes into a single token namespace.
|
|
1100
|
+
|
|
1101
|
+
```ts
|
|
1102
|
+
const palette = glaze.palette({ primary, danger, success, warning });
|
|
1103
|
+
const palette = glaze.palette(
|
|
1104
|
+
{ primary, danger, success },
|
|
1105
|
+
{ primary: 'primary' },
|
|
1106
|
+
);
|
|
1107
|
+
```
|
|
1108
|
+
|
|
1109
|
+
`GlazePaletteOptions`:
|
|
1110
|
+
|
|
1111
|
+
| Option | Description |
|
|
1112
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1113
|
+
| `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. |
|
|
1114
|
+
|
|
1115
|
+
A `GlazePalette` exposes:
|
|
1116
|
+
|
|
1117
|
+
| Method | Description |
|
|
1118
|
+
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
1119
|
+
| `palette.list()` | Theme names in insertion order. |
|
|
1120
|
+
| `palette.primary` | Primary theme name, if set. |
|
|
1121
|
+
| `palette.theme(name)` | Get a live theme instance by name. |
|
|
1122
|
+
| `palette.themes()` | Shallow copy of the theme map (same instances the palette holds). |
|
|
1123
|
+
| `palette.export()` | Authoring snapshot — restorable via `glaze.paletteFrom()`. Not the same as `palette.json()`. |
|
|
1124
|
+
| `palette.tokens(options?)` | Flat token map grouped by scheme variant. |
|
|
1125
|
+
| `palette.tasty(options?)` | [Tasty](https://tasty.style) style-to-state bindings. |
|
|
1126
|
+
| `palette.json(options?)` | Per-theme **resolved** color JSON (not restorable as authoring config). |
|
|
1127
|
+
| `palette.css(options?)` | CSS custom property declaration strings. |
|
|
1128
|
+
| `palette.dtcg(options?)` | Per-scheme W3C DTCG token trees. |
|
|
1129
|
+
| `palette.dtcgResolver(options?)` | One DTCG Resolver-Module document for every scheme. |
|
|
1130
|
+
| `palette.tailwind(options?)` | One Tailwind CSS v4 theme with scheme overrides. |
|
|
1131
|
+
|
|
1132
|
+
### `palette.export()` / `glaze.paletteFrom()`
|
|
1133
|
+
|
|
1134
|
+
```ts
|
|
1135
|
+
const snapshot = palette.export();
|
|
1136
|
+
// → {
|
|
1137
|
+
// kind: 'palette',
|
|
1138
|
+
// version: 1,
|
|
1139
|
+
// primary: 'brand',
|
|
1140
|
+
// themes: { brand: { kind: 'theme', ... }, danger: { ... } },
|
|
1141
|
+
// }
|
|
1142
|
+
|
|
1143
|
+
const restored = glaze.paletteFrom(JSON.parse(JSON.stringify(snapshot)));
|
|
1144
|
+
const brand = restored.theme('brand')!;
|
|
1145
|
+
```
|
|
1146
|
+
|
|
1147
|
+
Config snapshot vs resolved output: use `export()` / `paletteFrom()` to
|
|
1148
|
+
persist and restore the authoring graph (themes, color defs, relations). Use
|
|
1149
|
+
`json()` / `tokens()` / `css()` / … to emit resolved color strings for apps
|
|
1150
|
+
and design tools.
|
|
1151
|
+
|
|
1152
|
+
### `GlazePaletteExportOptions`
|
|
1153
|
+
|
|
1154
|
+
Shared by `tokens`, `tasty`, and `css`:
|
|
1155
|
+
|
|
1156
|
+
| Option | Default | Description |
|
|
1157
|
+
| --------- | ------------------------------ | -------------------------------------------------------------------------------------------- |
|
|
1158
|
+
| `prefix` | `true` (= `"<themeName>-"`) | `false` disables prefixing. Or pass a custom map: `{ primary: 'brand-', danger: 'error-' }`. |
|
|
1159
|
+
| `primary` | inherits from palette creation | `string` to override, `false` to disable for this call. |
|
|
1160
|
+
|
|
1161
|
+
Each export method also accepts its own format/options shape:
|
|
1162
|
+
|
|
1163
|
+
| Method | Additional options |
|
|
1164
|
+
| -------------------------------- | ----------------------------------------- |
|
|
1165
|
+
| `palette.tokens(options?)` | `format`, `modes` |
|
|
1166
|
+
| `palette.tasty(options?)` | `format`, `modes`, `states` |
|
|
1167
|
+
| `palette.css(options?)` | `format`, `suffix` |
|
|
1168
|
+
| `palette.dtcg(options?)` | `colorSpace`, `modes` |
|
|
1169
|
+
| `palette.dtcgResolver(options?)` | `colorSpace`, `modes`, resolver names |
|
|
1170
|
+
| `palette.tailwind(options?)` | `format`, `modes`, selectors, `namespace` |
|
|
1171
|
+
|
|
1172
|
+
`palette.css()` does not accept `modes`; it always returns all four CSS strings (`light`, `dark`, `lightContrast`, `darkContrast`).
|
|
1173
|
+
|
|
1174
|
+
### Prefix behavior
|
|
1175
|
+
|
|
1176
|
+
By default all palette tokens are prefixed:
|
|
1177
|
+
|
|
1178
|
+
```ts
|
|
1179
|
+
palette.tokens();
|
|
1180
|
+
// → {
|
|
1181
|
+
// light: { 'primary-surface': 'oklch(...)', 'danger-surface': 'oklch(...)' },
|
|
1182
|
+
// dark: { 'primary-surface': 'oklch(...)', 'danger-surface': 'oklch(...)' },
|
|
1183
|
+
// }
|
|
1184
|
+
```
|
|
1185
|
+
|
|
1186
|
+
Custom map (any theme not listed falls back to `"<themeName>-"`):
|
|
1187
|
+
|
|
1188
|
+
```ts
|
|
1189
|
+
palette.tokens({ prefix: { primary: 'brand-', danger: 'error-' } });
|
|
1190
|
+
```
|
|
1191
|
+
|
|
1192
|
+
Disable prefixing:
|
|
1193
|
+
|
|
1194
|
+
```ts
|
|
1195
|
+
palette.tokens({ prefix: false });
|
|
1196
|
+
```
|
|
1197
|
+
|
|
1198
|
+
### Collision detection
|
|
1199
|
+
|
|
1200
|
+
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:
|
|
1201
|
+
|
|
1202
|
+
```
|
|
1203
|
+
glaze: token "surface" from theme "b" collides with theme "a" — skipping.
|
|
1204
|
+
```
|
|
1205
|
+
|
|
1206
|
+
### Primary theme aliases
|
|
1207
|
+
|
|
1208
|
+
The primary theme's tokens are duplicated without prefix:
|
|
1209
|
+
|
|
1210
|
+
```ts
|
|
1211
|
+
const palette = glaze.palette(
|
|
1212
|
+
{ primary, danger, success },
|
|
1213
|
+
{ primary: 'primary' },
|
|
1214
|
+
);
|
|
1215
|
+
palette.tokens();
|
|
1216
|
+
// → {
|
|
1217
|
+
// light: {
|
|
1218
|
+
// 'primary-surface': 'oklch(...)',
|
|
1219
|
+
// 'danger-surface': 'oklch(...)',
|
|
1220
|
+
// 'success-surface': 'oklch(...)',
|
|
1221
|
+
// 'surface': 'oklch(...)', // unprefixed alias
|
|
1222
|
+
// },
|
|
1223
|
+
// }
|
|
1224
|
+
```
|
|
1225
|
+
|
|
1226
|
+
Override per-export:
|
|
1227
|
+
|
|
1228
|
+
```ts
|
|
1229
|
+
palette.tokens({ primary: 'danger' });
|
|
1230
|
+
palette.tokens({ primary: false });
|
|
1231
|
+
```
|
|
1232
|
+
|
|
1233
|
+
The primary alias works alongside any prefix mode — when using a custom map, primary tokens are still duplicated without prefix:
|
|
1234
|
+
|
|
1235
|
+
```ts
|
|
1236
|
+
palette.tokens({ prefix: { primary: 'p-', danger: 'd-' } });
|
|
1237
|
+
// → 'p-surface' + 'surface' (alias) + 'd-surface'
|
|
1238
|
+
```
|
|
1239
|
+
|
|
1240
|
+
### `palette.json()`
|
|
1241
|
+
|
|
1242
|
+
JSON export groups by theme name (no prefix needed):
|
|
1243
|
+
|
|
1244
|
+
```ts
|
|
1245
|
+
palette.json();
|
|
1246
|
+
// → {
|
|
1247
|
+
// primary: { surface: { light: 'oklch(...)', dark: 'oklch(...)' } },
|
|
1248
|
+
// danger: { surface: { light: 'oklch(...)', dark: 'oklch(...)' } },
|
|
1249
|
+
// }
|
|
1250
|
+
```
|
|
1251
|
+
|
|
1252
|
+
### `palette.css()`
|
|
1253
|
+
|
|
1254
|
+
```ts
|
|
1255
|
+
const css = palette.css();
|
|
1256
|
+
const stylesheet = `
|
|
1257
|
+
:root { ${css.light} }
|
|
1258
|
+
@media (prefers-color-scheme: dark) {
|
|
1259
|
+
:root { ${css.dark} }
|
|
1260
|
+
}
|
|
1261
|
+
`;
|
|
1262
|
+
```
|
|
1263
|
+
|
|
1264
|
+
`palette.css()` accepts the same `GlazeCssOptions` as `theme.css()` plus `GlazePaletteExportOptions`.
|
|
1265
|
+
It does not accept `modes`; all four result fields are always returned.
|
|
1266
|
+
|
|
1267
|
+
### `palette.dtcg()`
|
|
1268
|
+
|
|
1269
|
+
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).
|
|
1270
|
+
|
|
1271
|
+
```ts
|
|
1272
|
+
palette.dtcg();
|
|
1273
|
+
// → {
|
|
1274
|
+
// light: {
|
|
1275
|
+
// 'primary-surface': { $type: 'color', $value: { ... } },
|
|
1276
|
+
// 'surface': { $type: 'color', $value: { ... } }, // unprefixed alias
|
|
1277
|
+
// 'danger-surface': { $type: 'color', $value: { ... } },
|
|
1278
|
+
// },
|
|
1279
|
+
// dark: { ... },
|
|
1280
|
+
// }
|
|
1281
|
+
```
|
|
1282
|
+
|
|
1283
|
+
Accepts `GlazeDtcgOptions` plus `GlazePaletteExportOptions`.
|
|
1284
|
+
|
|
1285
|
+
### `palette.dtcgResolver()`
|
|
1286
|
+
|
|
1287
|
+
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.
|
|
1288
|
+
|
|
1289
|
+
```ts
|
|
1290
|
+
palette.dtcgResolver();
|
|
1291
|
+
// → {
|
|
1292
|
+
// version: '2025.10',
|
|
1293
|
+
// sets: { base: { sources: [ { 'primary-surface': {…}, 'surface': {…}, 'danger-surface': {…} } ] } },
|
|
1294
|
+
// modifiers: { scheme: { default: 'light', contexts: { light: [], dark: [ {…} ] } } },
|
|
1295
|
+
// resolutionOrder: [ { $ref: '#/sets/base' }, { $ref: '#/modifiers/scheme' } ],
|
|
1296
|
+
// }
|
|
1297
|
+
```
|
|
1298
|
+
|
|
1299
|
+
Accepts `GlazeDtcgResolverOptions` plus `GlazePaletteExportOptions`.
|
|
1300
|
+
|
|
1301
|
+
### `palette.tailwind()`
|
|
1302
|
+
|
|
1303
|
+
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`.
|
|
1304
|
+
|
|
1305
|
+
```ts
|
|
1306
|
+
const css = palette.tailwind();
|
|
1307
|
+
// @theme {
|
|
1308
|
+
// --color-primary-surface: oklch(...);
|
|
1309
|
+
// --color-surface: oklch(...); /* unprefixed alias */
|
|
1310
|
+
// --color-danger-surface: oklch(...);
|
|
1311
|
+
// }
|
|
1312
|
+
// .dark { ... }
|
|
1313
|
+
```
|
|
1314
|
+
|
|
1315
|
+
Accepts `GlazeTailwindOptions` plus `GlazePaletteExportOptions`. The palette `prefix` option (theme prefixing) is separate from `GlazeTailwindOptions.namespace` (the `--color-*` CSS namespace).
|
|
1316
|
+
|
|
1317
|
+
---
|
|
1318
|
+
|
|
1319
|
+
## Output formats
|
|
1320
|
+
|
|
1321
|
+
Control the color format with the `format` option on any export method:
|
|
1322
|
+
|
|
1323
|
+
| Format | Output (alpha = 1) | Output (alpha < 1) | Notes |
|
|
1324
|
+
| --------------------------------------------- | ------------------ | -------------------- | --------------------------------------------------------------------------------------------- |
|
|
1325
|
+
| `'oklch'` (default for CSS-string exports) | `oklch(L C H)` | `oklch(L C H / A)` | OKLab-based LCH. Native CSS. Required for `splitHue`. |
|
|
1326
|
+
| `'rgb'` | `rgb(R G B)` | `rgb(R G B / A)` | Rounded integers, modern space syntax. |
|
|
1327
|
+
| `'hsl'` | `hsl(H S% L%)` | `hsl(H S% L% / A)` | Modern space syntax. |
|
|
1328
|
+
| `'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()`). |
|
|
1329
|
+
| `'okhst'` | `okhst(H S% T%)` | `okhst(H S% T% / A)` | OKHST tone axis. **[Tasty](https://tasty.style)-only** — same restriction as `okhsl`. |
|
|
1330
|
+
|
|
1331
|
+
```ts
|
|
1332
|
+
theme.tokens(); // 'oklch(0.965 0.0123 280)' (default)
|
|
1333
|
+
theme.tokens({ format: 'rgb' }); // 'rgb(244 240 250)'
|
|
1334
|
+
theme.tasty(); // 'oklch(0.965 0.0123 280)' (default)
|
|
1335
|
+
theme.tasty({ format: 'okhst' }); // 'okhst(280 60% 97%)'
|
|
1336
|
+
```
|
|
1337
|
+
|
|
1338
|
+
All numeric output strips trailing zeros for cleaner CSS (e.g. `95` not `95.0`).
|
|
1339
|
+
|
|
1340
|
+
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.
|
|
1341
|
+
|
|
1342
|
+
### Hue channel splitting (`splitHue`)
|
|
1343
|
+
|
|
1344
|
+
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:
|
|
1345
|
+
|
|
1346
|
+
```css
|
|
1347
|
+
/* theme.css({ format: 'oklch', splitHue: true, name: 'brand' }) */
|
|
1348
|
+
--brand-hue: 240;
|
|
1349
|
+
--accent-hue: calc(var(--brand-hue) + 20);
|
|
1350
|
+
--surface-color: oklch(0.52 0.06 var(--brand-hue));
|
|
1351
|
+
--accent-color: oklch(0.62 0.03 var(--accent-hue));
|
|
1352
|
+
```
|
|
1353
|
+
|
|
1354
|
+
**Requirements:** every exported color must be pastel (`pastel: true` globally or per-color). Pastel mode bounds chroma by the hue-independent safe chroma at each lightness, so emitted `C` stays in sRGB for any rotated hue. Non-pastel palettes throw rather than emit values that would clip under rotation.
|
|
1355
|
+
|
|
1356
|
+
**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).
|
|
1357
|
+
|
|
1358
|
+
`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.
|
|
1359
|
+
|
|
1360
|
+
---
|
|
1361
|
+
|
|
1362
|
+
## Adaptation modes
|
|
1363
|
+
|
|
1364
|
+
`mode` controls how a color adapts across schemes:
|
|
1365
|
+
|
|
1366
|
+
| Mode | Behavior |
|
|
1367
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1368
|
+
| `'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. |
|
|
1369
|
+
| `'fixed'` | Color stays recognizable. Tone is _mapped_ (not inverted) into the dark window. Use for brand buttons, CTAs, status banners. |
|
|
1370
|
+
| `'static'` | No adaptation. Same tone in every scheme. |
|
|
1371
|
+
|
|
1372
|
+
### How relative tone adapts
|
|
1373
|
+
|
|
1374
|
+
**`auto`** — the offset is anchored to the base's per-scheme tone:
|
|
1375
|
+
|
|
1376
|
+
```
|
|
1377
|
+
Light: surface tone=97, text tone='-52' → tone 45 (dark text on light bg)
|
|
1378
|
+
Dark: surface inverts to a low tone; the '-52' offset re-anchors to the
|
|
1379
|
+
base's light tone and maps into the dark window (light text on dark bg)
|
|
1380
|
+
```
|
|
1381
|
+
|
|
1382
|
+
**`fixed`** — tone is mapped (not inverted), relative sign preserved:
|
|
1383
|
+
|
|
1384
|
+
```
|
|
1385
|
+
Light: accent-fill tone=52, accent-text tone='+20' → lighter than the fill
|
|
1386
|
+
Dark: accent-fill maps into the dark window, sign preserved
|
|
1387
|
+
```
|
|
1388
|
+
|
|
1389
|
+
Offsets that would push past `[0, 100]` clamp to the boundary, or — with `autoFlip` (default on) — mirror to the other side of the base. Set `autoFlip: false` to keep the authored side and clamp instead.
|
|
1390
|
+
|
|
1391
|
+
**`static`** — no adaptation, same tone in every scheme.
|
|
1392
|
+
|
|
1393
|
+
---
|
|
1394
|
+
|
|
1395
|
+
## Light / dark scheme mapping
|
|
1396
|
+
|
|
1397
|
+
The mapping is a single tone pipeline; there is no Möbius curve. See
|
|
1398
|
+
[Scheme adaptation](okhst.md#scheme-adaptation) for the product-level model and
|
|
1399
|
+
the [canonical OKHST specification](https://github.com/tenphi/okhst) for the
|
|
1400
|
+
transfer math.
|
|
1401
|
+
|
|
1402
|
+
### Light scheme
|
|
1403
|
+
|
|
1404
|
+
An authored tone (0–100) is remapped into the `lightTone` **tone window**.
|
|
1405
|
+
The window's `lo`/`hi` are OKHSL-lightness boundaries (0–100); authored tone is
|
|
1406
|
+
positioned within the corresponding tone interval and converted to final OKHSL
|
|
1407
|
+
lightness. `static` mode and HC variants use the full range.
|
|
1408
|
+
|
|
1409
|
+
```
|
|
1410
|
+
window = lightTone // default [10, 100]
|
|
1411
|
+
finalTone = remap(authorTone, window)
|
|
1412
|
+
finalL = fromTone(finalTone) // OKHSL lightness
|
|
1413
|
+
```
|
|
1414
|
+
|
|
1415
|
+
### Dark scheme
|
|
1416
|
+
|
|
1417
|
+
**`auto`** — invert the tone, then remap into the dark window:
|
|
1418
|
+
|
|
1419
|
+
```
|
|
1420
|
+
window = darkTone // default [15, 95]
|
|
1421
|
+
inverted = 100 - authorTone
|
|
1422
|
+
finalTone = remap(inverted, window)
|
|
1423
|
+
```
|
|
1424
|
+
|
|
1425
|
+
The inversion preserves authored tone spacing without a fitted curve. This is
|
|
1426
|
+
exactly contrast-even for neutrals and approximate for chromatic colors. The
|
|
1427
|
+
ordinary light/dark asymmetry lives in the two windows' `(lo, hi, eps)` values
|
|
1428
|
+
(`eps` defaults to the reference `0.05`).
|
|
1429
|
+
|
|
1430
|
+
**`fixed`** — remap into the dark window without inversion:
|
|
1431
|
+
|
|
1432
|
+
```
|
|
1433
|
+
finalTone = remap(authorTone, darkTone)
|
|
1434
|
+
```
|
|
1435
|
+
|
|
1436
|
+
In high-contrast variants both windows are bypassed (forced to the full `[0, 100]` range): `auto` still inverts, `fixed`/`static` do not.
|
|
1437
|
+
|
|
1438
|
+
### Dark scheme — saturation
|
|
1439
|
+
|
|
1440
|
+
`darkDesaturation` reduces saturation for all colors in dark scheme:
|
|
1441
|
+
|
|
1442
|
+
```ts
|
|
1443
|
+
S_dark = S_light * (1 - darkDesaturation); // default: 0.1
|
|
1444
|
+
```
|
|
1445
|
+
|
|
1446
|
+
`static` mode skips desaturation.
|
|
1447
|
+
|
|
1448
|
+
---
|
|
1449
|
+
|
|
1450
|
+
## Configuration
|
|
1451
|
+
|
|
1452
|
+
```ts
|
|
1453
|
+
glaze.configure({
|
|
1454
|
+
lightTone: [10, 100], // [lo, hi]; or { lo, hi, eps } / false to disable clamping
|
|
1455
|
+
darkTone: [15, 95], // [lo, hi]; or { lo, hi, eps } / false to disable clamping
|
|
1456
|
+
darkDesaturation: 0.1,
|
|
1457
|
+
states: {
|
|
1458
|
+
dark: '@media(prefers-color-scheme: dark)',
|
|
1459
|
+
highContrast: '@media(prefers-contrast: more)',
|
|
1460
|
+
},
|
|
1461
|
+
modes: {
|
|
1462
|
+
dark: true,
|
|
1463
|
+
highContrast: false,
|
|
1464
|
+
},
|
|
1465
|
+
shadowTuning: {
|
|
1466
|
+
alphaMax: 0.6,
|
|
1467
|
+
bgHueBlend: 0.2,
|
|
1468
|
+
},
|
|
1469
|
+
});
|
|
1470
|
+
```
|
|
1471
|
+
|
|
1472
|
+
A `ToneWindow` is `[lo, hi]` (OKHSL-lightness boundaries, reference eps — the
|
|
1473
|
+
common form), `{ lo, hi, eps }` (advanced: explicit per-scheme render eps), or
|
|
1474
|
+
`false` for the full range `[0, 100]` at the reference eps. `false` removes the
|
|
1475
|
+
boundaries, not the tone transfer.
|
|
1476
|
+
|
|
1477
|
+
`GlazeConfig`:
|
|
1478
|
+
|
|
1479
|
+
| Field | Default | Description |
|
|
1480
|
+
| --------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1481
|
+
| `lightTone` | `[10, 100]` | Light scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC. |
|
|
1482
|
+
| `darkTone` | `[15, 95]` | Dark scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC. |
|
|
1483
|
+
| `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). |
|
|
1484
|
+
| `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. |
|
|
1485
|
+
| `states.highContrast` | `'@media(prefers-contrast: more)'` | State alias for HC tokens ([Tasty](https://tasty.style) export). |
|
|
1486
|
+
| `modes.dark` | `true` | Include dark variants in exports. |
|
|
1487
|
+
| `modes.highContrast` | `false` | Include HC variants. |
|
|
1488
|
+
| `shadowTuning` | `undefined` | Default tuning for all shadow colors. Per-color tuning merges field-by-field. |
|
|
1489
|
+
| `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). |
|
|
1490
|
+
| `pastel` | `false` | Hue-independent "safe" chroma limit across all colors so scaling saturation never exceeds the sRGB boundary at any hue for the given lightness. Override per color via [`pastel`](#per-color-pastel). |
|
|
1491
|
+
| `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). |
|
|
1492
|
+
|
|
1493
|
+
| Method | Description |
|
|
1494
|
+
| ------------------------- | ----------------------------------------------------------------------------------- |
|
|
1495
|
+
| `glaze.configure(config)` | Merge into the global config. Bumps a config version that invalidates theme caches. |
|
|
1496
|
+
| `glaze.getConfig()` | Snapshot the current resolved config (shallow copy). |
|
|
1497
|
+
| `glaze.resetConfig()` | Reset to defaults (also bumps the version counter). |
|
|
1498
|
+
|
|
1499
|
+
Standalone `glaze.color()` tokens snapshot the resolve-relevant fields at create time, so later `configure()` calls don't change already-created tokens. Themes merge the live global at resolve time for fields not overridden via `GlazeConfigOverride`.
|
|
1500
|
+
|
|
1501
|
+
---
|
|
1502
|
+
|
|
1503
|
+
## Output modes
|
|
1504
|
+
|
|
1505
|
+
Control which scheme variants appear in `tokens()` / `tasty()` / `json()` exports:
|
|
1506
|
+
|
|
1507
|
+
```ts
|
|
1508
|
+
// Light only
|
|
1509
|
+
palette.tokens({ modes: { dark: false, highContrast: false } });
|
|
1510
|
+
|
|
1511
|
+
// Light + dark (default)
|
|
1512
|
+
palette.tokens({ modes: { highContrast: false } });
|
|
1513
|
+
|
|
1514
|
+
// All four variants
|
|
1515
|
+
palette.tokens({ modes: { dark: true, highContrast: true } });
|
|
1516
|
+
// → { light, dark, lightContrast, darkContrast }
|
|
1517
|
+
```
|
|
1518
|
+
|
|
1519
|
+
Resolution priority (highest first):
|
|
1520
|
+
|
|
1521
|
+
1. Per-call `modes` option on `tokens` / `tasty` / `json`.
|
|
1522
|
+
2. `glaze.configure({ modes })` — global config.
|
|
1523
|
+
3. Built-in default: `{ dark: true, highContrast: false }`.
|
|
1524
|
+
|
|
1525
|
+
---
|
|
1526
|
+
|
|
1527
|
+
## Validation
|
|
1528
|
+
|
|
1529
|
+
Invalid definitions throw before resolution when Glaze cannot produce a
|
|
1530
|
+
well-defined dependency graph. Recoverable numeric bounds are clamped. A
|
|
1531
|
+
physically unreachable contrast floor or a potentially misleading
|
|
1532
|
+
contrast/opacity combination emits `console.warn` and returns the closest
|
|
1533
|
+
available result.
|
|
1534
|
+
|
|
1535
|
+
| Condition | Behavior |
|
|
1536
|
+
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
1537
|
+
| `contrast` without `base` in a **theme** color | Validation error |
|
|
1538
|
+
| Relative `tone` without `base` in a **theme** color | Validation error |
|
|
1539
|
+
| `contrast` without `base` in `glaze.color()` | Anchors against the literal seed (no error) |
|
|
1540
|
+
| Relative `tone` without `base` in `glaze.color()` | Anchors against the literal seed (no error) |
|
|
1541
|
+
| Relative `tone` overshoots `[0, 100]` | Mirror to the other side of the base (`autoFlip` on, default), or clamp to the boundary (`autoFlip` off) |
|
|
1542
|
+
| `tone` resolves outside 0–100 | Clamp silently |
|
|
1543
|
+
| `'max'` / `'min'` without `base` | Allowed — resolves to the scheme's tone extreme (root color) |
|
|
1544
|
+
| `saturation` outside 0–1 | Clamp silently |
|
|
1545
|
+
| Circular `base` references | Validation error |
|
|
1546
|
+
| `base` references non-existent name | Validation error |
|
|
1547
|
+
| Shadow `bg` references non-existent color | Validation error |
|
|
1548
|
+
| Shadow `fg` references non-existent color | Validation error |
|
|
1549
|
+
| Shadow `bg` references another shadow color | Validation error |
|
|
1550
|
+
| Shadow `fg` references another shadow color | Validation error |
|
|
1551
|
+
| Regular color `base` references a shadow color | Validation error |
|
|
1552
|
+
| Shadow `intensity` outside 0–100 | Clamp silently |
|
|
1553
|
+
| `contrast` + `opacity` combined | `console.warn` |
|
|
1554
|
+
| Mix `base` references non-existent color | Validation error |
|
|
1555
|
+
| Mix `target` references non-existent color | Validation error |
|
|
1556
|
+
| Mix `base` references a shadow color | Validation error |
|
|
1557
|
+
| Mix `target` references a shadow color | Validation error |
|
|
1558
|
+
| Mix `value` outside 0–100 | Clamp silently |
|
|
1559
|
+
| Circular references involving mix colors | Validation error |
|
|
1560
|
+
| Contrast target physically unreachable | `console.warn` (deduped per `(name, scheme, target)`); closest passing variant returned |
|
|
1561
|
+
|
|
1562
|
+
---
|
|
1563
|
+
|
|
1564
|
+
## Color math utilities
|
|
1565
|
+
|
|
1566
|
+
For advanced use, Glaze re-exports its internal color math.
|
|
1567
|
+
|
|
1568
|
+
### Conversions
|
|
1569
|
+
|
|
1570
|
+
```ts
|
|
1571
|
+
import {
|
|
1572
|
+
okhslToLinearSrgb,
|
|
1573
|
+
okhslToSrgb,
|
|
1574
|
+
okhslToOklab,
|
|
1575
|
+
oklabToOkhsl,
|
|
1576
|
+
srgbToOkhsl,
|
|
1577
|
+
hslToSrgb,
|
|
1578
|
+
parseHex,
|
|
1579
|
+
parseHexAlpha,
|
|
1580
|
+
relativeLuminanceFromLinearRgb,
|
|
1581
|
+
contrastRatioFromLuminance,
|
|
1582
|
+
gamutClampedLuminance,
|
|
1583
|
+
} from '@tenphi/glaze';
|
|
1584
|
+
```
|
|
1585
|
+
|
|
1586
|
+
| Function | Description |
|
|
1587
|
+
| ------------------------------------- | ------------------------------------------------------------------------ |
|
|
1588
|
+
| `okhslToLinearSrgb(h, s, l)` | OKHSL (h: 0–360, s/l: 0–1) → linear sRGB tuple. |
|
|
1589
|
+
| `okhslToSrgb(h, s, l)` | OKHSL → gamma-encoded sRGB tuple (0–1 per channel). |
|
|
1590
|
+
| `okhslToOklab([h, s, l])` | OKHSL → OKLab `[L, a, b]`. |
|
|
1591
|
+
| `oklabToOkhsl([L, a, b])` | OKLab → OKHSL. |
|
|
1592
|
+
| `srgbToOkhsl([r, g, b])` | Gamma sRGB (0–1) → OKHSL. |
|
|
1593
|
+
| `hslToSrgb(h, s, l)` | CSS HSL → sRGB tuple. |
|
|
1594
|
+
| `parseHex(hex)` | Parse `#rgb` / `#rrggbb` to sRGB tuple. Returns `null` on invalid input. |
|
|
1595
|
+
| `parseHexAlpha(hex)` | Parse `#rgb` / `#rrggbb` / `#rrggbbaa`; returns `[r, g, b, a?]`. |
|
|
1596
|
+
| `relativeLuminanceFromLinearRgb(rgb)` | WCAG relative luminance from linear sRGB. |
|
|
1597
|
+
| `contrastRatioFromLuminance(yA, yB)` | WCAG contrast ratio from two luminances. |
|
|
1598
|
+
| `gamutClampedLuminance(linearRgb)` | Relative luminance with channel clamping for out-of-gamut colors. |
|
|
1599
|
+
|
|
1600
|
+
### Format writers
|
|
1601
|
+
|
|
1602
|
+
```ts
|
|
1603
|
+
import { formatOkhsl, formatRgb, formatHsl, formatOklch } from '@tenphi/glaze';
|
|
1604
|
+
|
|
1605
|
+
formatOkhsl(280, 60, 95); // 'okhsl(280 60% 95%)'
|
|
1606
|
+
formatRgb(280, 60, 95); // 'rgb(244 240 250)'
|
|
1607
|
+
formatHsl(280, 60, 95); // 'hsl(280 60% 95%)'
|
|
1608
|
+
formatOklch(280, 60, 95); // 'oklch(0.95 ... 280)'
|
|
1609
|
+
```
|
|
1610
|
+
|
|
1611
|
+
To attach an alpha component, use `glaze.format(variant, format)` on a `ResolvedColorVariant` (which carries the `alpha` channel) instead of these raw writers.
|
|
1612
|
+
|
|
1613
|
+
### OKHST tone utilities
|
|
1614
|
+
|
|
1615
|
+
```ts
|
|
1616
|
+
import {
|
|
1617
|
+
toTone,
|
|
1618
|
+
fromTone,
|
|
1619
|
+
toneFromY,
|
|
1620
|
+
yFromTone,
|
|
1621
|
+
okhstToOkhsl,
|
|
1622
|
+
okhslToOkhst,
|
|
1623
|
+
variantToOkhsl,
|
|
1624
|
+
REF_EPS,
|
|
1625
|
+
} from '@tenphi/glaze';
|
|
1626
|
+
```
|
|
1627
|
+
|
|
1628
|
+
| Function | Description |
|
|
1629
|
+
| ------------------------------------------- | ------------------------------------------------------------------------- |
|
|
1630
|
+
| `toTone(l, eps?)` | OKHSL lightness (0–1) → tone (0–100). Defaults to `REF_EPS`. |
|
|
1631
|
+
| `fromTone(t, eps?)` | Tone (0–100) → OKHSL lightness (0–1). Inverse of `toTone`. |
|
|
1632
|
+
| `toneFromY(y, eps?)` / `yFromTone(t, eps?)` | Same transfer in luminance space (0–1). |
|
|
1633
|
+
| `okhstToOkhsl({ h, s, t })` | OKHST → OKHSL (`{ h, s, l }`). |
|
|
1634
|
+
| `okhslToOkhst({ h, s, l })` | OKHSL → OKHST (`{ h, s, t }`). |
|
|
1635
|
+
| `variantToOkhsl(variant)` | `ResolvedColorVariant` (stores `t`) → `{ h, s, l, alpha }` for rendering. |
|
|
1636
|
+
| `REF_EPS` | Reference epsilon (`0.05`) for the canonical tone axis. |
|
|
1637
|
+
|
|
1638
|
+
`ResolvedColorVariant` stores `{ h, s, t, alpha }` (tone, not lightness). Use
|
|
1639
|
+
`variantToOkhsl(variant).l` to recover OKHSL lightness. See
|
|
1640
|
+
[OKHST in Glaze](okhst.md) for the model.
|
|
1641
|
+
|
|
1642
|
+
### Contrast solver
|
|
1643
|
+
|
|
1644
|
+
```ts
|
|
1645
|
+
import {
|
|
1646
|
+
findToneForContrast,
|
|
1647
|
+
findValueForMixContrast,
|
|
1648
|
+
resolveContrastForMode,
|
|
1649
|
+
resolveMinContrast,
|
|
1650
|
+
apcaContrast,
|
|
1651
|
+
} from '@tenphi/glaze';
|
|
1652
|
+
```
|
|
1653
|
+
|
|
1654
|
+
| Function | Description |
|
|
1655
|
+
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1656
|
+
| `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? }`. |
|
|
1657
|
+
| `findValueForMixContrast(opts)` | Same, but searches for a mix `value` (0–1) that meets a contrast floor between a base and a target. |
|
|
1658
|
+
| `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). |
|
|
1659
|
+
| `resolveMinContrast(value)` | Resolves a `MinContrast` (WCAG preset or number) to a numeric ratio. |
|
|
1660
|
+
| `apcaContrast(yText, yBg)` | APCA Lc magnitude (0–106) for two relative luminances. |
|
|
1661
|
+
|
|
1662
|
+
Exported constants: `APCA_PRESETS`, `APCA_HC_ENHANCEMENT` (`15`, the Enhanced Level delta), `APCA_MAX_LC` (`106`).
|
|
1663
|
+
|
|
1664
|
+
`findToneForContrast` options:
|
|
1665
|
+
|
|
1666
|
+
| Option | Default | Description |
|
|
1667
|
+
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1668
|
+
| `hue` | — | Candidate hue (0–360). |
|
|
1669
|
+
| `saturation` | — | Candidate saturation (0–1). |
|
|
1670
|
+
| `preferredTone` | — | Preferred candidate tone (0–1). Kept if it already meets the target. |
|
|
1671
|
+
| `baseLinearRgb` | — | Base color as linear sRGB tuple. |
|
|
1672
|
+
| `contrast` | — | `ResolvedContrast` (`{ metric, target }`). |
|
|
1673
|
+
| `toneRange` | `[0, 1]` | Search bounds in tone. |
|
|
1674
|
+
| `epsilon` | `1e-4` | Convergence threshold. |
|
|
1675
|
+
| `maxIterations` | `18` | Max binary-search iterations per branch. |
|
|
1676
|
+
| `initialDirection` | higher-contrast side | Direction to search first (`'lighter'` or `'darker'`). |
|
|
1677
|
+
| `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. |
|
|
1678
|
+
|
|
1679
|
+
Result: `{ tone, contrast, met, branch: 'lighter' | 'darker' | 'preferred', flipped? }`. `flipped: true` indicates the initial direction failed and the opposite direction satisfied the target.
|