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

package/README.md

@@ -4,14 +4,17 @@
 
 **层级 L1 · 设计令牌**。qw-ui 全链路样式的单一数据源，所有组件颜色/尺寸只允许引用本包派生出的 **T3 Semantic token（`--qw-sem-*`）**，禁止直写字面量。
 
-## 三层派生
+## 三层架构
 
 ```
-T1 Seed  ──derive() OKLCH──►  T2 Reference  ──►  T3 Semantic (--qw-sem-*)
-（少量种子色）                （完整色阶）        （组件消费的语义角色）
+T1 Seed（可选生成参数） ── alias / derive / calibrate ──► T2 Reference
+                                                           │
+                                                           ▼
+                                      T3 Semantic (--qw-sem-*) → Component / Style
 ```
 
-Style Dictionary 把三层编译成 CSS 变量与 TS 类型。组件与业务只碰 T3。
+T2 是完整机械标尺，可来自 Seed、设计校准、标准常量或外部标准；每条都带 DTCG
+provenance。T3 只引用 T2，组件与业务只碰 T3。
 
 ## 安装
 

package/dist/color-architecture.d.ts

@@ -9,7 +9,25 @@ export type T2AlphaStep = (typeof T2_ALPHA_STEPS)[number];
 export type T2AlphaKey = (typeof T2_ALPHA_KEYS)[number];
 export declare const T2_OKLCH_STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
 export type T2OklchStep = (typeof T2_OKLCH_STEPS)[number];
+/**
+ * T2 步进锚定 Alpha：锚定 OKLCH 档位实色 + 固定 alpha 的设计校准 rgba
+ * （`{seed}/{step}-a{alpha}`，如 `brand/500-a20`）。只声明被 T3 角色消费的条目，
+ * 不作为完整刻度生成。
+ */
+export declare const FIGMA_T2_STEP_ALPHA: ReadonlyArray<{
+    seed: T1ColorKey;
+    step: T2OklchStep;
+    alpha: T2AlphaStep;
+}>;
+/** T2 `pure` 步进（标准常量 #000000，OLED 画布用）仅提供给 black。 */
+export declare const T2_PURE_STEP = "pure";
+export declare const T2_PURE_SEEDS: readonly ["black"];
 export declare const FIGMA_T2_SOLID_SCALE: Record<T1ColorKey, Record<T2OklchStep, string>>;
