@tenphi/glaze 0.15.1 → 0.16.1

package/dist/index.d.cts

@@ -2,19 +2,46 @@
 type LinearRgb = [number, number, number];
 type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
 type MinContrast$1 = number | ContrastPreset;
+/**
+ * Named APCA Lc floor presets (APCA Bronze Simple Mode conformance levels),
+ * independent of role. Use them anywhere an APCA target is accepted.
+ *
+ * | Preset        | Lc  | Use case                                             |
+ * | ------------- | --- | ---------------------------------------------------- |
+ * | `'preferred'` | 90  | Preferred body / column text                         |
+ * | `'body'`      | 75  | Minimum body / column text                           |
+ * | `'content'`   | 60  | Readable non-body content (~WCAG AA 4.5:1)           |
+ * | `'large'`     | 45  | Large/bold headlines; fine icons/outlines (~3:1)     |
+ * | `'non-text'`  | 30  | Solid icons/controls; placeholder/disabled text      |
+ * | `'min'`       | 15  | Dividers/decorative; APCA "point of invisibility"    |
+ */
+type ApcaPreset = 'preferred' | 'body' | 'content' | 'large' | 'non-text' | 'min';
+/**
+ * Resolve an APCA target — a raw Lc number (kept as-is) or an `ApcaPreset`
+ * keyword mapped to its Lc value. The magnitude is forced non-negative.
+ */
+declare function resolveApcaTarget(value: number | ApcaPreset): number;
 /** Metric + numeric target after resolving a `ContrastSpec` for a mode. */
 interface ResolvedContrast {
   metric: 'wcag' | 'apca';
   /** WCAG ratio (>= 1) or APCA Lc magnitude (0–106). */
   target: number;
+  /**
+   * APCA argument order: which side the resolved (candidate) color plays
+   * against the base. `'fg'` (default) → `apcaContrast(yCandidate, yBase)`;
+   * `'bg'` → `apcaContrast(yBase, yCandidate)`. Always `'fg'` for WCAG
+   * (symmetric, ignored).
+   */
+  polarity?: 'fg' | 'bg';
 }
 declare function resolveMinContrast(value: MinContrast$1): number;
 /**
  * Resolve a `ContrastSpec` (already selected from any outer HC pair) for a
  * given mode into `{ metric, target }`. Handles the inner metric HC pair and
- * preset resolution.
+ * preset resolution. `polarity` is passed through to the result for the APCA
+ * branch (it controls argument order in the solver); WCAG ignores it.
  */
-declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean): ResolvedContrast;
+declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg'): ResolvedContrast;
 /**
  * APCA lightness contrast (Lc), signed: positive for dark text on light bg,
  * negative for light text on dark bg. Inputs are screen luminances (0–1).
@@ -101,17 +128,30 @@ type MinContrast = number | ContrastPreset;
  *
  * - `number` / `ContrastPreset`: a WCAG ratio (bare form).
  * - `{ wcag }`: WCAG ratio or preset, optionally an HC pair.
- * - `{ apca }`: APCA Lc target (absolute value), optionally an HC pair.
+ * - `{ apca }`: APCA Lc target (absolute value or preset), optionally an HC pair.
  *
  * The `[normal, highContrast]` pair may live at the outer level
  * (`[4.5, 7]`, `[{ wcag: 4.5 }, { wcag: 7 }]`) or inside the metric
- * (`{ wcag: [4.5, 7] }`, `{ apca: [45, 60] }`).
+ * (`{ wcag: [4.5, 7] }`, `{ apca: [45, 60] }`, `{ apca: ['content', 'body'] }`).
  */
 type ContrastSpec = number | ContrastPreset | {
   wcag: HCPair<number | ContrastPreset>;
 } | {
-  apca: HCPair<number>;
+  apca: HCPair<number | ApcaPreset>;
 };
