figma-raw-geometry

Use the Figma REST API as a measurement source. Return numeric measurements with field provenance and keep implementation assumptions separate from fetched values. A screenshot describes one rendered state; the node JSON exposes the state's geometry, transforms, visibility, and layer opacity.

1. Define the states and targets

Collect:

• the file key, decoded from the Figma URL;
• the containing frame or component-set id;
• every target state or variant id;
• the target layer mapping for each state; and
• the ordered prototype edges when reconstructing animation.

Decode a URL's node-id=123-456 as the Figma id 123:456, including URL percent-decoding when necessary. Do not infer prototype order from variant names. If an available Figma MCP metadata tool can enumerate a component set, use it. Otherwise, request the component-set node with the REST nodes endpoint and depth=1 to discover its direct variant children.

Map corresponding layers by structural path plus name. Include a sibling index when names repeat; do not assume that child node ids are shared between component variants.

Done when every requested state has a file key, root id, containing-frame id, and an unambiguous target-layer mapping, or an explicit unresolved reason.

2. Authenticate outside the conversation

Read FIGMA_TOKEN from the process environment. The token needs Figma's file_content:read scope and access to the target file.

If the variable is absent, ask the user to set it in their own shell or secret manager and then confirm that it is available. Keep the secret out of chat, files, command output, and commits. The agent cannot export a value into the user's parent shell, so do not ask the user to paste the token into the conversation.

Done when a usable environment token is available without the token value being printed or persisted by this workflow.

3. Fetch the node JSON in bounded bulk

Request all required ids together when the URL and response are practical. If the target set is too large, split it into bounded batches and pin the same Figma version for every batch. Use depth to avoid fetching irrelevant descendants; add geometry=paths only when vector path data is needed.