drift-detection

漂移检测

用于识别和分类设计系统漂移的技能——即设计系统的预期与使用该系统的产品中的实际实现之间不断累积的差距。生成漂移报告，为每项发现标注严重程度、来源分类和建议的应对措施。

开始之前：验证参考资料

确认此技能 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.* — 覆盖漂移发现的严重程度
• system.styling — 预先选择令牌漂移检测方式（CSS 变量、SCSS、Tailwind、CSS-in-JS）
• integrations.* — 漂移对比数据（见下文）
• recurring.* — 漂移趋势（见定期工作流）

自动拉取集成数据

Figma MCP（integrations.figma.enabled: true）：

• 从 integrations.figma.file_key 指定的已发布库中读取组件规范
• 将其用作设计侧参考，用于检测视觉漂移和 API 漂移
• 对比 Figma 组件属性与代码组件 props，无需手动编写规范即可检测 API 漂移

GitHub（integrations.github.enabled: true）：

• 在 integrations.github.repo 中搜索表明存在漂移的代码模式（参见知识说明中的 GitHub 注意事项）：
  • 设计系统包之外的硬编码颜色值
  • 本地重新实现的组件（在系统源代码之外使用的组件名称）
  • 使用 CSS !important 覆盖设计令牌属性的令牌覆盖
• 拉取近期 PR，识别在设计系统包之外更改的组件
• 通过对比各使用方在 package.json 中声明、并在锁定文件中解析出的设计系统版本与最新发布版本（npm view [package] version）来检测版本落后。提交历史无法表明使用方实际运行的是哪个版本

Chromatic（integrations.chromatic.enabled: true）：

• 拉取视觉差异数据——在设计系统发布周期之外接受了视觉变更的组件，可能存在视觉漂移
• 较高的变更接受率可能表明团队正在接受漂移，而不是纠正漂移

定期工作流

遵循配置与定期运行说明中的定期运行流程。此技能的特定要求：

• 持续性偏离（持续 2 个或更多周期）：提高严重程度。
• **分类变化：**标记分类发生变化的偏离，例如从意外偏离变为有意差异。
• 在报告中添加“偏离趋势”部分：
  • 偏离总数：增加 / 稳定 / 减少
  • 偏离速度：新增偏离的累积速度与解决速度相比如何？
  • 分类趋势：构成是否正转向更多系统缺口（E）或意外偏离（C）？

第 1 步：定义范围

询问或确认以下内容（自动提取已回答的问题可跳过）：

• 正在评估什么？（特定产品、特定组件集、特定令牌范围或整个系统）
• 有哪些可用于比较的来源？（Figma 文件、代码库、文档、Storybook、任何格式的令牌文件——JSON、CSS 自定义属性、SCSS 变量、Tailwind 配置）
• 是否有已怀疑存在偏离的特定区域？
• 是否有已知的有意差异应当记录，而不是标记为问题？

范围越具体，报告就越具可操作性。对“整个系统”进行偏离检测能发现模式，但会产生一长串优先级信号有限的问题。将范围限定在特定产品或特定组件类别，能得到更具可操作性的结果。

**偏离需要一个使用方。**如果能接触到的代码只有设计系统自身的代码库，那么就没有可供比较并发生偏离的对象。请停止并说明这一点，然后指出适用的技能：token-compliance 用于检查系统自身组件中的原始值，component-audit 用于检查库内部的重复和缺口，design-to-code-check 用于针对规范检查单个组件。请先索取使用方产品（路径、代码库或产品的 Figma 文件），再继续。

**小型系统说明（少于 5 个组件）：**对于此规模的系统，将范围设为整个系统——无需抽样。小型系统中的偏离模式有所不同：团队通常更小、协作更一致，因此偏离较少是意外造成的，更可能是有意差异（分类 A）或系统缺口（分类 E）——不过，二者仍都需要提供第 4 步要求的证据。将输出简化为逐组件检查清单，而非完整的偏离报告。如果所有组件均未发现偏离，请将此作为调查结果，并建议定期审查。

第 2 步：确定参考基准

偏离总是相对于某个基准而言。请确认所用的真实来源：

• 设计系统的 Figma 组件库
• 特定版本的已发布组件包
• 每个组件的文档规范
• 以上所有来源（它们之间的不一致本身就是偏离信号）

