Methodology

A practical guide for designing a real, production-grade Glaze palette. Recipe-ordered: the sections follow the same sequence you'd actually build a palette in, and each one ties the choice back to a Glaze behavior.

The mental model

A Glaze palette is a default neutral theme plus a small fan of colored sibling themes (success, danger, warning, note, …) created via extend(). Most colors live in the default theme as neutrals; brand-tinted colors come from extend() swapping the hue.

The default theme is what most components consume — its tokens are emitted unprefixed (#surface, #border). Colored themes are scoped to status surfaces and accent variants, emitted with a theme-name prefix (#success-surface, #danger-accent-surface).

You design the default theme once, and extend() propagates that design across every status hue.

Every color definition has an inherit flag (default: true) controlling whether it flows into child themes via extend(). Set inherit: false to scope a color to its parent theme only — this is how sibling themes stay lean, carrying only the tokens they actually need.

Hue / saturation seeds

Declare hues as named constants up top, plus a single shared seed saturation:

const PURPLE_HUE  = 280.3;
const SUCCESS_HUE = 156.9;
const DANGER_HUE  = 23.1;
const WARNING_HUE = 84.3;
const NOTE_HUE    = 302.3;

const SEED_SATURATION = 80;

Hues are design tokens too — keeping them named in one place beats burying numbers in extend() calls. The shared SEED_SATURATION keeps every status theme on the same saturation budget; per-color saturation factors below are 0–1 of this seed, not absolute.

Global glaze.configure()

Configure state aliases and output modes once at module load:

glaze.configure({
  states: { dark: '@dark', highContrast: '@hc' },
  modes:  { dark: true,    highContrast: true },
});

Match the state alias names to whatever your app wires into the global predefined states (@dark / @hc is what Tasty expects). Setting modes.highContrast: true makes every export emit four variants — HC tokens are then available globally without per-call overrides.

Naming conventions

A tight, predictable vocabulary that the rest of the doc relies on:

Pattern	Tokens
Surface ladder	surface, surface-2, surface-3
Text on surface (decreasing prominence)	<surface>-text, <surface>-text-soft, <surface>-text-soft-2
Misc neutral primitives	border, placeholder, focus, disabled
Neutral disabled chip	disabled-surface, disabled-surface-text
Fixed-mode dark surface	surface-inverse
Brand fills	accent-surface, accent-surface-2, accent-surface-3, accent-surface-hover
Brand fill anchor	accent-surface-text (the fixed white token everything anchors to)
Brand foregrounds on neutrals	accent-text, accent-text-soft, accent-icon
Brand-tinted disabled	accent-disabled-surface, accent-disabled-surface-text
Code syntax highlighting	code-comment, code-keyword, code-string, code-number, …
Loading animation	loading-face-1, loading-face-2, loading-face-3
Shadows	shadow-sm, shadow-md, shadow-lg
Backdrop	overlay

Rule of thumb: purpose-name first, variant suffix last (-2, -text, -soft, -hover, -disabled).

Surfaces (root colors)

surface is a root color (absolute tone, no base) with a low saturation factor. The ladder chains off it via small relative offsets:

defaultTheme.colors({
  surface:     { tone: 100, saturation: 0.11 },
  'surface-2': { base: 'surface', tone: '-2', saturation: 0.15, inherit: false },
  'surface-3': { base: 'surface', tone: '-4', saturation: 0.19, inherit: false },
});

A factor of 0.11 of the seed gives a barely-noticeable hue shift — enough that light/dark surfaces feel branded, not enough to look tinted. The slight saturation bump on -2 / -3 compensates for perceived saturation dropping as tone drops, so the ladder reads as one consistent surface family.

mode: 'auto' (the default) inverts these in tone (100 − t) and remaps into the dark window, so a tone: 100 light-mode surface lands at the dark window's floor in dark mode. Because tone is contrast-uniform, the relative deltas (-2, -4) translate to the same contrast steps in both schemes — no fitted curve required. inherit: false on -2 / -3 keeps colored sibling themes lean — they only need a single tinted surface, not the whole ladder.

Text on surfaces (anchor at the edge)

The headline trick of the whole methodology. Strong text uses an absolute tone near the edge of the window; soft variants use a directional relative hint plus a numeric contrast.

'surface-text': {
  base: 'surface', tone: 2, saturation: 0.475,
},
'surface-text-soft': {
  base: 'surface', tone: '-1', saturation: 0.375,
  contrast: [9, 11], inherit: false,
},
'surface-text-soft-2': {
  base: 'surface', tone: '-1', saturation: 0.24,
  contrast: [4.5, 5.5], inherit: false,
},

Repeat the same triple anchored to each subordinate surface (surface-2-text, surface-2-text-soft, surface-3-text, …) so the ladder stays self-consistent.

The strong-text tone: 2 pins the light-mode resolved value near the bottom of the light window (close to black against the near-white surface) and inverts to near-white in dark mode — both yielding very high contrast against their surface. A contrast: 'AAA' solver pass would have stopped at the AAA floor (cr = 7) and no further. Anchoring at the edge beats the contrast solver because the solver only needs to meet the floor, not exceed it.

The soft variants use tone: '-1' only as a directional hint — the real positioning comes from the numeric contrast. Numeric ratios give designers precise perceived weight where presets would only guarantee the AA/AAA floor.

In high-contrast mode the tone window is bypassed entirely (full [0, 100] range), so tone: 2 reaches close to black in light HC and close to white in dark HC — maximal contrast against the surface in both.

Other neutral primitives

Borders, placeholders, focus rings, and the floating "muted text" tone — all default-only:

border:      { base: 'surface', tone: ['-10', '-20'], saturation: 0.175,  inherit: false },
placeholder: { base: 'surface', tone: 67,             saturation: 0.175,  inherit: false },
focus:       { base: 'surface', tone: 71,             saturation: 0.8625, inherit: false },
disabled:    { tone: 80.8, saturation: 0.4,                                inherit: false },

border uses an HC pair — the border darkens twice as much in high-contrast mode for visibility. placeholder and focus give a base for namespacing but use absolute tone independently. disabled is a root color (no base) — it's used as a plain "muted text" token in some places, free of the surface chain.

Disabled chip (contrast-driven for scheme symmetry)

The disabled chip + label pair uses mode: 'auto' and explicit numeric contrast against surface, not preset 'AA' / 'AAA':

'disabled-surface': {
  base: 'surface', tone: '-1', saturation: 0.2,
  contrast: [1.5, 2], inherit: false,
},
'disabled-surface-text': {
  base: 'disabled-surface', tone: '+1', saturation: 0.3,
  contrast: 3, inherit: false,
},

Each token anchors to its immediate parent surface — *-surface contrasts against the root surface, while *-surface-text contrasts against its own chip (disabled-surface). This keeps the disabled state self-contained and resolves to consistent ratios in light, dark, and HC (chip ≈ 1.5–2× vs surface, label ≈ 3× on chip). An alpha-tinted overlay would have asymmetric behavior — composited alpha against a near-white light surface produces a much weaker chip than the same overlay against a near-dark dark surface, and the disabled state would stop looking disabled in one of the schemes.

The general rule: when a color needs to feel the same across schemes, anchor it with mode: 'auto' + a numeric contrast against a surface, not with a preset.

surface-inverse (the fixed-mode escape hatch)

'surface-inverse': {
  tone: 12, saturation: 0.475, mode: 'fixed', inherit: false,
},

mode: 'fixed' skips the dark-scheme tone inversion and only remaps the tone into the dark window, so surface-inverse reads as a dark surface in every scheme — light, dark, and HC. In high-contrast variants the window is bypassed entirely (identity), so the color stays at its raw tone across all four schemes.

Use it for tooltips, code blocks, popovers with their own dark theme. Pair with #white for foreground text.

This is the canonical "I want this color to stay recognizable" pattern. The other mode: 'fixed' use is the entire accent system below.

Accent system (anchor pattern)

The load-bearing trick. Define a single fixed white anchor accent-surface-text, then derive every accent surface from it with a small relative tone offset and a numeric contrast under mode: 'fixed':

'accent-surface-text': { tone: 100, mode: 'fixed' },

'accent-surface':       { base: 'accent-surface-text', tone: '-1', contrast: [4.5, 7],   mode: 'fixed' },
'accent-surface-2':     { base: 'accent-surface-text', tone: '-1', contrast: [4.8, 7.5], mode: 'fixed' },
'accent-surface-3':     { base: 'accent-surface-text', tone: '-1', contrast: [5.2, 8],   mode: 'fixed' },
'accent-surface-hover': { base: 'accent-surface-text', tone: '-1', contrast: [6,   8.5], mode: 'fixed' },

Three things make this work:

• One anchor, one chain. All accent surfaces stay in the same hue family because they all derive from accent-surface-text.
• mode: 'fixed' keeps the brand recognizable. Without it, the dark-scheme tone inversion would turn the brand fill into a tone-inverted counterpart that may no longer read as the intended brand surface. Fixed remaps the tone into the dark window without inverting, so a tone: 52 brand color stays mid-toned in dark mode — still recognizably the same color.
• Numeric contrasts, not presets. 'AA' / 'AAA' would let the solver push the color far away from its anchor in dark schemes, breaking the relationship between accent-surface and its neighbors. Numeric ratios make the darkening between accent-surface (4.5/7), -2 (4.8/7.5), -3 (5.2/8), and -hover (6/8.5) a tight, designed sequence — a stepped gradient rather than four solver-generated outliers.

The hover variant is a dedicated fixed token. Reusing accent-text (which is mode: 'auto' and inverts direction in dark) would break the hover feel.

Adaptive accent foregrounds

The opposite of the fills. Brand-colored foregrounds are anchored to surface, not accent-surface, with mode: 'auto' (default) and full saturation:

'accent-text':      { base: 'surface', tone: '-1', saturation: 1,      contrast: [6.4, 10] },
'accent-text-soft': { base: 'surface', tone: '-1', saturation: 1,      contrast: [4.5, 7]  },
'accent-icon':      { base: 'surface', tone: '-1', saturation: 0.9375, contrast: [3.2, 5]  },

Foregrounds need to stay readable on the surface they actually sit on — anchoring to the brand fill would only enforce contrast against that fill, leaving the dark-mode color washed out against the actual surface (e.g. SECONDARY button labels sit on surface, not on the brand fill). Anchoring to surface + mode: 'auto' lets the solver lift the tone in dark mode so the contrast floor holds in both schemes.

accent-text-soft shares the anchor and saturation but relaxes the contrast floor for a visibly less prominent secondary foreground (link base color, subdued labels). Critically, it stays mode: 'auto' — a fixed version would collapse to cr≈3 against the dark surface and break AA.

Brand-tinted disabled

Mirrors the neutral disabled pair from above but with higher saturation so the chip reads as a muted brand color rather than fully neutral grey. A disabled chip has no contrast requirement — it just needs to sit a hair off the surface and carry a faint label. That's a job for tone, not the contrast solver:

'accent-disabled-surface': {
  base: 'surface', tone: '+3', saturation: 0.5,
},
'accent-disabled-surface-text': {
  base: 'accent-disabled-surface', tone: '+18', saturation: 0.4,
  flip: false,
},

Tone offsets say what we mean directly: the chip is three tone steps off surface, the label eighteen steps off the chip — a deliberately low-contrast pair, no solver involved. Because tone is contrast-uniform, those steps look the same in light and dark, and mode: 'auto' (the default) keeps the relationship intact when the scheme inverts.

flip: false on the label is the safety rail. A relative tone: '+18' lands above the chip; if the chip is already near the top of the range (a light surface), +18 would overshoot 100. With flip on (the default), Glaze mirrors the offset to -18 so it reflects back into range — handy for contrast tokens, but here it would put the label on the wrong side of the chip. Turning flip off clamps to the boundary instead, keeping the label on the side you authored.

When a token genuinely needs the extreme — the lightest or darkest tone the scheme allows — reach for 'max' / 'min' rather than a large number or a contrast hack:

'card-floor':  { tone: 'min' }, // darkest tone (root, no base needed)
'card-ceil':   { tone: 'max' }, // lightest tone

'max' resolves to the scheme's highest authored tone (100) and 'min' to the lowest (0); neither needs a base. They flow through scheme mapping like any absolute tone, so under mode: 'auto' they invert in dark — 'max' is the lightest tone in light mode and, after inversion, the darkest in dark. Use mode: 'static' if you want the same extreme pinned across every scheme, or mode: 'fixed' to keep it on the same end without inverting. Either way: no magic numbers, no contrast floor standing in for "push it all the way".

These are inherited (no inherit: false), so each colored sibling theme automatically emits <theme>-accent-disabled-surface and <theme>-accent-disabled-surface-text. PRIMARY-style disabled buttons stay tinted with the active theme's hue (danger-tinted danger button, success-tinted success button), preserving brand identity even in the disabled state.

Per-color hue overrides (code highlighting)

The code-* tokens use absolute hue numbers regardless of the seed. Each is base: 'surface' with mode: 'auto', a per-token saturation, and a numeric contrast floor:

'code-comment': { base: 'surface', hue: 280,        saturation: 0.1, tone: '-1', contrast: [4.5, 7], inherit: false },
'code-keyword': { base: 'surface', hue: 348,        saturation: 1,   tone: '-1', contrast: [5, 7.5], inherit: false },
'code-string':  { base: 'surface', hue: SUCCESS_HUE, saturation: 1, tone: '-1', contrast: [4.5, 7], inherit: false },
// …code-punctuation, code-number, code-function, code-attribute follow the same shape

The canonical pattern for "I want a color from a different hue family but the same adaptive behavior". Absolute hue overrides the theme seed for a single color; everything else (contrast against surface, dark adaptation, HC tightening) still works. inherit: false because syntax highlighting is a default-only concern.

Loading-animation faces

A 3-step ramp using absolute tones with high saturation factors and tight numeric contrasts:

'loading-face-1': { base: 'surface', tone: 98, saturation: 0.3,  contrast: [1.04, 1.5], inherit: false },
'loading-face-2': { base: 'surface', tone: 91, saturation: 0.62, contrast: [1.24, 2.5], inherit: false },
'loading-face-3': { base: 'surface', tone: 79, saturation: 0.66, contrast: [1.75, 4],   inherit: false },

Combines absolute tone positioning (so the ramp is deterministic in light mode) with a numeric contrast floor (so the ramp still reads in dark and HC). The HC contrast jumps significantly (1.04 → 1.5, 1.24 → 2.5, 1.75 → 4) so the animation stays perceivable for low-vision users.

Shadows

Three sizes, all sharing bg: 'surface' and fg: 'surface-text', varying only intensity:

'shadow-sm': { type: 'shadow', bg: 'surface', fg: 'surface-text', intensity: 5,  inherit: false },
'shadow-md': { type: 'shadow', bg: 'surface', fg: 'surface-text', intensity: 10, inherit: false },
'shadow-lg': { type: 'shadow', bg: 'surface', fg: 'surface-text', intensity: 15, inherit: false },

Including fg matters: shadow strength scales with |l_bg − l_fg|, so anchoring fg to surface-text (which is anchored at the edge of the window) makes shadows automatically deeper in dark mode where the bg/fg gap is larger. All shadows are inherit: false — there's only one shadow system for the whole UI, and colored sibling themes don't carry their own.

For HC, pass intensity: [normal, hc] (e.g. [10, 20]) to deepen shadows in high-contrast mode. The full algorithm and tuning knobs are in api.md → Shadows.

Overlay (fixed opacity)

overlay: { tone: 10, opacity: 0.5, inherit: false },

The shortcut for one solid color with a fixed alpha — no shadow algorithm, no mix. opacity on a regular color attaches an alpha component to every variant. Use it for backdrops, scrims, modal overlays. (Combining opacity with contrast is not recommended — perceived lightness becomes unpredictable when alpha is fixed; Glaze emits a console.warn.)

Mixes for hover / tint

Reach for mix tokens when you want one color to "tint through" another:

hover: {
  type: 'mix', base: 'surface', target: 'accent-surface',
  value: 8, blend: 'transparent',
},
// hover → accent-surface with alpha = 0.08

tint: {
  type: 'mix', base: 'surface', target: 'accent-surface',
  value: 20,
},

• Transparent mix — the target color with controlled alpha. Useful for hover overlays.
• Opaque mix — solid blend of two colors. Good for subtle tints.

Choose space: 'okhsl' (default) for design tokens — perceptually uniform, consistent with the rest of Glaze. Choose space: 'srgb' to match what the browser would render with a plain CSS overlay. Mix colors support the same contrast prop as regular colors; the solver adjusts the mix ratio (opaque) or opacity (transparent) to meet the target.

Colored sibling themes via extend()

One shared TINTED_SURFACE_OVERRIDE, applied to every colored theme, with only the hue changing per status:

const TINTED_SURFACE_OVERRIDE: ColorMap = {
  surface: { tone: 96, saturation: 0.8 },
};

const primaryTheme = defaultTheme.extend({                       colors: TINTED_SURFACE_OVERRIDE });
const successTheme = defaultTheme.extend({ hue: SUCCESS_HUE,     colors: TINTED_SURFACE_OVERRIDE });
const dangerTheme  = defaultTheme.extend({ hue: DANGER_HUE,      colors: TINTED_SURFACE_OVERRIDE });
const warningTheme = defaultTheme.extend({ hue: WARNING_HUE,     colors: TINTED_SURFACE_OVERRIDE });
const noteTheme    = defaultTheme.extend({ hue: NOTE_HUE,        colors: TINTED_SURFACE_OVERRIDE });

Colored themes need a visibly tinted surface for status banners — saturation jumps from the neutral 0.11 (default theme) to 0.8. The inherit: false discipline pays off here: because most neutrals (surface-2, surface-3, border, placeholder, disabled-*, code-*, loading-*, shadow-*) are flagged default-only, each colored theme inherits only the accent + tinted surface chain and emits a small, focused token set.

primaryTheme keeps the default hue but gets the tinted surface — useful for places that want a brand-tinted banner without semantic status meaning.

Palette composition

Compose all themes into a palette so they can be exported as one token set:

const palette = glaze.palette({
  default: defaultTheme,
  primary: primaryTheme,
  success: successTheme,
  danger:  dangerTheme,
  warning: warningTheme,
  note:    noteTheme,
});

The default theme is conventionally exported unprefixed (its tokens land as #surface, #border); colored themes are prefixed with their name. See migration.md for the prefix map shape, alias patterns, and how to wire the resulting tokens into Tasty / CSS / framework-agnostic JSON.

High-contrast strategy

Glaze's high-contrast mode is opt-in per token: anywhere tone, contrast, intensity, or value accepts an HC pair, you can pass [normal, hc] to tighten the HC variant. The heuristic is to pair anything that's already contrast-driven:

• Text-against-surface contrasts ([9, 11], [4.5, 5.5], [6.4, 10]).
• The accent surface ladder ([4.5, 7] → [5.2, 8] → [6, 8.5]).
• The loading ramp's contrasts.
• Shadow intensity (e.g. intensity: [10, 20]).
• border tone (e.g. tone: ['-10', '-20']).

In HC the tone window is bypassed entirely — light HC and dark HC operate on the full [0, 100] range. That's why edge-anchored absolute tones like surface-text: { tone: 2 } reach close to black in light HC and close to white in dark HC, exactly what you want for maximum contrast.

Closing checklist

Before shipping a palette, verify:

• Every text token has an explicit contrast or an edge-anchored absolute tone.
• Every accent surface uses mode: 'fixed' + numeric contrast (not preset 'AA' / 'AAA').
• Every brand foreground (accent-text*, accent-icon) is anchored to surface, not to accent-surface.
• Every inherit: false is intentional — colored sibling themes only carry the tokens they actually need.
• HC pairs are present on every contrast-driven token, not just the strong ones.
• Shadow fg is set when you want shadows to deepen in dark mode.
• glaze.configure({ states, modes }) matches the global predefined states wired in your app's root.