Figma 转移动端

通过交互式澄清，将 Figma 设计稿转换为可运行的移动 UI 代码。

支持平台：Android Compose、Android XML、iOS SwiftUI、iOS UIKit。

前置条件

• 已设置 FIGMA_TOKEN 环境变量（Figma → Settings → Personal Access Tokens）。切勿将 token 直接粘贴至聊天窗口中。
• Python 3.10+，并安装 requests 包

安全的 token 配置方式（推荐）

• Windows PowerShell（当前会话）：
  • $env:FIGMA_TOKEN = "figd_..."
• Windows（持久化配置，对新终端生效）：
  • setx FIGMA_TOKEN "figd_..."
• macOS/Linux（当前 shell）：
  • export FIGMA_TOKEN="figd_..."

若您坚持使用 .env 文件，请在本地编辑（不要在聊天中操作），并确保该文件被 Git 忽略（例如通过 .gitignore 配置）。

触发与输入

当用户提供 Figma 链接时，本技能自动激活。

用户还可随链接附带行内提示（inline hints），例如：

• 目标平台：“Android XML”、“Compose”、“SwiftUI”、“UIKit”
• 布局偏好：“use ConstraintLayout”、“prefer StackView”
• 组件说明：“the switch is our custom CompactSwitch”、“this is a dynamic list”
• 其他关于设计的上下文信息

若用户已提供提示，请严格遵循，跳过对应问题。 例如，若用户说明“Android XML，3 张卡片是一个 RecyclerView 列表”，则不得再询问输出格式或卡片是否为动态/静态。

工作流程

步骤 1：获取与分析

当用户提供 Figma 链接时：

1. 判断输入类型：

   A. 不含具体 node-id 的链接（无 node-id 参数，或 node-id=0-1）： 该链接指向整页（page），而非特定 frame。请向用户说明：

   此链接指向整个页面。请在 Figma 中选中您要转换的具体 frame，右键选择“Copy link to selection”，然后发送该链接。 如需转换多个 frame，请分别发送多个链接。

   B. 单 frame 链接（含明确 node-id）： 执行 scripts/figma_fetch.py "" → 返回该 frame 的设计数据。 继续进入分析阶段。

   C. 多个链接（用户发送 2 个及以上 URL）： 首先根据 frame 名称及用户上下文判断其关系：

   • 同一页的不同视觉状态（例如“首页-有banner”和“首页-无banner”）： 启用 --compare 模式批量获取，并生成差异摘要。最终输出多状态代码（例如条件可见性、状态切换逻辑）。

   • 主页面 + 浮层/抽屉（例如“首页” + “首页-抽屉-xxx”）： 将每个 frame 分别生成为独立的布局文件；随后向用户说明二者关系：

     Frame 1（“首页”）与 Frame 2（“首页-抽屉”）看起来构成一个主页面加侧边抽屉的关系。 我已生成两个独立的布局文件。如何将它们组合（DrawerLayout、Navigation 等）取决于您的项目架构。

     本技能职责仅为生成 UI 布局代码，不参与架构决策（Activity vs Fragment vs Navigation）。

   • 多个相互独立的页面（例如“首页” + “设置页” + “个人中心”）： 逐个独立处理。每次仅请求一个 node，并在请求间暂停 2–3 秒以避免触发速率限制。 汇总所有页面信息后，询问用户希望优先转换哪一页（或按顺序全部转换）。

   • 关系不确定：主动向用户确认——“这些 frame 看似有关联，但我不确定具体关系。它们是同一页面的不同状态？主页面加浮层？还是完全独立的页面？”

   多链接调用的限流保护：批量获取多个 node 时，请求间隔不少于 2–3 秒；严禁并发发起超过 2 个请求。

2. 若链接不含具体 node-id，请引导用户重新从指定 frame 复制链接（见 A 类情形），禁止调用 API。

3. 分析结构：识别主要区域、重复模式、组件类型

4. 标记 INSTANCE 节点——表示可复用组件。检查 variantProperties 获取组件状态（如 State=Default、Size=Large），用于生成多状态代码

5. 记录渐变/阴影数据——若复杂度高，需在摘要中向用户显式标注

6. 在生成代码前，应用 Figma 节点解析规则

详细解析规则：参阅 references/figma-interpretation.md

步骤 1.5：结构摘要

在提出任何问题前，先向用户提供简明的结构摘要，供其确认理解是否正确：

我看到：[含返回按钮与标题的导航栏] → [2 个内容区：用户资料卡片、设置列表（共 8 项）] → [底部操作按钮]。总计约 25 个节点。

摘要控制在 2–3 行内，需包含：

• 识别出的主要区域（导航栏、内容区、页脚等）
• 重复模式（如“8 个相似列表项”、“3 个标签页文字”）
• 显著元素（渐变、复杂插图、堆叠卡片等）

若用户指出“不对”或修正结构描述，请更新理解后再进入步骤 2。

若设计中可见叶节点（leaf nodes，即映射为实际 View 的可见元素）≤10 个，则跳过本步骤——结构足够简单，可直接进入下一步。

步骤 2：确认与澄清

问题优先级（严格按序提问，先问靠前的问题）：

1. 输出格式（除非用户已明确指定，否则必须首问） → Android XML / Compose / SwiftUI / UIKit 该选择决定后续所有分析措辞与代码输出形式。

