@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.
@@ -0,0 +1,550 @@
1
+ ---
2
+ title: Light, dark, and high contrast
3
+ description: How one color definition adapts to light, dark, and high-contrast schemes, and the options that steer it.
4
+ ---
5
+
6
+ import { Callout } from '@tenphi/cookbook/components';
7
+ import SchemeGrid from '../docs-site/components/SchemeGrid.tsx';
8
+ import WindowMap from '../docs-site/components/schemes/WindowMap.tsx';
9
+ import SchemeExample from '../docs-site/components/schemes/SchemeExample.astro';
10
+
11
+ You define each color once. Glaze resolves it four times — light, dark, light
12
+ high contrast, and dark high contrast — by moving its **tone** through a
13
+ per-scheme pipeline. Hue and saturation stay as you authored them, apart from a
14
+ small dark desaturation, unless you give dark a seed of its own.
15
+
16
+ <SchemeGrid caption="One theme in all four schemes. Every color is resolved by Glaze for its scheme; none is tuned by hand." />
17
+
18
+ ## Four variants per color
19
+
20
+ Every color resolves to four variants:
21
+
22
+ | Variant | Scheme | Window |
23
+ | --------------- | -------------------- | --------------------------------------------------------------------------------------- |
24
+ | `light` | Light | `lightTone`, default `[10, 100]` in OKHSL lightness (tone 4.95–100) |
25
+ | `dark` | Dark | `darkTone`, default `[15, 95]` in OKHSL lightness (tone 9.25–95.9), inverted for `auto` |
26
+ | `lightContrast` | Light, high contrast | The full range, tone 0–100 |
27
+ | `darkContrast` | Dark, high contrast | The full range, inverted for `auto` |
28
+
29
+ `theme.resolve()` always returns all four. Exports include `light` and `dark`
30
+ by default; [output modes](#output-modes) choose which variants they emit.
31
+
32
+ For a regular color, each variant runs the same pipeline:
33
+
34
+ ```text
35
+ authored tone
36
+ -> invert (100 - t) when the scheme is dark and mode is 'auto'
37
+ -> remap into the scheme's tone window (the full range in high contrast)
38
+ -> store the canonical tone; convert to OKHSL lightness when formatting
39
+ ```
40
+
41
+ The tone axis itself — why equal tone steps give equal contrast, and the
42
+ transfer math — is covered in [Tone and OKHST](./okhst.mdx).
43
+
44
+ ## Dark is an inversion
45
+
46
+ Under the default `mode: 'auto'`, dark mode is a single inversion: an authored
47
+ tone `t` becomes `100 − t`, which is then remapped into the dark window. There
48
+ is no fitted curve. Because tone is contrast-shaped, the inversion itself keeps
49
+ the authored spacing — exactly for neutrals, approximately for chromatic
50
+ colors, whose luminance drifts a little with hue and saturation. The dark window
51
+ then scales every step to its span, about 0.87× at the defaults, so order and
52
+ direction carry over but steps come out a little smaller in dark. Tone deltas
53
+ scale the same way on every base; see
54
+ [How relative tone adapts](#how-relative-tone-adapts).
55
+
56
+ A surface at tone 97 becomes a dark surface, and text 52 tones below it
57
+ becomes light text above it. Hierarchy, ladders, and borders keep their order
58
+ without a second definition.
59
+
60
+ ### Tone windows
61
+
62
+ Ordinary schemes don't use the whole tone scale. Each one has a **tone window**:
63
+
64
+ ```ts
65
+ glaze.configure({
66
+ lightTone: [10, 100], // default
67
+ darkTone: [15, 95], // default
68
+ });
69
+ ```
70
+
71
+ The bounds are OKHSL lightness values. Glaze converts them to tone — the light
72
+ window spans tone 4.95 to 100, the dark window 9.25 to 95.9 — and spreads the
73
+ whole authored `0–100` scale across that interval. The window is a remap, not a
74
+ clamp: an authored tone of 0 renders at tone 4.95 in light, and every other tone
75
+ moves proportionally. Per scheme and mode:
76
+
77
+ ```text
78
+ light: t' = remap(t, lightTone)
79
+ dark, auto: t' = remap(100 - t, darkTone)
80
+ dark, fixed: t' = remap(t, darkTone)
81
+ static: t' = t
82
+ high contrast: the same, with the window [0, 100]
83
+
84
+ remap(t, [lo, hi]) = tone(lo) + t / 100 × (tone(hi) - tone(lo))
85
+ ```
86
+
87
+ <WindowMap caption="Authored tones 0–100 (top row) and the tone Glaze stores for each in light and dark. The light window lifts the bottom of the scale; the dark window reverses it and trims both ends." />
88
+
89
+ A window takes three forms:
90
+
91
+ - `[lo, hi]` — OKHSL lightness bounds at the reference eps. The common form.
92
+ - `{ lo, hi, eps }` — the same bounds with an explicit render eps for that
93
+ scheme (the reference eps is `0.05`). Glaze still stores the result on the
94
+ reference scale, so deltas and contrast stay comparable. Advanced; most
95
+ palettes keep the default.
96
+ - `false` — the full range `[0, 100]`. This removes the boundaries, not the
97
+ tone transfer.
98
+
99
+ Set windows globally with `glaze.configure()` or per theme or token with a
100
+ config override (`glaze(280, 80, { darkTone: [10, 98] })`). The defaults and
101
+ every field are listed in [Configuration](./reference/configuration.md#tone-windows).
102
+
103
+ Some colors skip a window:
104
+
105
+ - **High-contrast variants** ignore both windows and use the full range. See
106
+ [High contrast](#high-contrast).
107
+ - **`mode: 'static'` colors** skip both windows in every scheme. See
108
+ [Adaptation modes](#adaptation-modes).
109
+ - **A color seeded with `from`** (a literal hex, `rgb()`, `oklch()`, … value)
110
+ skips the light window, so its light variant reproduces the literal exactly,
111
+ and so does its light high-contrast variant, whose window is the full range
112
+ anyway. Dark, dark high contrast, and a contrast floor still adapt it. See
113
+ [`from`](./reference/color-definitions.md#from).
114
+ - **An extreme with a base** (`tone: 'max'` / `'min'`) can land outside the dark
115
+ window. See [Extremes in dark](#extremes-in-dark).
116
+
117
+ ## Adaptation modes
118
+
119
+ A color's `mode` decides how its tone moves between schemes. In light, `auto`
120
+ and `fixed` both remap the authored tone into the light window, and `static`
121
+ keeps it as authored. They differ in dark:
122
+
123
+ | Mode | In dark | Use it for |
124
+ | ------------------ | -------------------------------------------- | --------------------------------- |
125
+ | `'auto'` (default) | Inverted, then remapped into the dark window | Surfaces, text, borders, icons |
126
+ | `'fixed'` | Remapped into the dark window, not inverted | Brand fills, CTAs, status banners |
127
+ | `'static'` | The authored tone, as in light | Logos and other exact colors |
128
+
129
+ `auto` suits anything that should trade places with its background in dark;
130
+ `fixed` keeps a color on its side of the scale, as brand fills and inverse
131
+ surfaces need.
132
+
133
+ <SchemeExample
134
+ hue={280}
135
+ saturation={60}
136
+ colors={{
137
+ 'pale-auto': { tone: 92 },
138
+ 'deep-auto': { tone: 25 },
139
+ 'pale-fixed': { tone: 92, mode: 'fixed' },
140
+ 'deep-fixed': { tone: 25, mode: 'fixed' },
141
+ 'pale-static': { tone: 92, mode: 'static' },
142
+ 'deep-static': { tone: 25, mode: 'static' },
143
+ }}
144
+ rows={[
145
+ { label: "mode: 'auto'", show: ['pale-auto', 'deep-auto'] },
146
+ { label: "mode: 'fixed'", show: ['pale-fixed', 'deep-fixed'] },
147
+ { label: "mode: 'static'", show: ['pale-static', 'deep-static'] },
148
+ ]}
149
+ caption="The same two tones under each mode. auto swaps them, fixed keeps them on their side and only remaps them into the dark window, static renders the authored tone everywhere."
150
+ />
151
+
152
+ `static` skips more than the window: it also skips
153
+ [dark desaturation](#dark-desaturation) and any [dark seed](#dark-seed), so the
154
+ color is pinned to one tone, hue, and saturation. In high-contrast variants,
155
+ `auto` still inverts and `fixed` / `static` don't.
156
+
157
+ <Callout kind="note" title="Inversion is not autoFlip">
158
+ Dark tone inversion is controlled by `mode` alone. `autoFlip` is unrelated:
159
+ it only lets an overshooting tone delta, or a contrast floor that can't be met
160
+ on the requested side, reverse around its base. See
161
+ [autoFlip](./contrast.mdx#autoflip-crossing-to-the-other-side).
162
+ </Callout>
163
+
164
+ For a worked palette that picks a mode per token — surfaces and text `auto`,
165
+ accent fills `fixed` — see [Designing a palette](./methodology.mdx).
166
+
167
+ ## How relative tone adapts
168
+
169
+ A tone delta (`'+N'` / `'-N'`) places a dependent color relative to its base,
170
+ and the base is resolved separately in each scheme. What happens to the delta
171
+ depends on the dependent's mode:
172
+
173
+ - **`auto`** — in light, the delta is applied to the base's light tone as
174
+ written. In dark, Glaze adds the delta to the base's _light_ tone as authored
175
+ — before the light window lifted it — then inverts and remaps that result
176
+ through the dark window, exactly like an authored tone. The step flips
177
+ direction, keeps its place in the ladder, and comes out the dark window's
178
+ scale times the delta on every base, about 0.87× at the defaults: `'-4'`
179
+ becomes +3.5 in dark on a tone-97 surface and on a tone-50 base alike (and
180
+ `'+4'` on the tone-50 base becomes −3.5), and a chain of deltas steps the
181
+ same way at every link. In high contrast the windows are the full range, so
182
+ the step is exact in both schemes. A base whose tone a
183
+ [contrast floor](./contrast.mdx) chose has no authored tone, so its light
184
+ tone is taken back through the light window; its own dark tone is solved
185
+ separately, so the dependent follows where the base sits in light, not where
186
+ it lands in dark.
187
+ - **`fixed`** — the delta is applied to the base's tone in each scheme with its
188
+ sign preserved. A `'+30'` label stays 30 tones lighter than its fill in light
189
+ and in dark. A label on a `fixed` fill should be `fixed` too: the inversion
190
+ follows the label's own mode, so an `auto` label inverts in dark and lands on
191
+ the other side of its fill (30 tones above it in light, 29.5 below it in
192
+ dark).
193
+ - **`static`** — the delta is applied the same way as `fixed`, to the base's
194
+ tone in each scheme, without inversion. A static dependent of an adaptive base
195
+ therefore still moves with that base; only its own tone mapping is skipped.
196
+
197
+ <SchemeExample
198
+ hue={280}
199
+ saturation={30}
200
+ colors={{
201
+ surface: { tone: 97 },
202
+ 'surface-2': { base: 'surface', tone: '-4' },
203
+ border: { base: 'surface', tone: '-12' },
204
+ text: { base: 'surface', tone: '-52' },
205
+ fill: { tone: 52, mode: 'fixed' },
206
+ 'fill-text': { base: 'fill', tone: '+30', mode: 'fixed' },
207
+ }}
208
+ schemes={['light', 'dark', 'lightContrast', 'darkContrast']}
209
+ delta
210
+ ratio
211
+ caption="Each dependent is drawn over its base, with its tone step from the base (Δ) and the measured WCAG ratio. The auto ladder flips in dark with every step about 0.87× as large; the fixed pair keeps +30 everywhere; high contrast keeps every step exact."
212
+ />
213
+
214
+ The `text` row shows why legibility belongs to `contrast`, not to a delta: the
215
+ same `'-52'` step measures 4.93:1 in light and 3.92:1 in dark. A delta is a
216
+ visual relationship; a [contrast floor](./contrast.mdx) is a guarantee that is
217
+ solved in every scheme.
218
+
219
+ ### Overshooting deltas
220
+
221
+ When `base + delta` falls outside `[0, 100]`, the delta is mirrored to the other
222
+ side of the base — `'+10'` on a tone-97 surface resolves to 87.1 in light
223
+ instead of clamping at 100. If the mirrored target is also out of range, the
224
+ original delta is kept and clamped on the authored side. This is `autoFlip`,
225
+ on by default; set `autoFlip: false` on the color (or globally) to always clamp
226
+ on the authored side. Under `mode: 'auto'` the flip is decided on the light
227
+ tones, and dark mirrors whichever side light took.
228
+
229
+ ## Extremes in dark
230
+
231
+ `tone: 'max'` and `tone: 'min'` force a color to the end of the scheme's tone
232
+ scale without a magic number. `'max'` is authored tone 100 and `'min'` is 0, so
233
+ without a `base` they go through the ordinary scheme mapping:
234
+
235
+ - Under `auto`, they invert: `'max'` is the lightest color in light (tone 100)
236
+ and the darkest in dark (tone 9.25, the bottom of the dark window).
237
+ - Under `fixed`, they keep their end: `'max'` stays the lightest (tone 95.9 in
238
+ dark).
239
+ - Under `static`, they're pinned to the absolute end in every scheme.
240
+
241
+ With a `base`, an extreme keeps its contrast with that base instead. Remapping
242
+ the extreme through the narrower dark window would squeeze the span between
243
+ the two, so Glaze measures the tone shift the light scheme applied between base
244
+ and extreme, then replays it against the base's dark tone — mirrored under
245
+ `auto`, same-signed under `fixed`.
246
+
247
+ <SchemeExample
248
+ hue={0}
249
+ saturation={0}
250
+ colors={{
251
+ bg: { tone: 60 },
252
+ fg: { base: 'bg', tone: 'max' },
253
+ top: { tone: 'max' },
254
+ bottom: { tone: 'min' },
255
+ }}
256
+ delta
257
+ ratio
258
+ caption="fg replays the light shift (+38) as -38 in dark, keeping the same ratio. The root extremes top and bottom invert and land on the window edges."
259
+ />
260
+
261
+ The replayed tone is clamped to `[0, 100]` only, so it can cross the `darkTone`
262
+ boundary — `fg` above lands at tone 5.9, below the dark window's 9.25. That is
263
+ intended: you asked for the extreme. When the shift doesn't fit above or below
264
+ the dark base, the color pins at tone 100 or 0. `static` extremes are
265
+ unaffected. High-contrast variants follow the same rule, but their window is
266
+ already the full range, so the replay matches the plain mapping unless the base
267
+ itself sits asymmetrically across schemes.
268
+
269
+ ## Hue and saturation in dark
270
+
271
+ Tone is the only channel the scheme pipeline adapts. Hue and saturation enter
272
+ it as authored, with two adjustments for the dark schemes.
273
+
274
+ ### Dark desaturation
275
+
276
+ Dark variants get a flat saturation reduction, set by `darkDesaturation`
277
+ (default `0.1`):
278
+
279
+ ```text
280
+ S_dark = S_light × (1 − darkDesaturation)
281
+ ```
282
+
283
+ It applies to `dark` and `darkContrast`, skips `static` colors, and is bypassed
284
+ entirely for a color that has an explicit dark saturation (below). Set
285
+ `darkDesaturation` globally or per instance.
286
+
287
+ <SchemeExample
288
+ hue={280}
289
+ saturation={80}
290
+ colors={{
291
+ accent: { tone: 55 },
292
+ logo: { tone: 55, mode: 'static' },
293
+ }}
294
+ value="channels"
295
+ caption="Seed saturation 80: accent loses 10% of its saturation in dark; the static logo keeps it."
296
+ />
297
+
298
+ ### Dark seed
299
+
300
+ When a uniform reduction isn't enough — a hue that turns muddy on dark
301
+ surfaces, an accent that stays loud however far you turn the global knob — give
302
+ the theme a second seed for the dark schemes:
303
+
304
+ <SchemeExample
305
+ hue={280}
306
+ saturation={80}
307
+ darkHue={250}
308
+ darkSaturation={50}
309
+ colors={{
310
+ accent: { tone: 55 },
311
+ 'accent-alt': { tone: 55, hue: '+20' },
312
+ warning: { tone: 55, hue: 40 },
313
+ link: { tone: 55, hue: '+20', darkHue: '+35' },
314
+ highlight: { tone: 55, saturation: 0.9, darkSaturation: 0.6 },
315
+ logo: { tone: 55, mode: 'static' },
316
+ }}
317
+ value="channels"
318
+ caption="Hue and saturation per scheme. Relative hues re-anchor to the dark seed, the absolute warning hue stays put, link and highlight override dark on their own, and the static logo ignores the dark seed."
319
+ />
320
+
321
+ How the dark channels resolve:
322
+
323
+ - **Both levels.** `darkHue` / `darkSaturation` exist on the seed and on each
324
+ color, and apply to `dark` and `darkContrast`. On the seed, `darkSaturation`
325
+ is `0–100` like `saturation`; on a color it is a `0–1` factor of the dark seed
326
+ saturation, like a color's `saturation`.
327
+ - **Fallbacks.** A missing dark value falls back to its light counterpart, and
328
+ a color falls back to the seed. Omitting all of them reproduces the single-seed
329
+ output exactly.
330
+ - **Relative hue follows the dark seed.** `darkHue: '+N'` is relative to the dark
331
+ seed hue, and so is a plain `hue: '+N'` with no `darkHue`, so a whole palette
332
+ rotates together.
333
+ - **Absolute hue stays absolute.** A numeric `hue` with no `darkHue` is used
334
+ verbatim in dark.
335
+ - **No double reduction.** Any explicit dark saturation, on the seed or the
336
+ color, replaces `darkDesaturation` instead of stacking with it. The number you
337
+ write is the number you get. A
338
+ [`from`](./reference/color-definitions.md#from) color with neither
339
+ `saturation` nor `darkSaturation` of its own is the exception: it starts from
340
+ the literal's saturation, ignores a seed-level `darkSaturation`, and still
341
+ gets `darkDesaturation`. Give it a `saturation` and it reads the seed again,
342
+ dark seed included.
343
+ - **`static` ignores both**, and **shadows, glows, and mixes** have no channels
344
+ of their own: they derive hue and saturation from the colors they reference,
345
+ so they inherit dark overrides automatically.
346
+
347
+ With `splitHue` output, a dark seed makes the hue custom properties
348
+ scheme-dependent, and Glaze re-declares them in the dark block — see
349
+ [Dark hues](./reference/output.md#dark-hues). The full field rules are in
350
+ [Color definitions](./reference/color-definitions.md#dark-seed-darkhue--darksaturation); prefer tuning the seed
351
+ over scattering per-color dark overrides, as
352
+ [Designing a palette](./methodology.mdx) explains.
353
+
354
+ ## High contrast
355
+
356
+ The `lightContrast` and `darkContrast` variants serve readers who ask for more
357
+ contrast — by default through `@media(prefers-contrast: more)`. They differ from
358
+ the normal variants in three ways:
359
+
360
+ 1. **No tone windows.** Both windows are bypassed and the full `[0, 100]` range
361
+ is available, so edge tones reach the edge and contrast floors have more
362
+ room to solve. `auto` still inverts; `fixed` and `static` don't.
363
+ 2. **High-contrast pairs.** Any value written as `[normal, highContrast]` takes
364
+ its second entry.
365
+ 3. **Escalated contrast floors.** Unless you write an explicit high-contrast
366
+ value, WCAG presets step up (`AA → AAA`, `AA-large → AAA-large`) and APCA
367
+ targets gain 15 Lc. A bare WCAG number (`4.5`, `{ wcag: 6 }`) and the AAA
368
+ presets are not escalated; give them an explicit pair such as `[4.5, 7]`.
369
+ See [Contrast solving](./contrast.mdx#high-contrast).
370
+
371
+ <WindowMap
372
+ rows={[
373
+ { scheme: 'light' },
374
+ { scheme: 'lightContrast' },
375
+ { scheme: 'dark' },
376
+ { scheme: 'darkContrast' },
377
+ ]}
378
+ caption="Authored tones 0–100 in each scheme. The high-contrast rows use the full scale: auto still inverts, but nothing is trimmed."
379
+ />
380
+
381
+ High-contrast variants are always resolved. Whether they're exported is up to
382
+ [output modes](#output-modes), which leave them out by default.
383
+
384
+ ### High-contrast pairs
385
+
386
+ `HCPair<T>` is either one value used in both tiers or an explicit
387
+ `[normal, highContrast]` pair:
388
+
389
+ ```ts
390
+ type HCPair<T> = T | [T, T];
391
+ ```
392
+
393
+ It is accepted by `tone`, `contrast`, shadow and glow `intensity`, and mix
394
+ `value`:
395
+
396
+ ```ts
397
+ theme.colors({
398
+ surface: { tone: 97 },
399
+ // -8 in both tiers
400
+ divider: { base: 'surface', tone: '-8' },
401
+ // -8 normal, -16 high contrast
402
+ border: { base: 'surface', tone: ['-8', '-16'] },
403
+ // APCA preset: Lc 60, escalated to 75 in high contrast
404
+ text: { base: 'surface', contrast: { apca: 'content' } },
405
+ // Explicit pair: Lc 60 normal, Lc 90 high contrast
406
+ 'text-strong': {
407
+ base: 'surface',
408
+ contrast: { apca: ['content', 'preferred'] },
409
+ },
410
+ });
411
+ ```
412
+
413
+ For `contrast`, the pair can wrap the whole spec (`[4.5, 7]`) or sit inside the
414
+ metric (`{ wcag: [4.5, 7] }`). An explicit high-contrast value turns off the
415
+ automatic WCAG promotion or APCA boost for that color.
416
+
417
+ <SchemeExample
418
+ hue={280}
419
+ saturation={30}
420
+ colors={{
421
+ surface: { tone: 97 },
422
+ border: { base: 'surface', tone: ['-12', '-24'] },
423
+ text: { base: 'surface', tone: '-45', contrast: 'AA' },
424
+ }}
425
+ schemes={['light', 'dark', 'lightContrast', 'darkContrast']}
426
+ ratio
427
+ caption="The border doubles its step through an HC pair; the text's AA floor is promoted to AAA in high contrast."
428
+ />
429
+
430
+ High contrast is not a separate palette. Add pairs where readers should get
431
+ more separation — text and content contrast, accent fills, borders, shadows
432
+ and glows, decorative ramps that must stay perceivable — and leave the rest to
433
+ the window bypass and the automatic escalation.
434
+
435
+ ## Manual contrast level
436
+
437
+ The two tiers assume contrast is a binary OS preference. When it is a setting
438
+ your users control, set `contrastLevel` to a number from `0` to `100`: the
439
+ **normal** variants slide from the palette you authored (`0`) to its
440
+ high-contrast resolution (`100`), and every level in between is resolved at
441
+ that level. The default, `'auto'`, takes the authored normal entries as they
442
+ are. The authoring work is the same: the high-contrast pairs you already wrote
443
+ are what the slider ramps toward.
444
+
445
+ `contrastLevel` is a config field, so it works globally, per theme, per token,
446
+ and through `extend()`:
447
+
448
+ ```ts
449
+ glaze.configure({ contrastLevel: 60 });
450
+ const theme = glaze(280, 80, { contrastLevel: 60 });
451
+ glaze.color('#26fcb2', { contrastLevel: 60 });
452
+ ```
453
+
454
+ <SchemeExample
455
+ visual="levels"
456
+ hue={280}
457
+ saturation={60}
458
+ colors={{
459
+ surface: { tone: 97, saturation: 0.2 },
460
+ border: { base: 'surface', tone: ['-12', '-24'], saturation: 0.3 },
461
+ text: { base: 'surface', tone: '-45', contrast: 'AA', saturation: 0.5 },
462
+ 'accent-label': { tone: 100, mode: 'fixed' },
463
+ accent: {
464
+ base: 'accent-label',
465
+ tone: '-30',
466
+ contrast: { apca: ['content', 'body'] },
467
+ mode: 'fixed',
468
+ },
469
+ }}
470
+ after={
471
+ '// Each column is this theme with a config override:\n' +
472
+ '// { contrastLevel: 0 | 25 | 50 | 75 | 100 }'
473
+ }
474
+ caption="The normal light and dark variants at five levels. Under each: the measured WCAG ratio of text and border against the surface, and the APCA Lc of the accent label on its fill, whose floor ramps from 'content' (Lc 60) to 'body' (Lc 75). Level 0 is the authored palette; level 100 equals the theme's high-contrast tier (last column)."
475
+ />
476
+
477
+ What the level moves:
478
+
479
+ - **Authored pairs** — `tone`, `contrast`, `intensity`, and mix `value` pairs
480
+ are interpolated between their two entries.
481
+ - **The tone windows** — each endpoint walks toward the full range: light
482
+ `10 → 0`, dark `15 → 0` and `95 → 100`.
483
+ - **Contrast escalation** — the normal and escalated targets are interpolated,
484
+ so `AA` at level 50 solves for 5.75:1.
485
+
486
+ The interpolated values go through the ordinary resolve, so a contrast floor is
487
+ **solved** at every level, not approximated. Hue, saturation,
488
+ `darkDesaturation`, `opacity`, and `pastel` don't change with the level.
489
+
490
+ Level `0` reproduces `'auto'` and level `100` reproduces the high-contrast
491
+ output, bit for bit. The high-contrast tier itself ignores the level:
492
+ `lightContrast` / `darkContrast` stay the true high-contrast resolution, so a
493
+ `prefers-contrast: more` block still escalates on top of the reader's chosen
494
+ level. At a global level of `100` the tier would duplicate the normal set, so
495
+ it is dropped.
496
+
497
+ A pair with no midpoint switches from its normal entry to its high-contrast one
498
+ at level 50: one that mixes kinds (`[50, 'max']`, `[50, '+20']`), or any pair
499
+ of extremes (`['max', 'min']`), which have no magnitude to blend. A
500
+ contrast-solved color is pinned to the side of its base that the nearer
501
+ endpoint (level 0 or 100) resolves to, so it normally changes side at most
502
+ once, at level 50. Where the pinned side can't reach the target, it falls back
503
+ to the other side at that level. The full rules are in
504
+ [Manual contrast level](./reference/contrast.md#manual-contrast-level).
505
+
506
+ Because `configure()` invalidates every theme cache, a runtime slider only needs
507
+ to re-export:
508
+
509
+ ```ts
510
+ slider.oninput = () => {
511
+ glaze.configure({ contrastLevel: slider.valueAsNumber });
512
+ apply(theme.css());
513
+ };
514
+ ```
515
+
516
+ `contrastLevel: 0` is the natural rest position for a slider you ship but
517
+ default off. `configure()` never clears a field by omission, so pass
518
+ `contrastLevel: 'auto'` to leave manual mode. How `.export()` treats a level,
519
+ and what happens when a dependent and its base sit at different levels, is in
520
+ [Clearing it, exporting it, base links](./reference/contrast.md#clearing-it-exporting-it-base-links).
521
+
522
+ ## Output modes
523
+
524
+ Resolution always produces four variants; `modes` decides which ones an export
525
+ includes:
526
+
527
+ ```ts
528
+ // Light only
529
+ theme.tokens({ modes: { dark: false } });
530
+
531
+ // Light + dark (the default)
532
+ theme.tokens();
533
+
534
+ // All four
535
+ theme.tokens({ modes: { dark: true, highContrast: true } });
536
+ // → { light, dark, lightContrast, darkContrast }
537
+ ```
538
+
539
+ `modes` is accepted by `tokens()`, `tasty()`, `json()`, `dtcg()`,
540
+ `dtcgResolver()`, and `tailwind()`, on themes and palettes alike. `css()` has
541
+ no `modes` option: it always returns all four declaration blocks. A per-call
542
+ `modes` overrides `glaze.configure({ modes })`, and a global `contrastLevel` of
543
+ `100` drops the high-contrast tier even when `modes` asks for it; the full
544
+ precedence is in [Output modes](./reference/output.md#output-modes).
545
+
546
+ The selectors that switch variants in [Tasty](https://tasty.style) output come
547
+ from [`states.dark` and `states.highContrast`](./reference/output.md#state-aliases)
548
+ (by default the `prefers-color-scheme: dark` and `prefers-contrast: more` media
549
+ queries). How each export lays out its variants is in
550
+ [Output formats](./reference/output.md) and [Exporting and integration](./exporting.mdx).