+/**
+ * The semantic role a color plays against its base, used to fix APCA contrast
+ * polarity (which side is the foreground vs the background). WCAG is
+ * symmetric, so role never changes WCAG results.
+ */
+type Role = 'text' | 'surface' | 'border';
+/**
+ * Any string accepted as a `role`. Canonical values plus aliases normalized by
+ * `normalizeRole` (see `roles.ts`): `surface` (bg/background/fill/canvas/
+ * paper/layer), `text` (fg/foreground/content/ink/label/stroke), `border`
+ * (divider/outline/separator/hairline/rule).
+ */
+type RoleInput = Role | 'bg' | 'background' | 'fill' | 'canvas' | 'paper' | 'layer' | 'fg' | 'foreground' | 'content' | 'ink' | 'label' | 'stroke' | 'divider' | 'outline' | 'separator' | 'hairline' | 'rule';
 type AdaptationMode = 'auto' | 'fixed' | 'static';
 /** A signed relative offset string, e.g. '+20' or '-15.5'. */
 type RelativeValue = `+${number}` | `-${number}`;
@@ -132,7 +172,7 @@ type ExtremeValue = 'max' | 'min';
  */
 type ToneValue = number | RelativeValue | ExtremeValue;
 /** Color format for output. */
-type GlazeColorFormat = 'okhsl' | 'rgb' | 'hsl' | 'oklch';
+type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';
 /**
  * Controls which scheme variants are generated in the export.
  * Light is always included (it's the default).
@@ -224,6 +264,16 @@ interface RegularColorDef {
    * @see GlazeConfig.pastel
    */
   pastel?: boolean;
+  /**
+   * Semantic role against `base`: how this color is used. Fixes APCA contrast
+   * polarity (the argument order in `apcaContrast`). WCAG is symmetric so it
+   * never affects WCAG results.
+   *
+   * Resolution: explicit `role` wins; else inferred from the color name when
+   * `inferRole` is enabled (default); else the opposite of the base's role;
+   * else defaults to `'text'` (foreground).
+   */
+  role?: RoleInput;
   /**
    * Whether this color is inherited by child themes created via `extend()`.
    * Default: true. Set to false to make this color local to the current theme.
@@ -327,6 +377,12 @@ interface MixColorDef {
    * @see GlazeConfig.pastel
    */
   pastel?: boolean;
+  /**
+   * Semantic role of the mixed result against `base`. Same semantics as
+   * `RegularColorDef.role` (fixes APCA polarity). Resolution and defaults
+   * are identical.
+   */
+  role?: RoleInput;
   /**
    * Whether this color is inherited by child themes created via `extend()`.
    * Default: true. Set to false to make this color local to the current theme.
@@ -420,6 +476,13 @@ interface GlazeConfig {
    * @default false
    */
   pastel?: boolean;
+  /**
+   * If true (default), infer a color's `role` from its name when no explicit
+   * `role` is set. Set to `false` to opt out of name-based inference (the
+   * base-opposite and default-foreground fallbacks still apply).
+   * @default true
+   */
+  inferRole?: boolean;
 }
 interface GlazeConfigResolved {
   lightTone: ToneWindow;
@@ -433,6 +496,7 @@ interface GlazeConfigResolved {
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
   pastel: boolean;
+  inferRole: boolean;
 }
 /**
  * Per-instance config override for `glaze.color()` and `glaze()` themes.
@@ -456,6 +520,11 @@ interface GlazeConfigOverride {
    * for the given lightness.
    */
   pastel?: boolean;
+  /**
+   * If true, infer a color's `role` from its name when no explicit `role` is
+   * set. Falls through to the live global at resolve time when omitted.
+   */
+  inferRole?: boolean;
   /**
    * Shadow tuning defaults. Only meaningful for themes; harmless on
    * standalone color tokens.
@@ -527,6 +596,14 @@ interface GlazeColorInput {
    * @see GlazeConfig.pastel
    */
   pastel?: boolean;
+  /**
+   * Semantic role against `base` / the literal seed: how this token is used.
+   * Fixes APCA contrast polarity. Same resolution chain as
+   * `RegularColorDef.role` (explicit → name inference → opposite of base →
+   * `'text'`). For standalone tokens the name is internal, so set `role`
+   * explicitly or rely on the base-opposite / foreground default.
+   */
+  role?: RoleInput;
 }
 /**
  * Any single-color input form accepted by the value-shorthand
@@ -634,6 +711,12 @@ interface GlazeColorOverrides {
    * @see GlazeConfig.pastel
    */
   pastel?: boolean;