如果没有明确且唯一的真实来源，这本身就是一项调查结果，应列在报告顶部。

第 3 步：识别偏离实例

从以下四个维度进行评估：

视觉偏离

组件或模式的视觉呈现与设计系统参考之间的差异。包括间距、颜色（尤其是非令牌值）、排版、圆角、阴影和图标用法。

对于每个实例：写明组件或模式的名称，描述视觉差异，并指出其看起来是有意还是意外造成的。

行为偏离

交互行为方面的差异——状态转换、动画、时序、键盘行为、焦点管理——与设计并记录的组件行为相比有何不同。

如果没有直接测试，行为偏离通常最难发现，但它带来的风险最高，因为其中包括无障碍功能退化。

API 漂移

组件的实现与设计系统发布的 API 使用了不同的属性、属性名或属性语义。团队在本地实现组件而非使用系统中的组件时，最常出现这种情况；如果本地版本是在系统组件推出前构建的，之后也从未迁移，也会出现这种情况。

令牌漂移

在应引用设计令牌的地方使用了原始值、本地令牌覆盖与语义意图相冲突，以及不同实现中令牌名称使用不一致。

逐文件搜索原始值是 token-compliance 的职责，包括其样式方法规则和正向对照。不要在此处重复实现。如果产品已有 token-compliance 报告，请将其违规表作为令牌维度导入。如果没有，请先对使用该系统的产品运行 token-compliance，再继续。这项技能补充的是对每项违规进行使用方与系统的对照分析：若原始值与某个系统令牌解析后的值相同，通常属于 C 类或 D 类（有人输入了数值，而不是令牌名称）；若原始值与系统中的任何值都不匹配，则属于 A 类或 E 类，需要遵循步骤 4 中的证据规则。本地覆盖系统令牌（在产品中重新定义 --color-action-primary: #...、对由令牌驱动的属性使用 !important）不在 token-compliance 的职责范围内，因此请在此处搜索此类情况，并使用正向对照。

步骤 4：对每项漂移进行分类

在指定处理方式前，对每项发现进行分类。A、C 和 D 类是关于团队意图的判断，仅凭代码通常无法得知。只有满足其证据规则时才进行分类；否则标记为未分类 — 需要团队意见，并列出哪些信息可以帮助确定类别。

A 类：有意偏离 产品团队基于明确原因，决定有意偏离系统。这可能是合理的（系统无法满足此使用场景），也可能是对系统的贡献机会（该需求确实存在，应该纳入系统）。 *所需证据：*记录该决定的代码注释、ADR、PR 描述或团队声明。

B 类：版本滞后 该实现与设计系统的旧版本一致。系统已更新，产品却没有。这并非错误，而是常见的自然演变；但如果不处理，就会逐渐累积成迁移负担。 *所需证据：*使用方安装的版本（锁文件）低于最新发布版本，且发生漂移的行为与已安装版本一致。

C 类：意外漂移 实现无意间偏离了系统。最常见的原因是系统版本尚不可用时在本地实现组件，之后却没有迁移到系统版本。 *所需证据：*能证明该偏离并非有意选择的信息，例如本地版本早于系统版本（Git 历史），且没有任何决定记录；或者团队予以确认。

D 类：理解有误 实现反映了对文档或规范的误读。使用方以为自己正确使用了系统，却不知道实际并非如此。 *所需证据：*用法符合对文档的一种合理解读（引用含糊的段落），或者团队予以确认。

E 类：系统缺口 漂移的存在是因为系统没有产品团队所需的功能。偏离的实现是产品团队为解决设计系统缺口而采用的方案，并非错误。 *所需证据：*在使用方当前运行的版本中，没有系统组件或令牌能够满足该需求。

未分类 — 需要团队意见 现有证据不足以支持上述任何类别。报告该发现及其严重程度，并提出能够确定类别的问题（“CheckoutCard 上的 12px 内边距是有意设置的吗？”）。不要猜测。

步骤 4a：漂移影响严重程度加权

从基础严重程度开始，然后进行加权：

