@tenphi/glaze 1.1.0 → 1.2.0

package/docs/api.md

@@ -11,6 +11,7 @@ Full reference for every public method, option, and type exported by `@tenphi/gl
   - [Tailwind CSS](#themetailwindoptions)
 - [High-contrast pairs](#high-contrast-pairs)
 - [Color definitions](#color-definitions)
+  - [Dark seed](#dark-seed-darkhue--darksaturation)
 - [Standalone color tokens](#standalone-color-tokens)
 - [Shadows](#shadows)
 - [Mix colors](#mix-colors)
@@ -31,7 +32,7 @@ Full reference for every public method, option, and type exported by `@tenphi/gl
 | Method                                | Description                                                                                                           |
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `glaze(hue, saturation?, config?)`    | Create a theme from hue (0–360) and saturation (0–100). Optional `config` overrides the global config for this theme. |
-| `glaze({ hue, saturation }, config?)` | Create a theme from an options object, with optional per-theme config override.                                       |
+| `glaze({ hue, saturation, darkHue?, darkSaturation? }, config?)` | Create a theme from an options object, with optional per-theme config override. `darkHue` / `darkSaturation` seed the dark schemes — see [Dark seed](#dark-seed-darkhue--darksaturation). |
 | `glaze.themeFrom(data)`               | Create a theme from a `theme.export()` snapshot (`kind: 'theme'`).                                                    |
 | `glaze.from(data)`                    | Compat alias for `glaze.themeFrom`.                                                                                   |
 | `glaze.fromHex(hex)`                  | Create a theme from a hex color (`#rgb` or `#rrggbb`). Extracts hue and saturation.                                   |
@@ -45,6 +46,7 @@ Full reference for every public method, option, and type exported by `@tenphi/gl
 ```ts
 const a = glaze(280, 80);
 const b = glaze({ hue: 280, saturation: 80 });
+const bDark = glaze({ hue: 280, saturation: 80, darkHue: 268, darkSaturation: 65 });
 const c = glaze.fromHex('#7a4dbf');
 const d = glaze.fromRgb(122, 77, 191);
 const e = glaze.themeFrom(a.export());
@@ -75,6 +77,8 @@ A `GlazeTheme` exposes:
 | ------------------------------- | --------------------------------------------------------------------------------------------------- |
 | `theme.hue` (readonly)          | The hue seed (0–360).                                                                               |
 | `theme.saturation` (readonly)   | The saturation seed (0–100).                                                                        |
+| `theme.darkHue` (readonly)      | The dark-scheme hue seed (0–360), or `undefined` when `hue` is reused.                              |
+| `theme.darkSaturation` (readonly) | The dark-scheme saturation seed (0–100), or `undefined` when `saturation` is reused.              |
 | `theme.colors(defs)`            | Add/replace colors (additive merge — adds new, overwrites existing by name, doesn't remove others). |
 | `theme.color(name)`             | Get a color definition by name.                                                                     |
 | `theme.color(name, def)`        | Set a single color definition.                                                                      |
@@ -128,6 +132,8 @@ const highSat = base.extend({ config: { darkTone: [10, 100] } });
 | ------------ | --------------------- | -------------------------------------------------------------------------------------------- |
 | `hue`        | `number`              | Replace the hue seed. Defaults to the parent's hue.                                          |
 | `saturation` | `number`              | Replace the saturation seed. Defaults to the parent's saturation.                            |
+| `darkHue`    | `number`              | Replace the dark hue seed. Defaults to the parent's `darkHue`.                               |
+| `darkSaturation` | `number`          | Replace the dark saturation seed. Defaults to the parent's `darkSaturation`.                 |
 | `colors`     | `ColorMap`            | Per-theme overrides (additive merge over the inherited map).                                 |
 | `config`     | `GlazeConfigOverride` | Config override for the child. Shallow-merged with the parent's override — child fields win. |
 
@@ -417,6 +423,8 @@ type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 | `tone`       | `HCPair<ToneValue>`             | Number = absolute (0–100). `'+N'`/`'-N'` = a signed **tone delta** from the base (requires `base`). `'max'`/`'min'` = forced to the scheme's tone extreme (no `base`). Optional HC pair `[normal, hc]`.                                                                            |
 | `saturation` | `number`                        | Saturation factor applied to the seed saturation (0–1). Default: `1`.                                                                                                                                                                                                              |
 | `hue`        | `number \| RelativeValue`       | Number = absolute (0–360). String (`'+N'`/`'-N'`) = relative to the **theme seed hue** (never to a base color).                                                                                                                                                                    |
+| `darkHue`    | `number \| RelativeValue`       | Dark-scheme hue. Number = absolute (0–360). String = relative to the **theme dark seed hue**. Falls back to `hue`. See [Dark seed](#dark-seed-darkhue--darksaturation).                                                                                                            |
+| `darkSaturation` | `number`                    | Dark-scheme saturation factor (0–1) over the dark seed saturation. Falls back to `saturation`. When set, the global `darkDesaturation` reduction is **not** applied on top.                                                                                                        |
 | `base`       | `string`                        | Name of another color in the same theme — makes this a _dependent_ color.                                                                                                                                                                                                          |
 | `contrast`   | `HCPair<ContrastSpec>`          | Contrast floor against `base`. Requires `base`. See [`contrast`](#contrast-floor).                                                                                                                                                                                                 |
 | `mode`       | `'auto' \| 'fixed' \| 'static'` | Adaptation mode. Default: `'auto'`. See [Adaptation modes](#adaptation-modes).                                                                                                                                                                                                     |
@@ -437,7 +445,7 @@ can drift in measured luminance. See [OKHST in Glaze](okhst.md). To port old
 | ------------------- | ----------------------- | --------------------------------------------------------------------------------------------- |
 | Number (absolute)   | `tone: 45`              | Absolute tone 0–100.                                                                          |
 | String (tone delta) | `tone: '-52'`           | Signed difference from the base color's resolved tone (requires `base`).                      |
-| Extreme             | `tone: 'max'` / `'min'` | Force to the scheme's highest (`'max'` = 100) or lowest (`'min'` = 0) tone. No `base` needed. |
+| Extreme             | `tone: 'max'` / `'min'` | Force to the scheme's highest (`'max'` = 100) or lowest (`'min'` = 0) tone. With a `base`, the light-scheme shift is replayed in dark. No `base` needed. |
 | HC pair             | `tone: ['-7', '-20']`   | `[normal, high-contrast]`. A single value applies to both.                                    |
 
 **Absolute tone** on a dependent color (`base` set) positions the color independently. In dark mode it is tone-mapped (inverted + windowed) on its own. The `contrast` solver acts as a safety net.
@@ -447,9 +455,21 @@ It gives an exact contrast step for neutrals and a stable visual progression for
 chromatic colors. In dark mode with `mode: 'auto'`, it is anchored to the
 base's per-scheme tone. If `base + delta` falls outside `[0, 100]`, the result
 is clamped to the boundary, or — with `autoFlip` (default on) — mirrored to the
-other side of the base.
+other side of the base. If the mirrored target is also out of range, the original
+delta is kept and clamped on the authored side.
 
-**Extreme tone** (`'max'` / `'min'`) forces the color to the scheme's tone extreme without a contrast hack or a magic number. `'max'` resolves to author tone 100 and `'min'` to 0; both flow through scheme mapping like an absolute tone, so under `mode: 'auto'` they invert in dark (`'max'` is lightest in light, darkest in dark). Use `mode: 'static'` to pin the same extreme across schemes, or `mode: 'fixed'` to keep the same end without inverting. No `base` required.
+**Extreme tone** (`'max'` / `'min'`) forces the color to the scheme's tone extreme without a contrast hack or a magic number. `'max'` resolves to author tone 100 and `'min'` to 0. Without a `base`, both flow through scheme mapping like an absolute tone, so under `mode: 'auto'` they invert in dark (`'max'` is lightest in light, darkest in dark). Use `mode: 'static'` to pin the same extreme across schemes, or `mode: 'fixed'` to keep the same end without inverting. No `base` required.
+
+**Extreme tone with a `base`** keeps the pair's contrast across schemes. The tone windows are asymmetric by default (`lightTone: [10, 100]`, `darkTone: [15, 95]`), so re-mapping the extreme through the dark window would squeeze the base-to-extreme span and cost contrast. Instead Glaze measures the tone shift the light scheme applied between the base and the extreme, then replays it against the base's resolved dark tone — mirrored under `mode: 'auto'` (both ends invert), same-signed under `'fixed'`. The result is clamped to `[0, 100]` only, so it may cross the `darkTone` window edge; that is intentional, since the author asked for the extreme. When the shift does not fit above or below the dark base, the color pins at tone 100 / 0. `mode: 'static'` is unaffected, and high-contrast variants already use the full range.
+
+```ts
+theme.colors({
+  bg: { tone: 60 },
+  fg: { base: 'bg', tone: 'max' },
+});
+// light: bg 62.0, fg 100.0 — shift +38.0, contrast 3.18:1
+// dark:  bg 43.9, fg 5.9   — shift -38.0, contrast 3.18:1
+```
 
 A dependent color with `base` but no `tone` inherits the base's tone (equivalent to a delta of 0).
 
@@ -457,7 +477,7 @@ A dependent color with `base` but no `tone` inherits the base's tone (equivalent
 
 `autoFlip` governs what happens when a result would fall outside its valid range:
 
-- **Relative `tone` overshoot:** when `base ± delta` exceeds `[0, 100]`, `autoFlip` mirrors the delta to the other side of the base (e.g. `'+30'` becomes `'-30'`) instead of clamping to the boundary.
+- **Relative `tone` overshoot:** when `base ± delta` exceeds `[0, 100]`, `autoFlip` mirrors the delta to the other side of the base (e.g. `'+30'` becomes `'-30'`) instead of clamping to the boundary. If the mirrored target is also outside `[0, 100]`, the original delta is kept and clamped on the authored side.
 - **`contrast` direction:** when the requested tone direction can't meet the floor, `autoFlip` lets the solver try the opposite side (the same behavior as the global `autoFlip`).
 
 `autoFlip` defaults to the global `autoFlip` (`true`). Set `autoFlip: false` on a color to clamp instead of mirror — useful when you want a relative offset to stay on the authored side of the base, or to keep an unmet contrast pinned to one direction's extreme.
@@ -548,6 +568,48 @@ theme.colors({
 
 Relative hue is always relative to the **theme seed hue**, not to a base color.
 
+#### Dark seed (`darkHue` / `darkSaturation`)
+
+Tone inverts automatically between light and dark, but hue and saturation do
+not — by default every scheme reuses the one seed, with dark getting a flat
+`darkDesaturation` haircut. When a palette needs a genuinely different chroma in
+dark (a cooler accent, a calmer surface tint), author a second seed:
+
+```ts
+const theme = glaze({
+  hue: 280,
+  saturation: 80,
+  darkHue: 268, // dark schemes seed from 268 instead of 280
+  darkSaturation: 65, // and from 65 instead of 80
+});
+```
+
+Individual colors can override either channel for dark on their own:
+
+```ts
+theme.colors({
+  surface: { tone: 97 },
+  accent: { tone: 55, hue: '+20', darkHue: '+35' },
+  warning: { tone: 60, saturation: 0.9, darkSaturation: 0.6 },
+});
+```
+
+Both apply to the `dark` **and** `darkContrast` variants. The rules:
+
+| Rule | Behavior |
+| ---- | -------- |
+| Units | Seed-level `darkSaturation` is `0–100` (like `saturation` on the theme). Def-level `darkSaturation` is a `0–1` factor (like `saturation` on a color def). |
+| Fallback | `darkHue` falls back to `hue`, `darkSaturation` to `saturation`, and the def falls back to the seed. Omitting everything reproduces the previous behavior exactly. |
+| Relative hue | `darkHue: '+N'` anchors to the theme's **dark** seed hue. A plain `hue: '+N'` with no `darkHue` also re-anchors to the dark seed, so a whole palette rotates together. |
+| Absolute hue | An absolute `hue` (no `darkHue`) is used verbatim in dark — absolute means absolute in every scheme. |
+| `darkDesaturation` | Bypassed as soon as any explicit dark saturation is authored, at either level. The value you write is the value you get. |
+| `mode: 'static'` | Ignores both. A static color is pinned to one hue and saturation across every scheme. |
+| Shadows and mixes | Have no channels of their own — they derive hue and saturation from their `bg` / `fg` / `target`, so they inherit dark overrides automatically. |
+
+With [`splitHue`](#hue-channel-splitting-splithue), a dark seed makes the hue
+custom properties scheme-dependent; Glaze re-declares them in the dark block
+automatically.
+
 #### Per-color `pastel`
 
 `pastel: true` on a single color def overrides the per-theme / per-token `pastel` override for that color only. It toggles the hue-independent "safe" chroma limit used in every OKHSL↔sRGB conversion that touches this color: luminance calculations during contrast solving, gamut clamping during sRGB blend / mix edges, and output formatting. The effective flag is carried on the resolved variant (`ResolvedColorVariant.pastel`) so formatting matches the gamut mapping applied during resolution.
@@ -687,6 +749,9 @@ glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?:
 | `saturation`       | `number`                             | 0–100.                                                                                                                                          |
 | `tone`             | `HCPair<number \| ExtremeValue>`     | 0–100 (contrast-shaped) or `'max'`/`'min'`, optional HC pair.                                                                                   |
 | `saturationFactor` | `number`                             | Multiplier on the seed (0–1). Default: `1`.                                                                                                     |
+| `darkHue`          | `number \| RelativeValue`            | Dark-scheme hue. Absolute (0–360) or `'+N'`/`'-N'` relative to the dark seed hue (which defaults to `hue`). Falls back to `hue`.                 |
+| `darkSaturation`   | `number`                             | Dark-scheme seed saturation (0–100). Falls back to `saturation`.                                                                                |
+| `darkSaturationFactor` | `number`                         | Dark-scheme multiplier on the dark seed (0–1). Falls back to `saturationFactor`.                                                                |
 | `mode`             | `AdaptationMode`                     | Default: `'auto'`.                                                                                                                              |
 | `autoFlip`         | `boolean`                            | Flip out-of-bounds results instead of clamping. Default: global `autoFlip`.                                                                     |
 | `opacity`          | `number`                             | Fixed alpha 0–1.                                                                                                                                |
@@ -705,6 +770,9 @@ glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?:
 | `saturation`       | Override seed saturation (0–100).                                                                                                                           |
 | `tone`             | Number (absolute 0–100), `'+N'`/`'-N'`, or `'max'`/`'min'`. Without `base`, relative anchors to the seed; with `base`, anchors to `base`'s tone per scheme. |
 | `saturationFactor` | Multiplier on the seed (0–1).                                                                                                                               |
+| `darkHue`          | Dark-scheme hue: absolute (0–360) or `'+N'`/`'-N'` relative to the dark seed hue. Falls back to `hue`.                                                      |
+| `darkSaturation`   | Dark-scheme seed saturation (0–100). Falls back to `saturation`.                                                                                            |
+| `darkSaturationFactor` | Dark-scheme multiplier on the dark seed (0–1). Falls back to `saturationFactor`.                                                                        |
 | `mode`             | `'auto'` (default) / `'fixed'` / `'static'`.                                                                                                                |
 | `autoFlip`         | Flip out-of-bounds results instead of clamping. Default: global `autoFlip`.                                                                                 |
 | `contrast`         | Contrast floor (WCAG or APCA). Without `base`, anchored to the literal seed; with `base`, solved per scheme.                                                |
@@ -1357,6 +1425,21 @@ On `theme.css()`, `theme.tasty()`, `palette.css()`, `palette.tasty()`, and stand
 
 **Requirements:** every exported color must be pastel (`pastel: true` on the theme/token override or per-color). Pastel mode bounds chroma by the hue-independent safe chroma at each lightness, so emitted `C` stays in sRGB for any rotated hue. Non-pastel palettes throw rather than emit values that would clip under rotation.
 
+**Dark hues:** hue vars are scheme-independent unless the theme or a color authors a [dark hue](#dark-seed-darkhue--darksaturation). When one does, the whole hue set is re-declared in the dark block (and in the Tasty dark state, gated by `modes.dark`):
+
+```css
+/* glaze({ hue: 240, saturation: 18, darkHue: 200 }) */
+:root {
+  --brand-hue: 240;
+  --accent-hue: calc(var(--brand-hue) + 20);
+}
+/* dark */
+--brand-hue: 200;
+--accent-hue: calc(var(--brand-hue) + 20);
+```
+
+`--accent-hue` repeats verbatim on purpose: a custom property substitutes `var()` at computed-value time on the element that declares it, so it has to be re-declared to pick up the new `--brand-hue`. Colors with `mode: 'static'` are pinned to an absolute hue instead, so they don't drift with the dark seed.
+
 **Limitations:** `oklch` only (native CSS `var()` in the hue slot). Shadow and mix colors stay inline (blended hue). Standalone `.token()` / `.tasty()` do not support `splitHue` (return shape cannot carry the `$name-hue` declaration).
 
 `theme.dtcg()` / `theme.dtcgResolver()` / `palette.dtcg()` / `palette.dtcgResolver()` ignore `format` — DTCG emits structured `$value` objects, not CSS strings. Use the `colorSpace` option (`'srgb'` or `'oklch'`) to pick the color representation instead.
@@ -1390,7 +1473,7 @@ Light: accent-fill tone=52, accent-text tone='+20' → lighter than the fill
 Dark:  accent-fill maps into the dark window, sign preserved
 ```
 
-Offsets that would push past `[0, 100]` clamp to the boundary, or — with `autoFlip` (default on) — mirror to the other side of the base. Set `autoFlip: false` to keep the authored side and clamp instead.
+Offsets that would push past `[0, 100]` clamp to the boundary, or — with `autoFlip` (default on) — mirror to the other side of the base. If the mirror also overshoots, the original side is kept and clamped. Set `autoFlip: false` to keep the authored side and clamp instead.
 
 **`static`** — no adaptation, same tone in every scheme.
 
@@ -1541,7 +1624,7 @@ available result.
 | Relative `tone` without `base` in a **theme** color | Validation error                                                                                         |
 | `contrast` without `base` in `glaze.color()`        | Anchors against the literal seed (no error)                                                              |
 | Relative `tone` without `base` in `glaze.color()`   | Anchors against the literal seed (no error)                                                              |
-| Relative `tone` overshoots `[0, 100]`               | Mirror to the other side of the base (`autoFlip` on, default), or clamp to the boundary (`autoFlip` off) |
+| Relative `tone` overshoots `[0, 100]`               | Mirror to the other side of the base (`autoFlip` on, default), or clamp to the boundary (`autoFlip` off). If the mirror also overshoots, clamp on the authored side. |
 | `tone` resolves outside 0–100                       | Clamp silently                                                                                           |
 | `'max'` / `'min'` without `base`                    | Allowed — resolves to the scheme's tone extreme (root color)                                             |
 | `saturation` outside 0–1                            | Clamp silently                                                                                           |

package/docs/methodology.md

@@ -123,6 +123,29 @@ Per-color `saturation` is a factor of the theme seed, not an absolute
 saturation. With `SEED_SATURATION = 80`, `saturation: 0.25` means one quarter of
 that seed.
 
+### When dark needs its own chroma
+
+Dark schemes get a flat `darkDesaturation` haircut (10% by default), which is
+enough for most palettes. Reach for a second seed only when dark is wrong in a
+way a uniform reduction cannot fix — a hue that reads muddy against dark
+surfaces, or an accent that stays gaudy no matter how much you dial the global
+knob:
+
+```ts
+const primary = glaze({
+  hue: PURPLE_HUE,
+  saturation: SEED_SATURATION,
+  darkHue: PURPLE_HUE - 12, // cooler purple on dark surfaces
+  darkSaturation: 62, // calmer than a 10% haircut would give
+});
+```
+
+An explicit `darkSaturation` replaces `darkDesaturation` rather than stacking
+with it, so the number you write is the number you get. Prefer tuning the seed
+over per-color `darkHue` / `darkSaturation`: one seed keeps the palette
+coherent, while scattered per-color dark overrides drift apart as the palette
+grows. Save the per-color form for the one or two tokens that genuinely need it.
+
 ## Naming
 
 Prefer purpose first and variant last:
@@ -288,6 +311,11 @@ When a token needs the scheme extreme, use `tone: 'min'` or `tone: 'max'`
 directly. Avoid large magic numbers or fake contrast floors just to push a color
 to the edge.
 
+Pair the extreme with a `base` when the gap between the two has to survive the
+scheme switch. Glaze then replays the light-scheme tone shift against the
+resolved dark base instead of re-mapping the extreme through the dark window,
+so a knockout on a surface keeps the same contrast in both schemes.
+
 ## Fixed surfaces and accent fills
 
 Use `mode: 'fixed'` when the authored color should stay recognizable across

package/docs/okhst.md

@@ -44,7 +44,9 @@ surface: {
 }
 ```
 
-`'max'` and `'min'` select the corresponding end of the active scheme.
+`'max'` and `'min'` select the corresponding end of the active scheme. With a
+`base`, they instead preserve their distance from that base across schemes —
+see [Scheme adaptation](#scheme-adaptation).
 
 ### Tone delta
 
@@ -115,6 +117,24 @@ authored tone
 
 Dark schemes also apply `darkDesaturation` unless the color is `static`.
 
+**Hue and saturation are authoring inputs, not part of the tone transfer.** The
+tone axis is the only channel OKHST adapts across schemes; `h` and `s` pass
+through verbatim, with `darkDesaturation` as the one automatic adjustment.
+A theme (or a single color) can seed a different hue and saturation for the
+dark schemes via `darkHue` / `darkSaturation` — see
+[api.md](api.md#dark-seed-darkhue--darksaturation). Those pick the `h` and `s`
+that enter the pipeline above; they never change how tone is transferred.
+Authoring a dark saturation replaces the `darkDesaturation` step rather than
+stacking with it, and `static` colors ignore both.
+
+**Extremes with a base** take a different dark path. Because the light and dark
+windows are asymmetric, running an extreme through the dark window compresses
+the span between it and its base, which lowers contrast. For a color with both
+`base` and `tone: 'max'` / `'min'`, Glaze measures the tone shift the light
+scheme produced between the two, then replays it against the base's resolved
+dark tone (mirrored under `auto`, same-signed under `fixed`). Only `[0, 100]`
+clamping applies, so such a color may render past the `darkTone` boundary.
+
 ## Reference and render epsilon
 
 `REF_EPS = 0.05` defines Glaze's canonical tone scale. It is used for OKHST

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/glaze",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "OKHST-based color theme generator with WCAG contrast solving for light, dark, and high-contrast schemes",
   "type": "module",
   "main": "./dist/index.cjs",