UI 视觉设计 / 系统课时

用验收矩阵核对设计代码一致

用验收矩阵核对设计代码一致

同一款按钮在设计稿里符合规范,落到前端却可能出现尺寸偏差、键盘焦点缺失、禁用态仍能触发操作等问题。通过组件验收矩阵,可以把设计属性转换为可执行、可记录、可复测的检查项,明确每条差异的责任归属和关闭条件。

学习目标

  • 将组件的变体、尺寸、状态和内容边界转换为具体的验收场景。
  • 对照 Figma 设计实例与前端组件,分别核对视觉属性、交互行为和内容边界。
  • 使用可运行的检查脚本记录差异,并完成问题归属、修复和复测。

从设计属性建立验收矩阵

以项目中的 Button 组件为例,假设设计规范定义了两种变体 Primary、Secondary,两种尺寸 Small、Medium,以及 Default、Hover、Focus、Disabled、Loading 五种状态。

完整组合共有 2 × 2 × 5 = 20 种,但并非所有组合都需要相同的测试深度。先覆盖全部变体与尺寸的默认状态,再针对键盘焦点、禁用行为、加载状态和长文案等高风险场景增加检查项。如果不同变体的交互实现不共用同一逻辑,还应分别验证。

下面是项目示例的验收矩阵,数值属于本项目约定,并非所有设计系统通用的尺寸标准。

编号 设计场景 主要验收项 通过标准
BTN-01 Primary / Medium / Default 尺寸与间距 最小高度 40px、水平内边距 16px、圆角 8px
BTN-02 Primary / Medium / Focus 键盘焦点 Tab 可到达,焦点轮廓宽 2px、偏移 2px
BTN-03 Primary / Medium / Disabled 禁用行为 原生 disabled 生效,不能触发点击,Tab 顺序跳过
BTN-04 Secondary / Small / Default 外观样式 最小高度 32px、水平内边距 12px、边框 1px
BTN-05 Primary / Medium / 长文案 内容边界 容器宽 160px 时文字允许换行,不裁切、不产生横向溢出

矩阵中的每一行代表一个可以独立判定通过或失败的场景。BTN-01 检查静态尺寸,BTN-02 和 BTN-03 检查交互,BTN-05 检查内容变化后的布局。长文案场景使用最小高度而不是固定高度,避免文本换行后被裁切。

每条验收记录还应补充设计节点链接、前端组件场景标识、设计版本、代码版本、验收人员和结果。没有明确设计依据的属性不能直接判定代码错误,应先标记为待确认。

对照设计实例与前端实现

验收必须固定比较对象。设计师确认 Figma 中的组件主实例和对应变体,开发人员提供前端可复现的组件场景,例如 Storybook 中的 Button 示例。双方使用同一份验收矩阵,而不是分别依据截图作主观判断。

设计实例、验收矩阵与前端实现的数据对照流程

实际核对时按照以下顺序操作:

  1. 在 Figma 中选中目标组件实例,确认 Variant、Size、State 等属性,读取宽高、内边距、圆角、颜色和文字样式。将设计令牌名称与最终解析值一并记录。
  2. 打开对应的前端组件场景。以 Chrome 桌面浏览器、1280 × 800 视口、页面缩放 100% 作为本次验收环境,并确认字体已经加载。
  3. 右键检查按钮,在 Chrome DevTools 的 Elements → Computed 面板读取实际计算样式,例如 min-height、padding-left、border-radius 和 outline-width。
  4. 使用 Tab、Enter、Space 和鼠标操作验证状态行为。禁用按钮应无法触发动作;焦点状态应在键盘导航时正确出现。
  5. 将按钮父容器限制为 160px,替换成长文案,观察换行、最小高度及溢出行为,再填写矩阵结果。

用脚本检查可量化的验收项

对于尺寸、内边距、轮廓宽度、禁用属性和事件触发次数,可以把设计期望与实际测量数据记录为结构化对象,再自动检查是否一致。键盘焦点顺序、文字裁切和屏幕阅读器反馈仍需要实际交互验证,不能只依赖数值比较。

