@tenphi/glaze 0.1.0 → 0.2.0

package/README.md

@@ -23,6 +23,7 @@ Glaze generates robust **light**, **dark**, and **high-contrast** color schemes
 - **OKHSL color space** — perceptually uniform hue and saturation
 - **WCAG 2 contrast solving** — automatic lightness adjustment to meet AA/AAA targets
 - **Light + Dark + High-Contrast** — all schemes from one definition
+- **Per-color hue override** — absolute or relative hue shifts within a theme
 - **Multi-format output** — `okhsl`, `rgb`, `hsl`, `oklch`
 - **Import/Export** — serialize and restore theme configurations
 - **Create from hex/RGB** — start from an existing brand color
@@ -54,11 +55,11 @@ const primary = glaze(280, 80);
 
 // Define colors with explicit lightness and contrast relationships
 primary.colors({
-  surface:    { l: 97, sat: 0.75 },
-  text:       { base: 'surface', contrast: 52, ensureContrast: 'AAA' },
-  border:     { base: 'surface', contrast: [7, 20], ensureContrast: 'AA-large' },
-  'accent-fill': { l: 52, mode: 'fixed' },
-  'accent-text': { base: 'accent-fill', contrast: 48, ensureContrast: 'AA', mode: 'fixed' },
+  surface:       { lightness: 97, saturation: 0.75 },
+  text:          { base: 'surface', lightness: '-52', contrast: 'AAA' },
+  border:        { base: 'surface', lightness: ['-7', '-20'], contrast: 'AA-large' },
+  'accent-fill': { lightness: 52, mode: 'fixed' },
+  'accent-text': { base: 'accent-fill', lightness: '+48', contrast: 'AA', mode: 'fixed' },
 });
 
 // Create status themes by rotating the hue
@@ -77,6 +78,8 @@ const tokens = palette.tokens({ prefix: true });
 
 A single `glaze` theme is tied to one hue/saturation seed. Status colors (danger, success, warning) are derived via `extend`, which inherits all color definitions and replaces the seed.
 
