@qw-ui/tokens 0.3.0-next.4 → 0.3.0-next.5

package/dist/index.js

@@ -474,6 +474,41 @@ const T2_OKLCH_STEPS = [
 	800,
 	900
 ];
+/**
+* T2 步进锚定 Alpha：锚定 OKLCH 档位实色 + 固定 alpha 的设计校准 rgba
+* （`{seed}/{step}-a{alpha}`，如 `brand/500-a20`）。只声明被 T3 角色消费的条目，
+* 不作为完整刻度生成。
+*/
+const FIGMA_T2_STEP_ALPHA = [
+	{
+		seed: "brand",
+		step: 500,
+		alpha: 20
+	},
+	{
+		seed: "blue",
+		step: 600,
+		alpha: 20
+	},
+	{
+		seed: "blue",
+		step: 600,
+		alpha: 40
+	},
+	{
+		seed: "red",
+		step: 400,
+		alpha: 10
+	},
+	{
+		seed: "red",
+		step: 400,
+		alpha: 20
+	}
+];
+/** T2 `pure` 步进（标准常量 #000000，OLED 画布用）仅提供给 black。 */
+const T2_PURE_STEP = "pure";
+const T2_PURE_SEEDS = ["black"];
 const FIGMA_T2_SOLID_SCALE = {
 	brand: {
 		50: "#F2F6FF",
@@ -620,6 +655,11 @@ const FIGMA_T2_SOLID_SCALE = {
 		900: "#200B00"
 	}
 };
+/**
+* Figma「Color Token System」T3 语义角色表（60 个，light/dark 均引用 T2 路径）。
+* 与 Figma 节点 22258:49986 逐条对齐；`effect.shadow.*.color` 为复合阴影的颜色
+* 分量（对应 Figma 变量 `--qw-sem-effect-shadow-*-color`）。
+*/
 const FIGMA_T3_COLOR_ROLES = {
 	"surface.base": {
 		light: "color.white.base",
@@ -641,6 +681,26 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.blue.50",
 		dark: "color.blue.800"
 	},
+	"surface.canvas": {
+		light: "color.white.base",
+		dark: "color.black.pure"
+	},
+	"surface.sunken": {
+		light: "color.gray.100",
+		dark: "color.gray.800"
+	},
+	"surface.selected": {
+		light: "color.black.a5",
+		dark: "color.white.a10"
+	},
+	"surface.inverse": {
+		light: "color.black.800",
+		dark: "color.black.800"
+	},
+	"surface.canvas-subtle": {
+		light: "color.gray.50",
+		dark: "color.black.pure"
+	},
 	"content.primary": {
 		light: "color.black.base",
 		dark: "color.white.base"
@@ -661,6 +721,30 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.gray.400",
 		dark: "color.gray.500"
 	},
+	"content.disabled": {
+		light: "color.black.a30",
+		dark: "color.white.a30"
+	},
+	"content.link": {
+		light: "color.blue.700",
+		dark: "color.blue.400"
+	},
+	"content.icon-subtle": {
+		light: "color.black.a5",
+		dark: "color.white.a10"
+	},
+	"content.inverse": {
+		light: "color.white.base",
+		dark: "color.black.base"
+	},
+	"content.on-solid": {
+		light: "color.white.base",
+		dark: "color.white.base"
+	},
+	"content.on-warning-subtle": {
+		light: "color.yellow.800",
+		dark: "color.yellow.200"
+	},
 	"border.default": {
 		light: "color.gray.100",
 		dark: "color.gray.700"
@@ -673,6 +757,18 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.brand.base",
 		dark: "color.brand.500"
 	},
+	"border.subtle": {
+		light: "color.black.a5",
+		dark: "color.white.a5"
+	},
+	"border.disabled": {
+		light: "color.black.a10",
+		dark: "color.white.a10"
+	},
+	"border.on-media": {
+		light: "color.white.base",
+		dark: "color.white.base"
+	},
 	"fill.subtle": {
 		light: "color.gray.50",
 		dark: "color.white.a20"
@@ -689,6 +785,10 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.gray.50",
 		dark: "color.gray.900"
 	},
+	"fill.track": {
+		light: "color.black.a10",
+		dark: "color.white.a20"
+	},
 	"action.brand": {
 		light: "color.brand.base",
 		dark: "color.brand.500"
@@ -699,12 +799,44 @@ const FIGMA_T3_COLOR_ROLES = {
 	},
 	"action.selected": {
 		light: "color.blue.a20",
-		dark: "color.blue.a40"
+		dark: "color.blue.600-a40"
 	},
 	"action.inverse": {
 		light: "color.white.base",
 		dark: "color.black.base"
 	},
+	"control-action.brand.subtle": {
+		light: "color.brand.a10",
+		dark: "color.brand.500-a20"
+	},
+	"control-action.product.subtle": {
+		light: "color.blue.a10",
+		dark: "color.blue.600-a20"
+	},
+	"control-action.danger.default": {
+		light: "color.red.400",
+		dark: "color.red.400"
+	},
+	"control-action.danger.subtle": {
+		light: "color.red.400-a10",
+		dark: "color.red.400-a20"
+	},
+	"control-action.neutral.subtle": {
+		light: "color.black.a5",
+		dark: "color.white.a10"
+	},
+	"control-selection.brand": {
+		light: "color.brand.a10",
+		dark: "color.brand.500-a20"
+	},
+	"control-selection.product": {
+		light: "color.blue.a10",
+		dark: "color.blue.600-a20"
+	},
+	"selection.text-background": {
+		light: "color.blue.a20",
+		dark: "color.blue.600-a40"
+	},
 	"status.success": {
 		light: "color.green.base",
 		dark: "color.green.base"
@@ -721,13 +853,53 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.blue.base",
 		dark: "color.blue.600"
 	},
+	"status.success-subtle": {
+		light: "color.green.a10",
+		dark: "color.green.a20"
+	},
+	"status.warning-subtle": {
+		light: "color.yellow.a20",
+		dark: "color.yellow.a20"
+	},
+	"status.danger-subtle": {
+		light: "color.red.400-a10",
+		dark: "color.red.400-a20"
+	},
+	"status.info-subtle": {
+		light: "color.blue.a10",
+		dark: "color.blue.600-a20"
+	},
 	"overlay.scrim": {
 		light: "color.black.a50",
 		dark: "color.black.a70"
 	},
 	"overlay.guide": {
-		light: "color.black.a70",
-		dark: "color.black.a70"
+		light: "color.blue.a10",
+		dark: "color.blue.600-a20"
+	},
+	"overlay.media-subtle": {
+		light: "color.black.a40",
+		dark: "color.black.a40"
+	},
+	"overlay.media-strong": {
+		light: "color.black.a50",
+		dark: "color.black.a50"
+	},
+	shadow: {
+		light: "color.black.a10",
+		dark: "color.black.a50"
+	},
+	"effect.shadow.card.color": {
+		light: "color.black.a10",
+		dark: "color.black.a50"
+	},
+	"effect.shadow.floating.color": {
+		light: "color.black.a10",
+		dark: "color.black.a50"
+	},
+	"effect.shadow.dialog.color": {
+		light: "color.black.a10",
+		dark: "color.black.a50"
 	}
 };
 //#endregion
@@ -828,11 +1000,11 @@ const cubicBezier = z.tuple([
 const fontStack = z.array(z.string()).min(1);
 const colorSeedShape = Object.fromEntries(T1_COLOR_KEYS.map((key) => [key, seedColor]));
 /**
-* SeedSchema — T1 Seed 的唯一事实源校验（RFC 0001 §2.1，v3 修订）。
+* SeedSchema — T1 Seed 与兼容输入的运行时校验（RFC 0001 §2.1，v4 修订）。
 *
 * 五大类目 color/size/typography/motion/effect，字段结构对齐
-* packages/tokens/design/seed.tokens.json，全部字段必填——不允许省略后静默
-* 回退默认值，锚点缺口必须在 Seed 层显式补齐，Reference 层不得用硬编码兜底。
+* packages/tokens/design/seed.tokens.json。部分已不再驱动 canonical T2 的字段暂时
+* 保留为兼容输入；新 Reference 不得为了形式完整继续扩充伪 Seed。
 *
 * v3 变化：
 * - 颜色全部结构化（DTCG Color module，支持 srgb/oklch）。
@@ -881,8 +1053,11 @@ base: z.string() }),
 			textWindowsJa: fontStack
 		}),
 		fontWeight: z.object({
+			/** @deprecated T2 Font Weight 已是 standard-constant；保留到下一次 Seed API 主版本清理。 */
 			regular: z.number(),
+			/** @deprecated T2 Font Weight 已是 standard-constant；保留到下一次 Seed API 主版本清理。 */
 			medium: z.number(),
+			/** @deprecated T2 Font Weight 已是 standard-constant；保留到下一次 Seed API 主版本清理。 */
 			semibold: z.number()
 		}),
 		fontSize: z.object({ base: z.string() }),
@@ -1093,6 +1268,14 @@ function seedAlphaCss(seedColor, alpha) {
 	});
 	return rgba(hexRgb(seedColorToHex(seedColor)), alpha);
 }
