--- language: "en" title: "API reference" canonical: "https://glaze.tenphi.me/reference/" source: "docs/reference/index.md" version: "3.1.0" index: true --- # 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](/schemes/), [Contrast solving](/contrast/), [Shadows and glows](/shadows-and-glows/), [Mixes and transparency](/mixes/), and [Tone and OKHST](/okhst/). ```ts 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. ## Reference pages | Page | Covers | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Themes](/reference/theme/) | `glaze()`, `fromHex` / `fromRgb` / `themeFrom`, theme properties and methods, `extend`, `resolve`, `export`. | | [Color definitions](/reference/color-definitions/) | The `ColorDef` union: regular, shadow, glow, and mix colors, every field, and a glow's HDR value. | | [Contrast and high contrast](/reference/contrast/) | `HCPair`, `ContrastSpec`, WCAG and APCA presets, high-contrast escalation, the manual contrast level. | | [Color tokens](/reference/color-tokens/) | Standalone `glaze.color()` tokens, their methods, and `glaze.colorFrom()`. | | [Palettes](/reference/palette/) | `glaze.palette()`, prefixes, collisions, the primary alias, `glaze.paletteFrom()`. | | [Output formats](/reference/output/) | Every output method and option, color formats, output modes, state aliases, `splitHue`, HDR output. | | [Configuration](/reference/configuration/) | `glaze.configure()` and every `GlazeConfig` field, per-instance overrides, validation, warnings. | | [Utilities](/reference/utilities/) | `glaze.format` / `glaze.formatHdr`, the HDR channel helpers, standalone `glaze.shadow` / `glaze.glow`, color math, tone utilities, the contrast solver, role helpers, guards, and the measuring module (`@tenphi/glaze/harness/measure`). | ## `glaze` and its statics `glaze` is the only value most code needs. It is a function with static methods attached: | Member | Returns | Documented in | | ----------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------ | | `glaze(hue, saturation?, config?)` | `GlazeTheme` | [Themes](/reference/theme/#glazehue-saturation-config) | | `glaze(seed, config?)` | `GlazeTheme` | [Themes](/reference/theme/#glazeseed-config) | | `glaze.fromHex(hex)` | `GlazeTheme` | [Themes](/reference/theme/#glazefromhexhex--glazefromrgbr-g-b) | | `glaze.fromRgb(r, g, b)` | `GlazeTheme` | [Themes](/reference/theme/#glazefromhexhex--glazefromrgbr-g-b) | | `glaze.themeFrom(data)` | `GlazeTheme` | [Themes](/reference/theme/#glazethemefromdata--glazefromdata) | | `glaze.from(data)` | `GlazeTheme` | Alias of `themeFrom` — [Themes](/reference/theme/#glazethemefromdata--glazefromdata) | | `glaze.palette(themes, options?)` | `GlazePalette` | [Palettes](/reference/palette/#glazepalettethemes-options) | | `glaze.paletteFrom(data)` | `GlazePalette` | [Palettes](/reference/palette/#paletteexportoverride--glazepalettefromdata) | | `glaze.color(input, config?)` | `GlazeColorToken` | [Color tokens](/reference/color-tokens/#glazecolorinput-config) | | `glaze.colorFrom(data)` | `GlazeColorToken` | [Color tokens](/reference/color-tokens/#tokenexportoverride--glazecolorfromdata) | | `glaze.shadow(input)` | `ResolvedColorVariant` | [Utilities](/reference/utilities/#glazeshadowinput--glazeglowinput) | | `glaze.glow(input)` | `ResolvedColorVariant` | [Utilities](/reference/utilities/#glazeshadowinput--glazeglowinput) | | `glaze.format(variant, format?, pastel?)` | `string` | [Utilities](/reference/utilities/#glazeformatvariant-format-pastel) | | `glaze.formatHdr(variant, hdrFormat?)` | `string \| undefined` | [Utilities](/reference/utilities/#glazeformathdrvariant-hdrformat) | | `glaze.configure(config)` | `void` | [Configuration](/reference/configuration/#glazeconfigureconfig) | | `glaze.getConfig()` | `GlazeConfigResolved` | [Configuration](/reference/configuration/#glazegetconfig) | | `glaze.resetConfig()` | `void` | [Configuration](/reference/configuration/#global-config) | | `glaze.isThemeExport(data)` | `data is GlazeThemeExport` | [Authoring snapshots](#authoring-snapshots-and-versioning) | | `glaze.isColorTokenExport(data)` | `data is GlazeColorTokenExport` | [Authoring snapshots](#authoring-snapshots-and-versioning) | | `glaze.isPaletteExport(data)` | `data is GlazePaletteExport` | [Authoring snapshots](#authoring-snapshots-and-versioning) | ## Instance methods | Instance | Members | Documented in | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `GlazeTheme` | `hue`, `saturation`, `darkHue`, `darkSaturation`, `getConfig`, `colors`, `color`, `remove`, `has`, `list`, `reset`, `extend`, `resolve`, `export` | [Themes](/reference/theme/#theme-methods) | | `GlazeTheme` output | `tokens`, `tasty`, `json`, `css`, `dtcg`, `dtcgResolver`, `tailwind` | [Output formats](/reference/output/) | | `GlazePalette` | `list`, `primary`, `theme`, `themes`, `export`, and the seven output methods | [Palettes](/reference/palette/#palette-members) | | `GlazeColorToken` | `resolve`, `token`, `tasty`, `json`, `css`, `dtcg`, `dtcgResolver`, `tailwind`, `export` | [Color tokens](/reference/color-tokens/#token-methods) | ## Named exports 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](/reference/utilities/#measuring-module). | Export | Kind | Documented in | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `glaze` | Function | This page | | `GLAZE_EXPORT_VERSION` | Constant (`2`) | [Authoring snapshots](#authoring-snapshots-and-versioning) | | `isThemeExport`, `isColorTokenExport`, `isPaletteExport` | Type guards (same functions as the `glaze.*` statics) | [Authoring snapshots](#authoring-snapshots-and-versioning) | | `assertNativeFormat`, `assertAllPastel` | Export guards | [Utilities](/reference/utilities/#export-guards); where they apply: [Color formats](/reference/output/#color-formats) (`assertNativeFormat`), [`splitHue` requirements](/reference/output/#requirements) (`assertAllPastel`) | | `findToneForContrast`, `findValueForMixContrast`, `resolveMinContrast`, `resolveContrastForMode`, `resolveContrastForLevel`, `resolveApcaTarget`, `apcaContrast` | Contrast solver functions | [Utilities](/reference/utilities/#contrast-solver) | | `APCA_PRESETS`, `APCA_HC_ENHANCEMENT`, `APCA_MAX_LC` | Contrast constants | [Utilities](/reference/utilities/#constants-and-types); presets in [Contrast and high contrast](/reference/contrast/#apca-presets) | | `normalizeRole`, `inferRoleFromName`, `roleToPolarity`, `oppositeRole` | Role helpers | [Utilities](/reference/utilities/#role-helpers) | | `toTone`, `fromTone`, `toneFromY`, `yFromTone`, `okhstToOkhsl`, `okhslToOkhst`, `variantToOkhsl`, `REF_EPS` | OKHST tone utilities | [Utilities](/reference/utilities/#okhst-tone-utilities); the model in [Tone and OKHST](/okhst/) | | `okhslToLinearSrgb`, `okhslToSrgb`, `okhslToOklab`, `oklabToOkhsl`, `srgbToOkhsl`, `hslToSrgb`, `okhslToOklch`, `cuspLightness`, `parseHex`, `parseHexAlpha`, `srgbToHex`, `relativeLuminanceFromLinearRgb`, `contrastRatioFromLuminance`, `gamutClampedLuminance`, `apcaLuminanceFromLinearRgb` | Color math | [Utilities](/reference/utilities/#color-math) | | `formatOkhsl`, `formatOkhst`, `formatRgb`, `formatHsl`, `formatOklch` | Format writers (0–1 scale) | [Utilities](/reference/utilities/#format-writers) | | `formatSrgb`, `formatSrgbLinear` | HDR writers: extended or linear sRGB channels, unclamped, as `color(srgb R G B)` / `color(srgb-linear R G B)` | [Utilities](/reference/utilities/#format-writers); the format: [Extended sRGB](/hdr/#extended-srgb) | | `hdrToSrgb`, `hdrToLinearSrgb` | HDR channels: a `ResolvedHdr` → extended or linear sRGB, unclamped | [Utilities](/reference/utilities/#hdrtosrgbhdr--hdrtolinearsrgbhdr) | ## Types All public types are exported with `import type`. | Area | Types | Documented in | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Theme | `GlazeTheme`, `GlazeThemeSeed`, `GlazeExtendOptions`, `GlazeThemeExport` | [Themes](/reference/theme/) | | Resolved values | `ResolvedColor`, `ResolvedColorVariant` | [Themes](/reference/theme/#themeresolve) | | HDR values | `ResolvedHdr`, `GlazeHdrFormat` | [Color definitions](/reference/color-definitions/#hdr-values-resolvedhdr), [Utilities](/reference/utilities/#glazeformathdrvariant-hdrformat), [Output formats](/reference/output/#hdr-output) | | Color definitions | `ColorDef`, `ColorMap`, `RegularColorDef`, `ShadowColorDef`, `GlowColorDef`, `MixColorDef`, `LightingTuning`, `ShadowTuning`, `GlowTuning` | [Color definitions](/reference/color-definitions/) | | Tone and adaptation | `ToneValue`, `RelativeValue`, `ExtremeValue`, `AdaptationMode` | [Color definitions](/reference/color-definitions/), [Configuration](/reference/configuration/) | | Roles | `Role`, `RoleInput`, `Polarity` | [Color definitions](/reference/color-definitions/), [Utilities](/reference/utilities/) | | Contrast | `HCPair`, `MinContrast`, `ContrastSpec`, `ContrastPreset`, `ApcaPreset` | [Contrast and high contrast](/reference/contrast/) | | Contrast solver | `ResolvedContrast`, `FindToneForContrastOptions`, `FindToneForContrastResult`, `FindValueForMixContrastOptions`, `FindValueForMixContrastResult` | [Utilities](/reference/utilities/) | | Configuration | `GlazeConfig`, `GlazeConfigOverride`, `GlazeConfigResolved`, `ToneWindow` | [Configuration](/reference/configuration/) | | Color values | `GlazeColorValue`, `HexColor`, `OkhslColor`, `OkhstColor`, `RgbColor`, `OklchColor` | [Color tokens](/reference/color-tokens/) | | Color tokens | `GlazeColorToken`, `GlazeColorInput`, `GlazeFromInput`, `GlazeColorOverrides`, `GlazeColorCssOptions`, `GlazeColorTailwindOptions`, `GlazeColorDtcgResult`, `GlazeColorDtcgResolverOptions`, `GlazeColorTokenExport`, `GlazeColorInputExport`, `GlazeColorOverridesExport` | [Color tokens](/reference/color-tokens/) | | Standalone shadow and glow | `GlazeLightingInput`, `GlazeShadowInput`, `GlazeGlowInput` | [Utilities](/reference/utilities/) | | Palette | `GlazePalette`, `GlazePaletteOptions`, `GlazePaletteExportOptions`, `GlazePaletteTastyOptions`, `GlazePaletteCssOptions`, `GlazePaletteExport` | [Palettes](/reference/palette/) | | Output options | `GlazeColorFormat`, `GlazeOutputModes`, `GlazeTokenOptions`, `GlazeTastyOptions`, `GlazeJsonOptions`, `GlazeCssOptions`, `GlazeCssResult`, `GlazeCssSchemeBlocks`, `GlazeTailwindOptions` | [Output formats](/reference/output/) | | DTCG | `GlazeDtcgOptions`, `GlazeDtcgResult`, `DtcgColorSpace`, `DtcgColorToken`, `DtcgColorValue`, `DtcgSrgbColorValue`, `DtcgOklchColorValue`, `DtcgDocument` | [Output formats](/reference/output/#dtcgoptions) | | DTCG HDR extension | `GlazeDtcgExtensions`, `GlazeDtcgHdr` | [Output formats](/reference/output/#dtcg-extensions) | | DTCG resolver | `GlazeDtcgResolverOptions`, `GlazeDtcgResolverContextNames`, `GlazeDtcgResolverDocument`, `DtcgResolverSet`, `DtcgResolverModifier`, `DtcgResolverRef`, `DtcgTokenTree` | [Output formats](/reference/output/#dtcgresolveroptions) | | `splitHue` planning | `HuePlan`, `HueDeclaration`, `ChannelCtx` | [Output formats](/reference/output/#planning-types) | | Snapshots | `GlazeExportKind`, `GlazeExportVersion` | [Authoring snapshots](#authoring-snapshots-and-versioning) | ## Conventions ### Scales Glaze mixes a few numeric scales. Which one applies depends on where a value is authored: | Value | Scale | Where | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Hue | 0–360 degrees | Everywhere: seeds, per-color `hue` / `darkHue`, resolved variants, value objects. | | Seed saturation | 0–100 | `glaze(hue, saturation)`, `GlazeThemeSeed.saturation` / `darkSaturation`, `theme.saturation`, the structured `glaze.color({ saturation })`, `GlazeColorOverrides.saturation`. | | Per-color saturation | 0–1, a factor of the seed | `RegularColorDef.saturation` / `darkSaturation`; `saturationFactor` / `darkSaturationFactor` on color tokens. With `from`, an explicit `saturation` is still a factor of the seed. | | Tone | 0–100 | Authored `tone`, tone deltas (`'+20'`). Shadow and glow `intensity` is a step in tones (0–100). | | Tone window endpoints | 0–100 OKHSL lightness, not tone | `lightTone` / `darkTone` `lo` and `hi`. The default `darkTone: [15, 95]` holds tones 9.25–95.9, so a tone-100 `auto` surface lands at tone 9.25 in dark. See [Tone windows](/reference/configuration/#tone-windows). | | Mix `value` | 0–100 | `MixColorDef.value` (0 = base, 100 = target). | | Resolved variant | `h` 0–360; `s`, `t`, `alpha` 0–1 | `ResolvedColorVariant`, the input to `glaze.format()`. Its optional `hdr` (`ResolvedHdr`) uses the same scales plus `exposure`. | | Headroom, exposure | Stops above SDR white; each stop doubles luminance. `headroom` 0–2. | `glowTuning.headroom` and a glow's `tuning.headroom`; `ResolvedHdr.exposure` and DTCG `exposure`. 1 stop past white is tone 121.98, 2 stops tone 144.34. | | HDR channels | Extended or linear sRGB, unclamped; `1` is SDR white. One stop above it is `1.3533` extended, `2` linear. | Extended: every exporter's HDR strings, DTCG `hdr.value`, `glaze.formatHdr()` by default, `hdrToSrgb`, `formatSrgb`. Linear: `glaze.formatHdr(v, 'srgb-linear')`, `hdrToLinearSrgb`, `formatSrgbLinear`. | | Value objects | `{ h, s, l }` and `{ h, s, t }`: `s`, `l`, `t` 0–1. `{ r, g, b }`: 0–255. `{ l, c, h }`: `L` and `C` 0–1, `H` degrees. | `from`, `glaze.color()`, `glaze.shadow()` / `glaze.glow()` inputs. | | Format writers and converters | `h` 0–360; `s`, `l`, `t` 0–1 | `formatOkhsl` … `formatOklch` and the color math functions. The format writers warn when they get 0–100 percentages (the pre-2.0 scale). | | Opacity, ratios | 0–1 | `opacity`, `darkDesaturation`, lighting `tint` / `reach` / `hueBleed`. | | Contrast level | 0–100, or `'auto'` | `contrastLevel`. | | sRGB channels | 0–255 | `glaze.fromRgb(r, g, b)`, `rgb()` output. | ### Scheme variant names 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](/reference/output/#scheme-variants). ### High-contrast pairs Fields that can differ in high contrast accept an `HCPair`: either a single value or a `[normal, highContrast]` tuple. ```ts type HCPair = 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](/reference/contrast/). ### Tone values 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](/reference/color-definitions/#tone-values) and, for what tone means, [Tone and OKHST](/okhst/). ## Authoring snapshots and versioning Every instance can be saved as a JSON-safe **authoring snapshot** — the definitions and a frozen config, not resolved colors — and restored later: | Export | Restore | Kind | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------- | | [`theme.export(override?)`](/reference/theme/#themeexportoverride) | [`glaze.themeFrom(data)`](/reference/theme/#glazethemefromdata--glazefromdata) | `'theme'` | | [`token.export(override?)`](/reference/color-tokens/#tokenexportoverride--glazecolorfromdata) | [`glaze.colorFrom(data)`](/reference/color-tokens/#tokenexportoverride--glazecolorfromdata) | `'color'` | | [`palette.export(override?)`](/reference/palette/#paletteexportoverride--glazepalettefromdata) | [`glaze.paletteFrom(data)`](/reference/palette/#paletteexportoverride--glazepalettefromdata) | `'palette'` | Resolved output (`tokens()`, `css()`, `json()`, …) is a different thing: it can't be restored. [Exporting and integration](/exporting/) explains when to use which. ### `kind` and `version` Every `.export()` writes two fields: * `kind` — `GlazeExportKind`: `'theme'`, `'color'`, or `'palette'`. * `version` — `GLAZE_EXPORT_VERSION`, currently `2` (`GlazeExportVersion` is its literal type). | Version | Written by | | ------- | ------------------------------------------------------------------------------------ | | `1` | Glaze 1.1–2.x. | | `2` | Glaze 3: shadow `intensity`, `fg`, and tuning changed meaning, and `glow` was added. | ### Restore checks `themeFrom`, `colorFrom`, and `paletteFrom` apply the same rules: | Snapshot | Result | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | No `kind` / no `version` (legacy or hand-written) | Accepted. | | `kind` doesn't match the restore function | Throws, e.g. `glaze.themeFrom: expected kind "theme", got "palette".` | | `version` not an integer ≥ 1 | Throws `… invalid "version" field — expected an integer >= 1 (got ).` | | `version` greater than `GLAZE_EXPORT_VERSION` | Throws `… unsupported export version (this library supports version 2). Upgrade @tenphi/glaze to load this snapshot.` | | `version: 1` theme or palette with shadow colors or a `shadowTuning` config | Throws (below). | | `version: 1` without shadows | Restores as before. | 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: ```text 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](/migration/#30--shadows-and-glows). ### Type guards `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: | Guard | `true` when | | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `isThemeExport(data)` | A plain object with `kind: 'theme'` or no `kind`, numeric `hue` and `saturation`, and no `form` or `themes` field. | | `isColorTokenExport(data)` | A plain object with `kind: 'color'` or no `kind`, and `form` of `'value'` or `'structured'`. | | `isPaletteExport(data)` | A plain object with `kind: 'palette'` or no `kind`, a `themes` object, no `form`, and no numeric `hue`. | 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. ```ts 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); ```