@qw-ui/tokens 0.1.0 → 0.2.0

package/dist/design-doc.d.ts

@@ -0,0 +1,10 @@
+type Json = Record<string, unknown>;
+/** 生成 design/reference.tokens.json 的完整 JSON 对象。 */
+export declare function buildReferenceDesignDoc(): Json;
+/** 生成 design/semantic.tokens.json（mode 无关的结构角色）。 */
+export declare function buildSemanticDesignDoc(): Json;
+/** 生成 design/semantic.color.tokens.json（light/dark 合并视图）。 */
+export declare function buildSemanticColorDesignDoc(): Json;
+/** 三份生成文件的文件名 → 生成器映射，供导出脚本与 parity 测试共用。 */
+export declare const GENERATED_DESIGN_DOCS: Record<string, () => Json>;
+export {};

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

@@ -0,0 +1,14 @@
+export { FIGMA_COLOR_COLLECTION, FIGMA_COLOR_PREFIX, T1_COLOR_KEYS, T2_OKLCH_STEPS } from "../color-architecture.js";
+export declare const T2_ALPHA_STEPS: ["a5", "a10", "a20", "a30", "a40", "a50", "a60", "a70", "a80", "a90", "a100"];
+export declare const T2_OKLCH_STEP_KEYS: string[];
+export interface FigmaColorTokenValidationResult {
+    ok: boolean;
+    errors: string[];
+    counts: {
+        t1: number;
+        t2: number;
+        t3: number;
+    };
+}
+export declare function validateFigmaColorTokens(doc: unknown): FigmaColorTokenValidationResult;
+export declare function assertFigmaColorTokens(doc: unknown): void;

package/dist/index.d.ts

