@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/AGENTS.md +29 -28
- package/README.md +2 -2
- package/dist/index.cjs +604 -180
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +98 -34
- package/dist/index.d.mts +98 -34
- package/dist/index.mjs +602 -181
- package/dist/index.mjs.map +1 -1
- package/docs/exporting.mdx +2 -218
- package/docs/hdr.mdx +523 -0
- package/docs/methodology.mdx +2 -3
- package/docs/migration.md +53 -16
- package/docs/mixes.mdx +48 -5
- package/docs/okhst.mdx +2 -5
- package/docs/reference/color-definitions.md +13 -15
- package/docs/reference/color-tokens.md +11 -7
- package/docs/reference/configuration.md +28 -11
- package/docs/reference/contrast.md +4 -4
- package/docs/reference/index.md +7 -5
- package/docs/reference/output.md +31 -151
- package/docs/reference/palette.md +4 -4
- package/docs/reference/theme.md +10 -10
- package/docs/reference/utilities.md +40 -23
- package/docs/schemes.mdx +4 -5
- package/docs/shadows-and-glows.mdx +7 -225
- package/package.json +2 -2
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
|
|
124
|
-
`
|
|
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
|
|
146
|
-
|
|
147
|
-
the
|
|
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](./
|
|
143
|
-
|
|
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>"
|
|
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
|
|
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
|
|
478
|
-
- **Exposure.** `log2(min(Y(T*) / Y(base), 2^headroom / max channel))
|
|
479
|
-
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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)"
|
|
89
|
-
|
|
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
|
-
-
|
|
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](
|
|
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
|
|
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
|
|
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](../
|
|
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
|
|
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. |
|
|
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
|
|
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,
|
|
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
|
-
(
|
|
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,
|
|
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,
|
|
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
|
|
package/docs/reference/index.md
CHANGED
|
@@ -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
|
|
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
|
|