UI 视觉设计 / 系统课时

检查组件硬编码色值的残留

检查组件硬编码色值的残留

将组件接入设计令牌后,零散的十六进制色值、颜色函数和 SVG 填色仍可能绕过主题映射,让深色模式中的卡片、按钮或边框显得突兀。本课用源码检索建立候选清单,逐项判断是否替换为语义 Token,并通过组件对照确认修改有效。

学习目标

  • 检索组件样式、行内样式和 SVG 中的直接色值,识别误报。
  • 区分应迁移到语义 Token 的色值、令牌定义和可保留的局部特例。
  • 用浅色、深色及品牌主题的实际渲染结果验收修复。

扫描组件源码并记录命中

在项目根目录安装并使用 ripgrep(命令名 rg)。以下命令针对常见前端源码扩展名扫描十六进制颜色和 CSS 颜色函数;若项目不用 src 目录,将末尾路径替换为实际源码目录。

bash
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

预期输出:有命中时打印“文件路径:行号:源码行”,例如:

text
<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。下面是片段示例,前提是项目主题样式已定义这三个自定义语义令牌:

css
.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;结果只在交互时暴露主题不一致。

用组件对照验证残留是否清零

选同一张订单卡片,固定订单号、金额、文字和状态,在浅色与深色主题中分别观察修改前后;再切换第二套品牌主题。这样才能区分“查到了色值”和“色值确实破坏了语义映射”。

订单卡片硬编码颜色修复的双主题前后对照

按以下顺序验收:

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

验收标准是组件层没有未经说明的直接色值,而不是仓库内一个十六进制颜色也不剩:基础令牌和主题映射本来就需要实际颜色数值,合法例外则需要可追溯的记录。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

检查组件硬编码色值的残留

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通