• 🔴 严重 — 关键路径上出现可访问性或行为回归（结账时焦点丢失、登录时未播报错误）
• 🟠 高 — 其他位置出现可访问性或行为回归，或令牌漂移导致主题失效（采用主题的产品中出现硬编码颜色）
• 🟡 中 — 用户或开发者会注意到的视觉或 API 差异，但没有功能影响
• ⚪ 低 — 单个实例中的外观差异，或非面向用户的实用工具中的漂移

然后根据组件的关键程度加权：

关键路径组件（核心导航、身份验证、结账、主要数据录入）——此处的漂移会自动提升一个严重程度级别。结账组件上的中等程度问题会升级为高。

高流量组件（按钮、表单输入框、卡片、模态框）——此处的漂移会影响最多用户。评估结果保持不变，但要标明影响范围。

实用工具组件（布局包装器、间距辅助工具、图标容器）——此处的漂移风险较低。如果组件不面向用户，中等程度的问题可以降为低。

按分类采取的建议措施

将每个漂移实例分类后，按相应方式处理：

分类	主要处理方式	接下来运行的技能
A — 有意差异	记录为决策记录	decision-record
B — 版本滞后	指向该版本的迁移指南；如果差异可通过机械方式处理，则提供 codemod	codemod-generator，或用于令牌重命名的 token-migration 命令
C — 意外漂移	修复实现，并审查未能防止漂移的文档	design-to-code-check
D — 误解	更新文档，并通知受影响的团队	change-communication
E — 系统缺口	转入贡献工作流	contribution-workflow
未分类	向团队提出能够确定分类的问题	—

步骤 4b：按版本滞后分组

对于归类为 B 的漂移，按引入变更的版本分组（查看系统的 CHANGELOG，或检查使用方已安装版本与最新版本之间的 git 标签）。对每个分组，根据证据说明三点：使用方中有多少文件受到影响（计数）；变更是机械性的（codemod 可以完成的重命名或属性替换），还是结构性的；以及该版本是否附带迁移指南。没有迁移指南的破坏性版本发布本身就是一项治理问题；请单独标出。不要估算工时或用 T 恤尺码估算规模；团队需要据以规划的是文件数量，以及对变更属于机械性还是结构性的判断。

步骤 4c：跨系统漂移（仅当范围涉及多个系统时）

如果用户将两个或更多设计系统（品牌系统、平台系统）纳入范围，也要相互比较：不再一致的共享基元、解析为不同意图的相同语义名称，以及 API 不同但名称相同的组件。若范围仅涉及一个系统，则跳过此步骤，并在范围部分说明。

步骤 5：生成漂移报告

以一句标题句开篇。示例：“漂移程度中等，且大多是意外造成的——有 3 个组件偏离了系统，其中 2 个似乎是因为团队不知道该系统版本的存在。以下是完整情况。”

---

漂移检测报告

日期： [日期] 主题： [评估内容] 参考来源： [评估所依据的内容] 评估方法： [直接检查 / 据报 / 混合]

---

摘要

整体漂移情况如何？系统是在受控地演变，还是漂移在不断累积？最重要的发现是什么？请以向同事汇报的口吻撰写，而不是写成合规报告。

---

漂移发现

对于每项发现：

ID	位置	维度	分类	严重程度	描述	建议措施
DF-01	[仓库路径:行号，或 Figma 节点 ID；以及组件]	[视觉/行为/API/令牌]	[A–E / 未分类]	🔴/🟠/🟡/⚪	[具体描述：系统值和使用方的值]	[具体措施]

位置是证据，而不是标签：应提供读者可以打开的文件和行号，或 Figma 节点。没有位置信息的发现只是猜测，应列入“未分类”清单，并附上可用于确认的问题。

严重程度说明： 🔴 严重 · 🟠 高 · 🟡 中 · ⚪ 低（评级标准见步骤 4a）

---

按分类列出的发现

有意差异（A） 列出发现。对于每项发现，注明它是贡献候选项还是已接受的例外。如果是已接受的例外，应将其记录为决策记录。

版本滞后（B） 列出发现。按组件或令牌集分组。指出一次迁移冲刺能否解决其中大部分问题，还是这些问题过于分散，无法协调迁移。

意外漂移（C） 列出发现。这些应优先修正，因为它们并非有意为之——产品团队会希望了解这些情况。