下面使用 Node.js 18 或更新版本运行一个不依赖第三方包的验收脚本。示例中 design 表示已确认的设计基准,actual 表示一次假设验收记录的实测值;脚本本身不会自动连接 Figma 或浏览器。

将代码保存为 check.mjs:

js
const cases = [
  {
    id: 'BTN-01',
    design: { minHeight: 40, paddingX: 16, radius: 8 },
    actual: { minHeight: 40, paddingX: 16, radius: 8 }
  },
  {
    id: 'BTN-02',
    design: { outlineWidth: 2, outlineOffset: 2 },
    actual: { outlineWidth: 1, outlineOffset: 2 }
  },
  {
    id: 'BTN-03',
    design: { disabled: true, clickCount: 0 },
    actual: { disabled: true, clickCount: 0 }
  }
];

let failed = 0;

for (const row of cases) {
  // 只比较当前验收场景明确声明的字段。
  const diffs = Object.keys(row.design)
    .filter(key => row.design[key] !== row.actual[key])
    .map(key => `${key}: 设计=${row.design[key]}, 代码=${row.actual[key]}`);

  if (diffs.length > 0) {
    failed++;
    console.log(`${row.id} FAIL ${diffs.join('; ')}`);
  } else {
    console.log(`${row.id} PASS`);
  }
}

console.log(`通过 ${cases.length - failed}/${cases.length}`);

// 存在未通过项时返回非零退出码,便于接入CI。
process.exitCode = failed > 0 ? 1 : 0;

在终端执行 node check.mjs。

预期输出:

text
BTN-01 PASS
BTN-02 FAIL outlineWidth: 设计=2, 代码=1
BTN-03 PASS
通过 2/3

脚本会以退出码 1 结束,因为 BTN-02 存在差异。这不是运行异常,而是验收门禁正确发现问题。修复后将 BTN-02 的实际轮廓宽度重新测量并更新为 2,再执行检查,三个场景应全部通过,退出码变为 0。

实际项目可以从浏览器自动化测试或测试报告中导出实测数据,再使用相同的字段比较逻辑。不要把设计期望值直接复制为实际值,否则脚本虽然显示通过,却没有完成真实验收。

记录差异归属并完成复测

发现差异后,不能只写一句“按钮与设计不一致”。一条可以交付给责任人的问题记录,至少需要包含场景编号、设计基准、实际结果、复现步骤、责任归属和复测状态。

例如 BTN-02 的问题单可以这样填写:

字段 记录内容
场景编号 BTN-02
设计基准 Button / Primary / Medium / Focus,轮廓 2px、偏移 2px
代码实测 轮廓 1px、偏移 2px
复现步骤 打开 Button 场景,按 Tab 聚焦,检查 Computed 样式
差异归属 前端实现
处理动作 将焦点轮廓改为设计规定值,检查是否使用正确的语义令牌
当前状态 待修复

差异归属按证据判断:设计规范缺少某个状态或存在互相冲突的定义,由设计负责人补齐;规范清楚但前端实现不同,由开发负责人修复;字体未加载、浏览器缩放或测试数据错误,由验收人员先修复测试环境;需要更改原有设计规则的情况,则进入需求变更与设计审批,不能直接把代码现状改写成设计标准。

验收关闭建议使用以下条件:

  • 关键交互问题,例如禁用态仍执行操作、键盘无法到达必要控件、重要文本被裁切,必须修复后重新验证。
  • 可量化属性必须符合已批准的设计约束;如需容差,应在验收规则中预先定义,不能发现差异后临时放宽。
  • 每条问题都有修复版本、复测结果和相关证据。需要例外放行时,必须记录批准人、原因和后续处理期限。

复测 BTN-02 时,除了重新运行脚本,还应在真实浏览器中通过 Tab 触发 :focus-visible,确认轮廓宽度正确、没有被父容器裁切,并且焦点依然清晰可见。单纯修改验收数据不能算作修复。

最终交付的验收矩阵应保留每个场景的设计依据、实测值、通过状态及差异处理记录。这样组件版本更新后,团队可以重新执行相同的检查项,准确判断哪些行为保持一致、哪些属性发生了回归。

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

目录与阅读设置

阅读设置

17

记录一个想法

用验收矩阵核对设计代码一致

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

登录哪都通