用代码库数据检查设计系统是否变形

用代码库数据检查设计系统是否变形先把“变形”定义成可以检查的问题设计系统接入代码生成后开发速度只是其中一项观察。生成组件是否继续使用既有 Button、Select 和设计令牌是否新增了未经登记的颜色与间距公共组件 API 是否被绕开都影响后续维护。若没有持续记录这些变化“感觉写得更快”无法说明设计系统仍然一致。代码库本身可以提供一部分证据。AST 静态分析能统计硬编码样式、组件引用与属性用法构建产物可以观察体积变化视觉与交互测试则补上静态规则看不到的结果。指标的作用是指出值得审查的差异不是自动证明某次提交好或坏。生成代码可能偏离设计系统的地方1. 规范穿透与 Token 脏化Token Pollution提示没有提供设计令牌时模型可能输出 HEX 颜色、固定像素或内联样式。单处硬编码不一定错误但它绕开主题、响应式和品牌切换规则时就需要人工解释。扫描器应区分允许的例外与组件源码不能见到字面量就一律报错。2. 伪组件扩散与代码重合度增加生成器若不知道仓库已有SearchSelect可能重新组合 Input 与 Popover。重复实现会增加 API 和交互差异但不能仅凭组件名判断重复。扫描结果应链接到对应源码由评审者确认它是新职责、业务包装还是应复用现有组件。3. API 滥用与模式偏离复合组件通常约定子组件结构、受控状态和事件顺序。模型根据页面效果拼接属性时可能绕过这些约定。类型检查能发现不存在的属性却不一定发现调用模式虽然合法、语义却错误因此还需要组件级测试和代码评审。4. 评估维度失真Pass Rate 谎言编译与单元测试只覆盖各自的契约。一段代码能通过 TypeScript 检查仍可能包含未经登记的样式或错误的键盘交互。相反某个静态规则命中也不代表代码一定有问题。不同检查结果应分开显示避免压成一个缺少解释的总分。用简单指标发现变化Token 引用与硬编码样式的比例可以作为趋势信号但分母、扫描范围和豁免规则必须固定。测试夹具、图表数据与设计系统实现自身可能合法地出现字面量业务组件则采用另一套要求。没有统一采集口径版本之间的数字无法比较。一种覆盖率定义Design Token 覆盖率 ($C_{token}$)$$C_{token} \frac{N_{token_refs}}{N_{token_refs} N_{hardcoded_styles}} \times 100%$$这个比例描述扫描范围内 Token 引用与硬编码样式的关系。项目应根据现有基线和例外规则决定如何使用不能套用通用健康阈值。候选偏离项可以分别记录内联样式、未登记组件引用和重复结构。若要加权权重需要由团队说明依据比起一个抽象总分直接列出命中的文件和规则更便于修正。一个 Babel AST 扫描示例下面的 TypeScript 代码展示如何统计 JSX 中的组件名、style与className。它是说明性示例对成员表达式组件、模板字符串、条件 class 和样式函数的识别并不完整aiDebtScore的权重也只是示意。用于仓库门禁前应先用本项目代码建立误报清单并把规则改成团队能解释的判断。import * as parser from babel/parser; import traverse from babel/traverse; import * as t from babel/types; import * as fs from fs; import * as path from path; /** * 设计系统评估指标结果接口 */ export interface EvaluationMetrics { totalStyleAttributes: number; tokenReferences: number; hardcodedStyles: number; customComponentsCount: number; designSystemComponentCount: number; tokenCoverageRatio: number; aiDebtScore: number; } /** * 设计系统 AST 量化分析器 */ export class DesignSystemASTAnalyzer { private allowedDesignTokens: Setstring; private designSystemComponentNames: Setstring; constructor(tokens: string[], dsComponents: string[]) { this.allowedDesignTokens new Set(tokens); this.designSystemComponentNames new Set(dsComponents); } /** * 分析指定文件的 AST 并提取指标 * param filePath TSX/JSX 文件路径 */ public analyzeFile(filePath: string): EvaluationMetrics { const code fs.readFileSync(filePath, utf-8); const ast parser.parse(code, { sourceType: module, plugins: [jsx, typescript], }); let totalStyleAttributes 0; let tokenReferences 0; let hardcodedStyles 0; let customComponentsCount 0; let designSystemComponentCount 0; const tokensSet this.allowedDesignTokens; const dsComponentsSet this.designSystemComponentNames; traverse(ast, { // 1. 扫描 JSX 元素统计设计系统组件与自定义组件的使用比例 JSXOpeningElement(pathNode) { const nameNode pathNode.node.name; if (t.isJSXIdentifier(nameNode)) { const componentName nameNode.name; // 大写开头视为组件 if (/^[A-Z]/.test(componentName)) { if (dsComponentsSet.has(componentName)) { designSystemComponentCount; } else { customComponentsCount; } } } }, // 2. 扫描 style 属性与 className 属性识别硬编码样式与 Token 引用 JSXAttribute(pathNode) { const attrName pathNode.node.name.name; // 检测 style{{ color: #fff }} 等内联样式 if (attrName style) { totalStyleAttributes; const valueNode pathNode.node.value; if (t.isJSXExpressionContainer(valueNode)) { const expr valueNode.expression; if (t.isObjectExpression(expr)) { expr.properties.forEach((prop) { if (t.isObjectProperty(prop) t.isStringLiteral(prop.value)) { const val prop.value.value; // 判断是否使用了 var(--var-name) 形式的 Token if (val.includes(var() Array.from(tokensSet).some(t val.includes(t))) { tokenReferences; } else { hardcodedStyles; } } }); } } } // 检测 classNamebg-primary-500 p-4 是否契合 Token 命名规范 if (attrName className) { const valueNode pathNode.node.value; if (t.isStringLiteral(valueNode)) { const classes valueNode.value.split(/\s/); classes.forEach((cls) { if (cls.startsWith(ds-) || Array.from(tokensSet).some(t cls.includes(t))) { tokenReferences; } else if (cls.length 0) { hardcodedStyles; } }); } } }, }); const totalStyles tokenReferences hardcodedStyles; const tokenCoverageRatio totalStyles 0 ? (tokenReferences / totalStyles) * 100 : 100; // 计算 AI 脏代码指数 (硬编码越多、自定义重复组件越多分值越高) const aiDebtScore (hardcodedStyles * 1.5) (customComponentsCount * 2.0); return { totalStyleAttributes, tokenReferences, hardcodedStyles, customComponentsCount, designSystemComponentCount, tokenCoverageRatio: Number(tokenCoverageRatio.toFixed(2)), aiDebtScore: Number(aiDebtScore.toFixed(2)), }; } } // 使用示例与 CI 质量门禁校验 if (require.main module) { const sampleTokens [--color-primary, --spacing-md, ds-button]; const sampleDSComponents [Button, Select, Modal, Table]; const analyzer new DesignSystemASTAnalyzer(sampleTokens, sampleDSComponents); // 假设扫描生成的临时测试文件 const testFilePath path.join(__dirname, ComponentSample.tsx); if (fs.existsSync(testFilePath)) { const metrics analyzer.analyzeFile(testFilePath); console.log( 设计系统量化评估结果:, JSON.stringify(metrics, null, 2)); if (metrics.tokenCoverageRatio 80.0) { console.error(❌ CI 门禁拦截: Token 覆盖率 (${metrics.tokenCoverageRatio}%) 低于要求的 80%); process.exit(1); } } }把主观说法换成可复查材料下表不设通用阈值而是把常见说法对应到可以查看的证据。门禁是否阻断提交应根据仓库基线、变更类型和维护者确认来决定。主观评估误区实际工程隐患确定性量化治理对策“生成代码更快”可能增加人工修订或重复组件记录生成、修改和评审步骤并查看新增组件与既有组件的职责差异“界面看起来一样”可能绕开 Token、焦点和响应式规则扫描硬编码样式再配合视觉与键盘交互测试“模型理解设计规范”可能混用组件版本或属性限定组件清单使用本地类型定义和 Schema 校验候选结构“页面运行流畅”单次体验无法解释产物变化比较同一构建条件下的产物和性能记录变化超出基线时人工复核如何接入日常评审先以只报告、不阻断的方式运行扫描保存规则版本和基线观察哪些命中确实需要修改。规则稳定后再对边界清楚的项目目录设置门禁新增例外必须写明原因和失效条件。扫描失败只返回文件、位置和规则名不把源码或设计平台凭据发送到未知服务。评审页面同时展示本次差异与历史基线。维护者可以看到新增了哪些硬编码、哪些组件没有登记以及构建产物如何变化。对于误报修正规则或登记明确例外不要求开发者为了数字好看而改出更绕的代码。AST 数据只能说明代码结构不能替代设计评审、可访问性测试和真实交互。把静态结果当作定位入口再回到组件用途与页面行为作判断才是用代码库数据检查设计系统是否偏离原约定的可靠方式。