理解偏差（D） 列出发现。这些表明存在文档或沟通方面的缺口。应修正相关发现，并审查未能避免问题的文档或入门引导。

系统缺口（E） 列出发现。这些是贡献候选项。如果多个产品都存在相同缺口，将其纳入系统的理由就更充分。请交叉引用贡献工作流。

未分类——需要团队意见 列出发现，并附上可用于判定各项发现分类的问题。

---

根本原因模式

跳出单项发现，识别其中的模式：

• 是否存在反复出现的漂移类型，表明有系统性问题？
• 是否有特定团队或产品频繁出现在发现中？
• 是否有特定组件或令牌比其他项更容易发生漂移？

根本原因模式比单项发现更便于采取行动。解决根本原因可以防止未来发生漂移；解决单项发现只能修正当前状态。

---

建议措施

按优先级排列：

1. 严重和高严重程度的发现：优先处理，不受分类影响
2. 系统缺口发现：转交至贡献工作流
3. 版本滞后发现：安排迁移冲刺，或纳入下一个发布周期
4. 理解偏差发现：更新文档并通知受影响的团队
5. 有意差异：记录尚未登记的例外
6. 未分类的发现：向负责团队提出待解决的问题

---

范围

• 已检查：[实际阅读过的仓库、软件包、Figma 文件及版本]
• 未检查：[无法访问的产品或来源，因此未对此发表评论]
• 如何检查“未发现”：[例如，令牌漂移搜索的阳性对照——如果报告没有声称不存在相关情况，则省略此项]
• 假设：[任何被视为既定事实而未加验证的内容]

最后附上以下结束语。

---

步骤 6：视觉偏差对比（如果 Figma Console MCP 可用）

如果已连接 Southleft 的 Figma Console MCP（检查是否有 figma_capture_screenshot 和 figma_get_component_for_development 工具），请使用设计侧的视觉证据增强偏差报告。

捕获设计参考： 使用 figma_capture_screenshot 捕获 Figma 中每个偏差组件的当前状态。该工具使用插件的 exportAsync API，捕获的是实时状态，而非缓存的云端渲染结果。这是视觉对比中设计侧的真实依据。

捕获设计规范： 使用 figma_get_component_for_development 获取面向开发优化的设计数据及渲染图像。这仍属于设计侧——它以便于映射到实现属性的形式提供规范，而非实现本身。实现侧可使用 Storybook 或 Chromatic 快照（如果有），也可以描述代码。

报告中的视觉差异： 对于每项视觉或 API 偏差发现（任何类别），都应附上 Figma 截图，以及实现侧的快照或代码渲染效果描述。这样读者便能直观了解差距，而不只是看到属性不匹配的文字描述。

连接的是标准 Figma MCP（只读）时： 可通过 REST API 获取截图，但截图反映的是上次发布到云端的状态，而非当前实时状态。请注明这一限制——如果 Figma 文件有尚未发布的更改，截图可能无法反映最新的设计意图。

---

结束语（每份报告都要包含）

报告结尾请写上：

关于上下文的说明： 此分析会指出实现与系统不同之处，但不一定总能判断原因。分类体系（有意为之、意外偏差、版本滞后、理解有误、系统缺口）只是一个起点。如果有任何实例被错误分类，请告知我——您的更正有助于提高今后偏差检查的准确性。目标是区分需要修复的偏差与需要记录的偏差。

---

质量检查

• 每项发现都有分类和建议操作，而不只是描述
• 每项发现都有读者可以打开的位置（文件和行号，或 Figma 节点）
• Token 维度的发现取自 token-compliance 的表格，而非通过第二次搜索得出；报告需引用其 ID
• 如果范围内没有使用该系统的产品，则运行已停止并进行了重定向
• 严重程度评级有具体影响作为依据，而非泛泛指定
• 存在根本原因模式部分，且内容超出了单项发现列表
• 系统缺口类发现与错误有所区分——其偏差填补了真实系统缺口的产品团队，不应被视为做错了事
• 报告区分了应予纠正的偏差与应记录为可接受差异的偏差
• 如果已捕获视觉对比，每项发现都包含 Figma 参考截图
• 每项 A、C 或 D 分类都引用其规则要求的证据；其他情况均标记为未分类
• 包含 Scope 区块和关于有意偏差的结束语