+Individual colors can override the hue via the `hue` prop (see [Per-Color Hue Override](#per-color-hue-override)), but the primary purpose of a theme is to scope colors with the same hue.
+
 ### Color Definitions
 
 Every color is defined explicitly. No implicit roles — every value is stated.
@@ -85,48 +88,73 @@ Every color is defined explicitly. No implicit roles — every value is stated.
 
 ```ts
 primary.colors({
-  surface: { l: 97, sat: 0.75 },
-  border:  { l: 90, sat: 0.20 },
+  surface: { lightness: 97, saturation: 0.75 },
+  border:  { lightness: 90, saturation: 0.20 },
 });
 ```
 
-- `l` — lightness in the light scheme (0–100)
-- `sat` — saturation factor applied to the seed saturation (0–1, default: `1`)
+- `lightness` — lightness in the light scheme (0–100)
+- `saturation` — saturation factor applied to the seed saturation (0–1, default: `1`)
 
 #### Dependent Colors (relative to base)
 
 ```ts
 primary.colors({
-  surface: { l: 97, sat: 0.75 },
-  text:    { base: 'surface', contrast: 52, ensureContrast: 'AAA' },
+  surface: { lightness: 97, saturation: 0.75 },
+  text:    { base: 'surface', lightness: '-52', contrast: 'AAA' },
 });
 ```
 
 - `base` — name of another color in the same theme
-- `contrast` — lightness delta from the base color
-- `ensureContrast` — ensures the WCAG contrast ratio meets a target floor against the base
+- `lightness` — position of this color (see [Lightness Values](#lightness-values))
+- `contrast` — ensures the WCAG contrast ratio meets a target floor against the base
 
-Both `contrast` and `ensureContrast` are considered. The effective lightness satisfies both constraints — the more demanding one wins.
+### Lightness Values
 
-### Contrast Sign Convention
+The `lightness` prop accepts two forms:
 
-| Sign | Behavior |
-|---|---|
-| Negative (`-52`) | Always darker than base |
-| Positive (`+48`) | Always lighter than base |
-| Unsigned (`52`) | Auto-resolved: if `base_L + contrast > 100`, flips to negative |
+| Form | Example | Meaning |
+|---|---|---|
+| Number (absolute) | `lightness: 45` | Absolute lightness 0–100 |
+| String (relative) | `lightness: '-52'` | Relative to base color's lightness |
+
+**Absolute lightness** on a dependent color (with `base`) positions the color independently. In dark mode, it is dark-mapped on its own. The `contrast` WCAG solver acts as a safety net.
+
+**Relative lightness** applies a signed delta to the base color's resolved lightness. In dark mode with `auto` adaptation, the sign flips automatically.
 
 ```ts
-// Surface L=97
-'text': { base: 'surface', contrast: 52 }
-// → 97 + 52 = 149 > 100 → flips to 97 - 52 = 45 ✓
+// Relative: 97 - 52 = 45 in light mode
+'text': { base: 'surface', lightness: '-52' }
+
+// Absolute: lightness 45 in light mode, dark-mapped independently
+'text': { base: 'surface', lightness: 45 }
+```
+
+A dependent color with `base` but no `lightness` inherits the base's lightness (equivalent to a delta of 0).
+
+### Per-Color Hue Override
 
-// Button fill L=52
-'accent-text': { base: 'accent-fill', contrast: 48 }
-// → 52 + 48 = 100 → keeps as 100 ✓
+Individual colors can override the theme's hue. The `hue` prop accepts:
+
+| Form | Example | Meaning |
+|---|---|---|
+| Number (absolute) | `hue: 120` | Absolute hue 0–360 |
+| String (relative) | `hue: '+20'` | Relative to the **theme seed** hue |
+
+**Important:** Relative hue is always relative to the **theme seed hue**, not to a base color's hue.
+
+```ts
+const theme = glaze(280, 80);
+theme.colors({
+  surface:     { lightness: 97 },
+  // Gradient end — slight hue shift from seed (280 + 20 = 300)
+  gradientEnd: { lightness: 90, hue: '+20' },
+  // Entirely different hue
+  warning:     { lightness: 60, hue: 40 },
+});
 ```
 
-### ensureContrast (WCAG Floor)
+### contrast (WCAG Floor)
 
 Ensures the WCAG contrast ratio meets a target floor. Accepts a numeric ratio or a preset string:
 
@@ -141,26 +169,26 @@ type MinContrast = number | 'AA' | 'AAA' | 'AA-large' | 'AAA-large';
 | `'AA-large'` | 3 |
 | `'AAA-large'` | 4.5 |
 
-You can also pass any numeric ratio directly (e.g., `ensureContrast: 4.5`, `ensureContrast: 7`, `ensureContrast: 11`).
+You can also pass any numeric ratio directly (e.g., `contrast: 4.5`, `contrast: 7`, `contrast: 11`).
 
-The constraint is applied independently for each scheme. If the `contrast` delta already satisfies the floor, it's kept. Otherwise, the solver adjusts lightness until the target is met.
+The constraint is applied independently for each scheme. If the `lightness` already satisfies the floor, it's kept. Otherwise, the solver adjusts lightness until the target is met.
 
 ### High-Contrast via Array Values
 
-`contrast`, `ensureContrast`, and `l` accept a `[normal, high-contrast]` pair:
+`lightness` and `contrast` accept a `[normal, high-contrast]` pair:
 
 ```ts
-'border': { base: 'surface', contrast: [7, 20], ensureContrast: 'AA-large' }
-//                                      ↑   ↑
-//                                  normal  high-contrast
+'border': { base: 'surface', lightness: ['-7', '-20'], contrast: 'AA-large' }
+//                                        ↑      ↑
+//                                    normal  high-contrast
 ```
 
 A single value applies to both modes. All control is local and explicit.
 
 ```ts
-'text':   { base: 'surface', contrast: 52, ensureContrast: 'AAA' }
-'border': { base: 'surface', contrast: [7, 20], ensureContrast: 'AA-large' }
-'muted':  { base: 'surface', contrast: [35, 50], ensureContrast: ['AA-large', 'AA'] }
+'text':   { base: 'surface', lightness: '-52', contrast: 'AAA' }
+'border': { base: 'surface', lightness: ['-7', '-20'], contrast: 'AA-large' }
+'muted':  { base: 'surface', lightness: ['-35', '-50'], contrast: ['AA-large', 'AA'] }
 ```
 
 ## Theme Color Management
@@ -171,8 +199,8 @@ A single value applies to both modes. All control is local and explicit.
 
 ```ts
 const theme = glaze(280, 80);
-theme.colors({ surface: { l: 97 } });
-theme.colors({ text: { l: 30 } });
+theme.colors({ surface: { lightness: 97 } });
+theme.colors({ text: { lightness: 30 } });
 // Both 'surface' and 'text' are now defined
 ```
 
@@ -181,8 +209,8 @@ theme.colors({ text: { l: 30 } });
 `.color(name)` returns the definition, `.color(name, def)` sets it:
 
 ```ts
-theme.color('surface', { l: 97, sat: 0.75 }); // set
-const def = theme.color('surface');             // get → { l: 97, sat: 0.75 }
+theme.color('surface', { lightness: 97, saturation: 0.75 }); // set
+const def = theme.color('surface');                     // get → { lightness: 97, saturation: 0.75 }
 ```
 
 ### Removing Colors
@@ -214,7 +242,7 @@ Serialize a theme's configuration (hue, saturation, color definitions) to a plai
 ```ts
 // Export
 const snapshot = theme.export();
-// → { hue: 280, saturation: 80, colors: { surface: { l: 97, sat: 0.75 }, ... } }
+// → { hue: 280, saturation: 80, colors: { surface: { lightness: 97, saturation: 0.75 }, ... } }
 
 const jsonString = JSON.stringify(snapshot);
 
@@ -230,14 +258,14 @@ The export contains only the configuration — not resolved color values. Resolv
 Create a single color token without a full theme:
 
 ```ts
-const accent = glaze.color({ hue: 280, saturation: 80, l: 52, mode: 'fixed' });
+const accent = glaze.color({ hue: 280, saturation: 80, lightness: 52, mode: 'fixed' });
 
 accent.resolve();  // → ResolvedColor with light/dark/lightContrast/darkContrast
 accent.token();    // → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }
 accent.json();     // → { light: 'okhsl(...)', dark: 'okhsl(...)' }
 ```
 
-Standalone colors are always root colors (no `base`/`contrast`/`ensureContrast`).
+Standalone colors are always root colors (no `base`/`contrast`).
 
 ## From Existing Colors
 
@@ -255,8 +283,8 @@ The resulting theme has the extracted hue and saturation. Add colors as usual:
 
 ```ts
 brand.colors({
-  surface: { l: 97, sat: 0.75 },
-  text:    { base: 'surface', contrast: 52, ensureContrast: 'AAA' },
+  surface: { lightness: 97, saturation: 0.75 },
+  text:    { base: 'surface', lightness: '-52', contrast: 'AAA' },
 });
 ```
 
@@ -299,20 +327,20 @@ Modes control how colors adapt across schemes:
 | `'fixed'` | Color stays recognizable. Only safety corrections. For brand buttons, CTAs. |
 | `'static'` | No adaptation. Same value in every scheme. |
 
-### How `contrast` Adapts
+### How Relative Lightness Adapts
 
-**`auto` mode** — contrast sign flips in dark scheme:
+**`auto` mode** — relative lightness sign flips in dark scheme:
 
 ```ts
-// Light: surface L=97, text contrast=52 → L=45 (dark text on light bg)
+// Light: surface L=97, text lightness='-52' → L=45 (dark text on light bg)
 // Dark:  surface inverts to L≈14, sign flips → L=14+52=66
-//        ensureContrast solver may push further (light text on dark bg)
+//        contrast solver may push further (light text on dark bg)
 ```
 
-**`fixed` mode** — lightness is mapped (not inverted), contrast sign preserved:
+**`fixed` mode** — lightness is mapped (not inverted), relative sign preserved:
 
 ```ts
-// Light: accent-fill L=52, accent-text contrast=+48 → L=100 (white on brand)
+// Light: accent-fill L=52, accent-text lightness='+48' → L=100 (white on brand)
 // Dark:  accent-fill maps to L≈51.6, sign preserved → L≈99.6
 ```
 
@@ -367,7 +395,7 @@ Override individual colors (additive merge):
 ```ts
 const danger = primary.extend({
   hue: 23,
-  colors: { 'accent-fill': { l: 48, mode: 'fixed' } },
+  colors: { 'accent-fill': { lightness: 48, mode: 'fixed' } },
 });
 ```
 
@@ -446,33 +474,43 @@ glaze.configure({
 ## Color Definition Shape
 
 ```ts
+type RelativeValue = `+${number}` | `-${number}`;
 type HCPair<T> = T | [T, T]; // [normal, high-contrast]
 
 interface ColorDef {
-  // Root color (explicit position)
-  l?: HCPair<number>;    // 0–100, light scheme lightness
-  sat?: number;           // 0–1, saturation factor (default: 1)
+  // Lightness
+  lightness?: HCPair<number | RelativeValue>;
+  //   Number: absolute (0–100)
+  //   String: relative to base ('+N' / '-N')
+
+  // Hue override
+  hue?: number | RelativeValue;
+  //   Number: absolute (0–360)
+  //   String: relative to theme seed ('+N' / '-N')
+
+  // Saturation factor (0–1, default: 1)
+  saturation?: number;
 
-  // Dependent color (relative to base)
+  // Dependency
   base?: string;                  // name of another color
-  contrast?: HCPair<number>;     // lightness delta from base
-  ensureContrast?: HCPair<MinContrast>; // ensures WCAG contrast ratio meets target floor
+  contrast?: HCPair<MinContrast>; // WCAG contrast ratio floor against base
 
   // Adaptation mode
   mode?: 'auto' | 'fixed' | 'static'; // default: 'auto'
 }
 ```
 
-Every color must have either `l` (root) or `base` + `contrast` (dependent).
+A root color must have absolute `lightness` (a number). A dependent color must have `base`. Relative `lightness` (a string) requires `base`.
 
 ## Validation
 
 | Condition | Behavior |
 |---|---|
-| Both `l` and `base` on same color | Warning, `l` takes precedence |
+| Both absolute `lightness` and `base` on same color | Warning, `lightness` takes precedence |
 | `contrast` without `base` | Validation error |
-| `l` resolves outside 0–100 | Clamp silently |
-| `sat` outside 0–1 | Clamp silently |
+| Relative `lightness` without `base` | Validation error |
+| `lightness` resolves outside 0–100 | Clamp silently |
+| `saturation` outside 0–1 | Clamp silently |
 | Circular `base` references | Validation error |
 | `base` references non-existent name | Validation error |
 
@@ -506,14 +544,14 @@ import { glaze } from '@tenphi/glaze';
 const primary = glaze(280, 80);
 
 primary.colors({
-  surface:    { l: 97, sat: 0.75 },
-  text:       { base: 'surface', contrast: 52, ensureContrast: 'AAA' },
-  border:     { base: 'surface', contrast: [7, 20], ensureContrast: 'AA-large' },
-  bg:         { l: 97, sat: 0.75 },
-  icon:       { l: 60, sat: 0.94 },
-  'accent-fill': { l: 52, mode: 'fixed' },
-  'accent-text': { base: 'accent-fill', contrast: 48, ensureContrast: 'AA', mode: 'fixed' },
-  disabled:   { l: 81, sat: 0.40 },
+  surface:       { lightness: 97, saturation: 0.75 },
+  text:          { base: 'surface', lightness: '-52', contrast: 'AAA' },
+  border:        { base: 'surface', lightness: ['-7', '-20'], contrast: 'AA-large' },
+  bg:            { lightness: 97, saturation: 0.75 },
+  icon:          { lightness: 60, saturation: 0.94 },
+  'accent-fill': { lightness: 52, mode: 'fixed' },
+  'accent-text': { base: 'accent-fill', lightness: '+48', contrast: 'AA', mode: 'fixed' },
+  disabled:      { lightness: 81, saturation: 0.4 },
 });
 
 const danger  = primary.extend({ hue: 23 });
@@ -535,7 +573,7 @@ const restored = glaze.from(snapshot);
 
 // Create from an existing brand color
 const brand = glaze.fromHex('#7a4dbf');
-brand.colors({ surface: { l: 97 }, text: { base: 'surface', contrast: 52 } });
+brand.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '-52' } });
 ```
 
 ## API Reference

package/dist/index.cjs

@@ -495,7 +495,7 @@ function formatOklch(h, s, l) {
 *
 * Finds the closest OKHSL lightness that satisfies a WCAG 2 contrast target
 * against a base color. Used by glaze when resolving dependent colors
-* with `ensureContrast`.
+* with `contrast`.
 */
 const CONTRAST_PRESETS = {
 	AA: 4.5,
@@ -633,8 +633,8 @@ function coarseScan(h, s, lo, hi, yBase, target, epsilon, maxIter) {
 * against a base color, staying as close to `preferredLightness` as possible.
 */
 function findLightnessForContrast(options) {
-	const { hue, saturation, preferredLightness, baseLinearRgb, ensureContrast: ensureContrastInput, lightnessRange = [0, 1], epsilon = 1e-4, maxIterations = 14 } = options;
-	const target = resolveMinContrast(ensureContrastInput);
+	const { hue, saturation, preferredLightness, baseLinearRgb, contrast: contrastInput, lightnessRange = [0, 1], epsilon = 1e-4, maxIterations = 14 } = options;
+	const target = resolveMinContrast(contrastInput);
 	const yBase = relativeLuminanceFromLinearRgb(baseLinearRgb);
 	const crPref = contrastRatioFromLuminance(cachedLuminance(hue, saturation, preferredLightness), yBase);
 	if (crPref >= target) return {
@@ -715,9 +715,10 @@ function validateColorDefs(defs) {
 	const names = new Set(Object.keys(defs));
 	for (const [name, def] of Object.entries(defs)) {
 		if (def.contrast !== void 0 && !def.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
-		if (def.l !== void 0 && def.base !== void 0) console.warn(`glaze: color "${name}" has both "l" and "base". "l" takes precedence.`);
+		if (def.lightness !== void 0 && !isAbsoluteLightness(def.lightness) && !def.base) throw new Error(`glaze: color "${name}" has relative "lightness" without "base".`);
+		if (isAbsoluteLightness(def.lightness) && def.base !== void 0) console.warn(`glaze: color "${name}" has absolute "lightness" and "base". Absolute lightness takes precedence.`);
 		if (def.base && !names.has(def.base)) throw new Error(`glaze: color "${name}" references non-existent base "${def.base}".`);
-		if (def.l === void 0 && def.base === void 0) throw new Error(`glaze: color "${name}" must have either "l" (root) or "base" + "contrast" (dependent).`);
+		if (!isAbsoluteLightness(def.lightness) && def.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "lightness" (root) or "base" (dependent).`);
 	}
 	const visited = /* @__PURE__ */ new Set();
 	const inStack = /* @__PURE__ */ new Set();
@@ -726,7 +727,7 @@ function validateColorDefs(defs) {
 		if (visited.has(name)) return;
 		inStack.add(name);
 		const def = defs[name];
-		if (def.base && def.l === void 0) dfs(def.base);
+		if (def.base && !isAbsoluteLightness(def.lightness)) dfs(def.base);
 		inStack.delete(name);
 		visited.add(name);
 	}
@@ -739,7 +740,7 @@ function topoSort(defs) {
 		if (visited.has(name)) return;
 		visited.add(name);
 		const def = defs[name];
-		if (def.base && def.l === void 0) visit(def.base);
+		if (def.base && !isAbsoluteLightness(def.lightness)) visit(def.base);
 		result.push(name);
 	}
 	for (const name of Object.keys(defs)) visit(name);
@@ -755,44 +756,75 @@ function mapSaturationDark(s, mode) {
 	if (mode === "static") return s;
 	return s * (1 - globalConfig.darkDesaturation);
 }
+function clamp(v, min, max) {
+	return Math.max(min, Math.min(max, v));
+}
 /**
-* Resolve the effective lightness from a contrast delta.
+* Parse a value that can be absolute (number) or relative (signed string).
+* Returns the numeric value and whether it's relative.
 */
-function resolveContrastLightness(baseLightness, contrast) {
-	if (contrast < 0) return clamp(baseLightness + contrast, 0, 100);
-	const candidate = baseLightness + contrast;
-	if (candidate > 100) return clamp(baseLightness - contrast, 0, 100);
-	return clamp(candidate, 0, 100);
+function parseRelativeOrAbsolute(value) {
+	if (typeof value === "number") return {
+		value,
+		relative: false
+	};
+	return {
+		value: parseFloat(value),
+		relative: true
+	};
 }
-function clamp(v, min, max) {
-	return Math.max(min, Math.min(max, v));
+/**
+* Compute the effective hue for a color, given the theme seed hue
+* and an optional per-color hue override.
+*/
+function resolveEffectiveHue(seedHue, defHue) {
+	if (defHue === void 0) return seedHue;
+	const parsed = parseRelativeOrAbsolute(defHue);
+	if (parsed.relative) return ((seedHue + parsed.value) % 360 + 360) % 360;
+	return (parsed.value % 360 + 360) % 360;
+}
+/**
+* Check whether a lightness value represents an absolute root definition
+* (i.e. a number, not a relative string).
+*/
+function isAbsoluteLightness(lightness) {
+	if (lightness === void 0) return false;
+	return typeof (Array.isArray(lightness) ? lightness[0] : lightness) === "number";
 }
 function resolveRootColor(_name, def, _ctx, isHighContrast) {
-	const rawL = def.l;
+	const rawL = def.lightness;
 	return {
-		lightL: clamp(isHighContrast ? pairHC(rawL) : pairNormal(rawL), 0, 100),
-		sat: clamp(def.sat ?? 1, 0, 1)
+		lightL: clamp(parseRelativeOrAbsolute(isHighContrast ? pairHC(rawL) : pairNormal(rawL)).value, 0, 100),
+		satFactor: clamp(def.saturation ?? 1, 0, 1)
 	};
 }
-function resolveDependentColor(name, def, ctx, isHighContrast, isDark) {
+function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue) {
 	const baseName = def.base;
 	const baseResolved = ctx.resolved.get(baseName);
 	if (!baseResolved) throw new Error(`glaze: base "${baseName}" not yet resolved for "${name}".`);
 	const mode = def.mode ?? "auto";
-	const sat = clamp(def.sat ?? 1, 0, 1);
+	const satFactor = clamp(def.saturation ?? 1, 0, 1);
 	let baseL;
 	if (isDark && isHighContrast) baseL = baseResolved.darkContrast.l * 100;
 	else if (isDark) baseL = baseResolved.dark.l * 100;
 	else if (isHighContrast) baseL = baseResolved.lightContrast.l * 100;
 	else baseL = baseResolved.light.l * 100;
-	const rawContrast = def.contrast ?? 0;
-	let contrast = isHighContrast ? pairHC(rawContrast) : pairNormal(rawContrast);
-	if (isDark && mode === "auto") contrast = -contrast;
-	const preferredL = resolveContrastLightness(baseL, contrast);
-	const rawEnsureContrast = def.ensureContrast;
-	if (rawEnsureContrast !== void 0) {
-		const minCr = isHighContrast ? pairHC(rawEnsureContrast) : pairNormal(rawEnsureContrast);
-		const effectiveSat = isDark ? mapSaturationDark(sat * ctx.saturation / 100, mode) : sat * ctx.saturation / 100;
+	let preferredL;
+	const rawLightness = def.lightness;
+	if (rawLightness === void 0) preferredL = baseL;
+	else {
+		const parsed = parseRelativeOrAbsolute(isHighContrast ? pairHC(rawLightness) : pairNormal(rawLightness));
+		if (parsed.relative) {
+			let delta = parsed.value;
+			if (isDark && mode === "auto") delta = -delta;
+			preferredL = clamp(baseL + delta, 0, 100);
+		} else if (isDark) preferredL = mapLightnessDark(parsed.value, mode);
+		else preferredL = clamp(parsed.value, 0, 100);
+	}
+	const rawContrast = def.contrast;
+	if (rawContrast !== void 0) {
+		const minCr = isHighContrast ? pairHC(rawContrast) : pairNormal(rawContrast);
+		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode) : satFactor * ctx.saturation / 100;
 		let baseH;
 		let baseS;
 		let baseLNorm;
@@ -816,48 +848,49 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark) {
 		const baseLinearRgb = okhslToLinearSrgb(baseH, baseS, baseLNorm);
 		return {
 			l: findLightnessForContrast({
-				hue: ctx.hue,
+				hue: effectiveHue,
 				saturation: effectiveSat,
 				preferredLightness: preferredL / 100,
 				baseLinearRgb,
-				ensureContrast: minCr
+				contrast: minCr
 			}).lightness * 100,
-			sat
+			satFactor
 		};
 	}
 	return {
 		l: clamp(preferredL, 0, 100),
-		sat
+		satFactor
 	};
 }
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	const mode = def.mode ?? "auto";
-	const isRoot = def.l !== void 0;
+	const isRoot = isAbsoluteLightness(def.lightness) && !def.base;
+	const effectiveHue = resolveEffectiveHue(ctx.hue, def.hue);
 	let lightL;
-	let sat;
+	let satFactor;
 	if (isRoot) {
 		const root = resolveRootColor(name, def, ctx, isHighContrast);
 		lightL = root.lightL;
-		sat = root.sat;
+		satFactor = root.satFactor;
 	} else {
-		const dep = resolveDependentColor(name, def, ctx, isHighContrast, isDark);
+		const dep = resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue);
 		lightL = dep.l;
-		sat = dep.sat;
+		satFactor = dep.satFactor;
 	}
 	let finalL;
 	let finalSat;
 	if (isDark && isRoot) {
 		finalL = mapLightnessDark(lightL, mode);
-		finalSat = mapSaturationDark(sat * ctx.saturation / 100, mode);
+		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
 	} else if (isDark && !isRoot) {
 		finalL = lightL;
-		finalSat = mapSaturationDark(sat * ctx.saturation / 100, mode);
+		finalSat = mapSaturationDark(satFactor * ctx.saturation / 100, mode);
 	} else {
 		finalL = lightL;
-		finalSat = sat * ctx.saturation / 100;
+		finalSat = satFactor * ctx.saturation / 100;
 	}
 	return {
-		h: ctx.hue,
+		h: effectiveHue,
 		s: clamp(finalSat, 0, 1),
 		l: clamp(finalL / 100, 0, 1)
 	};
@@ -1064,8 +1097,8 @@ function createPalette(themes) {
 }
 function createColorToken(input) {
 	const defs = { __color__: {
-		l: input.l,
-		sat: input.sat,
+		lightness: input.lightness,
+		saturation: input.saturationFactor,
 		mode: input.mode
 	} };
 	return {