figma-use-slides

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

use_figma — Figma Plugin API Skill for Slides

use_figma — 面向Slides的Figma插件API技能

This skill contains Slides-specific context for the

use_figma

MCP tool. The figma-use skill provides foundational context for plugin API execution via MCP as well as the full Figma plugin API for more advanced use-cases that are not described here.

Always pass
skillNames: "figma-use-slides"
when calling
use_figma
for Slides operations. This is a logging parameter used to track skill usage — it does not affect execution.

本技能包含针对

use_figma

MCP工具的Slides专属场景信息。figma-use技能提供了通过MCP执行插件API的基础场景信息，以及完整的Figma插件API，适用于本文未提及的更高级场景。

在调用
use_figma
执行Slides操作时，务必传入
skillNames: "figma-use-slides"
。这是用于跟踪技能使用情况的日志参数，不会影响执行效果。

Critical Rules (Slides-specific)

Slides专属关键规则

Newly created Slides files have a default light theme. When a Slides file is created via
```
create_new_file
```
, a default light theme is automatically initialized. This theme is structural scaffolding — you should overwrite the theme's color variables and text styles with your own design direction for the deck you're building. Do not rely on or be influenced by the default light theme tokens.
MUST
appendChild
to the slide BEFORE setting
x
/
y
position. Slides have an internal coordinate origin; positioning before parenting causes silent offsets that produce broken/overlapping layouts. Do all property configuration after appending for safety. See slide-gotchas.md.
SLIDE_GRID and SLIDE_ROW are opaque nodes — do not access
```
.fills
```
,
```
.effects
```
, or layout properties on them. Only
```
SLIDE
```
nodes (type
```
'SLIDE'
```
) extend
```
BaseFrameMixin
```
. Exception:
```
SLIDE_ROW.name
```
IS settable — that's how plugins rename slide sections (e.g.
```
slideRow.name = "Intro"
```
). See slide-lifecycle.md.
get_metadata
does NOT work on Slides files. Use
```
use_figma
```
read-only scripts for validation. Return created node positions in
```
closePlugin()
```
output and verify no overlapping bounding boxes.
Do NOT call
figma.createPage()
in Slides. It throws
```
TypeError: figma.createPage no such property 'createPage' on the figma global object
```
—
```
createPage()
```
is a Design-file API only (
```
figma.com/design/...
```
); the Slides URL is
```
figma.com/slides/...
```
. Use the slide grid (
```
SLIDE_GRID
```
/
```
SLIDE_ROW
```
/
```
SLIDE
```
) to organize deck structure instead — see slide-lifecycle.md and slide-grid.md.

新建的Slides文件默认使用浅色主题。通过
```
create_new_file
```
创建Slides文件时，会自动初始化默认浅色主题。该主题仅为结构框架——你应当根据所构建演示文稿的设计方向，覆盖主题的颜色变量和文本样式。请勿依赖或受默认浅色主题标记的影响。
必须先将元素
appendChild
到幻灯片上，再设置
x
/
y
位置。Slides有内部坐标原点；在设置父节点前调整位置会导致无提示的偏移，进而产生布局错乱或重叠问题。为确保安全，请在添加元素后再进行所有属性配置。详见slide-gotchas.md。
SLIDE_GRID和SLIDE_ROW是不透明节点——请勿访问它们的
```
.fills
```
、
```
.effects
```
或布局属性。只有
```
SLIDE
```
节点（类型为
```
'SLIDE'
```
）继承自
```
BaseFrameMixin
```
。例外情况：
```
SLIDE_ROW.name
```
是可设置的——这是插件重命名幻灯片章节的方式（例如
```
slideRow.name = "Intro"
```
）。详见slide-lifecycle.md。
get_metadata
不适用于Slides文件。使用
```
use_figma
```
的只读脚本进行验证。在
```
closePlugin()
```
的输出中返回创建的节点位置，并检查是否存在重叠的边界框。
请勿在Slides中调用
figma.createPage()
。该操作会抛出
```
TypeError: figma.createPage no such property 'createPage' on the figma global object
```
错误——
```
createPage()
```
仅适用于Design文件API（
```
figma.com/design/...
```
）；而Slides的URL为
```
figma.com/slides/...
```
。请使用幻灯片网格（
```
SLIDE_GRID
```
/
```
SLIDE_ROW
```
/
```
SLIDE
```
）来组织演示文稿结构——详见slide-lifecycle.md和slide-grid.md。