+/** 从 Seed 颜色点分路径（"color.brand"）取 T1 键。 */
+function seedKeyOf(seedRef) {
+	return seedRef.split(".")[1];
+}
+/** 步进锚定 Alpha 的求值：FIGMA_T2_SOLID_SCALE 档位实色 + alpha → rgba。 */
+function stepAlphaCss(seed, step, alpha) {
+	return rgba(hexRgb(FIGMA_T2_SOLID_SCALE[seed][step]), alpha);
+}
 function formatFontFamily(list) {
 	return list.map((f) => /[\s./]/.test(f) ? `'${f}'` : f).join(", ");
 }
@@ -1154,6 +1337,7 @@ function evaluateDerivation(d, seed) {
 		case "oklchRamp": return ramp(seed.color[d.seedRef.split(".")[1]])[d.step];
 		case "figmaOklchScale": return d.value;
 		case "seedAlpha": return seedAlphaCss(seedValueAt(seed, d.seedRef), d.alpha);
+		case "stepAlpha": return stepAlphaCss(seedKeyOf(d.seedRef), d.step, d.alpha);
 		case "alphaScale": {
 			const step = seedValueAt(seed, d.stepRef);
 			return rgba(d.channel === "black" ? [
@@ -1168,7 +1352,7 @@ function evaluateDerivation(d, seed) {
 		}
 		case "fontStack": return formatFontFamily(seedValueAt(seed, d.seedRef));
 		case "cubicBezier": return formatCubicBezier(seedValueAt(seed, d.seedRef));
-		case "literal": return d.value;
+		case "literal": return String(d.value);
 		case "shadowLayer": {
 			const { offsetX, offsetY, blur, spread } = shadowShapeOf(seed, d.level);
 			return `${offsetX} ${offsetY} ${blur} ${spread} ${rgba([
@@ -1189,6 +1373,7 @@ function seedRefsOf(d) {
 		case "oklchRamp":
 		case "figmaOklchScale":
 		case "seedAlpha":
+		case "stepAlpha":
 		case "fontStack":
 		case "cubicBezier": return [d.seedRef];
 		case "offsetSteps": return [d.seedRef, d.stepRef];
@@ -1197,6 +1382,18 @@ function seedRefsOf(d) {
 		case "shadowLayer": return ["effect.shadow.base", "size.opacity.alphaStep"];
 	}
 }
+/** Derivation AST → 规范来源分类；作为 Figma/DTCG provenance 的唯一映射口。 */
+function sourceKindOf(d) {
+	switch (d.kind) {
+		case "alias":
+		case "fontStack":
+		case "cubicBezier": return "seed-alias";
+		case "figmaOklchScale":
+		case "stepAlpha": return "design-calibrated";
+		case "literal": return "standard-constant";
+		default: return "seed-derived";
+	}
+}
 /** 人读派生公式（Token Studio 展示用）。 */
 function formatDerivation(d) {
 	const sign = (n) => n >= 0 ? "+" : "−";
@@ -1210,20 +1407,24 @@ function formatDerivation(d) {
 		case "offsetSteps": return `= seed.${d.seedRef} ${sign(d.n)} seed.${d.stepRef} × ${Math.abs(d.n)}`;
 		case "oklchRamp": return `= oklch(seed.${d.seedRef}) @ L ${L_TARGETS[d.step]} · C × ${round2(chromaFactor(L_TARGETS[d.step]))}`;
 		case "figmaOklchScale": return `= figma Color/qw/t2/${d.seedRef.split(".")[1]}/${d.step}（OKLCH 设计校准）`;
+		case "stepAlpha": return `= figma Color/qw/t2/${d.seedRef.split(".")[1]}/${d.step}-a${round2(d.alpha * 100)}（步进锚定 Alpha）`;
 		case "seedAlpha": return `= seed.${d.seedRef} / ${round2(d.alpha * 100)}%`;
 		case "alphaScale": return `= ${d.channel === "black" ? "黑" : "白"} / seed.${d.stepRef} × ${d.multiplier}`;
-		case "literal": return `= ${d.value}（色彩空间端点，白名单字面量）`;
+		case "literal": return `= ${d.value}（canonical 标准常量）`;
 		case "shadowLayer": {
 			const f = SHADOW_LEVELS[d.level];
 			return `= seed.effect.shadow.base 形状 × {offset ${f.offset}, blur ${f.blur}} · 色 = 黑 / alphaStep × ${f.alphaMult}`;
 		}
 	}
 }
-function ref(path, derivation) {
+function ref(path, derivation, metadata = {}) {
+	const { sourceKind = sourceKindOf(derivation), ...details } = metadata;
 	return {
 		path,
 		cssVar: toVar("ref", path),
+		sourceKind,
 		seedRefs: seedRefsOf(derivation),
+		...details,
 		derivation
 	};
 }
@@ -1251,6 +1452,9 @@ function buildColorRampRecipes() {
 			seedRef,
 			step,
 			value: FIGMA_T2_SOLID_SCALE[name][step]
+		}, {
+			source: `Figma Color/qw/t2/${name}/${step}`,
+			rationale: "OKLCH solid scale is design-calibrated; the Seed records color-family lineage, not the final step value."
 		}));
 		out.push(ref([
 			"color",
@@ -1263,6 +1467,35 @@ function buildColorRampRecipes() {
 	}
 	return out;
 }
+/** 2. Figma T2 补充原语：步进锚定 Alpha（仅被 T3 消费的条目）+ black/pure 标准常量。 */
+function buildColorExtraRecipes() {
+	const out = [];
+	for (const { seed, step, alpha } of FIGMA_T2_STEP_ALPHA) out.push(ref([
+		"color",
+		seed,
+		`${step}-a${alpha}`
+	], {
+		kind: "stepAlpha",
+		seedRef: `color.${seed}`,
+		step,
+		alpha: alpha / 100
+	}, {
+		source: `Figma Color/qw/t2/${seed}/${step}-a${alpha}`,
+		rationale: "Step-anchored alpha is design-calibrated: both the anchored solid step and the alpha are pinned by the design file."
+	}));
+	out.push(ref([
+		"color",
+		"black",
+		"pure"
+	], {
+		kind: "literal",
+		value: "#000000"
+	}, {
+		source: "CSS Color sRGB endpoint",
+		rationale: "Mathematical black endpoint for OLED canvas; replaces deprecated neutral/1000 semantics; no theme-level generator input."
+	}));
+	return out;
+}
 /** 4. 间距刻度 = spacing.step × N (N=1..8)。 */
 function buildSpacingRecipes() {
 	const out = [];
@@ -1472,7 +1705,7 @@ const FONT_SIZE_FACTORS = {
 	xl: 1.429,
 	"2xl": 1.714
 };
-/** 11. 排版原子：字体族（三族 + 平台/语言变体）/字重直通，字号按既定倍数派生。 */
+/** 11. 排版原子：字体族来自平台 Seed；字重是机械标准常量；字号按既定倍数派生。 */
 function buildTypographyRecipes() {
 	const out = [];
 	for (const key of FONT_FAMILY_KEYS) out.push(ref([
@@ -1483,17 +1716,20 @@ function buildTypographyRecipes() {
 		kind: "fontStack",
 		seedRef: `typography.fontFamily.${key}`
 	}));
-	for (const key of [
-		"regular",
-		"medium",
-		"semibold"
+	for (const [key, value] of [
+		["regular", 400],
+		["medium", 500],
+		["semibold", 600]
 	]) out.push(ref([
 		"typography",
 		"fontWeight",
 		key
 	], {
-		kind: "alias",
-		seedRef: `typography.fontWeight.${key}`
+		kind: "literal",
+		value
+	}, {
+		source: "CSS Fonts numeric font-weight scale",
+		rationale: "Mechanical weight step; changing it is a semantic typography decision, not a global generator input."
 	}));
 	out.push(ref([
 		"typography",
@@ -1588,6 +1824,7 @@ function buildShadowRecipes() {
 function allReferenceRecipes() {
 	return [
 		...buildColorRampRecipes(),
+		...buildColorExtraRecipes(),
 		...buildSpacingRecipes(),
 		...buildRadiusRecipes(),
 		...buildControlIconSizeRecipes(),
@@ -1716,15 +1953,22 @@ const TYPOGRAPHY_ROLES = {
 		letterSpacingRef: T_LETTER
 	}
 };
-const COLOR_ROLES = {
-	...FIGMA_T3_COLOR_ROLES,
-	shadow: {
-		light: "color.black.a10",
-		dark: "color.black.a50"
-	}
+/**
+* 颜色角色的 Semantic 变量路径：绝大多数角色落在 `--qw-sem-color-*` 下；
+* `effect.shadow.*.color` 是复合阴影的颜色分量，对应 Figma 变量
+* `--qw-sem-effect-shadow-*-color`，不带 `color-` 前缀。
+*/
+function colorRoleSemPath(role) {
+	const segs = role.split(".");
+	return segs[0] === "effect" ? segs : ["color", ...segs];
+}
+const COLOR_ROLES = { ...FIGMA_T3_COLOR_ROLES };
+/** 复合阴影角色：形状取 Reference effect.shadow.<level>，颜色取各自的 effect.shadow.<role>.color 分量。 */
+const SHADOW_COMPOSITE_ROLES = {
+	card: "sm",
+	floating: "md",
+	dialog: "lg"
 };
-/** 复合阴影角色：形状取 Reference effect.shadow.<level>，颜色取 color.shadow。 */
-const SHADOW_COMPOSITE_ROLES = { dialog: "lg" };
 /**
 * 全量 Semantic 角色的结构化血缘表——"角色 → 引用的 Reference 路径（含 light/dark 分支）"。
 * 与 buildSemanticStructural/buildSemanticColor 的产出一一对应（顺序一致）。
@@ -1817,7 +2061,7 @@ function semanticRoleEntries() {
 		"standard"
 	], "motion.easing.standard");
 	for (const [path, refs] of Object.entries(COLOR_ROLES)) {
-		const segs = ["color", ...path.split(".")];
+		const segs = colorRoleSemPath(path);
 		out.push({
 			kind: "color",
 			path: segs.join("."),
@@ -1836,7 +2080,7 @@ function semanticRoleEntries() {
 			path: segs.join("."),
 			cssVar: semVar(segs),
 			shapeRef: `effect.shadow.${level}`,
-			colorRole: "color.shadow"
+			colorRole: `effect.shadow.${role}.color`
 		});
 	}
 	return out;
@@ -1864,9 +2108,9 @@ function buildSemanticColor(reference, mode) {
 		if (entry.kind !== "color") continue;
 		out[entry.cssVar] = pick(tokens, entry.refPath[mode]);
 	}
-	const shadowColor = out[semVar(["color", "shadow"])];
 	for (const [role, level] of Object.entries(SHADOW_COMPOSITE_ROLES)) {
 		const shape = shapes.shadow[level];
+		const shadowColor = out[semVar(colorRoleSemPath(`effect.shadow.${role}.color`))];
 		out[semVar([
 			"effect",
 			"shadow",
@@ -1905,8 +2149,9 @@ function derive(seed) {
 *
 * 与静态 tokens.css（解析后的字面值，SSR 稳定出口）不同，live CSS 把整棵派生
 * 树翻译成 CSS 原生表达式：
-* - T1 Seed 落为 `--qw-seed-*` 变量（唯一含具体数值的层）；
-* - T2 Reference 用 relative color（oklch(from …)）/ calc() 从 Seed 变量派生；
+* - T1 Seed 落为 `--qw-seed-*` 变量，承载需要全局级联的生成参数；
+* - T2 Reference 的 seed-derived 项用 relative color / calc() 派生，
+*   design-calibrated / standard-constant 项保留 canonical 直接值；
 * - T3 Semantic 全部是 `var(--qw-ref-*)` 别名；dark 模式只在暗色选择器下
 *   重映射 sem → 不同的 ref 档位。
 *
@@ -1914,11 +2159,11 @@ function derive(seed) {
 * 级联更新，零 JS 重算。依赖现代 CSS（relative color / round()），刻意不做
 * 老浏览器兼容——组件库消费方继续用静态 tokens.css。
 */
-const round4 = (n) => Math.round(n * 1e4) / 1e4;
+const round4$1 = (n) => Math.round(n * 1e4) / 1e4;
 function seedVar(dotted) {
 	return toVar("seed", dotted.split("."));
 }
-/** Seed 拍平成 `--qw-seed-*` → CSS 值。live CSS 里唯一携带具体数值的层。 */
+/** Seed 拍平成 `--qw-seed-*` → CSS 值；T2 仍可包含校准值或标准常量。 */
 function seedCssVars(seed) {
 	const out = {};
 	for (const [name, value] of Object.entries(seed.color)) out[seedVar(`color.${name}`)] = seedColorToCss(value);
@@ -1932,9 +2177,6 @@ function seedCssVars(seed) {
 	out[seedVar("size.opacity.alphaStep")] = String(seed.size.opacity.alphaStep);
 	out[seedVar("size.zIndex.step")] = String(seed.size.zIndex.step);
 	for (const key of FONT_FAMILY_KEYS) out[seedVar(`typography.fontFamily.${key}`)] = formatFontFamily(seed.typography.fontFamily[key]);
-	out[seedVar("typography.fontWeight.regular")] = String(seed.typography.fontWeight.regular);
-	out[seedVar("typography.fontWeight.medium")] = String(seed.typography.fontWeight.medium);
-	out[seedVar("typography.fontWeight.semibold")] = String(seed.typography.fontWeight.semibold);
 	out[seedVar("typography.fontSize.base")] = seed.typography.fontSize.base;
 	out[seedVar("typography.lineHeight.base")] = String(seed.typography.lineHeight.base);
 	out[seedVar("typography.letterSpacing.base")] = seed.typography.letterSpacing.base;
@@ -1972,13 +2214,14 @@ function derivationToCssExpr(d) {
 		case "offsetSteps": return `calc(var(${seedVar(d.seedRef)}) ${d.n >= 0 ? "+" : "-"} var(${seedVar(d.stepRef)}) * ${Math.abs(d.n)})`;
 		case "oklchRamp": {
 			const l = L_TARGETS[d.step];
-			const f = round4(chromaFactor(l));
+			const f = round4$1(chromaFactor(l));
 			return `oklch(from var(${seedVar(d.seedRef)}) ${l} calc(c * ${f}) h)`;
 		}
 		case "figmaOklchScale": return d.value;
-		case "seedAlpha": return `rgb(from var(${seedVar(d.seedRef)}) r g b / ${round4(d.alpha)})`;
+		case "seedAlpha": return `rgb(from var(${seedVar(d.seedRef)}) r g b / ${round4$1(d.alpha)})`;
+		case "stepAlpha": return stepAlphaCss(seedKeyOf(d.seedRef), d.step, d.alpha);
 		case "alphaScale": return `rgb(${d.channel === "black" ? "0 0 0" : "255 255 255"} / calc(var(${seedVar(d.stepRef)}) * ${d.multiplier}))`;
-		case "literal": return d.value;
+		case "literal": return String(d.value);
 		case "shadowLayer": {
 			const s = shadowShapeExprs(d.level);
 			const alpha = `calc(var(${seedVar("size.opacity.alphaStep")}) * ${SHADOW_LEVELS[d.level].alphaMult})`;
@@ -2021,6 +2264,372 @@ function buildLiveCss(seed, options = {}) {
 	].join("\n");
 }
 //#endregion
+//#region src/figma/color-snapshot.ts
+/**
+* color-snapshot — 生成 Figma `Color` 变量集合的 DTCG 快照（design/color.tokens.json）。
+*
+* Figma 导出自动化通道尚未建立（变量 ID 本次不回填），快照由
+* color-architecture.ts 的同一份事实表投影生成，供 validate:figma-color 与
+* color-contract 测试消费；接上 Figma 导出后以导出物替换本生成物。
+*/
+const NS$1 = "com.qianwen.qw-ui";
+const round4 = (n) => Math.round(n * 1e4) / 1e4;
+function hexComponents(hex) {
+	const m = /^#?([0-9a-f]{6})$/i.exec(hex);
+	if (!m) throw new Error(`[qw] invalid hex color: ${hex}`);
+	const n = Number.parseInt(m[1], 16);
+	return [
+		round4((n >> 16 & 255) / 255),
+		round4((n >> 8 & 255) / 255),
+		round4((n & 255) / 255)
+	];
+}
+function colorValue(hex, alpha = 1) {
+	return {
+		colorSpace: "srgb",
+		components: hexComponents(hex),
+		alpha
+	};
+}
+function t1Ref(seed) {
+	return `{qw.t1.${seed}}`;
+}
+/** T3 角色引用的 T2 点分路径（"color.blue.600-a20" → "qw.t2.blue.600-a20"）。 */
+function t2Ref(dotted) {
+	const [, seed, step] = dotted.split(".");
+	return `{qw.t2.${seed}.${step}}`;
+}
+function t2Token(value, provenance) {
+	return {
+		$type: "color",
+		$value: value,
+		$extensions: { [NS$1]: { provenance } }
+	};
+}
+function buildT1() {
+	const t1 = {};
+	for (const seed of T1_COLOR_KEYS) t1[seed] = {
+		$type: "color",
+		$value: colorValue(FIGMA_T1_SEED_HEX[seed])
+	};
+	return t1;
+}
+function buildT2() {
+	const t2 = {};
+	for (const seed of T1_COLOR_KEYS) {
+		const seedHex = FIGMA_T1_SEED_HEX[seed];
+		const steps = {};
+		steps.base = t2Token(colorValue(seedHex), {
+			sourceKind: "seed-alias",
+			seedRefs: [t1Ref(seed)],
+			formula: `= qw.t1.${seed}`
+		});
+		for (const alpha of T2_ALPHA_STEPS) steps[`a${alpha}`] = t2Token(colorValue(seedHex, alpha / 100), {
+			sourceKind: "seed-derived",
+			seedRefs: [t1Ref(seed)],
+			formula: `= qw.t1.${seed} / ${alpha}%`
+		});
+		for (const step of T2_OKLCH_STEPS) steps[String(step)] = t2Token(colorValue(FIGMA_T2_SOLID_SCALE[seed][step]), {
+			sourceKind: "design-calibrated",
+			seedRefs: [t1Ref(seed)],
+			source: `Figma Color/qw/t2/${seed}/${step}`,
+			formula: `= figma Color/qw/t2/${seed}/${step}（OKLCH 设计校准）`
+		});
+		for (const extra of FIGMA_T2_STEP_ALPHA) {
+			if (extra.seed !== seed) continue;
+			steps[`${extra.step}-a${extra.alpha}`] = t2Token(colorValue(FIGMA_T2_SOLID_SCALE[seed][extra.step], extra.alpha / 100), {
+				sourceKind: "design-calibrated",
+				seedRefs: [t1Ref(seed)],
+				source: `Figma Color/qw/t2/${seed}/${extra.step}-a${extra.alpha}`,
+				formula: `= figma Color/qw/t2/${seed}/${extra.step}-a${extra.alpha}（步进锚定 Alpha）`
+			});
+		}
+		if (T2_PURE_SEEDS.includes(seed)) steps.pure = t2Token(colorValue("#000000"), {
+			sourceKind: "standard-constant",
+			seedRefs: [],
+			source: "CSS Color sRGB endpoint",
+			rationale: "Mathematical black endpoint for OLED canvas; no theme-level generator input.",
+			formula: "= #000000（canonical 标准常量）"
+		});
+		t2[seed] = steps;
+	}
+	return t2;
+}
+function buildT3() {
+	const t3 = {};
+	for (const [role, refs] of Object.entries(FIGMA_T3_COLOR_ROLES)) {
+		const segs = role.split(".");
+		const node = {
+			$type: "color",
+			$value: t2Ref(refs.light),
+			$extensions: { [NS$1]: {
+				cssVar: toVar("sem", colorRoleSemPath(role)),
+				modes: {
+					light: t2Ref(refs.light),
+					dark: t2Ref(refs.dark)
+				}
+			} }
+		};
+		let cur = t3;
+		for (let i = 0; i < segs.length - 1; i++) {
+			const seg = segs[i];
+			if (!(seg in cur)) cur[seg] = {};
+			cur = cur[seg];
+		}
+		cur[segs[segs.length - 1]] = node;
+	}
+	return t3;
+}
+/** 生成 design/color.tokens.json 的完整 JSON 对象（qw/t1/t2/t3 结构）。 */
+function buildFigmaColorSnapshot() {
+	return {
+		$schema: "https://www.designtokens.org/schemas/2025.10/format.json",
+		$description: "qw-ui Color 变量集合快照（Figma 节点 22258:49986）。Figma 导出自动化通道建立前，由 scripts/export-design-tokens.ts 从 color-architecture.ts 同一份事实表投影生成，请勿手改；接上 Figma 导出后以导出物替换。校验：pnpm --filter @qw-ui/tokens validate:figma-color。",
+		$extensions: { [NS$1]: {
+			collection: "Color",
+			figmaNode: "22258:49986",
+			generated: true,
+			owner: "design-system"
+		} },
+		qw: {
+			t1: buildT1(),
+			t2: buildT2(),
+			t3: buildT3()
+		}
+	};
+}
+//#endregion
+//#region src/figma/color-contract.ts
+const T2_OKLCH_STEP_KEYS = T2_OKLCH_STEPS.map(String);
+const NS = "com.qianwen.qw-ui";
+const T1_SET = new Set(T1_COLOR_KEYS);
+const T2_ALPHA_SET = new Set(T2_ALPHA_KEYS);
+const T2_OKLCH_SET = new Set(T2_OKLCH_STEP_KEYS);
+const T2_PURE_SEED_SET = new Set(T2_PURE_SEEDS);
+const T3_SEGMENT = /^[a-z]+(?:-[a-z]+)*$/;
+/** 步进锚定 Alpha 步名（如 "500-a20"）：OKLCH 档位 + Alpha 档位两段。 */
+const T2_STEP_ALPHA_RE = /^(\d+)-a(\d+)$/;
+const PROVENANCE_SOURCE_KINDS = /* @__PURE__ */ new Set([
+	"seed-alias",
+	"seed-derived",
+	"design-calibrated",
+	"standard-constant",
+	"external-standard"
+]);
+const SEED_LINEAGE_KINDS = /* @__PURE__ */ new Set([
+	"seed-alias",
+	"seed-derived",
+	"design-calibrated"
+]);
+function isObject(value) {
+	return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function collectLeaves(node, path = [], out = []) {
+	if (!isObject(node)) return out;
+	if ("$value" in node) {
+		out.push({
+			path,
+			value: node.$value,
+			extensions: isObject(node.$extensions) ? node.$extensions : {}
+		});
+		return out;
+	}
+	for (const [key, child] of Object.entries(node)) {
+		if (key.startsWith("$")) continue;
+		collectLeaves(child, [...path, key], out);
+	}
+	return out;
+}
+function qwPath(path) {
+	const index = path.indexOf("qw");
+	return index >= 0 ? path.slice(index) : null;
+}
+function pathKey(path) {
+	return path.join(".");
+}
+function refToPath(ref) {
+	if (typeof ref !== "string") return null;
+	const match = /^\{(.+)\}$/.exec(ref.trim());
+	if (!match) return null;
+	return match[1].split(/[./]/).filter(Boolean);
+}
+function extensionObject(leaf) {
+	const ext = leaf.extensions[NS];
+	return isObject(ext) ? ext : {};
+}
+function modesOf(leaf) {
+	const ext = extensionObject(leaf);
+	return isObject(ext.modes) ? ext.modes : {};
+}
+function provenanceOf(leaf) {
+	const ext = extensionObject(leaf);
+	return isObject(ext.provenance) ? ext.provenance : {};
+}
+function isSolidColorValue(value) {
+	if (!isObject(value)) return false;
+	if (value.colorSpace !== "srgb" && value.colorSpace !== "oklch") return false;
+	if (!Array.isArray(value.components) || value.components.length !== 3) return false;
+	return value.alpha === 1;
+}
+function isColorLikeValue(value) {
+	if (!isObject(value)) return false;
+	if (value.colorSpace !== "srgb" && value.colorSpace !== "oklch") return false;
+	if (!Array.isArray(value.components) || value.components.length !== 3) return false;
+	return typeof value.alpha === "number" && value.alpha >= 0 && value.alpha <= 1;
+}
+function validateNoUnexpectedName(path, errors) {
+	const joined = pathKey(path);
+	if (joined.includes("_")) errors.push(`${joined}: token name must not contain underscores`);
+	if (path.some((segment) => /[A-Z]/.test(segment))) errors.push(`${joined}: token name must be lowercase`);
+}
+function validateT3Path(path, errors) {
+	const joined = pathKey(path);
+	for (const segment of path.slice(2)) if (!T3_SEGMENT.test(segment)) errors.push(`${joined}: T3 semantic segment "${segment}" must use kebab-case words without numeric suffixes`);
+}
+/** T2 步名分类：base / alpha / oklch / step-alpha / pure。 */
+function classifyT2Step(step) {
+	if (step === "base") return "base";
+	if (T2_ALPHA_SET.has(step)) return "alpha";
+	if (T2_OKLCH_SET.has(step)) return "oklch";
+	if (step === "pure") return "pure";
+	const match = T2_STEP_ALPHA_RE.exec(step);
+	if (match && T2_OKLCH_SET.has(match[1]) && T2_ALPHA_SET.has(`a${match[2]}`)) return "step-alpha";
+	return null;
+}
+/** 各 T2 步类对应的 provenance.sourceKind（血缘治理不变量）。 */
+const T2_STEP_SOURCE_KIND = {
+	base: "seed-alias",
+	alpha: "seed-derived",
+	oklch: "design-calibrated",
+	"step-alpha": "design-calibrated",
+	pure: "standard-constant"
+};
+function validateT2Provenance(leaf, seed, step, errors) {
+	const joined = pathKey(leaf.path);
+	const provenance = provenanceOf(leaf);
+	if (Object.keys(provenance).length === 0) {
+		errors.push(`${joined}: T2 token must declare $extensions.${NS}.provenance`);
+		return;
+	}
+	const { sourceKind, seedRefs } = provenance;
+	if (typeof sourceKind !== "string" || !PROVENANCE_SOURCE_KINDS.has(sourceKind)) {
+		errors.push(`${joined}: provenance.sourceKind must be one of ${[...PROVENANCE_SOURCE_KINDS].join(", ")}`);
+		return;
+	}
+	const stepKind = classifyT2Step(step);
+	if (stepKind && T2_STEP_SOURCE_KIND[stepKind] !== sourceKind) errors.push(`${joined}: T2 ${stepKind} token must declare provenance.sourceKind = "${T2_STEP_SOURCE_KIND[stepKind]}"`);
+	if (SEED_LINEAGE_KINDS.has(sourceKind)) {
+		const expected = `{qw.t1.${seed}}`;
+		if (!Array.isArray(seedRefs) || seedRefs.length !== 1 || seedRefs[0] !== expected) errors.push(`${joined}: provenance.seedRefs must be exactly ["${expected}"]`);
+		return;
+	}
+	if (Array.isArray(seedRefs) && seedRefs.length > 0) errors.push(`${joined}: provenance.sourceKind "${sourceKind}" must not fabricate Seed lineage`);
+	if (typeof provenance.source !== "string" || provenance.source.length === 0) errors.push(`${joined}: provenance.sourceKind "${sourceKind}" must declare provenance.source`);
+	if (typeof provenance.rationale !== "string" || provenance.rationale.length === 0) errors.push(`${joined}: provenance.sourceKind "${sourceKind}" must declare provenance.rationale`);
+}
+/** T3 角色全集（qw 路径），由 FIGMA_T3_COLOR_ROLES 投影。 */
+function figmaT3RolePaths() {
+	return Object.keys(FIGMA_T3_COLOR_ROLES).map((role) => pathKey([
+		"qw",
+		"t3",
+		...role.split(".")
+	]));
+}
+function validateFigmaColorTokens(doc) {
+	const errors = [];
+	const leaves = collectLeaves(doc).map((leaf) => ({
+		...leaf,
+		qwPath: qwPath(leaf.path)
+	})).filter((leaf) => leaf.qwPath != null);
+	const byQwPath = /* @__PURE__ */ new Map();
+	for (const leaf of leaves) {
+		const key = pathKey(leaf.qwPath);
+		if (byQwPath.has(key)) errors.push(`${key}: duplicated token path`);
+		byQwPath.set(key, leaf);
+		validateNoUnexpectedName(leaf.qwPath, errors);
+	}
+	const t1 = leaves.filter((leaf) => leaf.qwPath[1] === "t1");
+	const t2 = leaves.filter((leaf) => leaf.qwPath[1] === "t2");
+	const t3 = leaves.filter((leaf) => leaf.qwPath[1] === "t3");
+	const unknownLayers = leaves.filter((leaf) => ![
+		"t1",
+		"t2",
+		"t3"
+	].includes(leaf.qwPath[1] ?? ""));
+	for (const leaf of unknownLayers) errors.push(`${pathKey(leaf.qwPath)}: unknown Color token layer`);
+	const t1Keys = /* @__PURE__ */ new Set();
+	for (const leaf of t1) {
+		const [, , key, ...rest] = leaf.qwPath;
+		const joined = pathKey(leaf.qwPath);
+		if (rest.length > 0 || !key) errors.push(`${joined}: T1 token must be qw/t1/{seed}`);
+		if (key && !T1_SET.has(key)) errors.push(`${joined}: unexpected T1 seed "${key}"`);
+		if (!isSolidColorValue(leaf.value)) errors.push(`${joined}: T1 seed must be a solid color with alpha = 1`);
+		if (key) t1Keys.add(key);
+	}
+	const missingT1 = T1_COLOR_KEYS.filter((key) => !t1Keys.has(key));
+	const extraT1 = [...t1Keys].filter((key) => !T1_SET.has(key));
+	if (missingT1.length) errors.push(`qw.t1: missing required seeds ${missingT1.join(", ")}`);
+	if (extraT1.length) errors.push(`qw.t1: unexpected seeds ${extraT1.join(", ")}`);
+	const t2BySeed = /* @__PURE__ */ new Map();
+	for (const seed of T1_COLOR_KEYS) t2BySeed.set(seed, /* @__PURE__ */ new Set());
+	for (const leaf of t2) {
+		const [, , seed, step, ...rest] = leaf.qwPath;
+		const joined = pathKey(leaf.qwPath);
+		if (rest.length > 0 || !seed || !step) errors.push(`${joined}: T2 token must be qw/t2/{seed}/{base|alpha|oklch-step}`);
+		if (seed && !T1_SET.has(seed)) errors.push(`${joined}: T2 seed "${seed}" must exist in T1`);
+		const stepKind = step ? classifyT2Step(step) : null;
+		if (step && !stepKind) errors.push(`${joined}: unsupported T2 step "${step}"`);
+		if (stepKind === "pure" && seed && !T2_PURE_SEED_SET.has(seed)) errors.push(`${joined}: "pure" step is only provided for seeds ${[...T2_PURE_SEED_SET].join(", ")}`);
+		if (!isColorLikeValue(leaf.value) && step !== "base") errors.push(`${joined}: T2 token must carry a concrete color value`);
+		if (seed && step && T1_SET.has(seed) && stepKind) {
+			t2BySeed.get(seed).add(step);
+			validateT2Provenance(leaf, seed, step, errors);
+		}
+	}
+	for (const seed of T1_COLOR_KEYS) {
+		const steps = t2BySeed.get(seed);
+		const missingAlpha = T2_ALPHA_KEYS.filter((step) => !steps.has(step));
+		const missingOklch = T2_OKLCH_STEP_KEYS.filter((step) => !steps.has(step));
+		const unexpected = [...steps].filter((step) => !classifyT2Step(step));
+		if (!steps.has("base")) errors.push(`qw.t2.${seed}: missing base token`);
+		if (missingAlpha.length) errors.push(`qw.t2.${seed}: missing alpha steps ${missingAlpha.join(", ")}`);
+		if (missingOklch.length) errors.push(`qw.t2.${seed}: missing OKLCH steps ${missingOklch.join(", ")}`);
+		if (unexpected.length) errors.push(`qw.t2.${seed}: unexpected steps ${unexpected.join(", ")}`);
+	}
+	const expectedT3 = new Set(figmaT3RolePaths());
+	const actualT3 = /* @__PURE__ */ new Set();
+	for (const leaf of t3) {
+		const joined = pathKey(leaf.qwPath);
+		actualT3.add(joined);
+		validateT3Path(leaf.qwPath, errors);
+		if (!expectedT3.has(joined)) errors.push(`${joined}: unexpected T3 role (not in the 60-role Figma set)`);
+		const modes = modesOf(leaf);
+		const light = refToPath(modes.light);
+		const dark = refToPath(modes.dark);
+		if (!light || !dark) {
+			errors.push(`${joined}: T3 token must declare both light and dark mode references`);
+			continue;
+		}
+		for (const [modeName, ref] of [["light", light], ["dark", dark]]) if (ref[0] !== "qw" || ref[1] !== "t2") errors.push(`${joined}: ${modeName} mode must reference a T2 token`);
+		else if (!byQwPath.has(pathKey(ref))) errors.push(`${joined}: ${modeName} mode references missing token {${pathKey(ref)}}`);
+	}
+	const missingT3 = [...expectedT3].filter((role) => !actualT3.has(role));
+	if (missingT3.length) errors.push(`qw.t3: missing required roles ${missingT3.join(", ")}`);
+	return {
+		ok: errors.length === 0,
+		errors,
+		counts: {
+			t1: t1.length,
+			t2: t2.length,
+			t3: t3.length
+		}
+	};
+}
+function assertFigmaColorTokens(doc) {
+	const result = validateFigmaColorTokens(doc);
+	if (!result.ok) throw new Error(`Invalid Figma Color tokens:\n${result.errors.map((error) => `- ${error}`).join("\n")}`);
+}
+//#endregion
 //#region src/compat/schema.ts
 /** DTCG 兼容的颜色字面量：hex、hex/NN% 透明度后缀，或结构化 srgb。 */
 const legacyHexColor = z.string().regex(/^#[0-9A-Fa-f]{6}(\/\d{1,3}%)?$/, "期望 #RRGGBB 或 #RRGGBB/NN%");
@@ -2227,6 +2836,6 @@ function formatCompatTypes(build) {
 	return lines.join("\n");
 }
 //#endregion
-export { COLOR_ROLES, FIGMA_COLOR_COLLECTION, FIGMA_COLOR_PREFIX, FIGMA_T1_SEED_HEX, FIGMA_T2_SOLID_SCALE, FIGMA_T3_COLOR_ROLES, L_TARGETS, RAMP_COLORS, SHADOW_COMPOSITE_ROLES, STEPS, SeedSchema, T1_COLOR_KEYS, T2_ALPHA_KEYS, T2_ALPHA_STEPS, T2_OKLCH_STEPS, TYPOGRAPHY_ROLES, allReferenceRecipes, buildCompatFromRegistry, buildLiveCss, buildReference, buildSemanticColor, buildSemanticStructural, compatPathToCssVar, compatRegistrySchema, contrastRatio, defaultSeed, derivationToCssExpr, derive, evaluateDerivation, formatCompatTypes, formatDerivation, hexToSeedColor, ramp, seedColorToCss, seedColorToHex, seedCssVars, seedRefsOf, seedValueAt, semanticRoleEntries, toVar, validateSeed };
+export { COLOR_ROLES, FIGMA_COLOR_COLLECTION, FIGMA_COLOR_PREFIX, FIGMA_T1_SEED_HEX, FIGMA_T2_SOLID_SCALE, FIGMA_T2_STEP_ALPHA, FIGMA_T3_COLOR_ROLES, L_TARGETS, RAMP_COLORS, SHADOW_COMPOSITE_ROLES, STEPS, SeedSchema, T1_COLOR_KEYS, T2_ALPHA_KEYS, T2_ALPHA_STEPS, T2_OKLCH_STEPS, T2_PURE_SEEDS, T2_PURE_STEP, TYPOGRAPHY_ROLES, allReferenceRecipes, assertFigmaColorTokens, buildCompatFromRegistry, buildFigmaColorSnapshot, buildLiveCss, buildReference, buildSemanticColor, buildSemanticStructural, compatPathToCssVar, compatRegistrySchema, contrastRatio, defaultSeed, derivationToCssExpr, derive, evaluateDerivation, figmaT3RolePaths, formatCompatTypes, formatDerivation, hexToSeedColor, ramp, seedColorToCss, seedColorToHex, seedCssVars, seedRefsOf, seedValueAt, semanticRoleEntries, sourceKindOf, toVar, validateFigmaColorTokens, validateSeed };
 
 //# sourceMappingURL=index.js.map