@tenphi/glaze 0.15.1 → 0.16.0

package/dist/index.cjs

@@ -590,6 +590,24 @@ function formatOkhsl(h, s, l, pastel = false) {
 	return `okhsl(${fmt$1(h, 2)} ${fmt$1(outS, 2)}% ${fmt$1(l, 2)}%)`;
 }
 /**
+* Format OKHST values as a CSS `okhst(H S% T%)` string.
+* h: 0–360, s: 0–100, t: 0–100 (percentage scale for s and t).
+*
+* Pastel recompute matches `formatOkhsl`: convert via OKLab so external
+* parsers that only understand non-pastel OKHST render identically.
+*/
+function formatOkhst(h, s, t, pastel = false) {
+	let outS = s;
+	if (pastel) {
+		const REF_EPS = .05;
+		const den = Math.log(1 + REF_EPS) - Math.log(REF_EPS);
+		const y = Math.exp(t / 100 * den + Math.log(REF_EPS)) - REF_EPS;
+		const l = toe(Math.cbrt(Math.max(0, y)));
+		outS = oklabToOkhsl(okhslToOklab(h, s / 100, l, true), false)[1] * 100;
+	}
+	return `okhst(${fmt$1(h, 2)} ${fmt$1(outS, 2)}% ${fmt$1(t, 2)}%)`;
+}
+/**
 * Format OKHSL values as a CSS `rgb(R G B)` string.
 * Uses 2 decimal places to avoid 8-bit quantization contrast loss.
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
@@ -623,12 +641,34 @@ function formatHsl(h, s, l, pastel = false) {
 * h: 0–360, s: 0–100, l: 0–100 (percentage scale for s and l).
 */
 function formatOklch(h, s, l, pastel = false) {
-	const [L, a, b] = okhslToOklab(h, s / 100, l / 100, pastel);
-	const C = Math.sqrt(a * a + b * b);
-	let hh = Math.atan2(b, a) * (180 / Math.PI);
-	hh = constrainAngle(hh);
+	const [L, C, hh] = okhslToOklch(h, s / 100, l / 100, pastel);
 	return `oklch(${fmt$1(L, 4)} ${fmt$1(C, 4)} ${fmt$1(hh, 2)})`;
 }
+/**
+* Convert gamma-encoded sRGB channels (0–1) to a 6-digit lowercase hex
+* string (`#rrggbb`). Channels are clamped to [0,1] and rounded to 8-bit.
+* Alpha is not encoded here — DTCG carries it as a separate `alpha` field.
+*/
+function srgbToHex(rgb) {
+	const toByte = (c) => Math.max(0, Math.min(255, Math.round(c * 255)));
+	const r = toByte(rgb[0]);
+	const g = toByte(rgb[1]);
+	const b = toByte(rgb[2]);
+	return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+/**
+* Convert OKHSL (h: 0–360, s: 0–1, l: 0–1) to OKLCH components `[L, C, H]`.
+* L: 0–1, C: 0–~0.4 (chroma), H: 0–360 (hue). Shared by `formatOklch` and
+* the DTCG `oklch` colorSpace exporter so the two never drift apart.
+*/
+function okhslToOklch(h, s, l, pastel = false) {
+	const [L, a, b] = okhslToOklab(h, s, l, pastel);
+	return [
+		L,
+		Math.sqrt(a * a + b * b),
+		constrainAngle(Math.atan2(b, a) * (180 / Math.PI))
+	];
+}
 
 //#endregion
 //#region src/config.ts
@@ -658,7 +698,8 @@ function defaultConfig() {
 			highContrast: false
 		},
 		autoFlip: true,
-		pastel: false
+		pastel: false,
+		inferRole: true
 	};
 }
 let globalConfig = defaultConfig();
@@ -698,7 +739,8 @@ function configure(config) {
 		},
 		shadowTuning: config.shadowTuning ?? globalConfig.shadowTuning,
 		autoFlip: config.autoFlip ?? globalConfig.autoFlip,
-		pastel: config.pastel ?? globalConfig.pastel
+		pastel: config.pastel ?? globalConfig.pastel,
+		inferRole: config.inferRole ?? globalConfig.inferRole
 	};
 }
 function resetConfig() {
@@ -721,10 +763,57 @@ function mergeConfig(base, override) {
 		modes: base.modes,
 		shadowTuning: override.shadowTuning ?? base.shadowTuning,
 		autoFlip: override.autoFlip ?? base.autoFlip,
-		pastel: override.pastel ?? base.pastel
+		pastel: override.pastel ?? base.pastel,
+		inferRole: override.inferRole ?? base.inferRole
 	};
 }
 
