@tenphi/glaze 0.14.0 → 0.15.1

package/docs/api.md

@@ -219,6 +219,7 @@ type ColorDef = RegularColorDef | ShadowColorDef | MixColorDef;
 | `mode` | `'auto' \| 'fixed' \| 'static'` | Adaptation mode. Default: `'auto'`. See [Adaptation modes](#adaptation-modes). |
 | `flip` | `boolean` | Flip out-of-bounds results (relative `tone` overshoot / unmet `contrast`) to the opposite side instead of clamping. Default: the global `autoFlip` (`true`). See [`flip`](#flip). |
 | `opacity` | `number` | Fixed alpha 0–1. Output includes alpha in the CSS value. Combining with `contrast` is not recommended (a `console.warn` is emitted). |
+| `pastel` | `boolean` | Per-color override for the hue-independent "safe" chroma limit used in OKHSL↔sRGB conversions (luminance, contrast solving, output formatting). Falls through to the global / per-theme `pastel` config when omitted. Default: unset. See [Per-color `pastel`](#per-color-pastel). |
 | `inherit` | `boolean` | Whether this color is inherited by child themes via `extend()`. Default: `true`. Set to `false` to make the color local to the current theme. |
 
 #### Tone values
@@ -299,6 +300,38 @@ theme.colors({
 
 Relative hue is always relative to the **theme seed hue**, not to a base color.
 
+#### Per-color `pastel`
+
+`pastel: true` on a single color def overrides the global / per-theme `pastel` config 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.
+
+```ts
+const theme = glaze(280, 80);
+theme.colors({
+  plain: { tone: 50, saturation: 1 },
+  soft:  { tone: 50, saturation: 1, pastel: true },
+});
+// theme.resolve().get('soft')!.light.pastel === true
+// theme.css().light contains different rgb() triples for `--plain` and `--soft`
+```
+
+Omit the field to inherit the global / per-theme `pastel` config — useful for keeping the default behavior while opting a single accent into the pastel gamut.
+
+The flag is part of the def object, so `extend()` copies it through to child themes alongside the rest of the def. Override it again on the child to flip a single color back:
+
+```ts
+const parent = glaze(280, 80);
+parent.colors({ soft: { tone: 50, saturation: 1, pastel: true } });
+
+const child = parent.extend({
+  colors: { soft: { tone: 50, saturation: 1, pastel: false } },
+});
+// child.resolve().get('soft')!.light.pastel === false
+```
+
+> **Note:** Per-color `pastel` is also supported on `ShadowColorDef` and `MixColorDef` (see the tables above). For shadows the math itself happens in OKHSL space, so the flag mainly controls the gamut-mapped output formatting and any luminance verification for that variant.
+>
+> Standalone `glaze.color()` tokens accept the same `pastel` field on both the structured (`GlazeColorInput`) and value-shorthand (`GlazeColorOverrides`) forms, and it survives the `export()` / `glaze.colorFrom()` round-trip.
+
 ### `ShadowColorDef`
 
 | Field | Type | Description |
@@ -308,6 +341,7 @@ Relative hue is always relative to the **theme seed hue**, not to a base color.
 | `fg` | `string` | Optional foreground color name for tinting and intensity modulation. Must reference a non-shadow color. Omit for an achromatic shadow at full user-specified intensity. |
 | `intensity` | `HCPair<number>` | Shadow intensity, 0–100. Supports HC pairs. |
 | `tuning` | `ShadowTuning` | Per-color tuning overrides. Merged field-by-field with the global `shadowTuning`. |
+| `pastel` | `boolean` | Per-color `pastel` override. See [Per-color `pastel`](#per-color-pastel). |
 | `inherit` | `boolean` | Inheritance flag, default `true`. |
 
 See [Shadows](#shadows) below for the algorithm and tuning details.
@@ -323,6 +357,7 @@ See [Shadows](#shadows) below for the algorithm and tuning details.
 | `blend` | `'opaque' \| 'transparent'` | Default `'opaque'`. |
 | `space` | `'okhsl' \| 'srgb'` | Interpolation space for opaque blending. Default `'okhsl'`. Ignored for `'transparent'` (always composites in linear sRGB). |
 | `contrast` | `HCPair<ContrastSpec>` | Optional contrast floor against `base` (WCAG or APCA — see [`contrast`](#contrast-floor)). The solver adjusts the mix ratio (opaque) or opacity (transparent). |
+| `pastel` | `boolean` | Per-color `pastel` override. See [Per-color `pastel`](#per-color-pastel). |
 | `inherit` | `boolean` | Inheritance flag, default `true`. |
 
 See [Mix colors](#mix-colors) below.
@@ -378,6 +413,7 @@ glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?:
 | `opacity` | `number` | Fixed alpha 0–1. |
 | `base` | `GlazeColorToken \| GlazeColorValue` | Optional dependency. See [Pairing colors](#pairing-colors). |
 | `contrast` | `HCPair<ContrastSpec>` | Contrast floor against `base` (WCAG or APCA). Without `base`, anchored to the literal seed. |
+| `pastel` | `boolean` | Per-color `pastel` override. Falls through to the global / per-theme `pastel` config when omitted. See [Per-color `pastel`](#per-color-pastel). |
 | `name` | `string` | Debug label for warnings; doesn't change output keys. Reserved names (`'value'`, `'seed'`, `'externalBase'`) are rejected. |
 
 `GlazeFromInput` (from form) is `{ from: GlazeColorValue, ...colorOverrides }`:
@@ -394,6 +430,7 @@ glaze.color(color: GlazeFromInput | GlazeColorInput | GlazeColorValue, config?:
 | `contrast` | Contrast floor (WCAG or APCA). Without `base`, anchored to the literal seed; with `base`, solved per scheme. |
 | `base` | `GlazeColorToken` or raw `GlazeColorValue`. See [Pairing colors](#pairing-colors). |
 | `opacity` | Fixed alpha 0–1. Combining with `contrast` is not recommended — `console.warn` is emitted. |
+| `pastel` | Per-color `pastel` override. Falls through to the global / per-theme `pastel` config when omitted. See [Per-color `pastel`](#per-color-pastel). |
 | `name` | Debug label only — surfaces in warnings/errors. Does not change output keys. |
 
 Named CSS colors (`'red'`, `'blueviolet'`) are not supported.
@@ -404,7 +441,7 @@ Every input form defaults to `mode: 'auto'` so the resolved token adapts between
 
 - **Value-shorthand** (bare strings, value objects, and `{ from, ...overrides }`):
   - Light variant preserves the input tone exactly (`lightTone: false`).
-  - All other config fields (`darkTone`, `darkDesaturation`, `saturationTaper`, `autoFlip`) snapshot from `globalConfig` at create time.
+  - All other config fields (`darkTone`, `darkDesaturation`, `autoFlip`) snapshot from `globalConfig` at create time.
 - **Structured input** (`{ hue, saturation, tone, ... }`):
   - Both tone windows snapshot from `globalConfig` at create time (same as a theme color).
 - All fields are **snapshotted at color-creation time** — later `glaze.configure()` calls don't retroactively change existing tokens.
@@ -450,7 +487,6 @@ The optional `config` second argument (`GlazeConfigOverride`) overrides the reso
 | `lightTone` | `[10, 100]` | Light tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` (disable clamping). |
 | `darkTone` | `[15, 95]` | Dark tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` (disable clamping). |
 | `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). |
-| `saturationTaper` | `0.15` | Saturation taper strength toward the tone extremes (0–1). |
 | `autoFlip` | `true` | Default for each color's `flip`: when solving `contrast` (or applying a relative `tone` that overshoots), allow crossing to the opposite side instead of clamping. |
 | `shadowTuning` | `undefined` | Default shadow tuning (meaningful for themes; harmless on color tokens). |
 
@@ -989,10 +1025,6 @@ S_dark = S_light * (1 - darkDesaturation) // default: 0.1
 
 `static` mode skips desaturation.
 
-### Saturation taper
-
-`saturationTaper` (default `0.15`) gently reduces saturation toward the tone extremes, where in-gamut chroma collapses. It is the *strength* (0–1) — the maximum fraction of saturation removed at the very edges — ramped in smoothly over the outer ~15% of tone on each end. Mid-tones are untouched; `0` disables it.
-
 ---
 
 ## Configuration
@@ -1002,7 +1034,6 @@ glaze.configure({
   lightTone: [10, 100], // [lo, hi]; or { lo, hi, eps } / false to disable clamping
   darkTone: [15, 95],   // [lo, hi]; or { lo, hi, eps } / false to disable clamping
   darkDesaturation: 0.1,
-  saturationTaper: 0.15,
   states: {
     dark: '@dark',
     highContrast: '@high-contrast',
@@ -1027,7 +1058,6 @@ A `ToneWindow` is `[lo, hi]` (OKHSL-lightness endpoints, reference eps — the c
 | `lightTone` | `[10, 100]` | Light scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC. |
 | `darkTone` | `[15, 95]` | Dark scheme tone window: `[lo, hi]`, `{ lo, hi, eps }`, or `false` to disable clamping. Bypassed in HC. |
 | `darkDesaturation` | `0.1` | Saturation reduction in dark scheme (0–1). |
-| `saturationTaper` | `0.15` | Saturation taper strength toward the tone extremes (0–1). `0` disables. |
 | `states.dark` | `'@dark'` | State alias for dark mode tokens (Tasty export). |
 | `states.highContrast` | `'@high-contrast'` | State alias for HC tokens. |
 | `modes.dark` | `true` | Include dark variants in exports. |
@@ -1210,6 +1240,5 @@ import {
 | `maxIterations` | `18` | Max binary-search iterations per branch. |
 | `initialDirection` | higher-contrast side | Direction to search first (`'lighter'` or `'darker'`). |
 | `flip` | `false` | When `true`, try the opposite direction if the initial one doesn't meet the target. When `false`, only the initial direction is searched — unmet contrasts pin the result to that direction's extreme. |
-| `saturationTaper` | `0` | When `> 0`, candidate saturation rolls off toward the tone extremes (same envelope the renderer applies), so the solved tone meets the floor at its rendered saturation. |
 
 Result: `{ tone, contrast, met, branch: 'lighter' | 'darker' | 'preferred', flipped? }`. `flipped: true` indicates the initial direction failed and the opposite direction satisfied the target.

package/docs/migration.md

@@ -34,7 +34,7 @@ glaze.configure({ lightLightness: [10, 100], darkLightness: [15, 95], darkCurve:
 glaze.configure({
   lightTone: [10, 100],
   darkTone: [15, 95],
-  // darkCurve removed; saturationTaper: 0.15 is the new gentle-extremes knob
+  // darkCurve removed
 });
 ```
 

package/docs/okhst.md

@@ -155,19 +155,11 @@ A window is authored as `[lo, hi]` (reference eps — the common form),
 to disable clamping. `false` is the full range `[0, 100]` at the reference eps —
 it removes the **boundaries**, not the tone curve.
 
-Other defaults: `darkDesaturation = 0.1` (unchanged), `saturationTaper = 0.15`,
+Other defaults: `darkDesaturation = 0.1` (unchanged),
 `autoFlip = true`.
 
 Reference: `REF_EPS = 0.05`.
 
-## Saturation taper
-
-At the tone extremes the in-gamut chroma collapses, so high saturation near
-white/black reads as noise. `saturationEnvelope(s, toneFinal, taper)` applies a
-smoothstep rolloff over the outer `taper` fraction of the tone range (default
-`0.15` → outer 15% on each end). `taper = 0` disables it. It is conservative by
-design: mid-tones are untouched, so existing ramps barely shift.
-
 ## Contrast metric (unified)
 
 `contrast` is a single prop with a pluggable metric:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tenphi/glaze",
-  "version": "0.14.0",
-  "description": "OKHSL-based color theme generator with WCAG contrast solving for light, dark, and high-contrast schemes",
+  "version": "0.15.1",
+  "description": "OKHST-based color theme generator with WCAG contrast solving for light, dark, and high-contrast schemes",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -33,6 +33,7 @@
   "keywords": [
     "color",
     "theme",
+    "okhst",
     "okhsl",
     "contrast",
     "wcag",
@@ -57,10 +58,13 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.0",
+    "vite": "^8.0.16",
     "vitest": "^4.0.18"
   },
   "scripts": {
     "build": "tsdown",
+    "playground": "vite playground",
+    "build:playground": "vite build playground",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",