+  /**
+   * Semantic role against `base` / the literal seed: how this token is used.
+   * Fixes APCA contrast polarity. Same resolution chain as
+   * `RegularColorDef.role`.
+   */
+  role?: RoleInput;
 }
 /**
  * Object input for `glaze.color()` that carries a raw color value plus
@@ -663,6 +746,11 @@ interface GlazeColorCssOptions {
    * `theme.css` default).
    */
   suffix?: string;
+  /**
+   * Emit hue as a separate custom property, referenced via `var()`.
+   * Requires `format: 'oklch'` and a pastel token. oklch + all-pastel only.
+   */
+  splitHue?: boolean;
 }
 /** Return type for `glaze.color()`. */
 interface GlazeColorToken {
@@ -680,6 +768,25 @@ interface GlazeColorToken {
   json(options?: GlazeJsonOptions): Record<string, string>;
   /** Export as CSS custom property declarations grouped by scheme variant. */
   css(options: GlazeColorCssOptions): GlazeCssResult;
+  /**
+   * Export as W3C DTCG color tokens (one per scheme variant, no color name
+   * key). Each entry is a full `{ $type: 'color', $value }` token.
+   * @see https://www.designtokens.org/
+   */
+  dtcg(options?: GlazeDtcgOptions): GlazeColorDtcgResult;
+  /**
+   * Export as a single W3C DTCG Resolver-Module document for this color,
+   * keyed by `name` across all scheme variants. `name` is required.
+   * @see https://www.designtokens.org/
+   */
+  dtcgResolver(options: GlazeColorDtcgResolverOptions): GlazeDtcgResolverDocument;
+  /**
+   * Export as a Tailwind CSS v4 `@theme` block (light baseline) plus dark /
+   * high-contrast overrides. Returns a single ready-to-paste CSS string.
+   * `name` is required (forms `--color-<name>`).
+   * @see https://tailwindcss.com/docs/theme
+   */
+  tailwind(options: GlazeColorTailwindOptions): string;
   /**
    * Serialize the token as a JSON-safe object. Captures the original
    * input value, overrides, and config so it can be rehydrated via
@@ -731,6 +838,7 @@ interface GlazeColorInputExport {
   contrast?: HCPair<ContrastSpec>;
   name?: string;
   pastel?: boolean;
+  role?: RoleInput;
 }
 /**
  * Serializable shape of `GlazeColorOverrides`. `base` is replaced by
@@ -748,6 +856,7 @@ interface GlazeColorOverridesExport {
   opacity?: number;
   name?: string;
   pastel?: boolean;
+  role?: RoleInput;
 }
 interface GlazeTheme {
   /** The hue seed (0–360). */
@@ -796,6 +905,27 @@ interface GlazeTheme {
   json(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
   /** Export as CSS custom property declarations. */
   css(options?: GlazeCssOptions): GlazeCssResult;
+  /**
+   * Export as W3C Design Tokens Format Module (2025.10) documents, one per
+   * scheme variant. Consumable by Figma, Tokens Studio, Style Dictionary,
+   * Terrazzo, and any DTCG-compatible tool.
+   * @see https://www.designtokens.org/
+   */
+  dtcg(options?: GlazeDtcgOptions): GlazeDtcgResult;
+  /**
+   * Export as a single W3C DTCG Resolver-Module document describing every
+   * scheme variant as one `sets` entry plus a single `scheme` modifier with a
+   * context per variant. Consumable by resolver tools such as Dispersa.
+   * @see https://www.designtokens.org/
+   */
+  dtcgResolver(options?: GlazeDtcgResolverOptions): GlazeDtcgResolverDocument;
+  /**
+   * Export as a Tailwind CSS v4 `@theme` block (light baseline) plus dark /
+   * high-contrast overrides under configurable selectors. Returns a single
+   * ready-to-paste CSS string.
+   * @see https://tailwindcss.com/docs/theme
+   */
+  tailwind(options?: GlazeTailwindOptions): string;
 }
 interface GlazeExtendOptions {
   hue?: number;
@@ -816,6 +946,16 @@ interface GlazeTokenOptions {
   modes?: GlazeOutputModes;
   /** Output color format. Default: 'okhsl'. */
   format?: GlazeColorFormat;
+  /**
+   * Emit hue as a separate custom property, referenced via `var()`.
+   * Requires `format: 'oklch'` and every color to be pastel.
+   */
+  splitHue?: boolean;
+  /**
+   * Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
+   * Palette export auto-derives this from the theme name.
+   */
+  name?: string;
 }
 interface GlazeJsonOptions {
   /** Override which scheme variants to include. */
@@ -828,6 +968,16 @@ interface GlazeCssOptions {
   format?: GlazeColorFormat;
   /** Suffix appended to each CSS custom property name. Default: '-color'. */
   suffix?: string;
+  /**
+   * Emit hue as a separate custom property, referenced via `var()`.
+   * Requires `format: 'oklch'` and every color to be pastel.
+   */
+  splitHue?: boolean;
+  /**
+   * Base name for the theme-level hue var (`--{name}-hue`). Default: `'theme'`.
+   * Palette export auto-derives this from the theme name.
+   */
+  name?: string;
 }
 /** CSS custom property declarations grouped by scheme variant. */
 interface GlazeCssResult {
@@ -836,6 +986,182 @@ interface GlazeCssResult {
   lightContrast: string;
   darkContrast: string;
 }
+/**
+ * Color space used for DTCG `$value` color objects.
+ * @see https://www.designtokens.org/
+ */
+type DtcgColorSpace = 'srgb' | 'oklch';
+/**
+ * A DTCG color `$value` in the sRGB color space: gamma sRGB components in
+ * 0–1 plus a 6-digit `hex` hint. Universally understood by Figma, Tokens
+ * Studio, Style Dictionary, and every DTCG reader.
+ */
+interface DtcgSrgbColorValue {
+  colorSpace: 'srgb';
+  components: [number, number, number];
+  hex: HexColor;
+  /** Opacity 0–1. Omitted when fully opaque (alpha = 1). */
+  alpha?: number;
+}
+/**
+ * A DTCG color `$value` in the OKLCH color space: `[L, C, H]` components
+ * (L/C: 0–1, H: degrees). Wide-gamut and Glaze-native; no `hex` is emitted.
+ */
+interface DtcgOklchColorValue {
+  colorSpace: 'oklch';
+  components: [number, number, number];
+  /** Opacity 0–1. Omitted when fully opaque (alpha = 1). */
+  alpha?: number;
+}
+/** A DTCG `$value` for a color token, in either supported color space. */
+type DtcgColorValue = DtcgSrgbColorValue | DtcgOklchColorValue;
+/**
+ * A single W3C DTCG color token: `{ $type: 'color', $value }`.
+ * `$description` is optional and not populated by Glaze today.
+ */
+interface DtcgColorToken {
+  $type: 'color';
+  $value: DtcgColorValue;
+  $description?: string;
+}
+/**
+ * A W3C Design Tokens Format Module (2025.10) token tree for one scheme.
+ * Glaze emits one document per scheme variant — the most tool-compatible
+ * convention (one file per Style Dictionary theme / Tokens Studio set /
+ * Figma variable mode).
+ */
+type DtcgDocument = Record<string, DtcgColorToken>;
+/** DTCG token documents grouped by scheme variant. Light is always present. */
+interface GlazeDtcgResult {
+  light: DtcgDocument;
+  dark?: DtcgDocument;
+  lightContrast?: DtcgDocument;
+  darkContrast?: DtcgDocument;
+}
+/** A single DTCG color token grouped by scheme variant (standalone tokens). */
+interface GlazeColorDtcgResult {
+  light: DtcgColorToken;
+  dark?: DtcgColorToken;
+  lightContrast?: DtcgColorToken;
+  darkContrast?: DtcgColorToken;
+}
+/** Options for `theme.dtcg()` / `palette.dtcg()`. */
+interface GlazeDtcgOptions {
+  /** Override which scheme variants to include. */
+  modes?: GlazeOutputModes;
+  /**
+   * DTCG color space. `'srgb'` (default) emits sRGB components plus a `hex`
+   * hint — universally understood (Figma, Tokens Studio). `'oklch'` emits
+   * OKLCH components with no hex — Glaze-native, wide-gamut.
+   */
+  colorSpace?: DtcgColorSpace;
+}
+/**
+ * A node in a DTCG Resolver-Module token tree: either a leaf color token or a
+ * nested group. A flat `DtcgDocument` (top-level color-name keys) is a valid
+ * shallow tree, so Glaze's per-scheme documents slot directly into
+ * `sets.<name>.sources` and `modifiers.<name>.contexts.<ctx>` entries.
+ */
+interface DtcgTokenTree {
+  [key: string]: DtcgColorToken | DtcgTokenTree;
+}
+/** A named set in a resolver document: a list of token-tree sources. */
+interface DtcgResolverSet {
+  sources: DtcgTokenTree[];
+}
+/**
+ * A named modifier (an axis such as `scheme`) in a resolver document.
+ * `default` names the context applied when no override is selected; `contexts`
+ * maps each context name to the token-tree overrides applied for it.
+ */
+interface DtcgResolverModifier {
+  default: string;
+  contexts: Record<string, DtcgTokenTree[]>;
+}
+/** A JSON-pointer `$ref` entry in a resolver document's `resolutionOrder`. */
+interface DtcgResolverRef {
+  $ref: string;
+}
+/**
+ * A W3C DTCG Resolver-Module document. Describes every scheme variant in a
+ * single file as `sets` (base token sources) plus `modifiers` (per-context
+ * overrides) composed in `resolutionOrder`. Consumable by resolver tools such
+ * as Dispersa.
+ * @see https://www.designtokens.org/
+ */
+interface GlazeDtcgResolverDocument {
+  version: string;
+  sets: Record<string, DtcgResolverSet>;
+  modifiers: Record<string, DtcgResolverModifier>;
+  resolutionOrder: DtcgResolverRef[];
+}
+/** Renaming of the four scheme variants as resolver-modifier context names. */
+interface GlazeDtcgResolverContextNames {
+  light?: string;
+  dark?: string;
+  lightContrast?: string;
+  darkContrast?: string;
+}
+/**
+ * Options for `theme.dtcgResolver()` / `palette.dtcgResolver()`. Extends
+ * `GlazeDtcgOptions` so `modes` + `colorSpace` pass through to the underlying
+ * per-scheme `dtcg()` build.
+ */
+interface GlazeDtcgResolverOptions extends GlazeDtcgOptions {
+  /** Name of the single set holding the default (light) token tree. Default `'base'`. */
+  setName?: string;
+  /**
+   * Name of the modifier describing the scheme axis. Default `'scheme'`
+   * (Glaze's term for the light / dark / high-contrast axis).
+   */
+  modifierName?: string;
+  /**
+   * Override the four context names emitted on the modifier. Defaults to the
+   * Glaze variant keys: `light` / `dark` / `lightContrast` / `darkContrast`.
+   */
+  contextNames?: GlazeDtcgResolverContextNames;
+  /** Resolver document version. Default `'2025.10'`. */
+  version?: string;
+}
+/** Options for `glaze.color().dtcgResolver()`. `name` is required. */
+interface GlazeColorDtcgResolverOptions extends GlazeDtcgResolverOptions {
+  /** Token name keying the color within each token tree. Required. */
+  name: string;
+}
+/** Options for `theme.tailwind()` / `palette.tailwind()`. */
+interface GlazeTailwindOptions {
+  /** Override which scheme variants to include. */
+  modes?: GlazeOutputModes;
+  /** Output color format. Default: 'oklch'. */
+  format?: GlazeColorFormat;
+  /**
+   * CSS custom property namespace, forming `--<namespace><name>`.
+   * Default: `'color-'` → `--color-surface`. (Tailwind v4's `--color-*`
+   * convention, which auto-generates `bg-*` / `text-*` / `border-*`.)
+   *
+   * Named `namespace` rather than `prefix` to avoid clashing with the
+   * palette theme-prefix option on `palette.tailwind()`.
+   */
+  namespace?: string;
+  /**
+   * Selector wrapping the dark-scheme overrides. Default: `'.dark'`.
+   * Pass a media query such as `'@media (prefers-color-scheme: dark)'` to
+   * drive dark mode from the OS preference instead of a class.
+   */
+  darkSelector?: string;
+  /**
+   * Selector wrapping the light high-contrast overrides. Default:
+   * `'.high-contrast'`. The combined dark + high-contrast overrides are
+   * emitted under `${darkSelector}${highContrastSelector}` (e.g.
+   * `.dark.high-contrast`).
+   */
+  highContrastSelector?: string;
+}
+/** Options for `glaze.color().tailwind()`. `name` is required. */
+interface GlazeColorTailwindOptions extends GlazeTailwindOptions {
+  /** Custom property base name (without leading `--`). Required. */
+  name: string;
+}
 /** Options for `glaze.palette()` creation. */
 interface GlazePaletteOptions {
   /**
@@ -867,6 +1193,11 @@ interface GlazePaletteExportOptions {
    * When omitted, inherits the palette-level `primary`.
    */
   primary?: string | false;
+  /**
+   * Emit hue as a separate custom property, referenced via `var()`.
+   * Requires `format: 'oklch'` and every color to be pastel.
+   */
+  splitHue?: boolean;
 }
 interface GlazePalette {
   /**
@@ -894,6 +1225,25 @@ interface GlazePalette {
   }): Record<string, Record<string, Record<string, string>>>;
   /** Export all themes as CSS custom property declarations. */
   css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
+  /**
+   * Export all themes as W3C DTCG documents, one per scheme variant.
+   * Prefix defaults to `true`. Inherits the palette-level `primary`.
+   * @see https://www.designtokens.org/
+   */
+  dtcg(options?: GlazeDtcgOptions & GlazePaletteExportOptions): GlazeDtcgResult;
+  /**
+   * Export all themes as a single W3C DTCG Resolver-Module document. Prefix
+   * defaults to `true`. Inherits the palette-level `primary`.
+   * @see https://www.designtokens.org/
+   */
+  dtcgResolver(options?: GlazeDtcgResolverOptions & GlazePaletteExportOptions): GlazeDtcgResolverDocument;
+  /**
+   * Export all themes as a Tailwind CSS v4 `@theme` block plus dark /
+   * high-contrast overrides. Returns a single ready-to-paste CSS string.
+   * Prefix defaults to `true`.
+   * @see https://tailwindcss.com/docs/theme
+   */
+  tailwind(options?: GlazeTailwindOptions & GlazePaletteExportOptions): string;
 }
 //#endregion
 //#region src/glaze.d.ts
@@ -934,6 +1284,82 @@ declare namespace glaze {
   var resetConfig: () => void;
 }
 //#endregion
+//#region src/channels.d.ts
+interface HueDeclaration {
+  prop: string;
+  value: string;
+}
+interface HuePlan {
+  /** CSS `var()` reference spliced into `oklch(L C <hueVar>)`. */
+  hueVar: string;
+  /** When true, emit a full inline color (shadow/mix/achromatic). */
+  inline: boolean;
+  /** Scheme-independent `--*-hue` declarations for this color. */
+  declarations: HueDeclaration[];
+}
+interface ChannelCtx {
+  seedHue: number;
+  /** Theme-level hue var base name (without `--` / `-hue`). */
+  baseName: string;
+  /** Token / custom-property name prefix used for hue var naming (`brand-` etc.). */
+  prefix: string;
+  defs: ColorMap;
+  mode: 'theme' | 'standalone';
+  /** Standalone: resolved hue from the primary variant (scheme-independent). */
+  resolvedHue?: number;
+  /**
+   * When false, hue declarations are not emitted (the pass only references
+   * hue vars already declared by a sibling pass). Used by palette primary
+   * unprefixed aliases so they reference the themed `--{themeName}-*-hue`
+   * vars without re-declaring (and colliding with) other themes' base vars.
+   * Defaults to true.
+   */
+  emitDeclarations?: boolean;
+}
+//#endregion
+//#region src/format-guard.d.ts
+/**
+ * Throw when a non-native Glaze color space is requested for an export that
+ * emits raw CSS or non-Tasty token maps.
+ */
+declare function assertNativeFormat(format: GlazeColorFormat | undefined, method: string): void;
+/**
+ * Throw when `splitHue` is enabled but any exported color is not pastel.
+ * Hue rotation is only clip-free when chroma is bounded by the hue-independent
+ * safe chroma (`computeSafeChromaOKLCH`).
+ */
+declare function assertAllPastel(resolved: Map<string, ResolvedColor>, modes: Required<GlazeOutputModes>): void;
+//#endregion
+//#region src/roles.d.ts
+/**
+ * Normalize a `RoleInput` (canonical value or alias) into a canonical `Role`.
+ * Returns `undefined` for unrecognized strings so callers can fall through to
+ * the next step of the resolution chain.
+ */
+declare function normalizeRole(input: RoleInput | undefined): Role | undefined;
+/**
+ * Infer a `Role` from a color name by matching its tokens against the role
+ * keyword sets. When multiple tokens match, the **last** recognized token
+ * wins (so `button-text` → `text`, `input-bg` → `surface`, `card-border` →
+ * `border`). Returns `undefined` when no token matches.
+ */
+declare function inferRoleFromName(name: string): Role | undefined;
+/** APCA argument order: which side the resolved color plays. */
+type Polarity = 'fg' | 'bg';
+/**
+ * Map a role to its APCA polarity. `text` and `border` are foreground spots
+ * against their base (the candidate is the text argument); `surface` is the
+ * background (the base is the text argument).
+ */
+declare function roleToPolarity(role: Role): Polarity;
+/**
+ * The opposite role of `role`, used when a color with no explicit role and no
+ * inferable name depends on a base: the dependent color plays the opposite
+ * role of its base. `surface` ↔ `text`; `border` is treated as a foreground
+ * spot, so its opposite is `surface`.
+ */
+declare function oppositeRole(role: Role): Role;
+//#endregion
 //#region src/okhst.d.ts
 /**
  * Reference eps for the OKHST color space. WCAG 2 contrast is
@@ -1080,6 +1506,14 @@ declare function parseHexAlpha(hex: string): {
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
 declare function formatOkhsl(h: number, s: number, l: number, pastel?: boolean): string;
+/**
+ * Format OKHST values as a CSS `okhst(H S% T%)` string.
+ * h: 0–360, s: 0–100, t: 0–100 (percentage scale for s and t).
+ *
+ * Pastel recompute matches `formatOkhsl`: convert via OKLab so external
+ * parsers that only understand non-pastel OKHST render identically.
+ */
+declare function formatOkhst(h: number, s: number, t: number, pastel?: boolean): string;
 /**
  * Format OKHSL values as a CSS `rgb(R G B)` string.
  * Uses 2 decimal places to avoid 8-bit quantization contrast loss.
@@ -1096,6 +1530,18 @@ declare function formatHsl(h: number, s: number, l: number, pastel?: boolean): s
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
 declare function formatOklch(h: number, s: number, l: number, pastel?: boolean): string;
+/**
+ * Convert gamma-encoded sRGB channels (0–1) to a 6-digit lowercase hex
+ * string (`#rrggbb`). Channels are clamped to [0,1] and rounded to 8-bit.
+ * Alpha is not encoded here — DTCG carries it as a separate `alpha` field.
+ */
+declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
+/**
+ * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLCH components `[L, C, H]`.
+ * L: 0–1, C: 0–~0.4 (chroma), H: 0–360 (hue). Shared by `formatOklch` and
+ * the DTCG `oklch` colorSpace exporter so the two never drift apart.
+ */
+declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-export { type AdaptationMode, 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, REF_EPS, type RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ResolvedContrast, type RgbColor, type ShadowColorDef, type ShadowTuning, type ToneValue, type ToneWindow, apcaContrast, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveContrastForMode, resolveMinContrast, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+export { type AdaptationMode, type ApcaPreset, type ChannelCtx, type ColorDef, type ColorMap, type ContrastPreset, type ContrastSpec, type DtcgColorSpace, type DtcgColorToken, type DtcgColorValue, type DtcgDocument, type DtcgOklchColorValue, type DtcgResolverModifier, type DtcgResolverRef, type DtcgResolverSet, type DtcgSrgbColorValue, type DtcgTokenTree, type ExtremeValue, type FindToneForContrastOptions, type FindToneForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorDtcgResolverOptions, type GlazeColorDtcgResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorTailwindOptions, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, type GlazeConfig, type GlazeConfigOverride, type GlazeConfigResolved, type GlazeCssOptions, type GlazeCssResult, type GlazeDtcgOptions, type GlazeDtcgResolverContextNames, type GlazeDtcgResolverDocument, type GlazeDtcgResolverOptions, type GlazeDtcgResult, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeTokenOptions, type HCPair, type HexColor, type HueDeclaration, type HuePlan, 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, assertAllPastel, assertNativeFormat, contrastRatioFromLuminance, cuspLightness, findToneForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOkhst, formatOklch, formatRgb, fromTone, gamutClampedLuminance, glaze, hslToSrgb, inferRoleFromName, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.cts.map