网站到 Figma 设计文件
将运行中的 Web 应用转换为 Figma 文件，设计师可以直接从中进行重新设计：包含真实文案、真实图标、颜色与间距变量（支持亮/暗模式）、文本样式、可复用组件，以及由这些组件的实例构建的每个页面。截图仅作为参考，绝不是最终交付物。
此技能建立在 Figma 插件自身技能之上。在任何 use_figma 调用之前加载 figma-use 和 figma-generate-design，在创建组件或变量时加载 figma-generate-library。
何时使用
- "将我的网站导入 Figma，以便我重新设计"
- "在 Figma 中重新创建这些页面" / "将此应用推送到 Figma"
- 向以这种方式构建的 Figma 文件添加移动端画框或新页面
步骤
1. 读取事实来源
- 运行中的应用和全局样式表优先于设计文档。文档在重新设计期间可能会发生偏离；如果发现不匹配，请明确指出。
- 收集：主题令牌（亮和暗）、字体系列和粗细、布局网格（边距、轨道、列宽），以及每个页面部分背后的组件文件。
- 在编写样式之前，使用
figma.listAvailableFontsAsync()检查字体是否存在于 Figma 中。切勿静默地回退到 Inter。
2. 使用 Playwright 捕获参考截图，而非页面捕获
使用 scripts/ref-screenshots.mjs 在每个目标宽度（例如 1440 和 390）下运行。它会设置 reducedMotion: "reduce"，因此滚动揭示和进入动画不会隐藏内容。
generate_figma_design 页面捕获对于此任务不可靠：视图内动画后面的内容会被空白捕获，并且在后台浏览器标签页中打开的捕获经常会永远处于 pending 状态。如果你确实使用它们，请一次只打开一个标签页，并在其作为参考后立即删除捕获。如果你将捕获脚本注入应用，之后务必将其移除。
3. 从代码库导出真实数据和图标
编写一个一次性 tsx 脚本（在仓库外部，或之后删除），该脚本导入应用自身的数据模块，并使用 react-dom/server 的 renderToStaticMarkup 将图标组件渲染为 SVG 字符串。然后：
- 将
currentColor替换为真实颜色，并为每个 SVG 提供明确的width/height。图标库通常输出1em，Figma 无法调整其大小。 - 根据路径数据对图标去重。品牌映射经常将多个名称别名指向同一个标志。
- 使用 CMS 客户端拉取 CMS 内容（标题、摘要、分类），而不是重新输入。
4. 首先构建基础
每个操作调用一次，返回所有创建的 ID：
- 页面：基础、组件、每个断点一个页面。
- 变量集合：主题颜色（亮/暗模式）、分类或品牌颜色、布局令牌（桌面/移动端模式）。设置明确的
scopes和 WEB 代码语法。 - 为每种类型角色创建文本样式，以及显示尺寸的移动端变体。
- 为任何共享阴影创建效果样式。
5. 构建组件，从最小的开始
图标，然后是原语（按钮、链接、磁贴、徽章、芯片），然后是复合材料（页眉、页脚、英雄区、卡片）。公开 TEXT、BOOLEAN 和 INSTANCE_SWAP 属性，以便页面可以在不分离的情况下填充。为响应式组件提供 Breakpoint 变体，而不是在实例上覆盖尺寸。每组截图一次，修复问题后再继续。
6. 从实例组装页面
- 每个页面一次
use_figma调用，使用固定的画布位置，以便页面可以并行构建。 - 使用自动布局内边距（例如轨道和边距）镜像 CSS 网格，而不是绝对定位。
- 明确按行均衡卡片高度；Figma 不像 CSS 网格那样拉伸同级元素。
- 将每个页面的总高度和截图与参考进行比较。高度在百分之几以内表示间距正确。
7. 将组件链接回代码
Code Connect 仅适用于组织版和企业版计划。首先检查 whoami。在其他计划上，将源代码路径、组件名称和属性映射写入每个组件的 description 中，并将 documentationLinks 设置为 GitHub 上的文件。开发者模式会同时显示两者。不要将 .figma.ts 文件添加到无法发布它们的仓库中；没有 Code Connect 包，它们会破坏 tsc。
8. 清理
删除参考捕获，移除任何注入的脚本，停止你启动的开发服务器，并确认 git status 是干净的。
陷阱
在编写组件或页面脚本之前，请阅读 references/plugin-api-pitfalls.md。它列出了最耗时的失败，每个都附有修复方法：绑定不透明度、resize() 锁定自动布局大小、属性键被重新键控、克隆变体上丢失引用、每次调用的尺寸限制等等。
references/helpers.md 包含值得在每个页面构建脚本顶部粘贴的小型辅助函数。