fix-design-system-finding

修复一个设计系统问题

在 audit-design-system 已识别出具体问题后，使用此技能。

此技能的范围刻意设得很窄：

• 每次处理一个问题
• 每次处理一个问题节点或局部节点组
• 尽可能缩小读取范围
• 尽可能缩小写入范围

首先加载以下能力：

• 用于常规检查工具的 Figma MCP 读取权限
• 如果你的环境有此要求，则在任何 use_figma 写入调用前加载 figma-use 风格的辅助工具

如果任务涉及更广泛的整屏重新连接、需要协调修改多个部分，或用户明确要求全面检查整个画板，请改用 apply-design-system。

预期输入

优先使用以下任一项：

• 来自 audit-design-system 的单条 JSON 问题记录
• 完整的审核 JSON，以及需要处理的具体问题
• 对问题的转述，以及 Figma URL 或 fileKey 和 nodeId

如果问题来自 audit-design-system，请从以下字段提取目标：

• code_location.absolute_file_path = /figma/<fileKey>/nodes/<nodeId>

将审核结果视为范围约定。不要悄悄将单个问题扩展为全面清理。

范围规则

持续聚焦所选问题，直到符合以下任一情况：

• fixed：目标问题已修正
• blocked：修复需要缺失的库资源、无法访问的组件，或更广泛的产品决策
• needs-follow-up：目标节点已改进，但仍有一个独立的相邻问题需要单独审核

如果用户粘贴了多个问题，请处理他们选定的问题，或选择优先级最高的问题，并说明当前正在修复该问题。

必需工作流

1. 规范化问题

提取并重述：

• fileKey
• 有问题的 nodeId
• 问题标题
• 审核者标记此问题的原因

如果审核输出未指出具体节点，请停止并要求提供原始问题 JSON 或直接的 Figma 节点。

2. 当替换方案不明确时，进行本地兼容性检查

在备份或编辑画布前，先判断能否直接修复。

符合以下情况时，进行本地兼容性检查：

• 问题要求替换设计系统组件，但未指出具体组件
• 有多个库组件看起来都合适
• 覆盖行为或尺寸不明确
• 用户明确要求写入前进行额外调查

在兼容性检查得出以下结果之一之前，不要继续写入：

• safe-to-apply
• blocked
• needs-human-choice

兼容性检查应回答：

• 哪个具体组件或变体是首选候选项
• 是否支持文本、图标、状态和尺寸覆盖
• 替换后能否保留节点的布局约定

如果结果为 blocked，请停止并报告阻碍因素。

如果结果为 needs-human-choice，请停止并提出最简短的澄清问题，不要猜测。

3. 仅收集所需证据

写入前，使用尽可能少的读取操作检查目标：

1. 使用 get_screenshot 查看有问题的节点或最近的外围部分
2. 使用 get_metadata 获取结构上下文
3. 如果问题涉及令牌、原始值、颜色、间距或排版，则使用 get_variable_defs
4. 如果问题表明存在已有的映射组件，则使用 get_code_connect_map
5. 仅当仍需查找替换基础组件时，才使用 search_design_system

除非问题明确指向重复模式，且必须了解该模式才能选择修复方案，否则不要重新审核整个画板。

4. 对修复进行分类

准确选择一种修复模式：

• swap-instance：用正确的库组件或变体替换临时实例或错误实例
• compose-from-primitives：使用已发布的库部件重建本地自定义包装器
• bind-tokens：将原始值替换为变量或样式
• align-variant：将现有实例切换为正确的变体或属性状态
• blocked：目前无法通过库支持的方式进行有效修复

如果看起来有多种模式都适用，优先选择满足原始问题的最小改动。

5. 仅备份受影响区域

在进行破坏性编辑前，只复制有问题的节点，或范围最小的本地封装区域。

为备份起一个清晰的名称，例如：

• Backup - Fix finding 1
• Backup - Custom nav

在单独的一次写入调用中创建备份，并返回所创建节点的 ID。

6. 逐步应用修复

不要重建整个屏幕。

按以下小步骤操作：

1. 检查当前节点 ID 和组件关联
2. 导入或找到所需的库组件或变量
3. 仅替换、组合或重新绑定受影响区域的令牌
4. 返回所有已创建和已修改的节点 ID

如果 swapComponent() 能保留节点的位置和有效覆盖项，优先使用它。

在以下情况下，优先在原节点旁重建：

• 当前节点是包含混合自定义结构的本地包装器
• 评审问题指向的是自定义组合，而非单个基元
• 需要在替换原节点前进行视觉对比

如果首次验证发现推荐组件导致布局、文本可见性、图标行为或宽度约束退化，请停止。应报告 blocked 或 needs-follow-up，而不是继续强行使用同一个基元。

7. 验证问题，而非整个屏幕

写入后：

1. 对更改的节点或其直接所属区域截图
2. 确认具体的评审问题已不再存在
3. 如果目标是由库支持或绑定令牌，确认结果符合该目标
4. 确认间距和文本覆盖仍然合理

只有在修复触及导航等全局模式时，才将验证范围扩展到本地所属区域之外。

决策启发式

• 如果问题指出某个基元被重新创建成了画框，倾向于使用 swap-instance。
• 如果问题指出应将重复的本地包装器合并为共享模式，除非任务明确要求在所有同级节点上应用修复，否则只修复一个代表性节点。
• 如果问题涉及原始值与已绑定令牌的同类元素并存，倾向于使用 bind-tokens。
• 如果问题涉及本地编辑过但尺寸或状态错误的实例，倾向于使用 align-variant。
• 如果库中缺少所需组件系列，或导入失败，应标记为 blocked，不要临时伪造关联。
• 如果设计系统组件存在，但无法保留节点的文本、图标或尺寸约束，应标记为 blocked 或 needs-human-choice，不要强行替换。

编写规则

• 写入范围应严格对应所选问题。
• 如果替换选项存在歧义，在获得 safe-to-apply 兼容性结果前，不要写入。
• 修复一个问题后，不要声称整个屏幕都已“符合系统规范”。
• 优先使用确切的组件键和变量 ID，而不是名称。
• 不要因为发现了其他偏差，就继续处理无关的清理工作。
• 如果明显需要更大范围的重构，先完成针对性修复或报告阻碍，然后建议在下一轮使用 apply-design-system。

交付格式

结束任务时，请报告：

• Finding fixed：更改内容及其所在节点
• Validation：如何确认原问题已解决
• Blocked 或 Follow-up：仅在问题无法完全解决时报告

报告应围绕单个问题展开。除非用户要求，否则避免总结整个屏幕。