@tenphi/glaze 1.1.1 → 1.3.0

package/dist/index.d.cts

@@ -62,6 +62,24 @@ declare function resolveMinContrast(value: MinContrast$1): number;
  * selected spec rather than an outer pair).
  */
 declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg', outerExplicitHC?: boolean): ResolvedContrast;
+/**
+ * Resolve a `contrast` spec — including its outer `[normal, highContrast]`
+ * pair — at a manual contrast `level` (0–100), by resolving both ends and
+ * interpolating the numeric target.
+ *
+ * Level 0 / 100 delegate verbatim to {@link resolveContrastForMode}, so the
+ * endpoints are bit-identical to classic normal / high-contrast resolution.
+ * Resolving each end fully first also means every rule that governs the
+ * escalation still applies at both ends for free: preset mapping, the
+ * `APCA_MAX_LC` clamp, and the explicit-HC suppression that cancels the
+ * `AA → AAA` promotion and the `+15 Lc` enhancement.
+ *
+ * Throws when the two ends measure in different metrics — a WCAG ratio and an
+ * APCA Lc live on different scales, so there is no target between them. Such a
+ * pair is rejected at authoring time by `validateColorDefs`; this is the guard
+ * for direct callers.
+ */
+declare function resolveContrastForLevel(spec: HCPair<ContrastSpec>, level: number, 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).
@@ -88,6 +106,19 @@ interface FindToneForContrastOptions {
   initialDirection?: 'lighter' | 'darker';
   /** Auto-flip tone direction when contrast can't be met. Default: false. */
   flip?: boolean;
+  /**
+   * When `flip` is on and *both* directions meet the target, keep
+   * `initialDirection` instead of taking whichever result lands nearer the
+   * preferred tone. Default: false (nearest wins).
+   *
+   * The nearest-wins tie-break is unstable along a ramp of targets: which side
+   * is nearer shifts as the target grows, so a color can swap sides between two
+   * adjacent targets. Set this when a caller needs the side to be a property of
+   * the color rather than of the target — the manual contrast level does. The
+   * flip itself is unaffected: an initial direction that cannot reach the
+   * target still falls back to the opposite side.
+   */
+  preferInitial?: boolean;
   /** Use the hue-independent "safe" chroma boundary. Default: false. */
   pastel?: boolean;
 }
@@ -200,7 +231,14 @@ type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';
 interface GlazeOutputModes {
   /** Include dark scheme variants. Default: true. */
   dark?: boolean;
-  /** Include high-contrast variants (both light-HC and dark-HC). Default: false. */
+  /**
+   * Include high-contrast variants (both light-HC and dark-HC). Default: false.
+   *
+   * Inert while a global `contrastLevel` is set: a manual level has no separate
+   * high-contrast tier, so this reads as "emit high-contrast variants when
+   * contrast is automatic".
+   * @see GlazeConfig.contrastLevel
+   */
   highContrast?: boolean;
 }
 /** Hex color string for DX hints. Runtime validation in `parseHex()`. */