+//#endregion
+//#region src/format-guard.ts
+const NON_NATIVE_FORMATS = new Set(["okhsl", "okhst"]);
+/**
+* Throw when a non-native Glaze color space is requested for an export that
+* emits raw CSS or non-Tasty token maps.
+*/
+function assertNativeFormat(format, method) {
+	if (format !== void 0 && NON_NATIVE_FORMATS.has(format)) throw new Error(`glaze: ${format} output is only supported by tasty() (not a native CSS color space). Use tasty({ format: '${format}' }) or pick a native format (oklch|hsl|rgb) for ${method}().`);
+}
+const SCHEME_FIELDS = [
+	{
+		field: "light",
+		modes: () => true
+	},
+	{
+		field: "dark",
+		modes: (m) => m.dark
+	},
+	{
+		field: "lightContrast",
+		modes: (m) => m.highContrast
+	},
+	{
+		field: "darkContrast",
+		modes: (m) => m.dark && m.highContrast
+	}
+];
+/**
+* Throw when `splitHue` is enabled but any exported color is not pastel.
+* Hue rotation is only clip-free when chroma is bounded by the hue-independent
+* safe chroma (`computeSafeChromaOKLCH`).
+*/
+function assertAllPastel(resolved, modes) {
+	const nonPastel = [];
+	for (const [name, color] of resolved) for (const { field, modes: active } of SCHEME_FIELDS) {
+		if (!active(modes)) continue;
+		if (color[field].pastel !== true) {
+			if (!nonPastel.includes(name)) nonPastel.push(name);
+			break;
+		}
+	}
+	if (nonPastel.length === 0) return;
+	throw new Error(`glaze: splitHue requires every color to be pastel (hue rotation is only clip-free when chroma is bounded by the hue-independent safe chroma). Non-pastel: ${nonPastel.join(", ")}. Set pastel: true (global or per-color) or drop splitHue.`);
+}
+
 //#endregion
 //#region src/hc-pair.ts
 function pairNormal(p) {
@@ -989,6 +1078,22 @@ function schemeToneRange(isDark, mode, isHighContrast, config) {
 function metricLuminance(metric, linearRgb) {
 	return metric === "apca" ? apcaLuminanceFromLinearRgb(linearRgb) : gamutClampedLuminance(linearRgb);
 }
+const APCA_PRESETS = {
+	preferred: 90,
+	body: 75,
+	content: 60,
+	large: 45,
+	"non-text": 30,
+	min: 15
+};
+/**
+* Resolve an APCA target — a raw Lc number (kept as-is) or an `ApcaPreset`
+* keyword mapped to its Lc value. The magnitude is forced non-negative.
+*/
+function resolveApcaTarget(value) {
+	if (typeof value === "number") return Math.abs(value);
+	return APCA_PRESETS[value];
+}
 const CONTRAST_PRESETS = {
 	AA: 4.5,
 	AAA: 7,
@@ -1005,16 +1110,18 @@ function pickPair(p, isHighContrast) {
 /**
 * Resolve a `ContrastSpec` (already selected from any outer HC pair) for a
 * given mode into `{ metric, target }`. Handles the inner metric HC pair and
-* preset resolution.
+* preset resolution. `polarity` is passed through to the result for the APCA
+* branch (it controls argument order in the solver); WCAG ignores it.
 */
-function resolveContrastForMode(spec, isHighContrast) {
+function resolveContrastForMode(spec, isHighContrast, polarity) {
 	if (typeof spec === "number" || typeof spec === "string") return {
 		metric: "wcag",
 		target: resolveMinContrast(spec)
 	};
 	if ("apca" in spec) return {
 		metric: "apca",
-		target: Math.abs(pickPair(spec.apca, isHighContrast))
+		target: resolveApcaTarget(pickPair(spec.apca, isHighContrast)),
+		polarity: polarity ?? "fg"
 	};
 	return {
 		metric: "wcag",
@@ -1079,20 +1186,25 @@ function cachedLuminance(metric, h, s, t, pastel) {
 /**
 * Score a candidate luminance against the base for a metric. Returns a value
 * that is `>= target` exactly when the floor is met (WCAG ratio, or APCA Lc
-* magnitude).
+* magnitude). For APCA, `polarity` selects the argument order: `'fg'` (the
+* default) treats the candidate as the text against a background base
+* (`apcaContrast(yCandidate, yBase)`); `'bg'` treats the candidate as the
+* background (`apcaContrast(yBase, yCandidate)`). The magnitude is taken
+* either way. WCAG is symmetric, so polarity is ignored there.
 */
-function metricScore(metric, yCandidate, yBase) {
+function metricScore(metric, yCandidate, yBase, polarity) {
 	if (metric === "wcag") return contrastRatioFromLuminance(yCandidate, yBase);
-	return Math.abs(apcaContrast(yCandidate, yBase));
+	const lc = polarity === "bg" ? apcaContrast(yBase, yCandidate) : apcaContrast(yCandidate, yBase);
+	return Math.abs(lc);
 }
 /**
 * Binary search one branch `[lo, hi]` for the position nearest to `anchor`
 * that meets `target`. The domain is whatever `lum` interprets (tone 0–1 or
 * mix parameter 0–1); the search is identical in both cases.
 */
-function searchBranch(lum, lo, hi, yBase, metric, target, epsilon, maxIter, anchor) {
-	const scoreLo = metricScore(metric, lum(lo), yBase);
-	const scoreHi = metricScore(metric, lum(hi), yBase);
+function searchBranch(lum, lo, hi, yBase, metric, target, epsilon, maxIter, anchor, polarity) {
+	const scoreLo = metricScore(metric, lum(lo), yBase, polarity);
+	const scoreHi = metricScore(metric, lum(hi), yBase, polarity);
 	if (scoreLo < target && scoreHi < target) return scoreLo >= scoreHi ? {
 		pos: lo,
 		contrast: scoreLo,
@@ -1107,13 +1219,13 @@ function searchBranch(lum, lo, hi, yBase, metric, target, epsilon, maxIter, anch
 	for (let i = 0; i < maxIter; i++) {
 		if (high - low < epsilon) break;
 		const mid = (low + high) / 2;
-		if (metricScore(metric, lum(mid), yBase) >= target) if (mid < anchor) low = mid;
+		if (metricScore(metric, lum(mid), yBase, polarity) >= target) if (mid < anchor) low = mid;
 		else high = mid;
 		else if (mid < anchor) high = mid;
 		else low = mid;
 	}
-	const scoreLow = metricScore(metric, lum(low), yBase);
-	const scoreHigh = metricScore(metric, lum(high), yBase);
+	const scoreLow = metricScore(metric, lum(low), yBase, polarity);
+	const scoreHigh = metricScore(metric, lum(high), yBase, polarity);
 	const lowPasses = scoreLow >= target;
 	const highPasses = scoreHigh >= target;
 	if (lowPasses && highPasses) return Math.abs(low - anchor) <= Math.abs(high - anchor) ? {
@@ -1156,8 +1268,8 @@ function wcagToneSeed(yBase, target, darker) {
 	return Math.max(0, Math.min(1, toneFromY(yClamped, REF_EPS) / 100));
 }
 function solveNearestContrast(opts) {
-	const { lum, yBase, metric, target, searchTarget, lo, hi, searchAnchor, distanceAnchor, epsilon, maxIterations, flip, initialIsLower } = opts;
-	const runBranch = (lower) => lower ? searchBranch(lum, lo, searchAnchor, yBase, metric, searchTarget, epsilon, maxIterations, searchAnchor) : searchBranch(lum, searchAnchor, hi, yBase, metric, searchTarget, epsilon, maxIterations, searchAnchor);
+	const { lum, yBase, metric, target, searchTarget, lo, hi, searchAnchor, distanceAnchor, epsilon, maxIterations, flip, initialIsLower, polarity } = opts;
+	const runBranch = (lower) => lower ? searchBranch(lum, lo, searchAnchor, yBase, metric, searchTarget, epsilon, maxIterations, searchAnchor, polarity) : searchBranch(lum, searchAnchor, hi, yBase, metric, searchTarget, epsilon, maxIterations, searchAnchor, polarity);
 	const initialResult = runBranch(initialIsLower);
 	initialResult.met = initialResult.contrast >= target;
 	if (initialResult.met && !flip) return {
@@ -1188,7 +1300,7 @@ function solveNearestContrast(opts) {
 	const extreme = initialIsLower ? lo : hi;
 	return {
 		pos: extreme,
-		contrast: metricScore(metric, lum(extreme), yBase),
+		contrast: metricScore(metric, lum(extreme), yBase, polarity),
 		met: false,
 		lower: initialIsLower
 	};
@@ -1199,11 +1311,11 @@ function solveNearestContrast(opts) {
 */
 function findToneForContrast(options) {
 	const { hue, saturation, preferredTone, baseLinearRgb, contrast, toneRange = [0, 1], epsilon = 1e-4, maxIterations = 18, pastel = false } = options;
-	const { metric, target } = contrast;
+	const { metric, target, polarity } = contrast;
 	const searchTarget = metric === "wcag" ? target * 1.01 : target + .5;
 	const yBase = metricLuminance(metric, baseLinearRgb);
 	const lum = (t) => cachedLuminance(metric, hue, saturation, t, pastel);
-	const scorePref = metricScore(metric, lum(preferredTone), yBase);
+	const scorePref = metricScore(metric, lum(preferredTone), yBase, polarity);
 	if (scorePref >= searchTarget) return {
 		tone: preferredTone,
 		contrast: scorePref,
@@ -1223,7 +1335,7 @@ function findToneForContrast(options) {
 		met: false,
 		branch: "preferred"
 	};
-	else initialIsDarker = metricScore(metric, lum(minT), yBase) >= metricScore(metric, lum(maxT), yBase);
+	else initialIsDarker = metricScore(metric, lum(minT), yBase, polarity) >= metricScore(metric, lum(maxT), yBase, polarity);
 	const solved = solveNearestContrast({
 		lum,
 		yBase,
@@ -1237,7 +1349,8 @@ function findToneForContrast(options) {
 		epsilon,
 		maxIterations,
 		flip: options.flip ?? false,
-		initialIsLower: initialIsDarker
+		initialIsLower: initialIsDarker,
+		polarity
 	});
 	return {
 		tone: solved.pos,
@@ -1253,10 +1366,10 @@ function findToneForContrast(options) {
 */
 function findValueForMixContrast(options) {
 	const { preferredValue, baseLinearRgb, contrast, luminanceAtValue, epsilon = 1e-4, maxIterations = 20 } = options;
-	const { metric, target } = contrast;
+	const { metric, target, polarity } = contrast;
 	const searchTarget = metric === "wcag" ? target * 1.01 : target + .5;
 	const yBase = metricLuminance(metric, baseLinearRgb);
-	const scorePref = metricScore(metric, luminanceAtValue(preferredValue), yBase);
+	const scorePref = metricScore(metric, luminanceAtValue(preferredValue), yBase, polarity);
 	if (scorePref >= searchTarget) return {
 		value: preferredValue,
 		contrast: scorePref,
@@ -1272,7 +1385,7 @@ function findValueForMixContrast(options) {
 		contrast: scorePref,
 		met: false
 	};
-	else initialIsLower = metricScore(metric, luminanceAtValue(0), yBase) >= metricScore(metric, luminanceAtValue(1), yBase);
+	else initialIsLower = metricScore(metric, luminanceAtValue(0), yBase, polarity) >= metricScore(metric, luminanceAtValue(1), yBase, polarity);
 	const solved = solveNearestContrast({
 		lum: luminanceAtValue,
 		yBase,
@@ -1286,7 +1399,8 @@ function findValueForMixContrast(options) {
 		epsilon,
 		maxIterations,
 		flip: options.flip ?? false,
-		initialIsLower
+		initialIsLower,
+		polarity
 	});
 	return {
 		value: solved.pos,
@@ -1296,6 +1410,114 @@ function findValueForMixContrast(options) {
 	};
 }
 
+//#endregion
+//#region src/roles.ts
+const SURFACE_KEYWORDS = new Set([
+	"surface",
+	"bg",
+	"background",
+	"fill",
+	"canvas",
+	"paper",
+	"layer"
+]);
+const TEXT_KEYWORDS = new Set([
+	"text",
+	"fg",
+	"foreground",
+	"content",
+	"ink",
+	"label",
+	"stroke"
+]);
+const BORDER_KEYWORDS = new Set([
+	"border",
+	"divider",
+	"outline",
+	"separator",
+	"hairline",
+	"rule"
+]);
+const ALIAS_TO_ROLE = {
+	surface: "surface",
+	bg: "surface",
+	background: "surface",
+	fill: "surface",
+	canvas: "surface",
+	paper: "surface",
+	layer: "surface",
+	text: "text",
+	fg: "text",
+	foreground: "text",
+	content: "text",
+	ink: "text",
+	label: "text",
+	stroke: "text",
+	border: "border",
+	divider: "border",
+	outline: "border",
+	separator: "border",
+	hairline: "border",
+	rule: "border"
+};
+/**
+* Normalize a `RoleInput` (canonical value or alias) into a canonical `Role`.
+* Returns `undefined` for unrecognized strings so callers can fall through to
+* the next step of the resolution chain.
+*/
+function normalizeRole(input) {
+	if (input === void 0) return void 0;
+	return ALIAS_TO_ROLE[input];
+}
+/**
+* Tokenize a color name into lowercase keyword tokens, splitting on
+* non-alphanumeric boundaries and at camelCase boundaries. Examples:
+* - `'button-text'` → `['button', 'text']`
+* - `'inputBg'` → `['input', 'bg']`
+* - `'card_border-outline'` → `['card', 'border', 'outline']`
+*/
+function tokenizeName(name) {
+	const pieces = name.split(/[^0-9a-zA-Z]+/).filter(Boolean);
+	const tokens = [];
+	for (const piece of pieces) {
+		const sub = piece.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/\s+/).filter(Boolean);
+		for (const s of sub) tokens.push(s.toLowerCase());
+	}
+	return tokens;
+}
+/**
+* Infer a `Role` from a color name by matching its tokens against the role
+* keyword sets. When multiple tokens match, the **last** recognized token
+* wins (so `button-text` → `text`, `input-bg` → `surface`, `card-border` →
+* `border`). Returns `undefined` when no token matches.
+*/
+function inferRoleFromName(name) {
+	const tokens = tokenizeName(name);
+	let inferred;
+	for (const token of tokens) if (SURFACE_KEYWORDS.has(token)) inferred = "surface";
+	else if (TEXT_KEYWORDS.has(token)) inferred = "text";
+	else if (BORDER_KEYWORDS.has(token)) inferred = "border";
+	return inferred;
+}
+/**
+* Map a role to its APCA polarity. `text` and `border` are foreground spots
+* against their base (the candidate is the text argument); `surface` is the
+* background (the base is the text argument).
+*/
+function roleToPolarity(role) {
+	return role === "surface" ? "bg" : "fg";
+}
+/**
+* The opposite role of `role`, used when a color with no explicit role and no
+* inferable name depends on a base: the dependent color plays the opposite
+* role of its base. `surface` ↔ `text`; `border` is treated as a foreground
+* spot, so its opposite is `surface`.
+*/
+function oppositeRole(role) {
+	if (role === "surface") return "text";
+	return "surface";
+}
+
 //#endregion
 //#region src/shadow.ts
 /**
@@ -1502,7 +1724,7 @@ function warnContrastUnmet(name, isDark, isHighContrast, contrast, actual) {
 * warning when the actual measured contrast drifts below the target.
 */
 function warnContrastDrift(name, isDark, isHighContrast, contrast, yColor, yBase) {
-	const actual = contrast.metric === "apca" ? Math.abs(apcaContrast(yColor, yBase)) : contrastRatioFromLuminance(yColor, yBase);
+	const actual = contrast.metric === "apca" ? Math.abs(contrast.polarity === "bg" ? apcaContrast(yBase, yColor) : apcaContrast(yColor, yBase)) : contrastRatioFromLuminance(yColor, yBase);
 	if (actual >= (contrast.metric === "apca" ? contrast.target - CONTRAST_WARN_SLACK_APCA : contrast.target * CONTRAST_WARN_SLACK_WCAG)) return;
 	const scheme = schemeLabel(isDark, isHighContrast);
 	if (dedupe(`drift|${name}|${scheme}|${contrast.metric}|${contrast.target.toFixed(2)}|${actual.toFixed(2)}`)) return;
@@ -1559,8 +1781,53 @@ function toToneVariant(v) {
 		alpha: v.alpha
 	};
 }
-function resolveContrastSpec(spec, isHighContrast) {
-	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast);
+/**
+* Resolve the role of a base color referenced by `baseName`, returning the
+* role the *dependent* color should take (the opposite of the base's role).
+* A base that lives in `defs` recursively resolves and is inverted via
+* `oppositeRole`; an external base (no local def, e.g. an injected standalone
+* token) is treated as a background, so the dependent defaults to foreground
+* (`'text'`).
+*/
+function resolveBaseRoleInMap(baseName, defs, inferRole, roles) {
+	if (!baseName) return void 0;
+	const baseDef = defs[baseName];
+	if (!baseDef) return "text";
+	return oppositeRole(resolveRoleInMap(baseName, baseDef, defs, inferRole, roles));
+}
+/**
+* Role-resolution core that does not need a full `ResolveContext`. Shared by
+* the resolver (via `resolveRole`) and `verifyContrastDrift`.
+*/
+function resolveRoleInMap(name, def, defs, inferRole, roles) {
+	const cached = roles.get(name);
+	if (cached) return cached;
+	let role;
+	if (isShadowDef(def)) role = "surface";
+	else if (isMixDef(def)) role = normalizeRole(def.role) ?? (inferRole ? inferRoleFromName(name) : void 0) ?? resolveBaseRoleInMap(def.base, defs, inferRole, roles) ?? "text";
+	else {
+		const regDef = def;
+		role = normalizeRole(regDef.role) ?? (inferRole ? inferRoleFromName(name) : void 0) ?? resolveBaseRoleInMap(regDef.base, defs, inferRole, roles) ?? "text";
+	}
+	const finalRole = role ?? "text";
+	roles.set(name, finalRole);
+	return finalRole;
+}
+/**
+* Resolve a color's semantic `role` (text / surface / border) per the chain:
+*   1. explicit `def.role` (normalized)
+*   2. inferred from the color name when `config.inferRole` is on
+*   3. opposite of the base's role
+*   4. `'text'` (foreground) default
+*
+* Memoized on `ctx.roles` so the four scheme passes share one resolution.
+* Shadows have no contrast participation and default to `'surface'`.
+*/
+function resolveRole(name, def, ctx) {
+	return resolveRoleInMap(name, def, ctx.defs, ctx.config.inferRole, ctx.roles);
+}
+function resolveContrastSpec(spec, isHighContrast, polarity) {
+	return resolveContrastForMode(isHighContrast ? pairHC(spec) : pairNormal(spec), isHighContrast, polarity);
 }
 /**
 * Apply the relative-tone delta against a base, honoring `flip`.
@@ -1582,14 +1849,14 @@ function resolveRootColor(def, isHighContrast) {
 		satFactor: clamp(def.saturation ?? 1, 0, 1)
 	};
 }
-function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue) {
+function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effectiveHue, polarity, effectivePastel) {
 	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 satFactor = clamp(def.saturation ?? 1, 0, 1);
 	const flip = def.flip ?? ctx.config.autoFlip;
-	const pastel = def.pastel ?? ctx.config.pastel;
+	const pastel = effectivePastel;
 	const baseVariant = getSchemeVariant(baseResolved, isDark, isHighContrast);
 	const baseTone = baseVariant.t * 100;
 	let preferredTone;
@@ -1605,7 +1872,7 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 	}
 	const rawContrast = def.contrast;
 	if (rawContrast !== void 0) {
-		const resolvedContrast = resolveContrastSpec(rawContrast, isHighContrast);
+		const resolvedContrast = resolveContrastSpec(rawContrast, isHighContrast, polarity);
 		const effectiveSat = isDark ? mapSaturationDark(satFactor * ctx.saturation / 100, mode, ctx.config) : satFactor * ctx.saturation / 100;
 		const baseOkhsl = toOkhslVariant(baseVariant);
 		const baseLinearRgb = okhslToLinearSrgb(baseOkhsl.h, baseOkhsl.s, baseOkhsl.l, baseVariant.pastel ?? ctx.config.pastel);
@@ -1637,11 +1904,12 @@ function resolveDependentColor(name, def, ctx, isHighContrast, isDark, effective
 }
 function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 	if (isShadowDef(def)) return resolveShadowForScheme(def, ctx, isDark, isHighContrast);
-	if (isMixDef(def)) return resolveMixForScheme(def, ctx, isDark, isHighContrast);
+	if (isMixDef(def)) return resolveMixForScheme(name, def, ctx, isDark, isHighContrast);
 	const regDef = def;
 	const mode = regDef.mode ?? "auto";
 	const isRoot = isAbsoluteTone(regDef.tone) && !regDef.base;
 	const effectiveHue = resolveEffectiveHue(ctx.hue, regDef.hue);
+	const polarity = roleToPolarity(resolveRole(name, def, ctx));
 	const pastel = regDef.pastel ?? ctx.config.pastel;
 	let finalTone;
 	let satFactor;
@@ -1650,7 +1918,7 @@ function resolveColorForScheme(name, def, ctx, isDark, isHighContrast) {
 		finalTone = mapToneForScheme(root.authorTone, mode, isDark, isHighContrast, ctx.config);
 		satFactor = root.satFactor;
 	} else {
-		const dep = resolveDependentColor(name, regDef, ctx, isHighContrast, isDark, effectiveHue);
+		const dep = resolveDependentColor(name, regDef, ctx, isHighContrast, isDark, effectiveHue, polarity, pastel);
 		finalTone = dep.tone;
 		satFactor = dep.satFactor;
 	}
@@ -1713,7 +1981,7 @@ function linearRgbToToneVariant(rgb, pastel) {
 		alpha: 1
 	});
 }
-function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
+function resolveMixForScheme(name, def, ctx, isDark, isHighContrast) {
 	const baseResolved = ctx.resolved.get(def.base);
 	const targetResolved = ctx.resolved.get(def.target);
 	const baseVariant = toOkhslVariant(getSchemeVariant(baseResolved, isDark, isHighContrast));
@@ -1721,11 +1989,12 @@ function resolveMixForScheme(def, ctx, isDark, isHighContrast) {
 	let t = clamp(isHighContrast ? pairHC(def.value) : pairNormal(def.value), 0, 100) / 100;
 	const blend = def.blend ?? "opaque";
 	const space = def.space ?? "okhsl";
+	const polarity = roleToPolarity(resolveRole(name, def, ctx));
 	const pastel = def.pastel ?? ctx.config.pastel;
 	const baseLinear = okhslVariantToLinearRgb(baseVariant, baseVariant.pastel ?? ctx.config.pastel);
 	const targetLinear = okhslVariantToLinearRgb(targetVariant, targetVariant.pastel ?? ctx.config.pastel);
 	if (def.contrast !== void 0) {
-		const resolvedContrast = resolveContrastSpec(def.contrast, isHighContrast);
+		const resolvedContrast = resolveContrastSpec(def.contrast, isHighContrast, polarity);
 		const metric = resolvedContrast.metric;
 		let luminanceAt;
 		if (blend === "transparent" || space === "srgb") luminanceAt = (v) => metricLuminance(metric, linearSrgbLerp(baseLinear, targetLinear, v));
@@ -1814,6 +2083,7 @@ function seedField(order, ctx, field, source) {
 * its tone implies because chromatic luminance drifts from the gray tone.
 */
 function verifyContrastDrift(order, defs, result, config) {
+	const roles = /* @__PURE__ */ new Map();
 	for (const name of order) {
 		const def = defs[name];
 		if (isShadowDef(def) || isMixDef(def)) continue;
@@ -1822,6 +2092,7 @@ function verifyContrastDrift(order, defs, result, config) {
 		const color = result.get(name);
 		const base = result.get(regDef.base);
 		if (!color || !base) continue;
+		const polarity = roleToPolarity(resolveRoleInMap(name, def, defs, config.inferRole, roles));
 		for (const s of [
 			{
 				isDark: false,
@@ -1844,7 +2115,7 @@ function verifyContrastDrift(order, defs, result, config) {
 				field: "darkContrast"
 			}
 		]) {
-			const spec = resolveContrastSpec(regDef.contrast, s.isHighContrast);
+			const spec = resolveContrastSpec(regDef.contrast, s.isHighContrast, polarity);
 			const cVariant = color[s.field];
 			const bVariant = base[s.field];
 			const cOkhsl = toOkhslVariant(cVariant);
@@ -1865,7 +2136,8 @@ function resolveAllColors(hue, saturation, defs, config, externalBases) {
 		saturation,
 		defs,
 		resolved: /* @__PURE__ */ new Map(),
-		config
+		config,
+		roles: /* @__PURE__ */ new Map()
 	};
 	if (externalBases) for (const [name, color] of externalBases) ctx.resolved.set(name, color);
 	const lightMap = runPass(order, defs, ctx, false, false, "light");
@@ -1889,17 +2161,121 @@ function resolveAllColors(hue, saturation, defs, config, externalBases) {
 	return result;
 }
 
+//#endregion
+//#region src/channels.ts
+/**
+* Hue channel planning for `splitHue` exports.
+*
+* Builds per-color hue var references and scheme-independent `--*-hue`
+* declarations for oklch CSS / Tasty output when every color is pastel.
+*/
+const ACHROMATIC_EPSILON = 1e-6;
+function cssProp(prefix, name, suffix) {
+	return `--${prefix}${name}${suffix}`;
+}
+function isAchromatic(v) {
+	return v.s <= ACHROMATIC_EPSILON;
+}
+function themeHuePlan(name, def, variant, ctx) {
+	if (def === void 0 || isShadowDef(def) || isMixDef(def) || isAchromatic(variant)) return {
+		hueVar: "",
+		inline: true,
+		declarations: []
+	};
+	const regDef = def;
+	const baseHueVar = `var(--${ctx.baseName}-hue)`;
+	if (regDef.hue === void 0) return {
+		hueVar: baseHueVar,
+		inline: false,
+		declarations: []
+	};
+	const parsed = parseRelativeOrAbsolute(regDef.hue);
+	const prop = cssProp(ctx.prefix, name, "-hue");
+	if (parsed.relative) {
+		const sign = parsed.value >= 0 ? "+" : "-";
+		const magnitude = Math.abs(parsed.value);
+		const value = `calc(var(--${ctx.baseName}-hue) ${sign} ${magnitude})`;
+		return {
+			hueVar: `var(${prop})`,
+			inline: false,
+			declarations: [{
+				prop,
+				value
+			}]
+		};
+	}
+	const absHue = (parsed.value % 360 + 360) % 360;
+	return {
+		hueVar: `var(${prop})`,
+		inline: false,
+		declarations: [{
+			prop,
+			value: String(absHue)
+		}]
+	};
+}
+function standaloneHuePlan(name, variant, ctx) {
+	if (isAchromatic(variant)) return {
+		hueVar: "",
+		inline: true,
+		declarations: []
+	};
+	const hue = ctx.resolvedHue ?? variant.h;
+	const prop = cssProp(ctx.prefix, name, "-hue");
+	return {
+		hueVar: `var(${prop})`,
+		inline: false,
+		declarations: [{
+			prop,
+			value: String(hue)
+		}]
+	};
+}
+function buildHuePlan(name, def, variant, ctx) {
+	if (ctx.mode === "standalone") return standaloneHuePlan(name, variant, ctx);
+	return themeHuePlan(name, def, variant, ctx);
+}
+/** Collect unique hue declarations across all colors (theme + per-color). */
+function collectHueDeclarations(resolved, ctx) {
+	if (ctx.emitDeclarations === false) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	const push = (decl) => {
+		if (seen.has(decl.prop)) return;
+		seen.add(decl.prop);
+		out.push(decl);
+	};
+	if (ctx.mode === "theme") push({
+		prop: `--${ctx.baseName}-hue`,
+		value: String(ctx.seedHue)
+	});
+	for (const [name, color] of resolved) {
+		const def = ctx.defs[name];
+		const plan = buildHuePlan(name, def, color.light, ctx);
+		for (const decl of plan.declarations) push(decl);
+	}
+	return out;
+}
+function buildHuePlans(resolved, ctx) {
+	const plans = /* @__PURE__ */ new Map();
+	for (const [name, color] of resolved) plans.set(name, buildHuePlan(name, ctx.defs[name], color.light, ctx));
+	return plans;
+}
+
 //#endregion
 //#region src/formatters.ts
 /**
 * Output formatting for resolved color maps.
 *
 * Owns the CSS-string formatter dispatch table (`okhsl` / `rgb` / `hsl` /
-* `oklch`) and the four token-map shapes Glaze emits:
+* `oklch`) and the token-map shapes Glaze emits:
 * - `buildTokenMap` — Tasty style-to-state bindings (`#name` keys, state aliases).
 * - `buildFlatTokenMap` — `{ light, dark, ... }` per-variant maps.
 * - `buildJsonMap` — `{ name: { light, dark, ... } }` per-color JSON.
 * - `buildCssMap` — CSS custom property declaration strings per variant.
+* - `buildDtcgMap` — W3C DTCG (2025.10) token documents, one per scheme.
+* - `buildDtcgResolver` — W3C DTCG Resolver-Module document (one modifier, a context per scheme).
+* - `buildTailwindMap` — Tailwind v4 `@theme` block + dark/HC overrides.
 */
 const formatters = {
 	okhsl: formatOkhsl,
@@ -1911,13 +2287,37 @@ function fmt(value, decimals) {
 	return parseFloat(value.toFixed(decimals)).toString();
 }
 function formatVariant(v, format = "okhsl", pastel = false) {
+	const effectivePastel = v.pastel ?? pastel;
+	let base;
+	if (format === "okhst") base = formatOkhst(v.h, v.s * 100, v.t * 100, effectivePastel);
+	else {
+		const { l } = variantToOkhsl(v);
+		base = formatters[format](v.h, v.s * 100, l * 100, effectivePastel);
+	}
+	if (v.alpha >= 1) return base;
+	const closing = base.lastIndexOf(")");
+	return `${base.slice(0, closing)} / ${fmt(v.alpha, 4)})`;
+}
+/**
+* Format a resolved variant as `oklch(L C <hueVar>)`, splicing a CSS hue var
+* for `splitHue` exports. Falls back to inline when the plan is inline.
+*/
+function formatVariantHue(v, plan, pastel = false) {
 	const effectivePastel = v.pastel ?? pastel;
 	const { l } = variantToOkhsl(v);
-	const base = formatters[format](v.h, v.s * 100, l * 100, effectivePastel);
+	const [L, C] = okhslToOklch(v.h, v.s, l, effectivePastel);
+	let base;
+	if (plan.inline) if (v.s <= 1e-6) base = `oklch(${fmt(L, 4)} 0 0)`;
+	else base = formatOklch(v.h, v.s * 100, l * 100, effectivePastel);
+	else base = `oklch(${fmt(L, 4)} ${fmt(C, 4)} ${plan.hueVar})`;
 	if (v.alpha >= 1) return base;
 	const closing = base.lastIndexOf(")");
 	return `${base.slice(0, closing)} / ${fmt(v.alpha, 4)})`;
 }
+function formatColorValue(v, format, pastel, huePlan) {
+	if (format === "oklch" && huePlan !== void 0) return formatVariantHue(v, huePlan, pastel);
+	return formatVariant(v, format, pastel);
+}
 function resolveModes(override) {
 	const cfg = getConfig();
 	return {
@@ -1925,18 +2325,36 @@ function resolveModes(override) {
 		highContrast: override?.highContrast ?? cfg.modes.highContrast
 	};
 }
-function buildTokenMap(resolved, prefix, states, modes, format = "okhsl", pastel = false) {
+function buildTokenMap(resolved, prefix, states, modes, format = "okhsl", pastel = false, channelCtx) {
 	const tokens = {};
+	const huePlans = channelCtx !== void 0 && format === "oklch" ? buildHuePlans(resolved, channelCtx) : void 0;
+	if (huePlans !== void 0 && channelCtx !== void 0) {
+		const emitDecls = channelCtx.emitDeclarations !== false;
+		if (emitDecls && channelCtx.mode === "theme") tokens[`#${channelCtx.baseName}-hue`] = { "": String(channelCtx.seedHue) };
+		for (const [name, color] of resolved) {
+			const plan = huePlans.get(name);
+			if (emitDecls) for (const decl of plan.declarations) {
+				const key = `#${decl.prop.slice(2)}`;
+				if (!(key in tokens)) tokens[key] = { "": decl.value };
+			}
+			const colorKey = `#${prefix}${name}`;
+			tokens[colorKey] = buildTokenEntry(color, states, modes, format, pastel, huePlans.get(name));
+		}
+		return tokens;
+	}
 	for (const [name, color] of resolved) {
 		const key = `#${prefix}${name}`;
-		const entry = { "": formatVariant(color.light, format, pastel) };
-		if (modes.dark) entry[states.dark] = formatVariant(color.dark, format, pastel);
-		if (modes.highContrast) entry[states.highContrast] = formatVariant(color.lightContrast, format, pastel);
-		if (modes.dark && modes.highContrast) entry[`${states.dark} & ${states.highContrast}`] = formatVariant(color.darkContrast, format, pastel);
-		tokens[key] = entry;
+		tokens[key] = buildTokenEntry(color, states, modes, format, pastel);
 	}
 	return tokens;
 }
+function buildTokenEntry(color, states, modes, format, pastel, huePlan) {
+	const entry = { "": formatColorValue(color.light, format, pastel, huePlan) };
+	if (modes.dark) entry[states.dark] = formatColorValue(color.dark, format, pastel, huePlan);
+	if (modes.highContrast) entry[states.highContrast] = formatColorValue(color.lightContrast, format, pastel, huePlan);
+	if (modes.dark && modes.highContrast) entry[`${states.dark} & ${states.highContrast}`] = formatColorValue(color.darkContrast, format, pastel, huePlan);
+	return entry;
+}
 function buildFlatTokenMap(resolved, prefix, modes, format = "okhsl", pastel = false) {
 	const result = { light: {} };
 	if (modes.dark) result.dark = {};
@@ -1962,19 +2380,22 @@ function buildJsonMap(resolved, modes, format = "okhsl", pastel = false) {
 	}
 	return result;
 }
-function buildCssMap(resolved, prefix, suffix, format, pastel = false) {
+function buildCssMap(resolved, prefix, suffix, format, pastel = false, channelCtx) {
 	const lines = {
 		light: [],
 		dark: [],
 		lightContrast: [],
 		darkContrast: []
 	};
+	const huePlans = channelCtx !== void 0 && format === "oklch" ? buildHuePlans(resolved, channelCtx) : void 0;
+	if (huePlans !== void 0 && channelCtx !== void 0) for (const decl of collectHueDeclarations(resolved, channelCtx)) lines.light.push(`${decl.prop}: ${decl.value};`);
 	for (const [name, color] of resolved) {
 		const prop = `--${prefix}${name}${suffix}`;
-		lines.light.push(`${prop}: ${formatVariant(color.light, format, pastel)};`);
-		lines.dark.push(`${prop}: ${formatVariant(color.dark, format, pastel)};`);
-		lines.lightContrast.push(`${prop}: ${formatVariant(color.lightContrast, format, pastel)};`);
-		lines.darkContrast.push(`${prop}: ${formatVariant(color.darkContrast, format, pastel)};`);
+		const plan = huePlans?.get(name);
+		lines.light.push(`${prop}: ${formatColorValue(color.light, format, pastel, plan)};`);
+		lines.dark.push(`${prop}: ${formatColorValue(color.dark, format, pastel, plan)};`);
+		lines.lightContrast.push(`${prop}: ${formatColorValue(color.lightContrast, format, pastel, plan)};`);
+		lines.darkContrast.push(`${prop}: ${formatColorValue(color.darkContrast, format, pastel, plan)};`);
 	}
 	return {
 		light: lines.light.join("\n"),
@@ -1983,6 +2404,193 @@ function buildCssMap(resolved, prefix, suffix, format, pastel = false) {
 		darkContrast: lines.darkContrast.join("\n")
 	};
 }
+function roundTo(value, decimals) {
+	return parseFloat(value.toFixed(decimals));
+}
+/**
+* Build a DTCG `$value` color object for a resolved variant.
+*
+* `srgb` (default) emits gamma sRGB components in 0–1 plus a 6-digit `hex`
+* hint — the most universally understood form (Figma, Tokens Studio, Style
+* Dictionary). `oklch` emits `[L, C, H]` components with no hex — Glaze-native
+* and wide-gamut. `alpha` is included only when below 1.
+*/
+function dtcgColorValue(v, colorSpace = "srgb", pastel = false) {
+	const effectivePastel = v.pastel ?? pastel;
+	const { l } = variantToOkhsl(v);
+	const alpha = v.alpha < 1 ? roundTo(v.alpha, 6) : void 0;
+	if (colorSpace === "oklch") {
+		const [L, C, H] = okhslToOklch(v.h, v.s, l, effectivePastel);
+		const value = {
+			colorSpace: "oklch",
+			components: [
+				roundTo(L, 6),
+				roundTo(C, 6),
+				roundTo(H, 4)
+			]
+		};
+		if (alpha !== void 0) value.alpha = alpha;
+		return value;
+	}
+	const [r, g, b] = okhslToSrgb(v.h, v.s, l, effectivePastel);
+	const value = {
+		colorSpace: "srgb",
+		components: [
+			roundTo(r, 6),
+			roundTo(g, 6),
+			roundTo(b, 6)
+		],
+		hex: srgbToHex([
+			r,
+			g,
+			b
+		])
+	};
+	if (alpha !== void 0) value.alpha = alpha;
+	return value;
+}
+function dtcgToken(v, colorSpace, pastel) {
+	return {
+		$type: "color",
+		$value: dtcgColorValue(v, colorSpace, pastel)
+	};
+}
+/**
+* Build a `GlazeDtcgResult`: one spec-conformant DTCG token document per
+* scheme variant, gated by `modes`. Light is always present.
+*/
+function buildDtcgMap(resolved, prefix, modes, colorSpace = "srgb", pastel = false) {
+	const light = {};
+	const dark = modes.dark ? {} : void 0;
+	const lightContrast = modes.highContrast ? {} : void 0;
+	const darkContrast = modes.dark && modes.highContrast ? {} : void 0;
+	for (const [name, color] of resolved) {
+		const key = `${prefix}${name}`;
+		light[key] = dtcgToken(color.light, colorSpace, pastel);
+		if (dark) dark[key] = dtcgToken(color.dark, colorSpace, pastel);
+		if (lightContrast) lightContrast[key] = dtcgToken(color.lightContrast, colorSpace, pastel);
+		if (darkContrast) darkContrast[key] = dtcgToken(color.darkContrast, colorSpace, pastel);
+	}
+	return {
+		light,
+		dark,
+		lightContrast,
+		darkContrast
+	};
+}
+/**
+* Default context names emitted on the `scheme` modifier — the Glaze variant
+* keys, so the resolver document mirrors `GlazeDtcgResult` exactly.
+*/
+const DEFAULT_DTCG_CONTEXT_NAMES = {
+	light: "light",
+	dark: "dark",
+	lightContrast: "lightContrast",
+	darkContrast: "darkContrast"
+};
+/**
+* Wrap a per-scheme `GlazeDtcgResult` into a single W3C DTCG Resolver-Module
+* document. The light document becomes `sets[setName].sources[0]` (the default
+* context); each other present variant becomes a `contexts[ctx]` override
+* array on a single `modifiers[modifierName]`. Absent variants (per the
+* `modes` already applied to `result`) are omitted — light is always present
+* and is the modifier `default`. Only the resolver-specific options are read;
+* `modes` / `colorSpace` were already consumed by the `buildDtcgMap` call that
+* produced `result`.
+*/
+function buildDtcgResolver(result, options) {
+	const setName = options?.setName ?? "base";
+	const modifierName = options?.modifierName ?? "scheme";
+	const ctx = {
+		...DEFAULT_DTCG_CONTEXT_NAMES,
+		...options?.contextNames
+	};
+	const contexts = { [ctx.light]: [] };
+	if (result.dark) contexts[ctx.dark] = [result.dark];
+	if (result.lightContrast) contexts[ctx.lightContrast] = [result.lightContrast];
+	if (result.darkContrast) contexts[ctx.darkContrast] = [result.darkContrast];
+	return {
+		version: options?.version ?? "2025.10",
+		sets: { [setName]: { sources: [result.light] } },
+		modifiers: { [modifierName]: {
+			default: ctx.light,
+			contexts
+		} },
+		resolutionOrder: [{ $ref: `#/sets/${setName}` }, { $ref: `#/modifiers/${modifierName}` }]
+	};
+}
+function tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel) {
+	const lines = {
+		light: [],
+		dark: [],
+		lightContrast: [],
+		darkContrast: []
+	};
+	for (const [name, color] of resolved) {
+		const prop = `--${cssPrefix}${themePrefix}${name}`;
+		lines.light.push(`${prop}: ${formatVariant(color.light, format, pastel)};`);
+		lines.dark.push(`${prop}: ${formatVariant(color.dark, format, pastel)};`);
+		lines.lightContrast.push(`${prop}: ${formatVariant(color.lightContrast, format, pastel)};`);
+		lines.darkContrast.push(`${prop}: ${formatVariant(color.darkContrast, format, pastel)};`);
+	}
+	return lines;
+}
+function indentBlock(text, pad) {
+	return text.split("\n").map((line) => line.length === 0 ? line : pad + line).join("\n");
+}
+function emitRule(selector, body) {
+	return `${selector} {\n${indentBlock(body, "  ")}\n}`;
+}
+/**
+* Emit a CSS block for a set of declarations scoped by one or more selectors
+* / at-rules. Class-like selectors concatenate (`.dark.high-contrast`);
+* at-rules (`@media …`) nest `:root` (or the chained selector) inside.
+*/
+function emitScoped(scopes, declarations) {
+	if (declarations.length === 0) return void 0;
+	const atRules = [];
+	let selectorChain = "";
+	for (const scope of scopes) if (scope.startsWith("@")) atRules.push(scope);
+	else selectorChain += scope;
+	let css = emitRule(selectorChain || ":root", declarations.join("\n"));
+	for (const rule of atRules) css = emitRule(rule, css);
+	return css;
+}
+/**
+* Render accumulated per-scheme declaration lines as a Tailwind v4 CSS string:
+* an `@theme` block (light baseline) plus dark / high-contrast overrides under
+* the configured selectors. Empty blocks are skipped.
+*/
+function emitTailwindCss(lines, modes, darkSelector, highContrastSelector) {
+	const blocks = [];
+	if (lines.light.length > 0) blocks.push(emitRule("@theme", lines.light.join("\n")));
+	if (modes.dark) {
+		const dark = emitScoped([darkSelector], lines.dark);
+		if (dark) blocks.push(dark);
+	}
+	if (modes.highContrast) {
+		const hc = emitScoped([highContrastSelector], lines.lightContrast);
+		if (hc) blocks.push(hc);
+	}
+	if (modes.dark && modes.highContrast) {
+		const dhc = emitScoped([darkSelector, highContrastSelector], lines.darkContrast);
+		if (dhc) blocks.push(dhc);
+	}
+	return blocks.join("\n\n");
+}
+/**
+* Build per-scheme declaration lines for a single theme (used by
+* `theme.tailwind()` and as the palette `buildOne` step).
+*/
+function buildTailwindLines(resolved, themePrefix, cssPrefix, format, pastel) {
+	return tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel);
+}
+/**
+* Build a complete Tailwind v4 CSS string for a single theme.
+*/
+function buildTailwindMap(resolved, themePrefix, cssPrefix, modes, format, darkSelector, highContrastSelector, pastel = false) {
+	return emitTailwindCss(tailwindLinesFor(resolved, themePrefix, cssPrefix, format, pastel), modes, darkSelector, highContrastSelector);
+}
 
 //#endregion
 //#region src/color-token.ts
@@ -2327,6 +2935,7 @@ function buildStandaloneValueDefs(main, options) {
 		flip: options?.flip,
 		opacity: options?.opacity,
 		pastel: options?.pastel,
+		role: options?.role,
 		base: hasExternalBase ? STANDALONE_BASE : needsSeedAnchor ? STANDALONE_SEED : void 0
 	};
 	const defs = { [primary]: valueDef };
@@ -2367,10 +2976,51 @@ function createColorTokenFromDefs(seedHue, seedSaturation, defs, primary, effect
 		token: tokenLike,
 		tasty: tokenLike,
 		json(options) {
-			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), options?.format, effectiveConfig.pastel)[primary];
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "json");
+			return buildJsonMap(resolveOnce(), resolveModes(options?.modes), format, effectiveConfig.pastel)[primary];
 		},
 		css(options) {
-			return buildCssMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.suffix ?? "-color", options.format ?? "rgb", effectiveConfig.pastel);
+			const format = options.format ?? "rgb";
+			assertNativeFormat(format, "css");
+			const resolved = resolveOnce().get(primary);
+			const renamed = new Map([[options.name, resolved]]);
+			let channelCtx;
+			if (options.splitHue && format === "oklch") {
+				assertAllPastel(renamed, resolveModes());
+				channelCtx = {
+					seedHue,
+					baseName: options.name,
+					prefix: "",
+					defs: { [options.name]: defs[primary] },
+					mode: "standalone",
+					resolvedHue: resolved.light.h
+				};
+			}
+			return buildCssMap(renamed, "", options.suffix ?? "-color", format, effectiveConfig.pastel, channelCtx);
+		},
+		dtcg(options) {
+			const modes = resolveModes(options?.modes);
+			const doc = buildDtcgMap(resolveOnce(), "", modes, options?.colorSpace ?? "srgb", effectiveConfig.pastel);
+			const result = { light: doc.light[primary] };
+			if (doc.dark) result.dark = doc.dark[primary];
+			if (doc.lightContrast) result.lightContrast = doc.lightContrast[primary];
+			if (doc.darkContrast) result.darkContrast = doc.darkContrast[primary];
+			return result;
+		},
+		dtcgResolver(options) {
+			const doc = buildDtcgMap(resolveOnce(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", effectiveConfig.pastel);
+			const name = options.name;
+			const result = { light: { [name]: doc.light[primary] } };
+			if (doc.dark) result.dark = { [name]: doc.dark[primary] };
+			if (doc.lightContrast) result.lightContrast = { [name]: doc.lightContrast[primary] };
+			if (doc.darkContrast) result.darkContrast = { [name]: doc.darkContrast[primary] };
+			return buildDtcgResolver(result, options);
+		},
+		tailwind(options) {
+			const format = options.format ?? "oklch";
+			assertNativeFormat(format, "tailwind");
+			return buildTailwindMap(new Map([[options.name, resolveOnce().get(primary)]]), "", options.namespace ?? "color-", resolveModes(options?.modes), format, options.darkSelector ?? ".dark", options.highContrastSelector ?? ".high-contrast", effectiveConfig.pastel);
 		},
 		export: exportData
 	};
@@ -2428,6 +3078,7 @@ function createColorToken(input, configOverride) {
 		contrast: input.contrast,
 		opacity: input.opacity,
 		pastel: input.pastel,
+		role: input.role,
 		base: hasExternalBase ? STANDALONE_BASE : needsSeedAnchor ? STANDALONE_SEED : void 0
 	} };
 	if (needsSeedAnchor) {
@@ -2478,6 +3129,7 @@ function buildOverridesExport(options) {
 	if (options.opacity !== void 0) out.opacity = options.opacity;
 	if (options.name !== void 0) out.name = options.name;
 	if (options.pastel !== void 0) out.pastel = options.pastel;
+	if (options.role !== void 0) out.role = options.role;
 	if (options.base !== void 0) out.base = isGlazeColorToken(options.base) ? options.base.export() : options.base;
 	return out;
 }
@@ -2494,6 +3146,7 @@ function buildStructuredInputExport(input) {
 	if (input.contrast !== void 0) out.contrast = input.contrast;
 	if (input.name !== void 0) out.name = input.name;
 	if (input.pastel !== void 0) out.pastel = input.pastel;
+	if (input.role !== void 0) out.role = input.role;
 	if (input.base !== void 0) out.base = isGlazeColorToken(input.base) ? input.base.export() : input.base;
 	return out;
 }
@@ -2515,6 +3168,7 @@ function rehydrateOverrides(data) {
 	if (data.opacity !== void 0) out.opacity = data.opacity;
 	if (data.name !== void 0) out.name = data.name;
 	if (data.pastel !== void 0) out.pastel = data.pastel;
+	if (data.role !== void 0) out.role = data.role;
 	if (data.base !== void 0) out.base = isExportedToken(data.base) ? colorFromExport(data.base) : data.base;
 	return out;
 }
@@ -2531,6 +3185,7 @@ function rehydrateStructuredInput(data) {
 	if (data.contrast !== void 0) out.contrast = data.contrast;
 	if (data.name !== void 0) out.name = data.name;
 	if (data.pastel !== void 0) out.pastel = data.pastel;
+	if (data.role !== void 0) out.role = data.role;
 	if (data.base !== void 0) out.base = isExportedToken(data.base) ? colorFromExport(data.base) : data.base;
 	return out;
 }
@@ -2555,16 +3210,6 @@ function colorFromExport(data) {
 
 //#endregion
 //#region src/palette.ts
-/**
-* Palette factory.
-*
-* Composes multiple themes into a single token namespace with optional
-* theme-name prefixes and a "primary theme" that also surfaces an
-* unprefixed copy of its tokens. All four export methods (`tokens` /
-* `tasty` / `json` / `css`) share a `buildPaletteOutput` driver that
-* handles validation, per-theme iteration, prefix resolution, collision
-* filtering, and primary duplication.
-*/
 function resolvePrefix(options, themeName, defaultPrefix = false) {
 	const prefix = options?.prefix ?? defaultPrefix;
 	if (prefix === true) return `${themeName}-`;
@@ -2604,6 +3249,26 @@ function filterCollisions(resolved, prefix, seen, themeName, isPrimary) {
 	}
 	return filtered;
 }
+function colorMapFromTheme(theme) {
+	const defs = {};
+	for (const name of theme.list()) {
+		const def = theme.color(name);
+		if (def !== void 0) defs[name] = def;
+	}
+	return defs;
+}
+function channelCtxForTheme(theme, themeName, passPrefix, themedPrefix, splitHue, format, modes, filtered) {
+	if (!splitHue || format !== "oklch") return void 0;
+	assertAllPastel(filtered, modes);
+	return {
+		seedHue: theme.hue,
+		baseName: themeName,
+		prefix: themedPrefix,
+		defs: colorMapFromTheme(theme),
+		mode: "theme",
+		emitDeclarations: passPrefix === themedPrefix
+	};
+}
 /**
 * Shared per-theme driver for `tokens` / `tasty` / `css`. `json` skips
 * this because it doesn't do collision filtering or primary duplication.
@@ -2617,17 +3282,29 @@ function buildPaletteOutput(themes, paletteOptions, options, buildOne, merge, em
 		const resolved = theme.resolve();
 		const pastel = theme.getConfig().pastel;
 		const prefix = resolvePrefix(options, themeName, true);
-		merge(acc, buildOne(filterCollisions(resolved, prefix, seen, themeName), prefix, pastel));
-		if (themeName === effectivePrimary) merge(acc, buildOne(filterCollisions(resolved, "", seen, themeName, true), "", pastel));
+		merge(acc, buildOne(filterCollisions(resolved, prefix, seen, themeName), prefix, pastel, themeName, theme));
+		if (themeName === effectivePrimary) merge(acc, buildOne(filterCollisions(resolved, "", seen, themeName, true), "", pastel, themeName, theme));
 	}
 	return acc;
 }
 function createPalette(themes, paletteOptions) {
 	validatePrimaryTheme(paletteOptions?.primary, themes);
+	const buildDtcgResult = (options) => {
+		const modes = resolveModes(options?.modes);
+		const colorSpace = options?.colorSpace ?? "srgb";
+		return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel, _themeName, _theme) => buildDtcgMap(filtered, prefix, modes, colorSpace, pastel), (acc, part) => {
+			Object.assign(acc.light, part.light);
+			if (part.dark) acc.dark = Object.assign(acc.dark ?? {}, part.dark);
+			if (part.lightContrast) acc.lightContrast = Object.assign(acc.lightContrast ?? {}, part.lightContrast);
+			if (part.darkContrast) acc.darkContrast = Object.assign(acc.darkContrast ?? {}, part.darkContrast);
+		}, () => ({ light: {} }));
+	};
 	return {
 		tokens(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "tokens");
 			const modes = resolveModes(options?.modes);
-			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel) => buildFlatTokenMap(filtered, prefix, modes, options?.format, pastel), (acc, part) => {
+			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel) => buildFlatTokenMap(filtered, prefix, modes, format, pastel), (acc, part) => {
 				for (const variant of Object.keys(part)) {
 					if (!acc[variant]) acc[variant] = {};
 					Object.assign(acc[variant], part[variant]);
@@ -2641,18 +3318,27 @@ function createPalette(themes, paletteOptions) {
 				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
 			};
 			const modes = resolveModes(options?.modes);
-			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel) => buildTokenMap(filtered, prefix, states, modes, options?.format, pastel), (acc, part) => Object.assign(acc, part), () => ({}));
+			const format = options?.format ?? "okhsl";
+			return buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel, themeName, theme) => {
+				return buildTokenMap(filtered, prefix, states, modes, format, pastel, channelCtxForTheme(theme, themeName, prefix, resolvePrefix(options, themeName, true), options?.splitHue, format, modes, filtered));
+			}, (acc, part) => Object.assign(acc, part), () => ({}));
 		},
 		json(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "json");
 			const modes = resolveModes(options?.modes);
 			const result = {};
-			for (const [themeName, theme] of Object.entries(themes)) result[themeName] = buildJsonMap(theme.resolve(), modes, options?.format, theme.getConfig().pastel);
+			for (const [themeName, theme] of Object.entries(themes)) result[themeName] = buildJsonMap(theme.resolve(), modes, format, theme.getConfig().pastel);
 			return result;
 		},
 		css(options) {
 			const suffix = options?.suffix ?? "-color";
 			const format = options?.format ?? "rgb";
-			const lines = buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel) => buildCssMap(filtered, prefix, suffix, format, pastel), (acc, part) => {
+			assertNativeFormat(format, "css");
+			const modes = resolveModes();
+			const lines = buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel, themeName, theme) => {
+				return buildCssMap(filtered, prefix, suffix, format, pastel, channelCtxForTheme(theme, themeName, prefix, resolvePrefix(options, themeName, true), options?.splitHue, format, modes, filtered));
+			}, (acc, part) => {
 				for (const key of [
 					"light",
 					"dark",
@@ -2671,24 +3357,39 @@ function createPalette(themes, paletteOptions) {
 				lightContrast: lines.lightContrast.join("\n"),
 				darkContrast: lines.darkContrast.join("\n")
 			};
+		},
+		dtcg(options) {
+			return buildDtcgResult(options);
+		},
+		dtcgResolver(options) {
+			return buildDtcgResolver(buildDtcgResult(options), options);
+		},
+		tailwind(options) {
+			const modes = resolveModes(options?.modes);
+			const cssPrefix = options?.namespace ?? "color-";
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "tailwind");
+			const darkSelector = options?.darkSelector ?? ".dark";
+			const highContrastSelector = options?.highContrastSelector ?? ".high-contrast";
+			return emitTailwindCss(buildPaletteOutput(themes, paletteOptions, options, (filtered, prefix, pastel, _themeName, _theme) => buildTailwindLines(filtered, prefix, cssPrefix, format, pastel), (acc, part) => {
+				for (const variant of [
+					"light",
+					"dark",
+					"lightContrast",
+					"darkContrast"
+				]) acc[variant].push(...part[variant]);
+			}, () => ({
+				light: [],
+				dark: [],
+				lightContrast: [],
+				darkContrast: []
+			})), modes, darkSelector, highContrastSelector);
 		}
 	};
 }
 
 //#endregion
 //#region src/theme.ts
-/**
-* Theme factory.
-*
-* Wraps a hue/saturation seed, a mutable `ColorMap`, and an optional
-* per-theme `GlazeConfigOverride`. Exposes `tokens()` / `tasty()` /
-* `json()` / `css()` / `resolve()` / `export()` / `extend()`.
-*
-* The per-theme config override is **merged over the live global config at
-* resolve time** so the theme still reacts to later `configure()` calls
-* for fields it didn't override. The merged config is memoized by
-* `configVersion` to avoid rebuilding it on every export call.
-*/
 function createTheme(hue, saturation, initialColors, configOverride) {
 	let colorDefs = initialColors ? { ...initialColors } : {};
 	let cache = null;
@@ -2712,6 +3413,18 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 	function invalidate() {
 		cache = null;
 	}
+	function channelCtxFor(options, formatDefault, prefix) {
+		const format = options?.format ?? formatDefault;
+		if (!options?.splitHue || format !== "oklch") return void 0;
+		assertAllPastel(resolveCached(), resolveModes(options?.modes));
+		return {
+			seedHue: hue,
+			baseName: options.name ?? "theme",
+			prefix,
+			defs: colorDefs,
+			mode: "theme"
+		};
+	}
 	return {
 		get hue() {
 			return hue;
@@ -2775,8 +3488,10 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 			return new Map(resolveCached());
 		},
 		tokens(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "tokens");
 			const modes = resolveModes(options?.modes);
-			return buildFlatTokenMap(resolveCached(), "", modes, options?.format, getEffectiveConfig().pastel);
+			return buildFlatTokenMap(resolveCached(), "", modes, format, getEffectiveConfig().pastel);
 		},
 		tasty(options) {
 			const cfg = getEffectiveConfig();
@@ -2785,14 +3500,34 @@ function createTheme(hue, saturation, initialColors, configOverride) {
 				highContrast: options?.states?.highContrast ?? cfg.states.highContrast
 			};
 			const modes = resolveModes(options?.modes);
-			return buildTokenMap(resolveCached(), "", states, modes, options?.format, cfg.pastel);
+			const format = options?.format ?? "okhsl";
+			const channelCtx = channelCtxFor(options, "okhsl", "");
+			return buildTokenMap(resolveCached(), "", states, modes, format, cfg.pastel, channelCtx);
 		},
 		json(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "json");
 			const modes = resolveModes(options?.modes);
-			return buildJsonMap(resolveCached(), modes, options?.format, getEffectiveConfig().pastel);
+			return buildJsonMap(resolveCached(), modes, format, getEffectiveConfig().pastel);
 		},
 		css(options) {
-			return buildCssMap(resolveCached(), "", options?.suffix ?? "-color", options?.format ?? "rgb", getEffectiveConfig().pastel);
+			const format = options?.format ?? "rgb";
+			assertNativeFormat(format, "css");
+			const channelCtx = channelCtxFor(options, "rgb", "");
+			return buildCssMap(resolveCached(), "", options?.suffix ?? "-color", format, getEffectiveConfig().pastel, channelCtx);
+		},
+		dtcg(options) {
+			const modes = resolveModes(options?.modes);
+			return buildDtcgMap(resolveCached(), "", modes, options?.colorSpace ?? "srgb", getEffectiveConfig().pastel);
+		},
+		dtcgResolver(options) {
+			return buildDtcgResolver(buildDtcgMap(resolveCached(), "", resolveModes(options?.modes), options?.colorSpace ?? "srgb", getEffectiveConfig().pastel), options);
+		},
+		tailwind(options) {
+			const format = options?.format ?? "oklch";
+			assertNativeFormat(format, "tailwind");
+			const modes = resolveModes(options?.modes);
+			return buildTailwindMap(resolveCached(), "", options?.namespace ?? "color-", modes, format, options?.darkSelector ?? ".dark", options?.highContrastSelector ?? ".high-contrast", getEffectiveConfig().pastel);
 		}
 	};
 }
@@ -2986,29 +3721,39 @@ glaze.resetConfig = function resetConfig$1() {
 //#endregion
 exports.REF_EPS = REF_EPS;
 exports.apcaContrast = apcaContrast;
+exports.assertAllPastel = assertAllPastel;
+exports.assertNativeFormat = assertNativeFormat;
 exports.contrastRatioFromLuminance = contrastRatioFromLuminance;
 exports.cuspLightness = cuspLightness;
 exports.findToneForContrast = findToneForContrast;
 exports.findValueForMixContrast = findValueForMixContrast;
 exports.formatHsl = formatHsl;
 exports.formatOkhsl = formatOkhsl;
+exports.formatOkhst = formatOkhst;
 exports.formatOklch = formatOklch;
 exports.formatRgb = formatRgb;
 exports.fromTone = fromTone;
 exports.gamutClampedLuminance = gamutClampedLuminance;
 exports.glaze = glaze;
 exports.hslToSrgb = hslToSrgb;
+exports.inferRoleFromName = inferRoleFromName;
+exports.normalizeRole = normalizeRole;
 exports.okhslToLinearSrgb = okhslToLinearSrgb;
 exports.okhslToOkhst = okhslToOkhst;
 exports.okhslToOklab = okhslToOklab;
+exports.okhslToOklch = okhslToOklch;
 exports.okhslToSrgb = okhslToSrgb;
 exports.okhstToOkhsl = okhstToOkhsl;
 exports.oklabToOkhsl = oklabToOkhsl;
+exports.oppositeRole = oppositeRole;
 exports.parseHex = parseHex;
 exports.parseHexAlpha = parseHexAlpha;
 exports.relativeLuminanceFromLinearRgb = relativeLuminanceFromLinearRgb;
+exports.resolveApcaTarget = resolveApcaTarget;
 exports.resolveContrastForMode = resolveContrastForMode;
 exports.resolveMinContrast = resolveMinContrast;
+exports.roleToPolarity = roleToPolarity;
+exports.srgbToHex = srgbToHex;
 exports.srgbToOkhsl = srgbToOkhsl;
 exports.toTone = toTone;
 exports.toneFromY = toneFromY;