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

package/README.md

@@ -1,76 +1,43 @@
 # @qw-ui/tokens
 
-> QW token pipeline：Figma Color variables 是颜色唯一事实源；代码侧校验快照并构建出 CSS / TS 产物。
-
-**层级 L1 · 设计令牌**。qw-ui 全链路样式的单一数据源，所有组件颜色/尺寸只允许引用本包派生出的 **T3 Semantic token（`--qw-sem-*`）**，禁止直写字面量。
-
-## 三层派生
-
-```
-T1 Seed  ──derive() OKLCH──►  T2 Reference  ──►  T3 Semantic (--qw-sem-*)
-（少量种子色）                （完整色阶）        （组件消费的语义角色）
-```
-
-Style Dictionary 把三层编译成 CSS 变量与 TS 类型。组件与业务只碰 T3。
+设计 Token 与主题。Design tokens and theme utilities for qw-ui.
 
 ## 安装
 
+当前开发版本使用 `next`：
+
 ```bash
-pnpm add @qw-ui/tokens
+npm install @qw-ui/tokens@next
 ```
 
-无 peer 依赖。
+包发布于 [公共 npm](https://www.npmjs.com/package/@qw-ui/tokens)。如环境配置了其他镜像，可在安装命令后追加 `--registry=https://registry.npmjs.org/`。
 
 ## 最小示例
 
 ```ts
-// 1. 静态变量（构建期固化，SSR 友好，不随运行时切换）
-import "@qw-ui/tokens/tokens.css";
+import '@qw-ui/tokens/tokens.css';
+import { defaultSeed, derive } from '@qw-ui/tokens';
 
-// 2. 或 live 变量（支持运行时亮暗/主题切换）
-import "@qw-ui/tokens/tokens.live.css";
-
-// 3. TS 侧拿 token 路径类型 / 原始 JSON
-import type { TokenPath } from "@qw-ui/tokens/token-paths";
-import tokens from "@qw-ui/tokens/tokens.json" with { type: "json" };
-```
-
-CSS 里直接用变量：
-
-```css
-.card { color: var(--qw-sem-color-content-primary); background: var(--qw-sem-color-surface-base); }
+const theme = derive(defaultSeed);
+console.log(theme);
 ```
 
-## tokens.css vs tokens.live.css
+## 使用说明
 
-| 产物 | 用途 | 亮暗切换 |
-|---|---|---|
-| `tokens.css` | 默认静态变量，构建期固化 | 需整页换文件 |
-| `tokens.live.css` | 语义变量随 `<html data-qw-mode>` / Provider 解析 | 运行时切换（见下） |
+应用使用 `tokens.css` 提供默认变量；组件消费 `--qw-sem-*` 语义变量。可通过容器的 `data-qw-mode="dark"` 使用暗色主题。`tokens.live.css`、`tailwind.css`、`tokens.json` 等公开资源按项目需求选择，具体入口以 package exports 为准。
 
-**亮暗两种做法**：① 在 `<html>` 上写 `data-qw-mode="dark"`；② React/Vue 用 `QwConfigProvider` 的 `applyMode` / `toggleMode`。两者都只切 T3 解析，不改组件。
+## 兼容性
 
-## 关联包
-
-| 包 | 关系 |
-|---|---|
-| [@qw-ui/react](../react/README.md) / [@qw-ui/vue](../vue/README.md) | 消费 T3 token 渲染组件，需先引本包 CSS |
-| [@qw-ui/theme-editor](../theme-editor/README.md) | 可视化编辑 Seed → 实时预览三层级联 |
-| `@qw-ui/styles-core`（private，不发布） | vanilla-extract 样式事实源，只读本包 T3 token |
-
-设计稿老色值 → T3 映射见 skill `qw-legacy-token-map`。
+CSS 面向 Chrome 123 / iOS Safari 16.4。主题派生 API 可用于 Node 构建工具和浏览器。
 
 ## 版本通道
 
-| 通道 | 安装 | 说明 |
-|---|---|---|
-| `latest`（稳定） | `pnpm add @qw-ui/tokens` | `main` 通道，Release PR review 后发布 |
-| `next`（预发布） | `pnpm add @qw-ui/tokens@next` | `release/next` 通道，高频自增 `x.y.z-next.N` |
-
-8 个公开包 `fixed` 锁步同版本号。npm 发布固定走 `registry.npmjs.org`；内网装依赖走 `registry.anpm.alibaba-inc.com`（tnpm 代理），发布 registry 不要指向内网。流程详见 [development-workflow.md](../../docs/development-workflow.md)。
+- `next`：main 更新并通过检查后自动发布，用于试用当前能力。
+- `latest`：负责人手动发布的正式版本。正式版可用后，使用 `npm install @qw-ui/tokens@latest`；正式版支持范围以该版本 README 为准。
+- 生产项目建议锁定明确版本。配套使用的 `@qw-ui/*` 包应选择同批版本；内部运行时依赖由包管理器安装。
 
-## 仓库 & License
+## 文档与许可证
 
-- 主仓库：<http://gitlab.alibaba-inc.com/qianwen/qw-ui>
-- 问题反馈：<http://gitlab.alibaba-inc.com/qianwen/qw-ui/issues>
-- License：MIT
+- [组件文档与接入指南](https://qw-ui.qianwen.com/)
+- [npm 版本列表](https://www.npmjs.com/package/@qw-ui/tokens?activeTab=versions)
+- MIT，详见包内 `LICENSE`。

package/dist/color-architecture.d.ts

@@ -9,7 +9,20 @@ 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];
+/** RFC0012 approved local standard endpoint; Figma synchronization is pending. */
+export declare const T2_BLACK_CONTRAST_ENDPOINT: {
+    readonly step: "contrast-endpoint";
+    readonly value: "#000000";
+    readonly source: "CSS Color sRGB black mathematical endpoint; specs/rfcs/0012-brand-solid-text-contrast.md";
+    readonly rationale: "The zero sRGB endpoint is a standard constant for on-brand AA text, independent of Seed and existing color scales.";
+};
 export declare const FIGMA_T2_SOLID_SCALE: Record<T1ColorKey, Record<T2OklchStep, string>>;
+/**
+ * Figma「Color Token System」既有角色及用户批准的本地补充角色。
+ * 既有角色与 Figma 节点 22258:49986 对齐；新角色等待 Figma 同步，不冒充已回流。
+ * light/dark 均引用 T2；`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 +44,30 @@ 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.900";
+    };
+    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.900";
+    };
+    readonly "content.danger": {
+        readonly light: "color.red.600";
+        readonly dark: "color.red.300";
+    };
     readonly "content.primary": {
         readonly light: "color.black.base";
         readonly dark: "color.white.base";
@@ -51,6 +88,34 @@ 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-brand": {
+        readonly light: "color.white.base";
+        readonly dark: "color.black.contrast-endpoint";
+    };
+    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";
@@ -59,10 +124,26 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.gray.300";
         readonly dark: "color.gray.600";
     };
+    readonly "border.control": {
+        readonly light: "color.gray.600";
+        readonly dark: "color.gray.base";
+    };
     readonly "border.focus": {
         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 +160,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";
@@ -95,6 +180,38 @@ export declare const FIGMA_T3_COLOR_ROLES: {
         readonly light: "color.white.base";
         readonly dark: "color.black.base";
     };
+    readonly "control-action.brand.subtle": {
+        readonly light: "color.brand.a10";
+        readonly dark: "color.brand.a20";
+    };
+    readonly "control-action.product.subtle": {
+        readonly light: "color.blue.a10";
+        readonly dark: "color.blue.a20";
+    };
+    readonly "control-action.danger.default": {
+        readonly light: "color.red.600";
+        readonly dark: "color.red.600";
+    };
+    readonly "control-action.danger.subtle": {
+        readonly light: "color.red.a10";
+        readonly dark: "color.red.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.a20";
+    };
+    readonly "control-selection.product": {
+        readonly light: "color.blue.a10";
+        readonly dark: "color.blue.a20";
+    };
+    readonly "selection.text-background": {
+        readonly light: "color.blue.a20";
+        readonly dark: "color.blue.a40";
+    };
     readonly "status.success": {
         readonly light: "color.green.base";
         readonly dark: "color.green.base";
@@ -111,12 +228,56 @@ 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.a10";
+        readonly dark: "color.red.a20";
+    };
+    readonly "status.info-subtle": {
+        readonly light: "color.blue.a10";
+        readonly dark: "color.blue.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.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 "overlay.control-on-media": {
+        readonly light: "color.black.a50";
+        readonly dark: "color.white.a40";
+    };
+    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,9 +4,9 @@ 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 { 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 { 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, MOTION_EASING_ROLES, SKELETON_SIZE_ROLES, LOADING_SIZE_ROLES, LAYOUT_GAP_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 {
     /** 亮色全量 CSS 变量：--qw-ref-* ∪ --qw-sem-*（light 取值）。 */

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,27 @@ 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 引用，以及 RFC0012 批准的纯黑 standard-constant 数学端点。
+ *   T2 Color 不接受其它零散补色或「色阶 × Alpha」组合。
  */
 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 字符串或数字）。 */
 {
@@ -86,10 +100,16 @@ export type Derivation =
     kind: "cubicBezier";
     seedRef: string;
 }
-/** 白名单字面量（色彩空间数学端点，非设计决策）。 */
+/** canonical 常量（机械标准或数学端点，非主题生成参数）。 */
  | {
     kind: "literal";
-    value: string;
+    value: string | number;
+}
+/** UA-owned CSS environment value; preserved as an expression, never a guessed device length. */
+ | {
+    kind: "cssEnvironment";
+    name: `safe-area-inset-${"top" | "right" | "bottom" | "left"}`;
+    fallback: "0px";
 }
 /** 阴影档位：形状 = 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,8 @@ 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;
 export declare function formatFontFamily(list: string[]): string;
 /** 阴影档位系数：形状（offset/blur/spread 缩放）+ 颜色（alphaStep 倍数）。 */
 export declare const SHADOW_LEVELS: Record<ShadowLevel, {
@@ -136,6 +164,8 @@ 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"];
@@ -149,18 +179,48 @@ 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[];
+/** Existing public placeholder geometry: font-relative text and calibrated media. */
+export declare function buildPlaceholderSizeRecipes(): ReferenceRecipe[];
+/** Loading logo boxes follow the independent existing public size contract. */
+export declare function buildLoadingSizeRecipes(): 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,23 @@ 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>;
+/** Independent placeholder roles reference T2 directly, never other T3 roles. */
+export declare const SKELETON_SIZE_ROLES: Record<string, string>;
+export declare const MOTION_EASING_ROLES: Record<string, string>;
+export declare const LOADING_SIZE_ROLES: Record<string, string>;
+export declare const LAYOUT_GAP_ROLES: Record<string, string>;
+export declare const SAFE_AREA_INSET_ROLES: Record<string, string>;
+export declare const SAFE_AREA_MINIMUM_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 +50,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/derive/tailwind.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Tailwind v4 适配器 —— dist/tailwind.css 的生成引擎。
+ *
+ * 把 T3 Semantic 变量映射进 Tailwind v4 的 @theme 命名空间，让工具类
+ * （bg-surface-base / text-content-primary / rounded-control / p-inset-md …）
+ * 直接吃组件库 token。只映射 T3（--qw-sem-*），--qw-ref-* 永不出现在产物里。
+ *
+ * 必须用 `@theme inline`：值是对外部变量的引用时，inline 让工具类直接内联
+ * var(--qw-sem-*)，在使用元素处求值——子树级 [data-qw-mode="dark"] 覆盖才能
+ * 生效；非 inline 会在 :root 处解析一次，子树暗色失效。
+ *
+ * 映射规则（确定性，token 变了产物自动跟）：
+ * - --qw-sem-color-<x>                  → --color-<x>
+ * - --qw-sem-size-radius-<x>            → --radius-<x>
+ * - --qw-sem-size-inset-<x>             → --spacing-inset-<x>
+ * - --qw-sem-size-stack-<x>             → --spacing-stack-<x>
+ * - --qw-sem-typography-font-family-<x> → --font-<x>
+ * - --qw-sem-effect-shadow-<x>          → --shadow-<x>
+ * - --qw-sem-motion-easing-<x>          → --ease-<x>
+ *
+ * 其余子族（size 的 control-height/icon 等、typography 角色组、motion duration）
+ * 无对应 Tailwind 主题命名空间，不映射，消费方直接用 var(--qw-sem-*)。
+ * effect 的 shadow-<x>-color 是复合阴影的颜色通道，不是 box-shadow 值，同样不映射。
+ */
+/**
+ * 从 derive() 的 flat 变量映射（light 即可——变量名亮暗一致）挑出可映射的
+ * T3 token，产出 Tailwind @theme 变量 → `var(--qw-sem-*)` 引用表。
+ */
+export declare function tailwindThemeVars(flat: Record<string, string>): Record<string, string>;
+/** 组装 dist/tailwind.css 文本（消费方需先引入 tokens.css 提供 --qw-sem-* 取值）。 */
+export declare function buildTailwindCss(flat: Record<string, string>): string;

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

@@ -5,9 +5,10 @@ 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 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";