@tenphi/glaze 0.4.0 → 0.5.1

package/README.md

@@ -22,9 +22,10 @@ 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
+- **Shadow colors** — OKHSL-native shadow computation with automatic alpha, fg/bg tinting, and per-scheme adaptation
 - **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`
+- **Multi-format output** — `okhsl`, `rgb`, `hsl`, `oklch` with modern CSS space syntax
 - **CSS custom properties export** — ready-to-use `--var: value;` declarations per scheme
 - **Import/Export** — serialize and restore theme configurations
 - **Create from hex/RGB** — start from an existing brand color
@@ -290,34 +291,165 @@ brand.colors({
 });
 ```
 
+## Shadow Colors
+
+Shadow colors are colors with computed alpha. Instead of a parallel shadow system, they extend the existing color pipeline. All math is done natively in OKHSL.
+
+### Defining Shadow Colors
+
+Shadow colors use `type: 'shadow'` and reference a `bg` (background) color and optionally an `fg` (foreground) color for tinting and intensity modulation:
+
+```ts
+theme.colors({
+  surface: { lightness: 95 },
+  text:    { base: 'surface', lightness: '-52', contrast: 'AAA' },
+
+  'shadow-sm': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 5 },
+  'shadow-md': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 10 },
+  'shadow-lg': { type: 'shadow', bg: 'surface', fg: 'text', intensity: 20 },
+});
+```
+
+Shadow colors are included in all output methods (`tokens()`, `tasty()`, `css()`, `json()`) alongside regular colors:
+
+```ts
+theme.tokens({ format: 'oklch' });
+// light: { 'shadow-md': 'oklch(0.15 0.009 282 / 0.1)', ... }
+// dark:  { 'shadow-md': 'oklch(0.06 0.004 0 / 0.49)', ... }
+```
+
+### How Shadows Work
+
+The shadow algorithm computes a dark, low-saturation pigment color and an alpha value that produces the desired visual intensity:
+
+1. **Contrast weight** — when `fg` is provided, shadow strength scales with `|l_bg - l_fg|`. Dark text on a light background produces a strong shadow; near-background-lightness elements produce barely visible shadows.
+2. **Pigment color** — hue blended between fg and bg, low saturation, dark lightness.
+3. **Alpha** — computed via a `tanh` curve that saturates smoothly toward `alphaMax` (default 0.6), ensuring well-separated shadow levels even on dark backgrounds.
+
+### Achromatic Shadows
+
+Omit `fg` for a pure achromatic shadow at full user-specified intensity:
+
+```ts
+theme.colors({
+  'drop-shadow': { type: 'shadow', bg: 'surface', intensity: 12 },
+});
+```
+
+### High-Contrast Intensity
+
+`intensity` supports `[normal, highContrast]` pairs:
+
+```ts
+theme.colors({
+  'shadow-card': { type: 'shadow', bg: 'surface', fg: 'text', intensity: [10, 20] },
+});
+```
+
+### Fixed Opacity (Regular Colors)
+
+For a simple fixed-alpha color (no shadow algorithm), use `opacity` on a regular color:
+
+```ts
+theme.colors({
+  overlay: { lightness: 0, opacity: 0.5 },
+});
+// → 'oklch(0 0 0 / 0.5)'
+```
+
+### Shadow Tuning
+
+Fine-tune shadow behavior per-color or globally:
+
+```ts
+// Per-color tuning
+theme.colors({
+  'shadow-soft': {
+    type: 'shadow', bg: 'surface', intensity: 10,
+    tuning: { alphaMax: 0.3, saturationFactor: 0.1 },
+  },
+});
+
+// Global tuning
+glaze.configure({
+  shadowTuning: { alphaMax: 0.5, bgHueBlend: 0.3 },
+});
+```
+
+Available tuning parameters:
+
+| Parameter | Default | Description |
+|---|---|---|
+| `saturationFactor` | 0.18 | Fraction of fg saturation kept in pigment |
+| `maxSaturation` | 0.25 | Upper clamp on pigment saturation |
+| `lightnessFactor` | 0.25 | Multiplier for bg lightness to pigment lightness |
+| `lightnessBounds` | [0.05, 0.20] | Clamp range for pigment lightness |
+| `minGapTarget` | 0.05 | Target minimum gap between pigment and bg lightness |
+| `alphaMax` | 0.6 | Asymptotic maximum alpha |
+| `bgHueBlend` | 0.2 | Blend weight pulling pigment hue toward bg hue |
+
+### Standalone Shadow Computation
+
+Compute a shadow outside of a theme:
+
+```ts
+const v = glaze.shadow({
+  bg: '#f0eef5',
+  fg: '#1a1a2e',
+  intensity: 10,
+});
+// → { h: 280, s: 0.14, l: 0.2, alpha: 0.1 }
+
+const css = glaze.format(v, 'oklch');
+// → 'oklch(0.15 0.014 280 / 0.1)'
+```
+
+### Consuming in CSS
+
+```css
+.card {
+  box-shadow: 0 2px 6px var(--shadow-sm-color),
+              0 8px 24px var(--shadow-md-color);
+}
+```
+
 ## Output Formats
 
 Control the color format in exports with the `format` option:
 
 ```ts
 // Default: OKHSL
-theme.tokens();                        // → 'okhsl(280.0 60.0% 97.0%)'
+theme.tokens();                        // → 'okhsl(280 60% 97%)'
 
-// RGB with fractional precision
-theme.tokens({ format: 'rgb' });       // → 'rgb(244.123, 240.456, 249.789)'
+// RGB (modern space syntax, rounded integers)
+theme.tokens({ format: 'rgb' });       // → 'rgb(244 240 250)'
 
-// HSL
-theme.tokens({ format: 'hsl' });       // → 'hsl(270.5, 45.2%, 95.8%)'
+// HSL (modern space syntax)
+theme.tokens({ format: 'hsl' });       // → 'hsl(270.5 45.2% 95.8%)'
 
 // OKLCH
-theme.tokens({ format: 'oklch' });     // → 'oklch(96.5% 0.0123 280.0)'
+theme.tokens({ format: 'oklch' });     // → 'oklch(0.965 0.0123 280)'
 ```
 
 The `format` option works on all export methods: `theme.tokens()`, `theme.tasty()`, `theme.json()`, `theme.css()`, `palette.tokens()`, `palette.tasty()`, `palette.json()`, `palette.css()`, and standalone `glaze.color().token()` / `.tasty()` / `.json()`.
 