Design Thinking

设计思路

Not every task needs the same depth of design thinking. Before doing anything, identify which gear you're in:

Content/property edits — changing text, swapping a color, updating a number, fixing alignment, resizing an element. Skip design thinking. Just make the change and match what's already there.
Structural additions — adding slides, reworking a section's layout, changing the deck's color palette, introducing a new visual element. Design thinking applies, but in inherit mode: the existing deck is your design language. Inspect it, match its palette, type, spatial habits, and motifs. Extend the deck's existing character rather than reinventing it.
New deck creation — building a deck from scratch or from a blank file. Full design thinking applies as described below.

For structural additions to existing decks: run the inspection scripts (below) and take screenshots before making changes. The answers to "what color story?" and "what type treatment?" are already in the file — your job is to read them and stay consistent. The design principles in slide-design.md describe what you're matching, not what you're choosing.

并非所有任务都需要相同深度的设计思考。在开始操作前，先明确当前所处的场景：

内容/属性编辑——修改文本、替换颜色、更新数值、调整对齐方式、调整元素大小。无需设计思考，直接做出修改并与现有内容保持一致即可。
结构性添加——添加幻灯片、重新设计章节布局、更改演示文稿的调色板、引入新视觉元素。此时需要设计思考，但需遵循继承模式：现有演示文稿就是你的设计语言。审视它，匹配其调色板、字体、空间布局习惯和设计主题。延续演示文稿的现有风格，而非重新创造。
新建演示文稿——从零开始或基于空白文件构建演示文稿。此时需要完整的设计思考，如下所述。

对于现有演示文稿的结构性添加：在修改前运行检查脚本（如下所示）并截图。“采用何种配色方案？”“使用何种字体样式？”这些问题的答案已存在于文件中——你的任务是解读并保持一致性。slide-design.md中的设计原则描述的是你需要匹配的内容，而非你需要选择的内容。

New deck design process

新建演示文稿设计流程

Before writing any Plugin API code for a new deck, decide what it should feel like. Figma users have high visual expectations — a deck that looks like it came out of a generic template generator will stand out for the wrong reasons.

Read the brief. What is the deck communicating, and to whom? An investor pitch, a team retrospective, a product launch, and a technical deep-dive all demand different visual treatments. The design should be inseparable from the content.
Check for a design language. Before inventing anything, look at what the user already gave you. Brand guidelines in the prompt — color palettes, typography specs, logo rules, tone descriptors — are design decisions that have already been made. A link to a reference Figma file is a design language you should study, not glance at. The more specific the user's inputs, the less you should invent on your own. When the user provides a reference, your job shifts from designer to interpreter: extract the design language and apply it faithfully to new content.
Take a position — on what's left. If the user supplied a full brand system, your creative latitude is in layout, pacing, and composition — not in color or type. If they gave you a single reference slide for inspiration, you have more room but should still echo its character. If they gave you nothing, then you own every decision — choose a color story, a type treatment, a way of organizing space, and follow through on it across every slide. A deck with a clear perspective (even a quiet one) always reads better than one that plays it safe on every decision. The scope of "take a position" scales inversely with what the user provided.
Give it a signature. Every good deck has at least one element you'd recognize if you saw it out of context: a distinctive palette, an unexpected layout cadence, a recurring shape language. When working from brand guidelines, the signature should come from that brand language — amplify something that's already there rather than adding something foreign. When designing from scratch, decide what the signature is before you start building.

在为新建演示文稿编写任何插件API代码前，先确定它应具备的风格基调。Figma用户对视觉效果有较高期望——看起来像是来自通用模板生成器的演示文稿会因负面原因而引人注目。

