@qw-ui/tokens 0.1.0 → 0.2.0

package/dist/color-architecture.d.ts

@@ -0,0 +1,122 @@
+export declare const FIGMA_COLOR_COLLECTION = "Color";
+export declare const FIGMA_COLOR_PREFIX = "qw";
+export declare const T1_COLOR_KEYS: readonly ["brand", "black", "white", "gray", "red", "orange", "yellow", "green", "cyan", "blue", "purple", "brown"];
+export type T1ColorKey = (typeof T1_COLOR_KEYS)[number];
+export declare const FIGMA_T1_SEED_HEX: Record<T1ColorKey, string>;
+export declare const T2_ALPHA_STEPS: readonly [5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
+export declare const T2_ALPHA_KEYS: ["a5", "a10", "a20", "a30", "a40", "a50", "a60", "a70", "a80", "a90", "a100"];
+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];
+export declare const FIGMA_T2_SOLID_SCALE: Record<T1ColorKey, Record<T2OklchStep, string>>;
+export 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";
+    };
+};

package/dist/color.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 角度）。
+ */
+export interface SeedColorValue {
+    colorSpace: "srgb" | "oklch";
+    components: [number, number, number];
+    alpha: number;
+}
+type CuloriColor = {
+    mode: "rgb";
+    r: number;
+    g: number;
+    b: number;
+    alpha?: number;
+} | {
+    mode: "oklch";
+    l: number;
+    c: number;
+    h: number;
+    alpha?: number;
+};
+/** SeedColorValue → culori 可消费的颜色对象。 */
+export declare function toCulori(c: SeedColorValue): CuloriColor;
+/** 十六进制（#rgb / #rrggbb）→ 结构化 srgb SeedColorValue。编辑器色板输入的桥。 */
+export declare function hexToSeedColor(hex: string): SeedColorValue;
+/** 结构化颜色 → #rrggbb（丢 alpha；oklch 会先转 sRGB）。展示/对比度计算用。 */
+export declare function seedColorToHex(c: SeedColorValue): string;
+/**
+ * 结构化颜色 → CSS 颜色字符串。srgb 且不透明输出 hex；srgb 半透明输出
+ * `rgb(r g b / a)`；oklch 保持原生 `oklch(l c h / a)`（relative color 派生保真）。
+ */
+export declare function seedColorToCss(c: SeedColorValue): string;
+export {};

package/dist/compat/build.d.ts

@@ -0,0 +1,14 @@
+import { type CompatEntry, type CompatRegistry } from "./schema.js";
+export interface CompatBuild {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+    /** path → cssVar */
+    paths: Record<string, string>;
+    /** component → suffix[] */
+    byComponent: Record<string, string[]>;
+    entries: CompatEntry[];
+    graceDays: number;
+}
+export declare function buildCompatFromRegistry(registry: CompatRegistry): CompatBuild;
+/** 生成 compat token-paths TypeScript 片段（并入 tokens.ts） */
+export declare function formatCompatTypes(build: CompatBuild): string;

package/dist/compat/color.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 将 legacy hex（含 /NN% 透明度后缀）或 DTCG srgb 结构转为 CSS 颜色字符串。
+ */
+export declare function compatColorToCss(input: string | {
+    colorSpace: "srgb";
+    components: [number, number, number];
+    alpha: number;
+}): string;

package/dist/compat/index.d.ts

@@ -0,0 +1,5 @@
+export { compatRegistrySchema, compatEntrySchema, compatPathToCssVar, compatComponentOf, compatSuffixOf, } from "./schema.js";
+export type { CompatEntry, CompatRegistry, CompatStatus } from "./schema.js";
+export { compatColorToCss } from "./color.js";
+export { buildCompatFromRegistry, formatCompatTypes, } from "./build.js";
+export type { CompatBuild } from "./build.js";