+Colors with `alpha < 1` (shadow colors, or regular colors with `opacity`) include an alpha component:
+
+```ts
+// → 'oklch(0.15 0.009 282 / 0.1)'
+// → 'rgb(34 28 42 / 0.1)'
+```
+
 Available formats:
 
-| Format | Output | Notes |
-|---|---|---|
-| `'okhsl'` (default) | `okhsl(H S% L%)` | Native format, perceptually uniform |
-| `'rgb'` | `rgb(R, G, B)` | Fractional 0–255 values (3 decimals) |
-| `'hsl'` | `hsl(H, S%, L%)` | Standard CSS HSL |
-| `'oklch'` | `oklch(L% C H)` | OKLab-based LCH |
+| Format | Output (alpha = 1) | Output (alpha < 1) | Notes |
+|---|---|---|---|
+| `'okhsl'` (default) | `okhsl(H S% L%)` | `okhsl(H S% L% / A)` | Native format, not a CSS function |
+| `'rgb'` | `rgb(R G B)` | `rgb(R G B / A)` | Rounded integers, space syntax |
+| `'hsl'` | `hsl(H S% L%)` | `hsl(H S% L% / A)` | Modern space syntax |
+| `'oklch'` | `oklch(L C H)` | `oklch(L C H / A)` | OKLab-based LCH |
+
+All numeric output strips trailing zeros for cleaner CSS (e.g., `95` not `95.0`).
 
 ## Adaptation Modes
 
@@ -597,39 +729,40 @@ glaze.configure({
     dark: true,                // Include dark variants in exports
     highContrast: false,       // Include high-contrast variants
   },
+  shadowTuning: {              // Default tuning for all shadow colors
+    alphaMax: 0.6,
+    bgHueBlend: 0.2,
+  },
 });
 ```
 
 ## Color Definition Shape
 
+`ColorDef` is a discriminated union of regular colors and shadow colors:
+
 ```ts
-type RelativeValue = `+${number}` | `-${number}`;
-type HCPair<T> = T | [T, T]; // [normal, high-contrast]
+type ColorDef = RegularColorDef | ShadowColorDef;
 