阅读需求说明。该演示文稿要传达什么内容？受众是谁？投资者推介、团队回顾、产品发布和技术深度解析都需要不同的视觉处理方式。设计应与内容密不可分。
检查是否存在设计语言。在创造任何内容前，先查看用户已提供的信息。提示中的品牌指南——调色板、字体规范、Logo规则、风格描述——都是已做出的设计决策。指向参考Figma文件的链接是你应深入研究的设计语言，而非简单浏览。用户提供的信息越具体，你自行创造的内容就应越少。当用户提供参考文件时，你的角色从设计师转变为解读师：提取设计语言并将其忠实地应用于新内容。
对剩余部分做出决策。如果用户提供了完整的品牌体系，你的创意空间在于布局、节奏和构图——而非颜色或字体。如果他们提供了单张参考幻灯片作为灵感，你有更多发挥空间，但仍应呼应其风格。如果他们未提供任何信息，那么所有决策都由你负责——选择配色方案、字体样式、空间组织方式，并在所有幻灯片中保持一致。具有清晰风格定位（即使是低调的定位）的演示文稿总是比在每个决策上都保守的演示文稿更易被接受。“做出决策”的范围与用户提供的信息成反比。
赋予独特标识。优秀的演示文稿至少有一个元素，即使脱离上下文也能被识别：独特的调色板、出人意料的布局节奏、重复的形状语言。根据品牌指南设计时，独特标识应源自该品牌语言——强化已有的元素，而非添加外来元素。从零开始设计时，在开始构建前就确定独特标识。

Reading a reference file

解读参考文件

When the user provides a link to a Figma file as a reference, study it before designing anything. What you extract depends on what the file is:

A Slides file:
```
get_metadata
```
does not work on Slides files. Use
```
get_screenshot
```
to capture individual slides for visual reference, and
```
use_figma
```
with the reference file's
```
fileKey
```
to run read-only scripts that extract theme variables, color palettes, font choices, and layout patterns.
A Design file:
```
get_design_context
```
gives you comprehensive design data — colors, typography, layout structure.
```
get_screenshot
```
gives you visual reference. Use both.

What to look for in a reference file: the color palette (which hue leads, what the accent is, how dark/light backgrounds are used), the type choices (families, weights, how hierarchy is handled), the spatial habits (where content anchors, how much whitespace, whether things bleed off edges), and any recurring motifs (shapes, line treatments, decorative elements). These are the decisions you inherit — everything else is yours.

How closely to follow the reference depends on what the user asked for. "Make it look like this" means replicate the design language with new content. "Use this for inspiration" means echo the character but make it your own. "Here's our brand deck" means extract the brand system and apply it consistently. When in doubt, stay closer to the reference — it's easier for a user to ask you to diverge than to ask you to undo invented choices that conflict with their brand.

Load slide-design.md for specific guidance on color, type, layout patterns, composition, and what to avoid. When you have a reference file or brand guidelines, treat slide-design.md's principles as defaults for the decisions the user didn't make — not as overrides for the ones they did.

当用户提供Figma文件链接作为参考时，在设计前先研究它。你需要提取的内容取决于文件类型：

Slides文件：
```
get_metadata
```
不适用于Slides文件。使用
```
get_screenshot
```
捕获单张幻灯片作为视觉参考，并使用带有参考文件
```
fileKey
```
的
```
use_figma
```
运行只读脚本，提取主题变量、调色板、字体选择和布局模式。
Design文件：
```
get_design_context
```
可提供全面的设计数据——颜色、字体、布局结构。
```
get_screenshot
```
可提供视觉参考。两者结合使用。

在参考文件中寻找这些内容：调色板（主色调是什么、强调色是什么、背景深浅如何使用）、字体选择（字体族、字重、层级如何处理）、空间布局习惯（内容锚定位置、留白多少、元素是否超出边缘），以及任何重复的设计主题（形状、线条处理、装饰元素）。这些是你需要继承的决策——其他内容由你决定。

遵循参考文件的程度取决于用户的要求。“让它看起来和这个一样”意味着用新内容复制设计语言。“以此为灵感”意味着呼应其风格但加入自己的创意。“这是我们的品牌演示文稿”意味着提取品牌体系并一致应用。如有疑问，应更贴近参考文件——用户要求你偏离比要求你撤销与品牌冲突的自创选择更容易。