2. 结构性歧义（仅就真正不确定之处提问） → “这 N 个元素结构相似——应实现为动态列表，还是固定布局？” → “该区域：是单张图片资源，还是图标叠加背景的组合？”

3. 组件选型（仅当与目标平台强相关时） → “是否有需要使用的自定义组件？（否则将采用平台默认组件）”

提问规范：

• 用户已在行内提示中回答的问题，一律跳过
• 总提问数上限为 3–5 个，越少越好
• 每个问题须提供具体选项，并附带一行优缺点说明
• 每个问题均需包含开放选项：“或请进一步说明此处”
• 使用自然语言表达，禁用 JSON 或技术术语堆砌
• 若上下文完整且结构清晰，可完全跳过步骤 2

置信度参考——何时提问、何时直接生成：

• ≥3 个结构相似的同级节点 → 很可能为列表 → 提问（动态 or 静态）
• 多个 INSTANCE 节点共享相同 componentId → 可复用组件 → 可提及，但允许默认处理
• 层级清晰、无歧义 → 置信度高 → 跳过提问，直入步骤 3
• 设计中含渐变或复杂阴影 → 在摘要中注明（如“此处存在渐变，我将按 X 方式近似实现”）

步骤 2.5：项目扫描（可选，但推荐）

若目标项目本地可访问，建议执行项目扫描：

python scripts/project_scan.py /path/to/project --json --output scan-report.json

如何在代码生成中使用扫描结果：参阅 references/scan-usage.md

步骤 3：生成代码

待用户确认（或无需提问时），生成代码文件。

详细生成规则：参阅 references/generation-rules.md

若需生成多个文件，请为每个文件添加清晰的文件名标题：

📄 activity_notification_settings.xml
[code]

📄 item_expert_notification.xml
[code]

步骤 4：迭代与反馈收集

展示代码后，简要询问：

是否符合设计？是否需要调整？

用户可据此反馈持续优化输出。 常见迭代类型包括：

• “间距大了” → 调整特定间距值
• “Switch 换成我们的 CustomSwitch” → 替换组件实现
• “把标题栏去掉” → 删除对应区域
• “换成 Compose 版本” → 以不同格式重新生成
• “颜色不对，这里应该是 #333333” → 修正特定取值

持续迭代直至用户满意。

迭代输出规范：

• 若文件已写入磁盘 → 读取当前文件，仅应用最小补丁，仅输出变更行，并附带明确上下文（文件路径 + 行号范围）。禁止全量重生成。
• 若代码仅存在于对话中（未落盘） → 仅输出变更片段，并用注释标明替换位置（例如：// replaces lines 12-18 in activity_main.xml）。禁止重复整个文件。
• 仅当用户明确要求时（如“重新生成完整文件”、“show me the full file”），才全量重生成。

反馈收集（可选，需用户显式授权）： 仅当用户明确同意持久化日志时，将映射修正记录至目标项目根目录下的 .trae/figma-to-mobile/feedback-log.md（路径不存在则自动创建）。每条记录格式如下：

## YYYY-MM-DD HH:MM
- **Platform**: Android XML / Compose / SwiftUI / UIKit
- **Figma node type**: （例如：含 icon 的 FRAME、Tab bar、Button group）
- **Issue**: 错误简述
- **Before**: Agent 当前生成内容（代码片段或文字描述）
- **After**: 用户期望结果（代码片段或文字描述）
- **Rule candidate**: （可选）若该修正暗示通用规则模式，请在此注明

日志条目应满足：

• 简洁性 —— 仅记录相关差异，不保存整文件
• 可分类性 —— 必须包含 platform 和 Figma node type，便于后续分析
• 可操作性 —— 聚焦映射错误本身，而非外观偏好（例如“用户偏好 16dp”非规则；“VECTOR 组合应转为单个 ImageView”是规则）
• 安全性 —— 禁止记录密钥（tokens/keys）、专有完整代码块、完整设计载荷

以下情况禁止记录：

• 一次性个人偏好（特定颜色选择、命名约定）
• 非映射类问题修正（拼写错误、import 语句）
• 用户明确声明仅适用于当前项目的反馈（非通用规则）

定期（或应用户要求）运行 scripts/feedback_analyze.py，识别高频模式并生成候选规则。

错误处理

• 未设置 FIGMA_TOKEN（脚本返回 FIGMA_TOKEN_NOT_SET）→ 禁止引导用户将 token 粘贴至聊天窗口。应改为：
  1. 告知用户需要 Figma Personal Access Token（PAT）
  2. 说明获取路径：Figma → 头像 → Settings → Security → Personal Access Tokens
  3. 建议其在本地环境变量或密钥管理器中设置 FIGMA_TOKEN（推荐），然后重试
  4. 若用户坚持使用 .env，指导其在本地编辑该文件（禁止在聊天中操作），并确保 .env 已加入 .gitignore
• FIGMA_TOKEN 无效（API 返回 403/401）→ token 可能已过期或被撤销。请用户重新生成新 token 并本地设置后重试。
• URL 无效 → 展示合法 URL 示例：https://www.figma.com/design//?node-id=
• API 错误 → 显示原始错误信息，并建议检查网络或代理设置
• Node 过大（子节点 >200 个） → 建议用户选择更小的 frame
• 深度自动增加 → 若脚本检测到子节点被截断，将自动以更深 depth 重试。若发生此情况，请通知用户（例如：“我需要加深获取深度以获得全部细节”）。