API reference

The reference is organized for lookup. This page maps every public export to the page that documents it, then covers the conventions the whole API shares and how authoring snapshots are versioned. For explanations and visuals, start with the concept pages: Light, dark, and high contrast, Contrast solving, Shadows and glows, Mixes and transparency, and Tone and OKHST.

import { glaze } from '@tenphi/glaze';
import type { GlazeTheme, ColorMap } from '@tenphi/glaze';

The package ships ESM and CommonJS with full type declarations and has no runtime dependencies.

glaze is the only value most code needs. It is a function with static methods attached:

Everything below is exported from '@tenphi/glaze' next to glaze. Apart from GLAZE_EXPORT_VERSION and the type guards, these are lower-level building blocks for advanced use and custom pipelines.

One subpath has its own exports: @tenphi/glaze/harness/measure, the measuring module behind the agent tools. See Measuring module.

All public types are exported with import type.

Glaze mixes a few numeric scales. Which one applies depends on where a value is authored:

Every resolved color has four variants: light, dark, lightContrast, and darkContrast. ResolvedColor and the results of tokens(), json(), css(), and dtcg() use these names as keys. tasty() keys the variants by state alias, tailwind() by selector, and dtcgResolver() uses the names as its default context names. See Scheme variants.

Fields that can differ in high contrast accept an HCPair<T>: either a single value or a [normal, highContrast] tuple.

type HCPair<T> = T | [T, T];

theme.colors({
  border: { base: 'surface', tone: ['-8', '-20'] },
  'surface-text': { base: 'surface', contrast: ['AA', 'AAA'] },
});

tone, contrast, shadow and glow intensity, and mix value accept pairs. The first entry drives light / dark, the second lightContrast / darkContrast. Under a manual contrastLevel the normal variants interpolate between the two. Full rules: Contrast and high contrast.

An authored tone is a number (absolute, 0–100), a signed string ('+N' / '-N', a tone delta from base), or 'max' / 'min' (the scheme’s tone extreme). See Color definitions and, for what tone means, Tone and OKHST.

Every instance can be saved as a JSON-safe authoring snapshot — the definitions and a frozen config, not resolved colors — and restored later:

Resolved output (tokens(), css(), json(), …) is a different thing: it can’t be restored. Exporting and integration explains when to use which.

Every .export() writes two fields:

• kind — GlazeExportKind: 'theme', 'color', or 'palette'.
• version — GLAZE_EXPORT_VERSION, currently 2 (GlazeExportVersion is its literal type).

themeFrom, colorFrom, and paletteFrom apply the same rules:

A version-1 theme snapshot with shadows is rejected because Glaze 3 changed what shadow intensity, fg, and tuning mean: restoring it would silently render every shadow differently. The error names the shadows and points to the upgrade guide:

glaze.themeFrom: this snapshot is export version 1 (Glaze 1.1–2) and contains
  shadow colors ("card-shadow").
Glaze 3 changed what shadow "intensity", "fg" and tuning mean, so it would
  restore with different shadows.
Re-author them as described in docs/migration.md ("3.0 — shadows and
  glows") and export again.

A theme entry inside a palette snapshot that has no version of its own is checked against the palette’s version. The check keys on version: 1, so a snapshot without any version (a hand-written one, or one from Glaze 1.0) is not checked: re-author its shadows before restoring it. How to re-author Glaze 2 shadows is in 3.0 — shadows and glows.

isThemeExport, isColorTokenExport, and isPaletteExport (also available as glaze.isThemeExport etc.) tell the snapshot kinds apart. They check kind when present and fall back to the shape for legacy snapshots:

A kind that names a different snapshot type always returns false. The guards check structure only; they don’t validate version or the color definitions.

import { glaze } from '@tenphi/glaze';

const data: unknown = JSON.parse(saved);

if (glaze.isPaletteExport(data)) glaze.paletteFrom(data);
else if (glaze.isThemeExport(data)) glaze.themeFrom(data);
else if (glaze.isColorTokenExport(data)) glaze.colorFrom(data);