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 输入
在空项目目录执行以下命令,启用 ESM。若已有项目,保留现有 package.json,只安装相应开发依赖并确认运行环境满足要求。
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 误写成不带单位的数字。
{
"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 名出现碰撞时应立即停止构建。
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');运行生成器:
node build-tokens.mjs预期输出的最后一行(前面可能有 Style Dictionary 构建日志):
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。
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']);完成上述文件后,在项目根目录执行:
npx tsc --strict --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir build verify.ts dist/tokens.ts
node build/verify.js预期输出:
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/,则在发布前构建并执行相同的类型与值校验。