UI 视觉设计 / 系统课时

生成 TypeScript 常量与类型

生成 TypeScript 常量与类型

把一份 DTCG Token 编译为可导入的 tokens.ts,并同步产出 tokens.css。完成后,业务代码能获得 Token 名称自动补全、准确的值类型与 CSS 变量引用,还能通过类型检查和运行时断言发现两端不一致。

学习目标

  • 使用 Style Dictionary 的自定义 Format 生成 as const 常量及 TokenName、TokenValue 类型。
  • 固定源路径到 TypeScript 键名、CSS 自定义属性的映射规则。
  • 用 TypeScript 编译和逐项值检查验证生成物,而不是只看文件是否存在。

定义两端共用的命名契约

本例采用 Style Dictionary 5.4.2、Node.js 22 或更新版本、TypeScript 5.9。TypeScript 保留 DTCG 的点分源路径作为对象键,CSS 使用 name/kebab 转为短横线名称;两端共用 web 转换组,尺寸以 px 输出。这样无需在业务代码里手写第二份命名表。

DTCG 路径 TypeScript 读取方式 CSS 属性
color.brand.600 tokens['color.brand.600'] --color-brand-600
space.controlGap tokens['space.controlGap'] --space-control-gap
opacity.disabled tokens['opacity.disabled'] --opacity-disabled

DTCG 同源生成 CSS 和 TypeScript 的数据流

准备可复现的 DTCG 输入

在空项目目录执行以下命令,启用 ESM。若已有项目,保留现有 package.json,只安装相应开发依赖并确认运行环境满足要求。

bash
npm init -y
npm pkg set type=module
npm install -D style-dictionary@5.4.2 typescript@5.9.3 @types/node@22

预期结果:package.json 的 type 为 module,三个开发依赖安装成功;npm 的安装日志和审计提示随环境变化。

创建 tokens/tokens.json。这里使用 DTCG 2025.10 的结构化颜色、尺寸值,以及普通数值;不把尺寸 8px 误写成不带单位的数字。

json
{
  "color": {
    "brand": {
      "600": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.145098, 0.388235, 0.921569],
          "hex": "#2563eb"
        }
      }
    }
  },
  "space": {
    "controlGap": {
      "$type": "dimension",
      "$value": { "value": 8, "unit": "px" }
    }
  },
  "opacity": {
    "disabled": { "$type": "number", "$value": 0.4 }
  }
}

预期生效行为是得到三项扁平 Token:颜色 #2563eb、尺寸 8px、透明度数值 0.4;下一步直接检查真实构建产物。

编写 TypeScript Format 并执行构建

创建项目根目录的 build-tokens.mjs。自定义 Format 消费已完成转换与引用解析的 dictionary.allTokens:path 组成稳定业务键,name 组成 CSS 变量名,value 直接序列化为 TypeScript 字面量。键名和 CSS 名出现碰撞时应立即停止构建。

js
import StyleDictionary from 'style-dictionary';

StyleDictionary.registerFormat({
  name: 'app/typed-tokens',
  format: ({ dictionary }) => {
    const rows = dictionary.allTokens.map((token) => ({
      key: token.path.join('.'),
      cssRef: `var(--${token.name})`,
      value: token.value,
    })).sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));

    const keys = new Set();
    const cssRefs = new Set();
    for (const row of rows) {
      // 不允许不同源路径映射到同一个 CSS 名称。
      if (keys.has(row.key) || cssRefs.has(row.cssRef)) {
        throw new Error(`Token 命名冲突:${row.key}`);
      }
      if (!['string', 'number', 'boolean'].includes(typeof row.value)) {
        throw new Error(`复合类型需要专用序列化器:${row.key}`);
      }
      keys.add(row.key);
      cssRefs.add(row.cssRef);
    }

    const entries = (pick) => rows.map((row) =>
      `  ${JSON.stringify(row.key)}: ${JSON.stringify(pick(row))},`);

    return [
      '// Generated from DTCG. Do not edit.',
      'export const tokens = {',
      ...entries((row) => row.value),
      '} as const;',
      '',
      'export const cssVars = {',
      ...entries((row) => row.cssRef),
      '} as const;',
      '',
      'export type TokenName = keyof typeof tokens;',
      'export type TokenValue<K extends TokenName> = (typeof tokens)[K];',
      '',
    ].join('\n');
  },
});

