@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/okhst.mdx ADDED
@@ -0,0 +1,604 @@
1
+ ---
2
+ title: Tone and OKHST
3
+ description: The contrast-uniform tone axis Glaze authors every color on, its math and guarantees, and how a tone becomes a rendered color in each scheme.
4
+ ---
5
+
6
+ import Example from '../docs-site/components/Example.astro';
7
+ import ToneRamp from '../docs-site/components/ToneRamp.tsx';
8
+ import ToneDrift from '../docs-site/components/okhst/ToneDrift.tsx';
9
+ import SchemeRamp from '../docs-site/components/okhst/SchemeRamp.tsx';
10
+ import ToneLadder from '../docs-site/components/okhst/ToneLadder.tsx';
11
+ import FloorCompare from '../docs-site/components/okhst/FloorCompare.tsx';
12
+
13
+ Glaze places every color in [OKHST](https://github.com/tenphi/okhst): OKHSL's
14
+ hue and saturation, with the lightness axis replaced by **tone** — a 0–100
15
+ axis shaped so that equal tone steps give equal WCAG contrast. This page is the
16
+ reference for the color model as Glaze applies it: the transfer math, what tone
17
+ does and does not guarantee, and how an authored tone becomes a rendered color
18
+ in each scheme. The [OKHST repository](https://github.com/tenphi/okhst) is the
19
+ canonical specification of the color space itself: transfer functions,
20
+ derivation, and invariants.
21
+
22
+ To build a palette on this model, continue to
23
+ [Designing a palette](./methodology.mdx). Every option and utility named here is
24
+ listed in the [API reference](./reference/index.md).
25
+
26
+ ## OKHSL with a tone axis
27
+
28
+ OKHST keeps OKHSL's hue (`h`, 0–360) and saturation (`s`) verbatim and swaps
29
+ the third coordinate:
30
+
31
+ | Space | Coordinates | Third coordinate |
32
+ | ----- | ----------- | ----------------------------------------------------- |
33
+ | OKHSL | `h, s, l` | `l`: perceptual lightness (toe-adjusted OKLab `L`) |
34
+ | OKHST | `h, s, t` | `t`: tone, a normalized logarithm of luminance |
35
+
36
+ You author tone on a 0–100 scale (`tone: 97`). Resolved variants and the
37
+ `{ h, s, t }` input object carry it on 0–1, like saturation (hue stays 0–360).
38
+
39
+ OKHSL lightness is perceptually even, but equal lightness steps produce uneven
40
+ contrast: the ratio between neighbors changes along the axis. Tone is shaped so
41
+ equal steps produce equal WCAG contrast. Two things follow: a ramp authored in
42
+ tone is a contrast-even ladder for free, and dark-mode inversion is a single
43
+ subtraction (`100 - t`) instead of a fitted curve.
44
+
45
+ ### Equal tone steps, equal contrast
46
+
47
+ <ToneRamp
48
+ saturation={0}
49
+ caption="Eleven neutral steps, evenly spaced in tone. The row underneath is the WCAG ratio between neighbors: 1.36:1 at every step."
50
+ />
51
+
52
+ <ToneRamp
53
+ saturation={0}
54
+ axis="lightness"
55
+ caption="The same eleven steps evenly spaced in OKHSL lightness. They look even, but the ratio between neighbors runs from 1.16:1 at the dark end up to 1.46:1 and back down to 1.29:1."
56
+ />
57
+
58
+ ## The tone transfer
59
+
60
+ For a gray (`s = 0`) at OKHSL lightness `l`, luminance has a closed form through
61
+ the OKHSL toe and the OKLab cube:
62
+
63
+ ```text
64
+ Y = toeInv(l)^3 // OKLab L = toeInv(l), cubed
65
+ l = toe(cbrt(Y)) // exact inverse
66
+ ```
67
+
68
+ Tone is a normalized natural logarithm of `Y`, offset by a small `eps`:
69
+
70
+ ```text
71
+ D = ln(1 + eps) - ln(eps)
72
+
73
+ toneFromY(Y, eps) = 100 * (ln(Y + eps) - ln(eps)) / D
74
+ yFromTone(T, eps) = exp(T / 100 * D + ln(eps)) - eps
75
+ ```
76
+
77
+ `toTone(l)` and `fromTone(t)` compose these with the gray luminance above, so
78
+ they convert between OKHSL lightness (0–1) and tone (0–100) directly. The two
79
+ directions are exact analytic inverses: a round trip is lossless to
80
+ floating-point precision. `toneFromY(0)` is 0 and `toneFromY(1)` is 100 for any
81
+ `eps`, so tone is always a clean 0–100 scale.
82
+
83
+ ### Why `eps` is 0.05
84
+
85
+ WCAG 2 contrast is `(Y_hi + 0.05) / (Y_lo + 0.05)`. With `eps = 0.05`, tone is a
86
+ normalized `ln(Y + 0.05)`, so a fixed tone difference is a fixed ratio of
87
+ `Y + 0.05` — a fixed WCAG contrast — wherever it sits on the scale. Since
88
+ `ln(1.05) - ln(0.05) = ln(21)`:
89
+
90
+ ```text
91
+ ratio(T2, T1) = (Y2 + 0.05) / (Y1 + 0.05)
92
+ = exp((T2 - T1) / 100 * ln(21))
93
+ = 21 ^ ((T2 - T1) / 100)
94
+ ```
95
+
96
+ The whole scale is 21:1, black to white, and every 10 tones multiply contrast by
97
+ `21 ^ 0.1`, about 1.36. For neutrals:
98
+
99
+ | Tone | Contrast vs. black |
100
+ | ---: | -----------------: |
101
+ | 10 | 1.36:1 |
102
+ | 20 | 1.84:1 |
103
+ | 30 | 2.49:1 |
104
+ | 40 | 3.38:1 |
105
+ | 50 | 4.58:1 |
106
+ | 60 | 6.21:1 |
107
+ | 70 | 8.42:1 |
108
+ | 80 | 11.42:1 |
109
+ | 90 | 15.49:1 |
110
+ | 100 | 21:1 |
111
+
112
+ Inverted, the tone distance between two neutrals for a target ratio `R` is
113
+ `100 * ln(R) / ln(21)`:
114
+
115
+ | Ratio | Tone distance |
116
+ | ---------------------- | ------------: |
117
+ | 3:1 (`'AA-large'`) | 36.08 |
118
+ | 4.5:1 (`'AA'`) | 49.40 |
119
+ | 7:1 (`'AAA'`) | 63.92 |
120
+
121
+ These distances are exact for neutrals only. The next section explains why.
122
+
123
+ ## Same tone, same lightness
124
+
125
+ `okhstToOkhsl({ h, s, t })` passes `h` and `s` through unchanged and sets
126
+ `l = fromTone(100 * t)`. `fromTone` depends on the tone (and `eps`) alone, and OKHSL's
127
+ `l → L` map has no hue or saturation term: `h` and `s` enter only the chroma
128
+ math. That gives OKHST its core invariant:
129
+
130
+ > A given tone yields the same OKHSL lightness for every hue and saturation.
131
+
132
+ OKHST inherits OKHSL's gamut and reversibility exactly: every `(h, s, t)` is
133
+ realizable and round-trips.
134
+
135
+ ### Uniform in lightness, not luminance
136
+
137
+ The invariant is about lightness. Equal tone gives equal WCAG and APCA contrast
138
+ only for grays: a saturated red and a saturated green at the same tone share an
139
+ OKHSL lightness but differ in real luminance `Y`, because hue, saturation, and
140
+ gamut mapping all change the final sRGB values. This **chromatic drift** is the
141
+ one approximation in the model.
142
+
143
+ <ToneDrift
144
+ rows={[
145
+ { hue: 0, saturation: 0, label: 'Neutral' },
146
+ { hue: 25, saturation: 100 },
147
+ { hue: 25, saturation: 50 },
148
+ { hue: 110, saturation: 100 },
149
+ { hue: 150, saturation: 100 },
150
+ { hue: 300, saturation: 100 },
151
+ ]}
152
+ caption="Each column is drawn at the authored tone above it. The label in each cell is its measured tone: the tone of the gray with the same luminance. Neutrals match exactly; chromatic colors drift, and less so at lower saturation."
153
+ />
154
+
155
+ At full saturation, the rows above read up to 5.6 tones darker than their tone
156
+ (hue 300, purple) and 4.1 darker (hue 25, red), up to 2.7 tones lighter
157
+ (hue 150, green), and within a tone for yellow (hue 110). Across all hues the
158
+ extremes are 5.6 tones darker, near hue 300, and 2.9 lighter, near hue 143.
159
+ Drift shrinks with saturation: hue 25 at tone 50 reads 3.9 tones dark at full
160
+ saturation and 1.6 at half.
161
+
162
+ That splits the work between two tools:
163
+
164
+ - Use **tone deltas** for visual spacing within ramps and between related UI
165
+ colors. The spacing stays even and ordered for every hue.
166
+ - Use **`contrast`** when a rendered color must meet a measured WCAG or APCA
167
+ floor. The solver is the one deliberate exception to the invariant: it moves a
168
+ color's tone per hue and saturation until the measured floor is met. See
169
+ [Contrast floors](#contrast-floors-and-verification).
170
+
171
+ ## Tone windows
172
+
173
+ Each scheme renders authored tone into a **tone window**, configured by
174
+ `lightTone` and `darkTone`:
175
+
176
+ ```ts
177
+ import { glaze } from '@tenphi/glaze';
178
+
179
+ glaze.configure({
180
+ lightTone: [10, 100],
181
+ darkTone: [15, 95],
182
+ });
183
+ ```
184
+
185
+ The window's `lo` and `hi` are **OKHSL-lightness** boundaries (0–100). Glaze
186
+ converts them to tone, positions the authored tone linearly in that tone
187
+ interval, converts the result back to lightness with the window's `eps`, and
188
+ stores it as canonical tone:
189
+
190
+ ```text
191
+ loT = toTone(lo / 100, eps)
192
+ hiT = toTone(hi / 100, eps)
193
+ l = fromTone(loT + (T / 100) * (hiT - loT), eps)
194
+ t = toTone(l) / 100 // canonical tone (0–1), REF_EPS
195
+ ```
196
+
197
+ A window takes three forms:
198
+
199
+ | Form | Meaning |
200
+ | ----------------- | ------------------------------------------------------------------------------- |
201
+ | `[lo, hi]` | Boundaries at the reference `eps`. The common form. |
202
+ | `{ lo, hi, eps }` | Boundaries plus a render curvature for this scheme. Advanced. |
203
+ | `false` | The full range `[0, 100]` at the reference `eps`: no boundaries, same tone curve. |
204
+
205
+ Endpoints clamp to 0–100. A window with `lo` above `hi`, a non-finite endpoint,
206
+ or an `eps` that isn't above 0 throws instead of quietly inverting or breaking
207
+ the scale; the rules are in
208
+ [Configuration](./reference/configuration.md#tone-windows).
209
+
210
+ ### Calibrated defaults
211
+
212
+ | | `lightTone` | `darkTone` |
213
+ | ---------- | ----------: | ---------: |
214
+ | `lo` | 10 | 15 |
215
+ | `hi` | 100 | 95 |
216
+ | `eps` | 0.05 | 0.05 |
217
+ | Tone range | 4.95–100 | 9.25–95.9 |
218
+
219
+ The floors keep mapped tones off pure black in both schemes (OKHSL lightness 10
220
+ in light, 15 in dark), and the dark ceiling keeps them short of white at
221
+ lightness 95. `eps` is pinned to the reference 0.05 so the axis stays
222
+ WCAG-uniform inside the window. Because the remap is linear in tone, it scales
223
+ distances between absolute tones uniformly: about 95% of the authored distance
224
+ in light and 86.6% in dark.
225
+
226
+ <SchemeRamp
227
+ caption="Authored tones 0 to 100 (mode 'auto') resolved in every scheme. Each label is the tone Glaze stores. Light compresses into 4.95–100; dark inverts, then compresses into 9.25–95.9; high contrast uses the full range."
228
+ />
229
+
230
+ ### High contrast uses the full range
231
+
232
+ High-contrast variants run the same math with the window forced to the full
233
+ range `[0, 100]`, keeping the window's `eps`. There is no separate high-contrast
234
+ curve and no fitted dark curve.
235
+
236
+ ### Manual contrast level
237
+
238
+ A [manual contrast level](./reference/contrast.md#manual-contrast-level) generalizes that bypass
239
+ continuously. With `contrastLevel: L` and `f = L / 100`, each boundary moves
240
+ toward the full range instead of jumping to it:
241
+
242
+ ```text
243
+ lo(f) = lo + (0 - lo) * f
244
+ hi(f) = hi + (100 - hi) * f
245
+ ```
246
+
247
+ The light default walks `[10, 100] → [0, 100]` and the dark default
248
+ `[15, 95] → [0, 100]`; at level 50 they are `[5, 100]` (tone 1.63–100) and
249
+ `[7.5, 97.5]` (tone 3.15–97.97). The render `eps` is not interpolated, and a
250
+ `false` window is already the full range, so it is level-invariant.
251
+
252
+ The continuous form applies to the normal variants only. High-contrast variants
253
+ are already at the full range, so the level does not widen them further: the
254
+ bypass is what keeps the high-contrast tier independent of the level. The level
255
+ itself is covered in
256
+ [Light, dark, and high contrast](./schemes.mdx#manual-contrast-level).
257
+
258
+ ## Reference and render epsilon
259
+
260
+ Two `eps` values play separate roles:
261
+
262
+ - **Reference eps** — `REF_EPS = 0.05`, fixed. It defines the OKHST color
263
+ space and Glaze's canonical tone. `okhst()` input, `{ h, s, t }` input, the
264
+ stored `ResolvedColorVariant.t`, tone deltas, and the contrast solver all use
265
+ it, which keeps tone comparable between schemes.
266
+ - **Render eps** — the `eps` of an object tone window. A per-scheme curvature
267
+ control that only changes how authored tone maps through that scheme's
268
+ window. It defaults to the reference value, so by default the two coincide.
269
+
270
+ When a window's `eps` differs from the reference, Glaze maps with it to land a
271
+ final OKHSL lightness, then stores `toTone(l, REF_EPS)`, so deltas and contrast
272
+ calculations stay on the reference scale. For example,
273
+ `lightTone: { lo: 10, hi: 100, eps: 0.2 }` stores authored tone 50 at 63.89
274
+ instead of 52.47: mid tones bend lighter. Most palettes should keep the default.
275
+
276
+ ## The scheme pipeline
277
+
278
+ A regular color's tone goes through one pipeline per scheme:
279
+
280
+ ```text
281
+ authored tone T (0–100)
282
+ -> adaptation mode
283
+ auto + dark invert: T' = 100 - T
284
+ light / fixed keep: T' = T
285
+ static identity; skip the window
286
+ -> remap into the scheme's tone window (full range for high contrast)
287
+ -> render curvature (window eps) -> OKHSL lightness l
288
+ -> store canonical tone t = toTone(l, REF_EPS) / 100
289
+ // variant { h, s, t, alpha }, t on 0–1
290
+ -> at the rendering edge only:
291
+ fromTone(100 * t) -> l -> sRGB / luminance
292
+ optional: a contrast floor searches tone and overrides t
293
+ ```
294
+
295
+ ### Adaptation modes
296
+
297
+ The first step is the color's `mode`. Use `auto` for surfaces and foregrounds
298
+ that should trade places between light and dark, `fixed` for brand fills and
299
+ inverse surfaces that should stay on the same side of the scale, and `static`
300
+ for colors that must not adapt.
301
+ [Light, dark, and high contrast](./schemes.mdx#adaptation-modes) has the full
302
+ table and shows each mode side by side.
303
+
304
+ **Dark tone inversion is not `autoFlip`.** Inversion is ordinary scheme
305
+ adaptation, controlled by `mode`. `autoFlip` solves a different, local problem:
306
+ it may mirror a tone delta that overshoots `[0, 100]` to the other side of its
307
+ base, or let the contrast solver try the opposite side of a base.
308
+
309
+ ### Hue and saturation pass through
310
+
311
+ Tone is the only channel OKHST adapts across schemes; `h` and `s` are authoring
312
+ inputs that pass through the tone transfer untouched. The one automatic
313
+ adjustment is `darkDesaturation`, which dark schemes apply to every color except
314
+ `static` ones. A theme, or a single color, can seed a different hue and
315
+ saturation for the dark schemes with `darkHue` / `darkSaturation`; those pick the
316
+ `h` and `s` that enter the pipeline and never change how tone is transferred.
317
+ An authored dark saturation replaces the `darkDesaturation` step instead of
318
+ stacking with it: a color's own `darkSaturation` always does, and the theme's
319
+ seed does for every color that reads it. A `from` color with no `saturation` of
320
+ its own starts from the literal's saturation rather than the seed, so it keeps
321
+ the step. `static` colors ignore all of it. The rules are in
322
+ [Light, dark, and high contrast](./schemes.mdx#dark-seed) and
323
+ [Color definitions](./reference/color-definitions.md#dark-seed-darkhue--darksaturation).
324
+
325
+ ## Tone values
326
+
327
+ A color's `tone` takes one of three kinds of value. The full syntax, including
328
+ `[normal, highContrast]` pairs, is in
329
+ [Color definitions](./reference/color-definitions.md#tone-values).
330
+
331
+ ```ts
332
+ import { glaze } from '@tenphi/glaze';
333
+
334
+ const theme = glaze(280, 30);
335
+
336
+ theme.colors({
337
+ surface: { tone: 97 }, // absolute
338
+ border: { base: 'surface', tone: '-8' }, // tone delta
339
+ deep: { tone: 'min' }, // extreme
340
+ ink: { base: 'surface', tone: 'min' }, // extreme anchored to a base
341
+ });
342
+ ```
343
+
344
+ ### Absolute tone
345
+
346
+ A number places a color on the 0–100 scale independently of every other color.
347
+ Each scheme maps it through the pipeline above, so the stored tone is not the
348
+ authored one: `surface: { tone: 97 }` is stored as 97.15 in light and, inverted
349
+ to 3 and mapped into the dark window, as 11.85 in dark. A dependent color (one
350
+ with a `base`) can still take an absolute tone; it is then mapped on its own and
351
+ the base only matters to a `contrast` floor.
352
+
353
+ ### Tone deltas
354
+
355
+ A signed string is a **tone delta**: the signed difference between a dependent
356
+ color and its base.
357
+
358
+ ```ts
359
+ border: { base: 'surface', tone: '-8' }
360
+ ```
361
+
362
+ How the delta travels depends on the dependent color's `mode`:
363
+
364
+ - **`fixed` and `static` in every scheme, and `auto` in the light schemes:**
365
+ the delta is applied to the base's resolved tone in that scheme, sign
366
+ preserved. It is an exact tone step, so for neutrals it is an exact contrast
367
+ step.
368
+ - **`auto` in the dark schemes:** the delta is applied to the base's *light*
369
+ tone as authored — with the light window's lift taken back out — and the
370
+ result is inverted and mapped through the dark window like an absolute tone.
371
+ In dark high contrast it is the base's light high-contrast tone, which has no
372
+ lift to remove. Order and direction carry over — text that sits below its
373
+ surface in light sits above it in dark — and the step scales with the dark
374
+ window's span: 86.6% of the authored delta at the default windows, on every
375
+ base (a tone-50 base steps `'+4'` to −3.5 and `'-4'` to +3.5). In dark high
376
+ contrast the window is the full range, so the step is exact, only mirrored.
377
+
378
+ Order carries over only when the base inverts too. An `auto` delta on a
379
+ `fixed` or `static` base inverts on its own while the base keeps its side, so
380
+ it can cross to the other side of the base in dark: a `'+50'` label on a
381
+ `fixed` tone-30 fill sits 50 tones above it in light and about 9 below it in
382
+ dark. Make such a dependent `fixed` as well.
383
+
384
+ If `base + delta` overshoots `[0, 100]`, `autoFlip` (on by default) mirrors the
385
+ delta to the other side of the base; if the mirror overshoots too, or `autoFlip`
386
+ is off, the delta clamps on its authored side.
387
+
388
+ ### Extremes: `'max'` and `'min'`
389
+
390
+ `'max'` is author tone 100 and `'min'` is author tone 0. They select the
391
+ corresponding end of the scheme without a magic number.
392
+
393
+ - **Without a base,** an extreme flows through the pipeline like any absolute
394
+ tone: it lands on the window edge and, under `auto`, inverts in dark — `'min'`
395
+ is the darkest color in light and the lightest in dark. Use `fixed` to keep the
396
+ same end without inverting, or `static` to pin one tone everywhere.
397
+ - **With a base,** the dark scheme takes a different path. The windows are
398
+ asymmetric, so running the extreme through the dark window would squeeze the
399
+ span between it and its base and cost contrast. Instead Glaze measures the
400
+ tone shift the light scheme produced between the base and the extreme, then
401
+ replays it against the base's resolved dark tone: mirrored under `auto` (both
402
+ ends invert), same-signed under `fixed`. Only `[0, 100]` clamping applies, so
403
+ the color may render past the dark window's edge — on purpose, since you asked
404
+ for the extreme. When the shift does not fit, the color pins at tone 100 or 0.
405
+ `static` colors are unaffected. High-contrast variants follow the same rule,
406
+ but their window is already the full range, so the replay matches the plain
407
+ mapping unless the base itself sits asymmetrically across schemes. With a
408
+ `contrast` floor, an anchored extreme's starting tone is not clamped back
409
+ into the scheme window.
410
+
411
+ ```ts
412
+ const neutral = glaze(0, 0);
413
+
414
+ neutral.colors({
415
+ bg: { tone: 60 },
416
+ fg: { base: 'bg', tone: 'max' },
417
+ });
418
+ // light: bg 62.0, fg 100.0 (shift +38.0, 3.18:1)
419
+ // dark: bg 43.9, fg 5.9 (shift -38.0, 3.18:1)
420
+ ```
421
+
422
+ A root `tone: 'max'` in the same theme lands at the dark window's edge, tone
423
+ 9.25, and drops to 2.87:1 against `bg` in dark.
424
+
425
+ ### All three, light to dark
426
+
427
+ <Example
428
+ hue={280}
429
+ saturation={30}
430
+ colors={{
431
+ surface: { tone: 97 },
432
+ border: { base: 'surface', tone: '-8' },
433
+ text: { base: 'surface', tone: '-60' },
434
+ deep: { tone: 'min' },
435
+ ink: { base: 'surface', tone: 'min' },
436
+ }}
437
+ visual="none"
438
+ />
439
+
440
+ <ToneLadder
441
+ hue={280}
442
+ saturation={30}
443
+ colors={{
444
+ surface: { tone: 97 },
445
+ border: { base: 'surface', tone: '-8' },
446
+ text: { base: 'surface', tone: '-60' },
447
+ deep: { tone: 'min' },
448
+ ink: { base: 'surface', tone: 'min' },
449
+ }}
450
+ base="surface"
451
+ schemes={['light', 'dark', 'lightContrast', 'darkContrast']}
452
+ caption="Each chip shows the stored tone, the tone difference from surface, and the measured WCAG ratio against it. In dark, the deltas shrink with the window (−8 becomes +6.9, −60 becomes +52.0), deep stops at the window edge, and ink replays its full light span past it, clamped at 100. In high contrast the window is the full range and the deltas are exact."
453
+ />
454
+
455
+ The `text` color above has no contrast floor, so its ratio follows its tone
456
+ step: 6.29:1 in light and 4.85:1 in dark. Add `contrast` when the measured
457
+ ratio matters.
458
+
459
+ ## Contrast floors and verification
460
+
461
+ Tone is the contrast solver's search axis because it is contrast-uniform: the
462
+ search converges quickly and WCAG gets a closed-form starting point. But Glaze
463
+ never assumes a chromatic color has the luminance of the gray at its tone. It
464
+ measures the real color.
465
+
466
+ `contrast` takes one spec with a pluggable metric: a WCAG ratio (a bare number,
467
+ a preset such as `'AA'`, or `{ wcag }`) or an APCA Lc target (`{ apca }`).
468
+ Forms, presets, roles, and high-contrast escalation are covered in
469
+ [Contrast solving](./contrast.mdx) and
470
+ [Contrast and high contrast](./reference/contrast.md).
471
+
472
+ ### How a floor is solved
473
+
474
+ For a color with `base` and `contrast`, in each scheme Glaze:
475
+
476
+ 1. resolves the base and the color's preferred tone for that scheme, clamped
477
+ into the scheme's tone window (anchored extremes excepted);
478
+ 2. measures the requested WCAG ratio or APCA Lc at the preferred tone, using the
479
+ color's real hue and saturation — if it already clears the floor with a
480
+ small margin (×1.01 for a WCAG ratio, +0.5 Lc for APCA, to absorb rounding
481
+ in the output formats), the tone is kept (`contrast` is a floor, not a
482
+ target);
483
+ 3. otherwise searches tone. For WCAG the search starts from the gray tone whose
484
+ luminance hits the ratio exactly — `Y = R * (Y_base + 0.05) - 0.05` on the
485
+ lighter side, `(Y_base + 0.05) / R - 0.05` on the darker — then
486
+ binary-searches against the measured chromatic luminance. For APCA it
487
+ binary-searches against the Lc target directly. The search covers the full
488
+ 0–100 range, so a demanding floor can push a color past the window, and it
489
+ aims for the same margin past the target;
490
+ 4. warns when the target is physically unreachable in the scheme.
491
+
492
+ ```ts
493
+ import { glaze } from '@tenphi/glaze';
494
+
495
+ const theme = glaze(150, 90);
496
+
497
+ theme.colors({
498
+ surface: { tone: 97, saturation: 0 },
499
+ // 49.4 tones below the surface: exactly 4.5:1 for a neutral
500
+ 'step-text': { base: 'surface', tone: '-49.4' },
501
+ // Same starting tone, but the solver measures the real color
502
+ 'floor-text': { base: 'surface', tone: '-49.4', contrast: 'AA' },
503
+ });
504
+ ```
505
+
506
+ <FloorCompare
507
+ hues={[25, 110, 150, 265, 320]}
508
+ caption="Light scheme. Each row is one hue at the neutral AA distance below a neutral surface, without and with contrast: 'AA'. Hues that read lighter than their tone fall short and are moved darker; hues that read darker already pass and keep their tone. The neutral is nudged just past 4.5:1 by the search overshoot."
509
+ />
510
+
511
+ ### APCA
512
+
513
+ `apcaContrast(yText, yBg)` implements APCA-W3 0.1.9 (simplified SAPC): a
514
+ soft clamp for low luminances and separate exponents for normal and reverse
515
+ polarity, returning a signed Lc whose magnitude the solver compares with the
516
+ target. Its inputs are APCA **screen luminances** over the gamma-encoded sRGB
517
+ channels, not WCAG relative luminance:
518
+
519
+ ```text
520
+ Ys = 0.2126 * R^2.4 + 0.7152 * G^2.4 + 0.0722 * B^2.4
521
+ ```
522
+
523
+ The soft-clamp constants are calibrated against `Ys`, so the solver feeds APCA
524
+ that basis. The function it uses is exported as
525
+ [`apcaLuminanceFromLinearRgb`](./reference/utilities.md#luminance-and-contrast),
526
+ so `apcaContrast` over its output reproduces the solver's own Lc. The
527
+ implementation omits APCA's font-size lookup that maps an Lc to
528
+ a usable text size.
529
+
530
+ ### The drift check
531
+
532
+ After all four scheme passes, Glaze verifies every color that has a `base` and
533
+ a `contrast` floor. It re-measures the color against its base in each scheme, in
534
+ the floor's own metric (APCA screen luminance for APCA, WCAG luminance for
535
+ WCAG) and with each variant's own `pastel` flag, and emits a `console.warn` when
536
+ the result drifts below the target by more than a small slack: 2% of a WCAG
537
+ ratio, or 1.5 Lc. It skips a scheme where the solver couldn't reach the floor,
538
+ which already has the solver's "cannot meet" warning with the same measured
539
+ value, and an achromatic color (saturation 0), whose luminance is exactly its
540
+ tone's. Because the solver already measures the real chromatic color, a floor
541
+ it meets passes this check, so in practice the advisory stays silent; it
542
+ remains as a safety net for the chromatic approximation. Warnings are
543
+ deduplicated through a 256-key session cache that starts over when full. Both
544
+ warnings are listed in [Configuration](./reference/configuration.md#warnings).
545
+
546
+ ## Input and output
547
+
548
+ Glaze parses OKHST wherever it takes a color value — `glaze.color()`, a color
549
+ definition's `from`, and the `bg` / `fg` of the standalone `glaze.shadow()` /
550
+ `glaze.glow()`:
551
+
552
+ ```ts
553
+ import { glaze } from '@tenphi/glaze';
554
+
555
+ glaze.color('okhst(152 95% 70%)');
556
+ glaze.color({ h: 152, s: 0.95, t: 0.7 });
557
+ ```
558
+
559
+ Both value forms reproduce the color exactly in the light scheme. The
560
+ structured form `glaze.color({ hue: 152, saturation: 95, tone: 70 })` is
561
+ different: its `tone` is an authored tone on the 0–100 scale, mapped through the
562
+ light window like a theme color, so it renders at tone 71.48. See
563
+ [Color tokens](./reference/color-tokens.md#glazecolorinput).
564
+
565
+ There is no native CSS `okhst()` function, so native exports use `oklch`,
566
+ `rgb`, or `hsl`. [Tasty](https://tasty.style) can consume Glaze's custom
567
+ serialization, so `tasty()` accepts `format: 'okhst'`, as does `glaze.format()`
568
+ for a single variant. `tokens()`, `json()`, `css()`, and `tailwind()` throw and
569
+ name a native format instead; the DTCG exports pick a color space of their own.
570
+
571
+ ```ts
572
+ const theme = glaze(280, 30);
573
+
574
+ theme.colors({ surface: { tone: 97 } });
575
+ theme.tasty({ format: 'okhst' });
576
+ // {
577
+ // '#surface': {
578
+ // '': 'okhst(280 30% 97.15%)',
579
+ // '@media(prefers-color-scheme: dark)': 'okhst(280 27% 11.85%)',
580
+ // },
581
+ // }
582
+ ```
583
+
584
+ The color formats are listed in
585
+ [Output formats](./reference/output.md#color-formats); `toTone`, `fromTone`,
586
+ `toneFromY`, `yFromTone`, `okhstToOkhsl`, `okhslToOkhst`, `variantToOkhsl`, and
587
+ `REF_EPS` are exported for your own math (see
588
+ [Utilities](./reference/utilities.md#okhst-tone-utilities)).
589
+
590
+ ## Bringing existing colors into Glaze
591
+
592
+ When you move raw CSS colors or design tokens into Glaze, preserve the source
593
+ colors first: `glaze.fromHex()` and `glaze.fromRgb()` seed a theme from a
594
+ color, `glaze.color()` takes any color value, and a color definition's `from`
595
+ places a literal color inside a theme. Then replace one-off values with root
596
+ tones, tone deltas, and contrast floors as the relationships become clear.
597
+
598
+ To carry an OKHSL lightness `L` (0–100) over as a tone, convert it with
599
+ `toTone(L / 100)`; the two are not the same number. That tone is still an
600
+ authored tone, so the light window remaps it and it renders slightly lighter:
601
+ `L` 20 becomes tone 14.36 and renders at lightness 23.8. To keep a source color
602
+ exact in light, place it with `from`, which skips the light window, or turn the
603
+ window off with `lightTone: false`. The full workflow is in
604
+ [Migration and upgrading](./migration.md#migrating-from-an-existing-color-system).