Figma iOS 资源导出

工作流程

使用 scripts/export_figma_ios_assets.mjs 实现可重复的资源导出。该脚本调用 Figma REST API 的 GET /v1/images/:key 接口，并下载返回的资源 URL。普通 iOS 位图资源优先导出 PNG 格式的 @2x 和 @3x 版本；仅当用户明确要求矢量 PDF，或资源需保留矢量表达形式时，才导出 PDF。

资源优先原则（Asset-First Rule）

当 Figma 链接用于 iOS 实现或视觉对齐任务时，应将 Figma 文件视为自定义图像的唯一事实来源（source of truth）。在用原生绘制、CALayers、SwiftUI 形状、UIKit 视图或 SF Symbols 替换视觉节点前，请先判断该节点是否为可导出资源。

默认情况下，以下情形应导出真实的 Figma 节点：

• 自定义图标、标签栏/导航栏/操作栏图标、象形图（pictograms）、徽章（badges）、Logo、插画、空状态图、装饰性图片、复杂矢量组、渐变、蒙版、模糊效果图像、背景图，以及任何其像素级细节直接影响设计还原精度的节点。
• 外观类似图标的 Figma 节点，即使存在功能相似的 SF Symbol。
• 多图层或需本地化的视觉组合，若通过代码重建将导致近似结果或耗时过长。

仅在以下情形使用原生 iOS 绘制/布局：

• 文本、简单矩形、分隔线、标准控件、纯色填充、圆角、阴影及可通过代码直接精确复现的布局结构。
• 用户明确要求替换为 SF Symbols 或原生形状的资源。
• Figma 节点明显对应一个标准 SF Symbol，且设计规范或用户指定了该符号名称。

若因缺失 token、缺失 node id、权限不足或 Figma API 故障导致导出失败，请明确报告阻塞原因；仅在必要时使用带清晰标记的临时占位符继续流程。切勿静默地以 SF Symbols 或近似图层替代 Figma 原始图像。

Figma 链接分级处理（Figma Link Triage）

当用户粘贴 Figma URL 时：

1. 从 URL 中提取文件 key 和 node id。
2. 若 URL 指向屏幕/帧（screen/frame），请检查设计上下文或元数据，识别出应导出的子视觉节点。
3. 在实现该屏幕前，为每个可导出的视觉节点建立映射关系。
4. 若当前存在 Xcode 项目，则始终将资源导出至目标应用的 .xcassets 目录中。
5. 在 iOS 代码中通过生成的资源名称引用已导出的图像。
6. 说明所有有意不导出的节点，并解释其为何可安全地通过原生方式构建。

前提条件：

• 具备文件读取权限的 Figma token。可通过 --token-file 参数传入、设置环境变量 FIGMA_TOKEN_FILE，或设置 FIGMA_TOKEN。切勿将真实 token 存储于技能代码或已提交的映射文件中。
• 支持内置 fetch 的 Node.js 运行时。

映射文件（Mapping File）

创建 JSON 映射文件，顶层结构可为数组，也可为包含 items 字段的对象。若导出至真实应用，推荐使用稳定、具描述性的 asset 名称，并以前缀标明所属功能或页面，例如 home_empty_state 或 profile_nav_settings。

{
  "figmaUrl": "https://www.figma.com/design/FILE_KEY/FileName?node-id=1-607",
  "assetRoot": "/absolute/path/App/Assets.xcassets/FigmaSlices",
  "items": [
    { "asset": "figma_icon_settings", "nodeId": "1:202", "figmaName": "设置" },
    { "asset": "figma_icon_back", "nodeId": "1:476", "figmaName": "左侧图标/ic_back" }
  ]
}

字段说明：

• figmaUrl：目标 Figma 文件中的任意设计页 URL；脚本将从中提取文件 key 和文件名。
• assetRoot：可选。若设置该字段，每个 item 将生成 Xcode .imageset 并重写 Contents.json。
• outDir：assetRoot 的可选替代方案，将导出的原始文件写入指定目录。
• asset：若使用 assetRoot 则为必填项；在 outDir 模式下也用作导出文件名的主干（stem）。
• nodeId：必填的 Figma 节点 ID，格式支持 1:202 或 1-202。
• format：可选，默认映射格式，值为 png 或 pdf；推荐使用默认值 png。
• scales：可选的 PNG 缩放比例列表，默认为 [2, 3]。

即使用户仅粘贴单个节点 URL，也应创建映射文件，而非手动下载一次性资源。此举可确保资源命名、缩放比例及 .imageset 元数据的一致性与可复现性。

命令示例

导出为 Xcode PNG imageset：

node ~/.codex/skills/figma-ios-asset-export/scripts/export_figma_ios_assets.mjs 
  --mapping /tmp/figma-assets.json

导出为普通 PNG 文件：

node ~/.codex/skills/figma-ios-asset-export/scripts/export_figma_ios_assets.mjs 
  --figma-url "https://www.figma.com/design/FILE_KEY/FileName" 
  --mapping /tmp/figma-assets.json 
  --out-dir /tmp/figma-pngs

导出为矢量 PDF 资源：

node ~/.codex/skills/figma-ios-asset-export/scripts/export_figma_ios_assets.mjs 
  --mapping /tmp/figma-assets.json 
  --format pdf

验证

完成向 .xcassets 导出后，执行以下命令进行验证：

find PATH_TO_ASSET_ROOT -name '*.png' -o -name '*.pdf'
find PATH_TO_ASSET_ROOT -name Contents.json -print0 | xargs -0 python3 -m json.tool >/dev/null

对于 iOS 项目，请使用项目认可的验证命令执行构建验证。PNG @2x 和 @3x 是默认导出格式，因其直接对应 iOS 的缩放因子。PDF 可在 Figma 支持导出矢量图层时保留其矢量特性；但嵌入在 Figma 中的光栅图像，在导出的 PDF 中仍将保持为光栅内容。