加载slide-design.md获取关于颜色、字体、布局模式、构图以及应避免内容的具体指导。当你有参考文件或品牌指南时，将slide-design.md的原则视为用户未做出决策时的默认选项——而非对用户已做出决策的覆盖。

Sections

章节

A section is a horizontal row in the slide grid — every row is a section. Names show up in the editor (next to the row) and in Presenter View (so speakers can jump between groups). They're an organizational aid for whoever is editing the deck — the user owns where the breaks fall, not you.

章节是幻灯片网格中的水平行——每一行就是一个章节。章节名称会显示在编辑器中（行旁边）和演示者视图中（以便演讲者在不同组之间跳转）。它们是为编辑演示文稿的人提供的组织工具——章节的划分由用户决定，而非你。

When asked to organize a deck

当被要求整理演示文稿时

"Organize this deck" is ambiguous — grouping, reordering, deduping, or restructuring. Read the deck before reaching for

AskUserQuestion

Default: propose, don't ask. Most decks have cues — title bookend, numbered use cases, repeated Before / After pairs, transition slides ("Then X enters the chat"), a Thank you. When cues exist, pick a sectioning and surface it in one confirmation message. Bounded calls inside the proposal (one Use Cases row vs. three, where a transition slide lives) are reversible — pick one and move on.

Fallback: ask when cues are absent. If slides are in arbitrary order or there's no spine, ask which ranges go together and what to call them. Don't slice by thirds as a substitute for reading.

“整理这个演示文稿”的表述模糊——可能是分组、重新排序、去重或重构。在调用

AskUserQuestion

前先阅读演示文稿。

默认做法：提出方案，而非询问。大多数演示文稿都有线索——首尾标题、编号用例、重复的之前/之后配对、过渡幻灯片（“然后X登场”）、致谢页面。当存在线索时，确定一种章节划分方式并在一条确认消息中告知用户。方案中的有限选择（一个用例行还是三个、过渡幻灯片的位置）是可逆的——选择一个方案继续执行即可。

备选方案：无线索时询问。如果幻灯片顺序混乱或没有主线，询问哪些范围的幻灯片应归为一组以及如何命名。不要用三等分的方式替代阅读内容。

Naming + scoping

命名与范围

Names should be short (1–3 words), concrete (Demo beats Show & tell), and consistent within a deck. Two to five sections is typical; more only for long or repeating decks. Names aren't slide titles — they help find a group, not describe its content.

名称应简短（1-3个词）、具体（Demo比Show & tell更好），并在演示文稿中保持一致。通常2-5个章节较为合适；仅在演示文稿较长或有重复内容时使用更多章节。名称不是幻灯片标题——它们帮助查找分组，而非描述内容。

Renaming a section

重命名章节

getSlideGrid()

returns

SlideNode[][]

— the inner arrays are plain JS arrays of slides, NOT

SLIDE_ROW

nodes. Setting

.name

on those arrays silently no-ops. To rename a section, traverse the node tree and set

.name

on the actual

SLIDE_ROW

const slideGrid = figma.currentPage.children.find(c => c.type === "SLIDE_GRID");
slideGrid.children[0].name = "Intro";

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";

Inspecting Slides Files

检查Slides文件

There is no dedicated read tool for Slides files yet. Use

use_figma

with read-only scripts for inspection, and

get_screenshot

await node.screenshot()

for visual context.

Inspect before creating. Before creating anything, run a read-only
```
use_figma
```
to discover what already exists — slides, text, components, naming conventions. The figma-use Section 6 "Inspect first" pattern applies here.
get_metadata
does NOT work on Slides files — it only supports
```
figma
```
(Design) editor type.
console.log()
output is NOT returned — only the
```
return
```
value comes back. Always
```
return
```
the data you need.
Use
get_screenshot
for visual context — pass a valid
```
nodeId
```
to get a screenshot. You can also use
```
await node.screenshot()
```
inline within
```
use_figma
```
scripts.

