Sentry 前端语义化 Token 分类体系：`use-semantic-token` 规则的 Token Taxonomy 修复指南

Sentry 前端语义化 Token 分类体系use-semantic-token规则的 Token Taxonomy 修复指南【免费下载链接】sentryDeveloper-first error tracking and performance monitoring项目地址: https://gitcode.com/GitHub_Trending/sen/sentry导读本文围绕 Sentry 开源仓库中.agents/skills/lint-fix技能体系的核心参考文档token-taxonomy.md展开系统讲解 Sentry 前端static/app中语义化设计令牌theme.tokens.*的六大分类content / background / border / focus / graphics / syntax及其允许绑定的 CSS 属性。读完本文你将掌握use-semantic-tokenESLint 违规的判定原理关键词匹配、最深优先规则、属性到分类的快速查表方法以及保持后缀、仅换分类的标准修复模式并理解该规则在 tokenRules.ts 中的真实实现与测试验证方式。一、背景Sentry 前端的语义化 Token 体系Sentry 前端维护了一套基于 Emotion 主题emotion/react的设计令牌体系。主题对象通过theme.tokens.*暴露实际定义位于 static/app/utils/theme/scraps/theme/light.tsx 与 dark.tsx两套主题在 1883 行附近均以如下结构导出令牌export const lightTheme { ...baseTheme, shadow, tokens: { background, border, content, dataviz, elevation, focus, graphics, interactive, syntax, }, };从源码结构可以看到令牌命名空间包含content、background、border、focus、graphics、dataviz、elevation、syntax、interactive等多个顶层分组而颜色令牌的具体色值则沉淀在 static/app/utils/theme/scraps/tokens/color.tsx 中。令牌路径通常形如theme.tokens.interactive.chonky.neutral.content这样的多段式命名每一段都携带语义信息——这正是use-semantic-token规则能够做静态分类判定的前提。为了防止开发者在样式代码中把语义错误的令牌例如用border分类的令牌去写color滥用Sentry 在sentry/scrapsESLint 插件中实现了use-semantic-token规则。该规则没有自动修复autofix因此需要开发者依据token-taxonomy.md手动修复这也是本文所要展开的全部内容。二、Token 六大分类与允许的 CSS 属性核心表token-taxonomy.md的第一张核心表定义了六个令牌分类各自的关键词出现在令牌路径中用于识别与允许的 CSS 属性。这张表正是 tokenRules.ts 中TOKEN_RULES数组的文档化映射源码中每个规则由name、keywords、allowedProperties三个字段构成。分类路径关键词允许的 CSS 属性contentcontent、linkcolor、text-decoration、text-decoration-color、text-emphasis-color、caret-color、column-rule-color、-webkit-text-fill-color、-webkit-text-stroke-color、fill、stop-colorbackgroundbackgroundbackground、background-color、background-imageborderborderborder、border-color、border-top、border-right、border-bottom、border-left、所有border-*-color变体、border-block*、border-inline*、stroke、text-decoration、text-decoration-color、border-image、border-image-sourcefocusfocus、elevationbox-shadow、outline、outline-color、text-shadowgraphicsgraphics、datavizbackground、background-color、background-image、fill、stroke、stop-colorsyntaxsyntaxcolor、-webkit-text-fill-color、-webkit-text-stroke-color、background、background-color、background-image对照源码 tokenRules.ts 可以确认以下几点实现细节content 分类允许fill与stop-color这使其可以用于 SVG 文本着色border 分类不仅覆盖四个方向的颜色变体border-top-color、border-right-color、border-bottom-color、border-left-color还覆盖逻辑属性border-block*与border-inline*系列含-color、-start、-end等共 12 个变体同时放宽了stroke、text-decoration、border-image、border-image-sourcefocus 分类专门服务于交互态反馈允许box-shadow、outline、outline-color、text-shadow关键词同时包含focus与elevationgraphics 分类关键词为graphics与dataviz用于图表/数据可视化场景syntax 分类专门用于代码高亮场景是唯一同时允许文本色color、-webkit-text-*和背景色background*的分类。依据 light.tsx 的实际导出tokens下还包含dataviz、elevation、interactive分组。其中dataviz与graphics在规则中共享同一分类elevation与focus共享同一分类而interactive本身不作为独立分类它内部按交互状态细分出的子令牌如interactive.link.neutral.rest会继续用更深的content等关键词决定归属。三、CSS 属性 → 正确分类的快速查表token-taxonomy.md的第二张表是反向查表给定一个 CSS 属性应该从哪个分类取令牌。这张表与源码中PROPERTY_TO_RULE反向映射tokenRules.ts一一对应——后者由buildPropertyToRule遍历所有规则的allowedProperties生成property → rule name的 Map正是use-semantic-token规则报告 Use a{{suggestedCategory}}token instead 建议信息的来源。CSS 属性应使用的令牌分类colorcontent代码高亮场景用syntaxbackground、background-colorbackground数据可视化场景用graphicsborder、border-color、border-*borderbox-shadowfocusoutline、outline-colorfocustext-shadowfocusfill、strokecontent文字、graphics图表、或border装饰性text-decoration、text-decoration-colorcontent或border使用口诀先按语义猜属性再用表格核对分类。例如要给图表柱形上色用stroke查表应取graphics分类令牌要给普通文本设color取content要写键盘焦点样式outline-color只能取focus。四、关键词匹配策略为何最深优先token-taxonomy.md规定令牌路径按关键词匹配规则为将路径按.分割成段找出哪个分类的关键词出现在路径中**最深最后**的位置该分类的规则生效。例如interactive.background.content→content胜出因为它比background更深。这一策略在源码中由findRuleForTokentokenRules.ts精确实现export function findRuleForToken(tokenPath: string): TokenRule | null { const pathParts tokenPath.split(.); let bestMatch null; let bestPosition -1; for (const rule of TOKEN_RULES) { for (const keyword of rule.keywords) { const position pathParts.lastIndexOf(keyword); if (position bestPosition) { bestMatch rule; bestPosition position; } } } return bestMatch; }实现要点对每个规则关键词用lastIndexOf取其在路径中最后一次出现的位置取位置最大即路径最深层的关键词所属规则。之所以采用最深优先而非最先出现优先是因为 Sentry 的令牌路径设计遵循外层是组件状态内层是语义的约定——例如interactive.chonky.debossed.neutral.content.primary中interactive与chonky只是交互形态真正决定这个令牌能用来做什么的是最深的content。测试用例 useSemanticToken.spec.ts 中的interactive.chonky.debossed.neutral.content.primary、interactive.link.neutral.rest等路径被标记为color属性的合法用例正是对这一策略的验证。当路径中不含任何已知关键词时findRuleForToken返回null规则直接跳过该值见 useSemanticToken.ts。五、修复模式保持后缀仅换分类token-taxonomy.md给出的修复模式非常简洁保持同样的特异性后缀只更换分类前缀。因为各分类的令牌在相同语义层级primary、secondary、accent、warning、danger等上是对应的直接替换即可保持视觉意图。// Before错误用 border 令牌给 color 赋值 color: ${p p.theme.tokens.border.primary}; // After正确color 应使用 content 令牌 color: ${p p.theme.tokens.content.primary};配套的 fix-patterns.md 提供了更丰富的对照示例CSS 属性错误令牌正确令牌colortheme.tokens.border.primarytheme.tokens.content.primarybackgroundtheme.tokens.content.primarytheme.tokens.background.primaryborder-colortheme.tokens.background.secondarytheme.tokens.border.secondarybox-shadowtheme.tokens.content.primarytheme.tokens.focus.primary或theme.tokens.elevation.*fix-patterns.md同时强调use-semantic-token没有 autofix这是与no-core-import的关键区别必须人工确认每个修复点。如果不确定某个具体令牌名是否存在可以查看主题定义文件或在 IDE 中利用theme.tokens.category.的自动补全来探索可用的令牌名。六、规则实现原理use-semantic-token如何工作了解规则如何判定违规有助于写出更精准的修复。规则的完整实现位于 useSemanticToken.ts其核心流程如下快速退出文件不包含 emotion/styled 模式时直接跳过shouldAnalyze收集样式声明通过createStyleCollector收集 styled 模板字符串、css模板、style prop 等场景的StyleDeclaration逐个校验对每个声明的属性若属性名以--开头CSS 自定义属性则跳过对声明值列表中的每个值若带有tokenInfo则调用findRuleForToken解析分类比对白名单若分类未启用或属性在allowedProperties中则通过否则报告错误——若反向映射PROPERTY_TO_RULE能给出建议分类则报invalidPropertyWithSuggestion带建议否则报invalidProperty。规则还支持enabledCategories选项用于只启用部分分类的检查useSemanticToken.ts。令牌提取与值分解tokenInfo由 valueDecomposer.ts 生成。它会递归分解复杂表达式三元表达式foo ? a : b两个分支都作为可能值检查逻辑表达式a || b、a b两个操作数都可能被检查箭头函数p p.theme.tokens.content.primary注册参数p为 theme 绑定后递归分析函数体成员表达式链向上走完整个MemberExpression链找到tokens段取其后缀为tokenPath。theme 绑定追踪为了避免误报theme.ts 会做作用域感知的绑定分析——追踪import {useTheme} from emotion/react、const theme useTheme()、const {tokens} useTheme()以及回调参数(theme) ...、(p) p.theme等绑定形式只有确认基标识符是已知 theme 绑定或theme/p/t等约定名时才识别为令牌引用见 valueDecomposer.ts。测试验证测试文件 useSemanticToken.spec.ts 覆盖了大量场景包括合法用例color配content、background配background、border-color配border、嵌套伪类/媒体查询/模板插值对象等与违规用例如background: ${p p.theme.tokens.content.primary}建议syntax、border-color配content.accent建议border、box-shadow配content.primary建议focus等其中还验证了单个表达式含多个令牌三元时逐个上报的行为。七、实战工作流从违规统计到批量修复token-taxonomy.md定位是lint-fix技能在人工修复use-semantic-token违规时必须加载的参考文档见 .agents/skills/lint-fix/SKILL.md。结合 SKILL.md 给出的工作流一次完整的修复流程如下1. 统计违规规模pnpm exec eslint --rule sentry/scraps/use-semantic-token: error $1 21 | tail -5最后一行即违规总数如42 problems (42 errors, 0 warnings)。注意对整个static/app/跑 ESLint 可能耗时 2 分钟以上建议先缩小到子目录。2. 按规模选择策略100 个以内手动逐个修复每批 5~10 个文件每批后重跑验证100~500 个按子目录分批如static/app/views/、static/app/components/每批提交一个可审查的 PR500 个以上考虑用 jscodeshift 等 codemod 做机械替换或先将规则以warn级别灰度开启分多个 PR 推进。3. 严格遵循修复闭环运行pnpm exec eslint --rule sentry/scraps/use-semantic-token: error $1定位违规依据本文第二、三节表格确定正确分类保持后缀替换令牌对已改文件重跑 ESLint 确认清零扩大范围循环往复全部完成后对static/app/整体验证应报告0 problems。提交前还可用.venv/bin/prek run -q --files file1 [file2 ...]对改动文件跑 pre-commit 检查并按.github/CODEOWNERS的归属约定控制单个 PR 的改动量约 50 个文件PR 标题遵循fix(lint): enforce sentry/scraps/use-semantic-token for codeowner的约定。八、易错场景与排查建议伪类与嵌套选择器中的令牌a:hover、:focus、::before、media查询内的令牌都会被正常收集与校验测试中有对应合法用例修复时不要忽略嵌套作用域多令牌表达式一个三元表达式两个分支都违规时规则会分别报告两处见 useSemanticToken.spec.ts修复时需同时替换所有分支字面量与混合值纯字面量如background: red不触发规则混合了令牌与字面量的对象取值({none: tokens.content.secondary, alert: colors.yellow500})[status]只校验令牌部分CSS 自定义属性--*开头的属性一律跳过这是为了避免把动态变量绑定误判为令牌滥用不确定分类归属时优先看主题定义 light.tsx / dark.tsx 中对应分组的结构或依赖 IDE 对theme.tokens.category.的自动补全。总结Sentry 的语义化 Token 分类体系通过content、background、border、focus、graphics、syntax六大分类约束了每个令牌的合法使用范围use-semantic-token规则与token-taxonomy.md共同构成了这套约束的裁判 手册。修复违规的要点可以概括为一句话按 CSS 属性查分类表保持特异性后缀不变仅替换分类前缀。理解tokenRules.ts中关键词最深优先的匹配算法、PROPERTY_TO_RULE的反向建议机制以及useSemanticToken.ts中基于 AST 提取与 theme 绑定追踪的判定流程能让你在规模化修复时更快、更稳地定位并消灭全部违规。【免费下载链接】sentryDeveloper-first error tracking and performance monitoring项目地址: https://gitcode.com/GitHub_Trending/sen/sentry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考