@tenphi/glaze 0.0.0-snapshot.9a14acf → 0.0.0-snapshot.9dc79fc
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 +69 -32
- package/README.md +43 -23
- package/dist/index.cjs +2705 -1324
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +484 -102
- package/dist/index.d.mts +484 -102
- package/dist/index.mjs +2704 -1325
- package/dist/index.mjs.map +1 -1
- package/docs/contrast.mdx +755 -0
- package/docs/exporting.mdx +851 -0
- package/docs/getting-started.mdx +488 -0
- package/docs/methodology.mdx +977 -0
- package/docs/migration.md +417 -285
- package/docs/mixes.mdx +305 -0
- package/docs/okhst.mdx +681 -0
- package/docs/reference/color-definitions.md +554 -0
- package/docs/reference/color-tokens.md +418 -0
- package/docs/reference/configuration.md +510 -0
- package/docs/reference/contrast.md +277 -0
- package/docs/reference/index.md +223 -0
- package/docs/reference/output.md +834 -0
- package/docs/reference/palette.md +435 -0
- package/docs/reference/theme.md +332 -0
- package/docs/reference/utilities.md +629 -0
- package/docs/schemes.mdx +631 -0
- package/docs/shadows-and-glows.mdx +737 -0
- package/package.json +7 -4
- package/docs/api.md +0 -2021
- package/docs/methodology.md +0 -686
- package/docs/okhst.md +0 -207
package/dist/index.d.cts
CHANGED
|
@@ -102,9 +102,17 @@ interface FindToneForContrastOptions {
|
|
|
102
102
|
epsilon?: number;
|
|
103
103
|
/** Maximum binary-search iterations per branch. Default: 18. */
|
|
104
104
|
maxIterations?: number;
|
|
105
|
-
/**
|
|
105
|
+
/**
|
|
106
|
+
* Preferred search direction before auto-flip is considered. Default: the
|
|
107
|
+
* side whose bound scores higher (the only open side when `preferredTone`
|
|
108
|
+
* sits on a bound); a tie within float noise starts `'darker'`.
|
|
109
|
+
*/
|
|
106
110
|
initialDirection?: 'lighter' | 'darker';
|
|
107
|
-
/**
|
|
111
|
+
/**
|
|
112
|
+
* Also search the opposite direction. Default: false. When both directions
|
|
113
|
+
* meet the target, the result nearer `preferredTone` wins; a gap within
|
|
114
|
+
* twice the search resolution is a tie and keeps `initialDirection`.
|
|
115
|
+
*/
|
|
108
116
|
flip?: boolean;
|
|
109
117
|
/**
|
|
110
118
|
* When `flip` is on and *both* directions meet the target, keep
|
|
@@ -129,26 +137,42 @@ interface FindToneForContrastResult {
|
|
|
129
137
|
contrast: number;
|
|
130
138
|
/** Whether the target was reached. */
|
|
131
139
|
met: boolean;
|
|
132
|
-
/**
|
|
140
|
+
/**
|
|
141
|
+
* The side the result was found on. The two sides meet at `preferredTone`,
|
|
142
|
+
* so a met result sits on that side of the base too. `'preferred'` whenever
|
|
143
|
+
* a met result is `preferredTone` itself: it already cleared the
|
|
144
|
+
* overshooting search target, or it clears the bare target and no search
|
|
145
|
+
* could improve on it — no searched side met the floor, or the starting
|
|
146
|
+
* side's only position was `preferredTone` (it sits on that side's bound).
|
|
147
|
+
* Also `'preferred'` when `toneRange` leaves no room to search, met or not.
|
|
148
|
+
* An unmet result otherwise reports the side whose extreme it pinned to.
|
|
149
|
+
*/
|
|
133
150
|
branch: 'lighter' | 'darker' | 'preferred';
|
|
134
151
|
/** Whether the result auto-flipped to the opposite direction. */
|
|
135
152
|
flipped?: boolean;
|
|
136
153
|
}
|
|
137
154
|
/**
|
|
138
155
|
* Find the tone that satisfies a contrast floor against a base color,
|
|
139
|
-
* staying as close to `preferredTone` as possible.
|
|
156
|
+
* staying as close to `preferredTone` as possible. A searched result keeps the
|
|
157
|
+
* overshoot (1% for WCAG, 0.5 Lc for APCA). When no searched side reaches the
|
|
158
|
+
* floor, the result pins to the initial direction's extreme, unmet — unless
|
|
159
|
+
* `preferredTone` itself clears the bare target, which is then kept as met
|
|
160
|
+
* (`branch: 'preferred'`, the same label a met result gets when the starting
|
|
161
|
+
* side's only position is `preferredTone`).
|
|
140
162
|
*/
|
|
141
163
|
declare function findToneForContrast(options: FindToneForContrastOptions): FindToneForContrastResult;
|
|
142
164
|
interface FindValueForMixContrastOptions {
|
|
143
165
|
/** Preferred mix parameter (0–1). */
|
|
144
166
|
preferredValue: number;
|
|
145
|
-
/** Base color as linear sRGB. */
|
|
167
|
+
/** Base color as linear sRGB — the color the mix is measured against. */
|
|
146
168
|
baseLinearRgb: LinearRgb;
|
|
147
|
-
/** Target color as linear sRGB. */
|
|
148
|
-
targetLinearRgb: LinearRgb;
|
|
149
169
|
/** Resolved contrast floor (metric + target). */
|
|
150
170
|
contrast: ResolvedContrast;
|
|
151
|
-
/**
|
|
171
|
+
/**
|
|
172
|
+
* Luminance of the mixed color at parameter t, in the metric's basis
|
|
173
|
+
* ({@link metricLuminance}). This closure is the only view the solver has of
|
|
174
|
+
* the mix's target color, blend, and color space.
|
|
175
|
+
*/
|
|
152
176
|
luminanceAtValue: (t: number) => number;
|
|
153
177
|
/** Convergence threshold. Default: 1e-4. */
|
|
154
178
|
epsilon?: number;
|
|
@@ -166,6 +190,9 @@ interface FindValueForMixContrastResult {
|
|
|
166
190
|
/**
|
|
167
191
|
* Find the mix parameter (ratio or opacity) that satisfies a contrast floor
|
|
168
192
|
* against a base color, staying as close to `preferredValue` as possible.
|
|
193
|
+
* Misses pin to the initial direction's end like the tone solver, and a
|
|
194
|
+
* `preferredValue` that clears the bare target is kept as met when no searched
|
|
195
|
+
* side reaches the floor (a value of 1 has no room toward the target).
|
|
169
196
|
*/
|
|
170
197
|
declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
|
|
171
198
|
//#endregion
|
|
@@ -224,6 +251,13 @@ type ExtremeValue = 'max' | 'min';
|
|
|
224
251
|
type ToneValue = number | RelativeValue | ExtremeValue;
|
|
225
252
|
/** Color format for output. */
|
|
226
253
|
type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';
|
|
254
|
+
/**
|
|
255
|
+
* Output format for an HDR glow value (`glaze.formatHdr()`). Only
|
|
256
|
+
* `'srgb-linear'` — `color(srgb-linear R G B)` with channels that may exceed
|
|
257
|
+
* 1 — since OKLCH lightness clamps at parse time and `rgb()` / `hsl()` cannot
|
|
258
|
+
* go past white.
|
|
259
|
+
*/
|
|
260
|
+
type GlazeHdrFormat = 'srgb-linear';
|
|
227
261
|
/**
|
|
228
262
|
* Controls which scheme variants are generated in the export.
|
|
229
263
|
* Light is always included (it's the default).
|
|
@@ -241,6 +275,19 @@ interface GlazeOutputModes {
|
|
|
241
275
|
* @see GlazeConfig.contrastLevel
|
|
242
276
|
*/
|
|
243
277
|
highContrast?: boolean;
|
|
278
|
+
/**
|
|
279
|
+
* Include the HDR tier of glows past SDR white (`variant.hdr`, set by
|
|
280
|
+
* `GlowTuning.headroom`). Default: false — every exporter's output stays
|
|
281
|
+
* byte-identical to SDR even when a headroom is set.
|
|
282
|
+
*
|
|
283
|
+
* When on, each exporter adds the HDR values next to the SDR ones it
|
|
284
|
+
* already emits (only for the scheme variants the other modes include),
|
|
285
|
+
* always written as `color(srgb-linear R G B)`: Tasty `hdr` state keys,
|
|
286
|
+
* `json()` `lightHdr` / `darkHdr` / … keys, `tokens()` `lightHdr` / … maps,
|
|
287
|
+
* Tailwind blocks under `hdrSelector`, DTCG `$extensions`. `css()` reads
|
|
288
|
+
* its own `hdr` option, which falls back to this.
|
|
289
|
+
*/
|
|
290
|
+
hdr?: boolean;
|
|
244
291
|
}
|
|
245
292
|
/** Hex color string for DX hints. Runtime validation in `parseHex()`. */
|
|
246
293
|
type HexColor = `#${string}`;
|
|
@@ -296,7 +343,7 @@ interface RegularColorDef {
|
|
|
296
343
|
*/
|
|
297
344
|
from?: GlazeColorValue;
|
|
298
345
|
/**
|
|
299
|
-
* Tone value (0–100, contrast-uniform — see `docs/okhst.
|
|
346
|
+
* Tone value (0–100, contrast-uniform — see `docs/okhst.mdx`).
|
|
300
347
|
* - Number: absolute tone.
|
|
301
348
|
* - String ('+N' / '-N'): relative to base color's tone (requires `base`).
|
|
302
349
|
* - `'max'` / `'min'`: force to the scheme's tone extreme (no base needed).
|
|
@@ -390,44 +437,94 @@ interface RegularColorDef {
|
|
|
390
437
|
*/
|
|
391
438
|
inherit?: boolean;
|
|
392
439
|
}
|
|
393
|
-
/**
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
/**
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
440
|
+
/**
|
|
441
|
+
* Tuning shared by `shadow` and `glow`. Global defaults come from
|
|
442
|
+
* `shadowTuning` / `glowTuning`; a per-color `tuning` merges over them field
|
|
443
|
+
* by field.
|
|
444
|
+
*/
|
|
445
|
+
interface LightingTuning {
|
|
446
|
+
/**
|
|
447
|
+
* β — how strongly the object (`fg`) scales the step. The step is
|
|
448
|
+
* `intensity × k` with `k = max(0, 1 + β · d · (t_bg − t_fg) / 100)`,
|
|
449
|
+
* `d = +1` for a shadow and `−1` for a glow: a darker object deepens its
|
|
450
|
+
* shadow, a lighter one strengthens its glow. An object at the surface's
|
|
451
|
+
* own tone (or no `fg`) gives exactly `intensity`. `0` ignores the object.
|
|
452
|
+
* Default: 0.5.
|
|
453
|
+
*/
|
|
454
|
+
objectInfluence?: number;
|
|
403
455
|
/**
|
|
404
|
-
*
|
|
405
|
-
*
|
|
456
|
+
* Pigment saturation (0–1) in the surface's hue. Default: 0 (neutral black /
|
|
457
|
+
* white). Shows only with `reach` below 1 — pure black and white have no hue.
|
|
406
458
|
*/
|
|
407
|
-
|
|
408
|
-
/** Max alpha (0-1). Reached at intensity=100 with max contrast. Default: 1.0. */
|
|
409
|
-
alphaMax?: number;
|
|
459
|
+
tint?: number;
|
|
410
460
|
/**
|
|
411
|
-
*
|
|
412
|
-
*
|
|
461
|
+
* Where the pigment sits (0–1): the fraction of the way from the surface's
|
|
462
|
+
* tone to black (shadow) / white (glow). Default: 1 (pure black / white),
|
|
463
|
+
* the most reach. Lower values let a `tint` show at the cost of reach.
|
|
413
464
|
*/
|
|
414
|
-
|
|
465
|
+
reach?: number;
|
|
466
|
+
/**
|
|
467
|
+
* Pull (0–1) of the pigment hue from the surface's hue toward the object's
|
|
468
|
+
* (`fg`) hue. Default: 0. Needs `fg`, a `tint`, and `reach` below 1 to show.
|
|
469
|
+
*/
|
|
470
|
+
hueBleed?: number;
|
|
471
|
+
}
|
|
472
|
+
/**
|
|
473
|
+
* Tuning for `shadow` colors: the shared {@link LightingTuning}. It has no
|
|
474
|
+
* `headroom` — a shadow darkens toward black, and nothing goes below black —
|
|
475
|
+
* so a `headroom` set on a shadow's tuning throws.
|
|
476
|
+
*/
|
|
477
|
+
type ShadowTuning = LightingTuning;
|
|
478
|
+
/** Tuning for `glow` colors: the shared {@link LightingTuning} plus HDR `headroom`. */
|
|
479
|
+
interface GlowTuning extends LightingTuning {
|
|
480
|
+
/**
|
|
481
|
+
* Stops above SDR white a glow may use when its step crosses white. Default:
|
|
482
|
+
* 0 (SDR only). Counted in stops — doublings of SDR white's luminance — not
|
|
483
|
+
* as a ratio: `1` allows up to 2× white, `2` up to 4×. Must be a finite
|
|
484
|
+
* number ≥ 0; values above 2 clamp to 2 with a one-time warning.
|
|
485
|
+
*
|
|
486
|
+
* Only a glow whose target tone (surface tone + `intensity × k`) passes 100
|
|
487
|
+
* gets an HDR value: the variant's `hdr`, an opaque exposure of what SDR
|
|
488
|
+
* paints at its brightest — the pigment at full opacity, or a white surface
|
|
489
|
+
* no pigment can lift — plus a gain in stops. A pigment that cannot lift a
|
|
490
|
+
* non-white surface at all (`reach: 0` on a gray surface, say) paints
|
|
491
|
+
* nothing in SDR, so it gets no HDR value either and keeps the SDR "cannot
|
|
492
|
+
* reach" warning. On a chromatic surface a `reach: 0` gray can measure
|
|
493
|
+
* slightly brighter than the surface and pins at full opacity instead.
|
|
494
|
+
* Nothing about the SDR variant changes. The gain lands the exact step when
|
|
495
|
+
* the headroom allows it; the brightest channel caps at `2^headroom`.
|
|
496
|
+
* High-contrast schemes use the same headroom.
|
|
497
|
+
*
|
|
498
|
+
* The HDR value lands the whole step, not just the part past white. A
|
|
499
|
+
* full-reach glow (the default `reach: 1`) is pinned at white, so its HDR
|
|
500
|
+
* value starts at white (`exposure` → 0) as the target passes 100. A glow
|
|
501
|
+
* with `reach` below 1 is pinned at its pigment, below white: just under 100
|
|
502
|
+
* it stays short there (and warns), and just past 100 its HDR value jumps to
|
|
503
|
+
* the exact step.
|
|
504
|
+
*/
|
|
505
|
+
headroom?: number;
|
|
415
506
|
}
|
|
507
|
+
/**
|
|
508
|
+
* A translucent dark overlay that lands the surface (`bg`) exactly
|
|
509
|
+
* `intensity` tones darker in every scheme — a shade for state layers and
|
|
510
|
+
* scrims, or, with `fg`, an object-aware drop shadow.
|
|
511
|
+
*/
|
|
416
512
|
interface ShadowColorDef {
|
|
417
513
|
type: 'shadow';
|
|
418
514
|
/**
|
|
419
|
-
*
|
|
420
|
-
*
|
|
515
|
+
* The surface the shadow falls on. Must reference a color that is not a
|
|
516
|
+
* shadow or glow.
|
|
421
517
|
*/
|
|
422
518
|
bg: string;
|
|
423
519
|
/**
|
|
424
|
-
*
|
|
425
|
-
*
|
|
426
|
-
* Omit for
|
|
520
|
+
* The object casting the shadow (e.g. the card). A darker object casts a
|
|
521
|
+
* deeper shadow, a lighter one a softer shadow — see
|
|
522
|
+
* `LightingTuning.objectInfluence`. Omit for an exact shade of `intensity`
|
|
523
|
+
* tones. Must reference a color that is not a shadow or glow.
|
|
427
524
|
*/
|
|
428
525
|
fg?: string;
|
|
429
526
|
/**
|
|
430
|
-
*
|
|
527
|
+
* Tone step, 0–100: how many tones darker than `bg` the composite lands.
|
|
431
528
|
* Supports [normal, highContrast] pair.
|
|
432
529
|
*/
|
|
433
530
|
intensity: HCPair<number>;
|
|
@@ -446,6 +543,44 @@ interface ShadowColorDef {
|
|
|
446
543
|
*/
|
|
447
544
|
inherit?: boolean;
|
|
448
545
|
}
|
|
546
|
+
/**
|
|
547
|
+
* The mirror of {@link ShadowColorDef}: a translucent light overlay that lands
|
|
548
|
+
* the surface (`bg`) exactly `intensity` tones lighter in every scheme — for
|
|
549
|
+
* dark-mode elevation, edge highlights, and lightening state layers.
|
|
550
|
+
*/
|
|
551
|
+
interface GlowColorDef {
|
|
552
|
+
type: 'glow';
|
|
553
|
+
/**
|
|
554
|
+
* The surface the glow falls on. Must reference a color that is not a
|
|
555
|
+
* shadow or glow.
|
|
556
|
+
*/
|
|
557
|
+
bg: string;
|
|
558
|
+
/**
|
|
559
|
+
* The object emitting the glow. A lighter object glows stronger, a darker
|
|
560
|
+
* one weaker — see `LightingTuning.objectInfluence`. Omit for an exact tint
|
|
561
|
+
* of `intensity` tones. Must reference a color that is not a shadow or glow.
|
|
562
|
+
*/
|
|
563
|
+
fg?: string;
|
|
564
|
+
/**
|
|
565
|
+
* Tone step, 0–100: how many tones lighter than `bg` the composite lands.
|
|
566
|
+
* Supports [normal, highContrast] pair.
|
|
567
|
+
*/
|
|
568
|
+
intensity: HCPair<number>;
|
|
569
|
+
/** Override default tuning. Merged field-by-field with global `glowTuning`. */
|
|
570
|
+
tuning?: GlowTuning;
|
|
571
|
+
/**
|
|
572
|
+
* Per-color override for the hue-independent "safe" chroma limit used in
|
|
573
|
+
* OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
|
|
574
|
+
* Falls through to the per-theme / per-token `pastel` override when omitted.
|
|
575
|
+
* @see GlazeConfigOverride.pastel
|
|
576
|
+
*/
|
|
577
|
+
pastel?: boolean;
|
|
578
|
+
/**
|
|
579
|
+
* Whether this color is inherited by child themes created via `extend()`.
|
|
580
|
+
* Default: true. Set to false to make this color local to the current theme.
|
|
581
|
+
*/
|
|
582
|
+
inherit?: boolean;
|
|
583
|
+
}
|
|
449
584
|
interface MixColorDef {
|
|
450
585
|
type: 'mix';
|
|
451
586
|
/** Background/base color name — the "from" color. */
|
|
@@ -467,9 +602,12 @@ interface MixColorDef {
|
|
|
467
602
|
/**
|
|
468
603
|
* Interpolation color space for opaque blending. Default: 'okhsl'.
|
|
469
604
|
* - 'okhsl': perceptually uniform, consistent with Glaze's internal model.
|
|
470
|
-
* - 'srgb': linear sRGB interpolation
|
|
605
|
+
* - 'srgb': linear-light sRGB interpolation (like CSS
|
|
606
|
+
* `color-mix(in srgb-linear, …)`).
|
|
471
607
|
*
|
|
472
|
-
* Ignored for 'transparent' blend
|
|
608
|
+
* Ignored for 'transparent' blend: the browser composites that one, and
|
|
609
|
+
* its contrast solve models the browser (`source-over` on gamma-encoded
|
|
610
|
+
* sRGB).
|
|
473
611
|
*/
|
|
474
612
|
space?: 'okhsl' | 'srgb';
|
|
475
613
|
/**
|
|
@@ -499,7 +637,7 @@ interface MixColorDef {
|
|
|
499
637
|
*/
|
|
500
638
|
inherit?: boolean;
|
|
501
639
|
}
|
|
502
|
-
type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
|
|
640
|
+
type ColorDef = RegularColorDef | ShadowColorDef | GlowColorDef | MixColorDef;
|
|
503
641
|
type ColorMap = Record<string, ColorDef>;
|
|
504
642
|
/**
|
|
505
643
|
* Resolved color for a single scheme variant.
|
|
@@ -523,6 +661,35 @@ interface ResolvedColorVariant {
|
|
|
523
661
|
* gamut mapping applied during resolution.
|
|
524
662
|
*/
|
|
525
663
|
pastel?: boolean;
|
|
664
|
+
/**
|
|
665
|
+
* HDR tier of a glow whose step crosses SDR white, present only when the
|
|
666
|
+
* glow's `headroom` is above 0, its target tone passes 100, and SDR is
|
|
667
|
+
* pinned at its brightest — the pigment at full opacity, or a white surface
|
|
668
|
+
* (see `GlowTuning.headroom`). Absent everywhere else — shadows, mixes,
|
|
669
|
+
* regular colors, a glow whose pigment cannot lift a non-white surface, and
|
|
670
|
+
* every glow at the default headroom of 0.
|
|
671
|
+
*/
|
|
672
|
+
hdr?: ResolvedHdr;
|
|
673
|
+
}
|
|
674
|
+
/**
|
|
675
|
+
* The HDR value of a glow past SDR white: an opaque base plus a gain. The base
|
|
676
|
+
* is what SDR paints at its brightest — the glow's pigment at full opacity, or
|
|
677
|
+
* the white surface it cannot lift — and the HDR color is that base's linear
|
|
678
|
+
* sRGB times `2^exposure`. Format it with `glaze.formatHdr()`.
|
|
679
|
+
*
|
|
680
|
+
* Stored in OKHST like the variant. `s` is always standard (non-pastel)
|
|
681
|
+
* OKHSL saturation, whatever the variant's `pastel`, since the base is an
|
|
682
|
+
* arbitrary in-gamut composite.
|
|
683
|
+
*/
|
|
684
|
+
interface ResolvedHdr {
|
|
685
|
+
/** Base OKHSL hue (0–360). */
|
|
686
|
+
h: number;
|
|
687
|
+
/** Base OKHSL saturation (0–1, non-pastel). */
|
|
688
|
+
s: number;
|
|
689
|
+
/** Base canonical tone (0–1, reference eps). */
|
|
690
|
+
t: number;
|
|
691
|
+
/** Gain over the base in stops (`log2` of the linear factor), above 0. */
|
|
692
|
+
exposure: number;
|
|
526
693
|
}
|
|
527
694
|
/** Fully resolved color across all scheme variants. */
|
|
528
695
|
interface ResolvedColor {
|
|
@@ -531,7 +698,7 @@ interface ResolvedColor {
|
|
|
531
698
|
dark: ResolvedColorVariant;
|
|
532
699
|
lightContrast: ResolvedColorVariant;
|
|
533
700
|
darkContrast: ResolvedColorVariant;
|
|
534
|
-
/** Adaptation mode
|
|
701
|
+
/** Adaptation mode of a regular color; `undefined` for shadow / glow / mix. */
|
|
535
702
|
mode?: AdaptationMode;
|
|
536
703
|
}
|
|
537
704
|
/**
|
|
@@ -557,20 +724,31 @@ interface GlazeConfig {
|
|
|
557
724
|
darkDesaturation?: number;
|
|
558
725
|
/**
|
|
559
726
|
* State alias names for Tasty token export. Default to media-query states
|
|
560
|
-
* (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`
|
|
561
|
-
* so tokens react to the OS preference
|
|
727
|
+
* (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`
|
|
728
|
+
* / `'@media(dynamic-range: high)'`) so tokens react to the OS preference
|
|
729
|
+
* and the display without registering custom states. `hdr` keys an HDR
|
|
730
|
+
* glow value and is used only with `modes.hdr`.
|
|
562
731
|
*/
|
|
563
732
|
states?: {
|
|
564
733
|
dark?: string;
|
|
565
734
|
highContrast?: string;
|
|
735
|
+
hdr?: string;
|
|
566
736
|
};
|
|
567
737
|
/**
|
|
568
738
|
* Which scheme variants to include in exports. Defaults: `dark: true`,
|
|
569
|
-
* `highContrast: false`.
|
|
739
|
+
* `highContrast: false`, `hdr: false`.
|
|
570
740
|
*/
|
|
571
741
|
modes?: GlazeOutputModes;
|
|
572
|
-
/**
|
|
742
|
+
/**
|
|
743
|
+
* Default tuning for all shadow colors. Per-color tuning merges field-by-field.
|
|
744
|
+
* A `headroom` here throws: it is a glow-only field.
|
|
745
|
+
*/
|
|
573
746
|
shadowTuning?: ShadowTuning;
|
|
747
|
+
/**
|
|
748
|
+
* Default tuning for all glow colors, including HDR `headroom`. Per-color
|
|
749
|
+
* tuning merges field-by-field.
|
|
750
|
+
*/
|
|
751
|
+
glowTuning?: GlowTuning;
|
|
574
752
|
/**
|
|
575
753
|
* Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
|
|
576
754
|
* contrast (`100`), or `'auto'` (the default) to take the authored normal
|
|
@@ -590,7 +768,7 @@ interface GlazeConfig {
|
|
|
590
768
|
* approximation, and a color keeps to one side of its base as the level moves.
|
|
591
769
|
*
|
|
592
770
|
* Pass `'auto'` to leave manual mode; `configure()` never clears a field by
|
|
593
|
-
* omission. See `docs/
|
|
771
|
+
* omission. See `docs/reference/contrast.md` for the ramp's edge cases (un-interpolable
|
|
594
772
|
* pairs, side changes) and the export-freeze rule.
|
|
595
773
|
*
|
|
596
774
|
* @default 'auto'
|
|
@@ -626,9 +804,11 @@ interface GlazeConfigResolved {
|
|
|
626
804
|
states: {
|
|
627
805
|
dark: string;
|
|
628
806
|
highContrast: string;
|
|
807
|
+
hdr: string;
|
|
629
808
|
};
|
|
630
809
|
modes: Required<GlazeOutputModes>;
|
|
631
810
|
shadowTuning?: ShadowTuning;
|
|
811
|
+
glowTuning?: GlowTuning;
|
|
632
812
|
autoFlip: boolean;
|
|
633
813
|
/**
|
|
634
814
|
* Manual contrast level (0–100) for the normal variants, or `'auto'` to take
|
|
@@ -690,12 +870,22 @@ interface GlazeConfigOverride {
|
|
|
690
870
|
* standalone color tokens.
|
|
691
871
|
*/
|
|
692
872
|
shadowTuning?: ShadowTuning;
|
|
873
|
+
/**
|
|
874
|
+
* Glow tuning defaults. Only meaningful for themes; harmless on
|
|
875
|
+
* standalone color tokens.
|
|
876
|
+
*/
|
|
877
|
+
glowTuning?: GlowTuning;
|
|
693
878
|
}
|
|
694
879
|
/**
|
|
695
880
|
* Current authoring-export schema version. Bump when the export shape
|
|
696
881
|
* changes in a non-compatible way. Written on every `.export()` snapshot.
|
|
882
|
+
*
|
|
883
|
+
* - `1` — Glaze 2.x.
|
|
884
|
+
* - `2` — Glaze 3: `shadow` `intensity` / `fg` / `tuning` changed meaning and
|
|
885
|
+
* `glow` was added. Version-1 theme snapshots that carry shadow defs or a
|
|
886
|
+
* `shadowTuning` are rejected on restore.
|
|
697
887
|
*/
|
|
698
|
-
declare const GLAZE_EXPORT_VERSION:
|
|
888
|
+
declare const GLAZE_EXPORT_VERSION: 2;
|
|
699
889
|
/** Literal type of {@link GLAZE_EXPORT_VERSION}. */
|
|
700
890
|
type GlazeExportVersion = typeof GLAZE_EXPORT_VERSION;
|
|
701
891
|
/** Discriminator for authoring export snapshots. */
|
|
@@ -720,23 +910,27 @@ interface GlazeThemeExport {
|
|
|
720
910
|
*/
|
|
721
911
|
config?: GlazeConfigOverride;
|
|
722
912
|
}
|
|
723
|
-
/** Input for `glaze.shadow()` standalone
|
|
724
|
-
interface
|
|
913
|
+
/** Input for the `glaze.shadow()` and `glaze.glow()` standalone factories. */
|
|
914
|
+
interface GlazeLightingInput {
|
|
725
915
|
/**
|
|
726
|
-
*
|
|
727
|
-
* (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` /
|
|
728
|
-
* / `oklch()` strings, or literal objects
|
|
729
|
-
* `{
|
|
916
|
+
* The surface — accepts any `GlazeColorValue` form: hex
|
|
917
|
+
* (`#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` /
|
|
918
|
+
* `okhsl()` / `okhst()` / `oklch()` strings, or literal objects
|
|
919
|
+
* (`{ r, g, b }`, `{ h, s, l }`, `{ h, s, t }`, `{ l, c, h }`). Alpha
|
|
920
|
+
* components are dropped with a warning.
|
|
730
921
|
*/
|
|
731
922
|
bg: GlazeColorValue;
|
|
732
|
-
/**
|
|
733
|
-
* Foreground color for tinting + intensity modulation. Accepts the
|
|
734
|
-
* same forms as `bg`.
|
|
735
|
-
*/
|
|
923
|
+
/** The object casting the shadow / emitting the glow. Same forms as `bg`. */
|
|
736
924
|
fg?: GlazeColorValue;
|
|
737
|
-
/**
|
|
925
|
+
/** Tone step, 0–100. */
|
|
738
926
|
intensity: number;
|
|
739
|
-
tuning?:
|
|
927
|
+
tuning?: LightingTuning;
|
|
928
|
+
}
|
|
929
|
+
/** Input for `glaze.shadow()`. */
|
|
930
|
+
type GlazeShadowInput = GlazeLightingInput;
|
|
931
|
+
/** Input for `glaze.glow()`: the shared input, with glow tuning (`headroom`). */
|
|
932
|
+
interface GlazeGlowInput extends GlazeLightingInput {
|
|
933
|
+
tuning?: GlowTuning;
|
|
740
934
|
}
|
|
741
935
|
/** Input for the structured `glaze.color()` overload. */
|
|
742
936
|
interface GlazeColorInput {
|
|
@@ -769,14 +963,17 @@ interface GlazeColorInput {
|
|
|
769
963
|
*/
|
|
770
964
|
base?: GlazeColorToken | GlazeColorValue;
|
|
771
965
|
/**
|
|
772
|
-
* Contrast floor
|
|
966
|
+
* Contrast floor. Without `base`, solved against the token's own input
|
|
967
|
+
* color (`hue`, `saturation`, normal `tone`), held fixed in every scheme;
|
|
968
|
+
* with `base`, against the base's resolved variant per scheme. A bare
|
|
773
969
|
* number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the metric.
|
|
774
970
|
*/
|
|
775
971
|
contrast?: HCPair<ContrastSpec>;
|
|
776
972
|
/**
|
|
777
973
|
* Optional human-readable name for the token. Used in error and
|
|
778
974
|
* warning messages (otherwise an internal name like `"value"` is
|
|
779
|
-
* used).
|
|
975
|
+
* used) and as `resolve().name`. A debug label only: it does not
|
|
976
|
+
* affect output keys or the token's `role`.
|
|
780
977
|
*/
|
|
781
978
|
name?: string;
|
|
782
979
|
/**
|
|
@@ -787,11 +984,12 @@ interface GlazeColorInput {
|
|
|
787
984
|
*/
|
|
788
985
|
pastel?: boolean;
|
|
789
986
|
/**
|
|
790
|
-
* Semantic role against
|
|
791
|
-
*
|
|
792
|
-
*
|
|
793
|
-
*
|
|
794
|
-
*
|
|
987
|
+
* Semantic role against the token's anchor (`base`, or its own input
|
|
988
|
+
* color when `contrast` is set without one): how this token is used.
|
|
989
|
+
* Fixes APCA contrast polarity; WCAG ignores it. Defaults to `'text'` —
|
|
990
|
+
* the token is the foreground and the anchor the background, with or
|
|
991
|
+
* without `base`. Unlike a theme color, a token never infers its role
|
|
992
|
+
* from `name`, so `inferRole` has no effect on it.
|
|
795
993
|
*/
|
|
796
994
|
role?: RoleInput;
|
|
797
995
|
}
|
|
@@ -799,17 +997,35 @@ interface GlazeColorInput {
|
|
|
799
997
|
* Any single-color input form accepted by the value-shorthand
|
|
800
998
|
* overload of `glaze.color()`.
|
|
801
999
|
*
|
|
802
|
-
* Strings cover hex (`#rgb` / `#
|
|
803
|
-
*
|
|
804
|
-
* `
|
|
805
|
-
*
|
|
1000
|
+
* Strings cover hex with a leading `#` (`#rgb` / `#rgba` / `#rrggbb` /
|
|
1001
|
+
* `#rrggbbaa`) and the five color functions Glaze itself emits: `rgb()`,
|
|
1002
|
+
* `hsl()`, `okhsl()`, `okhst()`, `oklch()`, plus the `rgba()` / `hsla()`
|
|
1003
|
+
* aliases. Function names are case-insensitive; components are numbers or
|
|
1004
|
+
* percentages, separated by spaces or commas. Their scales:
|
|
1005
|
+
* - `rgb()` — channels 0–255, or percentages (`100%` is 255).
|
|
1006
|
+
* - `hsl()` / `okhsl()` / `okhst()` — saturation, lightness and tone are
|
|
1007
|
+
* percentages or bare 0–1 fractions: `hsl(120 50% 50%)` or
|
|
1008
|
+
* `hsl(120 0.5 0.5)`. Unlike CSS, a bare `hsl(120 50 50)` does not mean
|
|
1009
|
+
* 50%; it is out of range and resolves to white without a warning.
|
|
1010
|
+
* - `oklch()` — L 0–1 or a percentage; C bare, or a percentage where
|
|
1011
|
+
* `100%` is 0.4.
|
|
1012
|
+
* - Hue is in degrees, bare or with `deg`. Other angle units (`turn`,
|
|
1013
|
+
* `rad`, `grad`) are misread as degrees rather than rejected.
|
|
1014
|
+
*
|
|
1015
|
+
* An alpha component (hex alpha, `/ A`, or any fourth component) is
|
|
1016
|
+
* dropped with a warning. Named colors, other color functions, and
|
|
1017
|
+
* relative color syntax throw.
|
|
806
1018
|
*
|
|
807
|
-
* Literal object forms:
|
|
808
|
-
* - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1). Passing 0–100 for `s`/`l`
|
|
809
|
-
* throws with a hint to use the structured form.
|
|
810
|
-
* - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1.
|
|
1019
|
+
* Literal object forms, told apart by their keys:
|
|
811
1020
|
* - `{ r, g, b }` — sRGB 0–255.
|
|
812
1021
|
* - `{ l, c, h }` — OKLCh (L/C: 0–1, H: degrees), same as `oklch()` strings.
|
|
1022
|
+
* - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1, so `t: 0.7` is
|
|
1023
|
+
* tone 70.
|
|
1024
|
+
* - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1).
|
|
1025
|
+
*
|
|
1026
|
+
* An object `s`, `l`, `t` or `c` above 1.5 throws, which catches 0–100
|
|
1027
|
+
* input; the OKHSL / OKHST errors point to the structured form. String
|
|
1028
|
+
* components have no such check.
|
|
813
1029
|
*/
|
|
814
1030
|
type GlazeColorValue = string | OkhslColor | OkhstColor | RgbColor | OklchColor;
|
|
815
1031
|
/** Color overrides for the `from` and value-shorthand inputs. */
|
|
@@ -908,7 +1124,8 @@ interface GlazeColorOverrides {
|
|
|
908
1124
|
/**
|
|
909
1125
|
* Optional human-readable name for the token. Used in error and
|
|
910
1126
|
* warning messages (otherwise an internal name like `"value"` is
|
|
911
|
-
* used).
|
|
1127
|
+
* used) and as `resolve().name`. A debug label only: it does not
|
|
1128
|
+
* affect output keys or the token's `role`.
|
|
912
1129
|
*/
|
|
913
1130
|
name?: string;
|
|
914
1131
|
/**
|
|
@@ -919,9 +1136,12 @@ interface GlazeColorOverrides {
|
|
|
919
1136
|
*/
|
|
920
1137
|
pastel?: boolean;
|
|
921
1138
|
/**
|
|
922
|
-
* Semantic role against `base
|
|
923
|
-
*
|
|
924
|
-
*
|
|
1139
|
+
* Semantic role against the token's anchor (`base`, or the literal seed
|
|
1140
|
+
* when `contrast` / a relative `tone` is set without one): how this token
|
|
1141
|
+
* is used. Fixes APCA contrast polarity; WCAG ignores it. Defaults to
|
|
1142
|
+
* `'text'` — the token is the foreground and the anchor the background,
|
|
1143
|
+
* with or without `base`. Unlike a theme color, a token never infers its
|
|
1144
|
+
* role from `name`, so `inferRole` has no effect on it.
|
|
925
1145
|
*/
|
|
926
1146
|
role?: RoleInput;
|
|
927
1147
|
}
|
|
@@ -954,8 +1174,9 @@ interface GlazeColorCssOptions {
|
|
|
954
1174
|
*/
|
|
955
1175
|
suffix?: string;
|
|
956
1176
|
/**
|
|
957
|
-
* Emit hue as a separate custom property, referenced via
|
|
958
|
-
* Requires `format: 'oklch'`
|
|
1177
|
+
* Emit hue as a separate `--{name}-hue` custom property, referenced via
|
|
1178
|
+
* `var()`. Requires `format: 'oklch'` (any other format throws) and a
|
|
1179
|
+
* pastel token.
|
|
959
1180
|
*/
|
|
960
1181
|
splitHue?: boolean;
|
|
961
1182
|
}
|
|
@@ -1144,16 +1365,26 @@ interface GlazeTheme {
|
|
|
1144
1365
|
* theme.tokens()
|
|
1145
1366
|
* // → { light: { surface: 'okhsl(...)' }, dark: { surface: 'okhsl(...)' } }
|
|
1146
1367
|
* ```
|
|
1368
|
+
*
|
|
1369
|
+
* With `modes.hdr`, each scheme map is followed by a dense `<scheme>Hdr`
|
|
1370
|
+
* map (`lightHdr`, `darkHdr`, …): every glow with an HDR value in any
|
|
1371
|
+
* emitted scheme, as `color(srgb-linear …)`, or its SDR value where that
|
|
1372
|
+
* scheme has none.
|
|
1147
1373
|
*/
|
|
1148
1374
|
tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
|
|
1149
1375
|
/**
|
|
1150
1376
|
* Export as tasty style-to-state bindings.
|
|
1151
1377
|
* Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
|
|
1152
1378
|
* Spread into component styles or register as a recipe via `configure({ recipes })`.
|
|
1379
|
+
* With `modes.hdr`, a glow's HDR value follows each SDR key that has one,
|
|
1380
|
+
* under `states.hdr` (`'@media(dynamic-range: high)'`) combined with it.
|
|
1153
1381
|
* @see https://tasty.style/docs
|
|
1154
1382
|
*/
|
|
1155
|
-
tasty(options?:
|
|
1156
|
-
/**
|
|
1383
|
+
tasty(options?: GlazeTastyOptions): Record<string, Record<string, string>>;
|
|
1384
|
+
/**
|
|
1385
|
+
* Export as plain JSON. With `modes.hdr`, a glow variant with an HDR value
|
|
1386
|
+
* adds a `<scheme>Hdr` key (`lightHdr`, …) right after its SDR key.
|
|
1387
|
+
*/
|
|
1157
1388
|
json(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
|
|
1158
1389
|
/** Export as CSS custom property declarations. */
|
|
1159
1390
|
css(options?: GlazeCssOptions): GlazeCssResult;
|
|
@@ -1190,35 +1421,48 @@ interface GlazeExtendOptions {
|
|
|
1190
1421
|
/** Config override for the child theme. Merged with the parent's override. */
|
|
1191
1422
|
config?: GlazeConfigOverride;
|
|
1192
1423
|
}
|
|
1424
|
+
/**
|
|
1425
|
+
* Options for `token.token()` / `token.tasty()`, and the base of the theme and
|
|
1426
|
+
* palette `tasty()` options: output format, scheme variants, state aliases.
|
|
1427
|
+
*/
|
|
1193
1428
|
interface GlazeTokenOptions {
|
|
1194
|
-
/**
|
|
1195
|
-
|
|
1196
|
-
|
|
1429
|
+
/**
|
|
1430
|
+
* Override state aliases for this export. `hdr` keys an HDR glow value
|
|
1431
|
+
* (with `modes.hdr`); a `glaze.color()` token is never a glow, so it never
|
|
1432
|
+
* uses it.
|
|
1433
|
+
*/
|
|
1197
1434
|
states?: {
|
|
1198
1435
|
dark?: string;
|
|
1199
1436
|
highContrast?: string;
|
|
1437
|
+
hdr?: string;
|
|
1200
1438
|
};
|
|
1201
1439
|
/** Override which scheme variants to include. */
|
|
1202
1440
|
modes?: GlazeOutputModes;
|
|
1203
1441
|
/** Output color format. Default: 'oklch'. */
|
|
1204
1442
|
format?: GlazeColorFormat;
|
|
1443
|
+
}
|
|
1444
|
+
/** Options for `theme.tasty()`. */
|
|
1445
|
+
interface GlazeTastyOptions extends GlazeTokenOptions {
|
|
1205
1446
|
/**
|
|
1206
1447
|
* Emit hue as a separate custom property, referenced via `var()`.
|
|
1207
|
-
* Requires `format: 'oklch'` and every color to
|
|
1448
|
+
* Requires `format: 'oklch'` (any other format throws) and every color to
|
|
1449
|
+
* be pastel.
|
|
1208
1450
|
*/
|
|
1209
1451
|
splitHue?: boolean;
|
|
1210
1452
|
/**
|
|
1211
1453
|
* Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
|
|
1212
|
-
*
|
|
1454
|
+
* Must not equal the name of a color that sets its own hue (throws).
|
|
1213
1455
|
*/
|
|
1214
1456
|
name?: string;
|
|
1215
1457
|
}
|
|
1458
|
+
/** Options for `theme.tokens()` / `theme.json()` and their palette and token counterparts. */
|
|
1216
1459
|
interface GlazeJsonOptions {
|
|
1217
1460
|
/** Override which scheme variants to include. */
|
|
1218
1461
|
modes?: GlazeOutputModes;
|
|
1219
1462
|
/** Output color format. Default: 'oklch'. */
|
|
1220
1463
|
format?: GlazeColorFormat;
|
|
1221
1464
|
}
|
|
1465
|
+
/** Options for `theme.css()`. */
|
|
1222
1466
|
interface GlazeCssOptions {
|
|
1223
1467
|
/** Output color format. Default: 'oklch'. */
|
|
1224
1468
|
format?: GlazeColorFormat;
|
|
@@ -1226,22 +1470,43 @@ interface GlazeCssOptions {
|
|
|
1226
1470
|
suffix?: string;
|
|
1227
1471
|
/**
|
|
1228
1472
|
* Emit hue as a separate custom property, referenced via `var()`.
|
|
1229
|
-
* Requires `format: 'oklch'` and every color to
|
|
1473
|
+
* Requires `format: 'oklch'` (any other format throws) and every color to
|
|
1474
|
+
* be pastel.
|
|
1230
1475
|
*/
|
|
1231
1476
|
splitHue?: boolean;
|
|
1232
1477
|
/**
|
|
1233
1478
|
* Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
|
|
1234
|
-
*
|
|
1479
|
+
* Must not equal the name of a color that sets its own hue (throws).
|
|
1235
1480
|
*/
|
|
1236
1481
|
name?: string;
|
|
1482
|
+
/**
|
|
1483
|
+
* Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
|
|
1484
|
+
* Default: the global `modes.hdr` (false). `css()` has no `modes` — it
|
|
1485
|
+
* always emits all four schemes — so this is its HDR switch.
|
|
1486
|
+
*/
|
|
1487
|
+
hdr?: boolean;
|
|
1237
1488
|
}
|
|
1238
|
-
/** CSS custom property declarations
|
|
1239
|
-
interface
|
|
1489
|
+
/** CSS custom property declarations for each scheme variant. */
|
|
1490
|
+
interface GlazeCssSchemeBlocks {
|
|
1240
1491
|
light: string;
|
|
1241
1492
|
dark: string;
|
|
1242
1493
|
lightContrast: string;
|
|
1243
1494
|
darkContrast: string;
|
|
1244
1495
|
}
|
|
1496
|
+
/** CSS custom property declarations grouped by scheme variant. */
|
|
1497
|
+
interface GlazeCssResult extends GlazeCssSchemeBlocks {
|
|
1498
|
+
/**
|
|
1499
|
+
* The HDR tier, present when HDR output is on — the `hdr` option, which
|
|
1500
|
+
* defaults to the global `modes.hdr`: one block per scheme,
|
|
1501
|
+
* each re-declaring every color that has an HDR value in any scheme — its
|
|
1502
|
+
* HDR value (`color(srgb-linear R G B)`) where that scheme has one, and
|
|
1503
|
+
* the scheme's SDR declaration where it has none. The blocks are dense so
|
|
1504
|
+
* a light HDR value can never leak into dark: wire each one after the SDR
|
|
1505
|
+
* blocks, under the same selector plus `(dynamic-range: high)`. Every block
|
|
1506
|
+
* is an empty string when no color has an HDR value.
|
|
1507
|
+
*/
|
|
1508
|
+
hdr?: GlazeCssSchemeBlocks;
|
|
1509
|
+
}
|
|
1245
1510
|
/**
|
|
1246
1511
|
* Color space used for DTCG `$value` color objects.
|
|
1247
1512
|
* @see https://www.designtokens.org/
|
|
@@ -1271,14 +1536,49 @@ interface DtcgOklchColorValue {
|
|
|
1271
1536
|
}
|
|
1272
1537
|
/** A DTCG `$value` for a color token, in either supported color space. */
|
|
1273
1538
|
type DtcgColorValue = DtcgSrgbColorValue | DtcgOklchColorValue;
|
|
1539
|
+
/**
|
|
1540
|
+
* The HDR value of a glow past SDR white, carried in a DTCG token's
|
|
1541
|
+
* `$extensions['me.tenphi.glaze'].hdr` (`$value` stays the SDR color, since
|
|
1542
|
+
* DTCG color components stop at 1). Maps onto native APIs: UIKit / AppKit
|
|
1543
|
+
* `exposure`, SwiftUI `exposureAdjust(exposure)` on `base`, or Android
|
|
1544
|
+
* `Color.pack(…components, LINEAR_EXTENDED_SRGB)` from `value`.
|
|
1545
|
+
*/
|
|
1546
|
+
interface GlazeDtcgHdr {
|
|
1547
|
+
/** Gain over `base` in stops (`log2` of the linear factor), above 0. */
|
|
1548
|
+
exposure: number;
|
|
1549
|
+
/**
|
|
1550
|
+
* Luminance tone of the HDR value (e.g. `112`) — past 100 when the headroom
|
|
1551
|
+
* covers the step; a saturated base capped by `headroom` can land below 100,
|
|
1552
|
+
* though its brightest channel still exceeds 1.
|
|
1553
|
+
*/
|
|
1554
|
+
tone: number;
|
|
1555
|
+
/** The opaque base (what SDR paints), as a DTCG sRGB color. */
|
|
1556
|
+
base: DtcgSrgbColorValue;
|
|
1557
|
+
/**
|
|
1558
|
+
* The HDR color: linear sRGB `base × 2^exposure`, its brightest channel
|
|
1559
|
+
* above 1 (the others may stay below).
|
|
1560
|
+
*/
|
|
1561
|
+
value: {
|
|
1562
|
+
colorSpace: 'srgb-linear';
|
|
1563
|
+
components: [number, number, number];
|
|
1564
|
+
};
|
|
1565
|
+
}
|
|
1566
|
+
/** The Glaze namespace of a DTCG token's `$extensions`. */
|
|
1567
|
+
interface GlazeDtcgExtensions {
|
|
1568
|
+
'me.tenphi.glaze': {
|
|
1569
|
+
/** Present only with `modes.hdr`, on a glow variant that has an HDR value. */hdr: GlazeDtcgHdr;
|
|
1570
|
+
};
|
|
1571
|
+
}
|
|
1274
1572
|
/**
|
|
1275
1573
|
* A single W3C DTCG color token: `{ $type: 'color', $value }`.
|
|
1276
|
-
* `$description` is optional and not populated by Glaze today.
|
|
1574
|
+
* `$description` is optional and not populated by Glaze today. `$extensions`
|
|
1575
|
+
* is set only with `modes.hdr`, on a glow variant with an HDR value.
|
|
1277
1576
|
*/
|
|
1278
1577
|
interface DtcgColorToken {
|
|
1279
1578
|
$type: 'color';
|
|
1280
1579
|
$value: DtcgColorValue;
|
|
1281
1580
|
$description?: string;
|
|
1581
|
+
$extensions?: GlazeDtcgExtensions;
|
|
1282
1582
|
}
|
|
1283
1583
|
/**
|
|
1284
1584
|
* A W3C Design Tokens Format Module (2025.10) token tree for one scheme.
|
|
@@ -1412,6 +1712,15 @@ interface GlazeTailwindOptions {
|
|
|
1412
1712
|
* `.dark.high-contrast`).
|
|
1413
1713
|
*/
|
|
1414
1714
|
highContrastSelector?: string;
|
|
1715
|
+
/**
|
|
1716
|
+
* Selector wrapping the HDR overrides, emitted with `modes.hdr` after every
|
|
1717
|
+
* SDR block. Default: `'@media (dynamic-range: high)'`. Each HDR block is
|
|
1718
|
+
* dense (every color with an HDR value in any emitted scheme, SDR value
|
|
1719
|
+
* where the scheme has none) and is scoped by this selector alone (light),
|
|
1720
|
+
* combined with `darkSelector` (dark), with `highContrastSelector` (light
|
|
1721
|
+
* high contrast), or with both.
|
|
1722
|
+
*/
|
|
1723
|
+
hdrSelector?: string;
|
|
1415
1724
|
}
|
|
1416
1725
|
/** Options for `glaze.color().tailwind()`. `name` is required. */
|
|
1417
1726
|
interface GlazeColorTailwindOptions extends GlazeTailwindOptions {
|
|
@@ -1434,7 +1743,10 @@ interface GlazePaletteOptions {
|
|
|
1434
1743
|
*/
|
|
1435
1744
|
primary?: string;
|
|
1436
1745
|
}
|
|
1437
|
-
/**
|
|
1746
|
+
/**
|
|
1747
|
+
* Options shared by every palette export except `json()`: `tokens()`,
|
|
1748
|
+
* `tasty()`, `css()`, `dtcg()`, `dtcgResolver()`, and `tailwind()`.
|
|
1749
|
+
*/
|
|
1438
1750
|
interface GlazePaletteExportOptions {
|
|
1439
1751
|
/**
|
|
1440
1752
|
* Prefix mode. `true` uses `"<themeName>-"`, or provide a custom map.
|
|
@@ -1449,11 +1761,39 @@ interface GlazePaletteExportOptions {
|
|
|
1449
1761
|
* When omitted, inherits the palette-level `primary`.
|
|
1450
1762
|
*/
|
|
1451
1763
|
primary?: string | false;
|
|
1764
|
+
}
|
|
1765
|
+
/**
|
|
1766
|
+
* Options for `palette.tasty()`. There is no `name`: each theme's hue var is
|
|
1767
|
+
* named after the theme.
|
|
1768
|
+
*/
|
|
1769
|
+
interface GlazePaletteTastyOptions extends GlazeTokenOptions, GlazePaletteExportOptions {
|
|
1770
|
+
/**
|
|
1771
|
+
* Emit hue as a separate custom property, referenced via `var()`.
|
|
1772
|
+
* Requires `format: 'oklch'` (any other format throws) and every color to
|
|
1773
|
+
* be pastel. The theme-level hue var is `--{themeName}-hue`.
|
|
1774
|
+
*/
|
|
1775
|
+
splitHue?: boolean;
|
|
1776
|
+
}
|
|
1777
|
+
/**
|
|
1778
|
+
* Options for `palette.css()`. There is no `name`: each theme's hue var is
|
|
1779
|
+
* named after the theme.
|
|
1780
|
+
*/
|
|
1781
|
+
interface GlazePaletteCssOptions extends GlazePaletteExportOptions {
|
|
1782
|
+
/** Output color format. Default: 'oklch'. */
|
|
1783
|
+
format?: GlazeColorFormat;
|
|
1784
|
+
/** Suffix appended to each CSS custom property name. Default: '-color'. */
|
|
1785
|
+
suffix?: string;
|
|
1452
1786
|
/**
|
|
1453
1787
|
* Emit hue as a separate custom property, referenced via `var()`.
|
|
1454
|
-
* Requires `format: 'oklch'` and every color to
|
|
1788
|
+
* Requires `format: 'oklch'` (any other format throws) and every color to
|
|
1789
|
+
* be pastel. The theme-level hue var is `--{themeName}-hue`.
|
|
1455
1790
|
*/
|
|
1456
1791
|
splitHue?: boolean;
|
|
1792
|
+
/**
|
|
1793
|
+
* Add the HDR tier as `result.hdr` (see {@link GlazeCssResult.hdr}).
|
|
1794
|
+
* Default: the global `modes.hdr` (false).
|
|
1795
|
+
*/
|
|
1796
|
+
hdr?: boolean;
|
|
1457
1797
|
}
|
|
1458
1798
|
interface GlazePalette {
|
|
1459
1799
|
/** Theme names in insertion order. */
|
|
@@ -1492,13 +1832,14 @@ interface GlazePalette {
|
|
|
1492
1832
|
* Prefix defaults to `true`. Inherits the palette-level `primary`.
|
|
1493
1833
|
* @see https://tasty.style/docs
|
|
1494
1834
|
*/
|
|
1495
|
-
tasty(options?:
|
|
1496
|
-
/**
|
|
1497
|
-
|
|
1498
|
-
|
|
1499
|
-
|
|
1835
|
+
tasty(options?: GlazePaletteTastyOptions): Record<string, Record<string, string>>;
|
|
1836
|
+
/**
|
|
1837
|
+
* Export all themes as plain JSON grouped by theme name. No prefix, primary
|
|
1838
|
+
* alias, or collision handling: each theme keeps its own key.
|
|
1839
|
+
*/
|
|
1840
|
+
json(options?: GlazeJsonOptions): Record<string, Record<string, Record<string, string>>>;
|
|
1500
1841
|
/** Export all themes as CSS custom property declarations. */
|
|
1501
|
-
css(options?:
|
|
1842
|
+
css(options?: GlazePaletteCssOptions): GlazeCssResult;
|
|
1502
1843
|
/**
|
|
1503
1844
|
* Export all themes as W3C DTCG documents, one per scheme variant.
|
|
1504
1845
|
* Prefix defaults to `true`. Inherits the palette-level `primary`.
|
|
@@ -1553,9 +1894,13 @@ type PaletteInput = Record<string, GlazeTheme>;
|
|
|
1553
1894
|
* const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
|
|
1554
1895
|
* // with config override:
|
|
1555
1896
|
* const raw = glaze(280, 80, { lightTone: false });
|
|
1897
|
+
* const rawSeed = glaze({ hue: 280, saturation: 80 }, { lightTone: false });
|
|
1556
1898
|
* ```
|
|
1557
1899
|
*/
|
|
1558
|
-
declare function glaze(
|
|
1900
|
+
declare function glaze(hue: number, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
|
|
1901
|
+
declare function glaze(seed: GlazeThemeSeed, config?: GlazeConfigOverride): GlazeTheme;
|
|
1902
|
+
/** @deprecated Pass the config second: `glaze(seed, config)`. */
|
|
1903
|
+
declare function glaze(seed: GlazeThemeSeed, saturation: undefined, config?: GlazeConfigOverride): GlazeTheme;
|
|
1559
1904
|
declare namespace glaze {
|
|
1560
1905
|
var configure: (config: GlazeConfig) => void;
|
|
1561
1906
|
var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
|
|
@@ -1563,7 +1908,9 @@ declare namespace glaze {
|
|
|
1563
1908
|
var from: (data: GlazeThemeExport) => GlazeTheme;
|
|
1564
1909
|
var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
|
|
1565
1910
|
var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
|
|
1911
|
+
var glow: (input: GlazeGlowInput) => ResolvedColorVariant;
|
|
1566
1912
|
var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
|
|
1913
|
+
var formatHdr: (variant: ResolvedColorVariant, hdrFormat?: GlazeHdrFormat) => string | undefined;
|
|
1567
1914
|
var fromHex: (hex: string) => GlazeTheme;
|
|
1568
1915
|
var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
|
|
1569
1916
|
var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
|
|
@@ -1583,7 +1930,7 @@ interface HueDeclaration {
|
|
|
1583
1930
|
interface HuePlan {
|
|
1584
1931
|
/** CSS `var()` reference spliced into `oklch(L C <hueVar>)`. */
|
|
1585
1932
|
hueVar: string;
|
|
1586
|
-
/** When true, emit a full inline color (shadow/mix/achromatic). */
|
|
1933
|
+
/** When true, emit a full inline color (shadow/glow/mix/achromatic). */
|
|
1587
1934
|
inline: boolean;
|
|
1588
1935
|
/** Scheme-independent `--*-hue` declarations for this color. */
|
|
1589
1936
|
declarations: HueDeclaration[];
|
|
@@ -1720,7 +2067,11 @@ declare function variantToOkhsl(v: {
|
|
|
1720
2067
|
*
|
|
1721
2068
|
* Provides bidirectional OKHSL ↔ sRGB conversion, luminance computation
|
|
1722
2069
|
* for both contrast metrics (WCAG 2 relative luminance and APCA screen
|
|
1723
|
-
* luminance `Ys`
|
|
2070
|
+
* luminance `Ys` — both the exact functions the contrast solver uses, and
|
|
2071
|
+
* both public), strict hex parsing (`parseHex` / `parseHexAlpha` check every
|
|
2072
|
+
* digit), and multi-format output (okhsl, rgb, hsl, oklch, plus the
|
|
2073
|
+
* `color(srgb-linear …)` writer for HDR glow values, whose channels may exceed
|
|
2074
|
+
* 1).
|
|
1724
2075
|
*/
|
|
1725
2076
|
type Vec3 = [number, number, number];
|
|
1726
2077
|
/**
|
|
@@ -1766,6 +2117,22 @@ declare function okhslToSrgb(h: number, s: number, l: number, pastel?: boolean):
|
|
|
1766
2117
|
* This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
|
|
1767
2118
|
*/
|
|
1768
2119
|
declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
|
|
2120
|
+
/**
|
|
2121
|
+
* Compute APCA screen luminance (`Ys`) from linear sRGB.
|
|
2122
|
+
*
|
|
2123
|
+
* APCA does not use the WCAG piecewise sRGB EOTF; it defines its own
|
|
2124
|
+
* luminance as `0.2126·R^2.4 + 0.7152·G^2.4 + 0.0722·B^2.4` over the
|
|
2125
|
+
* gamma-encoded (display) channels with a simple 2.4 exponent. The APCA
|
|
2126
|
+
* soft-clamp threshold in `apcaContrast` is calibrated against this basis,
|
|
2127
|
+
* so the solver must feed it `Ys`, not WCAG relative luminance. Channels
|
|
2128
|
+
* are gamut-clamped to [0, 1] first, matching `gamutClampedLuminance`.
|
|
2129
|
+
*
|
|
2130
|
+
* This is exactly the luminance Glaze's contrast solver (and its drift
|
|
2131
|
+
* check) feeds `apcaContrast`, so
|
|
2132
|
+
* `apcaContrast(apcaLuminanceFromLinearRgb(text), apcaLuminanceFromLinearRgb(bg))`
|
|
2133
|
+
* reproduces the solver's Lc for a resolved pair.
|
|
2134
|
+
*/
|
|
2135
|
+
declare function apcaLuminanceFromLinearRgb(linearRgb: [number, number, number]): number;
|
|
1769
2136
|
/**
|
|
1770
2137
|
* Convert OKLab to OKHSL.
|
|
1771
2138
|
* Input: [L, a, b] where L: 0–1, a/b: roughly -0.5 to 0.5.
|
|
@@ -1787,7 +2154,9 @@ declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [
|
|
|
1787
2154
|
declare function hslToSrgb(h: number, s: number, l: number): [number, number, number];
|
|
1788
2155
|
/**
|
|
1789
2156
|
* Parse a hex color string (#rgb or #rrggbb) to sRGB [r, g, b] in 0–1 range.
|
|
1790
|
-
* Returns null if the string is not a valid hex
|
|
2157
|
+
* The leading `#` is optional. Returns null if the string is not a valid hex
|
|
2158
|
+
* color: a wrong length, any character outside `0-9a-f` (case-insensitive),
|
|
2159
|
+
* or a form with alpha.
|
|
1791
2160
|
*
|
|
1792
2161
|
* For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
|
|
1793
2162
|
* use {@link parseHexAlpha}.
|
|
@@ -1796,7 +2165,12 @@ declare function parseHex(hex: string): [number, number, number] | null;
|
|
|
1796
2165
|
/**
|
|
1797
2166
|
* Parse a hex color string (#rgb, #rrggbb, #rgba, or #rrggbbaa) to
|
|
1798
2167
|
* sRGB [r, g, b] in 0–1 range plus an optional alpha (0–1).
|
|
1799
|
-
* Returns null if the string is not a valid hex
|
|
2168
|
+
* The leading `#` is optional. Returns null if the string is not a valid hex
|
|
2169
|
+
* color: a wrong length or any character outside `0-9a-f`
|
|
2170
|
+
* (case-insensitive).
|
|
2171
|
+
*
|
|
2172
|
+
* Every digit is checked up front: `parseInt` alone stops at the first bad
|
|
2173
|
+
* character, so `'#1z2z3z'` would otherwise read as `#010203`.
|
|
1800
2174
|
*/
|
|
1801
2175
|
declare function parseHexAlpha(hex: string): {
|
|
1802
2176
|
rgb: [number, number, number];
|
|
@@ -1831,6 +2205,14 @@ declare function formatHsl(h: number, s: number, l: number, pastel?: boolean): s
|
|
|
1831
2205
|
* h: 0–360, s: 0–1, l: 0–1 (factor scale, as returned by every converter).
|
|
1832
2206
|
*/
|
|
1833
2207
|
declare function formatOklch(h: number, s: number, l: number, pastel?: boolean): string;
|
|
2208
|
+
/**
|
|
2209
|
+
* Format linear sRGB channels as a CSS `color(srgb-linear R G B)` string with
|
|
2210
|
+
* 4 decimals. Unlike the other writers it takes linear light, not OKHSL, and
|
|
2211
|
+
* does not clamp: a channel may exceed 1, which is how an HDR glow value
|
|
2212
|
+
* (`glaze.formatHdr()`) goes past SDR white — `1` is SDR white, `2` one stop
|
|
2213
|
+
* above it. Opaque only; HDR values carry no alpha.
|
|
2214
|
+
*/
|
|
2215
|
+
declare function formatSrgbLinear(rgb: [number, number, number]): string;
|
|
1834
2216
|
/**
|
|
1835
2217
|
* Convert gamma-encoded sRGB channels (0–1) to a 6-digit lowercase hex
|
|
1836
2218
|
* string (`#rrggbb`). Channels are clamped to [0,1] and rounded to 8-bit.
|
|
@@ -1844,5 +2226,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
|
|
|
1844
2226
|
*/
|
|
1845
2227
|
declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
|
|
1846
2228
|
//#endregion
|
|
1847
|
-
export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, GLAZE_EXPORT_VERSION, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeThemeSeed, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
|
|
2229
|
+
export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, GLAZE_EXPORT_VERSION, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeCssSchemeBlocks, type GlazeDtcgExtensions, type GlazeDtcgHdr, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeGlowInput, type GlazeHdrFormat, type GlazeJsonOptions, type GlazeLightingInput, type GlazeOutputModes, type GlazePalette, type GlazePaletteCssOptions, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazePaletteTastyOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTastyOptions, type GlazeTheme, type GlazeThemeExport, type GlazeThemeSeed, type GlazeTokenOptions, type GlowColorDef, type GlowTuning, type HCPair, type HexColor, type HueDeclaration, type HuePlan, type LightingTuning, type MinContrast, type MixColorDef, type OkhslColor, type OkhstColor, type OklchColor, type Polarity, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type ResolvedHdr, type RgbColor, type Role, type RoleInput, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, apcaLuminanceFromLinearRgb, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, formatSrgbLinear, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
|
|
1848
2230
|
//# sourceMappingURL=index.d.cts.map
|