design-to-code-check

设计到代码核查

一项用于审查设计规范与代码实现之间一致性的技能，并按维度和严重程度分类，生成结构化的差异报告。

开始之前：验证参考资料

确认此技能 frontmatter 中 references: 列出的每个路径都相对于此 SKILL.md 文件存在。如果有任何路径缺失，请停止：安装不完整，通常是因为扁平化安装器（例如 npx skills install）未复制仓库根目录下的 knowledge-notes/ 目录。告诉用户通过 1-INSTALL.md 中的方法重新安装，并从安装根目录运行 verify-install.sh。只有在用户明确要求继续时，才可在没有这些参考资料的情况下继续；此时请在输出中说明报告是在未使用此软件包参考资料的情况下生成的。

上下文

设计到代码的一致性审查会发现两类不同的问题。第一类是实现错误——开发者误将实现做成了与规范不同的样子，或者是因为规范不明确。第二类是规范歧义——设计未能完整定义行为，导致开发者无法正确实现，只能做出合理猜测，而这个猜测后来被证明是错误的。

这两类问题都很重要，但需要采取不同的应对方式。实现错误需要在代码中修正。规范歧义需要在设计中修正并记录下来，以免再次出现同样的猜测。

此技能会生成一份区分这两类问题的报告。

---

配置

如果存在 .ds-ops-config.yml，请遵循配置与重复执行知识说明（../../knowledge-notes/configuration-and-recurring.md），了解如何加载配置、处理集成回退和重复运行。此技能会读取：

• severity.* — 差异严重程度覆盖项，尤其是 specification_gap 和 missing_interaction_state
• system.framework 和 system.styling — 预先选择特定框架的核查指南
• integrations.figma — 设计规范（见下文）
• integrations.chromatic — 作为补充信号的视觉回归数据
• integrations.github — 组件源码
• gates.design_to_code — 如果作为 component-to-release 的一部分运行，则用于确定哪些发现会阻止发布

自动拉取集成数据

Figma MCP（integrations.figma.enabled: true，或请求中包含 Figma 链接）：

• 官方 Figma MCP：对组件节点调用 get_design_context，获取其属性、变体、布局和样式；调用 get_variable_defs，获取该节点绑定的变量，这些变量用于命名规范中的设计令牌。两者都需要指定选区或节点，因此如果只提供了文件 key，请索取节点链接。
• Figma Console MCP：调用 figma_get_component_for_development 获取可用于开发的规范，调用 figma_capture_screenshot 获取渲染后的参考图。
• 记录每个 Figma 数据值对应的节点 ID；它将作为证据写入日志。

Chromatic（integrations.chromatic.enabled: true）：

• 拉取正在核查的组件最新视觉快照
• 将 Chromatic 基准图与当前实现之间的视觉差异作为维度 1–3（间距、颜色、排版）的补充信号：这些差异可提示人工审查进行确认，但绝不能据此判定某个维度一致

GitHub（integrations.github.enabled: true）：

• 如果组件实现在配置的仓库中，则直接拉取组件源码文件
• 确定组件的最后更新时间和近期变更，以便为发现的问题提供背景

步骤 1：收集比较材料

询问或确认以下信息（自动拉取已提供的信息可跳过）：

• 设计参考：Figma 文件链接、导出的规格，或文字描述的规格（如果已从 Figma MCP 拉取，则跳过）
• 实现参考：代码中的组件（React、Vue、Twig 等）、运行中实现的链接，或对已构建内容的描述。注意所采用的样式方案——CSS 自定义属性、SCSS 变量、Tailwind 工具类或 CSS-in-JS——因为这会影响检查时如何识别令牌引用。
• 正在审查的组件或屏幕
• 这是首次审查，还是上一轮修改后的后续检查
• 审查需特别关注的已知问题

如果设计和实现均可直接查看，则开始检查。如果只有一方可用，在报告中注明比较中另一方是推断得出的，而非直接检查的；依赖推断一方的维度应标记为“未检查”，而非 ✅。

步骤 1b：设计规格检查清单

开始检查前，确认设计规格足够完整，可以作为检查依据。规格不完整是导致 Type II（规格缺失）问题的根本原因；提前发现这些问题可以减少报告中的干扰项。

设计规格完整性检查清单：

• 已定义所有交互状态（默认、悬停、激活、聚焦、禁用、错误、加载中）
• 间距值使用令牌名称指定，而非像素值
• 颜色值使用令牌名称指定，而非十六进制值
• 字体排版使用字号比例令牌指定
• 至少为两个断点定义了响应式行为
• 已指定焦点指示器样式
• 已定义内容溢出行为（截断、换行、滚动）
• 已为移动端断点指定触控目标尺寸

