@tenphi/glaze 0.0.0-snapshot.cdd8acc → 0.0.0-snapshot.d38eee5
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/README.md +24 -1148
- package/dist/index.cjs +2199 -945
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +679 -118
- package/dist/index.d.mts +679 -118
- package/dist/index.mjs +2182 -945
- package/dist/index.mjs.map +1 -1
- package/docs/api.md +1287 -0
- package/docs/methodology.md +346 -0
- package/docs/migration.md +308 -0
- package/docs/okhst.md +259 -0
- package/package.json +9 -9
package/dist/index.d.cts
CHANGED
|
@@ -1,48 +1,93 @@
|
|
|
1
1
|
//#region src/contrast-solver.d.ts
|
|
2
|
-
/**
|
|
3
|
-
* OKHSL Contrast Solver
|
|
4
|
-
*
|
|
5
|
-
* Finds the closest OKHSL lightness that satisfies a WCAG 2 contrast target
|
|
6
|
-
* against a base color. Used by glaze when resolving dependent colors
|
|
7
|
-
* with `contrast`.
|
|
8
|
-
*/
|
|
9
2
|
type LinearRgb = [number, number, number];
|
|
10
3
|
type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
|
|
11
4
|
type MinContrast$1 = number | ContrastPreset;
|
|
12
|
-
|
|
5
|
+
/**
|
|
6
|
+
* Named APCA Lc floor presets (APCA Bronze Simple Mode conformance levels),
|
|
7
|
+
* independent of role. Use them anywhere an APCA target is accepted.
|
|
8
|
+
*
|
|
9
|
+
* | Preset | Lc | Use case |
|
|
10
|
+
* | ------------- | --- | ---------------------------------------------------- |
|
|
11
|
+
* | `'preferred'` | 90 | Preferred body / column text |
|
|
12
|
+
* | `'body'` | 75 | Minimum body / column text |
|
|
13
|
+
* | `'content'` | 60 | Readable non-body content (~WCAG AA 4.5:1) |
|
|
14
|
+
* | `'large'` | 45 | Large/bold headlines; fine icons/outlines (~3:1) |
|
|
15
|
+
* | `'non-text'` | 30 | Solid icons/controls; placeholder/disabled text |
|
|
16
|
+
* | `'min'` | 15 | Dividers/decorative; APCA "point of invisibility" |
|
|
17
|
+
*/
|
|
18
|
+
type ApcaPreset = 'preferred' | 'body' | 'content' | 'large' | 'non-text' | 'min';
|
|
19
|
+
/**
|
|
20
|
+
* Resolve an APCA target — a raw Lc number (kept as-is) or an `ApcaPreset`
|
|
21
|
+
* keyword mapped to its Lc value. The magnitude is forced non-negative.
|
|
22
|
+
*/
|
|
23
|
+
declare function resolveApcaTarget(value: number | ApcaPreset): number;
|
|
24
|
+
/** Metric + numeric target after resolving a `ContrastSpec` for a mode. */
|
|
25
|
+
interface ResolvedContrast {
|
|
26
|
+
metric: 'wcag' | 'apca';
|
|
27
|
+
/** WCAG ratio (>= 1) or APCA Lc magnitude (0–106). */
|
|
28
|
+
target: number;
|
|
29
|
+
/**
|
|
30
|
+
* APCA argument order: which side the resolved (candidate) color plays
|
|
31
|
+
* against the base. `'fg'` (default) → `apcaContrast(yCandidate, yBase)`;
|
|
32
|
+
* `'bg'` → `apcaContrast(yBase, yCandidate)`. Always `'fg'` for WCAG
|
|
33
|
+
* (symmetric, ignored).
|
|
34
|
+
*/
|
|
35
|
+
polarity?: 'fg' | 'bg';
|
|
36
|
+
}
|
|
37
|
+
declare function resolveMinContrast(value: MinContrast$1): number;
|
|
38
|
+
/**
|
|
39
|
+
* Resolve a `ContrastSpec` (already selected from any outer HC pair) for a
|
|
40
|
+
* given mode into `{ metric, target }`. Handles the inner metric HC pair and
|
|
41
|
+
* preset resolution. `polarity` is passed through to the result for the APCA
|
|
42
|
+
* branch (it controls argument order in the solver); WCAG ignores it.
|
|
43
|
+
*/
|
|
44
|
+
declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg'): ResolvedContrast;
|
|
45
|
+
/**
|
|
46
|
+
* APCA lightness contrast (Lc), signed: positive for dark text on light bg,
|
|
47
|
+
* negative for light text on dark bg. Inputs are screen luminances (0–1).
|
|
48
|
+
*/
|
|
49
|
+
declare function apcaContrast(yText: number, yBg: number): number;
|
|
50
|
+
interface FindToneForContrastOptions {
|
|
13
51
|
/** Hue of the candidate color (0–360). */
|
|
14
52
|
hue: number;
|
|
15
53
|
/** Saturation of the candidate color (0–1). */
|
|
16
54
|
saturation: number;
|
|
17
|
-
/** Preferred
|
|
18
|
-
|
|
19
|
-
/** Base/reference color as linear sRGB
|
|
20
|
-
baseLinearRgb:
|
|
21
|
-
/**
|
|
22
|
-
contrast:
|
|
23
|
-
/** Search bounds for
|
|
24
|
-
|
|
55
|
+
/** Preferred tone of the candidate (0–1). */
|
|
56
|
+
preferredTone: number;
|
|
57
|
+
/** Base/reference color as linear sRGB. */
|
|
58
|
+
baseLinearRgb: LinearRgb;
|
|
59
|
+
/** Resolved contrast floor (metric + target). */
|
|
60
|
+
contrast: ResolvedContrast;
|
|
61
|
+
/** Search bounds for tone. Default: [0, 1]. */
|
|
62
|
+
toneRange?: [number, number];
|
|
25
63
|
/** Convergence threshold. Default: 1e-4. */
|
|
26
64
|
epsilon?: number;
|
|
27
|
-
/** Maximum binary-search iterations per branch. Default:
|
|
65
|
+
/** Maximum binary-search iterations per branch. Default: 18. */
|
|
28
66
|
maxIterations?: number;
|
|
67
|
+
/** Preferred search direction before auto-flip is considered. */
|
|
68
|
+
initialDirection?: 'lighter' | 'darker';
|
|
69
|
+
/** Auto-flip tone direction when contrast can't be met. Default: false. */
|
|
70
|
+
flip?: boolean;
|
|
71
|
+
/** Use the hue-independent "safe" chroma boundary. Default: false. */
|
|
72
|
+
pastel?: boolean;
|
|
29
73
|
}
|
|
30
|
-
interface
|
|
31
|
-
/** Chosen
|
|
32
|
-
|
|
33
|
-
/** Achieved WCAG
|
|
74
|
+
interface FindToneForContrastResult {
|
|
75
|
+
/** Chosen tone in 0–1. */
|
|
76
|
+
tone: number;
|
|
77
|
+
/** Achieved score (WCAG ratio or APCA Lc magnitude). */
|
|
34
78
|
contrast: number;
|
|
35
79
|
/** Whether the target was reached. */
|
|
36
80
|
met: boolean;
|
|
37
81
|
/** Which branch was selected. */
|
|
38
82
|
branch: 'lighter' | 'darker' | 'preferred';
|
|
83
|
+
/** Whether the result auto-flipped to the opposite direction. */
|
|
84
|
+
flipped?: boolean;
|
|
39
85
|
}
|
|
40
|
-
declare function resolveMinContrast(value: MinContrast$1): number;
|
|
41
86
|
/**
|
|
42
|
-
* Find the
|
|
43
|
-
*
|
|
87
|
+
* Find the tone that satisfies a contrast floor against a base color,
|
|
88
|
+
* staying as close to `preferredTone` as possible.
|
|
44
89
|
*/
|
|
45
|
-
declare function
|
|
90
|
+
declare function findToneForContrast(options: FindToneForContrastOptions): FindToneForContrastResult;
|
|
46
91
|
interface FindValueForMixContrastOptions {
|
|
47
92
|
/** Preferred mix parameter (0–1). */
|
|
48
93
|
preferredValue: number;
|
|
@@ -50,40 +95,82 @@ interface FindValueForMixContrastOptions {
|
|
|
50
95
|
baseLinearRgb: LinearRgb;
|
|
51
96
|
/** Target color as linear sRGB. */
|
|
52
97
|
targetLinearRgb: LinearRgb;
|
|
53
|
-
/**
|
|
54
|
-
contrast:
|
|
55
|
-
/**
|
|
56
|
-
* Compute the luminance of the mixed color at parameter t.
|
|
57
|
-
* For opaque: luminance of OKHSL-interpolated color.
|
|
58
|
-
* For transparent: luminance of alpha-composited color over base.
|
|
59
|
-
*/
|
|
98
|
+
/** Resolved contrast floor (metric + target). */
|
|
99
|
+
contrast: ResolvedContrast;
|
|
100
|
+
/** Compute the luminance of the mixed color at parameter t. */
|
|
60
101
|
luminanceAtValue: (t: number) => number;
|
|
61
102
|
/** Convergence threshold. Default: 1e-4. */
|
|
62
103
|
epsilon?: number;
|
|
63
104
|
/** Maximum binary-search iterations per branch. Default: 20. */
|
|
64
105
|
maxIterations?: number;
|
|
106
|
+
/** Auto-flip mix direction when contrast can't be met. Default: false. */
|
|
107
|
+
flip?: boolean;
|
|
65
108
|
}
|
|
66
109
|
interface FindValueForMixContrastResult {
|
|
67
|
-
/** Chosen mix parameter (0–1). */
|
|
68
110
|
value: number;
|
|
69
|
-
/** Achieved WCAG contrast ratio. */
|
|
70
111
|
contrast: number;
|
|
71
|
-
/** Whether the target was reached. */
|
|
72
112
|
met: boolean;
|
|
113
|
+
flipped?: boolean;
|
|
73
114
|
}
|
|
74
115
|
/**
|
|
75
|
-
* Find the mix parameter (ratio or opacity) that satisfies a
|
|
76
|
-
*
|
|
116
|
+
* Find the mix parameter (ratio or opacity) that satisfies a contrast floor
|
|
117
|
+
* against a base color, staying as close to `preferredValue` as possible.
|
|
77
118
|
*/
|
|
78
119
|
declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
|
|
79
120
|
//#endregion
|
|
80
121
|
//#region src/types.d.ts
|
|
81
122
|
/** A value or [normal, high-contrast] pair. */
|
|
82
123
|
type HCPair<T> = T | [T, T];
|
|
124
|
+
/** Bare WCAG contrast target: a ratio number or a named preset. */
|
|
83
125
|
type MinContrast = number | ContrastPreset;
|
|
126
|
+
/**
|
|
127
|
+
* A contrast floor with a pluggable metric.
|
|
128
|
+
*
|
|
129
|
+
* - `number` / `ContrastPreset`: a WCAG ratio (bare form).
|
|
130
|
+
* - `{ wcag }`: WCAG ratio or preset, optionally an HC pair.
|
|
131
|
+
* - `{ apca }`: APCA Lc target (absolute value or preset), optionally an HC pair.
|
|
132
|
+
*
|
|
133
|
+
* The `[normal, highContrast]` pair may live at the outer level
|
|
134
|
+
* (`[4.5, 7]`, `[{ wcag: 4.5 }, { wcag: 7 }]`) or inside the metric
|
|
135
|
+
* (`{ wcag: [4.5, 7] }`, `{ apca: [45, 60] }`, `{ apca: ['content', 'body'] }`).
|
|
136
|
+
*/
|
|
137
|
+
type ContrastSpec = number | ContrastPreset | {
|
|
138
|
+
wcag: HCPair<number | ContrastPreset>;
|
|
139
|
+
} | {
|
|
140
|
+
apca: HCPair<number | ApcaPreset>;
|
|
141
|
+
};
|
|
142
|
+
/**
|
|
143
|
+
* The semantic role a color plays against its base, used to fix APCA contrast
|
|
144
|
+
* polarity (which side is the foreground vs the background). WCAG is
|
|
145
|
+
* symmetric, so role never changes WCAG results.
|
|
146
|
+
*/
|
|
147
|
+
type Role = 'text' | 'surface' | 'border';
|
|
148
|
+
/**
|
|
149
|
+
* Any string accepted as a `role`. Canonical values plus aliases normalized by
|
|
150
|
+
* `normalizeRole` (see `roles.ts`): `surface` (bg/background/fill/canvas/
|
|
151
|
+
* paper/layer), `text` (fg/foreground/content/ink/label/stroke), `border`
|
|
152
|
+
* (divider/outline/separator/hairline/rule).
|
|
153
|
+
*/
|
|
154
|
+
type RoleInput = Role | 'bg' | 'background' | 'fill' | 'canvas' | 'paper' | 'layer' | 'fg' | 'foreground' | 'content' | 'ink' | 'label' | 'stroke' | 'divider' | 'outline' | 'separator' | 'hairline' | 'rule';
|
|
84
155
|
type AdaptationMode = 'auto' | 'fixed' | 'static';
|
|
85
156
|
/** A signed relative offset string, e.g. '+20' or '-15.5'. */
|
|
86
157
|
type RelativeValue = `+${number}` | `-${number}`;
|
|
158
|
+
/**
|
|
159
|
+
* Force a color to a tone extreme:
|
|
160
|
+
* - `'max'`: the highest tone in the active scheme range/window.
|
|
161
|
+
* - `'min'`: the lowest tone.
|
|
162
|
+
*
|
|
163
|
+
* Under `mode: 'auto'` the extreme inverts in the dark scheme (so `'max'`
|
|
164
|
+
* tracks the inversion and becomes the darkest tone). No `base` required.
|
|
165
|
+
*/
|
|
166
|
+
type ExtremeValue = 'max' | 'min';
|
|
167
|
+
/**
|
|
168
|
+
* A tone value as authored on a color.
|
|
169
|
+
* - Number: absolute tone (0–100).
|
|
170
|
+
* - `'+N'` / `'-N'`: relative to the base's tone (requires `base`).
|
|
171
|
+
* - `'max'` / `'min'`: forced to the scheme's tone extreme (no base needed).
|
|
172
|
+
*/
|
|
173
|
+
type ToneValue = number | RelativeValue | ExtremeValue;
|
|
87
174
|
/** Color format for output. */
|
|
88
175
|
type GlazeColorFormat = 'okhsl' | 'rgb' | 'hsl' | 'oklch';
|
|
89
176
|
/**
|
|
@@ -104,13 +191,35 @@ interface OkhslColor {
|
|
|
104
191
|
s: number;
|
|
105
192
|
l: number;
|
|
106
193
|
}
|
|
194
|
+
/**
|
|
195
|
+
* Direct OKHST color input — OKHSL with the lightness axis replaced by the
|
|
196
|
+
* contrast-uniform tone axis. `h`: 0–360, `s`: 0–1, `t`: 0–1 (tone).
|
|
197
|
+
*/
|
|
198
|
+
interface OkhstColor {
|
|
199
|
+
h: number;
|
|
200
|
+
s: number;
|
|
201
|
+
t: number;
|
|
202
|
+
}
|
|
203
|
+
/** sRGB components in 0–255 (value-shorthand object form). */
|
|
204
|
+
interface RgbColor {
|
|
205
|
+
r: number;
|
|
206
|
+
g: number;
|
|
207
|
+
b: number;
|
|
208
|
+
}
|
|
209
|
+
/** OKLCh components matching CSS `oklch(L C H)` (L/C: 0–1, H: degrees). */
|
|
210
|
+
interface OklchColor {
|
|
211
|
+
l: number;
|
|
212
|
+
c: number;
|
|
213
|
+
h: number;
|
|
214
|
+
}
|
|
107
215
|
interface RegularColorDef {
|
|
108
216
|
/**
|
|
109
|
-
*
|
|
110
|
-
* - Number: absolute
|
|
111
|
-
* - String ('+N' / '-N'): relative to base color's
|
|
217
|
+
* Tone value (0–100, contrast-uniform — see `docs/okhst.md`).
|
|
218
|
+
* - Number: absolute tone.
|
|
219
|
+
* - String ('+N' / '-N'): relative to base color's tone (requires `base`).
|
|
220
|
+
* - `'max'` / `'min'`: force to the scheme's tone extreme (no base needed).
|
|
112
221
|
*/
|
|
113
|
-
|
|
222
|
+
tone?: HCPair<ToneValue>;
|
|
114
223
|
/** Saturation factor applied to the seed saturation (0–1, default: 1). */
|
|
115
224
|
saturation?: number;
|
|
116
225
|
/**
|
|
@@ -121,18 +230,50 @@ interface RegularColorDef {
|
|
|
121
230
|
hue?: number | RelativeValue;
|
|
122
231
|
/** Name of another color in the same theme (dependent color). */
|
|
123
232
|
base?: string;
|
|
124
|
-
/**
|
|
125
|
-
|
|
233
|
+
/**
|
|
234
|
+
* Contrast floor against the base color. A bare number/preset is WCAG;
|
|
235
|
+
* use `{ wcag }` / `{ apca }` to pick the metric. Accepts an HC pair.
|
|
236
|
+
*/
|
|
237
|
+
contrast?: HCPair<ContrastSpec>;
|
|
126
238
|
/** Adaptation mode. Default: 'auto'. */
|
|
127
239
|
mode?: AdaptationMode;
|
|
240
|
+
/**
|
|
241
|
+
* Whether to flip out-of-bounds results to the opposite side instead of
|
|
242
|
+
* clamping to the extreme. Affects both:
|
|
243
|
+
* - relative `tone`: when `base ± delta` exceeds `[0, 100]`, mirror the
|
|
244
|
+
* delta to the other side of the base.
|
|
245
|
+
* - `contrast`: when the requested direction can't meet the floor, try the
|
|
246
|
+
* opposite side (same as the global `autoFlip`).
|
|
247
|
+
*
|
|
248
|
+
* Defaults to the global `autoFlip` config (default `true`). Set `false`
|
|
249
|
+
* to clamp instead.
|
|
250
|
+
*/
|
|
251
|
+
flip?: boolean;
|
|
128
252
|
/**
|
|
129
253
|
* Fixed opacity (0–1).
|
|
130
254
|
* Output includes alpha in the CSS value.
|
|
131
255
|
* Does not affect contrast resolution — a semi-transparent color
|
|
132
|
-
* has no fixed perceived
|
|
256
|
+
* has no fixed perceived tone, so `contrast` and `opacity`
|
|
133
257
|
* should not be combined (a console.warn is emitted).
|
|
134
258
|
*/
|
|
135
259
|
opacity?: number;
|
|
260
|
+
/**
|
|
261
|
+
* Per-color override for the hue-independent "safe" chroma limit used in
|
|
262
|
+
* OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
|
|
263
|
+
* Falls through to the global / per-theme `pastel` config when omitted.
|
|
264
|
+
* @see GlazeConfig.pastel
|
|
265
|
+
*/
|
|
266
|
+
pastel?: boolean;
|
|
267
|
+
/**
|
|
268
|
+
* Semantic role against `base`: how this color is used. Fixes APCA contrast
|
|
269
|
+
* polarity (the argument order in `apcaContrast`). WCAG is symmetric so it
|
|
270
|
+
* never affects WCAG results.
|
|
271
|
+
*
|
|
272
|
+
* Resolution: explicit `role` wins; else inferred from the color name when
|
|
273
|
+
* `inferRole` is enabled (default); else the opposite of the base's role;
|
|
274
|
+
* else defaults to `'text'` (foreground).
|
|
275
|
+
*/
|
|
276
|
+
role?: RoleInput;
|
|
136
277
|
/**
|
|
137
278
|
* Whether this color is inherited by child themes created via `extend()`.
|
|
138
279
|
* Default: true. Set to false to make this color local to the current theme.
|
|
@@ -182,6 +323,13 @@ interface ShadowColorDef {
|
|
|
182
323
|
intensity: HCPair<number>;
|
|
183
324
|
/** Override default tuning. Merged field-by-field with global `shadowTuning`. */
|
|
184
325
|
tuning?: ShadowTuning;
|
|
326
|
+
/**
|
|
327
|
+
* Per-color override for the hue-independent "safe" chroma limit used in
|
|
328
|
+
* OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
|
|
329
|
+
* Falls through to the global / per-theme `pastel` config when omitted.
|
|
330
|
+
* @see GlazeConfig.pastel
|
|
331
|
+
*/
|
|
332
|
+
pastel?: boolean;
|
|
185
333
|
/**
|
|
186
334
|
* Whether this color is inherited by child themes created via `extend()`.
|
|
187
335
|
* Default: true. Set to false to make this color local to the current theme.
|
|
@@ -215,12 +363,26 @@ interface MixColorDef {
|
|
|
215
363
|
*/
|
|
216
364
|
space?: 'okhsl' | 'srgb';
|
|
217
365
|
/**
|
|
218
|
-
* Minimum
|
|
366
|
+
* Minimum contrast between the base and the resulting color.
|
|
219
367
|
* In 'opaque' mode, adjusts the mix ratio to meet contrast.
|
|
220
368
|
* In 'transparent' mode, adjusts opacity to meet contrast against the composite.
|
|
221
|
-
*
|
|
369
|
+
* A bare number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the
|
|
370
|
+
* metric. Supports [normal, highContrast] pair.
|
|
222
371
|
*/
|
|
223
|
-
contrast?: HCPair<
|
|
372
|
+
contrast?: HCPair<ContrastSpec>;
|
|
373
|
+
/**
|
|
374
|
+
* Per-color override for the hue-independent "safe" chroma limit used in
|
|
375
|
+
* OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
|
|
376
|
+
* Falls through to the global / per-theme `pastel` config when omitted.
|
|
377
|
+
* @see GlazeConfig.pastel
|
|
378
|
+
*/
|
|
379
|
+
pastel?: boolean;
|
|
380
|
+
/**
|
|
381
|
+
* Semantic role of the mixed result against `base`. Same semantics as
|
|
382
|
+
* `RegularColorDef.role` (fixes APCA polarity). Resolution and defaults
|
|
383
|
+
* are identical.
|
|
384
|
+
*/
|
|
385
|
+
role?: RoleInput;
|
|
224
386
|
/**
|
|
225
387
|
* Whether this color is inherited by child themes created via `extend()`.
|
|
226
388
|
* Default: true. Set to false to make this color local to the current theme.
|
|
@@ -229,16 +391,28 @@ interface MixColorDef {
|
|
|
229
391
|
}
|
|
230
392
|
type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
|
|
231
393
|
type ColorMap = Record<string, ColorDef>;
|
|
232
|
-
/**
|
|
394
|
+
/**
|
|
395
|
+
* Resolved color for a single scheme variant.
|
|
396
|
+
*
|
|
397
|
+
* Stored in OKHST: `h` / `s` are OKHSL hue/saturation, `t` is the canonical
|
|
398
|
+
* contrast-uniform tone (0–1, reference eps). Convert to OKHSL lightness via
|
|
399
|
+
* `variantToOkhsl` at the rendering / luminance edges.
|
|
400
|
+
*/
|
|
233
401
|
interface ResolvedColorVariant {
|
|
234
402
|
/** OKHSL hue (0–360). */
|
|
235
403
|
h: number;
|
|
236
404
|
/** OKHSL saturation (0–1). */
|
|
237
405
|
s: number;
|
|
238
|
-
/**
|
|
239
|
-
|
|
406
|
+
/** Canonical tone (0–1, reference eps). */
|
|
407
|
+
t: number;
|
|
240
408
|
/** Opacity (0–1). Default: 1. */
|
|
241
409
|
alpha: number;
|
|
410
|
+
/**
|
|
411
|
+
* Effective `pastel` flag used while resolving this variant (author def or
|
|
412
|
+
* config fallback). Carried on the variant so output formatting matches the
|
|
413
|
+
* gamut mapping applied during resolution.
|
|
414
|
+
*/
|
|
415
|
+
pastel?: boolean;
|
|
242
416
|
}
|
|
243
417
|
/** Fully resolved color across all scheme variants. */
|
|
244
418
|
interface ResolvedColor {
|
|
@@ -250,20 +424,27 @@ interface ResolvedColor {
|
|
|
250
424
|
/** Adaptation mode. Present only for regular colors, omitted for shadows. */
|
|
251
425
|
mode?: AdaptationMode;
|
|
252
426
|
}
|
|
427
|
+
/**
|
|
428
|
+
* A scheme tone window.
|
|
429
|
+
* - `[lo, hi]`: OKHSL-lightness endpoints (0–100) the authored tone is
|
|
430
|
+
* remapped into, using the reference eps `0.05`. The common form.
|
|
431
|
+
* - `{ lo, hi, eps }`: same, with an explicit render curvature `eps`
|
|
432
|
+
* (advanced — most palettes never need this).
|
|
433
|
+
* - `false`: disable clamping (full range `[0, 100]` at the reference eps).
|
|
434
|
+
* This removes the *boundaries*, not the tone curve.
|
|
435
|
+
*/
|
|
436
|
+
type ToneWindow = false | [number, number] | {
|
|
437
|
+
lo: number;
|
|
438
|
+
hi: number;
|
|
439
|
+
eps: number;
|
|
440
|
+
};
|
|
253
441
|
interface GlazeConfig {
|
|
254
|
-
/** Light scheme
|
|
255
|
-
|
|
256
|
-
/** Dark scheme
|
|
257
|
-
|
|
442
|
+
/** Light scheme tone window — `[lo, hi]` (default `[10, 100]`), `{ lo, hi, eps }` for advanced eps tuning, or `false` to disable clamping. */
|
|
443
|
+
lightTone?: ToneWindow;
|
|
444
|
+
/** Dark scheme tone window — `[lo, hi]` (default `[15, 95]`), `{ lo, hi, eps }`, or `false` to disable clamping. */
|
|
445
|
+
darkTone?: ToneWindow;
|
|
258
446
|
/** Saturation reduction factor for dark scheme (0–1). Default: 0.1. */
|
|
259
447
|
darkDesaturation?: number;
|
|
260
|
-
/**
|
|
261
|
-
* Möbius beta for dark auto-inversion (0–1).
|
|
262
|
-
* Lower values expand subtle near-white distinctions in dark mode.
|
|
263
|
-
* Set to 1 for linear (legacy) behavior. Default: 0.5.
|
|
264
|
-
* Accepts [normal, highContrast] pair for separate HC tuning.
|
|
265
|
-
*/
|
|
266
|
-
darkCurve?: HCPair<number>;
|
|
267
448
|
/** State alias names for token export. */
|
|
268
449
|
states?: {
|
|
269
450
|
dark?: string;
|
|
@@ -273,31 +454,105 @@ interface GlazeConfig {
|
|
|
273
454
|
modes?: GlazeOutputModes;
|
|
274
455
|
/** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
|
|
275
456
|
shadowTuning?: ShadowTuning;
|
|
457
|
+
/**
|
|
458
|
+
* Automatically flip tone direction when contrast can't be met.
|
|
459
|
+
*
|
|
460
|
+
* When enabled (default `true`), the solver searches the requested
|
|
461
|
+
* tone direction first. If that direction can't reach the target,
|
|
462
|
+
* it tries the opposite direction and uses it when it passes. If neither
|
|
463
|
+
* side passes, the tone is pinned to the requested-direction
|
|
464
|
+
* extreme and a warning is emitted.
|
|
465
|
+
*
|
|
466
|
+
* Set to `false` for strict "no flip" behavior. The opposite
|
|
467
|
+
* direction is never considered: if the requested direction can't
|
|
468
|
+
* meet the target, the tone is pinned to its extreme (never
|
|
469
|
+
* falls back to the originally requested tone).
|
|
470
|
+
*/
|
|
471
|
+
autoFlip?: boolean;
|
|
472
|
+
/**
|
|
473
|
+
* If true, uses a hue-independent "safe" chroma limit across all colors
|
|
474
|
+
* so that scaling saturation never exceeds the sRGB boundary at any hue
|
|
475
|
+
* for the given lightness.
|
|
476
|
+
* @default false
|
|
477
|
+
*/
|
|
478
|
+
pastel?: boolean;
|
|
479
|
+
/**
|
|
480
|
+
* If true (default), infer a color's `role` from its name when no explicit
|
|
481
|
+
* `role` is set. Set to `false` to opt out of name-based inference (the
|
|
482
|
+
* base-opposite and default-foreground fallbacks still apply).
|
|
483
|
+
* @default true
|
|
484
|
+
*/
|
|
485
|
+
inferRole?: boolean;
|
|
276
486
|
}
|
|
277
487
|
interface GlazeConfigResolved {
|
|
278
|
-
|
|
279
|
-
|
|
488
|
+
lightTone: ToneWindow;
|
|
489
|
+
darkTone: ToneWindow;
|
|
280
490
|
darkDesaturation: number;
|
|
281
|
-
darkCurve: HCPair<number>;
|
|
282
491
|
states: {
|
|
283
492
|
dark: string;
|
|
284
493
|
highContrast: string;
|
|
285
494
|
};
|
|
286
495
|
modes: Required<GlazeOutputModes>;
|
|
287
496
|
shadowTuning?: ShadowTuning;
|
|
497
|
+
autoFlip: boolean;
|
|
498
|
+
pastel: boolean;
|
|
499
|
+
inferRole: boolean;
|
|
500
|
+
}
|
|
501
|
+
/**
|
|
502
|
+
* Per-instance config override for `glaze.color()` and `glaze()` themes.
|
|
503
|
+
* Fields that are set take priority over the live global config. Fields
|
|
504
|
+
* that are omitted fall through to the live global at resolve time.
|
|
505
|
+
*
|
|
506
|
+
* `false` for a tone window disables clamping (full range at reference eps).
|
|
507
|
+
*/
|
|
508
|
+
interface GlazeConfigOverride {
|
|
509
|
+
/** Light scheme tone window, or `false` to disable clamping. */
|
|
510
|
+
lightTone?: ToneWindow;
|
|
511
|
+
/** Dark scheme tone window, or `false` to disable clamping. */
|
|
512
|
+
darkTone?: ToneWindow;
|
|
513
|
+
/** Saturation reduction factor for dark scheme (0–1). */
|
|
514
|
+
darkDesaturation?: number;
|
|
515
|
+
/** Whether to auto-flip tone when contrast can't be met. */
|
|
516
|
+
autoFlip?: boolean;
|
|
517
|
+
/**
|
|
518
|
+
* If true, uses a hue-independent "safe" chroma limit across all colors
|
|
519
|
+
* so that scaling saturation never exceeds the sRGB boundary at any hue
|
|
520
|
+
* for the given lightness.
|
|
521
|
+
*/
|
|
522
|
+
pastel?: boolean;
|
|
523
|
+
/**
|
|
524
|
+
* If true, infer a color's `role` from its name when no explicit `role` is
|
|
525
|
+
* set. Falls through to the live global at resolve time when omitted.
|
|
526
|
+
*/
|
|
527
|
+
inferRole?: boolean;
|
|
528
|
+
/**
|
|
529
|
+
* Shadow tuning defaults. Only meaningful for themes; harmless on
|
|
530
|
+
* standalone color tokens.
|
|
531
|
+
*/
|
|
532
|
+
shadowTuning?: ShadowTuning;
|
|
288
533
|
}
|
|
289
534
|
/** Serialized theme configuration (no resolved values). */
|
|
290
535
|
interface GlazeThemeExport {
|
|
291
536
|
hue: number;
|
|
292
537
|
saturation: number;
|
|
293
538
|
colors: ColorMap;
|
|
539
|
+
/** Per-theme config override, if any. */
|
|
540
|
+
config?: GlazeConfigOverride;
|
|
294
541
|
}
|
|
295
542
|
/** Input for `glaze.shadow()` standalone factory. */
|
|
296
543
|
interface GlazeShadowInput {
|
|
297
|
-
/**
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
544
|
+
/**
|
|
545
|
+
* Background color — accepts any `GlazeColorValue` form: hex
|
|
546
|
+
* (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()`
|
|
547
|
+
* / `oklch()` strings, or literal objects (`{ r, g, b }`, `{ h, s, l }`,
|
|
548
|
+
* `{ l, c, h }`). Alpha components are dropped with a warning.
|
|
549
|
+
*/
|
|
550
|
+
bg: GlazeColorValue;
|
|
551
|
+
/**
|
|
552
|
+
* Foreground color for tinting + intensity modulation. Accepts the
|
|
553
|
+
* same forms as `bg`.
|
|
554
|
+
*/
|
|
555
|
+
fg?: GlazeColorValue;
|
|
301
556
|
/** Intensity 0-100. */
|
|
302
557
|
intensity: number;
|
|
303
558
|
tuning?: ShadowTuning;
|
|
@@ -306,22 +561,68 @@ interface GlazeShadowInput {
|
|
|
306
561
|
interface GlazeColorInput {
|
|
307
562
|
hue: number;
|
|
308
563
|
saturation: number;
|
|
309
|
-
|
|
564
|
+
tone: HCPair<number | ExtremeValue>;
|
|
310
565
|
saturationFactor?: number;
|
|
311
566
|
mode?: AdaptationMode;
|
|
567
|
+
/** Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. */
|
|
568
|
+
flip?: boolean;
|
|
569
|
+
/**
|
|
570
|
+
* Fixed opacity (0–1). Output includes alpha in the CSS value.
|
|
571
|
+
* Combining with `contrast` is not recommended (perceived tone
|
|
572
|
+
* becomes unpredictable) — a `console.warn` is emitted in that case.
|
|
573
|
+
*/
|
|
574
|
+
opacity?: number;
|
|
575
|
+
/**
|
|
576
|
+
* Optional dependency on another color. Same semantics as
|
|
577
|
+
* `GlazeColorOverrides.base` — `contrast` and relative `tone`
|
|
578
|
+
* anchor to the base per scheme.
|
|
579
|
+
*/
|
|
580
|
+
base?: GlazeColorToken | GlazeColorValue;
|
|
581
|
+
/**
|
|
582
|
+
* Contrast floor against `base`. Requires `base` to be set. A bare
|
|
583
|
+
* number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the metric.
|
|
584
|
+
*/
|
|
585
|
+
contrast?: HCPair<ContrastSpec>;
|
|
586
|
+
/**
|
|
587
|
+
* Optional human-readable name for the token. Used in error and
|
|
588
|
+
* warning messages (otherwise an internal name like `"value"` is
|
|
589
|
+
* used). Does not affect output keys.
|
|
590
|
+
*/
|
|
591
|
+
name?: string;
|
|
592
|
+
/**
|
|
593
|
+
* Per-color override for the hue-independent "safe" chroma limit used in
|
|
594
|
+
* OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
|
|
595
|
+
* Falls through to the global / per-theme `pastel` config when omitted.
|
|
596
|
+
* @see GlazeConfig.pastel
|
|
597
|
+
*/
|
|
598
|
+
pastel?: boolean;
|
|
599
|
+
/**
|
|
600
|
+
* Semantic role against `base` / the literal seed: how this token is used.
|
|
601
|
+
* Fixes APCA contrast polarity. Same resolution chain as
|
|
602
|
+
* `RegularColorDef.role` (explicit → name inference → opposite of base →
|
|
603
|
+
* `'text'`). For standalone tokens the name is internal, so set `role`
|
|
604
|
+
* explicitly or rely on the base-opposite / foreground default.
|
|
605
|
+
*/
|
|
606
|
+
role?: RoleInput;
|
|
312
607
|
}
|
|
313
608
|
/**
|
|
314
609
|
* Any single-color input form accepted by the value-shorthand
|
|
315
610
|
* overload of `glaze.color()`.
|
|
316
611
|
*
|
|
317
|
-
* Strings cover hex (`#rgb` / `#rrggbb`
|
|
318
|
-
* functions Glaze itself emits:
|
|
319
|
-
*
|
|
320
|
-
*
|
|
321
|
-
*
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
612
|
+
* Strings cover hex (`#rgb` / `#rrggbb` / `#rrggbbaa`, alpha dropped
|
|
613
|
+
* with a warning) and the four CSS color functions Glaze itself emits:
|
|
614
|
+
* `rgb()`, `hsl()`, `okhsl()`, `oklch()` (alpha components also dropped
|
|
615
|
+
* with a warning).
|
|
616
|
+
*
|
|
617
|
+
* Literal object forms:
|
|
618
|
+
* - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1). Passing 0–100 for `s`/`l`
|
|
619
|
+
* throws with a hint to use the structured form.
|
|
620
|
+
* - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1.
|
|
621
|
+
* - `{ r, g, b }` — sRGB 0–255.
|
|
622
|
+
* - `{ l, c, h }` — OKLCh (L/C: 0–1, H: degrees), same as `oklch()` strings.
|
|
623
|
+
*/
|
|
624
|
+
type GlazeColorValue = string | OkhslColor | OkhstColor | RgbColor | OklchColor;
|
|
625
|
+
/** Color overrides for the `from` and value-shorthand inputs. */
|
|
325
626
|
interface GlazeColorOverrides {
|
|
326
627
|
/**
|
|
327
628
|
* Override hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
|
|
@@ -332,26 +633,103 @@ interface GlazeColorOverrides {
|
|
|
332
633
|
/** Override seed saturation (0–100). Default: extracted from value. */
|
|
333
634
|
saturation?: number;
|
|
334
635
|
/**
|
|
335
|
-
* Override
|
|
336
|
-
* relative to the
|
|
337
|
-
*
|
|
636
|
+
* Override tone. Number is absolute (0–100, contrast-uniform); `'+N'`/`'-N'`
|
|
637
|
+
* is relative to the literal seed (the value passed to `glaze.color()`);
|
|
638
|
+
* `'max'` / `'min'` force to the scheme's tone extreme.
|
|
639
|
+
* Supports HCPair for high-contrast.
|
|
338
640
|
*/
|
|
339
|
-
|
|
641
|
+
tone?: HCPair<ToneValue>;
|
|
340
642
|
/** Saturation multiplier on the seed (0–1). Default: 1. */
|
|
341
643
|
saturationFactor?: number;
|
|
342
|
-
/**
|
|
644
|
+
/**
|
|
645
|
+
* Adaptation mode. Defaults to `'auto'` for every input form, so
|
|
646
|
+
* colors automatically adapt between light and dark like an ordinary
|
|
647
|
+
* theme color. All value-shorthand inputs (strings and literal objects)
|
|
648
|
+
* preserve light tone (`lightTone: false`) and snapshot
|
|
649
|
+
* `globalConfig.darkTone` on the dark side. Only the structured
|
|
650
|
+
* `{ hue, saturation, tone }` form also snapshots
|
|
651
|
+
* `globalConfig.lightTone`.
|
|
652
|
+
*
|
|
653
|
+
* Pass `'fixed'` explicitly to opt back into the linear, non-
|
|
654
|
+
* inverting mapping; pass `'static'` to pin the same tone
|
|
655
|
+
* across every variant.
|
|
656
|
+
*/
|
|
343
657
|
mode?: AdaptationMode;
|
|
344
658
|
/**
|
|
345
|
-
*
|
|
346
|
-
* `
|
|
347
|
-
*
|
|
659
|
+
* Flip out-of-bounds results (relative `tone` overshoot / unmet
|
|
660
|
+
* `contrast`) to the opposite side instead of clamping. Defaults to
|
|
661
|
+
* the global `autoFlip`.
|
|
662
|
+
*/
|
|
663
|
+
flip?: boolean;
|
|
664
|
+
/**
|
|
665
|
+
* Contrast floor. By default solved against the literal seed
|
|
666
|
+
* (the value itself); when `base` is set, solved against the base's
|
|
667
|
+
* resolved variant per scheme. Same shape as `RegularColorDef.contrast`
|
|
668
|
+
* (bare number/preset = WCAG; `{ wcag }` / `{ apca }` to pick the metric).
|
|
669
|
+
*/
|
|
670
|
+
contrast?: HCPair<ContrastSpec>;
|
|
671
|
+
/**
|
|
672
|
+
* Optional dependency on another color. Accepts either a
|
|
673
|
+
* `GlazeColorToken` (returned by another `glaze.color()`) or a raw
|
|
674
|
+
* `GlazeColorValue` (hex / CSS strings / `{ r, g, b }` / `{ h, s, l }` / …),
|
|
675
|
+
* which is automatically wrapped in `glaze.color(value)`.
|
|
676
|
+
*
|
|
677
|
+
* When set:
|
|
678
|
+
* - `contrast` is solved against the base's resolved variant
|
|
679
|
+
* per-scheme (light / dark / lightContrast / darkContrast).
|
|
680
|
+
* - Relative `tone: '+N'` / `'-N'` is anchored to the base's
|
|
681
|
+
* tone per-scheme (matches theme behavior for dependent colors).
|
|
682
|
+
* - Relative `hue: '+N'` / `'-N'` still anchors to the seed (the
|
|
683
|
+
* value passed to `glaze.color()`), not the base.
|
|
684
|
+
* - When the base was created via the structured form (with explicit
|
|
685
|
+
* `hue`/`saturation`/`tone`), it is resolved at full range
|
|
686
|
+
* (`lightTone: false`) for the linking math — ensuring the
|
|
687
|
+
* contrast/tone anchor matches the input tone, not the
|
|
688
|
+
* windowed output. The base's own `.resolve()` output is unaffected.
|
|
689
|
+
*
|
|
690
|
+
* The base token's `.resolve()` is called lazily on first resolve and
|
|
691
|
+
* its result is captured by reference; later mutations to the base's
|
|
692
|
+
* defining call don't apply (matches existing token snapshot semantics).
|
|
348
693
|
*/
|
|
349
|
-
base?: GlazeColorValue;
|
|
694
|
+
base?: GlazeColorToken | GlazeColorValue;
|
|
350
695
|
/**
|
|
351
|
-
*
|
|
352
|
-
*
|
|
696
|
+
* Fixed opacity (0–1). Output includes alpha in the CSS value.
|
|
697
|
+
* Combining with `contrast` is not recommended (perceived tone
|
|
698
|
+
* becomes unpredictable) — a `console.warn` is emitted in that case.
|
|
353
699
|
*/
|
|
354
|
-
|
|
700
|
+
opacity?: number;
|
|
701
|
+
/**
|
|
702
|
+
* Optional human-readable name for the token. Used in error and
|
|
703
|
+
* warning messages (otherwise an internal name like `"value"` is
|
|
704
|
+
* used). Does not affect output keys.
|
|
705
|
+
*/
|
|
706
|
+
name?: string;
|
|
707
|
+
/**
|
|
708
|
+
* Per-color override for the hue-independent "safe" chroma limit used in
|
|
709
|
+
* OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
|
|
710
|
+
* Falls through to the global / per-theme `pastel` config when omitted.
|
|
711
|
+
* @see GlazeConfig.pastel
|
|
712
|
+
*/
|
|
713
|
+
pastel?: boolean;
|
|
714
|
+
/**
|
|
715
|
+
* Semantic role against `base` / the literal seed: how this token is used.
|
|
716
|
+
* Fixes APCA contrast polarity. Same resolution chain as
|
|
717
|
+
* `RegularColorDef.role`.
|
|
718
|
+
*/
|
|
719
|
+
role?: RoleInput;
|
|
720
|
+
}
|
|
721
|
+
/**
|
|
722
|
+
* Object input for `glaze.color()` that carries a raw color value plus
|
|
723
|
+
* optional color overrides in the same object.
|
|
724
|
+
*
|
|
725
|
+
* ```ts
|
|
726
|
+
* glaze.color({ from: '#1a1a2e', base: bg, contrast: 'AA' })
|
|
727
|
+
* glaze.color({ from: { r: 38, g: 252, b: 178 }, tone: '+10' })
|
|
728
|
+
* ```
|
|
729
|
+
*/
|
|
730
|
+
interface GlazeFromInput extends GlazeColorOverrides {
|
|
731
|
+
/** The source color value. Accepts the same forms as a bare `GlazeColorValue`. */
|
|
732
|
+
from: GlazeColorValue;
|
|
355
733
|
}
|
|
356
734
|
/** Options for `GlazeColorToken.css()`. */
|
|
357
735
|
interface GlazeColorCssOptions {
|
|
@@ -385,12 +763,84 @@ interface GlazeColorToken {
|
|
|
385
763
|
json(options?: GlazeJsonOptions): Record<string, string>;
|
|
386
764
|
/** Export as CSS custom property declarations grouped by scheme variant. */
|
|
387
765
|
css(options: GlazeColorCssOptions): GlazeCssResult;
|
|
766
|
+
/**
|
|
767
|
+
* Serialize the token as a JSON-safe object. Captures the original
|
|
768
|
+
* input value, overrides, and config so it can be rehydrated via
|
|
769
|
+
* `glaze.colorFrom(...)`. `base` is recursively serialized.
|
|
770
|
+
*/
|
|
771
|
+
export(): GlazeColorTokenExport;
|
|
772
|
+
}
|
|
773
|
+
/**
|
|
774
|
+
* JSON-safe serialization of a `glaze.color()` token. Pass to
|
|
775
|
+
* `glaze.colorFrom(...)` to rehydrate.
|
|
776
|
+
*/
|
|
777
|
+
interface GlazeColorTokenExport {
|
|
778
|
+
/**
|
|
779
|
+
* Discriminator for the source overload that created the token.
|
|
780
|
+
* - `'value'`: created via `glaze.color(value)` or `glaze.color({ from, ...overrides })`.
|
|
781
|
+
* - `'structured'`: created via `glaze.color({ hue, saturation, ... })`.
|
|
782
|
+
*/
|
|
783
|
+
form: 'value' | 'structured';
|
|
784
|
+
/** Original input. For `form: 'value'` this is the raw `GlazeColorValue`; for `form: 'structured'` this is the structured input. */
|
|
785
|
+
input: GlazeColorValue | GlazeColorInputExport;
|
|
786
|
+
/**
|
|
787
|
+
* Overrides recorded at creation time. `base` is recursively
|
|
788
|
+
* serialized. Only present for `form: 'value'`.
|
|
789
|
+
*/
|
|
790
|
+
overrides?: GlazeColorOverridesExport;
|
|
791
|
+
/**
|
|
792
|
+
* Effective config snapshot at creation time — captures the merged
|
|
793
|
+
* result of the global config + any per-call override at the moment
|
|
794
|
+
* the token was created. Only fields that differ from their
|
|
795
|
+
* post-merge defaults are present. Used by `glaze.colorFrom()` to
|
|
796
|
+
* reproduce deterministic behavior across `configure()` calls.
|
|
797
|
+
*/
|
|
798
|
+
config?: GlazeConfigOverride;
|
|
799
|
+
}
|
|
800
|
+
/**
|
|
801
|
+
* Serializable shape of a structured `glaze.color({...})` input.
|
|
802
|
+
* Differs from `GlazeColorInput` only in that `base` is replaced by an
|
|
803
|
+
* `export` instead of a token reference.
|
|
804
|
+
*/
|
|
805
|
+
interface GlazeColorInputExport {
|
|
806
|
+
hue: number;
|
|
807
|
+
saturation: number;
|
|
808
|
+
tone: HCPair<number | ExtremeValue>;
|
|
809
|
+
saturationFactor?: number;
|
|
810
|
+
mode?: AdaptationMode;
|
|
811
|
+
flip?: boolean;
|
|
812
|
+
opacity?: number;
|
|
813
|
+
base?: GlazeColorTokenExport | GlazeColorValue;
|
|
814
|
+
contrast?: HCPair<ContrastSpec>;
|
|
815
|
+
name?: string;
|
|
816
|
+
pastel?: boolean;
|
|
817
|
+
role?: RoleInput;
|
|
818
|
+
}
|
|
819
|
+
/**
|
|
820
|
+
* Serializable shape of `GlazeColorOverrides`. `base` is replaced by
|
|
821
|
+
* its export (or left as a `GlazeColorValue` if it was originally a value).
|
|
822
|
+
*/
|
|
823
|
+
interface GlazeColorOverridesExport {
|
|
824
|
+
hue?: number | RelativeValue;
|
|
825
|
+
saturation?: number;
|
|
826
|
+
tone?: HCPair<ToneValue>;
|
|
827
|
+
saturationFactor?: number;
|
|
828
|
+
mode?: AdaptationMode;
|
|
829
|
+
flip?: boolean;
|
|
830
|
+
contrast?: HCPair<ContrastSpec>;
|
|
831
|
+
base?: GlazeColorTokenExport | GlazeColorValue;
|
|
832
|
+
opacity?: number;
|
|
833
|
+
name?: string;
|
|
834
|
+
pastel?: boolean;
|
|
835
|
+
role?: RoleInput;
|
|
388
836
|
}
|
|
389
837
|
interface GlazeTheme {
|
|
390
838
|
/** The hue seed (0–360). */
|
|
391
839
|
readonly hue: number;
|
|
392
840
|
/** The saturation seed (0–100). */
|
|
393
841
|
readonly saturation: number;
|
|
842
|
+
/** The effective config for this theme. */
|
|
843
|
+
getConfig(): GlazeConfigResolved;
|
|
394
844
|
/** Add/replace colors (additive merge with existing definitions). */
|
|
395
845
|
colors(defs: ColorMap): void;
|
|
396
846
|
/** Get a color definition by name. */
|
|
@@ -436,6 +886,8 @@ interface GlazeExtendOptions {
|
|
|
436
886
|
hue?: number;
|
|
437
887
|
saturation?: number;
|
|
438
888
|
colors?: ColorMap;
|
|
889
|
+
/** Config override for the child theme. Merged with the parent's override. */
|
|
890
|
+
config?: GlazeConfigOverride;
|
|
439
891
|
}
|
|
440
892
|
interface GlazeTokenOptions {
|
|
441
893
|
/** Prefix mode. `true` uses "<themeName>-", or provide a custom map. */
|
|
@@ -534,58 +986,155 @@ type PaletteInput = Record<string, GlazeTheme>;
|
|
|
534
986
|
/**
|
|
535
987
|
* Create a single-hue glaze theme.
|
|
536
988
|
*
|
|
989
|
+
* An optional `config` override can be supplied to customize the resolve
|
|
990
|
+
* behavior for this theme (tone windows, etc.). The
|
|
991
|
+
* override is **merged over the live global config at resolve time** —
|
|
992
|
+
* the theme still reacts to later `configure()` calls for fields it
|
|
993
|
+
* didn't override.
|
|
994
|
+
*
|
|
537
995
|
* @example
|
|
538
996
|
* ```ts
|
|
539
|
-
* const primary = glaze({ hue: 280, saturation: 80 });
|
|
540
|
-
* // or shorthand:
|
|
541
997
|
* const primary = glaze(280, 80);
|
|
998
|
+
* // or shorthand:
|
|
999
|
+
* const primary = glaze({ hue: 280, saturation: 80 });
|
|
1000
|
+
* // with config override:
|
|
1001
|
+
* const raw = glaze(280, 80, { lightTone: false });
|
|
542
1002
|
* ```
|
|
543
1003
|
*/
|
|
544
1004
|
declare function glaze(hueOrOptions: number | {
|
|
545
1005
|
hue: number;
|
|
546
1006
|
saturation: number;
|
|
547
|
-
}, saturation?: number): GlazeTheme;
|
|
1007
|
+
}, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
|
|
548
1008
|
declare namespace glaze {
|
|
549
1009
|
var configure: (config: GlazeConfig) => void;
|
|
550
|
-
var palette: (themes: PaletteInput, options?: GlazePaletteOptions) =>
|
|
551
|
-
tokens(options?: GlazeJsonOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
|
|
552
|
-
tasty(options?: GlazeTokenOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
|
|
553
|
-
json(options?: GlazeJsonOptions & {
|
|
554
|
-
prefix?: boolean | Record<string, string>;
|
|
555
|
-
}): Record<string, Record<string, Record<string, string>>>;
|
|
556
|
-
css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
|
|
557
|
-
};
|
|
1010
|
+
var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
|
|
558
1011
|
var from: (data: GlazeThemeExport) => GlazeTheme;
|
|
559
|
-
var color:
|
|
560
|
-
(input: GlazeColorInput): GlazeColorToken;
|
|
561
|
-
(value: GlazeColorValue, options?: GlazeColorOverrides): GlazeColorToken;
|
|
562
|
-
};
|
|
1012
|
+
var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
|
|
563
1013
|
var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
|
|
564
|
-
var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => string;
|
|
1014
|
+
var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
|
|
565
1015
|
var fromHex: (hex: string) => GlazeTheme;
|
|
566
1016
|
var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
|
|
1017
|
+
var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
|
|
567
1018
|
var getConfig: () => GlazeConfigResolved;
|
|
568
1019
|
var resetConfig: () => void;
|
|
569
1020
|
}
|
|
570
1021
|
//#endregion
|
|
1022
|
+
//#region src/roles.d.ts
|
|
1023
|
+
/**
|
|
1024
|
+
* Normalize a `RoleInput` (canonical value or alias) into a canonical `Role`.
|
|
1025
|
+
* Returns `undefined` for unrecognized strings so callers can fall through to
|
|
1026
|
+
* the next step of the resolution chain.
|
|
1027
|
+
*/
|
|
1028
|
+
declare function normalizeRole(input: RoleInput | undefined): Role | undefined;
|
|
1029
|
+
/**
|
|
1030
|
+
* Infer a `Role` from a color name by matching its tokens against the role
|
|
1031
|
+
* keyword sets. When multiple tokens match, the **last** recognized token
|
|
1032
|
+
* wins (so `button-text` → `text`, `input-bg` → `surface`, `card-border` →
|
|
1033
|
+
* `border`). Returns `undefined` when no token matches.
|
|
1034
|
+
*/
|
|
1035
|
+
declare function inferRoleFromName(name: string): Role | undefined;
|
|
1036
|
+
/** APCA argument order: which side the resolved color plays. */
|
|
1037
|
+
type Polarity = 'fg' | 'bg';
|
|
1038
|
+
/**
|
|
1039
|
+
* Map a role to its APCA polarity. `text` and `border` are foreground spots
|
|
1040
|
+
* against their base (the candidate is the text argument); `surface` is the
|
|
1041
|
+
* background (the base is the text argument).
|
|
1042
|
+
*/
|
|
1043
|
+
declare function roleToPolarity(role: Role): Polarity;
|
|
1044
|
+
/**
|
|
1045
|
+
* The opposite role of `role`, used when a color with no explicit role and no
|
|
1046
|
+
* inferable name depends on a base: the dependent color plays the opposite
|
|
1047
|
+
* role of its base. `surface` ↔ `text`; `border` is treated as a foreground
|
|
1048
|
+
* spot, so its opposite is `surface`.
|
|
1049
|
+
*/
|
|
1050
|
+
declare function oppositeRole(role: Role): Role;
|
|
1051
|
+
//#endregion
|
|
1052
|
+
//#region src/okhst.d.ts
|
|
1053
|
+
/**
|
|
1054
|
+
* Reference eps for the OKHST color space. WCAG 2 contrast is
|
|
1055
|
+
* `(Y_hi + 0.05) / (Y_lo + 0.05)`, so an eps of `0.05` makes equal tone
|
|
1056
|
+
* steps yield equal WCAG contrast. This is the canonical eps used by
|
|
1057
|
+
* `okhst()` input, `{ h, s, t }` input, stored `ResolvedColorVariant.t`,
|
|
1058
|
+
* relative `tone` offsets, and the contrast solver.
|
|
1059
|
+
*/
|
|
1060
|
+
declare const REF_EPS = 0.05;
|
|
1061
|
+
/**
|
|
1062
|
+
* Map a luminance `Y` (0–1) to tone (0–100) at the given eps.
|
|
1063
|
+
* `toneFromY(0) === 0` and `toneFromY(1) === 100` for any eps.
|
|
1064
|
+
*/
|
|
1065
|
+
declare function toneFromY(y: number, eps?: number): number;
|
|
1066
|
+
/** Map a tone (0–100) back to luminance (0–1). Inverse of {@link toneFromY}. */
|
|
1067
|
+
declare function yFromTone(t: number, eps?: number): number;
|
|
1068
|
+
/** OKHSL lightness (0–1) -> tone (0–100). */
|
|
1069
|
+
declare function toTone(l: number, eps?: number): number;
|
|
1070
|
+
/** Tone (0–100) -> OKHSL lightness (0–1). Inverse of {@link toTone}. */
|
|
1071
|
+
declare function fromTone(t: number, eps?: number): number;
|
|
1072
|
+
/** Convert OKHST `{ h, s, t }` (t in 0–1) to OKHSL `{ h, s, l }`. */
|
|
1073
|
+
declare function okhstToOkhsl(c: {
|
|
1074
|
+
h: number;
|
|
1075
|
+
s: number;
|
|
1076
|
+
t: number;
|
|
1077
|
+
}): {
|
|
1078
|
+
h: number;
|
|
1079
|
+
s: number;
|
|
1080
|
+
l: number;
|
|
1081
|
+
};
|
|
1082
|
+
/** Convert OKHSL `{ h, s, l }` to OKHST `{ h, s, t }` (t in 0–1). */
|
|
1083
|
+
declare function okhslToOkhst(c: {
|
|
1084
|
+
h: number;
|
|
1085
|
+
s: number;
|
|
1086
|
+
l: number;
|
|
1087
|
+
}): {
|
|
1088
|
+
h: number;
|
|
1089
|
+
s: number;
|
|
1090
|
+
t: number;
|
|
1091
|
+
};
|
|
1092
|
+
/**
|
|
1093
|
+
* Edge adapter: a resolved variant stores canonical tone `t` (0–1). Convert
|
|
1094
|
+
* it to the OKHSL `{ h, s, l }` the formatters and luminance pipeline expect.
|
|
1095
|
+
*/
|
|
1096
|
+
declare function variantToOkhsl(v: {
|
|
1097
|
+
h: number;
|
|
1098
|
+
s: number;
|
|
1099
|
+
t: number;
|
|
1100
|
+
}): {
|
|
1101
|
+
h: number;
|
|
1102
|
+
s: number;
|
|
1103
|
+
l: number;
|
|
1104
|
+
};
|
|
1105
|
+
//#endregion
|
|
571
1106
|
//#region src/okhsl-color-math.d.ts
|
|
572
1107
|
/**
|
|
573
1108
|
* OKHSL color math primitives for the glaze theme generator.
|
|
574
1109
|
*
|
|
575
|
-
* Provides bidirectional OKHSL ↔ sRGB conversion,
|
|
576
|
-
*
|
|
577
|
-
* (okhsl, rgb, hsl, oklch).
|
|
1110
|
+
* Provides bidirectional OKHSL ↔ sRGB conversion, luminance computation
|
|
1111
|
+
* for both contrast metrics (WCAG 2 relative luminance and APCA screen
|
|
1112
|
+
* luminance `Ys`), and multi-format output (okhsl, rgb, hsl, oklch).
|
|
578
1113
|
*/
|
|
579
1114
|
type Vec3 = [number, number, number];
|
|
1115
|
+
/**
|
|
1116
|
+
* OKHSL toe function: maps OKLab lightness L to perceptual lightness l.
|
|
1117
|
+
* Exported for the OKHST tone transfers in `okhst.ts`.
|
|
1118
|
+
*/
|
|
1119
|
+
/**
|
|
1120
|
+
* OKHSL lightness of the gamut cusp for a hue — the lightness where the
|
|
1121
|
+
* realizable chroma peaks. Reuses the same `find_cusp` OKHSL already runs for
|
|
1122
|
+
* its `s` normalization (no new color math); the OKLab cusp lightness is run
|
|
1123
|
+
* through the OKHSL `toe` and clamped to `[0.001, 0.999]` so divisions that
|
|
1124
|
+
* key off it stay safe. Cached per (rounded) hue.
|
|
1125
|
+
*
|
|
1126
|
+
* @param h Hue, 0–360.
|
|
1127
|
+
*/
|
|
1128
|
+
declare function cuspLightness(h: number): number;
|
|
580
1129
|
/**
|
|
581
1130
|
* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
|
|
582
1131
|
*/
|
|
583
|
-
declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
|
|
1132
|
+
declare function okhslToOklab(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
|
|
584
1133
|
/**
|
|
585
1134
|
* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
|
|
586
1135
|
* Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
|
|
587
1136
|
*/
|
|
588
|
-
declare function okhslToLinearSrgb(h: number, s: number, l: number): [number, number, number];
|
|
1137
|
+
declare function okhslToLinearSrgb(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
|
|
589
1138
|
/**
|
|
590
1139
|
* Compute relative luminance Y from linear sRGB channels.
|
|
591
1140
|
* Per WCAG 2: Y = 0.2126·R + 0.7152·G + 0.0722·B
|
|
@@ -598,7 +1147,7 @@ declare function contrastRatioFromLuminance(yA: number, yB: number): number;
|
|
|
598
1147
|
/**
|
|
599
1148
|
* Convert OKHSL to gamma-encoded sRGB (clamped to 0–1).
|
|
600
1149
|
*/
|
|
601
|
-
declare function okhslToSrgb(h: number, s: number, l: number): [number, number, number];
|
|
1150
|
+
declare function okhslToSrgb(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
|
|
602
1151
|
/**
|
|
603
1152
|
* Compute WCAG 2 relative luminance from linear sRGB, matching the browser
|
|
604
1153
|
* rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
|
|
@@ -610,12 +1159,12 @@ declare function gamutClampedLuminance(linearRgb: [number, number, number]): num
|
|
|
610
1159
|
* Input: [L, a, b] where L: 0–1, a/b: roughly -0.5 to 0.5.
|
|
611
1160
|
* Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
|
|
612
1161
|
*/
|
|
613
|
-
declare const oklabToOkhsl: (lab: Vec3) => Vec3;
|
|
1162
|
+
declare const oklabToOkhsl: (lab: Vec3, pastel?: boolean) => Vec3;
|
|
614
1163
|
/**
|
|
615
1164
|
* Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
|
|
616
1165
|
* Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
|
|
617
1166
|
*/
|
|
618
|
-
declare function srgbToOkhsl(rgb: [number, number, number]): [number, number, number];
|
|
1167
|
+
declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [number, number, number];
|
|
619
1168
|
/**
|
|
620
1169
|
* Convert CSS HSL (sRGB-based) to gamma-encoded sRGB [r, g, b] in 0–1 range.
|
|
621
1170
|
* h: 0–360, s: 0–1, l: 0–1.
|
|
@@ -627,29 +1176,41 @@ declare function hslToSrgb(h: number, s: number, l: number): [number, number, nu
|
|
|
627
1176
|
/**
|
|
628
1177
|
* Parse a hex color string (#rgb or #rrggbb) to sRGB [r, g, b] in 0–1 range.
|
|
629
1178
|
* Returns null if the string is not a valid hex color.
|
|
1179
|
+
*
|
|
1180
|
+
* For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
|
|
1181
|
+
* use {@link parseHexAlpha}.
|
|
630
1182
|
*/
|
|
631
1183
|
declare function parseHex(hex: string): [number, number, number] | null;
|
|
1184
|
+
/**
|
|
1185
|
+
* Parse a hex color string (#rgb, #rrggbb, #rgba, or #rrggbbaa) to
|
|
1186
|
+
* sRGB [r, g, b] in 0–1 range plus an optional alpha (0–1).
|
|
1187
|
+
* Returns null if the string is not a valid hex color.
|
|
1188
|
+
*/
|
|
1189
|
+
declare function parseHexAlpha(hex: string): {
|
|
1190
|
+
rgb: [number, number, number];
|
|
1191
|
+
alpha?: number;
|
|
1192
|
+
} | null;
|
|
632
1193
|
/**
|
|
633
1194
|
* Format OKHSL values as a CSS `okhsl(H S% L%)` string.
|
|
634
1195
|
* h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
|
|
635
1196
|
*/
|
|
636
|
-
declare function formatOkhsl(h: number, s: number, l: number): string;
|
|
1197
|
+
declare function formatOkhsl(h: number, s: number, l: number, pastel?: boolean): string;
|
|
637
1198
|
/**
|
|
638
1199
|
* Format OKHSL values as a CSS `rgb(R G B)` string.
|
|
639
1200
|
* Uses 2 decimal places to avoid 8-bit quantization contrast loss.
|
|
640
1201
|
* h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
|
|
641
1202
|
*/
|
|
642
|
-
declare function formatRgb(h: number, s: number, l: number): string;
|
|
1203
|
+
declare function formatRgb(h: number, s: number, l: number, pastel?: boolean): string;
|
|
643
1204
|
/**
|
|
644
1205
|
* Format OKHSL values as a CSS `hsl(H S% L%)` string.
|
|
645
1206
|
* h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
|
|
646
1207
|
*/
|
|
647
|
-
declare function formatHsl(h: number, s: number, l: number): string;
|
|
1208
|
+
declare function formatHsl(h: number, s: number, l: number, pastel?: boolean): string;
|
|
648
1209
|
/**
|
|
649
1210
|
* Format OKHSL values as a CSS `oklch(L C H)` string.
|
|
650
1211
|
* h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
|
|
651
1212
|
*/
|
|
652
|
-
declare function formatOklch(h: number, s: number, l: number): string;
|
|
1213
|
+
declare function formatOklch(h: number, s: number, l: number, pastel?: boolean): string;
|
|
653
1214
|
//#endregion
|
|
654
|
-
export { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type
|
|
1215
|
+
export { type AdaptationMode, type ApcaPreset, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, 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, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
|
|
655
1216
|
//# sourceMappingURL=index.d.cts.map
|