package/dist/compat/schema.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+export declare const compatStatusSchema: z.ZodEnum<{
+    active: "active";
+    aliased: "aliased";
+    deprecated: "deprecated";
+}>;
+export declare const compatEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    type: z.ZodEnum<{
+        color: "color";
+        dimension: "dimension";
+        motion: "motion";
+        typography: "typography";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodObject<{
+        light: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            colorSpace: z.ZodLiteral<"srgb">;
+            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            alpha: z.ZodNumber;
+        }, z.core.$strip>, z.ZodString]>;
+        dark: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            colorSpace: z.ZodLiteral<"srgb">;
+            components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+            alpha: z.ZodNumber;
+        }, z.core.$strip>, z.ZodString]>;
+    }, z.core.$strip>, z.ZodObject<{
+        value: z.ZodNumber;
+        unit: z.ZodEnum<{
+            "%": "%";
+            em: "em";
+            px: "px";
+            rem: "rem";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        aliasOf: z.ZodString;
+    }, z.core.$strip>]>;
+    source: z.ZodObject<{
+        figma: z.ZodString;
+        nodeId: z.ZodString;
+        legacyName: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    introducedBy: z.ZodString;
+    reason: z.ZodString;
+    owner: z.ZodString;
+    targetSemanticRole: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        active: "active";
+        aliased: "aliased";
+        deprecated: "deprecated";
+    }>;
+    reviewAfter: z.ZodString;
+    migrationIssue: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const compatRegistrySchema: z.ZodObject<{
+    $description: z.ZodOptional<z.ZodString>;
+    version: z.ZodLiteral<1>;
+    graceDays: z.ZodDefault<z.ZodNumber>;
+    entries: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        type: z.ZodEnum<{
+            color: "color";
+            dimension: "dimension";
+            motion: "motion";
+            typography: "typography";
+        }>;
+        value: z.ZodUnion<readonly [z.ZodObject<{
+            light: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                colorSpace: z.ZodLiteral<"srgb">;
+                components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                alpha: z.ZodNumber;
+            }, z.core.$strip>, z.ZodString]>;
+            dark: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                colorSpace: z.ZodLiteral<"srgb">;
+                components: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+                alpha: z.ZodNumber;
+            }, z.core.$strip>, z.ZodString]>;
+        }, z.core.$strip>, z.ZodObject<{
+            value: z.ZodNumber;
+            unit: z.ZodEnum<{
+                "%": "%";
+                em: "em";
+                px: "px";
+                rem: "rem";
+            }>;
+        }, z.core.$strip>, z.ZodObject<{
+            aliasOf: z.ZodString;
+        }, z.core.$strip>]>;
+        source: z.ZodObject<{
+            figma: z.ZodString;
+            nodeId: z.ZodString;
+            legacyName: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        introducedBy: z.ZodString;
+        reason: z.ZodString;
+        owner: z.ZodString;
+        targetSemanticRole: z.ZodNullable<z.ZodString>;
+        status: z.ZodEnum<{
+            active: "active";
+            aliased: "aliased";
+            deprecated: "deprecated";
+        }>;
+        reviewAfter: z.ZodString;
+        migrationIssue: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CompatEntry = z.infer<typeof compatEntrySchema>;
+export type CompatRegistry = z.infer<typeof compatRegistrySchema>;
+export type CompatStatus = z.infer<typeof compatStatusSchema>;
+/** path → CSS 变量名：`button.color.bg-soft-brand` → `--qw-compat-button-color-bg-soft-brand` */
+export declare function compatPathToCssVar(path: string): string;
+/** path → component slug（第一段） */
+export declare function compatComponentOf(path: string): string;
+/** path → helper suffix（component 之后的段，用 `-` 连接） */
+export declare function compatSuffixOf(path: string): string;

package/dist/derive/index.d.ts

@@ -0,0 +1,25 @@
+import type { Seed } from "../schema.js";
+export { toVar } from "./naming.js";
+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 { SemanticRoleEntry, ColorRoleRefs, TypographyRole } from "./semantic.js";
+export 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` 不在此处调用（沿用现状契约），校验是调用方的责任。
+ */
+export declare function derive(seed: Seed): DerivedTokens;

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

@@ -0,0 +1,18 @@
+import { type Derivation } from "./reference.js";
+import type { Seed } from "../schema.js";
+/** Seed 拍平成 `--qw-seed-*` → CSS 值。live CSS 里唯一携带具体数值的层。 */
+export declare function seedCssVars(seed: Seed): Record<string, string>;
+/** 一条 Derivation → 引用 `--qw-seed-*` 的 CSS 原生表达式。 */
+export declare function derivationToCssExpr(d: Derivation): string;
+export interface LiveCssOptions {
+    /** 亮色作用域选择器，默认 ":root"。 */
+    selector?: string;
+    /** 暗色作用域选择器，默认 '[data-qw-mode="dark"]'。 */
+    darkSelector?: string;
+}
+/**
+ * 生成整份 live CSS：
+ * 1. seed 块（具体数值）；2. ref 块（表达式派生）；3. sem 块（light 别名）；
+ * 4. dark 块（仅重映射随 mode 变化的 sem 颜色别名）。
+ */
+export declare function buildLiveCss(seed: Seed, options?: LiveCssOptions): string;

package/dist/derive/naming.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 生成器共用。
+ */
+export type Layer = "seed" | "ref" | "sem";
+export declare function toVar(layer: Layer, path: string[]): string;

package/dist/derive/oklch.d.ts

@@ -0,0 +1,28 @@
+import { type SeedColorValue } from "../color.js";
+/** 10 档 token: 50 / 100 / 200 / ... / 900 */
+export declare const STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+export 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 常量与这里同源。
+ */
+export declare const L_TARGETS: Record<Step, number>;
+/**
+ * chroma 端点衰减 — 在 L 的亮/暗两端轻微衰减 chroma，避免 out-of-gamut；
+ * 中段 (L≈0.6) 保留全 chroma。
+ */
+export declare function chromaFactor(l: number): number;
+export type Ramp = Record<Step, string>;
+/**
+ * 给一个 seed 颜色（结构化 SeedColorValue 或 CSS 颜色字符串），算 10 阶 ramp。
+ * L 走目标曲线，hue 固定，chroma 端点衰减后再 clampChroma 收进 sRGB 色域。
+ */
+export declare function ramp(seedColor: SeedColorValue | string): Ramp;
+/** 相对亮度 (WCAG) — 用于对偶/校验时的对比度判断。 */
+export declare function relativeLuminance(hex: string): number;
+/** WCAG 对比度 (1..21)。 */
+export declare function contrastRatio(fg: string, bg: string): number;

package/dist/derive/reference.d.ts

@@ -0,0 +1,189 @@
+import { type Step } from "./oklch.js";
+import { type T2OklchStep } from "../color-architecture.js";
+import type { Seed } from "../schema.js";
+/**
+ * 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 引用。
+ */
+export type ShadowLevel = "sm" | "md" | "lg";
+export 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;
+};
+export interface ReferenceRecipe {
+    path: string[];
+    cssVar: string;
+    /** 由 derivation 自动推导的 Seed 依赖（点分路径），供可追溯性校验与血缘展示。 */
+    seedRefs: string[];
+    derivation: Derivation;
+}
+/** 拍平后的 CSS 变量映射：cssVar → 字符串值（--qw-ref-* 全集）。 */
+export type ReferenceTokens = Record<string, string>;
+/** 阴影形状（不含颜色），供 Semantic 层复合 effect.shadow.* 时引用固定形状字段。 */
+export interface ShadowShape {
+    offsetX: string;
+    offsetY: string;
+    blur: string;
+    spread: string;
+}
+export interface ReferenceBuild {
+    recipes: ReferenceRecipe[];
+    tokens: ReferenceTokens;
+    shapes: {
+        shadow: {
+            sm: ShadowShape;
+            md: ShadowShape;
+            lg: ShadowShape;
+        };
+    };
+}
+/** 按点分路径读 Seed 字段（"size.spacing.step" → seed.size.spacing.step）。 */
+export declare function seedValueAt(seed: Seed, dotted: string): unknown;
+export declare function formatFontFamily(list: string[]): string;
+/** 阴影档位系数：形状（offset/blur/spread 缩放）+ 颜色（alphaStep 倍数）。 */
+export declare const SHADOW_LEVELS: Record<ShadowLevel, {
+    offset: number;
+    blur: number;
+    alphaMult: number;
+}>;
+/** 求值：一条 Derivation + Seed → 最终 CSS 值字符串。 */
+export declare function evaluateDerivation(d: Derivation, seed: Seed): string;
+/** Seed 依赖推导：AST 里出现的全部 Seed 点分路径。 */
+export declare function seedRefsOf(d: Derivation): string[];
+/** 人读派生公式（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[];
+/** @deprecated Figma T2 已不再使用 neutral 0/1000 端点；保留给历史迁移脚本。 */
+export declare function buildNeutralEndpointRecipes(): ReferenceRecipe[];
+export declare const BLACK_ALPHA: ReadonlyArray<readonly [string, number]>;
+export declare const WHITE_ALPHA: ReadonlyArray<readonly [string, number]>;
+/** @deprecated Figma T2 已改为每个 Seed 自带 Alpha 通道；保留给历史迁移脚本。 */
+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）。 */
+export declare const RADIUS_FACTORS: {
+    readonly sm: 0.5;
+    readonly md: 1;
+    readonly lg: 1.75;
+};
+/** 5. 圆角刻度：sm/md/lg 由 radius.base 按系数派生，full 直通独立裁切基准。 */
+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[];
+/** 8. 行高（typography 类目）：normal 直通 Seed，tight/relaxed = base ∓ 0.25。 */
+export declare function buildLineHeightRecipes(): ReferenceRecipe[];
+/** 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）。 */
+export declare const FONT_SIZE_FACTORS: Record<string, number>;
+/** 11. 排版原子：字体族（三族 + 平台/语言变体）/字重直通，字号按既定倍数派生。 */
+export declare function buildTypographyRecipes(): ReferenceRecipe[];
+/** 动效时长档位倍数。 */
+export declare const DURATION_FACTORS: {
+    readonly fast: 0.5;
+    readonly slow: 1.6;
+};
+/** 12. 动效：duration 按倍数派生，easing 直通。 */
+export declare function buildMotionRecipes(): ReferenceRecipe[];
+/**
+ * 13. 阴影：形状由 effect.shadow.base 按各档位比例缩放，颜色沿用
+ * alphaStep 结构锚点。它不是 Figma Color 变量体系里的 T2 颜色 token。
+ */
+export declare function buildShadowRecipes(): ReferenceRecipe[];
+export declare function allReferenceRecipes(): ReferenceRecipe[];
+/** T2 顶层入口：喂一个 Seed，产出全量 Reference recipes + 拍平后的 CSS 变量映射 + 阴影形状（供 Semantic 层消费）。 */
+export declare function buildReference(seed: Seed): ReferenceBuild;

package/dist/derive/semantic.d.ts

@@ -0,0 +1,75 @@
+import type { ReferenceBuild, ShadowLevel } from "./reference.js";
+/**
+ * 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 的血缘展示共用同一份事实。
+ */
+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 INSET_STACK_ROLES: Record<string, string>;
+export declare const Z_INDEX_ROLES: Record<string, string>;
+export declare const MOTION_DURATION_ROLES: Record<string, string>;
+/** 字体族角色：text（正文缺省）/ number（数字数据）/ code（等宽）。 */
+export declare const FONT_FAMILY_ROLES: Record<string, string>;
+export interface TypographyRole {
+    fontFamilyRef: string;
+    fontSizeRef: string;
+    fontWeightRef: string;
+    lineHeightRef: string;
+    letterSpacingRef: string;
+}
+/** typography.* 复合角色：每个字段各自引用 Reference（无任何裸字面量）。 */
+export declare const TYPOGRAPHY_ROLES: Record<string, TypographyRole>;
+export declare const TYPOGRAPHY_FIELDS: readonly ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing"];
+export interface ColorRoleRefs {
+    light: string;
+    dark: string;
+}
+export declare const COLOR_ROLES: Record<string, ColorRoleRefs>;
+/** 复合阴影角色：形状取 Reference effect.shadow.<level>，颜色取 color.shadow。 */
+export declare const SHADOW_COMPOSITE_ROLES: Record<string, ShadowLevel>;
+export 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 的产出一一对应（顺序一致）。
+ */
+export declare function semanticRoleEntries(): SemanticRoleEntry[];
+/**
+ * 结构类（mode 无关）：尺寸角色 + 字体族角色 + 排版复合角色 + 动效时长/缓动。
+ * `effect.shadow.*` 的颜色字段随 mode 变化，归入 `buildSemanticColor`。
+ */
+export declare function buildSemanticStructural(reference: ReferenceBuild): Record<string, string>;
+/**
+ * 颜色类（light/dark 分别求值）：color.* 全部角色。
+ */
+export declare function buildSemanticColor(reference: ReferenceBuild, mode: SemanticMode): Record<string, string>;