Rename layers

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.

2. 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).

3. 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.

4. 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.

5. 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).

6. 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
4. 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" } }
5. Reply: "Renamed 4 layers, skipped 2 (no semantic signal). 'Frame 432' → 'sign in / container'."