UI 视觉设计 / 系统课时
检查组件硬编码色值的残留
检查组件硬编码色值的残留
将组件接入设计令牌后,零散的十六进制色值、颜色函数和 SVG 填色仍可能绕过主题映射,让深色模式中的卡片、按钮或边框显得突兀。本课用源码检索建立候选清单,逐项判断是否替换为语义 Token,并通过组件对照确认修改有效。
学习目标
- 检索组件样式、行内样式和 SVG 中的直接色值,识别误报。
- 区分应迁移到语义 Token 的色值、令牌定义和可保留的局部特例。
- 用浅色、深色及品牌主题的实际渲染结果验收修复。
扫描组件源码并记录命中
在项目根目录安装并使用 ripgrep(命令名 rg)。以下命令针对常见前端源码扩展名扫描十六进制颜色和 CSS 颜色函数;若项目不用 src 目录,将末尾路径替换为实际源码目录。
rg -n --no-heading \
--glob '*.{css,scss,less,vue,jsx,tsx,js,ts,svg}' \
-e '#(?:[[:xdigit:]]{3}|[[:xdigit:]]{4}|[[:xdigit:]]{6}|[[:xdigit:]]{8})\b' \
-e '\b(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch|color)\s*\(' \
src预期输出:有命中时打印“文件路径:行号:源码行”,例如:
<PATH>:<LINE>: background-color: #fff;
<PATH>:<LINE>: box-shadow: 0 2px 8px rgb(0 0 0 / 12%);<PATH> 和 <LINE> 随项目变化。无命中时不打印内容,rg 返回退出码 1;退出码 2 表示检索错误。该命令只能形成候选清单:令牌定义、注释、SVG 片段标识符也可能命中;white 等颜色关键字则需要另外搜索,不能把扫描结果直接当成最终缺陷数。
按颜色职责决定处理方式
先打开命中行,确认它控制的是文字、表面、边框、交互状态、阴影还是插画,再追踪同一组件在不同主题下的表现。不要把每个 #fff 都机械替换成同一个变量。
| 命中位置与用途 | 处理决定 | 判断依据 |
|---|---|---|
订单卡片正文 #1f2937 |
使用已有 --color-text-primary |
正文需要随主题切换 |
卡片底色 #fff |
使用 --color-surface-card |
多处卡片共享表面角色 |
多处复用的阴影 rgb(0 0 0 / 12%) |
收敛到统一阴影令牌 | 需要统一调整层次 |
主题令牌文件中的 #fff |
保留为令牌取值 | 它是映射源,不是组件残留 |
| 不参与换肤的独立多色插画 | 经评审记录为特例 | 改为语义色可能破坏原图 |
组件消费层优先引用语义角色,而不是 --blue-600 这类基础色阶。若已有令牌命名不同,应使用项目现有名称;只有职责确实缺失且存在复用场景时才新增令牌。单色 SVG 图标通常可改用 currentColor 继承组件文字色,不能据此强行改写有固定配色要求的多色图形。
替换组件样式并核查状态
例如某订单卡片原先把背景写成 #fff、文字写成 #1f2937、边框写成 #d7dfea。下面是片段示例,前提是项目主题样式已定义这三个自定义语义令牌:
.order-card {
background-color: var(--color-surface-card);
color: var(--color-text-primary);
border: 1px solid var(--color-border-subtle);
}在示例主题中,可将三种令牌的浅色值分别设为 #ffffff、#1f2937、#d7dfea,深色值设为 #1d2735、#eef2f7、#3f4a5b。这些是演示取值,不是浏览器内置令牌;项目应以真实设计系统为准。浏览器开发者工具的 Computed 面板应显示当前主题对应的最终颜色,切换主题后数值应变化。
还要检查 :hover、:focus-visible、:disabled、错误态,以及组件的 style 属性、伪元素、渐变和图标 fill、stroke。常见漏改是默认态已经使用 var(...),悬停态仍写着 background: #2563eb;结果只在交互时暴露主题不一致。
用组件对照验证残留是否清零
选同一张订单卡片,固定订单号、金额、文字和状态,在浅色与深色主题中分别观察修改前后;再切换第二套品牌主题。这样才能区分“查到了色值”和“色值确实破坏了语义映射”。

按以下顺序验收:
- 在浏览器开发者工具中选择该组件,检查 Styles 中实际生效的
var(--...)引用及 Computed 中的背景、文字、边框颜色;确认没有被更高优先级的内联样式覆盖。 - 切换浅色、深色、另一品牌主题,分别检查默认、悬停、焦点和禁用状态;对错误提示还要确认颜色以外的图标或文案线索。
- 再次运行检索命令,逐条处理组件目录中的剩余候选:迁移、确认令牌定义,或登记例外。对于例外,写明文件与行号、用途、保留原因和复核负责人。
- 在代码评审中对照修改前后的组件截图,并检查新样式是否引用现有语义 Token,避免用
--special-white这类只为绕过扫描而创建的变量。
验收标准是组件层没有未经说明的直接色值,而不是仓库内一个十六进制颜色也不剩:基础令牌和主题映射本来就需要实际颜色数值,合法例外则需要可追溯的记录。