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

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 = [];
@@ -1277,13 +1510,14 @@ function buildSpacingRecipes() {
 	}));
 	return out;
 }
-/** 圆角档位系数（sm/lg 从 base 派生；默认 base=8px → 4/8/14）。 */
+/** 圆角档位系数（sm/lg/xl 从 base 派生；默认 base=8px → 4/8/14/16）。 */
 const RADIUS_FACTORS = {
 	sm: .5,
 	md: 1,
-	lg: 1.75
+	lg: 1.75,
+	xl: 2
 };
-/** 5. 圆角刻度：sm/md/lg 由 radius.base 按系数派生，full 直通独立裁切基准。 */
+/** 5. 圆角刻度：sm/md/lg/xl 由 radius.base 按系数派生，full 直通独立裁切基准。xl=2×base 对齐治理稿 Radius v2 的 T2 double。 */
 function buildRadiusRecipes() {
 	return [
 		ref([
@@ -1312,6 +1546,15 @@ function buildRadiusRecipes() {
 			seedRef: "size.radius.base",
 			factor: RADIUS_FACTORS.lg
 		}),
+		ref([
+			"size",
+			"radius",
+			"xl"
+		], {
+			kind: "scale",
+			seedRef: "size.radius.base",
+			factor: RADIUS_FACTORS.xl
+		}),
 		ref([
 			"size",
 			"radius",
@@ -1384,16 +1627,108 @@ function buildControlIconSizeRecipes() {
 		})
 	];
 }
-/** 7. 描边宽度 —— 直通引用。 */
-function buildBorderWidthRecipes() {
-	return [ref([
+/** 描边宽度梯度系数（Figma Stroke v1：Half/Base/Double/Triple = 0.5/1/2/3）。 */
+const STROKE_WIDTH_FACTORS = {
+	half: .5,
+	double: 2,
+	triple: 3
+};
+/** 7. 描边宽度（Figma Stroke v1）：base 直通 Seed，half/double/triple 按系数派生。 */
+function buildStrokeWidthRecipes() {
+	const seedRef = "size.borderWidth.hairline";
+	return [
+		ref([
+			"size",
+			"strokeWidth",
+			"half"
+		], {
+			kind: "scale",
+			seedRef,
+			factor: STROKE_WIDTH_FACTORS.half
+		}),
+		ref([
+			"size",
+			"strokeWidth",
+			"base"
+		], {
+			kind: "alias",
+			seedRef
+		}),
+		ref([
+			"size",
+			"strokeWidth",
+			"double"
+		], {
+			kind: "scale",
+			seedRef,
+			factor: STROKE_WIDTH_FACTORS.double
+		}),
+		ref([
+			"size",
+			"strokeWidth",
+			"triple"
+		], {
+			kind: "scale",
+			seedRef,
+			factor: STROKE_WIDTH_FACTORS.triple
+		})
+	];
+}
+/** 六档动作控件高度（Figma Action Control v1）：现有公开尺寸契约，不能由单一 T1 Base 可靠派生，直接定义在 T2（T1 不设 Control Size）。 */
+const ACTION_CONTROL_HEIGHTS = {
+	"2xs": 24,
+	xs: 28,
+	sm: 32,
+	md: 36,
+	lg: 42,
+	xl: 50
+};
+/** 7b. 动作控件尺寸：六档高度 + 2XS 图标特例（Square 复用同档 Height，不另设 token）。 */
+function buildActionControlRecipes() {
+	const out = [];
+	for (const [step, value] of Object.entries(ACTION_CONTROL_HEIGHTS)) out.push(ref([
 		"size",
-		"borderWidth",
-		"hairline"
+		"actionControlHeight",
+		step
 	], {
-		kind: "alias",
-		seedRef: "size.borderWidth.hairline"
-	})];
+		kind: "literal",
+		value: `${value}px`
+	}, {
+		source: "Figma 千问三方——Token 改造 · Foundation/Action Control Standard v1",
+		rationale: "六档高度 24/28/32/36/42/50 是现有公开尺寸契约，治理稿将其直接定义在 T2，T1 不设置 Control Size。"
+	}));
+	out.push(ref([
+		"size",
+		"actionControlIcon",
+		"2xs"
+	], {
+		kind: "literal",
+		value: "14px"
+	}, {
+		source: "Figma 千问三方——Token 改造 · Foundation/Action Control Standard v1",
+		rationale: "2XS 图标 14px 是治理稿已标记的组件特例（不扩充全局 Icon Scale）；视觉验证通过后优先归一化为 Icon Size/Small。"
+	}));
+	return out;
+}
+/** Avatar 三档直径（Figma 头像 · Avatar S/M/L = 40/50/58）。 */
+const AVATAR_DIAMETERS = {
+	sm: 40,
+	md: 50,
+	lg: 58
+};
+/** 7c. 展示类专用尺寸：Avatar 直径（Icon Size 规范要求 Avatar 直径使用自己的语义，禁止借用 Icon/Control 刻度）。 */
+function buildAvatarDiameterRecipes() {
+	return Object.entries(AVATAR_DIAMETERS).map(([step, value]) => ref([
+		"size",
+		"avatarDiameter",
+		step
+	], {
+		kind: "literal",
+		value: `${value}px`
+	}, {
+		source: "Figma 千问三方——Token 改造 · 头像 · Avatar（S/M/L）",
+		rationale: "Avatar 直径 40/50/58 是展示类专用尺寸契约；Icon Size 规范明确 Avatar 直径必须使用各自语义，不由 T1 派生。"
+	}));
 }
 /** 8. 行高（typography 类目）：normal 直通 Seed，tight/relaxed = base ∓ 0.25。 */
 function buildLineHeightRecipes() {
@@ -1465,14 +1800,15 @@ const FONT_FAMILY_KEYS = [
 	"textWindowsZh",
 	"textWindowsJa"
 ];
-/** 字号档位倍数（沿用既定视觉：14px 基准 → 12/16/20/24）。 */
+/** 字号档位倍数（沿用既定视觉：14px 基准 → 11/12/16/20/24；xs=11 对齐治理稿 T2 Font Size 2XS）。 */
 const FONT_SIZE_FACTORS = {
+	xs: .786,
 	sm: .857,
 	lg: 1.143,
 	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 +1819,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,10 +1927,13 @@ function buildShadowRecipes() {
 function allReferenceRecipes() {
 	return [
 		...buildColorRampRecipes(),
+		...buildColorExtraRecipes(),
 		...buildSpacingRecipes(),
 		...buildRadiusRecipes(),
 		...buildControlIconSizeRecipes(),
-		...buildBorderWidthRecipes(),
+		...buildStrokeWidthRecipes(),
+		...buildActionControlRecipes(),
+		...buildAvatarDiameterRecipes(),
 		...buildLineHeightRecipes(),
 		...buildOpacityRecipes(),
 		...buildZIndexRecipes(),
@@ -1626,8 +1968,10 @@ function semVar(path) {
 	return toVar("sem", path);
 }
 const RADIUS_ROLES = {
+	sm: "size.radius.sm",
 	control: "size.radius.md",
 	card: "size.radius.lg",
+	xl: "size.radius.xl",
 	pill: "size.radius.full",
 	full: "size.radius.full"
 };
@@ -1641,6 +1985,57 @@ const ICON_SIZE_ROLES = {
 	md: "size.iconSize.md",
 	lg: "size.iconSize.lg"
 };
+const ACTION_CONTROL_HEIGHT_ROLES = {
+	"2xs": "size.actionControlHeight.2xs",
+	xs: "size.actionControlHeight.xs",
+	sm: "size.actionControlHeight.sm",
+	md: "size.actionControlHeight.md",
+	lg: "size.actionControlHeight.lg",
+	xl: "size.actionControlHeight.xl"
+};
+const ACTION_CONTROL_PADDING_INLINE_ROLES = {
+	"2xs": "size.spacing.2",
+	xs: "size.spacing.2",
+	sm: "size.spacing.4",
+	md: "size.spacing.4",
+	lg: "size.spacing.5",
+	xl: "size.spacing.8"
+};
+const ACTION_CONTROL_ICON_ROLES = {
+	"2xs": "size.actionControlIcon.2xs",
+	xs: "size.iconSize.sm",
+	sm: "size.iconSize.sm",
+	md: "size.iconSize.sm",
+	lg: "size.iconSize.sm",
+	xl: "size.iconSize.md"
+};
+const ACTION_CONTROL_GAP_ROLES = {
+	"2xs": "size.spacing.1",
+	xs: "size.spacing.1",
+	sm: "size.spacing.2",
+	md: "size.spacing.2",
+	lg: "size.spacing.2",
+	xl: "size.spacing.2"
+};
+const BORDER_WIDTH_ROLES = {
+	default: "size.strokeWidth.base",
+	strong: "size.strokeWidth.double"
+};
+const DIVIDER_WIDTH_ROLES = {
+	thin: "size.strokeWidth.half",
+	default: "size.strokeWidth.base"
+};
+const FOCUS_RING_ROLES = {
+	width: "size.strokeWidth.double",
+	offset: "size.strokeWidth.double"
+};
+const INDICATOR_ROLES = { loading: "size.strokeWidth.double" };
+/** 展示类专用尺寸：Avatar 直径三档（Figma 头像 S/M/L）。 */
+const AVATAR_DIAMETER_ROLES = {
+	sm: "size.avatarDiameter.sm",
+	md: "size.avatarDiameter.md",
+	lg: "size.avatarDiameter.lg"
+};
 const INSET_STACK_ROLES = {
 	sm: "size.spacing.2",
 	md: "size.spacing.4",
@@ -1708,6 +2103,22 @@ const TYPOGRAPHY_ROLES = {
 		lineHeightRef: "typography.lineHeight.normal",
 		letterSpacingRef: T_LETTER
 	},
+	/** 大正文（治理稿 T3 字段「大正文 16px · T2 M」）：行高沿用 canonical 比例引擎。 */
+	bodyLg: {
+		fontFamilyRef: "typography.fontFamily.text",
+		fontSizeRef: "typography.fontSize.lg",
+		fontWeightRef: "typography.fontWeight.regular",
+		lineHeightRef: "typography.lineHeight.normal",
+		letterSpacingRef: T_LETTER
+	},
+	/** 小标签（治理稿 Text/Label/Small = 11/500/16）：字号取 T2 xs=11px。 */
+	labelSm: {
+		fontFamilyRef: "typography.fontFamily.text",
+		fontSizeRef: "typography.fontSize.xs",
+		fontWeightRef: "typography.fontWeight.medium",
+		lineHeightRef: "typography.lineHeight.normal",
+		letterSpacingRef: T_LETTER
+	},
 	code: {
 		fontFamilyRef: "typography.fontFamily.code",
 		fontSizeRef: "typography.fontSize.sm",
@@ -1716,15 +2127,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 的产出一一对应（顺序一致）。
@@ -1752,6 +2170,51 @@ function semanticRoleEntries() {
 		"iconSize",
 		role
 	], refPath);
+	for (const [role, refPath] of Object.entries(ACTION_CONTROL_HEIGHT_ROLES)) structural([
+		"size",
+		"actionControlHeight",
+		role
+	], refPath);
+	for (const [role, refPath] of Object.entries(ACTION_CONTROL_PADDING_INLINE_ROLES)) structural([
+		"size",
+		"actionControlPaddingInline",
+		role
+	], refPath);
+	for (const [role, refPath] of Object.entries(ACTION_CONTROL_ICON_ROLES)) structural([
+		"size",
+		"actionControlIcon",
+		role
+	], refPath);
+	for (const [role, refPath] of Object.entries(ACTION_CONTROL_GAP_ROLES)) structural([
+		"size",
+		"actionControlGap",
+		role
+	], refPath);
+	for (const [role, refPath] of Object.entries(BORDER_WIDTH_ROLES)) structural([
+		"size",
+		"borderWidth",
+		role
+	], refPath);
+	for (const [role, refPath] of Object.entries(DIVIDER_WIDTH_ROLES)) structural([
+		"size",
+		"dividerWidth",
+		role
+	], refPath);
+	for (const [role, refPath] of Object.entries(FOCUS_RING_ROLES)) structural([
+		"size",
+		"focusRing",
+		role
+	], refPath);
+	for (const [role, refPath] of Object.entries(INDICATOR_ROLES)) structural([
+		"size",
+		"indicator",
+		role
+	], refPath);
+	for (const [role, refPath] of Object.entries(AVATAR_DIAMETER_ROLES)) structural([
+		"size",
+		"avatarDiameter",
+		role
+	], refPath);
 	for (const [role, refPath] of Object.entries(INSET_STACK_ROLES)) {
 		structural([
 			"size",
@@ -1817,7 +2280,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 +2299,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 +2327,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 +2368,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 +2378,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 +2396,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 +2433,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,212 +2483,372 @@ function buildLiveCss(seed, options = {}) {
 	].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%");
-const structuredColor = z.object({
-	colorSpace: z.literal("srgb"),
-	components: z.tuple([
-		z.number(),
-		z.number(),
-		z.number()
-	]),
-	alpha: z.number().min(0).max(1)
-});
-const dimensionValue = z.object({
-	value: z.number(),
-	unit: z.enum([
-		"px",
-		"rem",
-		"em",
-		"%"
-	])
-});
-const modePair = z.object({
-	light: z.union([
-		legacyHexColor,
-		structuredColor,
-		z.string()
-	]),
-	dark: z.union([
-		legacyHexColor,
-		structuredColor,
-		z.string()
-	])
-});
-const compatStatusSchema = z.enum([
-	"active",
-	"aliased",
-	"deprecated"
-]);
-const compatEntrySchema = z.object({
-	path: z.string().regex(/^[a-z][a-z0-9-]*\.[a-z][a-z0-9.-]*$/, "path 格式：<component>.<category>.<name>，如 button.color.bg-soft-brand"),
-	type: z.enum([
-		"color",
-		"dimension",
-		"typography",
-		"motion"
-	]),
-	value: z.union([
-		modePair,
-		dimensionValue,
-		z.object({ aliasOf: z.string().min(1) })
-	]),
-	source: z.object({
-		figma: z.string().url(),
-		nodeId: z.string().min(1),
-		legacyName: z.string().nullable()
-	}),
-	introducedBy: z.string().min(1),
-	reason: z.string().min(1),
-	owner: z.string().min(1),
-	targetSemanticRole: z.string().nullable(),
-	status: compatStatusSchema,
-	reviewAfter: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
-	migrationIssue: z.string().nullable()
-}).superRefine((entry, ctx) => {
-	if (entry.status === "aliased") {
-		if (!("aliasOf" in entry.value)) ctx.addIssue({
-			code: "custom",
-			message: "status=aliased 时 value 必须为 { aliasOf }",
-			path: ["value"]
+//#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}`
 		});
-		if (!entry.targetSemanticRole) ctx.addIssue({
-			code: "custom",
-			message: "status=aliased 时 targetSemanticRole 必填",
-			path: ["targetSemanticRole"]
+		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;
 	}
-	if (entry.status === "active" && "aliasOf" in entry.value) ctx.addIssue({
-		code: "custom",
-		message: "status=active 时不得使用 aliasOf",
-		path: ["value"]
-	});
-});
-const compatRegistrySchema = z.object({
-	$description: z.string().optional(),
-	version: z.literal(1),
-	graceDays: z.number().int().positive().default(90),
-	entries: z.array(compatEntrySchema).min(1)
-});
-/** path → CSS 变量名：`button.color.bg-soft-brand` → `--qw-compat-button-color-bg-soft-brand` */
-function compatPathToCssVar(path) {
-	return `--qw-compat-${path.replace(/\./g, "-")}`;
+	return t2;
 }
-/** path → component slug（第一段） */
-function compatComponentOf(path) {
-	return path.split(".")[0];
+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;
 }
-/** path → helper suffix（component 之后的段，用 `-` 连接） */
-function compatSuffixOf(path) {
-	return path.split(".").slice(1).join("-");
+/** 生成 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/compat/color.ts
-/**
-* 将 legacy hex（含 /NN% 透明度后缀）或 DTCG srgb 结构转为 CSS 颜色字符串。
-*/
-function compatColorToCss(input) {
-	if (typeof input === "string") {
-		const m = /^#([0-9A-Fa-f]{6})(?:\/(\d{1,3})%)?$/.exec(input);
-		if (!m) throw new Error(`[qw-compat] 无法解析颜色: ${input}`);
-		const n = Number.parseInt(m[1], 16);
-		const r = n >> 16 & 255;
-		const g = n >> 8 & 255;
-		const b = n & 255;
-		const alpha = m[2] != null ? Number(m[2]) / 100 : 1;
-		if (alpha >= 1) return `#${m[1].toUpperCase()}`;
-		return `rgba(${r}, ${g}, ${b}, ${roundAlpha(alpha)})`;
+//#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;
 	}
-	const [r, g, b] = input.components.map((c) => Math.round(c * 255));
-	const alpha = input.alpha;
-	if (alpha >= 1) return `#${[
-		r,
-		g,
-		b
-	].map((x) => x.toString(16).padStart(2, "0")).join("")}`;
-	return `rgba(${r}, ${g}, ${b}, ${roundAlpha(alpha)})`;
-}
-function roundAlpha(a) {
-	return Math.round(a * 1e3) / 1e3;
+	for (const [key, child] of Object.entries(node)) {
+		if (key.startsWith("$")) continue;
+		collectLeaves(child, [...path, key], out);
+	}
+	return out;
 }
-//#endregion
-//#region src/compat/build.ts
-function dimensionToCss(value) {
-	return `${value.value}${value.unit}`;
-}
-function resolveEntryValue(entry, mode, semCssVar) {
-	const v = entry.value;
-	if ("aliasOf" in v) return `var(${semCssVar(v.aliasOf)})`;
-	if ("light" in v && "dark" in v) {
-		const raw = v[mode];
-		if (entry.type === "color") return compatColorToCss(raw);
-		return String(raw);
+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;
 	}
-	if ("value" in v && "unit" in v) return dimensionToCss(v);
-	throw new Error(`[qw-compat] 条目 ${entry.path} 的 value 形状无法解析`);
-}
-/** semantic role 点分路径 → --qw-sem-* CSS 变量 */
-function semRoleToCssVar(role) {
-	const parts = role.split(".");
-	return `--qw-sem-${parts[0]}-${parts.slice(1).join("-")}`;
-}
-function buildCompatFromRegistry(registry) {
-	const light = {};
-	const dark = {};
-	const paths = {};
-	const byComponent = {};
-	for (const entry of registry.entries) {
-		const cssVar = compatPathToCssVar(entry.path);
-		paths[entry.path] = cssVar;
-		const component = compatComponentOf(entry.path);
-		const suffix = compatSuffixOf(entry.path);
-		if (!byComponent[component]) byComponent[component] = [];
-		byComponent[component].push(suffix);
-		const resolve = (mode) => resolveEntryValue(entry, mode, semRoleToCssVar);
-		if ("light" in entry.value && "dark" in entry.value) {
-			light[cssVar] = resolve("light");
-			const darkVal = resolve("dark");
-			if (darkVal !== light[cssVar]) dark[cssVar] = darkVal;
-		} else light[cssVar] = resolve("light");
+	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;
 	}
-	return {
-		light,
-		dark,
-		paths,
-		byComponent,
-		entries: registry.entries,
-		graceDays: registry.graceDays
-	};
+	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`);
 }
-function componentSuffixTypeName(component) {
-	return `Compat${component.split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("")}Suffix`;
-}
-function componentSuffixConstName(component) {
-	return `compat${component.split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("")}Suffixes`;
-}
-/** 生成 compat token-paths TypeScript 片段（并入 tokens.ts） */
-function formatCompatTypes(build) {
-	const components = Object.keys(build.byComponent).sort();
-	const lines = ["export const compatComponents = " + JSON.stringify(components) + " as const;", "export type CompatComponent = (typeof compatComponents)[number];"];
-	for (const c of components) {
-		const suffixes = [...build.byComponent[c]].sort();
-		const constName = componentSuffixConstName(c);
-		const typeName = componentSuffixTypeName(c);
-		lines.push(`export const ${constName} = ${JSON.stringify(suffixes)} as const;`);
-		lines.push(`export type ${typeName} = (typeof ${constName})[number];`);
+/** 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);
 	}
-	if (components.length === 1) {
-		const c = components[0];
-		lines.push(`export type CompatSuffix<C extends CompatComponent> = C extends ${JSON.stringify(c)} ? ${componentSuffixTypeName(c)} : never;`);
-	} else if (components.length > 1) {
-		lines.push("export type CompatSuffix<C extends CompatComponent> =");
-		for (const c of components) lines.push(`  C extends ${JSON.stringify(c)} ? ${componentSuffixTypeName(c)} :`);
-		lines.push("  never;");
+	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);
 	}
-	return lines.join("\n");
+	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
-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, buildFigmaColorSnapshot, buildLiveCss, buildReference, buildSemanticColor, buildSemanticStructural, contrastRatio, defaultSeed, derivationToCssExpr, derive, evaluateDerivation, figmaT3RolePaths, formatDerivation, hexToSeedColor, ramp, seedColorToCss, seedColorToHex, seedCssVars, seedRefsOf, seedValueAt, semanticRoleEntries, sourceKindOf, toVar, validateFigmaColorTokens, validateSeed };
 
 //# sourceMappingURL=index.js.map