用 Figma Plugin API 在 Slides…

当需要通过 use_figma MCP 工具在 Figma Slides 文件中创建、编辑、组织幻灯片或撰写演讲者备注时使用。

适用场景

解决思路

1. 调用 use_figma 处理 Slides 时，始终在逗号分隔的 skillNames 参数中包含 figma-use-slides；若该技能是通过 MCP resource 加载的，必须加前缀 resource:（如 resource:figma-use-slides）。
2. 每个 deck 请求只选一种构建方式：默认用 use_figma + 本技能（支持新建、编辑、品牌匹配、参考文件风格、迭代优化、演讲者备注、完全创意控制）；仅当用户需要快速、无需自定义设计的简单 deck 时才用 generate_deck。选定后全程只用这一种，不要两者混用以免产生重复冲突的产物。
3. 新建 Slides 文件会自动初始化默认浅色主题，必须用自己设计方向的颜色变量和文本样式覆盖该主题，不要依赖默认浅色主题的 token。
4. 对每个节点、每一层嵌套，都必须先 appendChild 再设置 x/y。新建节点会被静默自动挂到幻灯片上下文绝对坐标 (240, 240)，先设 x/y 会导致最终位置偏移 (intended − 240, intended − 240)，且该 bug 是间歇性的。若发现节点偏移 (−240, −240)，应修正 appendChild 顺序，不要试图加回 240 补偿。
5. 不要访问 SLIDE_GRID 和 SLIDE_ROW 的 .fills、.effects 或布局属性，它们是不透明节点；只有 SLIDE 节点（type 'SLIDE'）继承 BaseFrameMixin。例外：SLIDE_ROW.name 可设置，用于重命名幻灯片分区（如 slideRow.name = "Intro"）。
6. get_metadata 不支持 Slides 文件，改用 use_figma 只读脚本做校验；在 closePlugin() 输出中返回创建的节点位置，并验证没有重叠的包围盒。
7. 不要在 Slides 中调用 figma.createPage()，它会抛出 TypeError；createPage() 仅适用于 Design 文件。改用幻灯片网格（SLIDE_GRID / SLIDE_ROW / SLIDE）组织 deck 结构。
8. 被要求改进、重新设计或换风格时，绝不删除已有幻灯片重建，应就地修改现有幻灯片；只有用户明确要求“从头开始”或“重做”时才删除。
9. 先判断任务深度：内容/属性编辑（改文字、换颜色、调数字、修对齐、改尺寸）跳过设计思考直接改；结构性新增（加幻灯片、重做某节布局、改配色、引入新视觉元素，含“改进/重新设计/换风格”）用继承模式，先检查现有 deck 并匹配其配色、字体、空间习惯和母题；新建 deck 才做完整设计思考。
10. 新建 deck 前先读 brief（deck 传达什么、给谁看），检查用户是否已提供设计语言（品牌指南、配色、字体、logo 规则、语气描述、参考 Figma 文件链接），用户给的越具体就越少自行发挥。
11. 在剩余空间上明确立场：用户给了完整品牌系统则创意空间在布局、节奏和构图；只给一张参考幻灯片则仍要呼应其气质；什么都没给则自己决定配色、字体、空间组织方式并贯穿每页。
12. 给 deck 一个标志性元素：独特配色、意外布局节奏或重复形状语言；有品牌指南时标志应来自品牌语言本身而非外加。
13. 读取参考文件：若参考是 Slides 文件，用 get_screenshot 截取单页，并用 use_figma 以参考文件 fileKey 运行只读脚本提取主题变量、配色、字体和布局模式；若是 Design 文件，用 get_design_context 获取颜色/字体/布局数据，用 get_screenshot 获取视觉参考。
14. 从参考文件提取：主导色相、强调色、深浅背景用法、字体家族与字重、层级处理、内容锚点、留白量、是否出血、重复母题。用户说“做成这样”就复刻设计语言，“用作灵感”就呼应气质但做出自己的风格，“这是我们的品牌 deck”就提取品牌系统一致应用；不确定时更贴近参考。
15. 构建 5 页以上新 deck 时用两阶段工作流。阶段一：完成设计思考后、写任何 use_figma 代码前，产出整份 deck 的幻灯片计划——逐页说明用途/内容、用空间语言描述布局（如“标题锚定左上，规格卡占右侧三分之一，装饰圆从右上出血”）、背景处理（深/浅/渐变），规划时不要算像素坐标。
16. 阶段一还要声明共享常量：字体家族与样式、按角色命名的配色（primary、accent、bgDark、surface、textPrimary、textMuted 等）、重复母题或标志元素。
17. 阶段一做布局多样性检查：按顺序读幻灯片计划，若布局描述重复（如“两栏、两栏、网格、两栏”）就在构建前重排，这是最便宜的多样化时机。
18. 阶段一写出代码前导：每个构建脚本顶部粘贴的 const C = { ... } 配色对象、Promise.all([...]) 字体加载块，以及 slide-gotchas.md 中的 addFrame/addText/addRect 辅助函数。
19. 阶段二大批量执行：每次 use_figma 调用构建 3–5 页，结构相似的幻灯片可同批；每页是独立子树，无跨页依赖，大批量安全。
20. 批次之间不要重新规划：设计已在阶段一定好，批次成功并通过校验就立即进入下一批；只有批次失败或出现需改变方案的视觉问题才重新规划。
21. 每个构建脚本顶部粘贴阶段一的代码前导（颜色、字体、辅助函数），逐字复制不要重新推导。
22. 每批用 slide-gotchas.md 中的确定性批次校验脚本验证，约 3 秒检查重叠元素、文字裁剪和越界节点；通过则无需截图继续，失败则截图受影响幻灯片并修复。
23. 只在检查点截图：第一批后（验证视觉系统：颜色、字体、设计方向）和最后一批后（整体质量），每个检查点用内联 await slide.screenshot() 截 1–2 张代表性幻灯片，不要单独调 get_screenshot。
24. 每个构建脚本都要返回所有创建的节点 ID。
25. 分区是幻灯片网格中的水平行，每行即一个分区，名称显示在编辑器行旁和 Presenter View 中。被要求“整理 deck”时默认提出方案而非询问：多数 deck 有线索（标题书签、编号用例、重复的 Before/After 对、过渡页、Thank you），有线索就选一种分区方案并用一条确认消息呈现；线索缺失（顺序随意、无主线）时才问哪些范围归一组、叫什么名字，不要按三等分切。
26. 分区命名要短（1–3 词）、具体（Demo 优于 Show & tell）、同一 deck 内一致；通常 2–5 个分区，长 deck 或重复 deck 才更多；名称不是幻灯片标题。
27. 重命名分区时注意 getSlideGrid() 返回 SlideNode[][]，内层数组是普通 JS 数组而非 SLIDE_ROW 节点，对其设 .name 会静默无效；应遍历节点树对真正的 SLIDE_ROW 设 .name，如 const slideGrid = figma.currentPage.children.find(c => c.type === "SLIDE_GRID"); slideGrid.children[0].name = "Intro";。
28. 写演讲者备注的时机：用户要求时，为每页有实质内容的幻灯片写（跳过分区隔页或纯装饰页）；用户明确要求可直接现场演示的 deck 时，在有助于理解节奏、过渡或幻灯片外上下文时添加；幻灯片围绕图表、图片、隐喻或挑衅性问题时，可用截图或 node.screenshot() 辅助说明，但不要默认每页都截图以免消耗上下文预算。
29. 不要在用户未要求时添加备注：普通幻灯片编辑、布局工作或更新现有 deck 时不要填充演讲者备注，以免改变演示流程、让 deck 所有者意外。
30. 好备注应补充而非重复幻灯片内容（幻灯片说“营收增长 40%”，备注应说为什么增长、听众应记住什么、通常引发什么问题）；简洁可扫读，用短要点而非密集段落，每点一个想法；包含过渡语（如“掌声平息后……”“这承接上一点——回扣 40% 这个数字”）；携带幻灯片无法承载的上下文（数据来源、注意事项、时间提示、预期问题）；匹配演示场合的语气（投资人路演精确排练，团队复盘随意灵活，主题演讲可含舞台指示）。
31. 备注中避免：完整逐字稿（除非用户明确要求脚本，默认用要点）；为观众做格式化（备注观众看不到）；与幻灯片冗余（幻灯片已自解释如“Thank You”加联系方式则无需备注，留空可以）。
32. 备注格式：slide.speakerNotes 接受 markdown 字符串，优先用无序列表作主结构，粗体用于强调关键短语；支持列表、粗体、斜体、删除线，不支持标题、代码块、行内代码、链接。
33. 检查 Slides 文件：创建前先跑只读 use_figma 发现已有内容（幻灯片、文字、组件、命名约定）；get_metadata 不支持 Slides；console.log() 输出不会返回，只返回 return 值，务必 return 所需数据；用 get_screenshot 传有效 nodeId 获取视觉上下文，也可在 use_figma 脚本内用 await node.screenshot()。
34. 列出 deck 中所有幻灯片：const grid = figma.getSlideGrid(); return grid.map((row, rowIdx) => row.map((slide, colIdx) => ({ id: slide.id, name: slide.name, row: rowIdx, col: colIdx, isSkipped: slide.isSkippedSlide, speakerNotes: slide.speakerNotes })));。
35. 获取指定幻灯片文字内容：用 figma.getNodeById("TARGET_SLIDE_ID") 取节点，用 findAllWithCriteria({ types: ["TEXT"] })（索引类型查找，比 findAll 快），遍历文字节点收集 fontName（处理 figma.mixed 时用 getStyledTextSegments(["fontName"])），逐个 await figma.loadFontAsync 后返回 id、name、characters、x、y、width、height。
36. 按需加载参考文档：slide-gotchas（坐标偏移、不透明节点类型、校验变通）、slide-lifecycle（创建/克隆/删除/重排幻灯片和行）、slide-grid（getSlideGrid、setSlideGrid）、slide-content（在幻灯片内构建文字、形状、auto-layout）、slide-properties（speakerNotes、isSkippedSlide、focusedSlide、focusedNode、slideThemeId、InteractiveSlideElementNode）、slide-design（配色策略、字体、布局多样性、空间构图、反模式）。

适用边界 · 注意事项

• 需要快速生成简单 deck 且用户不需要自定义设计、品牌匹配或参考文件风格时，用 generate_deck 而非本技能。
• 普通幻灯片编辑、布局工作或更新现有 deck 时，不要主动添加演讲者备注。
• 用户未明确要求“从头开始”或“重做”时，不要删除已有幻灯片重建。