-interface ColorDef {
-  // Lightness
+interface RegularColorDef {
   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;
+  hue?: number | RelativeValue;
+  base?: string;
+  contrast?: HCPair<MinContrast>;
+  mode?: 'auto' | 'fixed' | 'static';
+  opacity?: number; // fixed alpha (0–1)
+}
 
-  // Dependency
-  base?: string;                  // name of another color
-  contrast?: HCPair<MinContrast>; // WCAG contrast ratio floor against base
-
-  // Adaptation mode
-  mode?: 'auto' | 'fixed' | 'static'; // default: 'auto'
+interface ShadowColorDef {
+  type: 'shadow';
+  bg: string;       // background color name (non-shadow)
+  fg?: string;      // foreground color name (non-shadow)
+  intensity: HCPair<number>; // 0–100
+  tuning?: ShadowTuning;
 }
 ```
 
-A root color must have absolute `lightness` (a number). A dependent color must have `base`. Relative `lightness` (a string) requires `base`.
+A root color must have absolute `lightness` (a number). A dependent color must have `base`. Relative `lightness` (a string) requires `base`. Shadow colors use `type: 'shadow'` and must reference a non-shadow `bg` color.
 
 ## Validation
 
@@ -642,6 +775,13 @@ A root color must have absolute `lightness` (a number). A dependent color must h
 | `saturation` outside 0–1 | Clamp silently |
 | Circular `base` references | Validation error |
 | `base` references non-existent name | Validation error |
+| Shadow `bg` references non-existent color | Validation error |
+| Shadow `fg` references non-existent color | Validation error |
+| Shadow `bg` references another shadow color | Validation error |
+| Shadow `fg` references another shadow color | Validation error |
+| Regular color `base` references a shadow color | Validation error |
+| Shadow `intensity` outside 0–100 | Clamp silently |
+| `contrast` + `opacity` combined | Warning |
 
 ## Advanced: Color Math Utilities
 
@@ -681,6 +821,14 @@ primary.colors({
   'accent-fill': { lightness: 52, mode: 'fixed' },
   'accent-text': { base: 'accent-fill', lightness: '+48', contrast: 'AA', mode: 'fixed' },
   disabled:      { lightness: 81, saturation: 0.4 },
+
+  // Shadow colors — computed alpha, automatic dark-mode adaptation
+  'shadow-sm':   { type: 'shadow', bg: 'surface', fg: 'text', intensity: 5 },
+  'shadow-md':   { type: 'shadow', bg: 'surface', fg: 'text', intensity: 10 },
+  'shadow-lg':   { type: 'shadow', bg: 'surface', fg: 'text', intensity: 20 },
+
+  // Fixed-alpha overlay
+  overlay:       { lightness: 0, opacity: 0.5 },
 });
 
 const danger  = primary.extend({ hue: 23 });
@@ -692,21 +840,19 @@ const palette = glaze.palette({ primary, danger, success, warning, note });
 
 // Export as flat token map grouped by variant
 const tokens = palette.tokens({ prefix: true });
-// tokens.light → { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' }
-// tokens.dark  → { 'primary-surface': 'okhsl(...)', 'danger-surface': 'okhsl(...)' }
+// tokens.light → { 'primary-surface': 'okhsl(...)', 'primary-shadow-md': 'okhsl(... / 0.1)' }
 
 // Export as tasty style-to-state bindings (for Tasty style system)
 const tastyTokens = palette.tasty({ prefix: true });
-// tastyTokens['#primary-surface'] → { '': 'okhsl(...)', '@dark': 'okhsl(...)' }
-// Use as a recipe or spread into component styles (see Tasty Export section)
-
-// Export as RGB for broader CSS compatibility
-const rgbTokens = palette.tokens({ prefix: true, format: 'rgb' });
 
 // Export as CSS custom properties (rgb format by default)
 const css = palette.css({ prefix: true });
-// css.light → "--primary-surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
-// css.dark  → "--primary-surface-color: rgb(...);\n--danger-surface-color: rgb(...);"
+// css.light → "--primary-surface-color: rgb(...);\n--primary-shadow-md-color: rgb(... / 0.1);"
+
+// Standalone shadow computation
+const v = glaze.shadow({ bg: '#f0eef5', fg: '#1a1a2e', intensity: 10 });
+const shadowCss = glaze.format(v, 'oklch');
+// → 'oklch(0.15 0.014 280 / 0.1)'
 
 // Save and restore a theme
 const snapshot = primary.export();
@@ -729,6 +875,8 @@ brand.colors({ surface: { lightness: 97 }, text: { base: 'surface', lightness: '
 | `glaze.fromHex(hex)` | Create a theme from a hex color (`#rgb` or `#rrggbb`) |
 | `glaze.fromRgb(r, g, b)` | Create a theme from RGB values (0–255) |
 | `glaze.color(input)` | Create a standalone color token |
+| `glaze.shadow(input)` | Compute a standalone shadow color (returns `ResolvedColorVariant`) |
+| `glaze.format(variant, format?)` | Format any `ResolvedColorVariant` as a CSS string |
 
 ### Theme Methods
 

package/dist/index.cjs

@@ -441,23 +441,26 @@ function parseHex(hex) {
 	}
 	return null;
 }