@@ -1,624 +1,13 @@
-import { z } from 'zod';
-
-/**
- * SeedSchema — T1 Seed 的唯一事实源校验（RFC 0001 §2.1，v3 修订）。
- *
- * 五大类目 color/size/typography/motion/effect，字段结构对齐
- * packages/tokens/design/seed.tokens.json，全部字段必填——不允许省略后静默
- * 回退默认值，锚点缺口必须在 Seed 层显式补齐，Reference 层不得用硬编码兜底。
- *
- * v3 变化：
- * - 颜色全部结构化（DTCG Color module，支持 srgb/oklch）。
- * - radius/controlSize/iconSize 只留 base 锚点（full 是独立的裁切基准决策），
- *   sm/lg 由 Reference 层按既定公式派生。
- * - lineHeight 从 size 移入 typography；新增 letterSpacing.base 锚点。
- * - fontFamily 换 text/number/code 三族 + 平台/语言变体（textMacXx、textWindowsXx）。
- */
-declare const SeedSchema: z.ZodObject<{
-    color: z.ZodObject<{
-        brand: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        black: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        white: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        gray: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        red: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        orange: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        yellow: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        green: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        cyan: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        blue: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        purple: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-        brown: z.ZodObject<{
-            colorSpace: z.ZodEnum<{
-                srgb: "srgb";
-                oklch: "oklch";
-            }>;
-            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-            alpha: z.ZodNumber;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    size: z.ZodObject<{
-        spacing: z.ZodObject<{
-            step: z.ZodString;
-        }, z.core.$strip>;
-        borderWidth: z.ZodObject<{
-            hairline: z.ZodString;
-        }, z.core.$strip>;
-        radius: z.ZodObject<{
-            base: z.ZodString;
-            full: z.ZodString;
-        }, z.core.$strip>;
-        controlSize: z.ZodObject<{
-            base: z.ZodString;
-        }, z.core.$strip>;
-        iconSize: z.ZodObject<{
-            base: z.ZodString;
-        }, z.core.$strip>;
-        opacity: z.ZodObject<{
-            disabled: z.ZodNumber;
-            alphaStep: z.ZodNumber;
-        }, z.core.$strip>;
-        zIndex: z.ZodObject<{
-            step: z.ZodNumber;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    typography: z.ZodObject<{
-        fontFamily: z.ZodObject<{
-            text: z.ZodArray<z.ZodString>;
-            number: z.ZodArray<z.ZodString>;
-            code: z.ZodArray<z.ZodString>;
-            textMacLatin: z.ZodArray<z.ZodString>;
-            textMacZh: z.ZodArray<z.ZodString>;
-            textMacJa: z.ZodArray<z.ZodString>;
-            textWindowsLatin: z.ZodArray<z.ZodString>;
-            textWindowsZh: z.ZodArray<z.ZodString>;
-            textWindowsJa: z.ZodArray<z.ZodString>;
-        }, z.core.$strip>;
-        fontWeight: z.ZodObject<{
-            regular: z.ZodNumber;
-            medium: z.ZodNumber;
-            semibold: z.ZodNumber;
-        }, z.core.$strip>;
-        fontSize: z.ZodObject<{
-            base: z.ZodString;
-        }, z.core.$strip>;
-        lineHeight: z.ZodObject<{
-            base: z.ZodNumber;
-        }, z.core.$strip>;
-        letterSpacing: z.ZodObject<{
-            base: z.ZodString;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    motion: z.ZodObject<{
-        duration: z.ZodObject<{
-            base: z.ZodString;
-        }, z.core.$strip>;
-        easing: z.ZodObject<{
-            standard: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-    effect: z.ZodObject<{
-        shadow: z.ZodObject<{
-            base: z.ZodObject<{
-                color: z.ZodObject<{
-                    colorSpace: z.ZodEnum<{
-                        srgb: "srgb";
-                        oklch: "oklch";
-                    }>;
-                    components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
-                    alpha: z.ZodNumber;
-                }, z.core.$strip>;
-                offsetX: z.ZodString;
-                offsetY: z.ZodString;
-                blur: z.ZodString;
-                spread: z.ZodString;
-            }, z.core.$strip>;
-        }, z.core.$strip>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-type SeedInput = z.input<typeof SeedSchema>;
-type Seed = z.infer<typeof SeedSchema>;
-/**
- * validateSeed — ConfigProvider 在 dev 模式调用；生产环境可裁掉，不带 zod 体积。
- * 解析失败抛错，错误信息直接定位到字段。
- */
-declare function validateSeed(seed: unknown): Seed;
-
-declare const defaultSeed: Seed;
-
-/**
- * SeedColorValue — DTCG Color module 结构化颜色（design-tokens.org 2025.10）。
- * Seed 层颜色不再用十六进制字符串：结构化后输出 Web / iOS / Android / Figma
- * 插件 / 文档都更稳定，且支持 oklch 等更高级色彩空间直接作为设计输入。
- *
- * - srgb：components = [r, g, b]，各分量 0–1（不是 0–255）。
- * - oklch：components = [l, c, h]（l 0–1、c ≥0、h 角度）。
- */
-interface SeedColorValue {
-    colorSpace: "srgb" | "oklch";
-    components: [number, number, number];
-    alpha: number;
-}
-/** 十六进制（#rgb / #rrggbb）→ 结构化 srgb SeedColorValue。编辑器色板输入的桥。 */
-declare function hexToSeedColor(hex: string): SeedColorValue;
-/** 结构化颜色 → #rrggbb（丢 alpha；oklch 会先转 sRGB）。展示/对比度计算用。 */
-declare function seedColorToHex(c: SeedColorValue): string;
-/**
- * 结构化颜色 → CSS 颜色字符串。srgb 且不透明输出 hex；srgb 半透明输出
- * `rgb(r g b / a)`；oklch 保持原生 `oklch(l c h / a)`（relative color 派生保真）。
- */
-declare function seedColorToCss(c: SeedColorValue): string;
-
-declare const FIGMA_COLOR_COLLECTION = "Color";
-declare const FIGMA_COLOR_PREFIX = "qw";
-declare const T1_COLOR_KEYS: readonly ["brand", "black", "white", "gray", "red", "orange", "yellow", "green", "cyan", "blue", "purple", "brown"];
-type T1ColorKey = (typeof T1_COLOR_KEYS)[number];
-declare const FIGMA_T1_SEED_HEX: Record<T1ColorKey, string>;
-declare const T2_ALPHA_STEPS: readonly [5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
-declare const T2_ALPHA_KEYS: ["a5", "a10", "a20", "a30", "a40", "a50", "a60", "a70", "a80", "a90", "a100"];
-type T2AlphaStep = (typeof T2_ALPHA_STEPS)[number];
-type T2AlphaKey = (typeof T2_ALPHA_KEYS)[number];
-declare const T2_OKLCH_STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
-type T2OklchStep = (typeof T2_OKLCH_STEPS)[number];
-declare const FIGMA_T2_SOLID_SCALE: Record<T1ColorKey, Record<T2OklchStep, string>>;
-declare const FIGMA_T3_COLOR_ROLES: {
-    readonly "surface.base": {
-        readonly light: "color.white.base";
-        readonly dark: "color.black.base";
-    };
-    readonly "surface.subtle": {
-        readonly light: "color.gray.50";
-        readonly dark: "color.gray.900";
-    };
-    readonly "surface.elevated": {
-        readonly light: "color.white.base";
-        readonly dark: "color.gray.800";
-    };
-    readonly "surface.header": {
-        readonly light: "color.gray.100";
-        readonly dark: "color.gray.700";
-    };
-    readonly "surface.brand-subtle": {
-        readonly light: "color.blue.50";
-        readonly dark: "color.blue.800";
-    };
-    readonly "content.primary": {
-        readonly light: "color.black.base";
-        readonly dark: "color.white.base";
-    };
-    readonly "content.secondary": {
-        readonly light: "color.gray.600";
-        readonly dark: "color.gray.base";
-    };
-    readonly "content.tertiary": {
-        readonly light: "color.gray.base";
-        readonly dark: "color.gray.600";
-    };
-    readonly "content.placeholder": {
-        readonly light: "color.gray.300";
-        readonly dark: "color.white.a30";
-    };
-    readonly "content.intro": {
-        readonly light: "color.gray.400";
-        readonly dark: "color.gray.500";
-    };
-    readonly "border.default": {
-        readonly light: "color.gray.100";
-        readonly dark: "color.gray.700";
-    };
-    readonly "border.strong": {
-        readonly light: "color.gray.300";
-        readonly dark: "color.gray.600";
-    };
-    readonly "border.focus": {
-        readonly light: "color.brand.base";
-        readonly dark: "color.brand.500";
-    };
-    readonly "fill.subtle": {
-        readonly light: "color.gray.50";
-        readonly dark: "color.white.a20";
-    };
-    readonly "fill.hover": {
-        readonly light: "color.gray.100";
-        readonly dark: "color.gray.800";
-    };
-    readonly "fill.active": {
-        readonly light: "color.blue.50";
-        readonly dark: "color.blue.800";
-    };
-    readonly "fill.disabled": {
-        readonly light: "color.gray.50";
-        readonly dark: "color.gray.900";
-    };
-    readonly "action.brand": {
-        readonly light: "color.brand.base";
-        readonly dark: "color.brand.500";
-    };
-    readonly "action.product": {
-        readonly light: "color.blue.base";
-        readonly dark: "color.blue.600";
-    };
-    readonly "action.selected": {
-        readonly light: "color.blue.a20";
-        readonly dark: "color.blue.a40";
-    };
-    readonly "action.inverse": {
-        readonly light: "color.white.base";
-        readonly dark: "color.black.base";
-    };
-    readonly "status.success": {
-        readonly light: "color.green.base";
-        readonly dark: "color.green.base";
-    };
-    readonly "status.warning": {
-        readonly light: "color.yellow.base";
-        readonly dark: "color.yellow.base";
-    };
-    readonly "status.danger": {
-        readonly light: "color.red.400";
-        readonly dark: "color.red.400";
-    };
-    readonly "status.info": {
-        readonly light: "color.blue.base";
-        readonly dark: "color.blue.600";
-    };
-    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";
-    };
-};
-
-/**
- * T1/T2/T3 token 的 CSS 变量命名：`--qw-{layer}-{kebab(path)}`。
- *
- * `layer` 区分 Seed（"seed"，仅出现在 live CSS 产物里、供响应式级联的锚点变量）、
- * Reference（"ref"，原子层，组件禁止直接引用）与 Semantic（"sem"，组件唯一
- * 合法消费入口）。`path` 的每个 segment 是内部 TS 属性名（天然 camelCase，
- * 如 "brandSubtle"/"controlSize"），命名前需转成 kebab-case 才能对齐
- * packages/tokens/design/*.tokens.json 里锁定的 cssVar 字符串。
- *
- * 例：toVar("sem", ["color","surface","brandSubtle"]) → "--qw-sem-color-surface-brand-subtle"
- *     toVar("sem", ["size","controlHeight","sm"]) → "--qw-sem-size-control-height-sm"
- *     toVar("seed", ["color","brand"]) → "--qw-seed-color-brand"
- *
- * 这是唯一命名口子，运行时 flat var map、build-tokens.ts 的 CSS 出口与
- * live CSS 生成器共用。
- */
-type Layer = "seed" | "ref" | "sem";
-declare function toVar(layer: Layer, path: string[]): string;
-
-/** 10 档 token: 50 / 100 / 200 / ... / 900 */
-declare const STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
-type Step = (typeof STEPS)[number];
-/**
- * OKLCH L 目标曲线 — 感知均匀的亮度阶梯 (0..1)。
- * 50 最亮 → 900 最暗；端点 0.972 / 0.18 避免纯白纯黑导致对比"塌"。
- * (替换原 HSV：HSV 在感知上不均匀，深档发灰/浅档发白，WCAG 易不过。)
- *
- * 导出供 live-css 生成器复用：CSS relative color 语法
- * `oklch(from var(--seed) L calc(c * f) h)` 的 L/f 常量与这里同源。
- */
-declare const L_TARGETS: Record<Step, number>;
-type Ramp = Record<Step, string>;
-/**
- * 给一个 seed 颜色（结构化 SeedColorValue 或 CSS 颜色字符串），算 10 阶 ramp。
- * L 走目标曲线，hue 固定，chroma 端点衰减后再 clampChroma 收进 sRGB 色域。
- */
-declare function ramp(seedColor: SeedColorValue | string): Ramp;
-/** WCAG 对比度 (1..21)。 */
-declare function contrastRatio(fg: string, bg: string): number;
-
-/**
- * T2 Reference（Primitive）派生 —— RFC 0001 §2.1，v3 声明式重构。
- *
- * v3 核心变化：每条 Reference token 的派生规则不再是不透明的 `(seed) => string`
- * 函数，而是可机器读取的 `Derivation` AST——同一份 AST 同时驱动：
- * 1. 运行时求值（evaluateDerivation → tokens）；
- * 2. DTCG design 文件生成（scripts/export-design-tokens.ts，$value 全部结构化引用）；
- * 3. live CSS 生成（derive/live-css.ts，relative color / calc 表达式）；
- * 4. Token Studio 的派生公式展示（formatDerivation）。
- *
- * `seedRefs` 由 AST 自动推导（seedRefsOf），不再手写；可追溯性校验
- * （derive/reference.test.ts）遍历 recipes 断言 seedRefs 非空。
- * 颜色层对齐 Figma `Color/qw` 变量集合：
- * - T1 Seed 为 12 个单色种子；
- * - T2 Reference 为每个 seed 的 A5-A100 Alpha 通道、50-900 OKLCH 设计校准实色色阶、base 引用。
- */
-type ShadowLevel = "sm" | "md" | "lg";
-type Derivation = 
-/** 直通引用 Seed 字段（dimension/number/duration 字符串或数字）。 */
-{
-    kind: "alias";
-    seedRef: string;
-}
-/** dimension 字符串 × factor；round:"int" 时四舍五入为整数（字号档位用）。 */
- | {
-    kind: "scale";
-    seedRef: string;
-    factor: number;
-    round?: "int";
-}
-/** 无单位数字 × factor（zIndex 刻度）。 */
- | {
-    kind: "scaleNumber";
-    seedRef: string;
-    factor: number;
-}
-/** 无单位数字 + delta（lineHeight tight/relaxed = base ∓ 0.25）。 */
- | {
-    kind: "offsetNumber";
-    seedRef: string;
-    delta: number;
-}
-/** dimension + 另一 dimension × n（controlSize/iconSize sm/lg = base ∓ spacing.step × n）。 */
- | {
-    kind: "offsetSteps";
-    seedRef: string;
-    stepRef: string;
-    n: number;
-}
-/** OKLCH 感知均匀色阶（L 曲线 + chroma 端点衰减，算法见 oklch.ts）。 */
- | {
-    kind: "oklchRamp";
-    seedRef: string;
-    step: Step;
-}
-/** Figma 校准后的 OKLCH 实色色阶；血缘仍指向 T1 seed，但数值由设计稿拍板。 */
- | {
-    kind: "figmaOklchScale";
-    seedRef: string;
-    step: T2OklchStep;
-    value: string;
-}
-/** T1 seed 颜色的固定 Alpha 通道。 */
- | {
-    kind: "seedAlpha";
-    seedRef: string;
-    alpha: number;
-}
-/** 旧版纯黑/纯白透明度工具刻度。保留求值器兼容，不再由 T2 主链路生成。 */
- | {
-    kind: "alphaScale";
-    channel: "black" | "white";
-    stepRef: string;
-    multiplier: number;
-}
-/** 字体栈（string[] → CSS font-family 列表）。 */
- | {
-    kind: "fontStack";
-    seedRef: string;
-}
-/** cubic-bezier 四元组 → CSS 函数。 */
- | {
-    kind: "cubicBezier";
-    seedRef: string;
-}
-/** 白名单字面量（色彩空间数学端点，非设计决策）。 */
- | {
-    kind: "literal";
-    value: string;
-}
-/** 阴影档位：形状 = shadow.base × 档位比例，颜色 = alphaStep × 档位倍数。 */
- | {
-    kind: "shadowLayer";
-    level: ShadowLevel;
-};
-interface ReferenceRecipe {
-    path: string[];
-    cssVar: string;
-    /** 由 derivation 自动推导的 Seed 依赖（点分路径），供可追溯性校验与血缘展示。 */
-    seedRefs: string[];
-    derivation: Derivation;
-}
-/** 拍平后的 CSS 变量映射：cssVar → 字符串值（--qw-ref-* 全集）。 */
-type ReferenceTokens = Record<string, string>;
-/** 阴影形状（不含颜色），供 Semantic 层复合 effect.shadow.* 时引用固定形状字段。 */
-interface ShadowShape {
-    offsetX: string;
-    offsetY: string;
-    blur: string;
-    spread: string;
-}
-interface ReferenceBuild {
-    recipes: ReferenceRecipe[];
-    tokens: ReferenceTokens;
-    shapes: {
-        shadow: {
-            sm: ShadowShape;
-            md: ShadowShape;
-            lg: ShadowShape;
-        };
-    };
-}
-/** 按点分路径读 Seed 字段（"size.spacing.step" → seed.size.spacing.step）。 */
-declare function seedValueAt(seed: Seed, dotted: string): unknown;
-/** 求值：一条 Derivation + Seed → 最终 CSS 值字符串。 */
-declare function evaluateDerivation(d: Derivation, seed: Seed): string;
-/** Seed 依赖推导：AST 里出现的全部 Seed 点分路径。 */
-declare function seedRefsOf(d: Derivation): string[];
-/** 人读派生公式（Token Studio 展示用）。 */
-declare function formatDerivation(d: Derivation): string;
-declare const RAMP_COLORS: readonly ["brand", "black", "white", "gray", "red", "orange", "yellow", "green", "cyan", "blue", "purple", "brown"];
-declare function allReferenceRecipes(): ReferenceRecipe[];
-/** T2 顶层入口：喂一个 Seed，产出全量 Reference recipes + 拍平后的 CSS 变量映射 + 阴影形状（供 Semantic 层消费）。 */
-declare function buildReference(seed: Seed): ReferenceBuild;
-
-/**
- * T3 Semantic 派生 —— RFC 0001 §2.1，v3 修订。
- *
- * R7 类型隔离（强制 FR-010）：本模块**不 import `Seed`/`schema.ts`** 任何符号，
- * 只接受 `buildReference()` 的输出（`ReferenceBuild`）。Semantic 角色永远经由
- * Reference 层中转到 Seed，不允许绕过 Reference 直接引用 Seed 字段。
- *
- * v3 变化：全部角色表从模块私有改为导出的结构化元数据（SEMANTIC_ROLES），
- * 供 design 文件生成器（scripts/export-design-tokens.ts）、live CSS 生成器
- * （derive/live-css.ts）与 Token Studio 的血缘展示共用同一份事实。
- */
-type SemanticMode = "light" | "dark";
-interface TypographyRole {
-    fontFamilyRef: string;
-    fontSizeRef: string;
-    fontWeightRef: string;
-    lineHeightRef: string;
-    letterSpacingRef: string;
-}
-/** typography.* 复合角色：每个字段各自引用 Reference（无任何裸字面量）。 */
-declare const TYPOGRAPHY_ROLES: Record<string, TypographyRole>;
-interface ColorRoleRefs {
-    light: string;
-    dark: string;
-}
-declare const COLOR_ROLES: Record<string, ColorRoleRefs>;
-declare const SHADOW_COMPOSITE_ROLES: Record<string, ShadowLevel>;
-type SemanticRoleEntry = {
-    kind: "structural";
-    /** Semantic 路径（点分，如 "size.radius.control"）。 */
-    path: string;
-    cssVar: string;
-    /** 引用的 Reference 路径（点分）。 */
-    refPath: string;
-} | {
-    kind: "color";
-    path: string;
-    cssVar: string;
-    refPath: {
-        light: string;
-        dark: string;
-    };
-} | {
-    kind: "shadowComposite";
-    path: string;
-    cssVar: string;
-    /** 形状来源（reference.effect.shadow.<level>）+ 颜色来源。 */
-    shapeRef: string;
-    colorRole: string;
-};
-/**
- * 全量 Semantic 角色的结构化血缘表——"角色 → 引用的 Reference 路径（含 light/dark 分支）"。
- * 与 buildSemanticStructural/buildSemanticColor 的产出一一对应（顺序一致）。
- */
-declare function semanticRoleEntries(): SemanticRoleEntry[];
-/**
- * 结构类（mode 无关）：尺寸角色 + 字体族角色 + 排版复合角色 + 动效时长/缓动。
- * `effect.shadow.*` 的颜色字段随 mode 变化，归入 `buildSemanticColor`。
- */
-declare function buildSemanticStructural(reference: ReferenceBuild): Record<string, string>;
-/**
- * 颜色类（light/dark 分别求值）：color.* 全部角色。
- */
-declare function buildSemanticColor(reference: ReferenceBuild, mode: SemanticMode): Record<string, string>;
-
-interface DerivedTokens {
-    /** 亮色全量 CSS 变量：--qw-ref-* ∪ --qw-sem-*（light 取值）。 */
-    light: Record<string, string>;
-    /** 暗色全量 CSS 变量：--qw-ref-* ∪ --qw-sem-*（dark 取值）。 */
-    dark: Record<string, string>;
-}
-/**
- * derive — 单源派生（RFC 0001）。喂一个 Seed，编排 T2 Reference → T3 Semantic，
- * 返回亮/暗两套全量 CSS 变量映射（含 --qw-ref-* 与 --qw-sem-*）。
- * 外部签名/返回值形状与改造前保持一致（FR-014），供 `@qw-ui/react`、`@qw-ui/vue` 的
- * ConfigProvider 直接消费，无需改动。
- *
- * 注意：`validateSeed` 不在此处调用（沿用现状契约），校验是调用方的责任。
- */
-declare function derive(seed: Seed): DerivedTokens;
-
-/** Seed 拍平成 `--qw-seed-*` → CSS 值。live CSS 里唯一携带具体数值的层。 */
-declare function seedCssVars(seed: Seed): Record<string, string>;
-/** 一条 Derivation → 引用 `--qw-seed-*` 的 CSS 原生表达式。 */
-declare function derivationToCssExpr(d: Derivation): string;
-interface LiveCssOptions {
-    /** 亮色作用域选择器，默认 ":root"。 */
-    selector?: string;
-    /** 暗色作用域选择器，默认 '[data-qw-mode="dark"]'。 */
-    darkSelector?: string;
-}
-/**
- * 生成整份 live CSS：
- * 1. seed 块（具体数值）；2. ref 块（表达式派生）；3. sem 块（light 别名）；
- * 4. dark 块（仅重映射随 mode 变化的 sem 颜色别名）。
- */
-declare function buildLiveCss(seed: Seed, options?: LiveCssOptions): string;
-
-export { COLOR_ROLES, type ColorRoleRefs, type Derivation, type DerivedTokens, FIGMA_COLOR_COLLECTION, FIGMA_COLOR_PREFIX, FIGMA_T1_SEED_HEX, FIGMA_T2_SOLID_SCALE, FIGMA_T3_COLOR_ROLES, L_TARGETS, type Layer, type LiveCssOptions, type SemanticMode as Mode, RAMP_COLORS, type Ramp, type ReferenceBuild, type ReferenceRecipe, type ReferenceTokens, SHADOW_COMPOSITE_ROLES, STEPS, type Seed, type SeedColorValue, type SeedInput, SeedSchema, type SemanticRoleEntry, type Step, type T1ColorKey, T1_COLOR_KEYS, type T2AlphaKey, type T2AlphaStep, type T2OklchStep, T2_ALPHA_KEYS, T2_ALPHA_STEPS, T2_OKLCH_STEPS, TYPOGRAPHY_ROLES, allReferenceRecipes, buildLiveCss, buildReference, buildSemanticColor, buildSemanticStructural, contrastRatio, defaultSeed, derivationToCssExpr, derive, evaluateDerivation, formatDerivation, hexToSeedColor, ramp, seedColorToCss, seedColorToHex, seedCssVars, seedRefsOf, seedValueAt, semanticRoleEntries, toVar, validateSeed };
+export { defaultSeed } from "./seed/index.js";
+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 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 { 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";