@tenphi/glaze 0.0.0-snapshot.60e8979 → 0.0.0-snapshot.63c08ea

package/dist/index.d.mts

@@ -1,48 +1,113 @@
 //#region src/contrast-solver.d.ts
-/**
- * OKHSL Contrast Solver
- *
- * Finds the closest OKHSL lightness that satisfies a WCAG 2 contrast target
- * against a base color. Used by glaze when resolving dependent colors
- * with `contrast`.
- */
 type LinearRgb = [number, number, number];
 type ContrastPreset = 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
 type MinContrast$1 = number | ContrastPreset;
-interface FindLightnessForContrastOptions {
+/**
+ * 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';
+declare const APCA_PRESETS: Record<ApcaPreset, number>;
+/**
+ * APCA-W3 "Enhanced Level" delta added to a bare APCA target in high-contrast
+ * mode when no explicit HC value is provided (analogous to WCAG AAA over AA).
+ * Only applied when neither the outer `contrast` pair nor the inner `apca`
+ * pair carries an explicit HC entry.
+ */
+declare const APCA_HC_ENHANCEMENT = 15;
+/** Upper bound for an APCA Lc target after HC enhancement. */
+declare const APCA_MAX_LC = 106;
+/**
+ * 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. `polarity` is passed through to the result for the APCA
+ * branch (it controls argument order in the solver); WCAG ignores it.
+ *
+ * `outerExplicitHC` indicates whether the caller selected this `spec` from an
+ * explicit high-contrast entry of the outer `contrast` pair. Together with the
+ * inner metric pair, it decides whether the HC auto-enhancement fires:
+ *  - APCA: +15 Lc "Enhanced Level" boost when neither level is explicit.
+ *  - WCAG: AA → AAA / AA-large → AAA-large promotion (SC 1.4.3 → 1.4.6) when
+ *    neither level is explicit. AAA-family presets and bare numbers are left
+ *    unchanged (AAA is the top WCAG tier).
+ * Defaults to `false` (correct for direct callers, which pass a single
+ * selected spec rather than an outer pair).
+ */
+declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg', outerExplicitHC?: boolean): 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).
+ */
+declare function apcaContrast(yText: number, yBg: number): number;
+interface FindToneForContrastOptions {
   /** Hue of the candidate color (0–360). */
   hue: number;
   /** Saturation of the candidate color (0–1). */
   saturation: number;
-  /** Preferred lightness of the candidate (0–1). */
-  preferredLightness: number;
-  /** Base/reference color as linear sRGB (channels may be outside 0–1 before clamp). */
-  baseLinearRgb: [number, number, number];
-  /** WCAG contrast ratio target floor. */
-  contrast: MinContrast$1;
-  /** Search bounds for lightness. Default: [0, 1]. */
-  lightnessRange?: [number, number];
+  /** Preferred tone of the candidate (0–1). */
+  preferredTone: number;
+  /** Base/reference color as linear sRGB. */
+  baseLinearRgb: LinearRgb;
+  /** Resolved contrast floor (metric + target). */
+  contrast: ResolvedContrast;
+  /** Search bounds for tone. Default: [0, 1]. */
+  toneRange?: [number, number];
   /** Convergence threshold. Default: 1e-4. */
   epsilon?: number;
-  /** Maximum binary-search iterations per branch. Default: 14. */
+  /** Maximum binary-search iterations per branch. Default: 18. */
   maxIterations?: number;
+  /** Preferred search direction before auto-flip is considered. */
+  initialDirection?: 'lighter' | 'darker';
+  /** Auto-flip tone direction when contrast can't be met. Default: false. */
+  flip?: boolean;
+  /** Use the hue-independent "safe" chroma boundary. Default: false. */
+  pastel?: boolean;
 }
-interface FindLightnessForContrastResult {
-  /** Chosen lightness in 0–1. */
-  lightness: number;
-  /** Achieved WCAG contrast ratio. */
+interface FindToneForContrastResult {
+  /** Chosen tone in 0–1. */
+  tone: number;
+  /** Achieved score (WCAG ratio or APCA Lc magnitude). */
   contrast: number;
   /** Whether the target was reached. */
   met: boolean;
   /** Which branch was selected. */
   branch: 'lighter' | 'darker' | 'preferred';
+  /** Whether the result auto-flipped to the opposite direction. */
+  flipped?: boolean;
 }
-declare function resolveMinContrast(value: MinContrast$1): number;
 /**
- * Find the OKHSL lightness that satisfies a WCAG 2 contrast target
- * against a base color, staying as close to `preferredLightness` as possible.
+ * Find the tone that satisfies a contrast floor against a base color,
+ * staying as close to `preferredTone` as possible.
  */
-declare function findLightnessForContrast(options: FindLightnessForContrastOptions): FindLightnessForContrastResult;
+declare function findToneForContrast(options: FindToneForContrastOptions): FindToneForContrastResult;
 interface FindValueForMixContrastOptions {
   /** Preferred mix parameter (0–1). */
   preferredValue: number;
@@ -50,42 +115,84 @@ interface FindValueForMixContrastOptions {
   baseLinearRgb: LinearRgb;
   /** Target color as linear sRGB. */
   targetLinearRgb: LinearRgb;
-  /** WCAG contrast target. */
-  contrast: MinContrast$1;
-  /**
-   * Compute the luminance of the mixed color at parameter t.
-   * For opaque: luminance of OKHSL-interpolated color.
-   * For transparent: luminance of alpha-composited color over base.
-   */
+  /** Resolved contrast floor (metric + target). */
+  contrast: ResolvedContrast;
+  /** Compute the luminance of the mixed color at parameter t. */
   luminanceAtValue: (t: number) => number;
   /** Convergence threshold. Default: 1e-4. */
   epsilon?: number;
   /** Maximum binary-search iterations per branch. Default: 20. */
   maxIterations?: number;
+  /** Auto-flip mix direction when contrast can't be met. Default: false. */
+  flip?: boolean;
 }
 interface FindValueForMixContrastResult {
-  /** Chosen mix parameter (0–1). */
   value: number;
-  /** Achieved WCAG contrast ratio. */
   contrast: number;
-  /** Whether the target was reached. */
   met: boolean;
+  flipped?: boolean;
 }
 /**
- * Find the mix parameter (ratio or opacity) that satisfies a WCAG 2 contrast
- * target against a base color, staying as close to `preferredValue` as possible.
+ * Find the mix parameter (ratio or opacity) that satisfies a contrast floor
+ * against a base color, staying as close to `preferredValue` as possible.
  */
 declare function findValueForMixContrast(options: FindValueForMixContrastOptions): FindValueForMixContrastResult;
 //#endregion
 //#region src/types.d.ts
 /** A value or [normal, high-contrast] pair. */
 type HCPair<T> = T | [T, T];
+/** Bare WCAG contrast target: a ratio number or a named preset. */
 type MinContrast = number | ContrastPreset;
+/**
+ * A contrast floor with a pluggable metric.
+ *
+ * - `number` / `ContrastPreset`: a WCAG ratio (bare form).
+ * - `{ wcag }`: WCAG ratio or preset, 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] }`, `{ apca: ['content', 'body'] }`).
+ */
+type ContrastSpec = number | ContrastPreset | {
+  wcag: HCPair<number | ContrastPreset>;
+} | {
+  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}`;
+/**
+ * Force a color to a tone extreme:
+ * - `'max'`: the highest tone in the active scheme range/window.
+ * - `'min'`: the lowest tone.
+ *
+ * Under `mode: 'auto'` the extreme inverts in the dark scheme (so `'max'`
+ * tracks the inversion and becomes the darkest tone). No `base` required.
+ */
+type ExtremeValue = 'max' | 'min';
+/**
+ * A tone value as authored on a color.
+ * - Number: absolute tone (0–100).
+ * - `'+N'` / `'-N'`: relative to the base's tone (requires `base`).
+ * - `'max'` / `'min'`: forced to the scheme's tone extreme (no base needed).
+ */
+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).
@@ -104,13 +211,35 @@ interface OkhslColor {
   s: number;
   l: number;
 }
+/**
+ * Direct OKHST color input — OKHSL with the lightness axis replaced by the
+ * contrast-uniform tone axis. `h`: 0–360, `s`: 0–1, `t`: 0–1 (tone).
+ */
+interface OkhstColor {
+  h: number;
+  s: number;
+  t: number;
+}
+/** sRGB components in 0–255 (value-shorthand object form). */
+interface RgbColor {
+  r: number;
+  g: number;
+  b: number;
+}
+/** OKLCh components matching CSS `oklch(L C H)` (L/C: 0–1, H: degrees). */
+interface OklchColor {
+  l: number;
+  c: number;
+  h: number;
+}
 interface RegularColorDef {
   /**
-   * Lightness value (0–100).
-   * - Number: absolute lightness.
-   * - String ('+N' / '-N'): relative to base color's lightness (requires `base`).
+   * Tone value (0–100, contrast-uniform — see `docs/okhst.md`).
+   * - Number: absolute tone.
+   * - String ('+N' / '-N'): relative to base color's tone (requires `base`).
+   * - `'max'` / `'min'`: force to the scheme's tone extreme (no base needed).
    */
-  lightness?: HCPair<number | RelativeValue>;
+  tone?: HCPair<ToneValue>;
   /** Saturation factor applied to the seed saturation (0–1, default: 1). */
   saturation?: number;
   /**
@@ -121,18 +250,55 @@ interface RegularColorDef {
   hue?: number | RelativeValue;
   /** Name of another color in the same theme (dependent color). */
   base?: string;
-  /** WCAG contrast ratio floor against the base color. */
-  contrast?: HCPair<MinContrast>;
+  /**
+   * Contrast floor against the base color. A bare number/preset is WCAG;
+   * use `{ wcag }` / `{ apca }` to pick the metric. Accepts an HC pair.
+   */
+  contrast?: HCPair<ContrastSpec>;
   /** Adaptation mode. Default: 'auto'. */
   mode?: AdaptationMode;
+  /**
+   * Whether to flip out-of-bounds results to the opposite side instead of
+   * clamping to the extreme. Affects both:
+   * - relative `tone`: when `base ± delta` exceeds `[0, 100]`, mirror the
+   *   delta to the other side of the base.
+   * - `contrast`: when the requested direction can't meet the floor, try the
+   *   opposite side (same as the global `autoFlip`).
+   *
+   * Defaults to the global `autoFlip` config (default `true`). Set `false`
+   * to clamp instead.
+   */
+  autoFlip?: boolean;
   /**
    * Fixed opacity (0–1).
    * Output includes alpha in the CSS value.
    * Does not affect contrast resolution — a semi-transparent color
-   * has no fixed perceived lightness, so `contrast` and `opacity`
+   * has no fixed perceived tone, so `contrast` and `opacity`
    * should not be combined (a console.warn is emitted).
    */
   opacity?: number;
+  /**
+   * Per-color override for the hue-independent "safe" chroma limit used in
+   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
+   * Falls through to the global / per-theme `pastel` config when omitted.
+   * @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.
+   */
+  inherit?: boolean;
 }
 /** Shadow tuning knobs. All values use the 0–1 scale (OKHSL). */
 interface ShadowTuning {
@@ -177,6 +343,18 @@ interface ShadowColorDef {
   intensity: HCPair<number>;
   /** Override default tuning. Merged field-by-field with global `shadowTuning`. */
   tuning?: ShadowTuning;
+  /**
+   * Per-color override for the hue-independent "safe" chroma limit used in
+   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
+   * Falls through to the global / per-theme `pastel` config when omitted.
+   * @see GlazeConfig.pastel
+   */
+  pastel?: boolean;
+  /**
+   * 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.
+   */
+  inherit?: boolean;
 }
 interface MixColorDef {
   type: 'mix';
@@ -205,25 +383,56 @@ interface MixColorDef {
    */
   space?: 'okhsl' | 'srgb';
   /**
-   * Minimum WCAG contrast between the base and the resulting color.
+   * Minimum contrast between the base and the resulting color.
    * In 'opaque' mode, adjusts the mix ratio to meet contrast.
    * In 'transparent' mode, adjusts opacity to meet contrast against the composite.
-   * Supports [normal, highContrast] pair.
+   * A bare number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the
+   * metric. Supports [normal, highContrast] pair.
+   */
+  contrast?: HCPair<ContrastSpec>;
+  /**
+   * Per-color override for the hue-independent "safe" chroma limit used in
+   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
+   * Falls through to the global / per-theme `pastel` config when omitted.
+   * @see GlazeConfig.pastel
    */
-  contrast?: HCPair<MinContrast>;
+  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.
+   */
+  inherit?: boolean;
 }
 type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 type ColorMap = Record<string, ColorDef>;
-/** Resolved color for a single scheme variant. */
+/**
+ * Resolved color for a single scheme variant.
+ *
+ * Stored in OKHST: `h` / `s` are OKHSL hue/saturation, `t` is the canonical
+ * contrast-uniform tone (0–1, reference eps). Convert to OKHSL lightness via
+ * `variantToOkhsl` at the rendering / luminance edges.
+ */
 interface ResolvedColorVariant {
   /** OKHSL hue (0–360). */
   h: number;
   /** OKHSL saturation (0–1). */
   s: number;
-  /** OKHSL lightness (0–1). */
-  l: number;
+  /** Canonical tone (0–1, reference eps). */
+  t: number;
   /** Opacity (0–1). Default: 1. */
   alpha: number;
+  /**
+   * Effective `pastel` flag used while resolving this variant (author def or
+   * config fallback). Carried on the variant so output formatting matches the
+   * gamut mapping applied during resolution.
+   */
+  pastel?: boolean;
 }
 /** Fully resolved color across all scheme variants. */
 interface ResolvedColor {
@@ -235,21 +444,32 @@ interface ResolvedColor {
   /** Adaptation mode. Present only for regular colors, omitted for shadows. */
   mode?: AdaptationMode;
 }
+/**
+ * A scheme tone window.
+ * - `[lo, hi]`: OKHSL-lightness endpoints (0–100) the authored tone is
+ *   remapped into, using the reference eps `0.05`. The common form.
+ * - `{ lo, hi, eps }`: same, with an explicit render curvature `eps`
+ *   (advanced — most palettes never need this).
+ * - `false`: disable clamping (full range `[0, 100]` at the reference eps).
+ *   This removes the *boundaries*, not the tone curve.
+ */
+type ToneWindow = false | [number, number] | {
+  lo: number;
+  hi: number;
+  eps: number;
+};
 interface GlazeConfig {
-  /** Light scheme lightness window [lo, hi]. Default: [10, 100]. */
-  lightLightness?: [number, number];
-  /** Dark scheme lightness window [lo, hi]. Default: [15, 95]. */
-  darkLightness?: [number, number];
+  /** Light scheme tone window — `[lo, hi]` (default `[10, 100]`), `{ lo, hi, eps }` for advanced eps tuning, or `false` to disable clamping. */
+  lightTone?: ToneWindow;
+  /** Dark scheme tone window — `[lo, hi]` (default `[15, 95]`), `{ lo, hi, eps }`, or `false` to disable clamping. */
+  darkTone?: ToneWindow;
   /** Saturation reduction factor for dark scheme (0–1). Default: 0.1. */
   darkDesaturation?: number;
   /**
-   * Möbius beta for dark auto-inversion (0–1).
-   * Lower values expand subtle near-white distinctions in dark mode.
-   * Set to 1 for linear (legacy) behavior. Default: 0.5.
-   * Accepts [normal, highContrast] pair for separate HC tuning.
+   * State alias names for Tasty token export. Default to media-query states
+   * (`'@media(prefers-color-scheme: dark)'` / `'@media(prefers-contrast: more)'`)
+   * so tokens react to the OS preference without registering custom states.
    */
-  darkCurve?: HCPair<number>;
-  /** State alias names for token export. */
   states?: {
     dark?: string;
     highContrast?: string;
@@ -258,42 +478,303 @@ interface GlazeConfig {
   modes?: GlazeOutputModes;
   /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
   shadowTuning?: ShadowTuning;
+  /**
+   * Automatically flip tone direction when contrast can't be met.
+   *
+   * When enabled (default `true`), the solver searches the requested
+   * tone direction first. If that direction can't reach the target,
+   * it tries the opposite direction and uses it when it passes. If neither
+   * side passes, the tone is pinned to the requested-direction
+   * extreme and a warning is emitted.
+   *
+   * Set to `false` for strict "no flip" behavior. The opposite
+   * direction is never considered: if the requested direction can't
+   * meet the target, the tone is pinned to its extreme (never
+   * falls back to the originally requested tone).
+   */
+  autoFlip?: boolean;
+  /**
+   * If true, uses a hue-independent "safe" chroma limit across all colors
+   * so that scaling saturation never exceeds the sRGB boundary at any hue
+   * for the given lightness.
+   * @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 {
-  lightLightness: [number, number];
-  darkLightness: [number, number];
+  lightTone: ToneWindow;
+  darkTone: ToneWindow;
   darkDesaturation: number;
-  darkCurve: HCPair<number>;
   states: {
     dark: string;
     highContrast: string;
   };
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
+  autoFlip: boolean;
+  pastel: boolean;
+  inferRole: boolean;
+}
+/**
+ * Per-instance config override for `glaze.color()` and `glaze()` themes.
+ * Fields that are set take priority over the live global config. Fields
+ * that are omitted fall through to the live global at resolve time.
+ *
+ * `false` for a tone window disables clamping (full range at reference eps).
+ */
+interface GlazeConfigOverride {
+  /** Light scheme tone window, or `false` to disable clamping. */
+  lightTone?: ToneWindow;
+  /** Dark scheme tone window, or `false` to disable clamping. */
+  darkTone?: ToneWindow;
+  /** Saturation reduction factor for dark scheme (0–1). */
+  darkDesaturation?: number;
+  /** Whether to auto-flip tone when contrast can't be met. */
+  autoFlip?: boolean;
+  /**
+   * If true, uses a hue-independent "safe" chroma limit across all colors
+   * so that scaling saturation never exceeds the sRGB boundary at any hue
+   * 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.
+   */
+  shadowTuning?: ShadowTuning;
 }
 /** Serialized theme configuration (no resolved values). */
 interface GlazeThemeExport {
   hue: number;
   saturation: number;
   colors: ColorMap;
+  /** Per-theme config override, if any. */
+  config?: GlazeConfigOverride;
 }
 /** Input for `glaze.shadow()` standalone factory. */
 interface GlazeShadowInput {
-  /** Background color — hex string or OKHSL { h, s (0-1), l (0-1) }. */
-  bg: HexColor | OkhslColor;
-  /** Foreground color for tinting + intensity modulation. */
-  fg?: HexColor | OkhslColor;
+  /**
+   * Background color — accepts any `GlazeColorValue` form: hex
+   * (`#rgb` / `#rrggbb` / `#rrggbbaa`), `rgb()` / `hsl()` / `okhsl()`
+   * / `oklch()` strings, or literal objects (`{ r, g, b }`, `{ h, s, l }`,
+   * `{ l, c, h }`). Alpha components are dropped with a warning.
+   */
+  bg: GlazeColorValue;
+  /**
+   * Foreground color for tinting + intensity modulation. Accepts the
+   * same forms as `bg`.
+   */
+  fg?: GlazeColorValue;
   /** Intensity 0-100. */
   intensity: number;
   tuning?: ShadowTuning;
 }
-/** Input for `glaze.color()` standalone factory. */
+/** Input for the structured `glaze.color()` overload. */
 interface GlazeColorInput {
   hue: number;
   saturation: number;
-  lightness: HCPair<number>;
+  tone: HCPair<number | ExtremeValue>;
   saturationFactor?: number;
   mode?: AdaptationMode;
+  /** Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. */
+  autoFlip?: boolean;
+  /**
+   * Fixed opacity (0–1). Output includes alpha in the CSS value.
+   * Combining with `contrast` is not recommended (perceived tone
+   * becomes unpredictable) — a `console.warn` is emitted in that case.
+   */
+  opacity?: number;
+  /**
+   * Optional dependency on another color. Same semantics as
+   * `GlazeColorOverrides.base` — `contrast` and relative `tone`
+   * anchor to the base per scheme.
+   */
+  base?: GlazeColorToken | GlazeColorValue;
+  /**
+   * Contrast floor against `base`. Requires `base` to be set. A bare
+   * number/preset is WCAG; use `{ wcag }` / `{ apca }` to pick the metric.
+   */
+  contrast?: HCPair<ContrastSpec>;
+  /**
+   * Optional human-readable name for the token. Used in error and
+   * warning messages (otherwise an internal name like `"value"` is
+   * used). Does not affect output keys.
+   */
+  name?: string;
+  /**
+   * Per-color override for the hue-independent "safe" chroma limit used in
+   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
+   * Falls through to the global / per-theme `pastel` config when omitted.
+   * @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
+ * overload of `glaze.color()`.
+ *
+ * Strings cover hex (`#rgb` / `#rrggbb` / `#rrggbbaa`, alpha dropped
+ * with a warning) and the four CSS color functions Glaze itself emits:
+ * `rgb()`, `hsl()`, `okhsl()`, `oklch()` (alpha components also dropped
+ * with a warning).
+ *
+ * Literal object forms:
+ * - `{ h, s, l }` — OKHSL (h: 0–360, s/l: 0–1). Passing 0–100 for `s`/`l`
+ *   throws with a hint to use the structured form.
+ * - `{ h, s, t }` — OKHST (h: 0–360, s/t: 0–1). Tone in 0–1.
+ * - `{ r, g, b }` — sRGB 0–255.
+ * - `{ l, c, h }` — OKLCh (L/C: 0–1, H: degrees), same as `oklch()` strings.
+ */
+type GlazeColorValue = string | OkhslColor | OkhstColor | RgbColor | OklchColor;
+/** Color overrides for the `from` and value-shorthand inputs. */
+interface GlazeColorOverrides {
+  /**
+   * Override hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
+   * to the extracted (or overridden) seed hue — same semantics as
+   * `RegularColorDef.hue`.
+   */
+  hue?: number | RelativeValue;
+  /** Override seed saturation (0–100). Default: extracted from value. */
+  saturation?: number;
+  /**
+   * Override tone. Number is absolute (0–100, contrast-uniform); `'+N'`/`'-N'`
+   * is relative to the literal seed (the value passed to `glaze.color()`);
+   * `'max'` / `'min'` force to the scheme's tone extreme.
+   * Supports HCPair for high-contrast.
+   */
+  tone?: HCPair<ToneValue>;
+  /** Saturation multiplier on the seed (0–1). Default: 1. */
+  saturationFactor?: number;
+  /**
+   * Adaptation mode. Defaults to `'auto'` for every input form, so
+   * colors automatically adapt between light and dark like an ordinary
+   * theme color. All value-shorthand inputs (strings and literal objects)
+   * preserve light tone (`lightTone: false`) and snapshot
+   * `globalConfig.darkTone` on the dark side. Only the structured
+   * `{ hue, saturation, tone }` form also snapshots
+   * `globalConfig.lightTone`.
+   *
+   * Pass `'fixed'` explicitly to opt back into the linear, non-
+   * inverting mapping; pass `'static'` to pin the same tone
+   * across every variant.
+   */
+  mode?: AdaptationMode;
+  /**
+   * Flip out-of-bounds results (relative `tone` overshoot / unmet
+   * `contrast`) to the opposite side instead of clamping. Defaults to
+   * the global `autoFlip`.
+   */
+  autoFlip?: boolean;
+  /**
+   * Contrast floor. By default solved against the literal seed
+   * (the value itself); when `base` is set, solved against the base's
+   * resolved variant per scheme. Same shape as `RegularColorDef.contrast`
+   * (bare number/preset = WCAG; `{ wcag }` / `{ apca }` to pick the metric).
+   */
+  contrast?: HCPair<ContrastSpec>;
+  /**
+   * Optional dependency on another color. Accepts either a
+   * `GlazeColorToken` (returned by another `glaze.color()`) or a raw
+   * `GlazeColorValue` (hex / CSS strings / `{ r, g, b }` / `{ h, s, l }` / …),
+   * which is automatically wrapped in `glaze.color(value)`.
+   *
+   * When set:
+   * - `contrast` is solved against the base's resolved variant
+   *   per-scheme (light / dark / lightContrast / darkContrast).
+   * - Relative `tone: '+N'` / `'-N'` is anchored to the base's
+   *   tone per-scheme (matches theme behavior for dependent colors).
+   * - Relative `hue: '+N'` / `'-N'` still anchors to the seed (the
+   *   value passed to `glaze.color()`), not the base.
+   * - When the base was created via the structured form (with explicit
+   *   `hue`/`saturation`/`tone`), it is resolved at full range
+   *   (`lightTone: false`) for the linking math — ensuring the
+   *   contrast/tone anchor matches the input tone, not the
+   *   windowed output. The base's own `.resolve()` output is unaffected.
+   *
+   * The base token's `.resolve()` is called lazily on first resolve and
+   * its result is captured by reference; later mutations to the base's
+   * defining call don't apply (matches existing token snapshot semantics).
+   */
+  base?: GlazeColorToken | GlazeColorValue;
+  /**
+   * Fixed opacity (0–1). Output includes alpha in the CSS value.
+   * Combining with `contrast` is not recommended (perceived tone
+   * becomes unpredictable) — a `console.warn` is emitted in that case.
+   */
+  opacity?: number;
+  /**
+   * Optional human-readable name for the token. Used in error and
+   * warning messages (otherwise an internal name like `"value"` is
+   * used). Does not affect output keys.
+   */
+  name?: string;
+  /**
+   * Per-color override for the hue-independent "safe" chroma limit used in
+   * OKHSL↔sRGB conversions (luminance, contrast solving, output formatting).
+   * Falls through to the global / per-theme `pastel` config when omitted.
+   * @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
+ * optional color overrides in the same object.
+ *
+ * ```ts
+ * glaze.color({ from: '#1a1a2e', base: bg, contrast: 'AA' })
+ * glaze.color({ from: { r: 38, g: 252, b: 178 }, tone: '+10' })
+ * ```
+ */
+interface GlazeFromInput extends GlazeColorOverrides {
+  /** The source color value. Accepts the same forms as a bare `GlazeColorValue`. */
+  from: GlazeColorValue;
+}
+/** Options for `GlazeColorToken.css()`. */
+interface GlazeColorCssOptions {
+  /**
+   * Custom property base name (without leading `--`). Required.
+   * Becomes the variable identifier in the output, e.g.
+   * `name: 'brand'` → `--brand-color: …`.
+   */
+  name: string;
+  /** Output color format. Default: 'oklch'. */
+  format?: GlazeColorFormat;
+  /**
+   * Suffix appended to the name. Default: '-color' (matches
+   * `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 {
@@ -303,18 +784,111 @@ interface GlazeColorToken {
   token(options?: GlazeTokenOptions): Record<string, string>;
   /**
    * Export as a tasty style-to-state binding (no color name key).
-   * Uses `#name` keys and state aliases (`''`, `@dark`, etc.).
-   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   * Uses `#name` keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
+   * @see https://tasty.style/docs
    */
   tasty(options?: GlazeTokenOptions): Record<string, string>;
   /** Export as a flat JSON map (no color name key). */
   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
+   * `glaze.colorFrom(...)`. `base` is recursively serialized.
+   */
+  export(): GlazeColorTokenExport;
+}
+/**
+ * JSON-safe serialization of a `glaze.color()` token. Pass to
+ * `glaze.colorFrom(...)` to rehydrate.
+ */
+interface GlazeColorTokenExport {
+  /**
+   * Discriminator for the source overload that created the token.
+   * - `'value'`: created via `glaze.color(value)` or `glaze.color({ from, ...overrides })`.
+   * - `'structured'`: created via `glaze.color({ hue, saturation, ... })`.
+   */
+  form: 'value' | 'structured';
+  /** Original input. For `form: 'value'` this is the raw `GlazeColorValue`; for `form: 'structured'` this is the structured input. */
+  input: GlazeColorValue | GlazeColorInputExport;
+  /**
+   * Overrides recorded at creation time. `base` is recursively
+   * serialized. Only present for `form: 'value'`.
+   */
+  overrides?: GlazeColorOverridesExport;
+  /**
+   * Effective config snapshot at creation time — captures the merged
+   * result of the global config + any per-call override at the moment
+   * the token was created. Only fields that differ from their
+   * post-merge defaults are present. Used by `glaze.colorFrom()` to
+   * reproduce deterministic behavior across `configure()` calls.
+   */
+  config?: GlazeConfigOverride;
+}
+/**
+ * Serializable shape of a structured `glaze.color({...})` input.
+ * Differs from `GlazeColorInput` only in that `base` is replaced by an
+ * `export` instead of a token reference.
+ */
+interface GlazeColorInputExport {
+  hue: number;
+  saturation: number;
+  tone: HCPair<number | ExtremeValue>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+  autoFlip?: boolean;
+  opacity?: number;
+  base?: GlazeColorTokenExport | GlazeColorValue;
+  contrast?: HCPair<ContrastSpec>;
+  name?: string;
+  pastel?: boolean;
+  role?: RoleInput;
+}
+/**
+ * Serializable shape of `GlazeColorOverrides`. `base` is replaced by
+ * its export (or left as a `GlazeColorValue` if it was originally a value).
+ */
+interface GlazeColorOverridesExport {
+  hue?: number | RelativeValue;
+  saturation?: number;
+  tone?: HCPair<ToneValue>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+  autoFlip?: boolean;
+  contrast?: HCPair<ContrastSpec>;
+  base?: GlazeColorTokenExport | GlazeColorValue;
+  opacity?: number;
+  name?: string;
+  pastel?: boolean;
+  role?: RoleInput;
 }
 interface GlazeTheme {
   /** The hue seed (0–360). */
   readonly hue: number;
   /** The saturation seed (0–100). */
   readonly saturation: number;
+  /** The effective config for this theme. */
+  getConfig(): GlazeConfigResolved;
   /** Add/replace colors (additive merge with existing definitions). */
   colors(defs: ColorMap): void;
   /** Get a color definition by name. */
@@ -346,20 +920,43 @@ interface GlazeTheme {
   tokens(options?: GlazeJsonOptions): Record<string, Record<string, string>>;
   /**
    * Export as tasty style-to-state bindings.
-   * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+   * Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
    * Spread into component styles or register as a recipe via `configure({ recipes })`.
-   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   * @see https://tasty.style/docs
    */
   tasty(options?: GlazeTokenOptions): Record<string, Record<string, string>>;
   /** Export as plain JSON. */
   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;
   saturation?: number;
   colors?: ColorMap;
+  /** Config override for the child theme. Merged with the parent's override. */
+  config?: GlazeConfigOverride;
 }
 interface GlazeTokenOptions {
   /** Prefix mode. `true` uses "<themeName>-", or provide a custom map. */
@@ -371,20 +968,40 @@ interface GlazeTokenOptions {
   };
   /** Override which scheme variants to include. */
   modes?: GlazeOutputModes;
-  /** Output color format. Default: 'okhsl'. */
+  /** Output color format. Default: 'oklch'. */
   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. */
   modes?: GlazeOutputModes;
-  /** Output color format. Default: 'okhsl'. */
+  /** Output color format. Default: 'oklch'. */
   format?: GlazeColorFormat;
 }
 interface GlazeCssOptions {
-  /** Output color format. Default: 'rgb'. */
+  /** Output color format. Default: 'oklch'. */
   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 {
@@ -393,6 +1010,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 {
   /**
@@ -424,6 +1217,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 {
   /**
@@ -440,9 +1238,9 @@ interface GlazePalette {
   tokens(options?: GlazeJsonOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
   /**
    * Export all themes as tasty style-to-state bindings.
-   * Uses `#name` color token keys and state aliases (`''`, `@dark`, etc.).
+   * Uses `#name` color token keys and state aliases (`''`, `'@media(prefers-color-scheme: dark)'`, etc.).
    * Prefix defaults to `true`. Inherits the palette-level `primary`.
-   * @see https://cube-ui-kit.vercel.app/?path=/docs/tasty-documentation--docs
+   * @see https://tasty.style/docs
    */
   tasty(options?: GlazeTokenOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
   /** Export all themes as plain JSON grouped by theme name. */
@@ -451,6 +1249,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
@@ -458,54 +1275,201 @@ type PaletteInput = Record<string, GlazeTheme>;
 /**
  * Create a single-hue glaze theme.
  *
+ * An optional `config` override can be supplied to customize the resolve
+ * behavior for this theme (tone windows, etc.). The
+ * override is **merged over the live global config at resolve time** —
+ * the theme still reacts to later `configure()` calls for fields it
+ * didn't override.
+ *
  * @example
  * ```ts
- * const primary = glaze({ hue: 280, saturation: 80 });
- * // or shorthand:
  * const primary = glaze(280, 80);
+ * // or shorthand:
+ * const primary = glaze({ hue: 280, saturation: 80 });
+ * // with config override:
+ * const raw = glaze(280, 80, { lightTone: false });
  * ```
  */
 declare function glaze(hueOrOptions: number | {
   hue: number;
   saturation: number;
-}, saturation?: number): GlazeTheme;
+}, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
-  var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => {
-    tokens(options?: GlazeJsonOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
-    tasty(options?: GlazeTokenOptions & GlazePaletteExportOptions): Record<string, Record<string, string>>;
-    json(options?: GlazeJsonOptions & {
-      prefix?: boolean | Record<string, string>;
-    }): Record<string, Record<string, Record<string, string>>>;
-    css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
-  };
+  var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
   var from: (data: GlazeThemeExport) => GlazeTheme;
-  var color: (input: GlazeColorInput) => GlazeColorToken;
+  var color: (input: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?: GlazeConfigOverride) => GlazeColorToken;
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
-  var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => string;
+  var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat, pastel?: boolean) => string;
   var fromHex: (hex: string) => GlazeTheme;
   var fromRgb: (r: number, g: number, b: number) => GlazeTheme;
+  var colorFrom: (data: GlazeColorTokenExport) => GlazeColorToken;
   var getConfig: () => GlazeConfigResolved;
   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
+ * `(Y_hi + 0.05) / (Y_lo + 0.05)`, so an eps of `0.05` makes equal tone
+ * steps yield equal WCAG contrast. This is the canonical eps used by
+ * `okhst()` input, `{ h, s, t }` input, stored `ResolvedColorVariant.t`,
+ * relative `tone` offsets, and the contrast solver.
+ */
+declare const REF_EPS = 0.05;
+/**
+ * Map a luminance `Y` (0–1) to tone (0–100) at the given eps.
+ * `toneFromY(0) === 0` and `toneFromY(1) === 100` for any eps.
+ */
+declare function toneFromY(y: number, eps?: number): number;
+/** Map a tone (0–100) back to luminance (0–1). Inverse of {@link toneFromY}. */
+declare function yFromTone(t: number, eps?: number): number;
+/** OKHSL lightness (0–1) -> tone (0–100). */
+declare function toTone(l: number, eps?: number): number;
+/** Tone (0–100) -> OKHSL lightness (0–1). Inverse of {@link toTone}. */
+declare function fromTone(t: number, eps?: number): number;
+/** Convert OKHST `{ h, s, t }` (t in 0–1) to OKHSL `{ h, s, l }`. */
+declare function okhstToOkhsl(c: {
+  h: number;
+  s: number;
+  t: number;
+}): {
+  h: number;
+  s: number;
+  l: number;
+};
+/** Convert OKHSL `{ h, s, l }` to OKHST `{ h, s, t }` (t in 0–1). */
+declare function okhslToOkhst(c: {
+  h: number;
+  s: number;
+  l: number;
+}): {
+  h: number;
+  s: number;
+  t: number;
+};
+/**
+ * Edge adapter: a resolved variant stores canonical tone `t` (0–1). Convert
+ * it to the OKHSL `{ h, s, l }` the formatters and luminance pipeline expect.
+ */
+declare function variantToOkhsl(v: {
+  h: number;
+  s: number;
+  t: number;
+}): {
+  h: number;
+  s: number;
+  l: number;
+};
+//#endregion
 //#region src/okhsl-color-math.d.ts
 /**
  * OKHSL color math primitives for the glaze theme generator.
  *
- * Provides bidirectional OKHSL ↔ sRGB conversion, relative luminance
- * computation for WCAG 2 contrast calculations, and multi-format output
- * (okhsl, rgb, hsl, oklch).
+ * Provides bidirectional OKHSL ↔ sRGB conversion, luminance computation
+ * for both contrast metrics (WCAG 2 relative luminance and APCA screen
+ * luminance `Ys`), and multi-format output (okhsl, rgb, hsl, oklch).
+ */
+type Vec3 = [number, number, number];
+/**
+ * OKHSL toe function: maps OKLab lightness L to perceptual lightness l.
+ * Exported for the OKHST tone transfers in `okhst.ts`.
+ */
+/**
+ * OKHSL lightness of the gamut cusp for a hue — the lightness where the
+ * realizable chroma peaks. Reuses the same `find_cusp` OKHSL already runs for
+ * its `s` normalization (no new color math); the OKLab cusp lightness is run
+ * through the OKHSL `toe` and clamped to `[0.001, 0.999]` so divisions that
+ * key off it stay safe. Cached per (rounded) hue.
+ *
+ * @param h Hue, 0–360.
  */
+declare function cuspLightness(h: number): number;
 /**
  * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
  */
-declare function okhslToOklab(h: number, s: number, l: number): [number, number, number];
+declare function okhslToOklab(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 /**
  * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to linear sRGB.
  * Channels may exceed [0, 1] near gamut boundaries — caller must clamp if needed.
  */
-declare function okhslToLinearSrgb(h: number, s: number, l: number): [number, number, number];
+declare function okhslToLinearSrgb(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 /**
  * Compute relative luminance Y from linear sRGB channels.
  * Per WCAG 2: Y = 0.2126·R + 0.7152·G + 0.0722·B
@@ -518,44 +1482,90 @@ declare function contrastRatioFromLuminance(yA: number, yB: number): number;
 /**
  * Convert OKHSL to gamma-encoded sRGB (clamped to 0–1).
  */
-declare function okhslToSrgb(h: number, s: number, l: number): [number, number, number];
+declare function okhslToSrgb(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 /**
  * Compute WCAG 2 relative luminance from linear sRGB, matching the browser
  * rendering pipeline: gamma-encode, clamp to sRGB gamut [0,1], then linearize.
  * This avoids over/under-estimating luminance for out-of-gamut OKHSL colors.
  */
 declare function gamutClampedLuminance(linearRgb: [number, number, number]): number;
+/**
+ * Convert OKLab to OKHSL.
+ * Input: [L, a, b] where L: 0–1, a/b: roughly -0.5 to 0.5.
+ * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
+ */
+declare const oklabToOkhsl: (lab: Vec3, pastel?: boolean) => Vec3;
 /**
  * Convert gamma-encoded sRGB (0–1 per channel) to OKHSL.
  * Returns [h, s, l] where h: 0–360, s: 0–1, l: 0–1.
  */
-declare function srgbToOkhsl(rgb: [number, number, number]): [number, number, number];
+declare function srgbToOkhsl(rgb: [number, number, number], pastel?: boolean): [number, number, number];
+/**
+ * Convert CSS HSL (sRGB-based) to gamma-encoded sRGB [r, g, b] in 0–1 range.
+ * h: 0–360, s: 0–1, l: 0–1.
+ *
+ * Note: CSS HSL is not the same as OKHSL — it's HSL in the sRGB color space.
+ * Use this when parsing `hsl(...)` strings before passing to `srgbToOkhsl`.
+ */
+declare function hslToSrgb(h: number, s: number, l: number): [number, number, number];
 /**
  * Parse a hex color string (#rgb or #rrggbb) to sRGB [r, g, b] in 0–1 range.
  * Returns null if the string is not a valid hex color.
+ *
+ * For 8-digit hex (`#rrggbbaa`) and 4-digit hex (`#rgba`) with alpha,
+ * use {@link parseHexAlpha}.
  */
 declare function parseHex(hex: string): [number, number, number] | null;
+/**
+ * Parse a hex color string (#rgb, #rrggbb, #rgba, or #rrggbbaa) to
+ * sRGB [r, g, b] in 0–1 range plus an optional alpha (0–1).
+ * Returns null if the string is not a valid hex color.
+ */
+declare function parseHexAlpha(hex: string): {
+  rgb: [number, number, number];
+  alpha?: number;
+} | null;
 /**
  * Format OKHSL values as a CSS `okhsl(H S% L%)` 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): string;
+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.
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
-declare function formatRgb(h: number, s: number, l: number): string;
+declare function formatRgb(h: number, s: number, l: number, pastel?: boolean): string;
 /**
  * Format OKHSL values as a CSS `hsl(H S% L%)` string.
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
-declare function formatHsl(h: number, s: number, l: number): string;
+declare function formatHsl(h: number, s: number, l: number, pastel?: boolean): string;
 /**
  * Format OKHSL values as a CSS `oklch(L C H)` string.
  * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
  */
-declare function formatOklch(h: number, s: number, l: number): string;
+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 FindLightnessForContrastOptions, type FindLightnessForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorFormat, type GlazeColorInput, type GlazeColorToken, type GlazeConfig, type GlazeCssOptions, type GlazeCssResult, type GlazeExtendOptions, 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 RegularColorDef, type RelativeValue, type ResolvedColor, type ResolvedColorVariant, type ShadowColorDef, type ShadowTuning, contrastRatioFromLuminance, findLightnessForContrast, findValueForMixContrast, formatHsl, formatOkhsl, formatOklch, formatRgb, gamutClampedLuminance, glaze, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, parseHex, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
+export { APCA_HC_ENHANCEMENT, APCA_MAX_LC, APCA_PRESETS, 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.mts.map