+/**
+ * Figma「Color Token System」T3 语义角色表（60 个，light/dark 均引用 T2 路径）。
+ * 与 Figma 节点 22258:49986 逐条对齐；`effect.shadow.*.color` 为复合阴影的颜色
+ * 分量（对应 Figma 变量 `--qw-sem-effect-shadow-*-color`）。
+ */
 export declare const FIGMA_T3_COLOR_ROLES: {
     readonly "surface.base": {
         readonly light: "color.white.base";
@@ -31,6 +49,26 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.blue.50";
         readonly dark: "color.blue.800";
     };
+    readonly "surface.canvas": {
+        readonly light: "color.white.base";
+        readonly dark: "color.black.pure";
+    };
+    readonly "surface.sunken": {
+        readonly light: "color.gray.100";
+        readonly dark: "color.gray.800";
+    };
+    readonly "surface.selected": {
+        readonly light: "color.black.a5";
+        readonly dark: "color.white.a10";
+    };
+    readonly "surface.inverse": {
+        readonly light: "color.black.800";
+        readonly dark: "color.black.800";
+    };
+    readonly "surface.canvas-subtle": {
+        readonly light: "color.gray.50";
+        readonly dark: "color.black.pure";
+    };
     readonly "content.primary": {
         readonly light: "color.black.base";
         readonly dark: "color.white.base";
@@ -51,6 +89,30 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.gray.400";
         readonly dark: "color.gray.500";
     };
+    readonly "content.disabled": {
+        readonly light: "color.black.a30";
+        readonly dark: "color.white.a30";
+    };
+    readonly "content.link": {
+        readonly light: "color.blue.700";
+        readonly dark: "color.blue.400";
+    };
+    readonly "content.icon-subtle": {
+        readonly light: "color.black.a5";
+        readonly dark: "color.white.a10";
+    };
+    readonly "content.inverse": {
+        readonly light: "color.white.base";
+        readonly dark: "color.black.base";
+    };
+    readonly "content.on-solid": {
+        readonly light: "color.white.base";
+        readonly dark: "color.white.base";
+    };
+    readonly "content.on-warning-subtle": {
+        readonly light: "color.yellow.800";
+        readonly dark: "color.yellow.200";
+    };
     readonly "border.default": {
         readonly light: "color.gray.100";
         readonly dark: "color.gray.700";
@@ -63,6 +125,18 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.brand.base";
         readonly dark: "color.brand.500";
     };
+    readonly "border.subtle": {
+        readonly light: "color.black.a5";
+        readonly dark: "color.white.a5";
+    };
+    readonly "border.disabled": {
+        readonly light: "color.black.a10";
+        readonly dark: "color.white.a10";
+    };
+    readonly "border.on-media": {
+        readonly light: "color.white.base";
+        readonly dark: "color.white.base";
+    };
     readonly "fill.subtle": {
         readonly light: "color.gray.50";
         readonly dark: "color.white.a20";
@@ -79,6 +153,10 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.gray.50";
         readonly dark: "color.gray.900";
     };
+    readonly "fill.track": {
+        readonly light: "color.black.a10";
+        readonly dark: "color.white.a20";
+    };
     readonly "action.brand": {
         readonly light: "color.brand.base";
         readonly dark: "color.brand.500";
@@ -89,12 +167,44 @@ export declare const FIGMA_T3_COLOR_ROLES: {
     };
     readonly "action.selected": {
         readonly light: "color.blue.a20";
-        readonly dark: "color.blue.a40";
+        readonly dark: "color.blue.600-a40";
     };
     readonly "action.inverse": {
         readonly light: "color.white.base";
         readonly dark: "color.black.base";
     };
+    readonly "control-action.brand.subtle": {
+        readonly light: "color.brand.a10";
+        readonly dark: "color.brand.500-a20";
+    };
+    readonly "control-action.product.subtle": {
+        readonly light: "color.blue.a10";
+        readonly dark: "color.blue.600-a20";
+    };
+    readonly "control-action.danger.default": {
+        readonly light: "color.red.400";
+        readonly dark: "color.red.400";
+    };
+    readonly "control-action.danger.subtle": {
+        readonly light: "color.red.400-a10";
+        readonly dark: "color.red.400-a20";
+    };
+    readonly "control-action.neutral.subtle": {
+        readonly light: "color.black.a5";
+        readonly dark: "color.white.a10";
+    };
+    readonly "control-selection.brand": {
+        readonly light: "color.brand.a10";
+        readonly dark: "color.brand.500-a20";
+    };
+    readonly "control-selection.product": {
+        readonly light: "color.blue.a10";
+        readonly dark: "color.blue.600-a20";
+    };
+    readonly "selection.text-background": {
+        readonly light: "color.blue.a20";
+        readonly dark: "color.blue.600-a40";
+    };
     readonly "status.success": {
         readonly light: "color.green.base";
         readonly dark: "color.green.base";
@@ -111,12 +221,52 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.blue.base";
         readonly dark: "color.blue.600";
     };
+    readonly "status.success-subtle": {
+        readonly light: "color.green.a10";
+        readonly dark: "color.green.a20";
+    };
+    readonly "status.warning-subtle": {
+        readonly light: "color.yellow.a20";
+        readonly dark: "color.yellow.a20";
+    };
+    readonly "status.danger-subtle": {
+        readonly light: "color.red.400-a10";
+        readonly dark: "color.red.400-a20";
+    };
+    readonly "status.info-subtle": {
+        readonly light: "color.blue.a10";
+        readonly dark: "color.blue.600-a20";
+    };
     readonly "overlay.scrim": {
         readonly light: "color.black.a50";
         readonly dark: "color.black.a70";
     };
     readonly "overlay.guide": {
-        readonly light: "color.black.a70";
-        readonly dark: "color.black.a70";
+        readonly light: "color.blue.a10";
+        readonly dark: "color.blue.600-a20";
+    };
+    readonly "overlay.media-subtle": {
+        readonly light: "color.black.a40";
+        readonly dark: "color.black.a40";
+    };
+    readonly "overlay.media-strong": {
+        readonly light: "color.black.a50";
+        readonly dark: "color.black.a50";
+    };
+    readonly shadow: {
+        readonly light: "color.black.a10";
+        readonly dark: "color.black.a50";
+    };
+    readonly "effect.shadow.card.color": {
+        readonly light: "color.black.a10";
+        readonly dark: "color.black.a50";
+    };
+    readonly "effect.shadow.floating.color": {
+        readonly light: "color.black.a10";
+        readonly dark: "color.black.a50";
+    };
+    readonly "effect.shadow.dialog.color": {
+        readonly light: "color.black.a10";
+        readonly dark: "color.black.a50";
     };
 };

package/dist/derive/index.d.ts

@@ -4,8 +4,8 @@ export type { Layer } from "./naming.js";
 export { ramp, STEPS, L_TARGETS, chromaFactor, contrastRatio } from "./oklch.js";
 export type { Step, Ramp } from "./oklch.js";
 export type { SemanticMode as Mode } from "./semantic.js";
-export type { ReferenceRecipe, ReferenceTokens, ReferenceBuild, Derivation, ShadowLevel, ShadowShape, } from "./reference.js";
-export { buildReference, allReferenceRecipes, evaluateDerivation, seedRefsOf, formatDerivation, seedValueAt, RAMP_COLORS, BLACK_ALPHA, WHITE_ALPHA, RADIUS_FACTORS, FONT_SIZE_FACTORS, DURATION_FACTORS, SHADOW_LEVELS, FONT_FAMILY_KEYS, } from "./reference.js";
+export type { ReferenceRecipe, ReferenceTokens, ReferenceBuild, Derivation, ReferenceSourceKind, ShadowLevel, ShadowShape, } from "./reference.js";
+export { buildReference, allReferenceRecipes, evaluateDerivation, seedRefsOf, sourceKindOf, formatDerivation, seedValueAt, RAMP_COLORS, BLACK_ALPHA, WHITE_ALPHA, RADIUS_FACTORS, FONT_SIZE_FACTORS, DURATION_FACTORS, SHADOW_LEVELS, FONT_FAMILY_KEYS, } from "./reference.js";
 export { buildSemanticStructural, buildSemanticColor, semanticRoleEntries, RADIUS_ROLES, CONTROL_HEIGHT_ROLES, ICON_SIZE_ROLES, INSET_STACK_ROLES, Z_INDEX_ROLES, MOTION_DURATION_ROLES, FONT_FAMILY_ROLES, TYPOGRAPHY_ROLES, TYPOGRAPHY_FIELDS, COLOR_ROLES, SHADOW_COMPOSITE_ROLES, } from "./semantic.js";
 export type { SemanticRoleEntry, ColorRoleRefs, TypographyRole } from "./semantic.js";
 export interface DerivedTokens {

package/dist/derive/live-css.d.ts

@@ -1,6 +1,6 @@
 import { type Derivation } from "./reference.js";
 import type { Seed } from "../schema.js";
-/** Seed 拍平成 `--qw-seed-*` → CSS 值。live CSS 里唯一携带具体数值的层。 */
+/** Seed 拍平成 `--qw-seed-*` → CSS 值；T2 仍可包含校准值或标准常量。 */
 export declare function seedCssVars(seed: Seed): Record<string, string>;
 /** 一条 Derivation → 引用 `--qw-seed-*` 的 CSS 原生表达式。 */
 export declare function derivationToCssExpr(d: Derivation): string;

package/dist/derive/reference.d.ts

@@ -1,5 +1,5 @@
 import { type Step } from "./oklch.js";
-import { type T2OklchStep } from "../color-architecture.js";
+import { type T1ColorKey, type T2OklchStep } from "../color-architecture.js";
 import type { Seed } from "../schema.js";
 /**
  * T2 Reference（Primitive）派生 —— RFC 0001 §2.1，v3 声明式重构。
@@ -11,13 +11,26 @@ import type { Seed } from "../schema.js";
  * 3. live CSS 生成（derive/live-css.ts，relative color / calc 表达式）；
  * 4. Token Studio 的派生公式展示（formatDerivation）。
  *
- * `seedRefs` 由 AST 自动推导（seedRefsOf），不再手写；可追溯性校验
- * （derive/reference.test.ts）遍历 recipes 断言 seedRefs 非空。
+ * `sourceKind` 与 `seedRefs` 由 AST 自动推导（sourceKindOf / seedRefsOf）；
+ * Seed 来源类必须有血缘，标准常量与外部标准则记录来源/理由，不伪造 Seed。
  * 颜色层对齐 Figma `Color/qw` 变量集合：
  * - T1 Seed 为 12 个单色种子；
- * - T2 Reference 为每个 seed 的 A5-A100 Alpha 通道、50-900 OKLCH 设计校准实色色阶、base 引用。
+ * - T2 Reference 为每个 seed 的 A5-A100 Alpha 通道、50-900 OKLCH 设计校准实色色阶、
+ *   base 引用，以及少量补充原语（步进锚定 Alpha `{seed}/{step}-a{alpha}`、black/pure 标准常量）。
  */
 export type ShadowLevel = "sm" | "md" | "lg";
+/**
+ * T2 Reference 的规范来源类型。
+ *
+ * DTCG 不要求 Reference 必须引用 Seed；它只规范 token、group 与 alias 的表达。
+ * qw-ui 用本字段补足跨 Figma / code 的血缘治理：
+ * - seed-alias：原样承接一个 T1；
+ * - seed-derived：通过确定公式从一个或多个 T1 生成；
+ * - design-calibrated：保留 T1 设计血缘，但 canonical 值由设计校准拍板；
+ * - standard-constant：机械标准或数学端点，不伪造 T1；
+ * - external-standard：来自外部平台/规范，由外部来源负责版本化。
+ */
+export type ReferenceSourceKind = "seed-alias" | "seed-derived" | "design-calibrated" | "standard-constant" | "external-standard";
 export type Derivation = 
 /** 直通引用 Seed 字段（dimension/number/duration 字符串或数字）。 */
 {
@@ -69,6 +82,13 @@ export type Derivation =
     seedRef: string;
     alpha: number;
 }
+/** Figma 校准的步进锚定 Alpha：OKLCH 档位实色 + 固定 alpha（如 brand/500-a20）。 */
+ | {
+    kind: "stepAlpha";
+    seedRef: string;
+    step: T2OklchStep;
+    alpha: number;
+}
 /** 旧版纯黑/纯白透明度工具刻度。保留求值器兼容，不再由 T2 主链路生成。 */
  | {
     kind: "alphaScale";
@@ -86,10 +106,10 @@ export type Derivation =
     kind: "cubicBezier";
     seedRef: string;
 }
-/** 白名单字面量（色彩空间数学端点，非设计决策）。 */
+/** canonical 常量（机械标准或数学端点，非主题生成参数）。 */
  | {
     kind: "literal";
-    value: string;
+    value: string | number;
 }
 /** 阴影档位：形状 = shadow.base × 档位比例，颜色 = alphaStep × 档位倍数。 */
  | {
@@ -99,8 +119,14 @@ export type Derivation =
 export interface ReferenceRecipe {
     path: string[];
     cssVar: string;
-    /** 由 derivation 自动推导的 Seed 依赖（点分路径），供可追溯性校验与血缘展示。 */
+    /** 规范来源；决定 seedRefs 是否必须非空。 */
+    sourceKind: ReferenceSourceKind;
+    /** 由 derivation 自动推导的可选 Seed 依赖（点分路径），供可追溯性校验与血缘展示。 */
     seedRefs: string[];
+    /** 标准、设计稿或外部规范的可读来源；非 Seed 来源类必填。 */
+    source?: string;
+    /** 为什么该值属于 T2 而不是 T1 的简短依据。 */
+    rationale?: string;
     derivation: Derivation;
 }
 /** 拍平后的 CSS 变量映射：cssVar → 字符串值（--qw-ref-* 全集）。 */
@@ -125,6 +151,10 @@ export interface ReferenceBuild {
 }
 /** 按点分路径读 Seed 字段（"size.spacing.step" → seed.size.spacing.step）。 */
 export declare function seedValueAt(seed: Seed, dotted: string): unknown;
+/** 从 Seed 颜色点分路径（"color.brand"）取 T1 键。 */
+export declare function seedKeyOf(seedRef: string): T1ColorKey;
+/** 步进锚定 Alpha 的求值：FIGMA_T2_SOLID_SCALE 档位实色 + alpha → rgba。 */
+export declare function stepAlphaCss(seed: T1ColorKey, step: T2OklchStep, alpha: number): string;
 export declare function formatFontFamily(list: string[]): string;
 /** 阴影档位系数：形状（offset/blur/spread 缩放）+ 颜色（alphaStep 倍数）。 */
 export declare const SHADOW_LEVELS: Record<ShadowLevel, {
@@ -136,11 +166,15 @@ export declare const SHADOW_LEVELS: Record<ShadowLevel, {
 export declare function evaluateDerivation(d: Derivation, seed: Seed): string;
 /** Seed 依赖推导：AST 里出现的全部 Seed 点分路径。 */
 export declare function seedRefsOf(d: Derivation): string[];
+/** Derivation AST → 规范来源分类；作为 Figma/DTCG provenance 的唯一映射口。 */
+export declare function sourceKindOf(d: Derivation): ReferenceSourceKind;
 /** 人读派生公式（Token Studio 展示用）。 */
 export declare function formatDerivation(d: Derivation): string;
 export declare const RAMP_COLORS: readonly ["brand", "black", "white", "gray", "red", "orange", "yellow", "green", "cyan", "blue", "purple", "brown"];
 /** 1. 12 个 Seed ×（A5-A100 Alpha 通道 + 50-900 Figma OKLCH 校准色阶 + base）。 */
 export declare function buildColorRampRecipes(): ReferenceRecipe[];
+/** 2. Figma T2 补充原语：步进锚定 Alpha（仅被 T3 消费的条目）+ black/pure 标准常量。 */
+export declare function buildColorExtraRecipes(): ReferenceRecipe[];
 /** @deprecated Figma T2 已不再使用 neutral 0/1000 端点；保留给历史迁移脚本。 */
 export declare function buildNeutralEndpointRecipes(): ReferenceRecipe[];
 export declare const BLACK_ALPHA: ReadonlyArray<readonly [string, number]>;
@@ -149,18 +183,44 @@ export declare const WHITE_ALPHA: ReadonlyArray<readonly [string, number]>;
 export declare function buildAlphaScaleRecipes(): ReferenceRecipe[];
 /** 4. 间距刻度 = spacing.step × N (N=1..8)。 */
 export declare function buildSpacingRecipes(): ReferenceRecipe[];
-/** 圆角档位系数（sm/lg 从 base 派生；默认 base=8px → 4/8/14）。 */
+/** 圆角档位系数（sm/lg/xl 从 base 派生；默认 base=8px → 4/8/14/16）。 */
 export declare const RADIUS_FACTORS: {
     readonly sm: 0.5;
     readonly md: 1;
     readonly lg: 1.75;
+    readonly xl: 2;
 };
-/** 5. 圆角刻度：sm/md/lg 由 radius.base 按系数派生，full 直通独立裁切基准。 */
+/** 5. 圆角刻度：sm/md/lg/xl 由 radius.base 按系数派生，full 直通独立裁切基准。xl=2×base 对齐治理稿 Radius v2 的 T2 double。 */
 export declare function buildRadiusRecipes(): ReferenceRecipe[];
 /** 6. 控件/图标尺寸：md = base 直通，sm/lg = base ∓ spacing.step × n（控件 ×2、图标 ×1）。 */
 export declare function buildControlIconSizeRecipes(): ReferenceRecipe[];
-/** 7. 描边宽度 —— 直通引用。 */
-export declare function buildBorderWidthRecipes(): ReferenceRecipe[];
+/** 描边宽度梯度系数（Figma Stroke v1：Half/Base/Double/Triple = 0.5/1/2/3）。 */
+export declare const STROKE_WIDTH_FACTORS: {
+    readonly half: 0.5;
+    readonly double: 2;
+    readonly triple: 3;
+};
+/** 7. 描边宽度（Figma Stroke v1）：base 直通 Seed，half/double/triple 按系数派生。 */
+export declare function buildStrokeWidthRecipes(): ReferenceRecipe[];
+/** 六档动作控件高度（Figma Action Control v1）：现有公开尺寸契约，不能由单一 T1 Base 可靠派生，直接定义在 T2（T1 不设 Control Size）。 */
+export declare const ACTION_CONTROL_HEIGHTS: {
+    readonly "2xs": 24;
+    readonly xs: 28;
+    readonly sm: 32;
+    readonly md: 36;
+    readonly lg: 42;
+    readonly xl: 50;
+};
+/** 7b. 动作控件尺寸：六档高度 + 2XS 图标特例（Square 复用同档 Height，不另设 token）。 */
+export declare function buildActionControlRecipes(): ReferenceRecipe[];
+/** Avatar 三档直径（Figma 头像 · Avatar S/M/L = 40/50/58）。 */
+export declare const AVATAR_DIAMETERS: {
+    readonly sm: 40;
+    readonly md: 50;
+    readonly lg: 58;
+};
+/** 7c. 展示类专用尺寸：Avatar 直径（Icon Size 规范要求 Avatar 直径使用自己的语义，禁止借用 Icon/Control 刻度）。 */
+export declare function buildAvatarDiameterRecipes(): ReferenceRecipe[];
 /** 8. 行高（typography 类目）：normal 直通 Seed，tight/relaxed = base ∓ 0.25。 */
 export declare function buildLineHeightRecipes(): ReferenceRecipe[];
 /** 9. 禁用态不透明度 —— 直通引用。 */
@@ -168,9 +228,9 @@ export declare function buildOpacityRecipes(): ReferenceRecipe[];
 /** 10. 层级刻度 = zIndex.step × N (N=1..4)；角色分配交给 Semantic 层。 */
 export declare function buildZIndexRecipes(): ReferenceRecipe[];
 export declare const FONT_FAMILY_KEYS: readonly ["text", "number", "code", "textMacLatin", "textMacZh", "textMacJa", "textWindowsLatin", "textWindowsZh", "textWindowsJa"];
-/** 字号档位倍数（沿用既定视觉：14px 基准 → 12/16/20/24）。 */
+/** 字号档位倍数（沿用既定视觉：14px 基准 → 11/12/16/20/24；xs=11 对齐治理稿 T2 Font Size 2XS）。 */
 export declare const FONT_SIZE_FACTORS: Record<string, number>;
-/** 11. 排版原子：字体族（三族 + 平台/语言变体）/字重直通，字号按既定倍数派生。 */
+/** 11. 排版原子：字体族来自平台 Seed；字重是机械标准常量；字号按既定倍数派生。 */
 export declare function buildTypographyRecipes(): ReferenceRecipe[];
 /** 动效时长档位倍数。 */
 export declare const DURATION_FACTORS: {

package/dist/derive/semantic.d.ts

@@ -14,6 +14,16 @@ export type SemanticMode = "light" | "dark";
 export declare const RADIUS_ROLES: Record<string, string>;
 export declare const CONTROL_HEIGHT_ROLES: Record<string, string>;
 export declare const ICON_SIZE_ROLES: Record<string, string>;
+export declare const ACTION_CONTROL_HEIGHT_ROLES: Record<string, string>;
+export declare const ACTION_CONTROL_PADDING_INLINE_ROLES: Record<string, string>;
+export declare const ACTION_CONTROL_ICON_ROLES: Record<string, string>;
+export declare const ACTION_CONTROL_GAP_ROLES: Record<string, string>;
+export declare const BORDER_WIDTH_ROLES: Record<string, string>;
+export declare const DIVIDER_WIDTH_ROLES: Record<string, string>;
+export declare const FOCUS_RING_ROLES: Record<string, string>;
+export declare const INDICATOR_ROLES: Record<string, string>;
+/** 展示类专用尺寸：Avatar 直径三档（Figma 头像 S/M/L）。 */
+export declare const AVATAR_DIAMETER_ROLES: Record<string, string>;
 export declare const INSET_STACK_ROLES: Record<string, string>;
 export declare const Z_INDEX_ROLES: Record<string, string>;
 export declare const MOTION_DURATION_ROLES: Record<string, string>;
@@ -33,8 +43,14 @@ export interface ColorRoleRefs {
     light: string;
     dark: string;
 }
+/**
+ * 颜色角色的 Semantic 变量路径：绝大多数角色落在 `--qw-sem-color-*` 下；
+ * `effect.shadow.*.color` 是复合阴影的颜色分量，对应 Figma 变量
+ * `--qw-sem-effect-shadow-*-color`，不带 `color-` 前缀。
+ */
+export declare function colorRoleSemPath(role: string): string[];
 export declare const COLOR_ROLES: Record<string, ColorRoleRefs>;
-/** 复合阴影角色：形状取 Reference effect.shadow.<level>，颜色取 color.shadow。 */
+/** 复合阴影角色：形状取 Reference effect.shadow.<level>，颜色取各自的 effect.shadow.<role>.color 分量。 */
 export declare const SHADOW_COMPOSITE_ROLES: Record<string, ShadowLevel>;
 export type SemanticRoleEntry = {
     kind: "structural";

package/dist/design-doc.d.ts

@@ -5,6 +5,6 @@ export declare function buildReferenceDesignDoc(): Json;
 export declare function buildSemanticDesignDoc(): Json;
 /** 生成 design/semantic.color.tokens.json（light/dark 合并视图）。 */
 export declare function buildSemanticColorDesignDoc(): Json;
-/** 三份生成文件的文件名 → 生成器映射，供导出脚本与 parity 测试共用。 */
+/** 生成文件的文件名 → 生成器映射，供导出脚本与 parity 测试共用。 */
 export declare const GENERATED_DESIGN_DOCS: Record<string, () => Json>;
 export {};

package/dist/figma/color-contract.d.ts

@@ -10,5 +10,7 @@ export interface FigmaColorTokenValidationResult {
         t3: number;
     };
 }
+/** T3 角色全集（qw 路径），由 FIGMA_T3_COLOR_ROLES 投影。 */
+export declare function figmaT3RolePaths(): string[];
 export declare function validateFigmaColorTokens(doc: unknown): FigmaColorTokenValidationResult;
 export declare function assertFigmaColorTokens(doc: unknown): void;

package/dist/figma/color-snapshot.d.ts

@@ -0,0 +1,4 @@
+type Json = Record<string, unknown>;
+/** 生成 design/color.tokens.json 的完整 JSON 对象（qw/t1/t2/t3 结构）。 */
+export declare function buildFigmaColorSnapshot(): Json;
+export {};

package/dist/index.d.ts

@@ -3,11 +3,12 @@ export { SeedSchema, validateSeed } from "./schema.js";
 export type { Seed, SeedInput } from "./schema.js";
 export { hexToSeedColor, seedColorToHex, seedColorToCss } from "./color.js";
 export type { SeedColorValue } from "./color.js";
-export { FIGMA_COLOR_COLLECTION, FIGMA_COLOR_PREFIX, FIGMA_T1_SEED_HEX, FIGMA_T2_SOLID_SCALE, FIGMA_T3_COLOR_ROLES, T1_COLOR_KEYS, T2_ALPHA_KEYS, T2_ALPHA_STEPS, T2_OKLCH_STEPS, } from "./color-architecture.js";
+export { FIGMA_COLOR_COLLECTION, FIGMA_COLOR_PREFIX, FIGMA_T1_SEED_HEX, FIGMA_T2_SOLID_SCALE, FIGMA_T2_STEP_ALPHA, FIGMA_T3_COLOR_ROLES, T1_COLOR_KEYS, T2_ALPHA_KEYS, T2_ALPHA_STEPS, T2_OKLCH_STEPS, T2_PURE_SEEDS, T2_PURE_STEP, } from "./color-architecture.js";
 export type { T1ColorKey, T2AlphaKey, T2AlphaStep, T2OklchStep } from "./color-architecture.js";
-export { derive, toVar, ramp, STEPS, L_TARGETS, contrastRatio, buildReference, allReferenceRecipes, evaluateDerivation, formatDerivation, seedRefsOf, seedValueAt, buildSemanticStructural, buildSemanticColor, semanticRoleEntries, RAMP_COLORS, COLOR_ROLES, TYPOGRAPHY_ROLES, SHADOW_COMPOSITE_ROLES, } from "./derive/index.js";
-export type { DerivedTokens, Mode, Layer, Step, Ramp, ReferenceRecipe, ReferenceBuild, ReferenceTokens, Derivation, SemanticRoleEntry, ColorRoleRefs, } from "./derive/index.js";
+export { derive, toVar, ramp, STEPS, L_TARGETS, contrastRatio, buildReference, allReferenceRecipes, evaluateDerivation, formatDerivation, seedRefsOf, sourceKindOf, seedValueAt, buildSemanticStructural, buildSemanticColor, semanticRoleEntries, RAMP_COLORS, COLOR_ROLES, TYPOGRAPHY_ROLES, SHADOW_COMPOSITE_ROLES, } from "./derive/index.js";
+export type { DerivedTokens, Mode, Layer, Step, Ramp, ReferenceRecipe, ReferenceBuild, ReferenceTokens, Derivation, ReferenceSourceKind, SemanticRoleEntry, ColorRoleRefs, } from "./derive/index.js";
 export { buildLiveCss, seedCssVars, derivationToCssExpr } from "./derive/live-css.js";
 export type { LiveCssOptions } from "./derive/live-css.js";
-export { compatRegistrySchema, compatPathToCssVar, buildCompatFromRegistry, formatCompatTypes, } from "./compat/index.js";
-export type { CompatEntry, CompatRegistry, CompatBuild } from "./compat/index.js";
+export { buildFigmaColorSnapshot } from "./figma/color-snapshot.js";
+export { validateFigmaColorTokens, assertFigmaColorTokens, figmaT3RolePaths, } from "./figma/color-contract.js";
+export type { FigmaColorTokenValidationResult } from "./figma/color-contract.js";