@@ -248,6 +286,26 @@ interface RegularColorDef {
    * - String ('+N' / '-N'): relative to the theme seed hue.
    */
   hue?: number | RelativeValue;
+  /**
+   * Dark-scheme hue override. Applies to the `dark` and `darkContrast`
+   * variants; falls back to `hue` when omitted.
+   * - Number: absolute hue (0–360).
+   * - String ('+N' / '-N'): relative to the theme's **dark** seed hue
+   *   (`GlazeTheme.darkHue`, itself defaulting to the light seed hue).
+   *
+   * Ignored under `mode: 'static'`, which pins one value across all schemes.
+   */
+  darkHue?: number | RelativeValue;
+  /**
+   * Dark-scheme saturation factor (0–1) applied to the dark seed
+   * saturation. Applies to the `dark` and `darkContrast` variants; falls
+   * back to `saturation` when omitted.
+   *
+   * When set, the global `darkDesaturation` reduction is **not** applied on
+   * top — the resulting saturation is taken literally. Ignored under
+   * `mode: 'static'`.
+   */
+  darkSaturation?: number;
   /** Name of another color in the same theme (dependent color). */
   base?: string;
   /**
@@ -475,10 +533,38 @@ interface GlazeConfig {
     dark?: string;
     highContrast?: string;
   };
-  /** Which scheme variants to include in exports. Default: both true. */
+  /**
+   * Which scheme variants to include in exports. Defaults: `dark: true`,
+   * `highContrast: false`.
+   */
   modes?: GlazeOutputModes;
   /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
   shadowTuning?: ShadowTuning;
+  /**
+   * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
+   * contrast (`100`), or `'auto'` (the default) to keep the two-tier
+   * normal + high-contrast model.
+   *
+   * With a number, Glaze resolves the `light` / `dark` variants *at* that
+   * level and stops emitting a separate high-contrast tier:
+   * `lightContrast` / `darkContrast` mirror their normal counterparts and
+   * `modes.highContrast` defaults to `false`. Level `0` is therefore "normal
+   * contrast, no high-contrast tier"; `100` is "the high-contrast scheme as
+   * the only scheme".
+   *
+   * The level interpolates all three things that make high contrast differ:
+   * authored `[normal, highContrast]` pairs, the tone-window widening, and
+   * the `AA → AAA` / APCA `+15 Lc` escalation. Contrast floors are re-solved
+   * at the interpolated target, so every level is a solution rather than an
+   * approximation, and a color keeps to one side of its base as the level moves.
+   *
+   * Pass `'auto'` to leave manual mode; `configure()` never clears a field by
+   * omission. See `docs/api.md` for the ramp's edge cases (un-interpolable
+   * pairs, side changes) and the export-freeze rule.
+   *
+   * @default 'auto'
+   */
+  contrastLevel?: number | 'auto';
   /**
    * Automatically flip tone direction when contrast can't be met.
    *
@@ -513,6 +599,12 @@ interface GlazeConfigResolved {
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
+  /**
+   * Manual contrast level (0–100), or `'auto'` for the two-tier
+   * normal + high-contrast model.
+   * @see GlazeConfig.contrastLevel
+   */
+  contrastLevel: number | 'auto';
   /**
    * Instance-level pastel default (`def.pastel ?? config.pastel`).
    * Not set via `glaze.configure()` — only via per-theme / per-token
@@ -538,6 +630,17 @@ interface GlazeConfigOverride {
   darkDesaturation?: number;
   /** Whether to auto-flip tone when contrast can't be met. */
   autoFlip?: boolean;
+  /**
+   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out
+   * of a global level and keep the two-tier normal + high-contrast model.
+   *
+   * Only an instance-authored level is frozen into `.export()` snapshots — a
+   * level inherited from the global config is treated as a live preference and
+   * re-read at restore time.
+   *
+   * @see GlazeConfig.contrastLevel
+   */
+  contrastLevel?: number | 'auto';
   /**
    * Instance-level pastel default for colors that omit per-color `pastel`.
    * Not available on `glaze.configure()` — set here or per-color.
@@ -572,6 +675,10 @@ interface GlazeThemeExport {
   version?: number;
   hue: number;
   saturation: number;
+  /** Dark-scheme seed hue (0–360). Omitted when the theme reuses `hue`. */
+  darkHue?: number;
+  /** Dark-scheme seed saturation (0–100). Omitted when the theme reuses `saturation`. */
+  darkSaturation?: number;
   colors: ColorMap;
   /**
    * Effective config freeze from `.export()` —
@@ -604,6 +711,15 @@ interface GlazeColorInput {
   saturation: number;
   tone: HCPair<number | ExtremeValue>;
   saturationFactor?: number;
+  /**
+   * Dark-scheme hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
+   * to the dark seed hue, which defaults to `hue`. Falls back to `hue`.
+   */
+  darkHue?: number | RelativeValue;
+  /** Dark-scheme seed saturation (0–100). Defaults to `saturation`. */
+  darkSaturation?: number;
+  /** Dark-scheme multiplier on the dark seed (0–1). Defaults to `saturationFactor`. */
+  darkSaturationFactor?: number;
   mode?: AdaptationMode;
   /** Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. */
   autoFlip?: boolean;
@@ -673,6 +789,23 @@ interface GlazeColorOverrides {
   hue?: number | RelativeValue;
   /** Override seed saturation (0–100). Default: extracted from value. */
   saturation?: number;
+  /**
+   * Dark-scheme hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
+   * to the dark seed hue, which defaults to the (possibly overridden) seed
+   * hue. Falls back to `hue` when omitted.
+   */
+  darkHue?: number | RelativeValue;
+  /**
+   * Dark-scheme seed saturation (0–100). Defaults to `saturation`. When set,
+   * the global `darkDesaturation` reduction is not applied on top.
+   */
+  darkSaturation?: number;
+  /**
+   * Dark-scheme multiplier on the dark seed (0–1). Defaults to
+   * `saturationFactor`. When set, the global `darkDesaturation` reduction is
+   * not applied on top.
+   */
+  darkSaturationFactor?: number;
   /**
    * Override tone. Number is absolute (0–100, contrast-uniform); `'+N'`/`'-N'`
    * is relative to the literal seed (the value passed to `glaze.color()`);
@@ -889,6 +1022,9 @@ interface GlazeColorInputExport {
   saturation: number;
   tone: HCPair<number | ExtremeValue>;
   saturationFactor?: number;
+  darkHue?: number | RelativeValue;
+  darkSaturation?: number;
+  darkSaturationFactor?: number;
   mode?: AdaptationMode;
   autoFlip?: boolean;
   opacity?: number;
@@ -905,6 +1041,9 @@ interface GlazeColorInputExport {
 interface GlazeColorOverridesExport {
   hue?: number | RelativeValue;
   saturation?: number;
+  darkHue?: number | RelativeValue;
+  darkSaturation?: number;
+  darkSaturationFactor?: number;
   tone?: HCPair<ToneValue>;
   saturationFactor?: number;
   mode?: AdaptationMode;
@@ -916,11 +1055,33 @@ interface GlazeColorOverridesExport {
   pastel?: boolean;
   role?: RoleInput;
 }
+/**
+ * The hue/saturation seed pair a theme resolves against.
+ *
+ * `darkHue` / `darkSaturation` are a separate seed for the `dark` and
+ * `darkContrast` variants; each falls back to its light counterpart. Setting
+ * `darkSaturation` opts the theme out of the global `darkDesaturation`
+ * reduction — the authored value is used literally.
+ */
+interface GlazeThemeSeed {
+  /** Light-scheme hue seed (0–360). */
+  hue: number;
+  /** Light-scheme saturation seed (0–100). */
+  saturation: number;
+  /** Dark-scheme hue seed (0–360). Defaults to `hue`. */
+  darkHue?: number;
+  /** Dark-scheme saturation seed (0–100). Defaults to `saturation`. */
+  darkSaturation?: number;
+}
 interface GlazeTheme {
   /** The hue seed (0–360). */
   readonly hue: number;
   /** The saturation seed (0–100). */
   readonly saturation: number;
+  /** The dark-scheme hue seed (0–360), or `undefined` when `hue` is reused. */
+  readonly darkHue: number | undefined;
+  /** The dark-scheme saturation seed (0–100), or `undefined` when `saturation` is reused. */
+  readonly darkSaturation: number | undefined;
   /** The effective config for this theme. */
   getConfig(): GlazeConfigResolved;
   /** Add/replace colors (additive merge with existing definitions). */
@@ -988,6 +1149,10 @@ interface GlazeTheme {
 interface GlazeExtendOptions {
   hue?: number;
   saturation?: number;
+  /** Replace the dark-scheme hue seed (0–360). Defaults to the parent's. */
+  darkHue?: number;
+  /** Replace the dark-scheme saturation seed (0–100). Defaults to the parent's. */
+  darkSaturation?: number;
   colors?: ColorMap;
   /** Config override for the child theme. Merged with the parent's override. */
   config?: GlazeConfigOverride;
@@ -1341,19 +1506,23 @@ type PaletteInput = Record<string, GlazeTheme>;
  * the theme still reacts to later `configure()` calls for fields it
  * didn't override.
  *
+ * The object form also accepts `darkHue` / `darkSaturation` — a separate
+ * seed pair for the dark and dark-high-contrast schemes. Both default to
+ * their light counterparts, and an explicit `darkSaturation` opts the theme
+ * out of the global `darkDesaturation` reduction.
+ *
  * @example
  * ```ts
  * const primary = glaze(280, 80);
  * // or shorthand:
  * const primary = glaze({ hue: 280, saturation: 80 });
+ * // with a retuned dark seed:
+ * const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
  * // with config override:
  * const raw = glaze(280, 80, { lightTone: false });
  * ```
  */
-declare function glaze(hueOrOptions: number | {
-  hue: number;
-  saturation: number;
-}, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
+declare function glaze(hueOrOptions: number | GlazeThemeSeed, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
   var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
@@ -1388,6 +1557,11 @@ interface HuePlan {
 }
 interface ChannelCtx {
   seedHue: number;
+  /**
+   * Dark-scheme seed hue, when the theme authored one. Drives the dark
+   * `--{baseName}-hue` value; falls back to `seedHue`.
+   */
+  darkSeedHue?: number;
   /** Theme-level hue var base name (without `--` / `-hue`). */
   baseName: string;
   /** Token / custom-property name prefix used for hue var naming (`brand-` etc.). */
@@ -1632,5 +1806,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-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, GLAZE_EXPORT_VERSION, 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 GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, 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, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+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, GLAZE_EXPORT_VERSION, 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 GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeThemeSeed, 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, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -62,6 +62,24 @@ declare function resolveMinContrast(value: MinContrast$1): number;
  * selected spec rather than an outer pair).
  */
 declare function resolveContrastForMode(spec: ContrastSpec, isHighContrast: boolean, polarity?: 'fg' | 'bg', outerExplicitHC?: boolean): ResolvedContrast;
+/**
+ * Resolve a `contrast` spec — including its outer `[normal, highContrast]`
+ * pair — at a manual contrast `level` (0–100), by resolving both ends and
+ * interpolating the numeric target.
+ *
+ * Level 0 / 100 delegate verbatim to {@link resolveContrastForMode}, so the
+ * endpoints are bit-identical to classic normal / high-contrast resolution.
+ * Resolving each end fully first also means every rule that governs the
+ * escalation still applies at both ends for free: preset mapping, the
+ * `APCA_MAX_LC` clamp, and the explicit-HC suppression that cancels the
+ * `AA → AAA` promotion and the `+15 Lc` enhancement.
+ *
+ * Throws when the two ends measure in different metrics — a WCAG ratio and an
+ * APCA Lc live on different scales, so there is no target between them. Such a
+ * pair is rejected at authoring time by `validateColorDefs`; this is the guard
+ * for direct callers.
+ */
+declare function resolveContrastForLevel(spec: HCPair<ContrastSpec>, level: number, 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).
@@ -88,6 +106,19 @@ interface FindToneForContrastOptions {
   initialDirection?: 'lighter' | 'darker';
   /** Auto-flip tone direction when contrast can't be met. Default: false. */
   flip?: boolean;
+  /**
+   * When `flip` is on and *both* directions meet the target, keep
+   * `initialDirection` instead of taking whichever result lands nearer the
+   * preferred tone. Default: false (nearest wins).
+   *
+   * The nearest-wins tie-break is unstable along a ramp of targets: which side
+   * is nearer shifts as the target grows, so a color can swap sides between two
+   * adjacent targets. Set this when a caller needs the side to be a property of
+   * the color rather than of the target — the manual contrast level does. The
+   * flip itself is unaffected: an initial direction that cannot reach the
+   * target still falls back to the opposite side.
+   */
+  preferInitial?: boolean;
   /** Use the hue-independent "safe" chroma boundary. Default: false. */
   pastel?: boolean;
 }
@@ -200,7 +231,14 @@ type GlazeColorFormat = 'okhsl' | 'okhst' | 'rgb' | 'hsl' | 'oklch';
 interface GlazeOutputModes {
   /** Include dark scheme variants. Default: true. */
   dark?: boolean;
-  /** Include high-contrast variants (both light-HC and dark-HC). Default: false. */
+  /**
+   * Include high-contrast variants (both light-HC and dark-HC). Default: false.
+   *
+   * Inert while a global `contrastLevel` is set: a manual level has no separate
+   * high-contrast tier, so this reads as "emit high-contrast variants when
+   * contrast is automatic".
+   * @see GlazeConfig.contrastLevel
+   */
   highContrast?: boolean;
 }
 /** Hex color string for DX hints. Runtime validation in `parseHex()`. */
@@ -248,6 +286,26 @@ interface RegularColorDef {
    * - String ('+N' / '-N'): relative to the theme seed hue.
    */
   hue?: number | RelativeValue;
+  /**
+   * Dark-scheme hue override. Applies to the `dark` and `darkContrast`
+   * variants; falls back to `hue` when omitted.
+   * - Number: absolute hue (0–360).
+   * - String ('+N' / '-N'): relative to the theme's **dark** seed hue
+   *   (`GlazeTheme.darkHue`, itself defaulting to the light seed hue).
+   *
+   * Ignored under `mode: 'static'`, which pins one value across all schemes.
+   */
+  darkHue?: number | RelativeValue;
+  /**
+   * Dark-scheme saturation factor (0–1) applied to the dark seed
+   * saturation. Applies to the `dark` and `darkContrast` variants; falls
+   * back to `saturation` when omitted.
+   *
+   * When set, the global `darkDesaturation` reduction is **not** applied on
+   * top — the resulting saturation is taken literally. Ignored under
+   * `mode: 'static'`.
+   */
+  darkSaturation?: number;
   /** Name of another color in the same theme (dependent color). */
   base?: string;
   /**
@@ -475,10 +533,38 @@ interface GlazeConfig {
     dark?: string;
     highContrast?: string;
   };
-  /** Which scheme variants to include in exports. Default: both true. */
+  /**
+   * Which scheme variants to include in exports. Defaults: `dark: true`,
+   * `highContrast: false`.
+   */
   modes?: GlazeOutputModes;
   /** Default tuning for all shadow colors. Per-color tuning merges field-by-field. */
   shadowTuning?: ShadowTuning;
+  /**
+   * Manual contrast level — a 0–100 slider from normal contrast (`0`) to high
+   * contrast (`100`), or `'auto'` (the default) to keep the two-tier
+   * normal + high-contrast model.
+   *
+   * With a number, Glaze resolves the `light` / `dark` variants *at* that
+   * level and stops emitting a separate high-contrast tier:
+   * `lightContrast` / `darkContrast` mirror their normal counterparts and
+   * `modes.highContrast` defaults to `false`. Level `0` is therefore "normal
+   * contrast, no high-contrast tier"; `100` is "the high-contrast scheme as
+   * the only scheme".
+   *
+   * The level interpolates all three things that make high contrast differ:
+   * authored `[normal, highContrast]` pairs, the tone-window widening, and
+   * the `AA → AAA` / APCA `+15 Lc` escalation. Contrast floors are re-solved
+   * at the interpolated target, so every level is a solution rather than an
+   * approximation, and a color keeps to one side of its base as the level moves.
+   *
+   * Pass `'auto'` to leave manual mode; `configure()` never clears a field by
+   * omission. See `docs/api.md` for the ramp's edge cases (un-interpolable
+   * pairs, side changes) and the export-freeze rule.
+   *
+   * @default 'auto'
+   */
+  contrastLevel?: number | 'auto';
   /**
    * Automatically flip tone direction when contrast can't be met.
    *
@@ -513,6 +599,12 @@ interface GlazeConfigResolved {
   modes: Required<GlazeOutputModes>;
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
+  /**
+   * Manual contrast level (0–100), or `'auto'` for the two-tier
+   * normal + high-contrast model.
+   * @see GlazeConfig.contrastLevel
+   */
+  contrastLevel: number | 'auto';
   /**
    * Instance-level pastel default (`def.pastel ?? config.pastel`).
    * Not set via `glaze.configure()` — only via per-theme / per-token
@@ -538,6 +630,17 @@ interface GlazeConfigOverride {
   darkDesaturation?: number;
   /** Whether to auto-flip tone when contrast can't be met. */
   autoFlip?: boolean;
+  /**
+   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out
+   * of a global level and keep the two-tier normal + high-contrast model.
+   *
+   * Only an instance-authored level is frozen into `.export()` snapshots — a
+   * level inherited from the global config is treated as a live preference and
+   * re-read at restore time.
+   *
+   * @see GlazeConfig.contrastLevel
+   */
+  contrastLevel?: number | 'auto';
   /**
    * Instance-level pastel default for colors that omit per-color `pastel`.
    * Not available on `glaze.configure()` — set here or per-color.
@@ -572,6 +675,10 @@ interface GlazeThemeExport {
   version?: number;
   hue: number;
   saturation: number;
+  /** Dark-scheme seed hue (0–360). Omitted when the theme reuses `hue`. */
+  darkHue?: number;
+  /** Dark-scheme seed saturation (0–100). Omitted when the theme reuses `saturation`. */
+  darkSaturation?: number;
   colors: ColorMap;
   /**
    * Effective config freeze from `.export()` —
@@ -604,6 +711,15 @@ interface GlazeColorInput {
   saturation: number;
   tone: HCPair<number | ExtremeValue>;
   saturationFactor?: number;
+  /**
+   * Dark-scheme hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
+   * to the dark seed hue, which defaults to `hue`. Falls back to `hue`.
+   */
+  darkHue?: number | RelativeValue;
+  /** Dark-scheme seed saturation (0–100). Defaults to `saturation`. */
+  darkSaturation?: number;
+  /** Dark-scheme multiplier on the dark seed (0–1). Defaults to `saturationFactor`. */
+  darkSaturationFactor?: number;
   mode?: AdaptationMode;
   /** Flip out-of-bounds results instead of clamping. Default: global `autoFlip`. */
   autoFlip?: boolean;
@@ -673,6 +789,23 @@ interface GlazeColorOverrides {
   hue?: number | RelativeValue;
   /** Override seed saturation (0–100). Default: extracted from value. */
   saturation?: number;
+  /**
+   * Dark-scheme hue. Number is absolute (0–360); `'+N'`/`'-N'` is relative
+   * to the dark seed hue, which defaults to the (possibly overridden) seed
+   * hue. Falls back to `hue` when omitted.
+   */
+  darkHue?: number | RelativeValue;
+  /**
+   * Dark-scheme seed saturation (0–100). Defaults to `saturation`. When set,
+   * the global `darkDesaturation` reduction is not applied on top.
+   */
+  darkSaturation?: number;
+  /**
+   * Dark-scheme multiplier on the dark seed (0–1). Defaults to
+   * `saturationFactor`. When set, the global `darkDesaturation` reduction is
+   * not applied on top.
+   */
+  darkSaturationFactor?: number;
   /**
    * Override tone. Number is absolute (0–100, contrast-uniform); `'+N'`/`'-N'`
    * is relative to the literal seed (the value passed to `glaze.color()`);
@@ -889,6 +1022,9 @@ interface GlazeColorInputExport {
   saturation: number;
   tone: HCPair<number | ExtremeValue>;
   saturationFactor?: number;
+  darkHue?: number | RelativeValue;
+  darkSaturation?: number;
+  darkSaturationFactor?: number;
   mode?: AdaptationMode;
   autoFlip?: boolean;
   opacity?: number;
@@ -905,6 +1041,9 @@ interface GlazeColorInputExport {
 interface GlazeColorOverridesExport {
   hue?: number | RelativeValue;
   saturation?: number;
+  darkHue?: number | RelativeValue;
+  darkSaturation?: number;
+  darkSaturationFactor?: number;
   tone?: HCPair<ToneValue>;
   saturationFactor?: number;
   mode?: AdaptationMode;
@@ -916,11 +1055,33 @@ interface GlazeColorOverridesExport {
   pastel?: boolean;
   role?: RoleInput;
 }
+/**
+ * The hue/saturation seed pair a theme resolves against.
+ *
+ * `darkHue` / `darkSaturation` are a separate seed for the `dark` and
+ * `darkContrast` variants; each falls back to its light counterpart. Setting
+ * `darkSaturation` opts the theme out of the global `darkDesaturation`
+ * reduction — the authored value is used literally.
+ */
+interface GlazeThemeSeed {
+  /** Light-scheme hue seed (0–360). */
+  hue: number;
+  /** Light-scheme saturation seed (0–100). */
+  saturation: number;
+  /** Dark-scheme hue seed (0–360). Defaults to `hue`. */
+  darkHue?: number;
+  /** Dark-scheme saturation seed (0–100). Defaults to `saturation`. */
+  darkSaturation?: number;
+}
 interface GlazeTheme {
   /** The hue seed (0–360). */
   readonly hue: number;
   /** The saturation seed (0–100). */
   readonly saturation: number;
+  /** The dark-scheme hue seed (0–360), or `undefined` when `hue` is reused. */
+  readonly darkHue: number | undefined;
+  /** The dark-scheme saturation seed (0–100), or `undefined` when `saturation` is reused. */
+  readonly darkSaturation: number | undefined;
   /** The effective config for this theme. */
   getConfig(): GlazeConfigResolved;
   /** Add/replace colors (additive merge with existing definitions). */
@@ -988,6 +1149,10 @@ interface GlazeTheme {
 interface GlazeExtendOptions {
   hue?: number;
   saturation?: number;
+  /** Replace the dark-scheme hue seed (0–360). Defaults to the parent's. */
+  darkHue?: number;
+  /** Replace the dark-scheme saturation seed (0–100). Defaults to the parent's. */
+  darkSaturation?: number;
   colors?: ColorMap;
   /** Config override for the child theme. Merged with the parent's override. */
   config?: GlazeConfigOverride;
@@ -1341,19 +1506,23 @@ type PaletteInput = Record<string, GlazeTheme>;
  * the theme still reacts to later `configure()` calls for fields it
  * didn't override.
  *
+ * The object form also accepts `darkHue` / `darkSaturation` — a separate
+ * seed pair for the dark and dark-high-contrast schemes. Both default to
+ * their light counterparts, and an explicit `darkSaturation` opts the theme
+ * out of the global `darkDesaturation` reduction.
+ *
  * @example
  * ```ts
  * const primary = glaze(280, 80);
  * // or shorthand:
  * const primary = glaze({ hue: 280, saturation: 80 });
+ * // with a retuned dark seed:
+ * const primary = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
  * // with config override:
  * const raw = glaze(280, 80, { lightTone: false });
  * ```
  */
-declare function glaze(hueOrOptions: number | {
-  hue: number;
-  saturation: number;
-}, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
+declare function glaze(hueOrOptions: number | GlazeThemeSeed, saturation?: number, config?: GlazeConfigOverride): GlazeTheme;
 declare namespace glaze {
   var configure: (config: GlazeConfig) => void;
   var palette: (themes: PaletteInput, options?: GlazePaletteOptions) => GlazePalette;
@@ -1388,6 +1557,11 @@ interface HuePlan {
 }
 interface ChannelCtx {
   seedHue: number;
+  /**
+   * Dark-scheme seed hue, when the theme authored one. Drives the dark
+   * `--{baseName}-hue` value; falls back to `seedHue`.
+   */
+  darkSeedHue?: number;
   /** Theme-level hue var base name (without `--` / `-hue`). */
   baseName: string;
   /** Token / custom-property name prefix used for hue var naming (`brand-` etc.). */
@@ -1632,5 +1806,5 @@ declare function srgbToHex(rgb: [number, number, number]): `#${string}`;
  */
 declare function okhslToOklch(h: number, s: number, l: number, pastel?: boolean): [number, number, number];
 //#endregion
-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, GLAZE_EXPORT_VERSION, 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 GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, 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, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
+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, GLAZE_EXPORT_VERSION, 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 GlazeExportKind, type GlazeExportVersion, type GlazeExtendOptions, type GlazeFromInput, type GlazeJsonOptions, type GlazeOutputModes, type GlazePalette, type GlazePaletteExport, type GlazePaletteExportOptions, type GlazePaletteOptions, type GlazeShadowInput, type GlazeTailwindOptions, type GlazeTheme, type GlazeThemeExport, type GlazeThemeSeed, 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, isColorTokenExport, isPaletteExport, isThemeExport, normalizeRole, okhslToLinearSrgb, okhslToOkhst, okhslToOklab, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, oppositeRole, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveApcaTarget, resolveContrastForLevel, resolveContrastForMode, resolveMinContrast, roleToPolarity, srgbToHex, srgbToOkhsl, toTone, toneFromY, variantToOkhsl, yFromTone };
 //# sourceMappingURL=index.d.mts.map