audit-design-system

审核设计系统

检查 Figma 节点，确认设计是否未能妥善集成到设计系统中。

此技能为只读。如果用户随后要求执行写入操作，下游技能应通过 figma-use 风格的辅助工具使用 use_figma，以适应宿主环境的要求。

输出格式选择

• 以用户的明确要求为准：
  • 如果用户要求 --json 或 JSON，则输出原始 JSON（不加 Markdown 代码围栏，也不添加说明文字）。
  • 如果用户要求 --markdown、Markdown 或特定的易读格式，则输出易读的 Markdown 报告。
• Codex Desktop 应用：默认输出原始 JSON。
• Codex CLI 和其他聊天式环境：默认输出易读的 Markdown 报告。
• 供机器消费的审核界面：默认输出原始 JSON。
• 环境不明确：默认输出 Markdown。

工作流

1. 解析 Figma 输入。 接受完整的 Figma URL，或 fileKey 和 nodeId。 必要时，将节点 ID 从 72-293 规范化为 72:293。

2. 使用 Figma MCP 只读工具获取最低限度的必要证据。 调用 get_design_context，获取正在审核的确切节点。 调用 get_screenshot 进行视觉确认。 调用 get_variable_defs，查看实际绑定了哪些变量。 适用时调用 get_code_connect_map。 如果被审核的节点较大、重复出现或类似画板，且需要先映射嵌套实例再深入检查，则调用 get_metadata。 如果已识别出可能未系统化的基础元素，且有现实可能从已审核的设计系统中找到具体替代项，则调用 search_design_system。

3. 审核系统化方面的问题，而非视觉偏好。 留意本应继承设计系统，却由本地自行构建的部分。 每项发现都应以 Figma 中可见的结构为依据：实例、重复的画框、原始值、变体偏差或缺失的令牌绑定。 宁可不报告，也不要提出依据薄弱的发现。

4. 证据充分时，建议替代候选项。 识别出可能自定义的基础元素后，使用 search_design_system 查找已审核设计系统中最接近的组件系列。 只有当结构和命名足以支持匹配，而非仅凭截图相似度时，才纳入候选项。 如果搜索结果嘈杂或含糊，则省略候选项，不要猜测。

5. 根据环境以适当格式呈现发现。 Codex Desktop 和供机器消费的审核界面使用 JSON；Claude Code CLI 和其他聊天式环境使用 Markdown（参见上文“输出格式选择”）。

6. 用户需要修复时，将任务转交给合适的下游技能。 如果需要修复某个具体的违规节点，优先使用 fix-design-system-finding。 如果用户希望对整个屏幕进行更广泛的处理、需要协调修复多个部分，或要在写入前通过审核确定范围，则优先使用 apply-design-system。

应标记的情况

• 使用临时创建的画框，而非组件实例，重新创建共享 UI 基元。 常见对象：按钮、图标按钮、卡片、警告框、胶囊标签、标签、头像、统计信息块、标签栏、导航栏、FAB、列表行。

• 重复出现的同级结构，显然应合并为一个可复用基元。 示例：三个内容不同但几乎相同的统计信息块。

• 当设计系统的其他部分使用变量时，仍使用硬编码的视觉值。 常见对象：填充色、描边、文本颜色、圆角、间距、字体排版、阴影。 仅当证据明确时才标记，例如：原始十六进制值或自定义几何形状与使用设计令牌的同类元素并列出现。

• 使用自定义画框构建全局导航或其他高影响力模式，而非使用系统组件。 应积极标记，因为此类偏差会扩散到许多屏幕。

• 名义上属于同一组件的变体出现偏差。 示例：本地编辑按钮的尺寸、描边宽度或圆角异常，与预期的图标按钮基元不符。

不应标记的情况

• 纯粹的审美偏好。
• 文案或产品决策。
• 可以合理地保留为特定屏幕专属的布局选择。
• 底层基元已组件化且使用设计令牌的一次性组合。
• 需要基于设计库未记载的假设才能成立的说法。

证据标准

每项发现都必须回答以下两个问题：

1. 有哪些具体的 Figma 证据表明此处的系统化处理不正确？
2. 这为何会影响传播、一致性、主题适配或维护？

有力的证据包括：

• 本应是实例的节点却是普通画框
• 多个同级元素重复相同结构
• 在应使用变量或标准基元的地方出现原始颜色值或几何值
• 全局模式由自定义元素搭建

薄弱的证据包括：

• “这看起来是自定义的”
• “通常我会把它做成组件”
• 仅凭截图的视觉效果作出的任何判断，缺少结构性依据

替换建议规则

当发现涉及缺少共享基元时，尽量附上一条可能的替换建议。

在已明确缺少的对象类别后，使用 search_design_system，例如：

• 自定义头像组
• 定制统计信息块
• 本地警告卡片
• 手工搭建的导航项