目前还没有专门用于Slides文件的读取工具。使用带有只读脚本的

use_figma

进行检查，并使用

get_screenshot

await node.screenshot()

获取视觉上下文。

创建前检查。在创建任何内容前，运行只读的
```
use_figma
```
脚本，发现已存在的内容——幻灯片、文本、组件、命名规范。figma-use第6节“先检查”的模式同样适用于此处。
get_metadata
不适用于Slides文件——它仅支持
```
figma
```
（Design）编辑器类型。
console.log()
的输出不会返回——只有
```
return
```
的值会返回。务必
```
return
```
你需要的数据。
使用
get_screenshot
获取视觉上下文——传入有效的
```
nodeId
```
以获取截图。你也可以在
```
use_figma
```
脚本中内联使用
```
await node.screenshot()
```
。

Quick inspection scripts

快速检查脚本

List all slides in the 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,
  }))
);

Get text content from a specific slide:

const slide = figma.getNodeById("TARGET_SLIDE_ID");
const textNodes = slide.findAll(n => n.type === "TEXT");
const fontsToLoad = new Set();
for (const t of textNodes) {
  if (t.fontName !== figma.mixed) {
    fontsToLoad.add(JSON.stringify(t.fontName));
  } else {
    const segments = t.getStyledTextSegments(["fontName"]);
    for (const seg of segments) fontsToLoad.add(JSON.stringify(seg.fontName));
  }
}
for (const f of fontsToLoad) {
  await figma.loadFontAsync(JSON.parse(f));
}
return textNodes.map(t => ({
  id: t.id,
  name: t.name,
  characters: t.characters,
  x: t.x,
  y: t.y,
  width: t.width,
  height: t.height,
}));

列出演示文稿中的所有幻灯片：

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,
  }))
);

获取特定幻灯片的文本内容：

const slide = figma.getNodeById("TARGET_SLIDE_ID");
const textNodes = slide.findAll(n => n.type === "TEXT");
const fontsToLoad = new Set();
for (const t of textNodes) {
  if (t.fontName !== figma.mixed) {
    fontsToLoad.add(JSON.stringify(t.fontName));
  } else {
    const segments = t.getStyledTextSegments(["fontName"]);
    for (const seg of segments) fontsToLoad.add(JSON.stringify(seg.fontName));
  }
}
for (const f of fontsToLoad) {
  await figma.loadFontAsync(JSON.parse(f));
}
return textNodes.map(t => ({
  id: t.id,
  name: t.name,
  characters: t.characters,
  x: t.x,
  y: t.y,
  width: t.width,
  height: t.height,
}));

Reference Docs

参考文档

Load only the references your task needs:

slide-gotchas — Pitfalls specific to Slides (coordinate offsets, opaque node types, validation workarounds)
slide-lifecycle — Create, clone, delete, and reorder slides and slide rows
slide-grid — Work with the slide grid layout (
```
getSlideGrid
```
,
```
setSlideGrid
```
)
slide-content — Build content within slides (text, shapes, auto-layout — SlideNode extends BaseFrameMixin)

slide-properties — Slide-specific properties (

isSkippedSlide

focusedSlide

focusedNode

slideThemeId

InteractiveSlideElementNode

)

slide-design — Design principles for visually interesting, varied decks (color strategy, typography, layout variety, spatial composition, anti-patterns)

仅加载任务所需的参考文档：

slide-gotchas — Slides专属陷阱（坐标偏移、不透明节点类型、验证替代方案）
slide-lifecycle — 创建、克隆、删除和重新排序幻灯片及幻灯片行
slide-grid — 处理幻灯片网格布局（
```
getSlideGrid
```
、
```
setSlideGrid
```
）
slide-content — 在幻灯片内构建内容（文本、形状、自动布局——SlideNode继承自BaseFrameMixin）

slide-properties — Slides专属属性（

isSkippedSlide

、

focusedSlide

、

focusedNode

、

slideThemeId

、

InteractiveSlideElementNode

）

slide-design — 设计视觉有趣、风格多样的演示文稿的原则（配色策略、字体、布局多样性、空间构图、反模式）