@tenphi/glaze 1.3.1 → 1.5.0

package/dist/index.d.cts

@@ -234,9 +234,10 @@ interface GlazeOutputModes {
   /**
    * 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".
+   * Independent of `contrastLevel` — the level positions the normal variants
+   * while these stay the true high-contrast resolution, so the two compose. The
+   * exception is a global level of 100, where the normal variants already *are*
+   * the high-contrast ones: the tier would duplicate them and is dropped.
    * @see GlazeConfig.contrastLevel
    */
   highContrast?: boolean;
@@ -271,14 +272,44 @@ interface OklchColor {
   h: number;
 }
 interface RegularColorDef {
+  /**
+   * Seed this color from a literal color instead of from the theme.
+   *
+   * Accepts the same values as `glaze.color()` — hex, `rgb()`, `hsl()`,
+   * `okhsl()`, `okhst()`, `oklch()`, or a value object. It supplies three
+   * things at once: `hue`, `tone`, and — unlike every other color in a theme —
+   * an **absolute saturation** rather than a factor of the seed. That last
+   * part is the point: a color can now be more saturated than its theme, so
+   * honoring a brand color no longer means re-seeding the whole theme to reach
+   * it.
+   *
+   * The **light, normal-contrast** variant reproduces the value exactly
+   * (a local `lightTone: false`, matching the value-shorthand form of
+   * `glaze.color()`). Dark and high-contrast variants adapt as usual — they
+   * are where readability outranks fidelity, and a color pinned across every
+   * scheme would defeat both. A `contrast` floor still applies everywhere and
+   * still only moves the color when the authored value misses it.
+   *
+   * Sibling fields override what the value supplied, so
+   * `{ from: '#2F5BFF', hue: 300 }` keeps its saturation and tone but rotates
+   * the hue.
+   */
+  from?: GlazeColorValue;
   /**
    * 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).
+   *
+   * Defaults to the tone of `from` when that is set.
    */
   tone?: HCPair<ToneValue>;
-  /** Saturation factor applied to the seed saturation (0–1, default: 1). */
+  /**
+   * Saturation factor applied to the seed saturation (0–1, default: 1).
+   *
+   * With `from`, an explicit value here is still a factor of the seed and
+   * overrides the absolute saturation the color carried.
+   */
   saturation?: number;
   /**
    * Hue override for this color.
@@ -542,15 +573,15 @@ interface GlazeConfig {
   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.
+   * contrast (`100`), or `'auto'` (the default) to take the authored normal
+   * entries as-is.
    *
-   * 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".
+   * With a number, Glaze resolves the `light` / `dark` variants *at* that level.
+   * That is all it does: `lightContrast` / `darkContrast` stay the true
+   * high-contrast resolution at every level, and `modes.highContrast` alone
+   * decides whether they are emitted. Level `0` therefore reproduces `'auto'`
+   * bit for bit. At `100` the normal variants *are* the high-contrast ones, so a
+   * separate tier would duplicate them and a global level of 100 drops it.
    *
    * The level interpolates all three things that make high contrast differ:
    * authored `[normal, highContrast]` pairs, the tone-window widening, and
@@ -600,8 +631,8 @@ interface GlazeConfigResolved {
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
   /**
-   * Manual contrast level (0–100), or `'auto'` for the two-tier
-   * normal + high-contrast model.
+   * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
+   * the authored normal entries as-is.
    * @see GlazeConfig.contrastLevel
    */
   contrastLevel: number | 'auto';
@@ -631,8 +662,10 @@ interface GlazeConfigOverride {
   /** 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.
+   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out of a
+   * global level and take the authored normal entries as-is. Either way the
+   * instance keeps its high-contrast tier; a per-instance level never changes
+   * which modes are emitted.
    *
    * Only an instance-authored level is frozen into `.export()` snapshots — a
    * level inherited from the global config is treated as a live preference and

package/dist/index.d.mts

@@ -234,9 +234,10 @@ interface GlazeOutputModes {
   /**
    * 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".
+   * Independent of `contrastLevel` — the level positions the normal variants
+   * while these stay the true high-contrast resolution, so the two compose. The
+   * exception is a global level of 100, where the normal variants already *are*
+   * the high-contrast ones: the tier would duplicate them and is dropped.
    * @see GlazeConfig.contrastLevel
    */
   highContrast?: boolean;
@@ -271,14 +272,44 @@ interface OklchColor {
   h: number;
 }
 interface RegularColorDef {
+  /**
+   * Seed this color from a literal color instead of from the theme.
+   *
+   * Accepts the same values as `glaze.color()` — hex, `rgb()`, `hsl()`,
+   * `okhsl()`, `okhst()`, `oklch()`, or a value object. It supplies three
+   * things at once: `hue`, `tone`, and — unlike every other color in a theme —
+   * an **absolute saturation** rather than a factor of the seed. That last
+   * part is the point: a color can now be more saturated than its theme, so
+   * honoring a brand color no longer means re-seeding the whole theme to reach
+   * it.
+   *
+   * The **light, normal-contrast** variant reproduces the value exactly
+   * (a local `lightTone: false`, matching the value-shorthand form of
+   * `glaze.color()`). Dark and high-contrast variants adapt as usual — they
+   * are where readability outranks fidelity, and a color pinned across every
+   * scheme would defeat both. A `contrast` floor still applies everywhere and
+   * still only moves the color when the authored value misses it.
+   *
+   * Sibling fields override what the value supplied, so
+   * `{ from: '#2F5BFF', hue: 300 }` keeps its saturation and tone but rotates
+   * the hue.
+   */
+  from?: GlazeColorValue;
   /**
    * 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).
+   *
+   * Defaults to the tone of `from` when that is set.
    */
   tone?: HCPair<ToneValue>;
-  /** Saturation factor applied to the seed saturation (0–1, default: 1). */
+  /**
+   * Saturation factor applied to the seed saturation (0–1, default: 1).
+   *
+   * With `from`, an explicit value here is still a factor of the seed and
+   * overrides the absolute saturation the color carried.
+   */
   saturation?: number;
   /**
    * Hue override for this color.
@@ -542,15 +573,15 @@ interface GlazeConfig {
   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.
+   * contrast (`100`), or `'auto'` (the default) to take the authored normal
+   * entries as-is.
    *
-   * 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".
+   * With a number, Glaze resolves the `light` / `dark` variants *at* that level.
+   * That is all it does: `lightContrast` / `darkContrast` stay the true
+   * high-contrast resolution at every level, and `modes.highContrast` alone
+   * decides whether they are emitted. Level `0` therefore reproduces `'auto'`
+   * bit for bit. At `100` the normal variants *are* the high-contrast ones, so a
+   * separate tier would duplicate them and a global level of 100 drops it.
    *
    * The level interpolates all three things that make high contrast differ:
    * authored `[normal, highContrast]` pairs, the tone-window widening, and
@@ -600,8 +631,8 @@ interface GlazeConfigResolved {
   shadowTuning?: ShadowTuning;
   autoFlip: boolean;
   /**
-   * Manual contrast level (0–100), or `'auto'` for the two-tier
-   * normal + high-contrast model.
+   * Manual contrast level (0–100) for the normal variants, or `'auto'` to take
+   * the authored normal entries as-is.
    * @see GlazeConfig.contrastLevel
    */
   contrastLevel: number | 'auto';
@@ -631,8 +662,10 @@ interface GlazeConfigOverride {
   /** 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.
+   * Manual contrast level (0–100) for this instance, or `'auto'` to opt out of a
+   * global level and take the authored normal entries as-is. Either way the
+   * instance keeps its high-contrast tier; a per-instance level never changes
+   * which modes are emitted.
    *
    * Only an instance-authored level is frozen into `.export()` snapshots — a
    * level inherited from the global config is treated as a live preference and