+function fmt$1(value, decimals) {
+	return parseFloat(value.toFixed(decimals)).toString();
+}
 /**
 * 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).
 */
 function formatOkhsl(h, s, l) {
-	return `okhsl(${h.toFixed(1)} ${s.toFixed(1)}% ${l.toFixed(1)}%)`;
+	return `okhsl(${fmt$1(h, 1)} ${fmt$1(s, 1)}% ${fmt$1(l, 1)}%)`;
 }
 /**
-* Format OKHSL values as a CSS `rgb(R, G, B)` string with fractional 0–255 values.
+* Format OKHSL values as a CSS `rgb(R G B)` string with rounded integer values.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatRgb(h, s, l) {
 	const [r, g, b] = okhslToSrgb(h, s / 100, l / 100);
-	return `rgb(${(r * 255).toFixed(3)}, ${(g * 255).toFixed(3)}, ${(b * 255).toFixed(3)})`;
+	return `rgb(${Math.round(r * 255)} ${Math.round(g * 255)} ${Math.round(b * 255)})`;
 }
 /**
-* Format OKHSL values as a CSS `hsl(H, S%, L%)` string.
+* Format OKHSL values as a CSS `hsl(H S% L%)` string.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatHsl(h, s, l) {
@@ -474,10 +477,10 @@ function formatHsl(h, s, l) {
 		else if (max === g) hh = ((b - r) / delta + 2) * 60;
 		else hh = ((r - g) / delta + 4) * 60;
 	}
-	return `hsl(${hh.toFixed(1)}, ${(ss * 100).toFixed(1)}%, ${(ll * 100).toFixed(1)}%)`;
+	return `hsl(${fmt$1(hh, 1)} ${fmt$1(ss * 100, 1)}% ${fmt$1(ll * 100, 1)}%)`;
 }
 /**
-* Format OKHSL values as a CSS `oklch(L% C H)` string.
+* Format OKHSL values as a CSS `oklch(L C H)` string.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatOklch(h, s, l) {
@@ -485,7 +488,7 @@ function formatOklch(h, s, l) {
 	const C = Math.sqrt(a * a + b * b);
 	let hh = Math.atan2(b, a) * (180 / Math.PI);
 	hh = constrainAngle(hh);
-	return `oklch(${(L * 100).toFixed(1)}% ${C.toFixed(4)} ${hh.toFixed(1)})`;
+	return `oklch(${fmt$1(L, 4)} ${fmt$1(C, 4)} ${fmt$1(hh, 1)})`;
 }
 
 //#endregion
@@ -711,14 +714,84 @@ function pairNormal(p) {
 function pairHC(p) {
 	return Array.isArray(p) ? p[1] : p;
 }
+function isShadowDef(def) {
+	return def.type === "shadow";
+}
+const DEFAULT_SHADOW_TUNING = {
+	saturationFactor: .18,
+	maxSaturation: .25,
+	lightnessFactor: .25,
+	lightnessBounds: [.05, .2],
+	minGapTarget: .05,
+	alphaMax: 1,
+	bgHueBlend: .2
+};
+function resolveShadowTuning(perColor) {
+	return {
+		...DEFAULT_SHADOW_TUNING,
+		...globalConfig.shadowTuning,
+		...perColor,
+		lightnessBounds: perColor?.lightnessBounds ?? globalConfig.shadowTuning?.lightnessBounds ?? DEFAULT_SHADOW_TUNING.lightnessBounds
+	};
+}
+function circularLerp(a, b, t) {
+	let diff = b - a;
+	if (diff > 180) diff -= 360;
+	else if (diff < -180) diff += 360;
+	return ((a + diff * t) % 360 + 360) % 360;
+}
+/**
+* Compute the canonical max-contrast reference t value for normalization.
+* Uses bg.l=1, fg.l=0, intensity=100 — the theoretical maximum.
+* This is a fixed constant per tuning configuration, ensuring uniform
+* scaling across all bg/fg pairs at low intensities.
+*/
+function computeRefT(tuning) {
+	const EPSILON = 1e-6;
+	let lShRef = clamp(tuning.lightnessFactor, tuning.lightnessBounds[0], tuning.lightnessBounds[1]);
+	lShRef = Math.max(Math.min(lShRef, 1 - tuning.minGapTarget), 0);
+	return 1 / Math.max(1 - lShRef, EPSILON);
+}
+function computeShadow(bg, fg, intensity, tuning) {
+	const EPSILON = 1e-6;
+	const clampedIntensity = clamp(intensity, 0, 100);
+	const contrastWeight = fg ? Math.abs(bg.l - fg.l) : 1;
+	const deltaL = clampedIntensity / 100 * contrastWeight;
+	const h = fg ? circularLerp(fg.h, bg.h, tuning.bgHueBlend) : bg.h;
+	const s = fg ? Math.min(fg.s * tuning.saturationFactor, tuning.maxSaturation) : 0;
+	let lSh = clamp(bg.l * tuning.lightnessFactor, tuning.lightnessBounds[0], tuning.lightnessBounds[1]);
+	lSh = Math.max(Math.min(lSh, bg.l - tuning.minGapTarget), 0);
+	const t = deltaL / Math.max(bg.l - lSh, EPSILON);
+	const tRef = computeRefT(tuning);
+	const norm = Math.tanh(tRef / tuning.alphaMax);
+	const alpha = Math.min(tuning.alphaMax * Math.tanh(t / tuning.alphaMax) / norm, tuning.alphaMax);
+	return {
+		h,
+		s,
+		l: lSh,
+		alpha
+	};
+}
 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.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 (!isAbsoluteLightness(def.lightness) && def.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "lightness" (root) or "base" (dependent).`);
+		if (isShadowDef(def)) {
+			if (!names.has(def.bg)) throw new Error(`glaze: shadow "${name}" references non-existent bg "${def.bg}".`);
+			if (isShadowDef(defs[def.bg])) throw new Error(`glaze: shadow "${name}" bg "${def.bg}" references another shadow color.`);
+			if (def.fg !== void 0) {
+				if (!names.has(def.fg)) throw new Error(`glaze: shadow "${name}" references non-existent fg "${def.fg}".`);
+				if (isShadowDef(defs[def.fg])) throw new Error(`glaze: shadow "${name}" fg "${def.fg}" references another shadow color.`);
+			}
+			continue;
+		}
+		const regDef = def;
+		if (regDef.contrast !== void 0 && !regDef.base) throw new Error(`glaze: color "${name}" has "contrast" without "base".`);
+		if (regDef.lightness !== void 0 && !isAbsoluteLightness(regDef.lightness) && !regDef.base) throw new Error(`glaze: color "${name}" has relative "lightness" without "base".`);
+		if (isAbsoluteLightness(regDef.lightness) && regDef.base !== void 0) console.warn(`glaze: color "${name}" has absolute "lightness" and "base". Absolute lightness takes precedence.`);
+		if (regDef.base && !names.has(regDef.base)) throw new Error(`glaze: color "${name}" references non-existent base "${regDef.base}".`);
+		if (regDef.base && isShadowDef(defs[regDef.base])) throw new Error(`glaze: color "${name}" base "${regDef.base}" references a shadow color.`);
+		if (!isAbsoluteLightness(regDef.lightness) && regDef.base === void 0) throw new Error(`glaze: color "${name}" must have either absolute "lightness" (root) or "base" (dependent).`);
+		if (regDef.contrast !== void 0 && regDef.opacity !== void 0) console.warn(`glaze: color "${name}" has both "contrast" and "opacity". Opacity makes perceived lightness unpredictable.`);
 	}
 	const visited = /* @__PURE__ */ new Set();
 	const inStack = /* @__PURE__ */ new Set();
@@ -727,7 +800,13 @@ function validateColorDefs(defs) {
 		if (visited.has(name)) return;
 		inStack.add(name);
 		const def = defs[name];
-		if (def.base && !isAbsoluteLightness(def.lightness)) dfs(def.base);
+		if (isShadowDef(def)) {
+			dfs(def.bg);
+			if (def.fg) dfs(def.fg);
+		} else {
+			const regDef = def;
+			if (regDef.base && !isAbsoluteLightness(regDef.lightness)) dfs(regDef.base);
+		}
 		inStack.delete(name);
 		visited.add(name);
 	}
@@ -740,7 +819,13 @@ function topoSort(defs) {
 		if (visited.has(name)) return;
 		visited.add(name);
 		const def = defs[name];
-		if (def.base && !isAbsoluteLightness(def.lightness)) visit(def.base);
+		if (isShadowDef(def)) {
+			visit(def.bg);
+			if (def.fg) visit(def.fg);
+		} else {
+			const regDef = def;
+			if (regDef.base && !isAbsoluteLightness(regDef.lightness)) visit(regDef.base);
+		}
 		result.push(name);
 	}
 	for (const name of Object.keys(defs)) visit(name);
@@ -804,11 +889,8 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 	if (!baseResolved) throw new Error(`glaze: base "${baseName}" not yet resolved for "${name}".`);
 	const mode = def.mode ?? "auto";
 	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 baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
+	const baseL = baseVariant.l * 100;
 	let preferredL;
 	const rawLightness = def.lightness;
 	if (rawLightness === void 0) preferredL = baseL;
@@ -825,27 +907,7 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 	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;
-		if (isDark && isHighContrast) {
-			baseH = baseResolved.darkContrast.h;
-			baseS = baseResolved.darkContrast.s;
-			baseLNorm = baseResolved.darkContrast.l;
-		} else if (isDark) {
-			baseH = baseResolved.dark.h;
-			baseS = baseResolved.dark.s;
-			baseLNorm = baseResolved.dark.l;
-		} else if (isHighContrast) {
-			baseH = baseResolved.lightContrast.h;
-			baseS = baseResolved.lightContrast.s;
-			baseLNorm = baseResolved.lightContrast.l;
-		} else {
-			baseH = baseResolved.light.h;
-			baseS = baseResolved.light.s;
-			baseLNorm = baseResolved.light.l;
-		}
-		const baseLinearRgb = okhslToLinearSrgb(baseH, baseS, baseLNorm);
+		const baseLinearRgb = okhslToLinearSrgb(baseVariant.h, baseVariant.s, baseVariant.l);
 		return {
 			l: findLightnessForContrast({
 				hue: effectiveHue,
@@ -862,18 +924,26 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 		satFactor
 	};
 }
+function getSchemeVariant(color, isDark, isHighContrast) {
+	if (isDark && isHighContrast) return color.darkContrast;
+	if (isDark) return color.dark;
+	if (isHighContrast) return color.lightContrast;
+	return color.light;
+}
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
-	const mode = def.mode ?? "auto";
-	const isRoot = isAbsoluteLightness(def.lightness) && !def.base;
-	const effectiveHue = resolveEffectiveHue(ctx.hue, def.hue);
+	if (isShadowDef(def)) return resolveShadowForScheme(def, ctx, isDark, isHighContrast);
+	const regDef = def;
+	const mode = regDef.mode ?? "auto";
+	const isRoot = isAbsoluteLightness(regDef.lightness) && !regDef.base;
+	const effectiveHue = resolveEffectiveHue(ctx.hue, regDef.hue);
 	let lightL;
 	let satFactor;
 	if (isRoot) {
-		const root = resolveRootColor(name, def, ctx, isHighContrast);
+		const root = resolveRootColor(name, regDef, ctx, isHighContrast);
 		lightL = root.lightL;
 		satFactor = root.satFactor;
 	} else {
-		const dep = resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue);
+		const dep = resolveDependentColor(name, regDef, ctx, isHighContrast, isDark, effectiveHue);
 		lightL = dep.l;
 		satFactor = dep.satFactor;
 	}
@@ -892,9 +962,18 @@ function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	return {
 		h: effectiveHue,
 		s: clamp(finalSat, 0, 1),
-		l: clamp(finalL / 100, 0, 1)
+		l: clamp(finalL / 100, 0, 1),
+		alpha: regDef.opacity ?? 1
 	};
 }
+function resolveShadowForScheme(def, ctx, isDark, isHighContrast) {
+	const bgVariant = getSchemeVariant(ctx.resolved.get(def.bg), isDark, isHighContrast);
+	let fgVariant;
+	if (def.fg) fgVariant = getSchemeVariant(ctx.resolved.get(def.fg), isDark, isHighContrast);
+	const intensity = isHighContrast ? pairHC(def.intensity) : pairNormal(def.intensity);
+	const tuning = resolveShadowTuning(def.tuning);
+	return computeShadow(bgVariant, fgVariant, intensity, tuning);
+}
 function resolveAllColors(hue, saturation, defs) {
 	validateColorDefs(defs);
 	const order = topoSort(defs);
@@ -904,6 +983,9 @@ function resolveAllColors(hue, saturation, defs) {
 		defs,
 		resolved: /* @__PURE__ */ new Map()
 	};
+	function defMode(def) {
+		return isShadowDef(def) ? void 0 : def.mode ?? "auto";
+	}
 	const lightMap = /* @__PURE__ */ new Map();
 	for (const name of order) {
 		const variant = resolveColorForScheme(name, defs[name], ctx, false, false);
@@ -914,7 +996,7 @@ function resolveAllColors(hue, saturation, defs) {
 			dark: variant,
 			lightContrast: variant,
 			darkContrast: variant,
-			mode: defs[name].mode ?? "auto"
+			mode: defMode(defs[name])
 		});
 	}
 	const lightHCMap = /* @__PURE__ */ new Map();
@@ -937,7 +1019,7 @@ function resolveAllColors(hue, saturation, defs) {
 		dark: lightMap.get(name),
 		lightContrast: lightHCMap.get(name),
 		darkContrast: lightHCMap.get(name),
-		mode: defs[name].mode ?? "auto"
+		mode: defMode(defs[name])
 	});
 	for (const name of order) {
 		const variant = resolveColorForScheme(name, defs[name], ctx, true, false);
@@ -967,7 +1049,7 @@ function resolveAllColors(hue, saturation, defs) {
 		dark: darkMap.get(name),
 		lightContrast: lightHCMap.get(name),
 		darkContrast: darkHCMap.get(name),
-		mode: defs[name].mode ?? "auto"
+		mode: defMode(defs[name])
 	});
 	return result;
 }
@@ -977,8 +1059,14 @@ const formatters = {
 	hsl: formatHsl,
 	oklch: formatOklch
 };
+function fmt(value, decimals) {
+	return parseFloat(value.toFixed(decimals)).toString();
+}
 function formatVariant(v, format = "okhsl") {
-	return formatters[format](v.h, v.s * 100, v.l * 100);
+	const base = formatters[format](v.h, v.s * 100, v.l * 100);
+	if (v.alpha >= 1) return base;
+	const closing = base.lastIndexOf(")");
+	return `${base.slice(0, closing)} / ${fmt(v.alpha, 4)})`;
 }
 function resolveModes(override) {
 	return {
@@ -1229,7 +1317,8 @@ glaze.configure = function configure(config) {
 		modes: {
 			dark: config.modes?.dark ?? globalConfig.modes.dark,
 			highContrast: config.modes?.highContrast ?? globalConfig.modes.highContrast
-		}
+		},
+		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning
 	};
 };
 /**
@@ -1251,6 +1340,40 @@ glaze.color = function color(input) {
 	return createColorToken(input);
 };
 /**
+* Compute a shadow color from a bg/fg pair and intensity.
+*/
+glaze.shadow = function shadow(input) {
+	const bg = parseOkhslInput(input.bg);
+	const fg = input.fg ? parseOkhslInput(input.fg) : void 0;
+	const tuning = resolveShadowTuning(input.tuning);
+	return computeShadow({
+		...bg,
+		alpha: 1
+	}, fg ? {
+		...fg,
+		alpha: 1
+	} : void 0, input.intensity, tuning);
+};
+/**
+* Format a resolved color variant as a CSS string.
+*/
+glaze.format = function format(variant, colorFormat) {
+	return formatVariant(variant, colorFormat);
+};
+function parseOkhslInput(input) {
+	if (typeof input === "string") {
+		const rgb = parseHex(input);
+		if (!rgb) throw new Error(`glaze: invalid hex color "${input}".`);
+		const [h, s, l] = srgbToOkhsl(rgb);
+		return {
+			h,
+			s,
+			l
+		};
+	}
+	return input;
+}
+/**
 * Create a theme from a hex color string.
 * Extracts hue and saturation from the color.
 */