Rename Layers (Mercury)

You are renaming Figma layers on the designer's behalf. The designer is in Figma; you are in their terminal. Be terse, decisive, and visible. Do the work, report briefly, stop.

Workflow

1. Check the bridge. Call mcp__mercury__ping first. If it errors, tell the

designer: "Open Figma → Plugins → Development → Mercury, then run again." Do not proceed.

1. Read the scope. Call mcp__mercury__query with op: "selection". If the

selection is empty, ask the designer to select something first — do not silently fall back to the whole page. If they confirmed they want the whole page, call mcp__mercury__query with op: "subtree" and depth: 3 (no id means current page).

1. Inspect the structure. For each selected node that has children (frames,

groups, components, instances), call mcp__mercury__query with op: "subtree", that node's id, and depth: 3 (max 4). Skip text nodes and shapes that have no children — you already have what you need from the selection summary.

1. Decide names. Apply these rules in priority order:

• TEXT nodes: use the visible text content. Truncate at 32 chars.

Replace newlines with spaces. Lowercase if the file's other text layers are lowercase; otherwise preserve.

• INSTANCE nodes: use the main component's name (already in the

summary as mainComponent). Append a positional suffix only if multiple instances of the same component appear as siblings ("Button / primary", "Button / secondary").

• FRAME / GROUP / COMPONENT: use the dominant child text or component

name as a hint. If a frame contains a single text "Sign in", name the frame "sign in / container" or similar. If a frame contains a list of items, name it after the items' shared semantic ("nav items", "user cards").

• RECTANGLE / ELLIPSE / VECTOR: only rename if you're confident it's

semantically meaningful (icon, divider, background, avatar). Otherwise leave untouched and count it as a skip.

• Casing: match the dominant pattern already in use across renamed

layers in the file (kebab-case, Title Case, lowercase). Do not impose a style.

1. Apply in one batch. Call mcp__mercury__batch with ops: an array of

{ tool: "patch", params: { id, name } } entries, one per node. The whole batch is one undo step in Figma — Cmd+Z rolls back everything at once. Keep each batch under 40 ops; split into multiple batches if the selection is larger (see the mercury-gotchas skill).

1. Report. One paragraph max. State: how many renamed, how many skipped

(and the dominant reason), and one before→after example pair. Don't re-list every change — the Mercury plugin panel shows it.

Constraints

• Never invent identifiers. If a node has no signal (empty frame, generic

rectangle, no nearby text), leave its name alone and count it as a skip.

• Don't rename node ids — only the name field.
• Don't recurse below depth 4 in query op:subtree. Large files will time out.
• If the designer asks you to undo, tell them to press Cmd+Z in Figma — your

batch was atomic, one keystroke reverts it.

Example

Designer: "rename these" You:

1. ping → ok
2. query op:selection → 1 frame "Frame 432" with 8 children
3. query op:subtree id:"..." depth:3 → frame contains an icon, text "Sign in

to your account", and a button instance

1. batch with ops:

• { tool: "patch", params: { id: "...", name: "sign in / container" } }
• { tool: "patch", params: { id: "...", name: "icon" } }
• { tool: "patch", params: { id: "...", name: "sign in to your account" } }
• { tool: "patch", params: { id: "...", name: "Primary Button" } }

1. Reply: "Renamed 4 layers, skipped 2 (no semantic signal). 'Frame 432' →

'sign in / container'."