@tenphi/glaze 0.0.0-snapshot.63c08ea → 0.0.0-snapshot.6b78fce

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/docs/migration.md CHANGED
@@ -1,378 +1,319 @@
1
- # Migration & Integration
1
+ ---
2
+ title: Migration and upgrading
3
+ description: Move an existing color system to Glaze without renaming tokens, and upgrade between major Glaze versions.
4
+ ---
2
5
 
3
- How to plug a Glaze palette into an existing app — exporting tokens in the right shape, mapping prefixes to the names your components already consume, and migrating off a legacy color system without breaking layout, dark-mode wiring, or muscle-memory tokens.
4
-
5
- If you're starting from scratch, see [methodology.md](methodology.md) first — that's about *designing* the palette. This doc is about *consuming* it.
6
-
7
- ## Upgrading to the tone model (`lightness` → `tone`)
8
-
9
- Glaze replaced OKHSL **lightness** with a contrast-uniform **tone** axis (OKHST). The Möbius dark-mode curve is gone — dark mode is now a single tone inversion remapped into a per-mode window. See [`docs/okhst.md`](okhst.md) for the model. This is a breaking change; here's what to update.
10
-
11
- ### Rename the authoring axis
12
-
13
- `lightness` is gone. Replace it with `tone` everywhere:
14
-
15
- ```ts
16
- // before
17
- theme.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '-52' } });
18
- // after
19
- theme.colors({ surface: { tone: 97 }, text: { base: 'surface', tone: '-52' } });
20
- ```
21
-
22
- The same applies to `glaze.color({ ..., lightness })` (structured form) → `tone`, and the `{ h, s, l }` value object is unchanged (still OKHSL) — but you can now also pass `{ h, s, t }` (OKHST) or an `okhst(H S% T%)` string.
23
-
24
- Tone is **0–100** like the old lightness, but the *scale is contrast-uniform*, not perceptual-lightness-uniform. Numeric values won't land at the same OKHSL lightness — equal tone steps now give equal WCAG contrast. Re-eyeball absolute values (especially mid-range ones); relative deltas and contrast-floored tokens usually need no change because they were already contrast-driven.
25
-
26
- ### Config window shape
27
-
28
- The lightness windows became tone windows, and `darkCurve` was removed (no curve to tune). The `[lo, hi]` tuple form carries over directly:
29
-
30
- ```ts
31
- // before
32
- glaze.configure({ lightLightness: [10, 100], darkLightness: [15, 95], darkCurve: 0.5 });
33
- // after
34
- glaze.configure({
35
- lightTone: [10, 100],
36
- darkTone: [15, 95],
37
- // darkCurve removed
38
- });
39
- ```
40
-
41
- `lightLightness`/`darkLightness` → `lightTone`/`darkTone`. The window value is `[lo, hi]` (reference eps — the common form), `{ lo, hi, eps }` (advanced: explicit render curvature), or `false` to disable clamping. `false` removes the *boundaries* (full `[0, 100]` range), not the contrast-uniform tone curve. Per-token `glaze.color(value, config)` overrides use the same shape.
42
-
43
- ### The `contrast` prop now selects a metric
44
-
45
- A bare number or preset is still **WCAG** and needs no change. To use APCA or split a pair across the metric, use the object form:
46
-
47
- ```ts
48
- contrast: 4.5 // unchanged — WCAG 4.5
49
- contrast: { wcag: 6 } // explicit WCAG
50
- contrast: { apca: 60 } // APCA Lc floor
51
- contrast: { wcag: [4.5, 7] } // pair inside the metric
52
- ```
53
-
54
- ### Forcing extremes: `'max'` / `'min'`
55
-
56
- For colors that should sit at the scheme's tone extreme (pure-white knockouts, near-black scrims, deliberately faint disabled chips), reach for `tone: 'max'` / `tone: 'min'` instead of a large absolute number or a low contrast floor standing in for "push it all the way". `'max'` resolves to author tone 100, `'min'` to 0, and both flow through scheme mapping (so they invert in dark under `mode: 'auto'`). No `base` required.
57
-
58
- ```ts
59
- // before — low contrast as a proxy for "stay near the surface"
60
- 'disabled-text': { base: 'chip', tone: '+1', contrast: 1.51, mode: 'fixed' }
61
- // after — say it directly with tone
62
- 'disabled-text': { base: 'chip', tone: '+18', saturation: 0.4, autoFlip: false }
63
- ```
64
-
65
- ### The `autoFlip` prop (previously `flip`)
66
-
67
- The per-color configuration property `flip` has been renamed to `autoFlip` to align with the global `autoFlip` configuration option and to avoid confusion with dark-mode/scheme tone inversion (which is handled automatically by the system).
68
-
69
- Relative `tone` offsets that overshoot `[0, 100]` now **mirror to the other side of the base by default** (controlled by the per-color `autoFlip`, which inherits the global `autoFlip`, default `true`). Previously such offsets always clamped to the boundary. If you relied on clamping — e.g. `tone: '+48'` to stack a color up to 100 — set `autoFlip: false` on that color (or `glaze.configure({ autoFlip: false })` globally) to restore the clamping behavior. `autoFlip` also governs the contrast solver's direction (its previous sole role).
70
-
71
- ### Resolved variants store tone
72
-
73
- `ResolvedColorVariant` now exposes `t` (tone, 0–1) instead of `l`. If you read resolved internals, convert with `variantToOkhsl(variant).l`. Token/CSS/JSON output uses native formats by default (`oklch` for `tokens()` / `json()`, `okhsl` for `tasty()`); use `tasty({ format: 'okhsl' })` or `tasty({ format: 'okhst' })` for Glaze-native spaces.
74
-
75
- ### 0.16.0 — output format defaults and Tasty-only spaces
76
-
77
- **Breaking changes in 0.16.0:**
78
-
79
- | Export | Old default | New default |
80
- |---|---|---|
81
- | `tokens()` / `json()` (theme + palette) | `okhsl` | `oklch` |
82
- | Standalone `.json()` | `okhsl` | `oklch` |
83
- | `tasty()` | `okhsl` (unchanged) | `okhsl` |
84
-
85
- `'okhsl'` and the new `'okhst'` output format are **Tasty-only**. Passing either to `css()`, `tailwind()`, `tokens()`, or `json()` throws. Migrate:
86
-
87
- ```ts
88
- // before
89
- theme.tokens({ format: 'okhsl' })
90
- theme.json()
91
-
92
- // after — pick one
93
- theme.tasty({ format: 'okhsl' }) // Tasty #name keys, okhsl strings
94
- theme.tokens({ format: 'oklch' }) // native CSS (new default)
95
- ```
96
-
97
- **New:** `splitHue` on `css()` / `tasty()` (theme + palette) and standalone `color.css()` emits hue as a separate custom property for runtime re-skinning. Requires `format: 'oklch'` and every color to be pastel. See [api.md → Hue channel splitting](api.md#hue-channel-splitting-splithue).
98
-
99
- ### Export snapshots
100
-
101
- `theme.export()` / `color.export()` snapshots now carry `lightTone` / `darkTone` window objects (not `lightLightness` / `darkLightness`). Old exported JSON with the legacy keys will need its `config` block rewritten before `glaze.from()` / `glaze.colorFrom()`.
102
-
103
- ## Choosing an export
104
-
105
- Glaze emits the same resolved colors in six shapes. Pick one based on your renderer / tooling.
106
-
107
- | Method | Output shape | Use it for |
108
- |---|---|---|
109
- | `palette.tasty(options?)` | `{ '#name': { '': value, '@media(prefers-color-scheme: dark)': value, '@media(prefers-contrast: more)': value } }` | The [Tasty](https://tasty.style/docs) style system. Single object, state aliases keyed inside each token. |
110
- | `palette.tokens(options?)` | `{ light: { name: value }, dark: { name: value }, ... }` | Most CSS-in-JS systems. Per-variant flat maps, easy to feed into a `:root { ... }` selector via your framework's globals. |
111
- | `palette.css(options?)` | `{ light: '--name-color: rgb(...);', dark: '...', ... }` | Framework-free CSS / static stylesheets. Variant-grouped CSS custom property strings ready to wrap in `:root` and `prefers-color-scheme` queries. |
112
- | `palette.json(options?)` | `{ themeName: { name: { light, dark, ... } } }` | Tooling, JSON pipelines. |
113
- | `palette.dtcg(options?)` | `{ light: { name: { $type, $value } }, dark: { ... }, ... }` | W3C [DTCG 2025.10](https://www.designtokens.org/) `.tokens.json` — Figma, Tokens Studio, Style Dictionary, Terrazzo, Penpot. One document per scheme. |
114
- | `palette.dtcgResolver(options?)` | `{ version, sets, modifiers, resolutionOrder }` | W3C DTCG **Resolver-Module** — a single document describing every scheme variant as `sets` + a `scheme` modifier with a context per variant. For resolver tools such as Dispersa. |
115
- | `palette.tailwind(options?)` | `'@theme { --color-*: ... } .dark { ... } ...'` | Tailwind CSS v4. A single ready-to-paste `@theme` block plus dark / high-contrast overrides. |
116
-
117
- `tasty()`, `tokens()`, `json()`, `dtcg()`, `dtcgResolver()`, and `tailwind()` accept `modes` (`{ dark, highContrast }`). `css()` always returns all four strings (`light`, `dark`, `lightContrast`, `darkContrast`). The CSS-string exports accept `format` (`'rgb' \| 'hsl' \| 'oklch'` on `tokens`/`json`/`css`/`tailwind`; `'okhsl' \| 'okhst'` on `tasty()` only); `dtcg()` and `dtcgResolver()` use `colorSpace` (`'srgb' \| 'oklch'`) instead. See [api.md → Palette](api.md#palette) for full options.
118
-
119
- ## Wiring exports into the app
120
-
121
- ### Tasty
122
-
123
- Spread the result of `palette.tasty()` into a global style call:
124
-
125
- ```ts
126
- import type { Styles } from '@tenphi/tasty';
127
- import { useGlobalStyles } from '@tenphi/tasty';
128
- import { tastyStatic } from '@tenphi/tasty/static';
129
-
130
- export const PALETTE_TOKENS = palette.tasty({ /* prefix map */ }) as Styles;
131
-
132
- // In your root component:
133
- useGlobalStyles('body', PALETTE_TOKENS);
134
-
135
- // Or, for zero-runtime builds:
136
- tastyStatic('body', PALETTE_TOKENS);
137
- ```
138
-
139
- By default the dark / high-contrast variants are keyed by media-query states — `'@media(prefers-color-scheme: dark)'` and `'@media(prefers-contrast: more)'` — so the tokens react to the OS preference out of the box, with no extra Tasty setup.
140
-
141
- If you'd rather drive the schemes from custom aliases (e.g. a manual toggle that also falls back to the OS preference), set your own [`glaze.configure({ states })`](api.md#configuration) and register what those states *mean*:
142
-
143
- ```ts
144
- import { setGlobalPredefinedStates } from '@tenphi/tasty';
145
-
146
- // glaze.configure({ states: { dark: '@dark', highContrast: '@hc' } });
147
- setGlobalPredefinedStates({
148
- '@dark':
149
- '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
150
- '@hc':
151
- '@root(contrast=high) | (!@root(contrast) & @media(prefers-contrast: more))',
152
- });
153
- ```
154
-
155
- The state names here must match the `states` you set in [`glaze.configure({ states })`](api.md#configuration).
156
-
157
- You can also register the tokens as a Tasty recipe instead of spreading them globally:
158
-
159
- ```ts
160
- import { configure, tasty } from '@tenphi/tasty';
161
-
162
- configure({ recipes: { 'theme-tokens': PALETTE_TOKENS } });
163
-
164
- const Page = tasty({
165
- styles: { recipe: 'theme-tokens', fill: '#surface', color: '#surface-text' },
166
- });
167
- ```
168
-
169
- ### CSS custom properties
170
-
171
- ```ts
172
- const css = palette.css();
173
- const stylesheet = `
174
- :root { ${css.light} }
175
- @media (prefers-color-scheme: dark) { :root { ${css.dark} } }
176
- @media (prefers-contrast: more) { :root { ${css.lightContrast} } }
177
- @media (prefers-color-scheme: dark) and (prefers-contrast: more) {
178
- :root { ${css.darkContrast} }
179
- }
180
- `;
181
- ```
182
-
183
- Each property name is `--<prefix><name>-color` by default. Override the suffix:
184
-
185
- ```ts
186
- palette.css({ suffix: '' }); // → '--surface: rgb(...);'
187
- palette.css({ format: 'oklch' }); // → '--surface-color: oklch(...);'
188
- ```
189
-
190
- ### Framework-agnostic JSON
191
-
192
- ```ts
193
- const data = palette.json();
194
- // → { primary: { surface: { light: 'okhsl(...)', dark: 'okhsl(...)' } }, ... }
195
- ```
196
-
197
- Feed into your tooling pipeline. Each color is grouped by theme name, then by token name, then by variant — no prefix logic to undo.
198
-
199
- ### W3C DTCG (`.tokens.json`)
200
-
201
- ```ts
202
- import { writeFileSync } from 'node:fs';
203
- const dtcg = palette.dtcg();
204
-
205
- writeFileSync('tokens.light.tokens.json', JSON.stringify(dtcg.light, null, 2));
206
- if (dtcg.dark) {
207
- writeFileSync('tokens.dark.tokens.json', JSON.stringify(dtcg.dark, null, 2));
208
- }
209
- ```
210
-
211
- Each document is a spec-conformant token tree. One file per scheme is the most tool-compatible convention — Style Dictionary treats them as themes, Tokens Studio as sets, and Figma as variable modes. Use `colorSpace: 'oklch'` for wide-gamut, Glaze-native values (no `hex`); the default `'srgb'` emits components plus a `hex` hint that every reader understands. Feed the files straight into Style Dictionary v4+, Tokens Studio, or any DTCG-compatible tool — no Glaze-specific transform needed.
212
-
213
- ### W3C DTCG Resolver-Module (single document)
214
-
215
- When you want **one file** describing every scheme variant — for a resolver tool such as [Dispersa](https://github.com/dispersa-core/dispersa) — use `dtcgResolver()` instead of `dtcg()`:
216
-
217
- ```ts
218
- import { writeFileSync } from 'node:fs';
219
- const resolver = palette.dtcgResolver({ modes: { highContrast: true } });
220
-
221
- writeFileSync('resolver.json', JSON.stringify(resolver, null, 2));
222
- ```
223
-
224
- The document places the light tokens in `sets.base.sources[0]` (the default context) and emits a single `scheme` modifier with a context per variant (`light` / `dark` / `lightContrast` / `darkContrast`). Each non-default context holds that variant's exact resolved tokens — Glaze resolves `darkContrast` independently, so the four-context shape keeps every value correct (two independent modifiers would compose additively and produce wrong dark + high-contrast values). Rename the set, modifier, or contexts via `setName` / `modifierName` / `contextNames` if your resolver expects different labels. Prefer `dtcg()` when you need maximum per-file tool compatibility; prefer `dtcgResolver()` when a resolver tool consumes the document for you.
225
-
226
- ### Tailwind CSS v4
227
-
228
- ```ts
229
- const css = palette.tailwind();
230
- // Write to your CSS entry, or paste into a `@import "tailwindcss"` stylesheet:
231
- // @theme { --color-primary-surface: oklch(...); ... }
232
- // .dark { --color-primary-surface: oklch(...); ... }
233
- ```
234
-
235
- The `--color-*` namespace makes every color available as `bg-*` / `text-*` / `border-*`. Drive dark mode from the OS preference instead of a class with `darkSelector: '@media (prefers-color-scheme: dark)'` (it nests `:root` automatically). High-contrast overrides land under `.high-contrast` and `.dark.high-contrast` by default; both are omitted unless `modes.highContrast` is enabled.
236
-
237
- ## Prefix map strategies
238
-
239
- `palette.tokens()` / `tasty()` / `css()` / `dtcg()` / `tailwind()` accept a `prefix` option:
240
-
241
- | Value | Result |
242
- |---|---|
243
- | `true` (default) | Every theme prefixes its tokens with `<themeName>-`. |
244
- | `false` | No prefixes. Colliding keys produce a `console.warn`; first-write wins. |
245
- | `Record<string, string>` | Per-theme prefix overrides. Themes not listed fall back to `<themeName>-`. |
246
-
247
- The most common production pattern: **default theme unprefixed, every other theme prefixed with its name**:
248
-
249
- ```ts
250
- palette.tasty({
251
- prefix: {
252
- default: '',
253
- primary: 'primary-',
254
- success: 'success-',
255
- danger: 'danger-',
256
- warning: 'warning-',
257
- note: 'note-',
258
- },
259
- });
260
- ```
261
-
262
- This makes neutral tokens consume as `#surface`, `#border`, `#disabled-surface` (no theme namespace) while status colors live under `#danger-surface`, `#success-accent-text`, etc.
263
-
264
- ### Alias themes for legacy names
265
-
266
- Two aliases for the same theme instance produce identical token values under different prefixes — useful when you want to support a legacy token name without duplicating definitions:
267
-
268
- ```ts
269
- const palette = glaze.palette({
270
- default: defaultTheme,
271
- primary: primaryTheme,
272
- purple: primaryTheme, // legacy alias — same theme, different prefix
273
- // ...
274
- });
275
-
276
- palette.tasty({
277
- prefix: {
278
- default: '',
279
- primary: 'primary-',
280
- purple: 'purple-', // emits #purple-surface alongside #primary-surface
281
- },
282
- });
283
- ```
284
-
285
- Both `#primary-surface` and `#purple-surface` resolve to the exact same color. Drop the alias when the legacy name is no longer referenced.
286
-
287
- ### `primary` (the unprefixed alias)
288
-
289
- `glaze.palette(themes, { primary })` and the per-export `primary` option duplicate one theme's tokens *without* prefix on top of any prefix map. Equivalent to listing that theme twice with different prefixes; useful when the "primary" theme is conceptually distinct from `default` and you want both sets of unprefixed tokens.
290
-
291
- ```ts
292
- const palette = glaze.palette(
293
- { brand, accent },
294
- { primary: 'brand' },
295
- );
296
- palette.tokens();
297
- // → { light: { 'brand-surface': '...', 'surface': '...', 'accent-surface': '...' } }
298
- ```
299
-
300
- Override per call: `palette.tokens({ primary: 'accent' })`, or disable with `palette.tokens({ primary: false })`.
6
+ This page covers two kinds of move: bringing an existing CSS, design-token, or
7
+ application color system over to Glaze, and upgrading Glaze itself across a
8
+ major version. For designing a palette from scratch, see
9
+ [Designing a palette](./methodology.mdx); for choosing an export shape and
10
+ wiring it into your app, see [Exporting and integration](./exporting.mdx).
301
11
 
302
12
  ## Migrating from an existing color system
303
13
 
304
- The fastest path: **map first, design second**. Get every existing token name producing a Glaze-resolved color value (even if it's a rough first pass), wire the new palette in, then iterate on the resolved colors without touching component code.
14
+ The fastest path is **map first, design second**. Get every existing token name
15
+ producing a Glaze-resolved color (even a rough first pass), wire the new
16
+ palette in, then iterate on the resolved colors without touching component
17
+ code.
305
18
 
306
19
  ### 1. Inventory the existing tokens
307
20
 
308
- Walk your current color system and bucket every token into one of these categories:
21
+ Walk your current color system and put every token into one of these buckets:
309
22
 
310
- - **Surfaces** — backgrounds, panels, cards, banners.
311
- - **Surface text** — body text, headings, captions, labels.
312
- - **Borders / dividers / focus rings** — neutral structural lines.
313
- - **Brand fills** — solid CTA backgrounds, badges, status banners.
314
- - **Brand foregrounds** — link text, status text, icon colors on neutral backgrounds.
315
- - **Disabled** — disabled chip + label.
316
- - **Shadows / overlays** — elevation, scrims.
317
- - **One-off colors** — syntax highlighting, charts, illustrations.
23
+ - **Surfaces**: backgrounds, panels, cards, banners.
24
+ - **Surface text**: body text, headings, captions, labels.
25
+ - **Borders, dividers, focus rings**: neutral structural lines.
26
+ - **Brand fills**: solid CTA backgrounds, badges, status banners.
27
+ - **Brand foregrounds**: link text, status text, icon colors on neutral
28
+ backgrounds.
29
+ - **Disabled**: disabled chip and its label.
30
+ - **Shadows and overlays**: elevation and state layers (`shadow` / `glow`),
31
+ and fixed-alpha overlays such as scrims (`opacity`).
32
+ - **One-off colors**: syntax highlighting, charts, illustrations.
318
33
 
319
- Each bucket maps cleanly to one of the patterns in [methodology.md](methodology.md). The bucket determines the *shape* of the Glaze definition (root vs dependent, `mode: 'auto'` vs `'fixed'`, contrast-floor vs absolute tone), not the value.
34
+ Each bucket maps onto one of the patterns in
35
+ [Designing a palette](./methodology.mdx). The bucket decides the _shape_ of the
36
+ Glaze definition (root or dependent, `mode: 'auto'` or `'fixed'`, a contrast
37
+ floor or an absolute tone), not its value.
320
38
 
321
39
  ### 2. Reproduce the existing values
322
40
 
323
- Pick a Glaze definition shape that lands the new color *close to* the legacy hex in light mode. The methodology doc explains the shape per bucket; the API doc covers the levers (`tone`, `saturation`, `contrast`, `mode`, `hue`).
324
-
325
- Two tactics that make matching easier:
326
-
327
- - **Anchor strong text at the edge** instead of solving for `'AAA'`. The contrast solver stops at the floor (cr=7), which usually leaves text noticeably softer than a legacy hex like `#1a1a1a`. An absolute `tone: 2` (or wherever the legacy token sits) preserves the look.
328
- - **Use numeric `contrast` ratios** for soft / accent / disabled tokens. Presets give you the WCAG floor and nothing more — for matching a designed palette you usually want a specific perceived weight, not the floor.
41
+ Pick a definition shape that lands the new color _close to_ the legacy value in
42
+ light mode. [Designing a palette](./methodology.mdx) explains the shape per
43
+ bucket; the [Color definitions](./reference/color-definitions.md) reference
44
+ covers the levers (`tone`, `saturation`, `contrast`, `mode`, `hue`).
45
+
46
+ Three tactics make matching easier:
47
+
48
+ - **Anchor strong text at the edge** instead of solving for `'AAA'`. The
49
+ contrast solver stops at the floor, which usually leaves text noticeably
50
+ softer than the legacy value: on a white surface, a neutral
51
+ `contrast: 'AAA'` (7:1) solves to tone 36, while a legacy `#1a1a1a` sits at
52
+ tone 6.2 (17.4:1). An absolute `tone` preserves the look, but author it a
53
+ little below the measured value: the light
54
+ [tone window](./schemes.mdx#tone-windows) lifts authored tones (tone 0
55
+ renders at about 5, tone 2 at 6.9), so a neutral `tone: 1.3` renders
56
+ `#1a1a1a`. With `lightTone: false` on the theme, light tones render exactly
57
+ as authored.
58
+ - **Match the metric the old system actually used.** Numeric WCAG ratios are
59
+ useful when you reproduce a measured legacy ratio. For new content roles,
60
+ prefer the APCA presets from the methodology. For low-stakes spacing, use a
61
+ tone delta instead of inventing a contrast target. See
62
+ [Contrast solving](./contrast.mdx).
63
+ - **Pin values that are a contract with `from`.** A brand color you must honor
64
+ can be given as a literal: `{ from: '#2f5bff' }` reproduces that exact value
65
+ in the light scheme whatever the theme's seed saturation, while dark and high
66
+ contrast still adapt. Add `base` and `contrast` when it must stay legible
67
+ against something. See [`from`](./reference/color-definitions.md#from).
329
68
 
330
69
  ### 3. Keep the old token names
331
70
 
332
- Use a custom `prefix` map (and theme aliases if needed) so the names your components already consume keep working:
71
+ Use a custom `prefix` map (and [alias themes](./exporting.mdx#alias-themes-for-legacy-names)
72
+ if needed) so the names your components already consume keep working:
333
73
 
334
74
  ```ts
335
75
  // Old: components consume `#dark`, `#dark-02`, `#dark-03`.
336
76
  // New: define them in Glaze, map the prefix so they emit unchanged.
337
77
 
338
78
  defaultTheme.colors({
339
- dark: { base: 'surface', tone: 2, saturation: 0.475 },
340
- 'dark-02': { base: 'surface', tone: '-1', saturation: 0.375, contrast: [9, 11] },
341
- 'dark-03': { base: 'surface', tone: '-1', saturation: 0.24, contrast: [4.5, 5.5] },
79
+ dark: { base: 'surface', tone: 2, saturation: 0.475 },
80
+ 'dark-02': {
81
+ base: 'surface',
82
+ tone: '-1',
83
+ saturation: 0.375,
84
+ contrast: [9, 11],
85
+ },
86
+ 'dark-03': {
87
+ base: 'surface',
88
+ tone: '-1',
89
+ saturation: 0.24,
90
+ contrast: [4.5, 5.5],
91
+ },
342
92
  });
343
93
 
344
94
  palette.tasty({ prefix: { default: '' } });
345
- // → '#dark', '#dark-02', '#dark-03' — components don't change.
95
+ // → '#dark', '#dark-02', '#dark-03': components don't change.
346
96
  ```
347
97
 
348
- Once consumers are off the legacy names, rename the Glaze tokens to match your conventions.
349
-
350
- ### 4. Verify dark mode and HC before promoting
351
-
352
- Glaze gives you light/dark/HC for free, but only the light mode is matched against the legacy palette. Before promoting the migration:
353
-
354
- - Spot-check every surface, text, accent, and disabled pair in dark mode. The tone inversion plus per-color `mode` choices may produce results that *look right* in light but feel off in dark (typical fix: switch a brand color to `mode: 'fixed'`, or anchor a foreground to `surface` instead of the brand fill — see [methodology.md](methodology.md)).
355
- - If the legacy system had no high-contrast mode, audit the HC variants Glaze emits. Anywhere the resolved cr is too low or the color blows out, add an HC pair (`tone: ['-7', '-20']`, `contrast: [4.5, 7]`, etc.).
356
- - Run real screens, not just the token grid. The interaction of multiple Glaze tokens against each other (text on chip, hover bg vs. fill, disabled label on disabled chip) is where mismatches show up.
98
+ Once consumers are off the legacy names, rename the Glaze tokens to match your
99
+ conventions. [Prefix map strategies](./exporting.mdx#prefix-map-strategies)
100
+ shows every naming option with real output.
101
+
102
+ ### 4. Verify dark mode and high contrast before promoting
103
+
104
+ Glaze gives you light, dark, and high contrast for free, but only the light
105
+ scheme was matched against the legacy palette. Before you promote the
106
+ migration:
107
+
108
+ - Spot-check every surface, text, accent, and disabled pair in dark mode. The
109
+ tone inversion plus the per-color `mode` can produce results that look right
110
+ in light but feel off in dark. The usual fixes: switch a brand color to
111
+ `mode: 'fixed'`, or anchor a foreground to `surface` instead of the brand
112
+ fill (see [adaptation modes](./schemes.mdx#adaptation-modes) and
113
+ [Designing a palette](./methodology.mdx)).
114
+ - If the legacy system had no high-contrast mode, audit the high-contrast
115
+ variants Glaze emits. Wherever the resolved contrast is too low or a color
116
+ blows out, add a `[normal, highContrast]` pair (`tone: ['-7', '-20']`,
117
+ `contrast: [4.5, 7]`, and so on).
118
+ - Run real screens, not just the token grid. The interaction of several Glaze
119
+ tokens against each other (text on a chip, a hover background against its
120
+ fill, a disabled label on a disabled chip) is where mismatches show up.
357
121
 
358
122
  ### 5. Trim what `extend()` doesn't need
359
123
 
360
- After migration, mark every default-only token (borders, shadows, disabled chip, code highlighting, etc.) `inherit: false`. Colored sibling themes only need the accent + tinted-surface chain — flagging the rest cuts the emitted token set per theme dramatically.
124
+ After the migration, mark every default-only token (borders, shadows, glows,
125
+ the disabled chip, code highlighting, and so on) `inherit: false`. Colored
126
+ sibling themes created with `extend()` only need the accent and tinted-surface
127
+ chain; flagging the rest cuts the token set each theme emits dramatically.
128
+
129
+ ## Upgrading Glaze
130
+
131
+ ### 3.0 — shadows and glows
132
+
133
+ `shadow` was rebuilt so `intensity` produces the same visible change on every
134
+ surface, and `glow` was added as its mirror. Both emit a translucent pigment
135
+ whose opacity is solved, per surface and per scheme, so the composite lands an
136
+ exact **tone step** away from `bg`: darker for `shadow`, lighter for `glow`.
137
+ See [Shadows and glows](./shadows-and-glows.mdx).
138
+
139
+ What changed:
140
+
141
+ - **`intensity` is a tone step.** In 2.x it went through a `tanh` curve in
142
+ OKHSL lightness, so the same number darkened white by 9 tones, a tone-35
143
+ surface by 13.9, and a tone-6 surface by 4.4. Now `intensity: 10` is 10 tones
144
+ on every surface with 10 tones of room. A step past black (or white, for a
145
+ glow) is pinned to the strongest composite the pigment reaches, and Glaze
146
+ warns; see [Unreachable steps](./shadows-and-glows.mdx#unreachable-steps).
147
+ - **`fg` is the object, not a contrast reference.** In 2.x, strength scaled
148
+ with `|l_bg − l_fg|` and the docs pointed `fg` at `text`, which ran opposite
149
+ to the physics: a white card on a light surface got almost no shadow. Now
150
+ `fg` is the element casting the shadow; a darker object deepens it, a lighter
151
+ one softens it, and an object at the surface's tone (or no `fg`) gives
152
+ exactly `intensity`.
153
+ - **The pigment is neutral by default**: pure black for `shadow`, pure white
154
+ for `glow`. The surface keeps its hue and the output is clean: `intensity: 10`
155
+ on a white surface emits `rgb(0 0 0 / 0.1326)`, which composites to tone 90.
156
+ - **The `ShadowTuning` fields were replaced.** `saturationFactor`,
157
+ `maxSaturation`, `lightnessFactor`, `lightnessBounds`, `minGapTarget`,
158
+ `alphaMax`, and `bgHueBlend` are gone. The new knobs are `objectInfluence`,
159
+ `tint`, `reach`, and `hueBleed`, shared by `shadowTuning` and the new
160
+ `glowTuning`. The type is now `LightingTuning`; `ShadowTuning` and
161
+ `GlowTuning` remain as aliases of it.
162
+ - **`GLAZE_EXPORT_VERSION` is 2.** A version-1 theme or palette snapshot that
163
+ contains shadow colors or a `shadowTuning` now throws on restore instead of
164
+ silently re-rendering every shadow.
165
+ - **`ColorDef` has a fourth member, `GlowColorDef`.** Exhaustive `switch`es
166
+ over `def.type` need a `'glow'` branch.
167
+
168
+ How 2.x shadows map onto 3.0 (2.x steps measured with browser compositing):
169
+
170
+ | 2.x definition | 2.x step for `intensity: 10` | 3.0 equivalent |
171
+ | --- | --- | --- |
172
+ | No `fg`, light surface (tone 97–100) | ≈ 9 tones | `intensity: 9`, or keep `10` (a tone stronger) |
173
+ | No `fg`, mid surface (tone 50) | ≈ 13.6 tones | `intensity: 13.6`, or settle on one value for all surfaces |
174
+ | No `fg`, dark surface (tone 10) | ≈ 7.6 tones, and saturating | `intensity: 7.6`; dark shadows were weaker than authored and now aren't |
175
+ | `fg: 'text'` on a light surface | ≈ 7 tones | Drop `fg` and use `intensity: 7`, or point `fg` at the element and re-tune |
176
+ | `fg` = a near-white card on light | ≈ 0.3 tones (barely visible) | `fg: 'card'`, then pick `intensity` for the look you want |
177
+
178
+ Then:
179
+
180
+ 1. Replace `fg: 'text'` (or any contrast-reference `fg`) with either no `fg` or
181
+ the element that casts the shadow.
182
+ 2. Pick `intensity` as the number of tones you want. For a ladder, `4` / `8` /
183
+ `12` reads as evenly spaced on every surface with room for the deepest step.
184
+ Check the dark schemes: a white `auto` page sits at about tone 9 in dark and
185
+ at tone 0 in dark high contrast. Shadows on it deeper than about `8`–`9` (a
186
+ saturated page has a little less room) pin to black and warn in dark, and
187
+ every shadow on it stays transparent and warns in dark high contrast. Use
188
+ glows for dark elevation, on a surface that also leaves them room in light
189
+ ([Dark-mode elevation](./shadows-and-glows.mdx#dark-mode-elevation)). Leaving
190
+ a shadow token out of the dark schemes hides the pinned result but not the
191
+ warning: every color resolves in all four schemes.
192
+ 3. Delete the old fields inside `tuning` / `shadowTuning` (`saturationFactor`,
193
+ `alphaMax`, …); TypeScript flags them. A tinted pigment is
194
+ `tuning: { tint: 0.3, reach: 0.85 }`. There is no opacity cap: lower
195
+ `intensity` for a lighter overlay.
196
+ 4. Replace hand-tuned translucent white mixes (dark-mode elevation, edge
197
+ highlights, lightening state layers) with
198
+ `{ type: 'glow', bg, intensity }`. Direction is fixed per type, so a
199
+ `shadow` darkens and a `glow` lightens in light and dark alike. A glow on a
200
+ white light-mode surface has nothing to lighten and warns.
201
+ 5. Re-export snapshots. A 2.x snapshot with shadows or a `shadowTuning` throws
202
+ on restore, so re-author it. In code, rebuild the theme with 3.0 shadow defs
203
+ and call `export()`. In the JSON, fix the shadow defs, drop
204
+ `config.shadowTuning`, and set `version` to `2` (a palette snapshot has one at
205
+ the top and one per theme), then load it and export again. Snapshots without
206
+ shadows load unchanged.
207
+
208
+ `glaze.shadow()` keeps its signature with the new semantics, and `glaze.glow()`
209
+ takes the same input. See
210
+ [`glaze.shadow()` / `glaze.glow()`](./reference/utilities.md#glazeshadowinput--glazeglowinput).
211
+
212
+ ### 3.0 — even dark steps for tone deltas
213
+
214
+ In 2.x an `auto` tone delta's dark variant stepped from the base's light tone,
215
+ which already carries the light window's lift, so the lift landed in the dark
216
+ step: on a tone-50 base, `'+4'` came out −5.6 in dark and `'-4'` +1.3. In 3.0
217
+ it steps from the base's authored tone, so every dark step is the dark window's
218
+ scale times the delta (about 0.87× at the defaults: `'+4'` steps −3.5 and
219
+ `'-4'` +3.5) on every base, along chains of deltas, and for `from` colors. Dark
220
+ variants of `auto` tone-delta colors shift as a result — by up to about 4 tones
221
+ on the lowest bases, about 2 on a tone-50 base, a fraction of a tone on a light
222
+ surface — and so does anything solved, mixed, or lit from them in dark. Light
223
+ and high-contrast variants are unchanged, and `glaze.color()` tokens already
224
+ stepped this way. Re-check dark values you have pinned in tests or snapshots;
225
+ see [How relative tone adapts](./schemes.mdx#how-relative-tone-adapts).
226
+
227
+ ### 3.0 — output options
228
+
229
+ Options an output method accepted but never read are gone from its type, so
230
+ TypeScript flags them. Delete them; the output doesn't change.
231
+
232
+ - `palette.json()` takes `GlazeJsonOptions` only: no `prefix`.
233
+ - `splitHue` is gone from `palette.tokens()`, `dtcg()`, `dtcgResolver()`, and
234
+ `tailwind()` (it left `GlazePaletteExportOptions`), and from `token.token()` /
235
+ `token.tasty()`.
236
+ - `theme.tasty()` takes the new `GlazeTastyOptions`, without `prefix`.
237
+ `GlazeTokenOptions` is now just `format`, `modes`, and `states`, as taken by
238
+ `token.token()` / `token.tasty()`.
239
+ - `palette.tasty()` and `palette.css()` take the new
240
+ `GlazePaletteTastyOptions` / `GlazePaletteCssOptions`, without `name`: their
241
+ hue vars are always named after each theme.
242
+
243
+ `splitHue` also stops failing silently. With a `format` other than `'oklch'`
244
+ it now throws instead of emitting inline colors, and a color that sets its own
245
+ hue under the theme hue var's name (a `brand` color with `name: 'brand'`, or a
246
+ color named after another theme in an unprefixed palette) throws instead of
247
+ rendering at the theme's hue. Hue values in its declarations are rounded to 2
248
+ decimals, so a `from` color emits `--logo-hue: 266.16` rather than
249
+ `266.15797905637027`. See
250
+ [`splitHue`](./reference/output.md#hue-channel-splitting-splithue).
251
+
252
+ ### 2.0 — `format*` takes 0–1
253
+
254
+ The `format*` writers (`formatOkhsl`, `formatOkhst`, `formatRgb`, `formatHsl`,
255
+ `formatOklch`) used to take `s` / `l` / `t` on a 0–100 percentage scale, while
256
+ everything that _produces_ those values (`resolve()`, `variantToOkhsl`,
257
+ `srgbToOkhsl`, `oklabToOkhsl`, `okhslToSrgb`) returns them on 0–1. Composing
258
+ the two, which is the obvious thing to do, was off by 100x and failed
259
+ silently: `0.7` is a legal percentage, so you got a valid CSS string naming the
260
+ wrong (near-black) color.
261
+
262
+ The writers now take the 0–1 factors, so the whole library speaks one scale.
263
+ Drop the `* 100`:
264
+
265
+ ```diff
266
+ - formatOkhsl(v.h, v.s * 100, l * 100);
267
+ + formatOkhsl(v.h, v.s, l);
268
+
269
+ - formatOkhst(v.h, v.s * 100, v.t * 100);
270
+ + formatOkhst(v.h, v.s, v.t);
271
+ ```
272
+
273
+ Nothing else moves: `h` was always 0–360, `alpha` was always 0–1, and every
274
+ export method (`css()`, `tokens()`, `json()`, `tasty()`, `dtcg()`,
275
+ `tailwind()`, `glaze.format()`) emits the same colors, because they were
276
+ compensating internally. Dropping the redundant `×100 ÷100` round-trip shifts
277
+ float noise by an ULP, which shows up nowhere except the (meaningless) hue term
278
+ of a fully desaturated `hsl()` string. `toTone` / `fromTone` still speak the
279
+ 0–100 tone axis the authoring API takes, so divide a tone from them by 100
280
+ before passing it to `formatOkhst`.
281
+
282
+ A leftover `* 100` is no longer silent: a value above 1 cannot be a factor, so
283
+ the writers `console.warn` once per writer, and you get an obviously broken
284
+ string such as `okhsl(280 7040.68% 5000%)` instead of a plausible wrong color.
285
+ See [format writers](./reference/utilities.md#format-writers).
286
+
287
+ ### 0.14 — `lightness` became `tone`
288
+
289
+ Colors used to be authored on OKHSL lightness. They are now authored on
290
+ **tone**, a contrast-uniform 0–100 axis (see [Tone and OKHST](./okhst.mdx)):
291
+
292
+ - The `lightness` prop is gone everywhere (theme colors, `glaze.color()`
293
+ structured input, tone deltas); use `tone`. Equal tone steps give equal
294
+ WCAG contrast, so numeric values don't map to the same OKHSL lightness as
295
+ before. Re-check absolute mid-range values.
296
+ - The config windows `lightLightness` / `darkLightness` became `lightTone` /
297
+ `darkTone`, and `darkCurve` was removed.
298
+ - `ResolvedColorVariant` stores `{ h, s, t, alpha }` instead of `{ h, s, l }`.
299
+ Use `variantToOkhsl()` to recover OKHSL lightness.
300
+ - Tone deltas that overshoot `[0, 100]` mirror to the other side of the base
301
+ by default instead of clamping. Set `autoFlip: false` on the color
302
+ (or globally) to clamp.
361
303
 
362
304
  ## Common pitfalls
363
305
 
364
306
  | Symptom | Cause | Fix |
365
- |---|---|---|
366
- | Disabled state stops looking disabled in dark mode. | Alpha-tinted overlay on `surface-text` (which inverts), giving asymmetric perceived contrast. | Replace with a `mode: 'auto'` color anchored to `surface` with a numeric `contrast` (see [methodology.md → Disabled chip](methodology.md#disabled-chip-contrast-driven-for-scheme-symmetry)). |
367
- | Brand color flips to its complement in dark mode. | Default `mode: 'auto'` inverts the tone. | Set `mode: 'fixed'` so the tone is remapped (not inverted). |
368
- | Brand text washes out against the dark surface. | Foreground was anchored to `accent-surface` (the brand fill), so contrast was only enforced against that fill — not the actual surface. | Anchor `accent-text` etc. to `surface` with `mode: 'auto'`. |
369
- | Tokens look right in light, broken in HC. | The HC pass bypasses the tone window — solver runs over the full `[0, 100]` range. | Add explicit `[normal, hc]` pairs to `tone` / `contrast` for the affected tokens. |
370
- | A relative `tone` like `'+48'` lands on the *wrong* (darker) side of its base. | Overshooting offsets now mirror to the other side of the base by default (`autoFlip` inherits `autoFlip`). | Set `autoFlip: false` on the color to clamp to the boundary instead, or use `tone: 'max'`/`'min'` to force the extreme. |
371
- | `palette.tokens()` emits unexpected unprefixed names. | A `primary` was set on the palette (or per-call) and is duplicating the theme's tokens without prefix. | Pass `primary: false` to disable for that export, or rename `glaze.palette(themes, { primary })`. |
372
- | `console.warn: token "foo" collides with theme "bar"`. | Two themes resolved to the same output key under your prefix config. | Adjust the prefix map so each token is unique, or accept the first-write-wins behavior. |
373
- | `console.warn: color "X" cannot meet contrast`. | The requested contrast target is physically unreachable for the color's hue/saturation against its base. | Lower the floor, change the base, or accept the closest passing variant. Use the `name` override on standalone colors to make the warning identifiable. |
374
-
375
- ## See also
376
-
377
- - [methodology.md](methodology.md) — how to design the palette in the first place.
378
- - [api.md](api.md) — full reference for every option mentioned here.
307
+ | --- | --- | --- |
308
+ | A disabled state stops looking disabled in dark mode. | An alpha-tinted overlay on `surface-text` (which inverts) gives asymmetric perceived contrast. | Replace it with an adaptive color anchored to `surface`: a tone delta for visual spacing, or a contrast floor when one is required. See [chips and disabled states](./methodology.mdx#chips-and-disabled-states). |
309
+ | A brand fill turns dark in dark mode and stops reading as the brand. | The default `mode: 'auto'` inverts the tone. | Set `mode: 'fixed'` so the tone is remapped into the dark window, not inverted. See [adaptation modes](./schemes.mdx#adaptation-modes). |
310
+ | Brand text washes out against the dark surface. | The foreground was anchored to `accent-surface` (the brand fill), so contrast was enforced only against that fill, not against the surface it sits on. | Anchor `accent-text` and friends to `surface` with `mode: 'auto'`. |
311
+ | Tokens look right in light but broken in high contrast. | High contrast bypasses the tone window, so absolute tones and deltas land on the full `[0, 100]` range (a white `auto` page is black in dark high contrast), and floors without an explicit high-contrast value rise a tier (`'AA'` → `'AAA'`, APCA +15 Lc). | Add explicit `[normal, highContrast]` pairs to `tone` / `contrast` for the affected tokens. |
312
+ | A tone delta like `'+48'` lands on the _wrong_ (darker) side of its base. | Overshooting tone deltas mirror to the other side of the base by default (a color's `autoFlip` defaults to the global `autoFlip`, which is on). | Set `autoFlip: false` on the color to clamp to the boundary instead, or use `tone: 'max'` / `'min'` to force the extreme. |
313
+ | `palette.tokens()` emits unexpected unprefixed names. | A `primary` was set on the palette (or per call) and duplicates that theme's tokens without a prefix. | Pass `primary: false` to disable it for that export, or change `glaze.palette(themes, { primary })`. See [the `primary` alias](./exporting.mdx#the-primary-alias). |
314
+ | `glaze: token "surface" from theme "danger" collides with theme "default" — skipping.` | Two themes resolved to the same output name under your prefix config. | Adjust the prefix map so each name is unique, or accept first-write-wins. See [Collisions](./exporting.mdx#collisions). |
315
+ | `glaze: formatOkhsl() got a value above 1 …` | Pre-2.0 percentage-scale input to a `format*` writer (a leftover `* 100`). | Pass the 0–1 factors the converters return; see [2.0 — `format*` takes 0–1](#20--format-takes-01). |
316
+ | `glaze: color "X" cannot meet WCAG … in light scheme (got …)` | The contrast target is physically unreachable for the color's hue and saturation against its base. The color pins to the extreme of the side it searched first, which may not be the closer one; see [When a floor can't be met](./contrast.mdx#when-a-floor-cant-be-met). | Lower the floor or change the base. If only the high-contrast schemes fail, give `contrast` an explicit, reachable high-contrast entry (`['AA', 'AA']`). On standalone colors, set `name` so the warning is identifiable; see [`name`](./reference/color-tokens.md#name). |
317
+ | `glaze: mix "X" cannot meet WCAG … against its base in light scheme (got …)` | Even the pure target doesn't reach the floor against the mix's `base`. The mix pins to the pure target, or to the pure base when its `value` is already 100; see [Contrast on mixes](./mixes.mdx#contrast-on-mixes). | Mix toward a target further from the base, or lower the floor. If only the high-contrast schemes fail, give `contrast` an explicit, reachable high-contrast entry. Keep `value` below 100 when you set a floor. |
318
+ | `glaze: shadow "X" cannot reach a 10.0-tone step …` (or `glow`) | The surface has fewer tones of room than `intensity` asks for: a glow on white, a deep shadow on near-black, or any shadow on a light `auto` page in dark high contrast (at or near tone 0 there). The overlay is pinned to its strongest composite (transparent when the surface is already at the pigment's extreme). | Lower `intensity` or give the overlay a surface with room in every scheme, and use glows for dark elevation. Otherwise expect the warning: every color resolves in all four schemes, so not using the token in a scheme doesn't silence it. See [Unreachable steps](./shadows-and-glows.mdx#unreachable-steps). |
319
+ | `glaze.themeFrom: this snapshot is export version 1 (Glaze 2) …` | A 2.x snapshot with shadow colors or `shadowTuning`; shadows changed meaning in 3.0. | Re-author the shadows and export again; see [3.0 — shadows and glows](#30--shadows-and-glows). |