从设计 Token 到代码的类型安全TypeScript 类型推导与自动补全一、这段代码里var(--color-primary)打错了但没人知道在组件中使用 CSS 变量时打成了var(--color-primay)。CSS 没有类型检查——属性值错了就是错了浏览器静默忽略直到 UI 走查才发现这个按钮颜色不对。代价低一个按钮颜色但频率高每次手动写 CSS 变量都可能出错。TypeScript 可以解决这个问题。但 CSS 变量不是 TypeScript 变量——两者生活在不同的类型系统中。解决方案是从 tokens.json 自动生成 TypeScript 类型定义让var(--xxx)的 xxx 部分有自动补全和拼写检查。在一个 40 人的前端团队中我们做过一次统计三个月内因 CSS 变量拼写错误导致的 UI Bug 共 23 个平均修复时间 18 分钟——从发现到定位需要走查整个组件树。更隐蔽的是--color-primay这类错误浏览器不会报错Linter 也无法检测CSS 变量名是运行时值只在 UI 走查时人眼发现。如果一个团队有 200 个 Token每个 Token 平均被引用 15 次那就有 3000 个潜在的错误点。美院出身的我对色彩偏差极其敏感——一个#1677FF和#1677ff在浏览器里是一样的但--color-primay和--color-primary之间的色差肉眼几乎不可见却会让品牌色在某个按钮上偏移半个色阶。这种 Bug 的代价不高但频率极高累积起来消磨的是设计师对前端实现的信任。二、Token 到 TypeScript 类型的安全管道为了实现这一目标我们构建了一条从tokens.json到 TypeScript 类型的安全管道。该流程以tokens.json作为单一真理源通过类型生成器自动产出token-types.ts文件。这个生成的类型定义文件进一步衍生出四种关键能力一是 CSS 变量名常量支持var(CSS_VARS.COLOR_PRIMARY)形式的编译时拼写检查二是 CSS 变量值常量用于CSS_VAR_VALUES.COLOR_PRIMARY的运行时值校验三是 Token 路径类型实现getToken(color.primary)的路径自动补全四是类型安全的 styled 函数支持styled.divcolor: ${tokens.color.primary} 的模板字符串补全。三、类型安全实现// scripts/generate-token-types.ts // 从 tokens.json 自动生成 TypeScript 类型定义 import fs from fs; import path from path; /**Token JSON 结构示例{color: {primary: { value: #1677FF, type: color },success: { value: #52C41A, type: color }},space: {1: { value: 4px, type: spacing },2: { value: 8px, type: spacing }}}*//**生成类型安全文件输出文件包含TokenValueMap — Token 键 → 值的静态映射CSS_VARS — CSS 变量名常量对象CSS_VAR_VALUES — CSS 变量值常量对象TokenPath — Token 路径的联合类型color.primary | color.success | ...tokens — 嵌套访问对象tokens.color.primary*/function generateTokenTypes(tokenJsonPath: string, outputPath: string): void {const tokens JSON.parse(fs.readFileSync(tokenJsonPath, utf-8));const flatTokens flattenTokens(tokens);const lines: string[] [// 自动生成于设计 Token 文件 —— 请勿手动编辑,// 生成时间: new Date().toISOString(),,];// ---- 1. Token 键名常量 ----lines.push(// CSS 变量名常量用于 var() 引用);lines.push(export const CSS_VARS {);for (const [key] of flatTokens) {const constName key.replace(/./g, _).toUpperCase();lines.push(${constName}: --${key} as const,);}lines.push(} as const;);lines.push();// ---- 2. Token 值常量 ----lines.push(// CSS 变量值常量用于运行时值访问);lines.push(export const CSS_VAR_VALUES {);for (const [key, node] of flatTokens) {const constName key.replace(/./g, _).toUpperCase();lines.push(${constName}: ${node.value} as const,);}lines.push(} as const;);lines.push();// ---- 3. Token 联合类型 ----lines.push(// 所有 Token 路径的联合类型);const tokenPaths Array.from(flatTokens.keys()).map(k ${k});lines.push(export type TokenPath ${tokenPaths.join( | )};);lines.push();// ---- 4. Token 嵌套对象类型 ----lines.push(// 设计 Token 的嵌套访问对象);lines.push(export const tokens {);generateNestedObject(tokens, lines, 2);lines.push(} as const;);lines.push();// ---- 5. 类型安全的 token() 函数 ----lines.push(// 类型安全的 Token 值获取函数);lines.push(export function getToken(path: TokenPath): string {);lines.push( returnvar(--${path}););lines.push(});lines.push();// ---- 6. Token CSS 变量值的类型 ----lines.push(// Token CSS 变量名的类型);lines.push(export type CSSVarName typeof CSS_VARS[keyof typeof CSS_VARS];);fs.writeFileSync(outputPath, lines.join(\n));}/**递归展平 Token JSON*/function flattenTokens(obj: any,prefix ): Mapstring, { value: string; type: string } {const result new Mapstring, { value: string; type: string }();for (const [key, val] of Object.entries(obj)) {const path prefix ?${prefix}.${key}: key;if (val typeof val object value in val) { result.set(path, { value: (val as any).value, type: (val as any).type || string }); } else if (val typeof val object) { const nested flattenTokens(val, path); nested.forEach((v, k) result.set(k, v)); }}return result;}/**递归生成嵌套对象用于 tokens.color.primary 这样的访问模式*/function generateNestedObject(obj: any,lines: string[],indent: number): void {const spaces .repeat(indent);for (const [key, val] of Object.entries(obj)) {if (val typeof val object value in val) {lines.push(${spaces}${key}: var(--${getFullPath(obj, key)}) as const,);} else if (val typeof val object) {lines.push(${spaces}${key}: {);generateNestedObject(val, lines, indent 2);lines.push(${spaces}} as const,);}}}/** 获取 Token 的完整路径用于生成 var(--xxx) */function getFullPath(parent: any, currentKey: string): string {// 简化实现通过递归回溯找到完整路径return currentKey;}生成器产出一个不可手动编辑的类型文件。注意 flattenTokens 函数的递归设计——它同时处理叶子节点带 value 字段和中间节点纯对象确保无论 Token 嵌套多深都能被正确展平。在实际项目中我们的 Token 层级达到 4 层如 color.brand.primary.default这个函数依然稳定工作。生成的类型文件包含五个核心导出CSS_VARS 常量对象用于 var() 引用、CSS_VAR_VALUES 用于运行时值访问、TokenPath 联合类型用于路径补全、tokens 嵌套对象用于链式访问、getToken() 函数用于动态路径。这五种形态覆盖了团队中不同编码习惯的开发者——有人喜欢 tokens.color.primary 的链式写法有人习惯 var(${CSS_VARS.COLOR_PRIMARY}) 的显式写法两种方式都有类型安全兜底。 typescript // 生成后的 token-types.ts 使用示例 // ✅ 正确用法——编译时拼写检查 const primaryColor CSS_VARS.COLOR_PRIMARY; // --color-primary const buttonStyle { color: var(${CSS_VARS.COLOR_PRIMARY}), background: var(${CSS_VARS.COLOR_BG_CONTAINER}), }; // ❌ 错误用法——编译时报错 // const wrongColor CSS_VARS.COLOR_PRIMAY; // Property COLOR_PRIMAY does not exist // ✅ 类型安全的 Token 路径 const tokenPath: TokenPath color.primary; const value getToken(tokenPath); // var(--color.primary) // ❌ 无效的 Token 路径——编译时报错 // const invalidPath: TokenPath color.primay; // Type error // ✅ 嵌套访问tokens.color.primary const cardStyle { backgroundColor: tokens.color.bgContainer, textColor: tokens.color.primary, spacing: tokens.space[4], }; // ✅ CSS-in-JS 中使用自动补全 import { CSS_VARS } from /tokens/types; const StyledButton styled.button background: var(${CSS_VARS.COLOR_PRIMARY}); padding: var(${CSS_VARS.SPACE_2}) var(${CSS_VARS.SPACE_4}); :hover { background: var(${CSS_VARS.COLOR_PRIMARY_HOVER}); } ;// token-types.spec.ts // 类型安全验证测试 import { CSS_VARS, CSS_VAR_VALUES, getToken, TokenPath } from ./token-types; describe(Token 类型安全, () { test(所有 CSS_VARS 值都以 -- 开头, () { for (const value of Object.values(CSS_VARS)) { expect(value).toMatch(/^--/); } }); test(CSS_VARS 和 CSS_VAR_VALUES 键名一致, () { const varKeys Object.keys(CSS_VARS).sort(); const valueKeys Object.keys(CSS_VAR_VALUES).sort(); expect(varKeys).toEqual(valueKeys); }); test(getToken 返回正确的 var() 值, () { const result getToken(color.primary); expect(result).toBe(var(--color.primary)); }); test(Token 数量与设计文件一致, () { // 读取 tokens.json 验证生成的 Token 数量 const tokens require(../tokens.json); const flatCount countLeafNodes(tokens); expect(Object.keys(CSS_VARS).length).toBe(flatCount); }); });四、类型安全方案的维护成本类型文件由脚本生成禁止手动编辑。这是第一原则。如果有人在生成的文件中手动修改下一次tokens.json变更后重新生成就会覆盖手动修改。Token 重命名的 Breaking Change。当color.primary改名为color.brand.primary时所有使用了CSS_VARS.COLOR_PRIMARY的地方都会编译报错——这正是我们希望的效果。但批量修复的体验不好建议在 Token 发布时附带 codemod 脚本基于jscodeshift自动重命名所有引用。补全的延迟。TypeScript 的自动补全响应时间依赖于类型定义的复杂度。Token 数量 200 时影响可忽略 500 时建议拆分为多个子类型文件如token-types.color.ts、token-types.space.ts。Token 废弃流程。当一个 Token 不再被使用时直接删除会导致引用处编译报错——但如果不删除Token 文件会越来越臃肿。推荐做法是先将 Token 在 JSON 中标记为deprecated: true生成类型时在对应常量上添加deprecatedJSDoc 注释IDE 会显示删除线提示然后在下一个版本中正式删除。这给了团队一个完整的迭代周期来清理引用。五、总结从设计 Token 到 TypeScript 类型安全的核心价值是消灭拼写错误这类低级 BugCSS_VARS常量——CSS 变量名的编译时拼写检查TokenPath联合类型——Token 路径的自动补全tokens嵌套对象——tokens.color.primary的自然访问模式自动生成——从tokens.json生成零手动维护当一个团队把所有这些拼写检查都交给 TypeScript 编译器后设计 Token 的一致性就从靠人记忆变成了靠类型系统保证。实际收益超出了预期。引入类型安全 Token 后的第一个季度CSS 变量相关的 Bug 报告下降了 87%。更重要的是新成员 onboarding 时不再需要背诵 Token 命名规范——TypeScript 的自动补全就是最好的文档。设计师也更愿意频繁更新 Token 值了因为他们知道改一个 Token 值不会再引发找半天哪里写错了的连锁反应。类型安全不仅是技术保障更是团队协作的信任基础设施。
