@tenphi/glaze 0.9.3 → 0.10.0

package/dist/index.d.cts

@@ -294,21 +294,189 @@ interface GlazeThemeExport {
 }
 /** 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, an `OkhslColor` object, or an `[r, g, b]`
+   * (0–255) tuple. 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>;
   saturationFactor?: number;
   mode?: AdaptationMode;
+  /**
+   * Fixed opacity (0–1). Output includes alpha in the CSS value.
+   * Combining with `contrast` is not recommended (perceived lightness
+   * 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 `lightness`
+   * anchor to the base per scheme.
+   */
+  base?: GlazeColorToken | GlazeColorValue;
+  /**
+   * WCAG contrast floor against `base`. Requires `base` to be set.
+   */
+  contrast?: HCPair<MinContrast>;
+  /**
+   * 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;
+}
+/**
+ * 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).
+ *
+ * The OKHSL object form `{ h, s, l }` matches Glaze's native shape
+ * (h: 0–360, s/l: 0–1). Passing 0–100 values for `s`/`l` throws with
+ * a hint to use the structured `{ hue, saturation, lightness }` form.
+ *
+ * The tuple form is `[r, g, b]` in 0–255, matching `glaze.fromRgb`'s
+ * range. Out-of-range or non-finite components throw.
+ */
+type GlazeColorValue = string | OkhslColor | readonly [number, number, number];
+/** Optional overrides for `glaze.color(value, overrides?)`. */
+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 lightness. Number is absolute (0–100); `'+N'`/`'-N'` is
+   * relative to the literal seed (the value passed to `glaze.color()`).
+   * Supports HCPair for high-contrast.
+   */
+  lightness?: HCPair<number | RelativeValue>;
+  /** Saturation multiplier on the seed (0–1). Default: 1. */
+  saturationFactor?: number;
+  /**
+   * Adaptation mode. Defaults vary by input form:
+   * - String inputs (`'#1a1a1a'`, `'rgb(...)'`, etc.): `'auto'` (Möbius
+   *   curve — pairs with the extended dark window to invert
+   *   `#000` ↔ `#fff` between light and dark).
+   * - `OkhslColor` and `[r, g, b]` tuple inputs: `'fixed'` (linear,
+   *   preserves light lightness exactly).
+   *
+   * Pass `'fixed'` explicitly to opt a string input back into the
+   * linear, non-inverting mapping; pass `'static'` to pin the same
+   * lightness across every variant.
+   */
+  mode?: AdaptationMode;
+  /**
+   * WCAG 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`.
+   */
+  contrast?: HCPair<MinContrast>;
+  /**
+   * Optional dependency on another color. Accepts either a
+   * `GlazeColorToken` (returned by another `glaze.color()`) or a raw
+   * `GlazeColorValue` (hex / `rgb()` / `OkhslColor` / `[r, g, b]`),
+   * 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 `lightness: '+N'` / `'-N'` is anchored to the base's
+   *   lightness 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.
+   *
+   * 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 lightness
+   * 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-call lightness-window overrides for `glaze.color()`. Mirrors
+ * the field names from `GlazeConfig`.
+ *
+ * Defaults for `glaze.color()` vary by input form, and both fields are
+ * snapshotted from `globalConfig` at color-creation time so later
+ * `glaze.configure()` calls don't retroactively change already-created
+ * tokens (and `token.export()` round-trips byte-for-byte):
+ *
+ * - **String inputs** (`'#1a1a1a'`, `'rgb(...)'`, `'okhsl(...)'`, ...):
+ *   - `lightLightness: false` — preserve input exactly.
+ *   - `darkLightness: [globalConfig.darkLightness[0], 100]` — extended
+ *     dark window so the auto-mode dark variant can Möbius-invert all
+ *     the way up to white.
+ *
+ * - **`OkhslColor` / `[r, g, b]` tuple / structured inputs**:
+ *   - `lightLightness: false` — preserve input exactly.
+ *   - `darkLightness: globalConfig.darkLightness` — same window
+ *     theme colors use, snapshotted at create time.
+ *
+ * Passing this object replaces both fields at once. To keep one
+ * field's default while overriding the other, restate the default
+ * explicitly.
+ */
+interface GlazeColorScaling {
+  /** Light-mode lightness window. `false` (default) preserves input. */
+  lightLightness?: false | [number, number];
+  /**
+   * Dark-mode lightness window. Snapshotted from `globalConfig` at
+   * create time: extended `[globalConfig.darkLightness[0], 100]` for
+   * string inputs, plain `globalConfig.darkLightness` for object /
+   * tuple / structured inputs. Pass `false` to preserve input
+   * lightness in dark mode too.
+   */
+  darkLightness?: false | [number, number];
+}
+/** 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: 'rgb' (matches `theme.css` default). */
+  format?: GlazeColorFormat;
+  /**
+   * Suffix appended to the name. Default: '-color' (matches
+   * `theme.css` default).
+   */
+  suffix?: string;
 }
 /** Return type for `glaze.color()`. */
 interface GlazeColorToken {
@@ -324,6 +492,66 @@ interface GlazeColorToken {
   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;
+  /**
+   * Serialize the token as a JSON-safe object. Captures the original
+   * input value, overrides, and scaling 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, overrides?, scaling?)`.
+   * - `'structured'`: created via `glaze.color({ hue, saturation, ... }, scaling?)`.
+   */
+  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;
+  /** Lightness scaling override, if any. */
+  scaling?: GlazeColorScaling;
+}
+/**
+ * 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;
+  lightness: HCPair<number>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+  opacity?: number;
+  base?: GlazeColorTokenExport | GlazeColorValue;
+  contrast?: HCPair<MinContrast>;
+  name?: string;
+}
+/**
+ * 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;
+  lightness?: HCPair<number | RelativeValue>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+  contrast?: HCPair<MinContrast>;
+  base?: GlazeColorTokenExport | GlazeColorValue;
+  opacity?: number;
+  name?: string;
 }
 interface GlazeTheme {
   /** The hue seed (0–360). */
@@ -495,11 +723,15 @@ declare namespace glaze {
     css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
   };
   var from: (data: GlazeThemeExport) => GlazeTheme;
-  var color: (input: GlazeColorInput) => GlazeColorToken;
+  var color: {
+    (input: GlazeColorInput, scaling?: GlazeColorScaling): GlazeColorToken;
+    (value: GlazeColorValue, overrides?: GlazeColorOverrides, scaling?: GlazeColorScaling): GlazeColorToken;
+  };
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
   var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => 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;
 }
