Skip to content

docs: fix get_metadata page-enumeration guidance (returns only the active page) #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jkRaccoon wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fix get_metadata page-enumeration guidance (returns only the active page) #75

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions skills/figma-use/references/gotchas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,8 +232,8 @@ The same rule generalizes to *any* traversal: scope it to the smallest known anc

A Figma file can have multiple pages (canvas nodes). `get_metadata` only returns the subtree of whichever node you pass it. To get a usable index of every page:

- Call `get_metadata` with **no nodeId** — it returns the document's top-level pages as `{guid, name}` entries (no XML dump). This is the cheapest way to discover pages.
- For more detail per page (e.g. child counts, top-level node types), fall back to `use_figma`:
- **Do not rely on `get_metadata` to enumerate pages.** Even with **no nodeId**, its response header reads "Listing the top-level pages of the document" but it returns only the **currently-active page**, not all of them. (Verified 2026-07-10 against a 9-page file: it returned a single page.) The tool's own `description` makes the same incorrect claim, so an agent that trusts it wastes a call every time it needs the full page list.
- **Enumerate pages with `use_figma` — this is the only reliable way:**

```js
const pages = figma.root.children.map(p => `${p.name} id=${p.id} children=${p.children.length}`);
Expand Down