**如果规格未通过此检查清单：**记录缺失项并继续检查。缺失的规格项会作为 Type II 问题出现在报告中；但提前指出这些问题有助于设定正确预期：这是设计缺陷，而非实现错误。

步骤 2：检查所有维度

从五个维度检查一致性。每个维度的目标不是列出所有差异——四舍五入处理中的细微亚像素差异不值得作为问题报告。目标是找出影响视觉一致性、用户体验或系统完整性的差异。

维度 1：间距与布局

检查：

• 内边距和外边距值：是否符合设计规格，是否使用了正确的间距令牌？
• 元素对齐：组件在容器内的水平和垂直对齐方式
• Flex 或 Grid 布局中元素之间的间距
• 组件尺寸：指定时检查宽度和高度；未固定时检查比例行为
• 响应式行为：实现是否按规格适配各断点？

如果规格指定了某个令牌（或系统中有对应的令牌），那么即使数值相同，实现中使用原始值也属于差异：它无法随主题变化，也无法与比例系统保持同步。应针对规格涵盖的属性记录问题。无论规格如何，对整个组件进行原始值扫描属于 token-compliance 的职责，它针对不同样式方案定义了何为令牌引用（SCSS 变量、var()、Tailwind 工具类与任意值、Emotion 辅助函数）；此处也应用相同规则，且检查范围不要超出规格指定的属性。

维度 2：颜色与视觉处理

检查：

• 背景色、边框颜色、文本颜色：是否引用了正确的设计令牌？
• 阴影与层级：数值和令牌引用是否正确？
• 边框圆角：数值是否正确，是否符合设计系统的圆角刻度？
• 不透明度：数值是否正确，是否应用于正确的元素？
• 渐变或背景处理（如有）

对于规范涵盖的属性，像维度 1 中那样标记原始颜色值。

维度 3：排版

检查：

• 字体系列：是否应用了正确的字体？
• 字号：字号是否正确，是否使用了正确的字体令牌？
• 字重：各文本角色的字重是否正确？
• 行高：行距是否正确，是否使用了正确的令牌或文档记录的数值？
• 字间距：指定的字距是否正确？
• 文本对齐：是否按设计采用左对齐、居中、右对齐或两端对齐？
• 文本截断或溢出处理：实现是否按照设计处理长字符串？

维度 4：交互状态

检查：

• 默认状态：视觉处理是否符合设计？
• 悬停状态：悬停时是否应用了正确的处理？
• 激活／按下状态：点击或触摸时是否采用了正确的处理？
• 焦点状态：是否应用了清晰可见且符合规范的焦点指示器（这也是无障碍检查项）？
• 禁用状态：是否采用了正确的弱化处理？
• 加载状态：如果设计中有，是否正确实现？
• 错误状态：如适用，是否正确应用并与相关元素正确关联？
• 空状态：如适用，是否正确实现？

交互状态是最常见的实现不足项。标记所有已设计但未在实现中体现的状态。

如何根据源代码检查状态。 当源代码中存在相应规则时，该状态即视为已实现：:hover、:focus-visible（或 :focus）、:active、:disabled 或 [disabled]／[aria-disabled="true"]、[aria-busy="true"] 或加载属性分支、[aria-invalid="true"] 或错误属性分支，以及模板中的空状态分支。阅读这些选择器和分支，并将其值与规范进行比较。已设计但没有规则或分支的状态属于“未实现”。这些规则渲染出的内容（屏幕上实际显示的悬停颜色、焦点环在背景上的可见度）只能在运行中的构建版本或 Storybook 中确认；如果没有使用这些环境，应报告源代码中对比出的数值，并将渲染标记为“未检查”，而不是 ✅。

维度 5：响应式与自适应行为

检查：

• 断点切换：布局是否在设计指定的断点处发生变化？
• 组件在窄视口下的表现：是否出现故障、溢出或意外截断？
• 触摸目标尺寸：交互元素是否至少为 24×24 CSS px（WCAG 2.5.8，AA）？44×44 CSS px 为 AAA 标准（2.5.5）。平台指南为 iOS 上的 44pt 和 Android 上的 48dp——采用规范或团队所选的标准，并说明采用的是哪一种。
• 内容重排：文本在所有断点下是否都能正确重排？

从源代码检查：阅读媒体查询、容器查询和响应式属性分支。要检查各断点下的渲染效果，需要运行中的构建版本；如果没有，应将渲染标记为“未检查”。