const sd = new StyleDictionary({
  source: ['tokens/tokens.json'],
  platforms: {
    web: {
      // CSS 与 TS 共享命名、颜色和尺寸转换。
      transformGroup: 'web',
      buildPath: 'dist/',
      files: [
        {
          destination: 'tokens.css',
          format: 'css/variables',
          options: { showFileHeader: false },
        },
        { destination: 'tokens.ts', format: 'app/typed-tokens' },
      ],
    },
  },
});

await sd.buildAllPlatforms();
console.log('Generated: dist/tokens.css, dist/tokens.ts');

运行生成器:

bash
node build-tokens.mjs

预期输出的最后一行(前面可能有 Style Dictionary 构建日志):

text
Generated: dist/tokens.css, dist/tokens.ts

检查 dist/tokens.ts 应有 tokens、cssVars 两个 as const 对象及两项类型声明;tokens['space.controlGap'] 的值为字符串 8px,tokens['opacity.disabled'] 则为数字 0.4。dist/tokens.css 中应有对应的 --space-control-gap: 8px; 和 --opacity-disabled: 0.4;。

在业务代码中进行类型和资源双重验收

创建项目根目录的 verify.ts。真实业务可以从 ./dist/tokens.js 导入生成模块;这里额外读取 CSS,逐一比对每个 Token 的变量名和值,捕捉手工改坏或构建策略分叉的情况。当前示例只导出已转换成字符串、数字或布尔值的 Token。

ts
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { tokens, cssVars } from './dist/tokens.js';
import type { TokenName, TokenValue } from './dist/tokens.js';

function getToken<K extends TokenName>(name: K): TokenValue<K> {
  return tokens[name];
}

const color: string = getToken('color.brand.600');
const opacity: number = getToken('opacity.disabled');
const css = readFileSync('dist/tokens.css', 'utf8');

// 检查全部生成键,而不是只抽查一个颜色。
for (const key of Object.keys(tokens) as TokenName[]) {
  const cssName = cssVars[key].slice(4, -1); // 去掉 var( 与 )
  assert.ok(
    css.includes(`${cssName}: ${String(tokens[key])};`),
    `CSS 与 TS 不一致:${key}`,
  );
}

console.log(`PASS ${Object.keys(tokens).length} tokens`);
console.log(color, opacity);
console.log(cssVars['space.controlGap']);

完成上述文件后,在项目根目录执行:

bash
npx tsc --strict --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir build verify.ts dist/tokens.ts
node build/verify.js

预期输出:

text
PASS 3 tokens
#2563eb 0.4
var(--space-control-gap)

TokenName 是合法键名的联合类型,TokenValue<'opacity.disabled'> 推导为数字字面量 0.4。若将 getToken('color.brand.600') 赋给 number,会出现 TS2322;若把键写成 color.brand.500,会出现 TS2345。两种错误都应在提交代码前修正,而不是通过 as any 消除提示。

处理主题切换与类型边界

as const 只让编译器保留只读属性和字面量类型,不会在运行时调用 Object.freeze。更重要的是,导入 tokens['color.brand.600'] 得到的是构建时的静态色值;如果页面通过主题选择器覆盖 CSS 变量,组件样式应使用 cssVars['color.brand.600'],而不是把静态颜色直接写入 style。

这个 Format 有意拒绝尚未序列化的阴影、排版等复合值;后续加入它们时,先定义平台输出表示,再扩展序列化和测试,不要用 String(object) 得到无意义的 [object Object]。fooBar 与 foo-bar 可能同时映射为 --foo-bar,所以生成器会在碰撞时失败。

团队如果把 dist/ 纳入版本控制,应在 CI 中重新运行 node build-tokens.mjs、TypeScript 验证,并使用 git diff --exit-code -- dist/ 拦截未提交的生成结果;如果不提交 dist/,则在发布前构建并执行相同的类型与值校验。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成 TypeScript 常量与类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通