@@ -512,6 +744,7 @@ declare namespace glaze {
  * computation for WCAG 2 contrast calculations, and multi-format output
  * (okhsl, rgb, hsl, oklch).
  */
+type Vec3 = [number, number, number];
 /**
  * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
  */
@@ -540,16 +773,42 @@ declare function okhslToSrgb(h: number, s: number, l: number): [number, number,
  * 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) => 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];
+/**
+ * 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).
@@ -572,5 +831,5 @@ declare function formatHsl(h: number, s: number, l: number): string;
  */
 declare function formatOklch(h: number, s: number, l: number): string;
 //#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 { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorScaling, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, 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, hslToSrgb, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -294,21 +294,189 @@ interface GlazeThemeExport {
 }
 /** 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, an `OkhslColor` object, or an `[r, g, b]`
+   * (0–255) tuple. 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>;
   saturationFactor?: number;
   mode?: AdaptationMode;
+  /**
+   * Fixed opacity (0–1). Output includes alpha in the CSS value.
+   * Combining with `contrast` is not recommended (perceived lightness
+   * 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 `lightness`
+   * anchor to the base per scheme.
+   */
+  base?: GlazeColorToken | GlazeColorValue;
+  /**
+   * WCAG contrast floor against `base`. Requires `base` to be set.
+   */
+  contrast?: HCPair<MinContrast>;
+  /**
+   * 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;
+}
+/**
+ * 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).
+ *
+ * The OKHSL object form `{ h, s, l }` matches Glaze's native shape
+ * (h: 0–360, s/l: 0–1). Passing 0–100 values for `s`/`l` throws with
+ * a hint to use the structured `{ hue, saturation, lightness }` form.
+ *
+ * The tuple form is `[r, g, b]` in 0–255, matching `glaze.fromRgb`'s
+ * range. Out-of-range or non-finite components throw.
+ */
+type GlazeColorValue = string | OkhslColor | readonly [number, number, number];
+/** Optional overrides for `glaze.color(value, overrides?)`. */
+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 lightness. Number is absolute (0–100); `'+N'`/`'-N'` is
+   * relative to the literal seed (the value passed to `glaze.color()`).
+   * Supports HCPair for high-contrast.
+   */
+  lightness?: HCPair<number | RelativeValue>;
+  /** Saturation multiplier on the seed (0–1). Default: 1. */
+  saturationFactor?: number;
+  /**
+   * Adaptation mode. Defaults vary by input form:
+   * - String inputs (`'#1a1a1a'`, `'rgb(...)'`, etc.): `'auto'` (Möbius
+   *   curve — pairs with the extended dark window to invert
+   *   `#000` ↔ `#fff` between light and dark).
+   * - `OkhslColor` and `[r, g, b]` tuple inputs: `'fixed'` (linear,
+   *   preserves light lightness exactly).
+   *
+   * Pass `'fixed'` explicitly to opt a string input back into the
+   * linear, non-inverting mapping; pass `'static'` to pin the same
+   * lightness across every variant.
+   */
+  mode?: AdaptationMode;
+  /**
+   * WCAG 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`.
+   */
+  contrast?: HCPair<MinContrast>;
+  /**
+   * Optional dependency on another color. Accepts either a
+   * `GlazeColorToken` (returned by another `glaze.color()`) or a raw
+   * `GlazeColorValue` (hex / `rgb()` / `OkhslColor` / `[r, g, b]`),
+   * 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 `lightness: '+N'` / `'-N'` is anchored to the base's
+   *   lightness 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.
+   *
+   * 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 lightness
+   * 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-call lightness-window overrides for `glaze.color()`. Mirrors
+ * the field names from `GlazeConfig`.
+ *
+ * Defaults for `glaze.color()` vary by input form, and both fields are
+ * snapshotted from `globalConfig` at color-creation time so later
+ * `glaze.configure()` calls don't retroactively change already-created
+ * tokens (and `token.export()` round-trips byte-for-byte):
+ *
+ * - **String inputs** (`'#1a1a1a'`, `'rgb(...)'`, `'okhsl(...)'`, ...):
+ *   - `lightLightness: false` — preserve input exactly.
+ *   - `darkLightness: [globalConfig.darkLightness[0], 100]` — extended
+ *     dark window so the auto-mode dark variant can Möbius-invert all
+ *     the way up to white.
+ *
+ * - **`OkhslColor` / `[r, g, b]` tuple / structured inputs**:
+ *   - `lightLightness: false` — preserve input exactly.
+ *   - `darkLightness: globalConfig.darkLightness` — same window
+ *     theme colors use, snapshotted at create time.
+ *
+ * Passing this object replaces both fields at once. To keep one
+ * field's default while overriding the other, restate the default
+ * explicitly.
+ */
+interface GlazeColorScaling {
+  /** Light-mode lightness window. `false` (default) preserves input. */
+  lightLightness?: false | [number, number];
+  /**
+   * Dark-mode lightness window. Snapshotted from `globalConfig` at
+   * create time: extended `[globalConfig.darkLightness[0], 100]` for
+   * string inputs, plain `globalConfig.darkLightness` for object /
+   * tuple / structured inputs. Pass `false` to preserve input
+   * lightness in dark mode too.
+   */
+  darkLightness?: false | [number, number];
+}
+/** 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: 'rgb' (matches `theme.css` default). */
+  format?: GlazeColorFormat;
+  /**
+   * Suffix appended to the name. Default: '-color' (matches
+   * `theme.css` default).
+   */
+  suffix?: string;
 }
 /** Return type for `glaze.color()`. */
 interface GlazeColorToken {
@@ -324,6 +492,66 @@ interface GlazeColorToken {
   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;
+  /**
+   * Serialize the token as a JSON-safe object. Captures the original
+   * input value, overrides, and scaling 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, overrides?, scaling?)`.
+   * - `'structured'`: created via `glaze.color({ hue, saturation, ... }, scaling?)`.
+   */
+  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;
+  /** Lightness scaling override, if any. */
+  scaling?: GlazeColorScaling;
+}
+/**
+ * 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;
+  lightness: HCPair<number>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+  opacity?: number;
+  base?: GlazeColorTokenExport | GlazeColorValue;
+  contrast?: HCPair<MinContrast>;
+  name?: string;
+}
+/**
+ * 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;
+  lightness?: HCPair<number | RelativeValue>;
+  saturationFactor?: number;
+  mode?: AdaptationMode;
+  contrast?: HCPair<MinContrast>;
+  base?: GlazeColorTokenExport | GlazeColorValue;
+  opacity?: number;
+  name?: string;
 }
 interface GlazeTheme {
   /** The hue seed (0–360). */
@@ -495,11 +723,15 @@ declare namespace glaze {
     css(options?: GlazeCssOptions & GlazePaletteExportOptions): GlazeCssResult;
   };
   var from: (data: GlazeThemeExport) => GlazeTheme;
-  var color: (input: GlazeColorInput) => GlazeColorToken;
+  var color: {
+    (input: GlazeColorInput, scaling?: GlazeColorScaling): GlazeColorToken;
+    (value: GlazeColorValue, overrides?: GlazeColorOverrides, scaling?: GlazeColorScaling): GlazeColorToken;
+  };
   var shadow: (input: GlazeShadowInput) => ResolvedColorVariant;
   var format: (variant: ResolvedColorVariant, colorFormat?: GlazeColorFormat) => 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;
 }
