UI 视觉设计 / 系统课时

排查设计稿与线上样式不一致

排查设计稿与线上样式不一致

订单页切换深色主题后,Figma 中的主按钮已经变为浅蓝色,线上却仍是旧蓝色。下面用一个可复现的案例,依次检查设计变量、Token 源文件、生成产物、已部署 CSS 与浏览器计算样式,最终找到并消除覆盖规则。

学习目标

  • 用同一主题、组件和颜色值建立可比对的故障样本。
  • 沿 Figma、Token JSON、构建产物与浏览器逐层缩小故障范围。
  • 根据 CSS 级联证据修复问题,并验证重新发布后的结果。

固定故障样本与复现条件

先把“颜色不对”写成可核对的事实。本例约定页面根元素为 <html data-theme="dark">,主按钮使用 .button-primary,语义变量为 --color-action-primary;这些都是示例项目约定,排查实际项目时应替换成真实选择器和变量名。

检查项 预期 线上现象
设计模式 Figma Dark 页面已切到 dark
按钮背景 #93c5fd #155eef
CSS 颜色 rgb(147, 197, 253) rgb(21, 94, 239)
故障范围 所有 Dark 主按钮 订单页可稳定复现

记录页面 URL、发布版本或 Git 提交、浏览器及复现步骤,避免拿未发布的设计稿与旧环境直接比较。若只有一个按钮异常,先怀疑组件局部样式;若整站 Dark 颜色都不对,优先查主题模式和全局变量。

从 Figma 追到 Token 源文件

在 Figma 中选中异常按钮所属的 Frame,检查右侧 Appearance 的变量模式,并在对应填充属性查看绑定变量;有 Dev Mode 权限时可在 Inspect 中追踪 Alias 链。确认按钮使用的是 color.action.primary 而不是手填色值,同时核对父级是否把模式固定在 Light。模式为 Auto 时,还要沿父级追踪最终继承到的模式;具体入口可参考 Figma 变量模式说明。

再对照版本库中的 Token。本例 Dark 模式的有效输入采用 Style Dictionary 兼容的 $type / $value 结构;以下为片段示例,实际可能拆分在多个文件。这里的十六进制字符串颜色值是示例工程采用的兼容写法,不是 DTCG 2025.10 所要求的颜色对象格式。

json
{
  "color": {
    "brand": {
      "primary": { "$type": "color", "$value": "#93c5fd" }
    },
    "action": {
      "primary": {
        "$type": "color",
        "$value": "{color.brand.primary}"
      }
    }
  }
}

如果项目采用 DTCG 2025.10,颜色值应使用含 colorSpace、components 的对象,并核对构建工具兼容性,避免把解析错误误判为同步失败;参见 Style Dictionary 的 DTCG 兼容性说明。

检查主题文件是否已同步到当前 Git 提交,别名是否指向正确的路径,以及构建配置是否确实选择了 Dark 覆盖值。若 Figma 是 #93c5fd、仓库仍是旧色,故障就在设计到源文件的同步环节;不要通过改线上 CSS 掩盖源数据落后。

重建生成文件并确认线上版本

本例仓库的 package.json 已定义 build:tokens 脚本,调用 Style Dictionary 生成 generated/tokens.css,且已有 package-lock.json。在项目根目录执行:

bash
npm ci
npm run build:tokens
git diff -- generated/tokens.css

预期结果:构建成功,重新生成的 Dark 声明包含以下值;若仓库提交了构建产物且输入未变,git diff 应无差异。以下 CSS 为产物片段,不是所有 Style Dictionary 项目的固定输出格式。

css
[data-theme="dark"] {
  --color-action-primary: #93c5fd;
}

若生成值不对,检查 Style Dictionary 配置中的 source、include、主题组合、引用解析、转换及输出过滤。若本地产物正确、线上仍错,打开 Chrome DevTools 的 Network,筛选 CSS,核对实际请求 URL、响应内容、缓存状态和部署版本;启用 Disable cache 后重新加载,确认线上响应确实包含新值。不能只看到本地文件正确就认为线上已发布。构建命令及参数可对照 Style Dictionary CLI 文档。

从 Figma 到浏览器的主题颜色故障定位链

用 Styles 和 Computed 锁定覆盖来源

在故障按钮上右键选择“检查”,进入 Chrome DevTools 的 Elements > Computed,搜索 background-color 并展开来源;然后转到 Elements > Styles,查找 --color-action-primary 的声明及被划掉的规则。还要确认 <html> 上的 data-theme 实际为 dark,而不是仅切换了应用内状态。各面板的判断方式可参照 Chrome DevTools CSS 检查指南。

本例生成文件的 [data-theme="dark"] 声明是正确的,但应用样式表里遗留了下面这条规则(片段示例):

css
:root[data-theme="dark"] {
  --color-action-primary: #155eef;
}

.button-primary {
  background-color: var(--color-action-primary);
}

在同一 CSS 来源和级联层级、均为普通声明的前提下,:root[data-theme="dark"] 的选择器优先级高于 [data-theme="dark"],所以即使构建产物正确,最终变量仍是旧值。真实项目还应检查 !important、@layer、行内样式与组件局部覆盖,不能仅凭文件加载先后断言谁生效。

在故障页面的 Console 执行以下完整检查代码;它依赖本例页面存在 .button-primary 元素。

js
(() => {
  const button = document.querySelector(".button-primary");
  if (!button) throw new Error("找不到 .button-primary,请换成实际选择器");

  const root = document.documentElement;
  const token = "--color-action-primary";
  const result = {
    theme: root.getAttribute("data-theme"),
    rootToken: getComputedStyle(root).getPropertyValue(token).trim(),
    buttonToken: getComputedStyle(button).getPropertyValue(token).trim(),
    background: getComputedStyle(button).backgroundColor
  };
  console.log(JSON.stringify(result));
})();

本例故障状态的预期输出:

text
{"theme":"dark","rootToken":"#155eef","buttonToken":"#155eef","background":"rgb(21, 94, 239)"}

若根变量正确但按钮背景不对,继续展开按钮自身的 background-color 来源,排查硬编码、局部 Token 或更高优先级的声明;若根变量就错,先找影响根元素的覆盖规则。

删除错误覆盖并做回归验收

修复时删除应用样式表中重复维护的 Dark 主色声明,使 generated/tokens.css 成为该语义变量在本模式下的实际来源;不要直接修改生成文件,因为下次构建会覆盖手工改动。提交源样式修复,重跑构建及发布流程,再使用 Network 确认新 CSS 已加载。

在相同的 Dark 页面重新执行上述 Console 代码,预期输出变为:

text
{"theme":"dark","rootToken":"#93c5fd","buttonToken":"#93c5fd","background":"rgb(147, 197, 253)"}

最后分别检查 Light、Dark 模式的主按钮默认态、Hover、Disabled;在 DevTools 切换模式后再次观察 Computed,并与 Figma 对应模式核对。验收记录至少保留设计变量值、构建产物片段、线上 CSS 响应和最终计算值四份证据。若生产环境仍显示旧色,优先比对资源版本与缓存,而不是继续修改 Token 数值。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查设计稿与线上样式不一致

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

登录哪都通