第 3 步：对每项差异分类

对于发现的每项差异，请进行分类：

类型 I：实现错误 规范明确，但实现与规范不符。应在代码中修正。

类型 II：规范缺失 设计未定义此情况。实现采用了合理的假设。更新设计规范，记录预期行为，然后使实现与之保持一致。

类型 III：系统不一致 设计本身与设计系统不一致（例如使用了非系统颜色、未采用间距刻度中的数值等）。问题出在设计文件，而非实现。

类型 IV：已接受的偏差 已知且有意为之的差异，通常是设计未考虑到的技术限制。如果尚未记录，应将其记录下来。

步骤 3b：移交（仅在请求时）

• 组件属性 API 契约（属性缺失、未记录或默认值不正确）：请运行 component-api-validator，而不是在此处检查。
• AI 描述偏差（六部分描述不再与构建内容一致）：请运行 ai-component-description 重新生成或验证。

步骤 4：生成报告

---

设计转代码检查报告

以一句标题句开篇，说明整体情况以及需要重点关注的方面。

组件/屏幕： [名称] 设计参考： [Figma 链接或描述] 实现参考： [链接或描述] 审核日期： [日期] 审核轮次： [首轮 / 后续轮次]

---

摘要

用一段话说明整体一致性如何。差异是否集中在某个特定维度？工作主要集中在少数几项修复上，还是需要大幅返工？

---

差异记录

ID	维度	类型	严重程度	元素	设计规范（证据）	实现情况（证据）	行动
DC-01	[维度]	[I–IV]	🔴 严重 / 🟠 高 / 🟡 中 / ⚪ 低	[具体元素]	[设计说明，附 Figma 节点 ID 或规范行]	[实现情况，附文件:行号]	[由谁执行什么操作]

每一行都必须包含两方面的证据。实现一侧没有文件和行号，或设计一侧没有节点 ID 或规范行的差异，不应记录在此处；应列在“未检查”下，并说明需要哪些信息才能进行检查。

严重程度参考：

• 🔴 严重：无障碍回归——焦点不可见（移除了轮廓且没有其他替代样式）、颜色对比度不足，或组件无法通过键盘访问或操作
• 规范中未定义焦点样式，但浏览器默认焦点环仍会显示的情况，属于 🟠 高严重程度的 II 类规范缺口，而非回归：焦点可见，只是没有设计过。判定为严重之前，请检查 CSS 中是否有 outline: none / outline: 0
• 🟠 高：用户可见，影响感知质量或易用性
• 🟡 中：系统不一致（硬编码值、令牌错误），需仔细检查才能发现
• ⚪ 低：不影响用户体验的细微差异

---

按维度汇总

每个维度用一行说明：✅ 通过（已对比、无差异，并注明证据）、⚠️ 警告（仅有中或低严重程度的差异）、❌ 未通过（存在任何严重或高严重程度的差异），或未检查（一侧依据推断得出或不可用——请说明是哪一侧）。帮助团队了解工作重点所在。

---

已发现的规范缺口

单独列出任何 II 类发现。这些问题需要设计师而非开发者采取行动，应作为设计任务跟踪，而不是开发缺陷。

---

范围

• 已检查： [实际进行对比的设计来源（Figma 节点、导出文件、描述）和实现文件或运行中的构建]
• 未检查： [任意一侧无法提供的状态、断点或变体]
• 如何检查“未发现问题”： [对于任何 ✅ 维度，说明进行了哪些对比——例如，针对每种状态将计算后的样式与 Figma 值进行对比]
• 假设： [例如，Figma 画板是当前已批准的规范]

如果这些差异中有任何一项是有意为之的（已知限制或商定的偏差），请告知我，我会在后续运行中将其记录为 IV 类。

质量检查

• 差异需同时说明设计规范和实际实现的内容，而不能只写「颜色不对」
• 明确区分 I 型（错误）和 II 型（规范缺失）问题——它们需要由不同负责人处理
• 彻底检查交互状态，而不只是默认状态
• 将令牌合规性纳入颜色和间距维度检查，而不只是检查视觉正确性
• 无法看见焦点、对比度不足、无法通过键盘访问等无障碍回归问题一律视为严重问题；未设计焦点样式但仍显示浏览器默认样式的情况属于高优先级问题
• 报告需具体到无需后续沟通即可采取行动
• 每项记录的差异都必须包含实现侧的文件和行号，以及设计侧的节点 ID 或规范行号
• 从源代码的选择器和分支中对比状态和断点；除非使用了构建产物或 Storybook，否则渲染情况均标记为「未检查」