@@ -512,6 +744,7 @@ declare namespace glaze {
  * computation for WCAG 2 contrast calculations, and multi-format output
  * (okhsl, rgb, hsl, oklch).
  */
+type Vec3 = [number, number, number];
 /**
  * Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLab [L, a, b].
  */
@@ -540,16 +773,42 @@ declare function okhslToSrgb(h: number, s: number, l: number): [number, number,
  * 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) => 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];
+/**
+ * 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).
@@ -572,5 +831,5 @@ declare function formatHsl(h: number, s: number, l: number): string;
  */
 declare function formatOklch(h: number, s: number, l: number): string;
 //#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 { type AdaptationMode, type ColorDef, type ColorMap, type ContrastPreset, type FindLightnessForContrastOptions, type FindLightnessForContrastResult, type FindValueForMixContrastOptions, type FindValueForMixContrastResult, type GlazeColorCssOptions, type GlazeColorFormat, type GlazeColorInput, type GlazeColorInputExport, type GlazeColorOverrides, type GlazeColorOverridesExport, type GlazeColorScaling, type GlazeColorToken, type GlazeColorTokenExport, type GlazeColorValue, 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, hslToSrgb, okhslToLinearSrgb, okhslToOklab, okhslToSrgb, oklabToOkhsl, parseHex, parseHexAlpha, relativeLuminanceFromLinearRgb, resolveMinContrast, srgbToOkhsl };
 //# sourceMappingURL=index.d.mts.map