@tenphi/glaze 0.0.0-snapshot.0fcd6cf → 0.0.0-snapshot.12fd135

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/mixes.mdx CHANGED
@@ -120,8 +120,11 @@ matches the "missing component" behavior of CSS `color-mix()`: a mix from
120
120
  such a white toward an accent stays in the accent's hue the whole way instead
121
121
  of sweeping through other hues.
122
122
 
123
- Only exactly zero counts. A white or black that keeps any saturation, such as
124
- `{ tone: 100 }` in a saturated theme, still carries its hue, and a mix toward
123
+ Only zero counts, along with float noise up to 1e-6. A gray given as a value,
124
+ such as `'#f5f5f5'` or `rgb(250 250 250)`, parses with a saturation of zero,
125
+ and so does an `srgb` mix that lands on a gray. A white or black that keeps
126
+ real saturation, such as `{ tone: 100 }` in a saturated theme, still carries
127
+ its hue, and a mix toward
125
128
  an accent of another hue sweeps between the two. A mix between two
126
129
  zero-saturation colors stays gray in either space; the spaces differ only in
127
130
  how lightness is spread along the ramp (see black toward white above).
@@ -142,9 +145,10 @@ how lightness is spread along the ramp (see black toward white above).
142
145
  ## Transparent mix
143
146
 