仅在以下条件满足时提出替换建议：

• 节点的用途明确
• 搜索结果属于相关的库或已审查的文件上下文
• 候选组件在结构上适用于该发现

建议措辞示例：

• 这个自定义头像画框可能可以替换为库 X 中的 Avatar。
• 这些重复的统计信息块似乎对应于库 X 中的 Metric item。

不要夸大其词：

• 除非证据明确，否则不要声称建议的组件一定正确
• 不要强行在每项发现中都添加替换候选项
• 不要仅仅因为搜索结果将其列在首位，就推荐来自无关库的组件

输出格式

JSON 输出

选择 JSON 输出格式时，请严格按以下 JSON 结构返回，不要使用 Markdown 代码围栏，也不要添加其他说明：

{
  "findings": [
    {
      "title": "<= 80 chars, imperative>",
      "body": "<valid Markdown explaining why this is a problem>",
      "confidence_score": 0.0,
      "priority": 0,
      "code_location": {
        "absolute_file_path": "/figma/<fileKey>/nodes/<nodeId>",
        "line_range": {
          "start": 1,
          "end": 1
        }
      }
    }
  ],
  "overall_correctness": "patch is correct" | "patch is incorrect",
  "overall_explanation": "<1-3 sentence summary>",
  "overall_confidence_score": 0.0
}

Schema 说明：

• 只要发现一项或多项设计系统集成问题，就设置 overall_correctness: "patch is incorrect"。
• 仅当没有发现问题时，才设置 overall_correctness: "patch is correct"。
• 对每项发现，将 code_location.absolute_file_path 设置为 /figma/<fileKey>/nodes/<nodeId>，并指向问题最具体的节点。
• 始终将 line_range.start 和 line_range.end 设置为 1。

人类可读的 Markdown 报告

当选择的输出格式为 Markdown 时，请提供格式化的 Markdown 报告，其中包含：

1. 标题部分：

   • 正在审查的文件名和节点
   • 总体结论：✅ 通过 / ⚠️ 需要改进 / ❌ 存在重大问题
   • 置信度百分比

2. 摘要： 用 2-3 句话说明整体情况

3. 发现问题表格： 概览问题并标注优先级

   • 🔴 严重（优先级 3）：严重的库级或导航级问题
   • 🟠 高（优先级 2）：重要的可复用基元或令牌化问题
   • 🟡 中（优先级 1）：中等程度的系统偏差
   • ⚪ 低（优先级 0）：细枝末节或影响较小的一致性问题

4. 详情部分： 展开说明每项发现，包含：

   • 问题所在（提供 Figma 结构中的具体证据）
   • 问题影响（对维护、一致性和主题化的影响）
   • 在 search_design_system 支持时，提供可能的替代方案
   • 受影响的节点 ID，供参考

5. 建议： 按优先级排列的待办事项

输出规则

• 聚焦于信号最强的问题。通常列出 0-6 项。
• 标题使用祈使语气，且不超过 80 个字符。
• 每项发现都必须关联到具体的节点 ID，以便用户在 Figma 中定位。
• 对于 JSON 输出，不要编造文件系统路径。请严格使用 /figma/<fileKey>/nodes/<nodeId>。
• 如果替代方案可信，请在问题详情中注明。

审查启发式

按以下方式使用 priority：

• 0：细枝末节或影响较小的一致性问题
• 1：中等程度的系统偏差
• 2：重要的可复用基元或令牌化问题
• 3：严重的库级或导航级问题，可能造成广泛影响

按以下方式使用 confidence_score：

• 0.9-1.0：有直接的结构证据
• 0.7-0.89：根据重复情况和附近的令牌用法得出的有力推断
• 0.5-0.69：证据合理但不完整；最好省略

画板和屏幕范围

对于单个屏幕：

• 检查根节点
• 深入检查重复出现或影响范围较大的子节点
• 将问题关联到最具体的违规节点

对于画板或较大的页面：

• 首先使用 get_metadata 确定候选屏幕或重复模块
• 仅审查最相关的节点，不要试图审计所有内容
• 确保问题范围明确且有证据支持

示例触发语句

• “审查此 Figma 屏幕的设计系统集成情况”
• “审计此画板，检查是否缺少组件用法”
• “检查此设计是否正确使用令牌”
• “/audit-design-system https://figma.com/design/...”
• “/audit-design-system --json https://figma.com/design/...” （用于 JSON 输出）

移交指南

审查后按以下规则分派：

• 一项具体发现且修改范围较窄：使用 fix-design-system-finding
• 多项发现可归并为更广泛的屏幕或区域协调工作：使用 apply-design-system

不要强行将每项审查结果都交由单项问题修复技能处理。有些审查更适合作为范围发现，为更广泛的应用工作做准备。