@tenphi/glaze 0.0.0-snapshot.63c08ea → 0.0.0-snapshot.6b78fce

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,972 @@
1
+ ---
2
+ title: Designing a palette
3
+ description: Build a complete Glaze palette step by step, from the surface ladder to status themes, and see it grow in every scheme.
4
+ ---
5
+
6
+ import { Callout, Steps } from '@tenphi/cookbook/components';
7
+ import PaletteStep from '../docs-site/components/methodology/PaletteStep.tsx';
8
+ import PalettePreview from '../docs-site/components/methodology/PalettePreview.tsx';
9
+ import StatusThemes from '../docs-site/components/methodology/StatusThemes.tsx';
10
+ import PaletteOutput from '../docs-site/components/methodology/PaletteOutput.astro';
11
+ import { PURPLE_HUE } from '../docs-site/components/methodology/palette.ts';
12
+
13
+ A practical way to design a Glaze palette without fighting dark mode. Start
14
+ from tone relationships, add contrast only where a role needs a readable floor,
15
+ and let `extend()` carry the same decisions across status hues.
16
+
17
+ This guide builds one palette from scratch: a neutral default theme with
18
+ surfaces, text, accents, disabled states, and effects, then a set of status
19
+ themes extended from it. After each step you see the tokens it adds and the
20
+ product UI built from the palette so far, resolved live in the scheme you are
21
+ viewing. Switch the Appearance menu to check dark and high contrast as you go.
22
+ This is where the guide ends up:
23
+
24
+ <PalettePreview caption="The finished palette, in the scheme you are viewing. Every part of this UI appears in the step that defines its token." />
25
+
26
+ For the color model behind tone, see [Tone and OKHST](./okhst.mdx); the
27
+ derivation lives in the
28
+ [canonical OKHST specification](https://github.com/tenphi/okhst). Every option
29
+ used here is documented in the [API reference](./reference/index.md).
30
+
31
+ ## The mental model
32
+
33
+ Glaze palettes work best as one default neutral theme plus a few colored
34
+ sibling themes:
35
+
36
+ - `default` owns the neutral system most components consume: `#surface`,
37
+ `#surface-text`, `#border`, `#disabled-surface`, and so on.
38
+ - Status themes (`success`, `danger`, `warning`, `note`, …) are created with
39
+ `extend()`. They swap the hue and keep only the inherited tokens that should
40
+ become status-aware.
41
+ - `inherit: false` keeps a token local to the parent theme. Use it for neutral
42
+ ladders, shadows, code colors, scrims, and anything that should not be
43
+ repeated for every status hue.
44
+
45
+ The main simplification is OKHST tone. Dark mode is a single inversion
46
+ (`100 - t`) plus a scheme tone window, so tone relationships carry over from
47
+ light to dark. A relative **tone delta** such as `tone: '-4'` is placed against
48
+ its base's light tone, then inverted and remapped like any authored tone: in
49
+ dark it flips with its base and keeps its place in the ladder, slightly
50
+ compressed by the dark window (about 0.87× at the defaults, on every base; high
51
+ contrast keeps it exact). The step is exactly contrast-even for neutrals and
52
+ approximate for chromatic colors; add a `contrast` floor when the measured
53
+ result matters.
54
+ [How relative tone adapts](./schemes.mdx#how-relative-tone-adapts) shows the
55
+ mapping.
56
+
57
+ Use `glaze.color()` instead of a theme when you need one standalone color or
58
+ one base/dependent pair and do not need a named palette. The same tone,
59
+ adaptation, and contrast rules apply; see
60
+ [Color tokens](./reference/color-tokens.md).
61
+
62
+ ## Implementation workflow
63
+
64
+ Build in dependency order so every decision has a clear base:
65
+
66
+ <Steps>
67
+ <li>Configure the output schemes and application states once.</li>
68
+ <li>Choose the default theme's hue and saturation seed.</li>
69
+ <li>Define root surfaces with absolute tones.</li>
70
+ <li>Add dependent surfaces, text, borders, and icons with tone deltas.</li>
71
+ <li>Add contrast floors only to roles that need measured readability or recognizability.</li>
72
+ <li>Choose adaptation per color: `auto`, `fixed`, or `static`.</li>
73
+ <li>Add high-contrast pairs to tones and effects that should separate more in high contrast.</li>
74
+ <li>Mark default-only tokens `inherit: false`, then extend the shared definitions into status themes.</li>
75
+ <li>Compose and export the palette in the shape your application consumes.</li>
76
+ <li>Verify complete screens in all emitted scheme variants.</li>
77
+ </Steps>
78
+
79
+ The sections below follow this order and build one palette incrementally.
80
+
81
+ ## Authoring decisions
82
+
83
+ Use this order when defining a token:
84
+
85
+ 1. Pick the base it visually belongs to.
86
+ 2. Use an absolute numeric `tone` for independent placement. Use a signed
87
+ **tone delta** (`'+N'` / `'-N'`) for distance from a base: surface ladders,
88
+ soft chips, disabled states, and similar relationships. Under `auto`, the
89
+ dark step is computed from the base's light tone, so it follows a base
90
+ placed by tone but not a `fixed` or contrast-solved one: make a delta off a
91
+ `fixed` base `fixed` too, and give a link hover its own `contrast` floor, or
92
+ use a [state layer](#state-layers) on fills.
93
+ 3. Add `contrast` only when readability or recognizability needs a measured
94
+ floor.
95
+ 4. Prefer APCA presets for content-like colors when perceptual readability is
96
+ the design goal: `contrast: { apca: 'content' }`.
97
+ 5. Use WCAG numbers or presets when compatibility, policy, or migration
98
+ requires a WCAG ratio: `contrast: 4.5`, `contrast: 'AAA'`, or
99
+ `contrast: { wcag: [4.5, 7] }`.
100
+ 6. Let token names infer APCA roles. A name whose last recognized keyword is
101
+ `text`, `label`, `border`, `surface`, `fill`, `bg`, or a similar alias
102
+ already tells Glaze which side is foreground or background, so
103
+ `surface-text-soft` is text and `accent-surface-hover` is a surface. Set
104
+ `role` only when a name is ambiguous.
105
+ 7. Let high contrast escalate floors on its own: an APCA floor rises by Lc 15,
106
+ `'AA'` becomes `'AAA'`, and `'AA-large'` becomes `'AAA-large'`. Add a
107
+ high-contrast pair where a value does not escalate by itself (tone, shadow /
108
+ glow intensity, mix value, a bare WCAG number) or where you want a different
109
+ high-contrast target.
110
+
111
+ [Contrast solving](./contrast.mdx) explains the two metrics and the presets;
112
+ [Roles and APCA polarity](./contrast.mdx#roles-and-apca-polarity) covers name
113
+ inference.
114
+
115
+ ### Choosing adaptation mode
116
+
117
+ Pick the mode by role. This palette uses all three:
118
+
119
+ | Mode | Roles |
120
+ | --- | --- |
121
+ | `auto` (default) | Surfaces, text, borders, icons, and accent foregrounds on neutral UI: they trade places with their background in dark. |
122
+ | `fixed` | Accent fills, their label, and the inverse surface: they keep their side of the tone scale. |
123
+ | `static` | The modal scrim, which must stay pure black in every scheme. |
124
+
125
+ [Adaptation modes](./schemes.mdx#adaptation-modes) shows what each mode does
126
+ per scheme. Dark tone inversion is controlled by `mode` alone; `autoFlip` only
127
+ lets an overshooting tone delta or an unmet contrast direction reverse around
128
+ its base.
129
+
130
+ ### Root or dependent?
131
+
132
+ - Use a root color when its tone has meaning on its own: the page surface, a
133
+ fixed brand anchor, or a scheme extreme.
134
+ - Use a dependent color when its purpose exists relative to another token:
135
+ text on a surface, a border around a fill, or a tint of an accent.
136
+ - Setting `base` with an absolute tone is valid when the color needs a
137
+ contrast relationship but not a tone delta. The absolute position is resolved
138
+ independently; `contrast` acts as a safety floor. Without `contrast`, such a
139
+ base does not change the resolved color; it only records which surface the
140
+ color belongs to.
141
+
142
+ ## Seed and configure
143
+
144
+ Keep hue decisions named and configure output modes once:
145
+
146
+ ```ts
147
+ import { glaze } from '@tenphi/glaze';
148
+
149
+ const PURPLE_HUE = 280.3;
150
+ const SUCCESS_HUE = 156.9;
151
+ const DANGER_HUE = 23.1;
152
+ const WARNING_HUE = 84.3;
153
+ const NOTE_HUE = 302.3;
154
+
155
+ const SEED_SATURATION = 80;
156
+
157
+ glaze.configure({
158
+ states: { dark: '@dark', highContrast: '@hc' },
159
+ modes: { dark: true, highContrast: true },
160
+ });
161
+ ```
162
+
163
+ `states` names the selectors your app uses for dark and high contrast, and
164
+ `modes` turns on the variants Glaze emits; both are covered in
165
+ [Configuration](./reference/configuration.md).
166
+
167
+ Per-color `saturation` is a factor of the theme seed, not an absolute
168
+ saturation. With `SEED_SATURATION = 80`, `saturation: 0.25` means one quarter
169
+ of that seed.
170
+
171
+ ### When dark needs its own chroma
172
+
173
+ Dark schemes get a flat `darkDesaturation` haircut (10% by default), which is
174
+ enough for most palettes. Reach for a second seed only when dark is wrong in a
175
+ way a uniform reduction cannot fix — a hue that reads muddy against dark
176
+ surfaces, or an accent that stays gaudy no matter how much you dial the global
177
+ knob. Pass the dark seed with the object form when you create the theme:
178
+
179
+ ```ts
180
+ const defaultTheme = glaze({
181
+ hue: PURPLE_HUE,
182
+ saturation: SEED_SATURATION,
183
+ darkHue: PURPLE_HUE - 12, // cooler purple on dark surfaces
184
+ darkSaturation: 62, // calmer than a 10% haircut would give
185
+ });
186
+ ```
187
+
188
+ <PalettePreview
189
+ columns={[
190
+ { label: 'Dark · seed only', scheme: 'dark' },
191
+ {
192
+ label: 'Dark · with the dark seed',
193
+ scheme: 'dark',
194
+ darkHue: PURPLE_HUE - 12,
195
+ darkSaturation: 62,
196
+ },
197
+ ]}
198
+ caption="The finished palette in dark, without and with the dark seed above. The accent fill's dark saturation goes from 72 (the seed's 80 less the 10% haircut) to exactly 62."
199
+ />
200
+
201
+ An explicit `darkSaturation` replaces `darkDesaturation` rather than stacking
202
+ with it, so the number you write is the number you get. Prefer tuning the seed
203
+ over per-color `darkHue` / `darkSaturation`: one seed keeps the palette
204
+ coherent, while scattered per-color dark overrides drift apart as the palette
205
+ grows. Save the per-color form for the one or two tokens that genuinely need
206
+ it. [Dark seed](./schemes.mdx#dark-seed) shows the effect per scheme, and
207
+ [Color definitions](./reference/color-definitions.md) has the per-color rules.
208
+ The rest of this guide builds the default theme without a dark seed, so its
209
+ previews show the plain haircut.
210
+
211
+ ## Naming
212
+
213
+ Prefer purpose first and variant last:
214
+
215
+ - Surfaces: `surface`, `surface-2`, `surface-3`.
216
+ - Foregrounds: `surface-text`, `surface-text-soft`, `surface-text-soft-2`.
217
+ - Structure: `border`, `divider`, `outline`, `placeholder`, `focus`.
218
+ - Fills: `accent-surface`, `accent-surface-2`, `accent-surface-hover`.
219
+ - Foregrounds on neutral surfaces: `accent-text`, `accent-text-soft`,
220
+ `accent-icon`.
221
+ - Disabled states: `disabled-surface`, `disabled-surface-text`,
222
+ `accent-disabled-surface`, `accent-disabled-surface-text`.
223
+ - Effects: `shadow-sm`, `shadow-md`, `shadow-lg`, `surface-hover`,
224
+ `accent-surface-pressed`, `accent-surface-highlight`, `scrim`, `hover`,
225
+ `tint`.
226
+
227
+ These names are not only readable. They also help APCA role inference pick the
228
+ right polarity. For example, `button-text` is foreground, `input-bg` is a
229
+ surface, and `card-outline` is a border.
230
+
231
+ ## Build the default theme
232
+
233
+ ### The surface ladder
234
+
235
+ Start with the surface family. It is mostly tone, with small saturation changes
236
+ to keep the ladder visually coherent:
237
+
238
+ ```ts
239
+ const defaultTheme = glaze(PURPLE_HUE, SEED_SATURATION);
240
+
241
+ defaultTheme.colors({
242
+ surface: { tone: 100, saturation: 0.11 },
243
+ 'surface-2': {
244
+ base: 'surface',
245
+ tone: '-2',
246
+ saturation: 0.15,
247
+ inherit: false,
248
+ },
249
+ 'surface-3': {
250
+ base: 'surface',
251
+ tone: '-4',
252
+ saturation: 0.19,
253
+ inherit: false,
254
+ },
255
+ });
256
+ ```
257
+
258
+ <PaletteStep
259
+ step="surfaces"
260
+ schemes={['light', 'dark']}
261
+ caption="The ladder in light and dark. Each step moves away from surface's end of the scale in both schemes. Before any text exists, the UI is a wireframe: the page is surface-2, the cards are surface, and the bars and track are surface-3."
262
+ />
263
+
264
+ Each tone delta is placed against `surface`'s light tone and then mapped into
265
+ each scheme like an authored tone, so the ladder keeps its order everywhere and
266
+ flips with `surface` in dark. The dark window compresses the steps a little:
267
+ `'-2'` and `'-4'` land 1.7 and 3.5 tones from `surface` in dark, and high
268
+ contrast keeps them exact. These small deltas are enough to define the ladder;
269
+ there is no separate dark-mode curve to tune.
270
+
271
+ ### Text and borders
272
+
273
+ Use a hard edge tone for maximum-prominence text, and APCA floors for softer
274
+ content:
275
+
276
+ ```ts
277
+ defaultTheme.colors({
278
+ 'surface-text': {
279
+ base: 'surface',
280
+ tone: 2,
281
+ saturation: 0.475,
282
+ },
283
+ 'surface-text-soft': {
284
+ base: 'surface',
285
+ tone: '-1',
286
+ saturation: 0.375,
287
+ contrast: { apca: ['content', 'body'] },
288
+ inherit: false,
289
+ },
290
+ 'surface-text-soft-2': {
291
+ base: 'surface',
292
+ tone: '-1',
293
+ saturation: 0.24,
294
+ contrast: { apca: ['large', 'content'] },
295
+ inherit: false,
296
+ },
297
+ border: {
298
+ base: 'surface',
299
+ tone: ['-10', '-20'],
300
+ saturation: 0.175,
301
+ inherit: false,
302
+ },
303
+ });
304
+ ```
305
+
306
+ <PaletteStep
307
+ step="text"
308
+ caption="Each foreground on its base, with the APCA Lc it reaches against surface in your scheme. The soft variants land on their floors (Lc 60 and 45, or 75 and 60 in high contrast). The border has no floor; APCA rates very dark pairs at Lc 0, so in dark it reads 0 although it sits about 9 tones off surface (20 in high contrast)."
309
+ />
310
+
311
+ `surface-text` uses an absolute `tone: 2`: it is intentionally edge-anchored,
312
+ and with no `contrast` floor its `base` only records which surface it belongs
313
+ to. The soft variants use a `-1` tone delta as the preferred direction and
314
+ APCA as the readable floor. Their pairs only spell out what high contrast does
315
+ anyway (an APCA floor rises by Lc 15), so a bare `{ apca: 'content' }`
316
+ resolves the same; this guide writes them out to keep the high-contrast target
317
+ visible. `border` needs its tone pair, because tones do not escalate on their
318
+ own and borders usually need a larger visible step in high contrast.
319
+
320
+ Repeat the same pattern for `surface-2` and `surface-3` only if components need
321
+ text directly on those surfaces.
322
+
323
+ ### Neutral utility tokens
324
+
325
+ Keep neutral-only primitives local to the default theme:
326
+
327
+ ```ts
328
+ defaultTheme.colors({
329
+ placeholder: {
330
+ base: 'surface',
331
+ tone: 67,
332
+ saturation: 0.175,
333
+ inherit: false,
334
+ },
335
+ focus: {
336
+ base: 'surface',
337
+ tone: 71,
338
+ saturation: 0.8625,
339
+ inherit: false,
340
+ },
341
+ disabled: {
342
+ tone: 80.8,
343
+ saturation: 0.4,
344
+ inherit: false,
345
+ },
346
+ });
347
+ ```
348
+
349
+ <PaletteStep
350
+ step="utility"
351
+ caption="A search field with its placeholder and focus ring, and an unavailable option drawn in disabled."
352
+ />
353
+
354
+ Absolute tones are fine for primitives whose job is visual placement rather
355
+ than a strict relationship to a specific surface.
356
+
357
+ ## Chips and disabled states
358
+
359
+ For subtle fills, tone is usually clearer than contrast:
360
+
361
+ ```ts
362
+ defaultTheme.colors({
363
+ 'disabled-surface': {
364
+ base: 'surface',
365
+ tone: '-3',
366
+ saturation: 0.2,
367
+ inherit: false,
368
+ },
369
+ 'disabled-surface-text': {
370
+ base: 'disabled-surface',
371
+ tone: '-18',
372
+ saturation: 0.3,
373
+ autoFlip: false,
374
+ inherit: false,
375
+ },
376
+ });
377
+ ```
378
+
379
+ <PaletteStep
380
+ step="chips"
381
+ caption="A disabled chip: a small tone step off surface, with a deliberately faint label 16 to 18 tones from the chip in every scheme. In dark its Lc drops toward 0 for the same reason the border's does."
382
+ />
383
+
384
+ This says exactly what the pair should do: the chip sits a small tone delta off
385
+ `surface`, and the label sits a muted delta from the chip. `autoFlip: false`
386
+ keeps the label on the authored side when the delta reaches the edge. Point the
387
+ delta away from the nearer edge: the chip sits at tone 97 in light, so `'+18'`
388
+ would have only three tones of room, and with `autoFlip: false` it would clamp
389
+ at 100 and the label would all but vanish.
390
+
391
+ Use contrast instead when the chip must hit an explicit accessibility floor:
392
+
393
+ ```ts
394
+ defaultTheme.colors({
395
+ 'disabled-surface-text': {
396
+ base: 'disabled-surface',
397
+ tone: '+1',
398
+ saturation: 0.3,
399
+ contrast: { apca: 'non-text' },
400
+ inherit: false,
401
+ },
402
+ });
403
+ ```
404
+
405
+ <PaletteStep
406
+ step="chips"
407
+ extra="disabled-floor"
408
+ preview={false}
409
+ caption="The same chip with the floor instead: the label reaches the same APCA Lc in light and dark (30, raised automatically to 45 in high contrast). The '+1' preference is too close to meet it, so the solver crosses to the other side of the chip."
410
+ />
411
+
412
+ When a token needs the scheme extreme, use `tone: 'min'` or `tone: 'max'`
413
+ directly. Avoid large magic numbers or fake contrast floors just to push a
414
+ color to the edge.
415
+
416
+ Pair the extreme with a `base` when the gap between the two has to survive the
417
+ scheme switch. Glaze then replays the light-scheme tone shift against the
418
+ resolved dark base instead of re-mapping the extreme through the dark window,
419
+ so a knockout on a surface keeps the same contrast in both schemes.
420
+ [Extremes in dark](./schemes.mdx#extremes-in-dark) shows the replay.
421
+
422
+ ## Fixed surfaces and accent fills
423
+
424
+ Use `mode: 'fixed'` when the authored color should stay recognizable across
425
+ schemes.
426
+
427
+ ```ts
428
+ defaultTheme.colors({
429
+ 'surface-inverse': {
430
+ tone: 12,
431
+ saturation: 0.475,
432
+ mode: 'fixed',
433
+ inherit: false,
434
+ },
435
+
436
+ 'accent-surface-text': {
437
+ tone: 100,
438
+ mode: 'fixed',
439
+ },
440
+ 'accent-surface': {
441
+ base: 'accent-surface-text',
442
+ tone: '-1',
443
+ contrast: { apca: ['content', 'body'] },
444
+ mode: 'fixed',
445
+ },
446
+ 'accent-surface-2': {
447
+ base: 'accent-surface-text',
448
+ tone: '-1',
449
+ contrast: { apca: [65, 80] },
450
+ mode: 'fixed',
451
+ },
452
+ 'accent-surface-hover': {
453
+ base: 'accent-surface-text',
454
+ tone: '-1',
455
+ contrast: { apca: ['body', 'preferred'] },
456
+ mode: 'fixed',
457
+ },
458
+ });
459
+ ```
460
+
461
+ <PaletteStep
462
+ step="fixed"
463
+ schemes={['light', 'dark']}
464
+ caption="Fixed tokens keep their side of the scale: surface-inverse stays dark and the accent fills keep a light label in both schemes. Lc is measured with accent-surface-text as the label on each fill."
465
+ />
466
+
467
+ The accent fill family is a fixed chain against a fixed text anchor. The names
468
+ infer `surface` and `text` roles, so APCA gets the right polarity without extra
469
+ fields.
470
+
471
+ ## Adaptive accent foregrounds
472
+
473
+ Brand foregrounds that sit on neutral surfaces should stay adaptive:
474
+
475
+ ```ts
476
+ defaultTheme.colors({
477
+ 'accent-text': {
478
+ base: 'surface',
479
+ tone: '-1',
480
+ saturation: 1,
481
+ contrast: { apca: ['content', 'body'] },
482
+ },
483
+ 'accent-text-soft': {
484
+ base: 'surface',
485
+ tone: '-1',
486
+ saturation: 1,
487
+ contrast: { apca: ['large', 'content'] },
488
+ },
489
+ 'accent-icon': {
490
+ base: 'surface',
491
+ tone: '-1',
492
+ saturation: 0.9375,
493
+ contrast: { apca: ['non-text', 'large'] },
494
+ },
495
+ });
496
+ ```
497
+
498
+ <PaletteStep
499
+ step="adaptive"
500
+ caption="A link, its softer caption, and an icon, each floored against surface."
501
+ />
502
+
503
+ Anchor these to `surface`, not to `accent-surface`. Their real job is to remain
504
+ readable on neutral UI, so `mode: 'auto'` and a surface base are the right
505
+ defaults.
506
+
507
+ Brand-tinted disabled states can usually be pure tone:
508
+
509
+ ```ts
510
+ defaultTheme.colors({
511
+ 'accent-disabled-surface': {
512
+ base: 'surface',
513
+ tone: '+3',
514
+ saturation: 0.5,
515
+ },
516
+ 'accent-disabled-surface-text': {
517
+ base: 'accent-disabled-surface',
518
+ tone: '-18',
519
+ saturation: 0.4,
520
+ autoFlip: false,
521
+ },
522
+ });
523
+ ```
524
+
525
+ <PaletteStep
526
+ step="accent-disabled"
527
+ caption="The brand-tinted disabled button."
528
+ />
529
+
530
+ On the white default `surface` there is no room for `'+3'`, so `autoFlip`
531
+ (on by default) mirrors the chip just below `surface`; on the tinted status
532
+ surfaces later in this guide it lands above. The label follows the same rule as
533
+ the neutral disabled chip.
534
+
535
+ These are inherited, so status themes automatically get
536
+ `success-accent-disabled-surface`, `danger-accent-disabled-surface`, and the
537
+ matching text tokens.
538
+
539
+ ## Special-purpose colors
540
+
541
+ Use absolute `hue` overrides for tokens that should come from another hue
542
+ family but keep the same adaptation behavior:
543
+
544
+ ```ts
545
+ defaultTheme.colors({
546
+ 'code-comment': {
547
+ base: 'surface',
548
+ hue: 280,
549
+ saturation: 0.1,
550
+ tone: '-1',
551
+ contrast: { apca: ['large', 'content'] },
552
+ inherit: false,
553
+ },
554
+ 'code-keyword': {
555
+ base: 'surface',
556
+ hue: 348,
557
+ saturation: 1,
558
+ tone: '-1',
559
+ contrast: { apca: ['content', 'body'] },
560
+ inherit: false,
561
+ },
562
+ 'code-string': {
563
+ base: 'surface',
564
+ hue: SUCCESS_HUE,
565
+ saturation: 1,
566
+ tone: '-1',
567
+ contrast: { apca: ['large', 'content'] },
568
+ inherit: false,
569
+ },
570
+ });
571
+ ```
572
+
573
+ <PaletteStep
574
+ step="code"
575
+ caption="Syntax colors from three hue families, each floored against surface like any other foreground."
576
+ />
577
+
578
+ Use small tone ramps for decorative motion:
579
+
580
+ ```ts
581
+ defaultTheme.colors({
582
+ 'loading-face-1': {
583
+ base: 'surface',
584
+ tone: 98,
585
+ saturation: 0.3,
586
+ inherit: false,
587
+ },
588
+ 'loading-face-2': {
589
+ base: 'surface',
590
+ tone: 91,
591
+ saturation: 0.62,
592
+ inherit: false,
593
+ },
594
+ 'loading-face-3': {
595
+ base: 'surface',
596
+ tone: 79,
597
+ saturation: 0.66,
598
+ inherit: false,
599
+ },
600
+ });
601
+ ```
602
+
603
+ <PaletteStep
604
+ step="loading"
605
+ caption="A loading skeleton built from the three faces."
606
+ />
607
+
608
+ Absolute tones invert and remap the same way in every scheme, so the ramp keeps
609
+ its order and close to its spacing without involving the contrast solver: the
610
+ tone windows narrow it to about 95% in light and 87% in dark, and high contrast
611
+ keeps it exact. Use a high-contrast tone pair only when the animation should
612
+ become more pronounced in high contrast.
613
+
614
+ ## Effects
615
+
616
+ Shadows and glows are translucent overlays with an exact tone step:
617
+ `intensity` is how many tones darker (`shadow`) or lighter (`glow`) the surface
618
+ ends up once the browser composites it. The opacity is solved per surface, so
619
+ the same number reads the same on white, on a mid-tone accent and on a dark
620
+ surface. Direction is fixed per type: a `shadow` always darkens and a `glow`
621
+ always lightens, in every scheme. [Shadows and glows](./shadows-and-glows.mdx)
622
+ covers the model in depth.
623
+
624
+ ### Shadows
625
+
626
+ Define one neutral shadow system. Point `bg` at the surface the shadow falls on
627
+ and `fg` at the element that casts it — here a `surface` card on the
628
+ `surface-2` page:
629
+
630
+ ```ts
631
+ defaultTheme.colors({
632
+ 'shadow-sm': {
633
+ type: 'shadow',
634
+ bg: 'surface-2',
635
+ fg: 'surface',
636
+ intensity: 4,
637
+ inherit: false,
638
+ },
639
+ 'shadow-md': {
640
+ type: 'shadow',
641
+ bg: 'surface-2',
642
+ fg: 'surface',
643
+ intensity: [8, 14],
644
+ inherit: false,
645
+ },
646
+ 'shadow-lg': {
647
+ type: 'shadow',
648
+ bg: 'surface-2',
649
+ fg: 'surface',
650
+ intensity: [12, 20],
651
+ inherit: false,
652
+ },
653
+ });
654
+ ```
655
+
656
+ <PaletteStep
657
+ step="shadows"
658
+ schemes={['light', 'dark', 'lightContrast', 'darkContrast']}
659
+ preview={false}
660
+ caption="A surface card casting each shadow on surface-2, in all four schemes. The value line is the solved opacity and the tone step the composite actually lands."
661
+ />
662
+
663
+ `fg` modulates the step the way bounce light does: an object at the surface's
664
+ own tone gives exactly `intensity`, a darker object casts a deeper shadow and a
665
+ lighter one a softer shadow. Do not point `fg` at text — it is the object, not
666
+ a contrast reference. Use a high-contrast pair for shadows that should deepen
667
+ in high contrast.
668
+
669
+ <Callout kind="caution" title="Shadows need room below the surface">
670
+ A shadow can only darken as far as black. The page surface here,
671
+ `surface-2`, sits at tone 98 in light but about 11 in dark and 2 in dark
672
+ high contrast, so `shadow-lg` falls just short of its step in dark, and in
673
+ dark high contrast all three pin at full opacity and still land only about 2
674
+ tones down. Glaze warns for each step it cannot reach. Every color resolves
675
+ in all four schemes, so not binding a shadow in dark only keeps the pinned
676
+ value off screen; the warning fires anyway. The fix is headroom: a lower
677
+ `intensity`, or a surface with room below it in every scheme. For elevation
678
+ in dark, reach for [glows](./shadows-and-glows.mdx#dark-mode-elevation)
679
+ instead. This palette keeps its near-white page, so these warnings are
680
+ expected.
681
+ </Callout>
682
+
683
+ ### State layers
684
+
685
+ Without `fg`, a shadow or glow is an exact shade or tint — the right tool for
686
+ state layers, which need the same visible change on every fill:
687
+
688
+ ```ts
689
+ defaultTheme.colors({
690
+ 'surface-hover': { type: 'shadow', bg: 'surface', intensity: 3 },
691
+ 'accent-surface-pressed': {
692
+ type: 'shadow',
693
+ bg: 'accent-surface',
694
+ intensity: [6, 10],
695
+ },
696
+ 'accent-surface-highlight': {
697
+ type: 'glow',
698
+ bg: 'accent-surface',
699
+ intensity: 5,
700
+ },
701
+ });
702
+ ```
703
+
704
+ <PaletteStep
705
+ step="state-layers"
706
+ caption="Each layer over the fill it targets, then in the UI: the hovered row and the pressed and highlighted buttons. The cards now carry shadow-md and shadow-sm."
707
+ />
708
+
709
+ A fixed opacity cannot do this: an 8% black layer darkens white by about 6
710
+ tones but a tone-10 surface by about 1
711
+ ([The same step on every surface](./shadows-and-glows.mdx#the-same-step-on-every-surface)
712
+ compares the two). The same headroom rule applies, though: in dark high
713
+ contrast `surface` sits at tone 0, so `surface-hover` has nothing to darken
714
+ there and resolves transparent, with a warning.
715
+
716
+ Glows are the mirror, for dark-mode elevation and edge highlights. A glow needs
717
+ headroom above its surface, so a glow on a white light-mode surface has
718
+ nothing to lighten — Glaze leaves it transparent and warns, even if you only
719
+ use the token in dark. Give glows a surface with room in every scheme, as
720
+ `accent-surface-highlight` has on the mid-tone accent fill.
721
+
722
+ ### Fixed opacity and mixes
723
+
724
+ Use `opacity` for one fixed-alpha color, such as a modal scrim:
725
+
726
+ ```ts
727
+ defaultTheme.colors({
728
+ scrim: {
729
+ tone: 0,
730
+ saturation: 0,
731
+ mode: 'static',
732
+ opacity: 0.5,
733
+ inherit: false,
734
+ },
735
+ });
736
+ ```
737
+
738
+ <PaletteStep
739
+ step="scrim"
740
+ schemes={['light', 'dark']}
741
+ preview={false}
742
+ caption="The scrim at a fixed 50% over surface: black in light and dark, and in both high-contrast variants."
743
+ />
744
+
745
+ `mode: 'static'` keeps the scrim pure black. Under the default `auto`, tone 0
746
+ would be remapped to about 5 in light and inverted to about 96 in dark, turning
747
+ the scrim into a light 50% wash there.
748
+
749
+ Use mixes when one color should tint through another:
750
+
751
+ ```ts
752
+ defaultTheme.colors({
753
+ hover: {
754
+ type: 'mix',
755
+ base: 'surface',
756
+ target: 'accent-surface',
757
+ value: 8,
758
+ blend: 'transparent',
759
+ },
760
+ tint: {
761
+ type: 'mix',
762
+ base: 'surface',
763
+ target: 'accent-surface',
764
+ value: 20,
765
+ },
766
+ });
767
+ ```
768
+
769
+ <PaletteStep
770
+ step="mixes"
771
+ caption="A transparent accent hover over surface and a solid 20% tint, then the complete default theme."
772
+ />
773
+
774
+ Transparent mixes are good for tinted hover washes. Opaque mixes are good for
775
+ solid tints. Opaque mixes default to perceptual OKHSL interpolation; set
776
+ `space: 'srgb'` for linear-light channel interpolation. Transparent mixes are
777
+ composited by the browser, and their contrast solve models that compositing.
778
+ Mix colors can also use `contrast`; the solver adjusts the value or opacity to
779
+ meet the floor. If the floor is out of reach, the mix settles at the pure target
780
+ (the pure base when its value is already 100) and Glaze warns, as it does for a
781
+ regular color. See [Mixes and transparency](./mixes.mdx).
782
+
783
+ ## High contrast
784
+
785
+ High contrast is not a separate palette. Contrast floors escalate on their own
786
+ in the high-contrast variants: an APCA floor rises by Lc 15, `'AA'` becomes
787
+ `'AAA'`, and `'AA-large'` becomes `'AAA-large'` (a bare WCAG number stays as
788
+ written). Text, icons, and accent fills tighten with no extra fields;
789
+ [Contrast solving](./contrast.mdx#high-contrast) has the full table.
790
+
791
+ Tones, shadow / glow `intensity`, and mix `value` do not escalate. Give them a
792
+ high-contrast pair where users should get more separation:
793
+
794
+ - Borders: `tone: ['-10', '-20']`.
795
+ - Shadows and glows: `intensity: [8, 14]`.
796
+ - Decorative ramps that must stay perceivable.
797
+
798
+ A contrast pair is only needed for a different high-contrast target than the
799
+ automatic one, such as `{ apca: ['content', 'preferred'] }`.
800
+
801
+ In high-contrast variants, Glaze bypasses the normal tone window and uses the
802
+ full `[0, 100]` range. Edge tones can reach the edge; contrast floors have more
803
+ room to solve.
804
+
805
+ <PalettePreview
806
+ schemes={['light', 'dark', 'lightContrast', 'darkContrast']}
807
+ caption="The finished palette in all four schemes. In high contrast the borders deepen, soft text and accent fills move to their high-contrast floors, and the surfaces reach the ends of the scale."
808
+ />
809
+
810
+ ### A slider through the tier
811
+
812
+ The two-tier model assumes contrast is a binary OS preference. When contrast is
813
+ instead a setting _your users_ control, set
814
+ [`contrastLevel`](./reference/contrast.md#manual-contrast-level) to a number
815
+ and your **normal** palette slides along a `0–100` ramp: level `0` is the
816
+ palette you authored, `100` is its high-contrast variant, and everything
817
+ between is resolved at that level.
818
+
819
+ <PalettePreview
820
+ columns={[
821
+ { label: 'Light · level 0', scheme: 'light', contrastLevel: 0 },
822
+ { label: 'Light · level 50', scheme: 'light', contrastLevel: 50 },
823
+ { label: 'Light · level 100', scheme: 'light', contrastLevel: 100 },
824
+ ]}
825
+ caption="The finished palette's light variant at three levels. No new fields: the slider ramps toward the high-contrast values, escalated floors and pairs alike."
826
+ />
827
+
828
+ The authoring work is the same: the slider ramps toward the values the
829
+ high-contrast tier uses, so a palette tuned for high contrast needs no new
830
+ fields. Two things worth planning for:
831
+
832
+ - The slider and the tier compose. The high-contrast tier keeps resolving at
833
+ full contrast regardless of the level, so wire the level into your build or
834
+ runtime _and_ keep your `prefers-contrast: more` block: a user who has raised
835
+ the slider and asked their OS for more contrast still gets the escalation on
836
+ top. The one exception is a global level of `100`
837
+ (`glaze.configure({ contrastLevel: 100 })`), where the two coincide and the
838
+ tier is dropped as a duplicate. A per-theme level of `100` still emits the
839
+ tier, with values equal to the normal ones.
840
+ - `contrastLevel: 0` is the natural rest position for a slider you ship but
841
+ default off — it reproduces the `'auto'` output bit for bit.
842
+
843
+ [Manual contrast level](./schemes.mdx#manual-contrast-level) shows the level
844
+ as a strip; [Contrast and high contrast](./reference/contrast.md#manual-contrast-level)
845
+ in the API reference has the exact interpolation rules.
846
+
847
+ ## Extend into status themes
848
+
849
+ Once the default theme is shaped, create colored siblings by replacing hue and
850
+ overriding only the root surface that should become visibly tinted:
851
+
852
+ ```ts
853
+ const TINTED_SURFACE_OVERRIDE = {
854
+ surface: { tone: 96, saturation: 0.8 },
855
+ };
856
+
857
+ const primaryTheme = defaultTheme.extend({
858
+ colors: TINTED_SURFACE_OVERRIDE,
859
+ });
860
+ const successTheme = defaultTheme.extend({
861
+ hue: SUCCESS_HUE,
862
+ colors: TINTED_SURFACE_OVERRIDE,
863
+ });
864
+ const dangerTheme = defaultTheme.extend({
865
+ hue: DANGER_HUE,
866
+ colors: TINTED_SURFACE_OVERRIDE,
867
+ });
868
+ const warningTheme = defaultTheme.extend({
869
+ hue: WARNING_HUE,
870
+ colors: TINTED_SURFACE_OVERRIDE,
871
+ });
872
+ const noteTheme = defaultTheme.extend({
873
+ hue: NOTE_HUE,
874
+ colors: TINTED_SURFACE_OVERRIDE,
875
+ });
876
+ ```
877
+
878
+ <StatusThemes caption="Each theme painted only with its own tokens. The token count shows inherit: false at work: the default theme carries the whole palette, each sibling only the inherited subset." />
879
+
880
+ The inherited accent tokens (including `accent-disabled-*`) now resolve in each
881
+ status hue. Tokens marked `inherit: false` stay default-only, so sibling themes
882
+ remain small. [`theme.extend()`](./reference/theme.md#themeextendoptions)
883
+ documents how inherited and overriding definitions merge.
884
+
885
+ <Callout kind="caution" title="A dark seed is inherited too">
886
+ `extend()` keeps the parent's `darkHue` and `darkSaturation` unless you pass
887
+ new ones. If the default theme has the dark seed from
888
+ [When dark needs its own chroma](#when-dark-needs-its-own-chroma), a status
889
+ theme that only sets `hue` turns purple in dark. Pass its own `darkHue` next
890
+ to `hue`, for example `hue: SUCCESS_HUE, darkHue: SUCCESS_HUE - 12`.
891
+ </Callout>
892
+
893
+ ## Export the palette
894
+
895
+ Compose the themes once:
896
+
897
+ ```ts
898
+ const palette = glaze.palette({
899
+ default: defaultTheme,
900
+ primary: primaryTheme,
901
+ success: successTheme,
902
+ danger: dangerTheme,
903
+ warning: warningTheme,
904
+ note: noteTheme,
905
+ });
906
+ ```
907
+
908
+ The usual export shape is default unprefixed and status themes prefixed:
909
+
910
+ ```ts
911
+ const prefix = {
912
+ default: '',
913
+ primary: 'primary-',
914
+ success: 'success-',
915
+ danger: 'danger-',
916
+ warning: 'warning-',
917
+ note: 'note-',
918
+ };
919
+
920
+ palette.tasty({ prefix });
921
+ ```
922
+
923
+ <PaletteOutput />
924
+
925
+ An explicit prefix map is the clearest choice when the palette has a neutral
926
+ `default` theme. The separate palette `primary` option serves another pattern:
927
+ it duplicates one named theme without a prefix while retaining its prefixed
928
+ tokens. Do not combine the two accidentally; choose the token namespace your
929
+ components expect.
930
+
931
+ The palette design is independent of the exporter:
932
+
933
+ ```ts
934
+ palette.tokens({ prefix }); // JavaScript maps, native oklch by default
935
+ palette.css({ prefix }); // CSS custom-property declarations
936
+ palette.dtcg({ prefix }); // one design-token tree per scheme
937
+ palette.tailwind({ prefix }); // Tailwind CSS v4 theme
938
+ ```
939
+
940
+ Use `palette.tasty({ prefix })` for [Tasty](https://tasty.style) state
941
+ bindings. [Choosing an export](./exporting.mdx#choosing-an-export) covers
942
+ output shapes and application wiring, and
943
+ [the `primary` alias](./exporting.mdx#the-primary-alias) the alias pattern;
944
+ every palette option is in the [Palettes](./reference/palette.md) reference.
945
+
946
+ ## Checklist
947
+
948
+ Before shipping a palette, verify:
949
+
950
+ - Text, icon, and content tokens either have APCA/WCAG contrast or are
951
+ deliberately edge-anchored.
952
+ - Accent fills use `mode: 'fixed'`; accent foregrounds on neutral UI stay
953
+ `mode: 'auto'` and are based on `surface`.
954
+ - Ambiguous APCA tokens have an explicit `role`; obvious names rely on
955
+ inference.
956
+ - Low-stakes visual relationships use tone deltas instead of fake contrast
957
+ floors.
958
+ - `inherit: false` is set on default-only tokens so status themes stay
959
+ focused.
960
+ - Tones, shadow / glow intensities, and mix values that should change in high
961
+ contrast have a high-contrast pair. Contrast floors escalate on their own;
962
+ both feed a manual `contrastLevel`.
963
+ - Status themes extended from a theme with a dark seed pass their own
964
+ `darkHue`.
965
+ - `glaze.configure({ states, modes })` matches the states registered in the
966
+ app.
967
+ - Every emitted scheme (`light`, `dark`, `lightContrast`, `darkContrast`) has
968
+ been reviewed on complete screens, not only in a token grid.
969
+ - Rendered WCAG/APCA results have been checked for chromatic foreground/base
970
+ pairs that carry accessibility requirements.
971
+ - Resolution emits no unexplained unreachable-contrast (colors and mixes),
972
+ unreachable shadow / glow, or token-collision warnings.