144
147
  With `blend: 'transparent'`, the output is the **target** color (its resolved
145
- hue, saturation, and tone) with `alpha = value / 100`. Nothing is blended in
146
- Glaze; the browser composites it over whatever is underneath, which should be
147
- the `base`.
148
+ hue, saturation, and tone, in the mix's gamut when their
149
+ [`pastel` flags](#pastel-mixes) differ) with `alpha = value / 100`. Nothing is
150
+ blended in Glaze; the browser composites it over whatever is underneath, which
151
+ should be the `base`.
148
152
 
149
153
  ```ts
150
154
  theme.colors({
@@ -290,6 +294,45 @@ or a color with `opacity`, used as a mix's `base` or `target` (or as a shadow's
290
294
  `bg`), counts as its opaque color: a mix toward a 10% accent wash comes out the
291
295
  same as a mix toward the accent. Chain off opaque colors.
292
296
 
297
+ ## Pastel mixes
298
+
299
+ A mix's `pastel` sets the gamut of the color it emits. Like any color, a mix
300
+ takes the theme's `pastel` unless it sets its own. Its base and target keep
301
+ their own flags, and when a flag differs from the mix's, the mix reads that
302
+ color in its own gamut through the color it paints:
303
+
304
+ - A standard mix holds every pastel color, so `value: 0` paints the base and
305
+ `value: 100` the target exactly.
306
+ - A pastel mix caps a vivid color at the pastel limit, keeping its hue and
307
+ lightness. A pastel mix toward a vivid brand color ends at the brand with
308
+ its saturation capped.
309
+ - A transparent mix's overlay is the target in the mix's gamut, and an
310
+ `srgb` mix interpolates the colors as painted, then caps the result.
311
+
312
+ ```ts
313
+ const theme = glaze(280, 80, { pastel: true });
314
+
315
+ theme.colors({
316
+ surface: { tone: 95 },
317
+ brand: { tone: 40, pastel: false },
318
+ // pastel like the theme: at value 100 it would be the brand, capped
319
+ 'brand-soft': { type: 'mix', base: 'surface', target: 'brand', value: 60 },
320
+ // standard: the brand in full at value 100
321
+ 'brand-tint': {
322
+ type: 'mix',
323
+ base: 'surface',
324
+ target: 'brand',
325
+ value: 60,
326
+ pastel: false,
327
+ },
328
+ });
329
+ ```
330
+
331
+ The contrast solver measures the color the mix paints, so a floor holds on
332
+ screen. When a pastel mix misses its floor because the cap took the target's
333
+ saturation, the [warning](./reference/configuration.md#mix-contrast-unmet)
334
+ says so; `pastel: false` on the mix paints the target in full.
335
+
293
336
  ## Mix, shadow, glow, or opacity?
294
337
 
295
338
  | You want | Use |
package/docs/okhst.mdx CHANGED
@@ -139,11 +139,8 @@ logarithm of `Y + 0.05`, so equal tone steps past 100 are still equal ratios of
139
139
  defined only up to SDR white, so a tone past 100 has no contrast meaning, and
140
140
  the contrast solver never searches there.
141
141
 
142
- [HDR glows](./shadows-and-glows.mdx#hdr-glows) are the only place Glaze goes
143
- past 100. A glow whose step would cross white, given `headroom` above 0, can
144
- carry an HDR value next to its SDR one: an opaque base plus an exposure in
145
- stops that lands it on the tone past 100, as far as the headroom allows. A
146
- resolved variant's own `t` stays within 0–1.
142
+ Only [HDR glows](./hdr.mdx) go past 100, in an HDR value kept next to the SDR
143
+ one; a resolved variant's own `t` stays within 0–1.
147
144
 
148
145
  ## Same tone, same lightness
149
146
 
@@ -317,7 +317,7 @@ child.resolve().get('soft')!.light.pastel; // → false
317
317
  ```
318
318
 
319
319
  - **Shadows and glows**: `pastel` sets the gamut used to convert the pigment for the opacity solve and for output. The surface (`bg`) keeps its own flag.
320
- - **Mixes**: `pastel` sets the gamut of the mixed result. The base and target keep their own flags.
320
+ - **Mixes**: `pastel` sets the gamut of the mixed result. The base and target keep their own flags, and the mix reads each in its gamut through the color it paints: a standard mix paints a pastel base or target exactly, and a pastel mix caps a vivid one at the pastel limit, keeping its hue and lightness. A transparent mix's overlay is the target in that gamut. The contrast solver measures the color the mix paints. See [Pastel mixes](../mixes.mdx#pastel-mixes).
321
321
  - **Color tokens**: the same field exists on both `glaze.color()` input forms and survives the `export()` / `colorFrom()` round-trip; see [Color tokens](./color-tokens.md).
322
322
  - **`splitHue`** requires every emitted color to be pastel; see [Output formats](./output.md#hue-channel-splitting-splithue).
323
323
 
@@ -409,7 +409,7 @@ theme.colors({
409
409
  - **HC pairs and the level.** `intensity` accepts `[normal, highContrast]` and is interpolated by a manual [`contrastLevel`](./contrast.md#manual-contrast-level).
410
410
  - **Output.** Shadows and glows appear in every output method next to regular colors, with an alpha component. They have no `role` (always `'surface'`), no `mode`, and no channels of their own; `ResolvedColor.mode` is `undefined` for them.
411
411
  - **Unreachable steps.** A glow on white or a deep shadow on near-black can't reach the step. The result pins to the pigment's strongest composite (full opacity, or transparent when the pigment can't move the surface at all) and emits a deduped `console.warn`. This includes the common case of a shadow on an `auto` light surface: a tone-97 surface sits at tone 3 in `darkContrast`, so `card-shadow` and `surface-hover` above pin to opaque black and warn there (`accent-pressed`, on a mid-tone accent, is unaffected). Use a glow for elevation in dark. A glow with a `headroom` can go past white instead; see [HDR values](#hdr-values-resolvedhdr).
412
- - **Errors.** `glaze: shadow "<name>" references non-existent bg "<ref>".` and `glaze: glow "<name>" fg "<ref>" references a shadow color.` (and the same for the other combinations).
412
+ - **Errors.** `glaze: shadow "<name>" is missing "bg".`, `glaze: shadow "<name>" references non-existent bg "<ref>".`, and `glaze: glow "<name>" fg "<ref>" references a shadow color.` (and the same for the other combinations).
413
413
 
414
414
  How the opacity solve works, the [object-factor table](../shadows-and-glows.mdx#object-influence), state layers, and [dark-mode elevation](../shadows-and-glows.mdx#dark-mode-elevation) are in [Shadows and glows](../shadows-and-glows.mdx). The standalone functions are in [`glaze.shadow()` / `glaze.glow()`](./utilities.md#glazeshadowinput--glazeglowinput).
415
415
 
@@ -431,12 +431,12 @@ interface GlowTuning extends LightingTuning {
431
431
  | Field | Default | Description |
432
432
  | --- | --- | --- |
433
433
  | `objectInfluence` | `0.5` | β in the object factor. `0` removes `fg`'s effect on the step (`k = 1`); `fg` still feeds `hueBleed`. `k` tops out at `1 + β`, for a black object on a white surface (shadow). |
434
- | `tint` | `0` | Pigment saturation (0–1) in the surface's hue. `0` is neutral black or white. Shows only with `reach` below `1`, because pure black and white have no hue. |
434
+ | `tint` | `0` | Pigment saturation (0–1) in the surface's hue. `0` is neutral black or white. Shows only with `reach` below `1`, because pure black and white have no hue. On a neutral surface (saturation at most `1e-4`, which covers every gray given as a value) the tint takes the object's hue when `hueBleed` is above `0`, and the pigment stays neutral otherwise. |
435
435
  | `reach` | `1` | Where the pigment sits: the fraction (0–1) of the way from the surface's tone to black (shadow) or white (glow). `1` is pure black or white, the most reach. Lower values let a `tint` show and cost reach. |
436
436
  | `hueBleed` | `0` | Pull (0–1) of the pigment hue from the surface's hue toward the object's (`fg`) hue. Needs `fg`, a `tint`, and `reach` below `1` to show. |
437
- | `headroom` | `0` | Glows only. Stops above SDR white a glow may use when its step crosses white: `1` allows up to 2× white's luminance, `2` up to 4×. A finite number ≥ 0; above 2 it clamps to 2 with a warning. On a shadow's tuning it throws. See [HDR values](#hdr-values-resolvedhdr) and [Glow headroom](./configuration.md#glow-headroom). |
437
+ | `headroom` | `0` | Glows only. Stops above SDR white a glow may use when its step crosses white: `1` allows up to 2× white in each linear channel, `2` up to 4×. A finite number ≥ 0; above 2 it clamps to 2 with a warning. On a shadow's tuning it throws. See [HDR values](#hdr-values-resolvedhdr) and [Glow headroom](./configuration.md#glow-headroom). |
438
438
 
439
- `tint`, `reach`, and `hueBleed` are clamped to 0–1. Each field resolves separately, later wins:
439
+ `tint`, `reach`, and `hueBleed` are clamped to 0–1. A field that is set must be a finite number, or the tuning throws (`glaze: shadowTuning.reach must be a finite number (got NaN).`); a field set to `undefined` counts as unset. Each field resolves separately, later wins:
440
440
 
441
441
  1. The defaults above.
442
442
  2. The global `shadowTuning` (for shadows) or `glowTuning` (for glows), from `glaze.configure()`. A theme or token [config override](./configuration.md#glazeconfigoverride) that sets `shadowTuning` / `glowTuning` replaces the global object as a whole.
@@ -462,7 +462,7 @@ There is no opacity cap: when the step is reachable, it is exact. For a lighter
462
462
 
463
463
  ### HDR values (`ResolvedHdr`)
464
464
 
465
- With a `headroom` above 0, a glow whose target tone (the surface's luminance tone + `intensity × k`) passes 100 gets an HDR value on its resolved variant, next to the unchanged SDR one:
465
+ With a `headroom` above 0, a glow whose target tone (the surface's luminance tone + `intensity × k`) passes 100 while its SDR value is pinned at its brightest gets an HDR value on its resolved variant, next to the unchanged SDR one. What it is for and when it appears: [HDR glows](../hdr.mdx).
466
466
 
467
467
  ```ts
468
468
  interface ResolvedHdr {
@@ -474,11 +474,9 @@ interface ResolvedHdr {
474
474
  // ResolvedColorVariant.hdr?: ResolvedHdr
475
475
  ```
476
476
 
477
- - **Base.** What SDR paints at its brightest, taken opaque: the pigment at full opacity, or a white surface (tone 100) that no pigment can lift. The HDR color is the base's linear sRGB times `2^exposure`. `variant.t` stays at most 1.
478
- - **Exposure.** `log2(min(Y(T*) / Y(base), 2^headroom / max channel))`, with `T*` the target tone: the exact step when the headroom allows it, otherwise capped so no channel passes `2^headroom`, with a [warning](./configuration.md#shadow-or-glow-out-of-reach). A step the HDR value covers doesn't warn.
479
- - **`s` is never pastel.** The base can be any in-gamut composite, so `s` is standard OKHSL saturation even on a `pastel` variant.
480
- - **Absent elsewhere.** The `hdr` key is missing (not `undefined`) on regular colors, shadows, mixes, glows that stay below white, a glow whose pigment can't lift a non-white surface at all (`reach: 0` on a gray surface, say: SDR paints nothing, so there is nothing to expose; on a chromatic surface the `reach: 0` gray can be slightly brighter than the surface, pin at full opacity, and get an HDR value), and every glow at `headroom: 0`.
481
- - **Continuity.** A full-reach glow (the default `reach: 1`) is pinned at white, so its HDR value starts at white (`exposure` → 0) as the target passes 100. A glow with `reach` below 1 is pinned at its pigment, below white: just under 100 it stays short there and warns, and just past 100 it jumps to the exact step.
477
+ - **Base.** What SDR paints at its brightest, taken opaque: the pigment at full opacity, or a white surface (tone 100) that no pigment can lift. `s` is standard OKHSL saturation, even on a `pastel` variant. `variant.t` stays at most 1.
478
+ - **Exposure.** The HDR color is the base's linear sRGB times `2^exposure`, with `exposure = log2(min(Y(T*) / Y(base), 2^headroom / max channel))` and `T*` the target tone: the exact step when the headroom allows it, otherwise capped so no linear channel passes `2^headroom`, with a [warning](./configuration.md#shadow-or-glow-out-of-reach). A step the HDR value covers doesn't warn.
479
+ - **Absent elsewhere.** The `hdr` key is missing (not `undefined`) on regular colors, shadows, mixes, glows that stay below white, glows whose pigment can't lift a non-white surface at all, and every glow at `headroom: 0`. The edge cases: [When a glow gets an HDR value](../hdr.mdx#when-a-glow-gets-an-hdr-value) and [Crossing white](../hdr.mdx#crossing-white).
482
480
 
483
481
  ```ts
484
482
  const theme = glaze(280, 80, { glowTuning: { headroom: 1 } });
@@ -491,11 +489,11 @@ const glow = theme.resolve().get('surface-glow')!;
491
489
  glaze.format(glow.light); // 'oklch(1 0 0 / 0)' — SDR can't lift white
492
490
  glow.light.hdr?.exposure; // 0.5489…
493
491
  glaze.formatHdr(glow.light);
494
- // → 'color(srgb-linear 1.4631 1.4631 1.4631)', tone 112
492
+ // → 'color(srgb 1.1813 1.1813 1.1813)', tone 112
495
493
  glow.dark.hdr; // undefined — the dark surface leaves room below white
496
494
  ```
497
495
 
498
- Exporters emit HDR values only with `modes.hdr`; see [HDR output](./output.md#hdr-output). What HDR glows are for: [HDR glows](../shadows-and-glows.mdx#hdr-glows). Formatting: [`glaze.formatHdr()`](./utilities.md#glazeformathdrvariant-hdrformat).
496
+ [`glaze.formatHdr()`](./utilities.md#glazeformathdrvariant-hdrformat) writes it as extended `color(srgb R G B)`, and [`hdrToSrgb()` / `hdrToLinearSrgb()`](./utilities.md#hdrtosrgbhdr--hdrtolinearsrgbhdr) return its channels. Exporters emit it only with `modes.hdr`; see [HDR output](./output.md#hdr-output).
499
497
 
500
498
  ## `MixColorDef`
501
499
 
@@ -544,8 +542,8 @@ theme.colors({
544
542
  });
545
543
  ```
546
544
 
547
- - **Transparent output.** The color is the target's hue, saturation, and tone with `alpha = value / 100`. The browser composites it with `source-over` on gamma-encoded sRGB, and the contrast solve models exactly that, so a solved opacity renders at the contrast it was solved for.
548
- - **Achromatic colors.** In `'okhsl'`, a side with a saturation of exactly zero (a color defined with `saturation: 0`) has no hue, so the mix takes the other side's hue, matching CSS `color-mix()` "missing component" behavior. A white or black that keeps any saturation still carries its hue. A mix of two zero-saturation colors stays gray in either space. See [Achromatic colors](../mixes.mdx#achromatic-colors).
545
+ - **Transparent output.** The color is the target's hue, saturation, and tone (in the mix's gamut when their [`pastel` flags](#per-color-pastel) differ) with `alpha = value / 100`. The browser composites it with `source-over` on gamma-encoded sRGB, and the contrast solve models exactly that, so a solved opacity renders at the contrast it was solved for.
546
+ - **Achromatic colors.** In `'okhsl'`, a side with a saturation of zero or of float noise up to 1e-6 (a color defined with `saturation: 0`, or a gray given as a value such as `'#f5f5f5'`, which parses with zero saturation) has no hue, so the mix takes the other side's hue, matching CSS `color-mix()` "missing component" behavior. A white or black that keeps real saturation still carries its hue. A mix of two zero-saturation colors stays gray in either space. See [Achromatic colors](../mixes.mdx#achromatic-colors).
549
547
  - **Chaining.** A mix can use another mix as its `base` or `target`. A transparent mix or an `opacity` color is accepted as a mix's `base` / `target` or a shadow's or glow's `bg` / `fg`, but its alpha is ignored: its opaque color is used.
550
548
  - **`autoFlip`.** Mixes have no per-color `autoFlip`; the contrast solve uses the theme's.
551
549
  - **Adaptation.** A mix reads its base and target in each scheme, so it adapts to dark and high contrast with them. `ResolvedColor.mode` is `undefined` for mixes.
@@ -85,11 +85,13 @@ The literal color forms. They are accepted by `glaze.color()`, by [`from`](./col
85
85
  - An alpha component (`#rrggbbaa`, `#rgba`, `/ 0.8`, or any fourth component, comma- or space-separated) is dropped with a `console.warn`. Use [`opacity`](#glazecoloroverrides) instead:
86
86
 
87
87
  ```text
88
- glaze: alpha component dropped from "rgb(1 2 3 4)" (standalone
89
- color has no opacity field).
88
+ glaze: alpha component dropped from "rgb(1 2 3 4)"; use the color's
89
+ `opacity` (or a transparent mix) for translucency.
90
90
  ```
91
91
  - Value objects are recognized by their keys: `r`, `g`, `b` → RGB; `l`, `c`, `h` → OKLCh; `h`, `s`, `t` → OKHST; otherwise OKHSL.
92
- - Hue is read in degrees, bare or with `deg`. Other angle units (`turn`, `rad`, `grad`) are not rejected but misread as degrees: `hsl(0.5turn 50% 50%)` gets hue 0.5°, not 180°.
92
+ - A hue is a bare number (degrees) or takes `deg`, `turn`, `rad`, or `grad`: `hsl(0.5turn 50% 50%)` has hue 180°.
93
+ - A component may be the CSS keyword `none`, read as 0 as CSS renders a missing component: `oklch(0.97 0 none)` is a gray. Any other component that isn't a number throws (`glaze: invalid component "abc" in "hsl(abc 50% 50%)".`).
94
+ - Out-of-range values clamp, as CSS clamps them: an `rgb()` channel to 0–255, `hsl()` / `okhsl()` / `okhst()` percentages to 0–100%, `oklch()` L to 0–1 and C to at least 0. A value object clamps a 0–1 field between 1 and 1.5 the same way, but throws for one below 0 or above 1.5, and for an RGB channel outside 0–255 (below).
93
95
  - Not supported: named colors (`'red'`), relative color syntax, and `[r, g, b]` tuples.
94
96
 
95
97
  | Input | Error |
@@ -97,11 +99,13 @@ The literal color forms. They are accepted by `glaze.color()`, by [`from`](./col
97
99
  | `'red'` | `glaze: unsupported color string "red".` |
98
100
  | `'#12'` | `glaze: invalid hex color "#12".` |
99
101
  | `'rgb(38 252)'` | `glaze: expected 3 components in "rgb(38 252)".` |
102
+ | `'rgb(38 252 x)'` | `glaze: invalid component "x" in "rgb(38 252 x)".` |
100
103
  | `{ h: 152, s: 95, l: 74 }` | `glaze.color: OkhslColor s/l must be in 0–1 range. Did you mean the structured form { hue, saturation, tone } (which uses 0–100)?` |
104
+ | `{ h: 152, s: -0.1, l: 0.74 }` | `glaze.color: OkhslColor s must be 0 or more (got -0.1).` |
101
105
  | `[38, 252, 178]` | `glaze.color: RGB tuple [r, g, b] is no longer supported — use { r, g, b } instead.` |
102
106
  | `{ r: 300, g: 0, b: 0 }` | `glaze.color: RgbColor r must be a finite number in 0–255 (got 300).` |
103
107
 
104
- The OKHSL, OKHST, and OKLCh object checks reject `s`, `l`, `t`, or `c` above 1.5, which catches 0–100 input meant for the structured form. String components have no such guard (see `hsl()` above).
108
+ The OKHSL, OKHST, and OKLCh object checks reject `s`, `l`, `t`, or `c` below 0, and above 1.5, which catches 0–100 input meant for the structured form. String components have no such guard (see `hsl()` above).
105
109
 
106
110
  ## `GlazeColorOverrides`
107
111
 
@@ -211,7 +215,7 @@ brand.tailwind({ name: 'brand' });
211
215
 
212
216
  - Every output that takes `format` defaults to `'oklch'`; `dtcg()` and `dtcgResolver()` take a `colorSpace` instead (`'srgb'` by default). `json()`, `css()`, and `tailwind()` accept only the native CSS formats (`'oklch'`, `'rgb'`, `'hsl'`) and throw on `'okhsl'` / `'okhst'`; `token()` and `tasty()` accept all five. See [Color formats](./output.md#color-formats).
213
217
  - `modes` and `states` default to the global config, as on themes. `css()` ignores `modes`. See [Output modes](./output.md#output-modes).
214
- - A token is never a glow, so it never carries an [HDR value](./output.md#hdr-output): `modes.hdr`, `states.hdr`, and `hdrSelector` change nothing, and `css()` has no `hdr` option.
218
+ - A token is never a glow, so it never carries an [HDR value](../hdr.mdx): `modes.hdr`, `states.hdr`, and `hdrSelector` change nothing, and `css()` has no `hdr` option.
215
219
  - The output methods share their option types with themes, except four. `token()` and `tasty()` take `GlazeTokenOptions` — `theme.tasty()`'s options without `splitHue` and `name`. `css()` takes the `GlazeColorCssOptions` below. `tailwind()` and `dtcgResolver()` take `GlazeColorTailwindOptions` and `GlazeColorDtcgResolverOptions`: the theme types plus a required `name`. Full shapes are in [Output formats](./output.md).
216
220
 
217
221
  ### `GlazeColorCssOptions`
@@ -350,7 +354,7 @@ Set `role: 'surface'` (or an alias such as `'bg'`) for a token that is a fill wi
350
354
 
351
355
  ## `token.export(override?)` / `glaze.colorFrom(data)`
352
356
 
353
- `token.export()` returns a JSON-safe authoring snapshot: the original input, the overrides (with a token `base` exported recursively), and the effective config frozen at call time. `glaze.colorFrom()` rebuilds the token from it and pins the frozen config, so later `glaze.configure()` calls don't change the restored token.
357
+ `token.export()` returns a detached, JSON-safe authoring snapshot: the original input, the overrides (with the `base` exported recursively), and the effective config frozen at call time. `glaze.colorFrom()` rebuilds the token from it and pins the frozen config, so later `glaze.configure()` calls don't change the restored token.
354
358
 
355
359
  ```ts
356
360
  const bg = glaze.color('#1a1a2e');
@@ -402,7 +406,7 @@ const restored = glaze.colorFrom(JSON.parse(JSON.stringify(data)));
402
406
  | `overrides` | `GlazeColorOverridesExport` | The value form's overrides, when any were given. |
403
407
  | `config` | `GlazeConfigOverride` | The frozen effective config. |
404
408
 
405
- `GlazeColorInputExport` and `GlazeColorOverridesExport` have the same fields as `GlazeColorInput` and `GlazeColorOverrides`, except that a token `base` is stored as its `GlazeColorTokenExport` (a raw-value base is kept as is).
409
+ `GlazeColorInputExport` and `GlazeColorOverridesExport` have the same fields as `GlazeColorInput` and `GlazeColorOverrides`, except that a `base` is stored as its `GlazeColorTokenExport`: a raw-value base as the snapshot of the token it is wrapped in, so its config is frozen too. A snapshot written by an earlier release with a raw-value base still restores, with that base following the live config.
406
410
 
407
411
  `glaze.colorFrom()` throws when:
408
412
 
@@ -82,10 +82,10 @@ The input to `glaze.configure()`. Every field is optional.
82
82
  | `darkDesaturation` | `number` | `0.1` | Fraction (0–1) of saturation removed in `dark` and `darkContrast`. Clamps to 0–1; non-finite numbers throw. See [Saturation](#saturation). |
83
83
  | `states.dark` | `string` | `'@media(prefers-color-scheme: dark)'` | State key for dark variants in [`tasty()`](./output.md#state-aliases) output. |
84
84
  | `states.highContrast` | `string` | `'@media(prefers-contrast: more)'` | State key for high-contrast variants in `tasty()` output. |
85
- | `states.hdr` | `string` | `'@media(dynamic-range: high)'` | State key for the HDR values of glows in `tasty()` output. Used only with `modes.hdr`. |
85
+ | `states.hdr` | `string` | `'@media(dynamic-range: high)'` | State key for the HDR values of glows in `tasty()` output. Used only with `modes.hdr`. Experimental, like every CSS HDR tier. |
86
86
  | `modes.dark` | `boolean` | `true` | Emit dark variants. See [Output modes](./output.md#output-modes). |
87
87
  | `modes.highContrast` | `boolean` | `false` | Emit high-contrast variants. Independent of `contrastLevel`, except that a global level of `100` drops the tier (it would duplicate the normal one). |
88
- | `modes.hdr` | `boolean` | `false` | Emit the HDR values of glows past SDR white next to their SDR values, in every exporter. Off, the output is the same as with no `headroom` set. `css()` reads its own `hdr` option, which falls back to this. See [HDR output](./output.md#hdr-output). |
88
+ | `modes.hdr` | `boolean` | `false` | Emit the HDR values of glows past SDR white next to their SDR values, in every exporter. Off, the output is the same as with no `headroom` set. `css()` reads its own `hdr` option, which falls back to this. The CSS tiers (`css()`, `tasty()`, `tailwind()`) are [experimental](../hdr.mdx#browsers), so prefer turning it on per call, such as `theme.dtcg({ modes: { hdr: true } })`. See [HDR output](./output.md#hdr-output). |
89
89
  | `shadowTuning` | `ShadowTuning` | — | Default tuning for every `shadow` color. A per-color `tuning` merges over it field by field. Fields and defaults: [`LightingTuning`](./color-definitions.md#lightingtuning). A `headroom` here throws. |
90
90
  | `glowTuning` | `GlowTuning` | — | Default tuning for every `glow` color. Same shape and merge rule, plus [`headroom`](#glow-headroom). |
91
91
  | `autoFlip` | `boolean` | `true` | Default for each color's `autoFlip`. When on, a contrast floor that can't be met on the requested side of the base may be met on the other side, and a tone delta that overshoots `[0, 100]` mirrors to the other side of its base. When off, only the requested direction is used: an unmet floor pins the tone to that direction's extreme (with a warning) and an overshooting tone delta clamps. Mix colors have no per-color `autoFlip` and always use this value. |
@@ -142,14 +142,14 @@ Windows are validated where they enter: by `configure()` on the spot, and for a
142
142
 
143
143
  ## Glow headroom
144
144
 
145
- `glowTuning.headroom` lets a glow go past SDR white. It counts stops above white, doublings of white's luminance: `1` allows up to 2× white (tone 121.98), `2` up to 4× (tone 144.34). At the default `0` nothing changes and no variant carries an HDR value. What an HDR glow is for, and where browsers stand: [HDR glows](../shadows-and-glows.mdx#hdr-glows).
145
+ `glowTuning.headroom` lets a glow go past SDR white. It counts stops above white, doublings of white's luminance: `1` allows up to 2× white (tone 121.98), `2` up to 4× (tone 144.34). At the default `0` nothing changes and no variant carries an HDR value. What an HDR glow is for, and where browsers stand: [HDR glows](../hdr.mdx).
146
146
 
147
147
  ```ts
148
148
  glaze.configure({ glowTuning: { headroom: 1 } });
149
149
  ```
150
150
 
151
151
  - **Where it's set.** Globally (`glowTuning`), per theme (the override's `glowTuning`; a `glaze.color()` token is never a glow), per color (a glow's `tuning`), or per call (`glaze.glow({ tuning })`). A glow's `tuning.headroom` merges over the global `glowTuning` field by field. An override's `glowTuning` replaces the global object as a whole, so `glaze(280, 80, { glowTuning: { tint: 0.1 } })` drops a global `headroom`, and so does a child's `glowTuning` in `extend()`.
152
- - **When it applies.** Only to a glow whose target tone (the surface's luminance tone + `intensity × k`) passes 100, and only where SDR is pinned at its brightest: the pigment at full opacity, or a white surface (tone 100) the pigment can't lift. Such a variant gains `hdr`, an opaque base plus a gain in stops; see [`ResolvedHdr`](./color-definitions.md#hdr-values-resolvedhdr). Every scheme uses the same headroom, high contrast included.
152
+ - **When it applies.** Only to a glow whose target tone passes 100 while its SDR value is pinned at its brightest; the exact conditions are in [When a glow gets an HDR value](../hdr.mdx#when-a-glow-gets-an-hdr-value). Such a variant gains `hdr`, an opaque base plus a gain in stops; see [`ResolvedHdr`](./color-definitions.md#hdr-values-resolvedhdr). Every scheme uses the same headroom, high contrast included.
153
153
  - **Validation.** It must be a finite number ≥ 0; anything else throws. Above 2 it clamps to 2 with a [warning](#headroom-clamped), deduplicated per field and value and printed only once the whole `configure()` call, instance override, or color map has passed. A `headroom` on `shadowTuning`, a shadow's `tuning`, or `glaze.shadow()` throws: a shadow darkens toward black, and nothing goes below black.
154
154
  - **Export.** `export()` freezes `glowTuning` with the clamped headroom, and a glow's own `tuning.headroom` travels with its definition. Snapshots stay at version 2.
155
155
  - **Output.** The exporters emit HDR values only with `modes.hdr`; see [HDR output](./output.md#hdr-output).
@@ -323,22 +323,27 @@ Glaze validates a theme's definitions when it resolves — on the first `resolve
323
323
  | Relative `tone` without `base` (theme color), in either entry of a pair (`[50, '+20']` included) | `glaze: color "a" has relative "tone" without "base".` |
324
324
  | No absolute `tone`, no `from`, and no `base` | `glaze: color "a" must have either absolute "tone" (root), "from" (a literal color), or "base" (dependent).` |
325
325
  | `from` can't be parsed | `glaze: color "a" has an invalid "from" value. glaze: invalid hex color "#zzz".` |
326
+ | Malformed `contrast`, regular or mix: a misspelled preset (`'aa'`, `{ apca: 'Body' }`), a non-finite number, an object without exactly one of `wcag` / `apca` set (a key holding `undefined` is unset; other keys are ignored), or a pair without two entries | `glaze: color "a" has an invalid "contrast" "aa". Use a WCAG ratio or 'AA' / 'AAA' / 'AA-large' / 'AAA-large', { wcag: … }, { apca: … }, or a [normal, highContrast] pair of these.` |
327
+ | A color field the resolver can't place: a `tone`, `hue`, `darkHue`, `saturation`, `darkSaturation`, mix `value`, or shadow / glow `intensity` that isn't a finite number, a relative string that isn't `'+N'` / `'-N'` (`'+-5'`), or an `opacity` outside 0–1 | `glaze: color "a" has an invalid "tone" NaN.` |
328
+ | A theme seed `hue` / `saturation` (or a given `darkHue` / `darkSaturation`) that isn't a finite number, at `glaze()` | `glaze: theme seed saturation must be a finite number (got undefined).` |
326
329
  | `contrast` pair switches metric (`[4.5, { apca: 75 }]`), regular or mix | `glaze: color "a" has a "contrast" pair that switches metric (wcag → apca). A WCAG ratio and an APCA Lc are different scales; use one metric for both entries, e.g. { wcag: [normal, highContrast] }.` |
327
330
  | `base` names a missing color | `glaze: color "a" references non-existent base "nope".` |
328
331
  | `base` names a shadow or glow | `glaze: color "b" base "a" references a glow color.` |
332
+ | Shadow / glow without a `bg` | `glaze: shadow "a" is missing "bg".` (`glaze.shadow()` / `glaze.glow()`: `glaze.shadow(): "bg" is required.`) |
329
333
  | Shadow / glow `bg` or `fg` names a missing color | `glaze: shadow "a" references non-existent bg "nope".` |
330
334
  | Shadow / glow `bg` or `fg` names a shadow or glow | `glaze: glow "b" bg "a" references a shadow color.` |
331
335
  | Mix `base` names a missing color | `glaze: mix "a" references non-existent base "nope".` |
332
336
  | Mix `target` names a missing color | `glaze: mix "a" references non-existent target "nope".` |
333
337
  | Mix `base` / `target` names a shadow or glow | `glaze: mix "a" target "sh" references a shadow color.` |
334
338
  | Circular reference through `base`, `bg`, `fg`, or a mix's `base` / `target` | `glaze: circular base reference detected involving "a".` |
335
- | Non-finite or non-number `contrastLevel` other than `'auto'` (thrown by `configure()`, or when an instance with such an override resolves) | `glaze: contrastLevel must be a finite number 0–100 or 'auto' (got NaN).` |
339
+ | Non-finite or non-number `contrastLevel` other than `'auto'`, `null` included (thrown by `configure()`, or when an instance with such an override resolves) | `glaze: contrastLevel must be a finite number 0–100 or 'auto' (got NaN).` |
336
340
  | Non-finite or non-number `darkDesaturation` (same two places) | `glaze: darkDesaturation must be a finite number 0–1 (got NaN).` |
337
341
  | Tone window with `lo` above `hi` (same two places, for `lightTone` or `darkTone`) | `glaze: lightTone lo (90) is above hi (20). A window runs from its dark end to its light end: [lo, hi] with lo ≤ hi, e.g. [20, 90].` |
338
342
  | Tone window endpoint that isn't a finite number | `glaze: lightTone lo must be a finite number (got NaN).` |
339
343
  | Object tone window whose `eps` isn't a finite number above 0 and at most `1e6` (missing included) | `glaze: lightTone eps must be a finite number above 0 and at most 1e6 (got 0).` |
340
344
  | Tone window that isn't `[lo, hi]`, `{ lo, hi, eps }`, or `false` (`null` included) | `glaze: lightTone must be [lo, hi], { lo, hi, eps }, or false (got [10]).` |
341
345
  | Glow `headroom` that isn't a finite number ≥ 0: in `glowTuning` (same two places), a glow's `tuning` (at resolve), or `glaze.glow()` | `glaze: glowTuning.headroom must be a finite number ≥ 0 — stops above SDR white (got -1).` The prefix names the source (`glow "g" tuning`, `glaze.glow() tuning`), and the value is shown as written: `(got "2")`, `(got [1])`. |
346
+ | `objectInfluence`, `tint`, `reach`, or `hueBleed` set to something other than a finite number, in any tuning | `glaze: shadowTuning.reach must be a finite number (got NaN).` (prefixed like `headroom`) |
342
347
  | `headroom` in `shadowTuning`, a shadow's `tuning`, or `glaze.shadow()` | `glaze: shadowTuning.headroom is not supported — a shadow darkens toward black, and nothing goes below black. Headroom is for glows (glowTuning or a glow's tuning).` |
343
348
 
344
349
  ### Color value errors
@@ -350,8 +355,10 @@ Every place that takes a `GlazeColorValue` — a theme color's `from`, `glaze.co
350
355
  | Hex of the wrong length (not 3, 4, 6, or 8 digits) or with non-hex digits | `glaze: invalid hex color "#zzz".` |
351
356
  | A string that isn't hex or `rgb()` / `rgba()` / `hsl()` / `hsla()` / `okhsl()` / `okhst()` / `oklch()` (named colors included) | `glaze: unsupported color string "red".` |
352
357
  | A color function without exactly 3 components (alpha aside) | `glaze: expected 3 components in "rgb(1 2)".` |
358
+ | A color-function component that isn't a number (or `none`), or has a unit it can't take | `glaze: invalid component "abc" in "hsl(abc 50% 50%)".` |
353
359
  | `{ h, s, l }` with a non-finite field | `glaze.color: OkhslColor h/s/l must be finite numbers.` |
354
360
  | `{ h, s, l }` with `s` or `l` above 1.5 | `glaze.color: OkhslColor s/l must be in 0–1 range. Did you mean the structured form { hue, saturation, tone } (which uses 0–100)?` |
361
+ | `{ h, s, l }`, `{ h, s, t }`, or `{ l, c, h }` with a 0–1 field below 0 | `glaze.color: OkhslColor s must be 0 or more (got -0.1).` (`OkhstColor` / `OklchColor` likewise) |
355
362
  | `{ h, s, t }` with a non-finite field, or `s` / `t` above 1.5 | `glaze.color: OkhstColor h/s/t must be finite numbers.` / `glaze.color: OkhstColor s/t must be in 0–1 range. …` |
356
363
  | `{ r, g, b }` with a channel outside 0–255 | `glaze.color: RgbColor r must be a finite number in 0–255 (got 300).` |
357
364
  | `{ l, c, h }` with a non-finite field, or `l` / `c` above 1.5 | `glaze.color: OklchColor l/c/h must be finite numbers.` / `glaze.color: OklchColor l/c must be in 0–1 range (matching oklch() strings).` |
@@ -391,7 +398,7 @@ A tone delta that overshoots `[0, 100]` mirrors to the other side of its base wh
391
398
  | A regular color's `contrast` floor is out of reach | Pins to the extreme of the side searched first; [contrast unmet](#contrast-unmet) warning. |
392
399
  | A mix's `contrast` floor is out of reach | Pins to the end of the base → target range it searched; [mix contrast unmet](#mix-contrast-unmet) warning. |
393
400
  | A shadow / glow step is out of the pigment's reach | Pins to the pigment's strongest composite (or stays transparent if it can't move the surface at all); [lighting](#shadow-or-glow-out-of-reach) warning. A glow whose HDR value covers the step doesn't warn. |
394
- | A glow step past white that its `headroom` cap leaves short | The HDR value pins at the cap, `2^headroom` on the brightest channel; the HDR form of the [lighting](#shadow-or-glow-out-of-reach) warning. |
401
+ | A glow step past white that its `headroom` cap leaves short | The HDR value pins at the cap, `2^headroom` on the brightest linear channel; the HDR form of the [lighting](#shadow-or-glow-out-of-reach) warning. |
395
402
  | A glow `headroom` above 2 | Clamps to 2; [headroom clamped](#headroom-clamped) warning. |
396
403
  | `contrast` and `opacity` on the same color | Resolves the floor for the opaque color; [contrast and opacity](#contrast-and-opacity) warning. |
397
404
  | A color string with an alpha component (`#rrggbbaa`, `rgb(… / a)`) where Glaze has no opacity field | Alpha dropped; [alpha dropped](#alpha-dropped) warning. |
@@ -410,11 +417,11 @@ Glaze reports problems it can recover from through `console.warn`, always prefix
410
417
  | [Shadow or glow out of reach](#shadow-or-glow-out-of-reach) | A `shadow` / `glow` step exceeds what its pigment can do, or a glow's `headroom` cap leaves its step short. | Yes |
411
418
  | [Headroom clamped](#headroom-clamped) | A glow `headroom` above 2 is clamped. | Yes |
412
419
  | [Contrast and opacity](#contrast-and-opacity) | A regular color has both `contrast` and `opacity`. | No — once per resolve |
413
- | [Alpha dropped](#alpha-dropped) | A color value carries alpha that Glaze discards. | No |
420
+ | [Alpha dropped](#alpha-dropped) | A color value carries alpha that Glaze discards. | Once per color string |
414
421
  | [Percentage scale](#percentage-scale) | A `format*` writer gets a value above 1. | Once per writer |
415
422
  | Palette collision | Two palette themes produce the same token name. See [Collision detection](./palette.md#collision-detection). | No |
416
423
 
417
- The first five share one session cache of 256 keys, which starts over when full. A key includes the color name, scheme, target, and measured value (for a clamp, the field and value), so a dev server that re-resolves on every change prints each distinct problem once. Resolved themes are cached until their definitions or the config change, so the contrast-and-opacity warning prints once per actual resolve. The alpha-dropped warning for a theme color's `from` can print several times within one resolve, since the value is parsed more than once.
424
+ The first five share one session cache of 256 keys, which starts over when full. A key includes the color name, scheme, target, and measured value (for a clamp, the field and value), so a dev server that re-resolves on every change prints each distinct problem once. Resolved themes are cached until their definitions or the config change, so the contrast-and-opacity warning prints once per actual resolve. The alpha-dropped warning keeps its own cache of 256 color strings, so it prints once per string.
418
425
 
419
426
  ### Contrast unmet
420
427
 
@@ -438,6 +445,16 @@ Even the pure target falls short; try lowering the contrast target or
438
445
 
439
446
  This one is for `accent-wash: { type: 'mix', base: 'surface', target: 'accent', value: 10, contrast: 'AA' }` in `glaze(280, 80)`, with `surface` at tone 97 and `accent` at tone 55. It uses the same margins and scheme labels as [contrast unmet](#contrast-unmet), measured between the mix and its `base`. `got` is the contrast of the value the mix settled at: the pure target, or the pure base when the value is already 100 (`got 1.00`, or `0.00` for an APCA floor). Fixes: [Contrast on mixes](../mixes.mdx#contrast-on-mixes).
440
447
 
448
+ When the pastel cap is why a mix misses (its target is a standard color outside the pastel gamut that would meet the floor painted in full), the hint names the cap:
449
+
450
+ ```text
451
+ Even the pure target falls short once the mix's pastel gamut caps its
452
+ saturation; try `pastel: false` on the mix, lowering the contrast
453
+ target, or mixing toward a color further from the base.
454
+ ```
455
+
456
+ See [Pastel mixes](../mixes.mdx#pastel-mixes).
457
+
441
458
  ### Contrast drift
442
459
 
443
460
  ```text
@@ -468,7 +485,7 @@ glaze: glow "big" cannot reach a 30.0-tone step in light scheme even
468
485
  Lower the intensity or raise `headroom`.
469
486
  ```
470
487
 
471
- At `headroom: 2` the advice reads ``Lower the intensity; `headroom` is already at its 2-stop maximum.`` A glow whose pigment can't lift a non-white surface at all (`reach: 0` on a gray surface, say) gets no HDR value and keeps the first form. On a chromatic surface a `reach: 0` pigment is a gray at the surface's tone that can be slightly brighter than the surface: it then pins at full opacity and, past white, gets an HDR value like any pinned pigment.
488
+ At `headroom: 2` the advice reads ``Lower the intensity; `headroom` is already at its 2-stop maximum.`` A glow without an HDR value, such as one whose pigment can't lift a non-white surface at all (`reach: 0` on a gray surface), keeps the first form; see [When a glow gets an HDR value](../hdr.mdx#when-a-glow-gets-an-hdr-value).
472
489
 
473
490
  ### Headroom clamped
474
491
 
@@ -492,8 +509,8 @@ Emitted during validation. For a translucent color with a floor, use a [transpar
492
509
  ### Alpha dropped
493
510
 
494
511
  ```text
495
- glaze: alpha component dropped from "#ffffff80"
496
- (standalone color has no opacity field).
512
+ glaze: alpha component dropped from "#ffffff80"; use the color's
513
+ `opacity` (or a transparent mix) for translucency.
497
514
  ```
498
515
 
499
516
  Any color string Glaze parses — a `from` value, a `glaze.color()` value, or a `glaze.shadow()` / `glaze.glow()` input — keeps only its color. Use `opacity` on a regular color, or a transparent mix, for translucency.
@@ -128,11 +128,11 @@ Without an explicit high-contrast entry, the `lightContrast` / `darkContrast` va
128
128
  | `'AA-large'`, `{ wcag: 'AA-large' }` | 3 | 4.5 (`'AAA-large'`) |
129
129
  | `'AAA'`, `'AAA-large'` | 7, 4.5 | Unchanged — already the top WCAG tier. |
130
130
  | A WCAG number (`4.5`, `{ wcag: 6 }`) | as written | Unchanged — a bare ratio has no successor tier. |
131
- | An APCA number or preset | Lc | Lc + 15, capped at 106. |
131
+ | An APCA number or preset | Lc | Lc + 15, capped at 106 (a target already above 106 is kept). |
132
132
  | An explicit pair, outer or inner | first entry | second entry, no escalation. |
133
133
 
134
134
  - **WCAG promotion** follows the spec's own Enhanced level, SC 1.4.3 → SC 1.4.6.
135
- - **APCA Enhanced Level** adds `APCA_HC_ENHANCEMENT` (15 Lc), the Lc analog of AAA over AA, and clamps the result to `APCA_MAX_LC` (106).
135
+ - **APCA Enhanced Level** adds `APCA_HC_ENHANCEMENT` (15 Lc), the Lc analog of AAA over AA, and clamps the result to `APCA_MAX_LC` (106). The cap only limits the boost: a normal target already above 106 stays as it is, never lower than the normal tier's.
136
136
  - **An explicit high-contrast value** in the outer `contrast` pair or the inner `wcag` / `apca` pair replaces the automatic step. Use one to hold a ceiling. APCA caps large or bold text at Lc 90 to avoid glare, so for a heading write `{ apca: ['preferred', 'preferred'] }` rather than letting high contrast boost it past 90.
137
137
  - **Other pairs** (`tone`, `intensity`, mix `value`) have no automatic escalation: a single value is used in both tiers.
138
138
  - **Tone windows** don't apply in high contrast: placement and the contrast search use the full `0–100` tone range. See [Light, dark, and high contrast](../schemes.mdx#high-contrast).
@@ -209,10 +209,10 @@ A `contrast` pair can't switch metric at all; see [Metric switching](#metric-swi
209
209
 
210
210
  [`autoFlip`](./color-definitions.md#autoflip) decides per solve, and its tie-break (when both sides of the base meet the floor, take the one nearer the preferred tone) depends on the target. Along a ramp of targets that tie-break can change, so a naive solve would let a color jump across its own base as the slider moves.
211
211
 
212
- Under a manual level, the side is chosen once per half of the ramp, by a solve at the nearer endpoint's target (level `0` below 50, level `100` from 50 up), and then preferred at every level in that half:
212
+ Under a manual level, each level first runs a probe: a solve at the nearer endpoint's target (level `0` below 50, level `100` from 50 up), from that level's preferred tone and base. The color then prefers the side the probe lands on:
213
213
 
214
214
  - While the preferred side meets the floor, the color stays there, even where the other side would be nearer its preferred tone.
215
- - The preferred side changes only at level 50, where un-interpolable pairs also switch, and only when the two endpoints land on different sides.
215
+ - The probe's target is the same across each half of the ramp, so the preferred side normally holds through it and changes only at level 50, where un-interpolable pairs also switch, when the two endpoints land on different sides. The preferred tone and the base move with the tone windows, though, so a color whose endpoint solve is close to a tie (both sides about equally near its preferred tone) can switch sides at another level.
216
216
  - Flipping is re-ordered, not disabled. At a level where the preferred side can't reach the interpolated target, the solver falls back to the opposite side, so the floor is met wherever either side can meet it. Where neither side can, the color pins to the preferred side's extreme. A color near the limit of what either side can reach can therefore cross its base at other levels, and back again, even when both endpoints land on the same side.
217
217
  - A probe that lands on its base pins no side. With `contrast: [1, 4.5]`, the level-0 probe keeps the preferred tone, and for a `'+0'` delta that is the base's own tone. Each level then picks a side by the solver's own tie rule, exactly as the same color without a `tone` would.
218
218
 
@@ -23,7 +23,7 @@ The package ships ESM and CommonJS with full type declarations and has no runtim
23
23
  | [Palettes](./palette.md) | `glaze.palette()`, prefixes, collisions, the primary alias, `glaze.paletteFrom()`. |
24
24
  | [Output formats](./output.md) | Every output method and option, color formats, output modes, state aliases, `splitHue`, HDR output. |
25
25
  | [Configuration](./configuration.md) | `glaze.configure()` and every `GlazeConfig` field, per-instance overrides, validation, warnings. |
26
- | [Utilities](./utilities.md) | `glaze.format` / `glaze.formatHdr`, standalone `glaze.shadow` / `glaze.glow`, color math, tone utilities, the contrast solver, role helpers, guards. |
26
+ | [Utilities](./utilities.md) | `glaze.format` / `glaze.formatHdr`, the HDR channel helpers, standalone `glaze.shadow` / `glaze.glow`, color math, tone utilities, the contrast solver, role helpers, guards. |
27
27
 
28
28
  ## `glaze` and its statics
29
29
 
@@ -77,7 +77,8 @@ Everything below is exported from `'@tenphi/glaze'` next to `glaze`. Apart from
77
77
  | `toTone`, `fromTone`, `toneFromY`, `yFromTone`, `okhstToOkhsl`, `okhslToOkhst`, `variantToOkhsl`, `REF_EPS` | OKHST tone utilities | [Utilities](./utilities.md#okhst-tone-utilities); the model in [Tone and OKHST](../okhst.mdx) |
78
78
  | `okhslToLinearSrgb`, `okhslToSrgb`, `okhslToOklab`, `oklabToOkhsl`, `srgbToOkhsl`, `hslToSrgb`, `okhslToOklch`, `cuspLightness`, `parseHex`, `parseHexAlpha`, `srgbToHex`, `relativeLuminanceFromLinearRgb`, `contrastRatioFromLuminance`, `gamutClampedLuminance`, `apcaLuminanceFromLinearRgb` | Color math | [Utilities](./utilities.md#color-math) |
79
79
  | `formatOkhsl`, `formatOkhst`, `formatRgb`, `formatHsl`, `formatOklch` | Format writers (0–1 scale) | [Utilities](./utilities.md#format-writers) |
80
- | `formatSrgbLinear` | HDR writer: linear sRGB channels, unclamped, as `color(srgb-linear R G B)` | [Utilities](./utilities.md#format-writers); where it applies: [HDR strings](./output.md#hdr-strings) |
80
+ | `formatSrgb`, `formatSrgbLinear` | HDR writers: extended or linear sRGB channels, unclamped, as `color(srgb R G B)` / `color(srgb-linear R G B)` | [Utilities](./utilities.md#format-writers); the format: [Extended sRGB](../hdr.mdx#extended-srgb) |
81
+ | `hdrToSrgb`, `hdrToLinearSrgb` | HDR channels: a `ResolvedHdr` → extended or linear sRGB, unclamped | [Utilities](./utilities.md#hdrtosrgbhdr--hdrtolinearsrgbhdr) |
81
82
 
82
83
  ## Types
83
84
 
@@ -121,6 +122,7 @@ Glaze mixes a few numeric scales. Which one applies depends on where a value is
121
122
  | Mix `value` | 0–100 | `MixColorDef.value` (0 = base, 100 = target). |
122
123
  | Resolved variant | `h` 0–360; `s`, `t`, `alpha` 0–1 | `ResolvedColorVariant`, the input to `glaze.format()`. Its optional `hdr` (`ResolvedHdr`) uses the same scales plus `exposure`. |
123
124
  | Headroom, exposure | Stops above SDR white; each stop doubles luminance. `headroom` 0–2. | `glowTuning.headroom` and a glow's `tuning.headroom`; `ResolvedHdr.exposure` and DTCG `exposure`. 1 stop past white is tone 121.98, 2 stops tone 144.34. |
125
+ | HDR channels | Extended or linear sRGB, unclamped; `1` is SDR white. One stop above it is `1.3533` extended, `2` linear. | Extended: every exporter's HDR strings, DTCG `hdr.value`, `glaze.formatHdr()` by default, `hdrToSrgb`, `formatSrgb`. Linear: `glaze.formatHdr(v, 'srgb-linear')`, `hdrToLinearSrgb`, `formatSrgbLinear`. |
124
126
  | Value objects | `{ h, s, l }` and `{ h, s, t }`: `s`, `l`, `t` 0–1. `{ r, g, b }`: 0–255. `{ l, c, h }`: `L` and `C` 0–1, `H` degrees. | `from`, `glaze.color()`, `glaze.shadow()` / `glaze.glow()` inputs. |
125
127
  | Format writers and converters | `h` 0–360; `s`, `l`, `t` 0–1 | `formatOkhsl` … `formatOklch` and the color math functions. The format writers warn when they get 0–100 percentages (the pre-2.0 scale). |
126
128
  | Opacity, ratios | 0–1 | `opacity`, `darkDesaturation`, lighting `tint` / `reach` / `hueBleed`. |
@@ -171,7 +173,7 @@ Every `.export()` writes two fields:
171
173
 
172
174
  | Version | Written by |
173
175
  | --- | --- |
174
- | `1` | Glaze 2.x. |
176
+ | `1` | Glaze 1.1–2.x. |
175
177
  | `2` | Glaze 3: shadow `intensity`, `fg`, and tuning changed meaning, and `glow` was added. |
176
178
 
177
179
  ### Restore checks
@@ -190,7 +192,7 @@ Every `.export()` writes two fields:
190
192
  A version-1 theme snapshot with shadows is rejected because Glaze 3 changed what shadow `intensity`, `fg`, and tuning mean: restoring it would silently render every shadow differently. The error names the shadows and points to the upgrade guide:
191
193
 
192
194
  ```text
193
- glaze.themeFrom: this snapshot is export version 1 (Glaze 2) and contains
195
+ glaze.themeFrom: this snapshot is export version 1 (Glaze 1.1–2) and contains
194
196
  shadow colors ("card-shadow").
195
197
  Glaze 3 changed what shadow "intensity", "fg" and tuning mean, so it would
196
198
  restore with different shadows.
@@ -198,7 +200,7 @@ Re-author them as described in docs/migration.md ("3.0 — shadows and
198
200
  glows") and export again.
199
201
  ```
200
202
 
201
- A theme entry inside a palette snapshot that has no `version` of its own is checked against the palette's `version`. The check keys on `version: 1`, so a snapshot without any `version` is not checked. How to re-author Glaze 2 shadows is in [3.0 — shadows and glows](../migration.md#30--shadows-and-glows).
203
+ A theme entry inside a palette snapshot that has no `version` of its own is checked against the palette's `version`. The check keys on `version: 1`, so a snapshot without any `version` (a hand-written one, or one from Glaze 1.0) is not checked: re-author its shadows before restoring it. How to re-author Glaze 2 shadows is in [3.0 — shadows and glows](../migration.md#30--shadows-and-glows).
202
204
 
203
205
  ### Type guards
204
206