@qw-ui/tokens 0.3.0-next.40 → 0.3.0-next.43

package/dist/index.js

@@ -474,6 +474,13 @@ const T2_OKLCH_STEPS = [
 	800,
 	900
 ];
+/** RFC0012 approved local standard endpoint; Figma synchronization is pending. */
+const T2_BLACK_CONTRAST_ENDPOINT = {
+	step: "contrast-endpoint",
+	value: "#000000",
+	source: "CSS Color sRGB black mathematical endpoint; specs/rfcs/0012-brand-solid-text-contrast.md",
+	rationale: "The zero sRGB endpoint is a standard constant for on-brand AA text, independent of Seed and existing color scales."
+};
 const FIGMA_T2_SOLID_SCALE = {
 	brand: {
 		50: "#F2F6FF",
@@ -621,8 +628,9 @@ const FIGMA_T2_SOLID_SCALE = {
 	}
 };
 /**
-* Figma「Color Token System」T3 语义角色表（60 个，light/dark 均引用 T2 路径）。
-* 与 Figma 节点 22258:49986 逐条对齐；`effect.shadow.*.color` 为复合阴影的颜色
+* Figma「Color Token System」既有角色及用户批准的本地补充角色。
+* 既有角色与 Figma 节点 22258:49986 对齐；新角色等待 Figma 同步，不冒充已回流。
+* light/dark 均引用 T2；`effect.shadow.*.color` 为复合阴影的颜色
 * 分量（对应 Figma 变量 `--qw-sem-effect-shadow-*-color`）。
 */
 const FIGMA_T3_COLOR_ROLES = {
@@ -666,6 +674,10 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.gray.50",
 		dark: "color.black.900"
 	},
+	"content.danger": {
+		light: "color.red.600",
+		dark: "color.red.300"
+	},
 	"content.primary": {
 		light: "color.black.base",
 		dark: "color.white.base"
@@ -706,6 +718,10 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.white.base",
 		dark: "color.white.base"
 	},
+	"content.on-brand": {
+		light: "color.white.base",
+		dark: "color.black.contrast-endpoint"
+	},
 	"content.on-warning-subtle": {
 		light: "color.yellow.800",
 		dark: "color.yellow.200"
@@ -718,6 +734,10 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.gray.300",
 		dark: "color.gray.600"
 	},
+	"border.control": {
+		light: "color.gray.600",
+		dark: "color.gray.base"
+	},
 	"border.focus": {
 		light: "color.brand.base",
 		dark: "color.brand.500"
@@ -779,8 +799,8 @@ const FIGMA_T3_COLOR_ROLES = {
 		dark: "color.blue.a20"
 	},
 	"control-action.danger.default": {
-		light: "color.red.400",
-		dark: "color.red.400"
+		light: "color.red.600",
+		dark: "color.red.600"
 	},
 	"control-action.danger.subtle": {
 		light: "color.red.a10",
@@ -850,6 +870,10 @@ const FIGMA_T3_COLOR_ROLES = {
 		light: "color.black.a50",
 		dark: "color.black.a50"
 	},
+	"overlay.control-on-media": {
+		light: "color.black.a50",
+		dark: "color.white.a40"
+	},
 	shadow: {
 		light: "color.black.a10",
 		dark: "color.black.a50"
@@ -1309,6 +1333,7 @@ function evaluateDerivation(d, seed) {
 		case "fontStack": return formatFontFamily(seedValueAt(seed, d.seedRef));
 		case "cubicBezier": return formatCubicBezier(seedValueAt(seed, d.seedRef));
 		case "literal": return String(d.value);
+		case "cssEnvironment": return `env(${d.name}, ${d.fallback})`;
 		case "shadowLayer": {
 			const { offsetX, offsetY, blur, spread } = shadowShapeOf(seed, d.level);
 			return `${offsetX} ${offsetY} ${blur} ${spread} ${rgba([
@@ -1333,7 +1358,8 @@ function seedRefsOf(d) {
 		case "cubicBezier": return [d.seedRef];
 		case "offsetSteps": return [d.seedRef, d.stepRef];
 		case "alphaScale": return [d.stepRef];
-		case "literal": return [];
+		case "literal":
+		case "cssEnvironment": return [];
 		case "shadowLayer": return ["effect.shadow.base", "size.opacity.alphaStep"];
 	}
 }
@@ -1345,6 +1371,7 @@ function sourceKindOf(d) {
 		case "cubicBezier": return "seed-alias";
 		case "figmaOklchScale": return "design-calibrated";
 		case "literal": return "standard-constant";
+		case "cssEnvironment": return "external-standard";
 		default: return "seed-derived";
 	}
 }
@@ -1364,6 +1391,7 @@ function formatDerivation(d) {
 		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}（canonical 标准常量）`;
+		case "cssEnvironment": return `= env(${d.name}, ${d.fallback})（UA external standard）`;
 		case "shadowLayer": {
 			const f = SHADOW_LEVELS[d.level];
 			return `= seed.effect.shadow.base 形状 × {offset ${f.offset}, blur ${f.blur}} · 色 = 黑 / alphaStep × ${f.alphaMult}`;
@@ -1418,11 +1446,32 @@ function buildColorRampRecipes() {
 			seedRef
 		}));
 	}
+	out.push(ref([
+		"color",
+		"black",
+		T2_BLACK_CONTRAST_ENDPOINT.step
+	], {
+		kind: "literal",
+		value: T2_BLACK_CONTRAST_ENDPOINT.value
+	}, {
+		source: T2_BLACK_CONTRAST_ENDPOINT.source,
+		rationale: T2_BLACK_CONTRAST_ENDPOINT.rationale
+	}));
 	return out;
 }
 /** 4. 间距刻度 = spacing.step × N (N=1..8)。 */
 function buildSpacingRecipes() {
-	const out = [];
+	const out = [ref([
+		"size",
+		"spacing",
+		"0"
+	], {
+		kind: "literal",
+		value: "0px"
+	}, {
+		source: "CSS Values zero length",
+		rationale: "A canonical zero needs no theme Seed dependency."
+	})];
 	for (let n = 1; n <= 8; n++) out.push(ref([
 		"size",
 		"spacing",
@@ -1434,6 +1483,25 @@ function buildSpacingRecipes() {
 	}));
 	return out;
 }
+function buildSafeAreaInsetRecipes() {
+	return [
+		"top",
+		"right",
+		"bottom",
+		"left"
+	].map((edge) => ref([
+		"size",
+		"safeAreaInset",
+		edge
+	], {
+		kind: "cssEnvironment",
+		name: `safe-area-inset-${edge}`,
+		fallback: "0px"
+	}, {
+		source: "https://www.w3.org/TR/css-env-1/#safe-area-insets",
+		rationale: "Dynamic UA-owned viewport inset; a CSS expression, not a fixed device dimension or Seed input."
+	}));
+}
 /** 圆角档位系数（sm/lg/xl 从 base 派生；默认 base=8px → 4/8/14/16）。 */
 const RADIUS_FACTORS = {
 	sm: .5,
@@ -1489,6 +1557,48 @@ function buildRadiusRecipes() {
 		})
 	];
 }
+/** Existing public placeholder geometry: font-relative text and calibrated media. */
+function buildPlaceholderSizeRecipes() {
+	return [ref([
+		"size",
+		"placeholderTextHeight",
+		"base"
+	], {
+		kind: "literal",
+		value: "1em"
+	}, {
+		source: "CSS Values font-relative em unit; qw-ui Skeleton public text default",
+		rationale: "Text placeholder follows inherited font size without adding a theme seed."
+	}), ref([
+		"size",
+		"placeholderMediaHeight",
+		"base"
+	], {
+		kind: "literal",
+		value: "120px"
+	}, {
+		source: "qw-ui Skeleton existing public media placeholder geometry; specs/036-native-display",
+		rationale: "Preserves the existing calibrated media default independently of control/avatar scales."
+	})];
+}
+/** Loading logo boxes follow the independent existing public size contract. */
+function buildLoadingSizeRecipes() {
+	return Object.entries({
+		sm: 32,
+		md: 48,
+		lg: 60
+	}).map(([size, value]) => ref([
+		"size",
+		"loadingLogoSize",
+		size
+	], {
+		kind: "literal",
+		value: `${value}px`
+	}, {
+		source: "qw-ui Loading public logo-size contract; specs/037-native-loading",
+		rationale: "Independent calibrated logo boxes must not change with unrelated control or icon size seeds."
+	}));
+}
 /** 6. 控件/图标尺寸：md = base 直通，sm/lg = base ∓ spacing.step × n（控件 ×2、图标 ×1）。 */
 function buildControlIconSizeRecipes() {
 	const step = "size.spacing.step";
@@ -1674,6 +1784,18 @@ function buildLineHeightRecipes() {
 			kind: "alias",
 			seedRef: "typography.lineHeight.base"
 		}),
+		ref([
+			"typography",
+			"lineHeight",
+			"comfortable"
+		], {
+			kind: "literal",
+			value: 1.625
+		}, {
+			sourceKind: "design-calibrated",
+			source: "Figma RihMzcoamEChrLxQa0xjmH / I22378:53258;17214:12764 / frozen scene-22378-53247-reference.tsx",
+			rationale: "Exact 26px / 16px title ratio; independent of lineHeight Seed anchor."
+		}),
 		ref([
 			"typography",
 			"lineHeight",
@@ -1820,6 +1942,37 @@ function buildMotionRecipes() {
 			seedRef: "motion.duration.base",
 			factor: DURATION_FACTORS.slow
 		}),
+		ref([
+			"motion",
+			"duration",
+			"shimmer"
+		], {
+			kind: "scale",
+			seedRef: "motion.duration.base",
+			factor: 10
+		}),
+		ref([
+			"motion",
+			"easing",
+			"linear"
+		], {
+			kind: "literal",
+			value: "linear"
+		}, {
+			source: "CSS Easing Functions: linear identity function",
+			rationale: "Uniform decorative spin without an entrance or symmetric pulse curve."
+		}),
+		ref([
+			"motion",
+			"easing",
+			"symmetric"
+		], {
+			kind: "literal",
+			value: "ease-in-out"
+		}, {
+			source: "CSS Easing Functions: ease-in-out equals cubic-bezier(0.42, 0, 0.58, 1)",
+			rationale: "Symmetric repeating shimmer preserves the existing easing; distinct from entrance easing."
+		}),
 		ref([
 			"motion",
 			"easing",
@@ -1852,6 +2005,9 @@ function allReferenceRecipes() {
 	return [
 		...buildColorRampRecipes(),
 		...buildSpacingRecipes(),
+		...buildSafeAreaInsetRecipes(),
+		...buildPlaceholderSizeRecipes(),
+		...buildLoadingSizeRecipes(),
 		...buildRadiusRecipes(),
 		...buildControlIconSizeRecipes(),
 		...buildStrokeWidthRecipes(),
@@ -1862,6 +2018,15 @@ function allReferenceRecipes() {
 		...buildZIndexRecipes(),
 		...buildTypographyRecipes(),
 		...buildMotionRecipes(),
+		ref([
+			"effect",
+			"blur",
+			"sm"
+		], {
+			kind: "scale",
+			seedRef: "size.spacing.step",
+			factor: .5
+		}),
 		...buildShadowRecipes()
 	];
 }
@@ -1890,40 +2055,44 @@ function pick(tokens, dottedRefPath) {
 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"
-};
-const CONTROL_HEIGHT_ROLES = {
-	sm: "size.controlSize.sm",
-	md: "size.controlSize.md",
-	lg: "size.controlSize.lg"
-};
-const ICON_SIZE_ROLES = {
-	sm: "size.iconSize.sm",
-	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"
-};
+/** Create independent ordinary role tables; prefix compression preserves each literal reference. */
+function referenceRoles(prefix, values) {
+	return Object.fromEntries(Object.entries(values).map(([role, value]) => [role, `${prefix}.${value}`]));
+}
+const RADIUS_ROLES = /* @__PURE__ */ referenceRoles("size.radius", {
+	sm: "sm",
+	control: "md",
+	card: "lg",
+	xl: "xl",
+	pill: "full",
+	full: "full"
+});
+const CONTROL_HEIGHT_ROLES = /* @__PURE__ */ referenceRoles("size.controlSize", {
+	sm: "sm",
+	md: "md",
+	lg: "lg"
+});
+const ICON_SIZE_ROLES = /* @__PURE__ */ referenceRoles("size.iconSize", {
+	sm: "sm",
+	md: "md",
+	lg: "lg"
+});
+const ACTION_CONTROL_HEIGHT_ROLES = /* @__PURE__ */ referenceRoles("size.actionControlHeight", {
+	"2xs": "2xs",
+	xs: "xs",
+	sm: "sm",
+	md: "md",
+	lg: "lg",
+	xl: "xl"
+});
+const ACTION_CONTROL_PADDING_INLINE_ROLES = /* @__PURE__ */ referenceRoles("size.spacing", {
+	"2xs": "2",
+	xs: "2",
+	sm: "4",
+	md: "4",
+	lg: "5",
+	xl: "8"
+});
 const ACTION_CONTROL_ICON_ROLES = {
 	"2xs": "size.actionControlIcon.2xs",
 	xs: "size.iconSize.sm",
@@ -1932,124 +2101,123 @@ const ACTION_CONTROL_ICON_ROLES = {
 	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" };
+const ACTION_CONTROL_GAP_ROLES = /* @__PURE__ */ referenceRoles("size.spacing", {
+	"2xs": "1",
+	xs: "1",
+	sm: "2",
+	md: "2",
+	lg: "2",
+	xl: "2"
+});
+const BORDER_WIDTH_ROLES = /* @__PURE__ */ referenceRoles("size.strokeWidth", {
+	default: "base",
+	strong: "double"
+});
+const DIVIDER_WIDTH_ROLES = /* @__PURE__ */ referenceRoles("size.strokeWidth", {
+	thin: "half",
+	default: "base"
+});
+const FOCUS_RING_ROLES = /* @__PURE__ */ referenceRoles("size.strokeWidth", {
+	width: "double",
+	offset: "double"
+});
+const INDICATOR_ROLES = /* @__PURE__ */ referenceRoles("size.strokeWidth", { loading: "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",
-	lg: "size.spacing.6"
-};
-const Z_INDEX_ROLES = {
-	dropdown: "size.zIndex.1",
-	sticky: "size.zIndex.2",
-	overlay: "size.zIndex.3",
-	toast: "size.zIndex.4"
-};
-const MOTION_DURATION_ROLES = {
-	fast: "motion.duration.fast",
-	base: "motion.duration.base",
-	slow: "motion.duration.slow"
+const AVATAR_DIAMETER_ROLES = /* @__PURE__ */ referenceRoles("size.avatarDiameter", {
+	sm: "sm",
+	md: "md",
+	lg: "lg"
+});
+/** Independent placeholder roles reference T2 directly, never other T3 roles. */
+const SKELETON_SIZE_ROLES = {
+	textHeight: "size.placeholderTextHeight.base",
+	rectHeight: "size.placeholderMediaHeight.base",
+	circleDiameter: "size.avatarDiameter.sm"
 };
+const MOTION_EASING_ROLES = /* @__PURE__ */ referenceRoles("motion.easing", {
+	standard: "standard",
+	symmetric: "symmetric",
+	linear: "linear"
+});
+const LOADING_SIZE_ROLES = /* @__PURE__ */ referenceRoles("size.loadingLogoSize", {
+	sm: "sm",
+	md: "md",
+	lg: "lg"
+});
+const LAYOUT_GAP_ROLES = /* @__PURE__ */ referenceRoles("size.spacing", {
+	sm: "2",
+	md: "4",
+	lg: "6"
+});
+const SAFE_AREA_INSET_ROLES = /* @__PURE__ */ referenceRoles("size.safeAreaInset", {
+	top: "top",
+	right: "right",
+	bottom: "bottom",
+	left: "left"
+});
+const SAFE_AREA_MINIMUM_ROLES = /* @__PURE__ */ referenceRoles("size.spacing", {
+	none: "0",
+	sm: "2",
+	md: "4",
+	lg: "6"
+});
+const INSET_STACK_ROLES = /* @__PURE__ */ referenceRoles("size.spacing", {
+	sm: "2",
+	md: "4",
+	lg: "6"
+});
+const Z_INDEX_ROLES = /* @__PURE__ */ referenceRoles("size.zIndex", {
+	dropdown: "1",
+	sticky: "2",
+	overlay: "3",
+	toast: "4"
+});
+const MOTION_DURATION_ROLES = /* @__PURE__ */ referenceRoles("motion.duration", {
+	fast: "fast",
+	base: "base",
+	slow: "slow",
+	shimmer: "shimmer",
+	spin: "shimmer"
+});
 /** 字体族角色：text（正文缺省）/ number（数字数据）/ code（等宽）。 */
-const FONT_FAMILY_ROLES = {
-	text: "typography.fontFamily.text",
-	number: "typography.fontFamily.number",
-	code: "typography.fontFamily.code"
-};
+const FONT_FAMILY_ROLES = /* @__PURE__ */ referenceRoles("typography.fontFamily", {
+	text: "text",
+	number: "number",
+	code: "code"
+});
 const T_LETTER = "typography.letterSpacing.base";
+/** Fresh records retain independent mutable role values and original property order. */
+function typographyRole(size, weight = "regular", lineHeight = "normal", family = "text") {
+	return {
+		fontFamilyRef: `typography.fontFamily.${family}`,
+		fontSizeRef: `typography.fontSize.${size}`,
+		fontWeightRef: `typography.fontWeight.${weight}`,
+		lineHeightRef: `typography.lineHeight.${lineHeight}`,
+		letterSpacingRef: T_LETTER
+	};
+}
 /** typography.* 复合角色：每个字段各自引用 Reference（无任何裸字面量）。 */
 const TYPOGRAPHY_ROLES = {
-	body: {
-		fontFamilyRef: "typography.fontFamily.text",
-		fontSizeRef: "typography.fontSize.base",
-		fontWeightRef: "typography.fontWeight.regular",
-		lineHeightRef: "typography.lineHeight.normal",
-		letterSpacingRef: T_LETTER
-	},
-	bodyStrong: {
-		fontFamilyRef: "typography.fontFamily.text",
-		fontSizeRef: "typography.fontSize.base",
-		fontWeightRef: "typography.fontWeight.medium",
-		lineHeightRef: "typography.lineHeight.normal",
-		letterSpacingRef: T_LETTER
-	},
-	headingSm: {
-		fontFamilyRef: "typography.fontFamily.text",
-		fontSizeRef: "typography.fontSize.lg",
-		fontWeightRef: "typography.fontWeight.semibold",
-		lineHeightRef: "typography.lineHeight.tight",
-		letterSpacingRef: T_LETTER
-	},
-	headingMd: {
-		fontFamilyRef: "typography.fontFamily.text",
-		fontSizeRef: "typography.fontSize.xl",
-		fontWeightRef: "typography.fontWeight.semibold",
-		lineHeightRef: "typography.lineHeight.tight",
-		letterSpacingRef: T_LETTER
-	},
-	headingLg: {
-		fontFamilyRef: "typography.fontFamily.text",
-		fontSizeRef: "typography.fontSize.2xl",
-		fontWeightRef: "typography.fontWeight.semibold",
-		lineHeightRef: "typography.lineHeight.tight",
-		letterSpacingRef: T_LETTER
-	},
-	caption: {
-		fontFamilyRef: "typography.fontFamily.text",
-		fontSizeRef: "typography.fontSize.sm",
-		fontWeightRef: "typography.fontWeight.regular",
-		lineHeightRef: "typography.lineHeight.normal",
-		letterSpacingRef: T_LETTER
-	},
+	body: /* @__PURE__ */ typographyRole("base"),
+	bodyStrong: /* @__PURE__ */ typographyRole("base", "medium"),
+	productTitle: /* @__PURE__ */ typographyRole("lg", "semibold", "comfortable"),
+	headingSm: /* @__PURE__ */ typographyRole("lg", "semibold", "tight"),
+	headingMd: /* @__PURE__ */ typographyRole("xl", "semibold", "tight"),
+	headingLg: /* @__PURE__ */ typographyRole("2xl", "semibold", "tight"),
+	caption: /* @__PURE__ */ typographyRole("sm"),
 	/** 大正文（治理稿 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
-	},
+	bodyLg: /* @__PURE__ */ typographyRole("lg"),
 	/** 小标签（治理稿 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",
-		fontWeightRef: "typography.fontWeight.regular",
-		lineHeightRef: "typography.lineHeight.normal",
-		letterSpacingRef: T_LETTER
-	}
+	labelSm: /* @__PURE__ */ typographyRole("xs", "medium"),
+	code: /* @__PURE__ */ typographyRole("sm", "regular", "normal", "code")
 };
+const typographyProjectionFields = [...[
+	"fontFamily",
+	"fontSize",
+	"fontWeight",
+	"lineHeight",
+	"letterSpacing"
+]];
 /**
 * 颜色角色的 Semantic 变量路径：绝大多数角色落在 `--qw-sem-color-*` 下；
 * `effect.shadow.*.color` 是复合阴影的颜色分量，对应 Figma 变量
@@ -2066,6 +2234,26 @@ const SHADOW_COMPOSITE_ROLES = {
 	floating: "md",
 	dialog: "lg"
 };
+/** Keep source table references live; preserve projection order without repeated loops. */
+const SIZE_ROLE_GROUPS = [
+	["radius", RADIUS_ROLES],
+	["controlHeight", CONTROL_HEIGHT_ROLES],
+	["iconSize", ICON_SIZE_ROLES],
+	["actionControlHeight", ACTION_CONTROL_HEIGHT_ROLES],
+	["actionControlPaddingInline", ACTION_CONTROL_PADDING_INLINE_ROLES],
+	["actionControlIcon", ACTION_CONTROL_ICON_ROLES],
+	["actionControlGap", ACTION_CONTROL_GAP_ROLES],
+	["borderWidth", BORDER_WIDTH_ROLES],
+	["dividerWidth", DIVIDER_WIDTH_ROLES],
+	["focusRing", FOCUS_RING_ROLES],
+	["indicator", INDICATOR_ROLES],
+	["avatarDiameter", AVATAR_DIAMETER_ROLES],
+	["layoutGap", LAYOUT_GAP_ROLES],
+	["safeAreaInset", SAFE_AREA_INSET_ROLES],
+	["safeAreaMinimum", SAFE_AREA_MINIMUM_ROLES],
+	["loading", LOADING_SIZE_ROLES],
+	["skeleton", SKELETON_SIZE_ROLES]
+];
 /**
 * 全量 Semantic 角色的结构化血缘表——"角色 → 引用的 Reference 路径（含 light/dark 分支）"。
 * 与 buildSemanticStructural/buildSemanticColor 的产出一一对应（顺序一致）。
@@ -2078,64 +2266,9 @@ function semanticRoleEntries() {
 		cssVar: semVar(path),
 		refPath
 	});
-	for (const [role, refPath] of Object.entries(RADIUS_ROLES)) structural([
-		"size",
-		"radius",
-		role
-	], refPath);
-	for (const [role, refPath] of Object.entries(CONTROL_HEIGHT_ROLES)) structural([
-		"size",
-		"controlHeight",
-		role
-	], refPath);
-	for (const [role, refPath] of Object.entries(ICON_SIZE_ROLES)) structural([
-		"size",
-		"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([
+	for (const [group, table] of SIZE_ROLE_GROUPS) for (const [role, refPath] of Object.entries(table)) 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",
+		group,
 		role
 	], refPath);
 	for (const [role, refPath] of Object.entries(INSET_STACK_ROLES)) {
@@ -2165,43 +2298,26 @@ function semanticRoleEntries() {
 		"fontFamily",
 		role
 	], refPath);
-	for (const [role, spec] of Object.entries(TYPOGRAPHY_ROLES)) {
-		structural([
-			"typography",
-			role,
-			"fontFamily"
-		], spec.fontFamilyRef);
-		structural([
-			"typography",
-			role,
-			"fontSize"
-		], spec.fontSizeRef);
-		structural([
-			"typography",
-			role,
-			"fontWeight"
-		], spec.fontWeightRef);
-		structural([
-			"typography",
-			role,
-			"lineHeight"
-		], spec.lineHeightRef);
-		structural([
-			"typography",
-			role,
-			"letterSpacing"
-		], spec.letterSpacingRef);
-	}
+	for (const [role, spec] of Object.entries(TYPOGRAPHY_ROLES)) for (const field of typographyProjectionFields) structural([
+		"typography",
+		role,
+		field
+	], spec[`${field}Ref`]);
 	for (const [role, refPath] of Object.entries(MOTION_DURATION_ROLES)) structural([
 		"motion",
 		"duration",
 		role
 	], refPath);
-	structural([
+	for (const [role, refPath] of Object.entries(MOTION_EASING_ROLES)) structural([
 		"motion",
 		"easing",
-		"standard"
-	], "motion.easing.standard");
+		role
+	], refPath);
+	structural([
+		"effect",
+		"blur",
+		"media-control"
+	], "effect.blur.sm");
 	for (const [path, refs] of Object.entries(COLOR_ROLES)) {
 		const segs = colorRoleSemPath(path);
 		out.push({
@@ -2363,6 +2479,7 @@ function derivationToCssExpr(d) {
 		case "seedAlpha": return `rgb(from var(${seedVar(d.seedRef)}) r g b / ${round4$1(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 String(d.value);
+		case "cssEnvironment": return `env(${d.name}, ${d.fallback})`;
 		case "shadowLayer": {
 			const s = shadowShapeExprs(d.level);
 			const alpha = `calc(var(${seedVar("size.opacity.alphaStep")}) * ${SHADOW_LEVELS[d.level].alphaMult})`;
@@ -2478,12 +2595,20 @@ function buildT2() {
 		});
 		t2[seed] = steps;
 	}
+	t2.black[T2_BLACK_CONTRAST_ENDPOINT.step] = t2Token(colorValue(T2_BLACK_CONTRAST_ENDPOINT.value), {
+		sourceKind: "standard-constant",
+		seedRefs: [],
+		source: T2_BLACK_CONTRAST_ENDPOINT.source,
+		rationale: T2_BLACK_CONTRAST_ENDPOINT.rationale,
+		formula: "= sRGB(0, 0, 0), alpha 1"
+	});
 	return t2;
 }
 function buildT3() {
 	const t3 = {};
 	for (const [role, refs] of Object.entries(FIGMA_T3_COLOR_ROLES)) {
 		const segs = role.split(".");
+		const approval = role === "content.on-brand" ? "RFC0012 user 2026-10-12" : role === "content.danger" ? "RFC0026" : role === "border.control" ? "SPEC085" : void 0;
 		const node = {
 			$type: "color",
 			$value: t2Ref(refs.light),
@@ -2492,7 +2617,11 @@ function buildT3() {
 				modes: {
 					light: t2Ref(refs.light),
 					dark: t2Ref(refs.dark)
-				}
+				},
+				...approval ? {
+					approval,
+					figmaSync: "pending"
+				} : {}
 			} }
 		};
 		let cur = t3;
@@ -2514,7 +2643,11 @@ function buildFigmaColorSnapshot() {
 			collection: "Color",
 			figmaNode: "22258:49986",
 			generated: true,
-			owner: "design-system"
+			owner: "design-system",
+			localExtensions: {
+				rfc: "0012",
+				figmaSync: "pending"
+			}
 		} },
 		qw: {
 			t1: buildT1(),
@@ -2587,17 +2720,18 @@ function provenanceOf(leaf) {
 	const ext = extensionObject(leaf);
 	return isObject(ext.provenance) ? ext.provenance : {};
 }
-function isSolidColorValue(value) {
+/** Shared structural checks preserve the same short-circuit/getter order in both guards. */
+function hasColorComponents(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;
+	return true;
+}
+function isSolidColorValue(value) {
+	return hasColorComponents(value) && 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;
+	return hasColorComponents(value) && typeof value.alpha === "number" && value.alpha >= 0 && value.alpha <= 1;
 }
 function validateNoUnexpectedName(path, errors) {
 	const joined = pathKey(path);
@@ -2608,18 +2742,20 @@ 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 Color 固定为 base / Seed Alpha / OKLCH 三类标准档位。 */
+/** Existing scales plus the explicitly approved RFC0012 standard endpoint. */
 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 === T2_BLACK_CONTRAST_ENDPOINT.step) return "constant";
 	return null;
 }
 /** 各 T2 步类对应的 provenance.sourceKind（血缘治理不变量）。 */
 const T2_STEP_SOURCE_KIND = {
 	base: "seed-alias",
 	alpha: "seed-derived",
-	oklch: "design-calibrated"
+	oklch: "design-calibrated",
+	constant: "standard-constant"
 };
 function validateT2Provenance(leaf, seed, step, errors) {
 	const joined = pathKey(leaf.path);
@@ -2695,6 +2831,11 @@ function validateFigmaColorTokens(doc) {
 		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 (stepKind === "constant") {
+			if (seed !== "black") errors.push(`${joined}: RFC0012 endpoint is only permitted under black`);
+			const value = leaf.value;
+			if (!isObject(value) || value.colorSpace !== "srgb" || value.alpha !== 1 || !Array.isArray(value.components) || value.components.length !== 3 || value.components.some((channel) => channel !== 0)) errors.push(`${joined}: contrast endpoint must be the approved opaque sRGB black mathematical endpoint`);
+		}
 		if (step && !stepKind) errors.push(`${joined}: unsupported T2 step "${step}"`);
 		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) {
@@ -2711,6 +2852,7 @@ function validateFigmaColorTokens(doc) {
 		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(", ")}`);
+		if (seed === "black" && !steps.has(T2_BLACK_CONTRAST_ENDPOINT.step)) errors.push("qw.t2.black: missing RFC0012 contrast endpoint");
 	}
 	const expectedT3 = new Set(figmaT3RolePaths());
 	const actualT3 = /* @__PURE__ */ new Set();
@@ -2718,7 +2860,7 @@ function validateFigmaColorTokens(doc) {
 		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)`);
+		if (!expectedT3.has(joined)) errors.push(`${joined}: unexpected T3 role (not in the canonical Figma/local-approved set)`);
 		const modes = modesOf(leaf);
 		const light = refToPath(modes.light);
 		const dark = refToPath(modes.dark);