Figma Local Workflow

Local Figma workflow

Use an inspect-first sequence. Do not begin by querying arbitrary page nodes or editing the current selection.

Required sequence

1. Call figma_bridge_status. Continue only when exactly one plugin is connected, and use its reported page name to confirm the expected Figma context.
2. Call figma_get_user_preferences before choosing components, styles, tokens, typography, layout conventions, or copy patterns. Treat only returned confirmed preferences as durable user guidance.
3. When review feedback is relevant, call figma_comment_status, then figma_list_comments before editing. Comment access is optional; if it is unavailable, report the missing REST setup without blocking unrelated canvas work.
4. Call figma_list_design_system_assets, then figma_list_artboards. Discover verified component/style/token candidates and stable artboard IDs; never guess IDs or recreate an appropriate available component. If the relevant artboard is absent, call figma_list_pages, navigate with figma_navigate_to_page, then repeat discovery.
5. Identify the relevant artboard or page pair:
   • Call figma_read_frame_content with detail: summary for one artboard.
   • Call figma_read_spread_content with detail: summary for a spread, passing nodeIds in the order returned by figma_list_artboards.
   • Request detail: full only when hierarchy or hidden variants are needed.
6. For routine copy-only work, use the structured read and figma_audit_text_overflow; do not export or screenshot by default. Export or screenshot only when layout, imagery, geometry or uncertain wrapping needs visual judgement.
7. Analyse copy and layout before proposing or making changes. Call figma_audit_text_overflow when text fit, truncation, clipping, or typography may matter.
8. Only then edit identified nodes. Prefer the narrowest appropriate mutation tool and preserve unrelated content.
9. Verify after editing:
   • Re-read affected frame or spread content.
   • Re-run the overflow audit when text or dimensions changed.
   • Capture a screenshot only for uncertain wraps, adjacency or visual hierarchy; export a PNG only for a full-page/layout review, imagery or retained comparison.

Fast review path

After artboard discovery, use figma_prepare_review only for a visual page/spread review. It reads the copy and optionally audits overflow in one plugin operation, then writes the PNG exports locally without leaving document edits. For copy reconciliation, prefer figma_read_copy and overflow auditing so routine work does not consume image tokens.

Review comments

Comments use Figma's REST API rather than the live plugin connection. Canvas tools remain token-free; figma_comment_status reports whether the optional token and file key are configured without revealing the token.

• If comment access is unavailable, direct the user to Figma API access in the connected plugin. Never ask them to paste a token into chat or an MCP tool call. The plugin can save it to secure OS storage and verify read access; write access is verified only by an intentional comment write.

• List comments before editing when the user refers to review feedback. Preserve returned comment IDs, parent IDs, author, resolved state, node/canvas position and timestamps as source data.

• Post a root comment only at a verified frame ID or explicit canvas coordinates. Reply using the identified root comment ID; do not invent a thread relationship.

• The API does not offer edit or resolve operations through this bridge. Never claim a comment was edited or resolved. Post a correction/reply or ask the user to resolve it in Figma.

• Delete only a comment the user explicitly identifies, and pass the deletion confirmation guard. Deletion is permanent.

• Re-list comments after a write when verification matters. Treat a successful REST response as comment verification; it does not prove a canvas edit.

Layout responsibility and evidence cost

Use the bridge for deterministic mechanics: frame geometry, hierarchy, components, named styles, text bounds, overflow, alignment and mutations. Use this skill for editorial hierarchy, page purpose, content density, print-reading judgement and deciding when an image review is worth its cost.

Reference boards and new canvas areas must use native Figma structure: create a SECTION with figma_create_section, then place native frames, components and editable text inside it. Never use an imported SVG group as a board, panel system, UI layout, or editable label. Reserve figma_import_svg for approved logos, icons and isolated vector artwork.

Do not ask image output to prove routine text updates. Treat text bounds, re-read copy and overflow results as sufficient unless a change may alter adjacent elements, column balance, image relationship or hierarchy. Prefer one targeted screenshot over a PNG export when a visual check is necessary.

Design-system preferences and tie-breaks

Treat the bridge preference store as explicit per-user memory, not automatic learning.

• Query it with figma_get_user_preferences. The user may ask in natural language what is known, why a choice is preferred, or which scope it applies to; answer from the returned records.
• Prefer assets in this order: a confirmed scoped user choice; an appropriate linked-system component already used in the file; another verified component instance; a named style or bound variable; a verified source-node style; raw construction only when none applies.
• Use figma_create_component_instance for a verified component ID/key and figma_apply_design_style for a verified style ID/key. Preserve component linkage and variables instead of detaching or copying raw values.
• When two or more systems or assets remain equally plausible, call figma_resolve_design_choice. If it returns needsClarification: true, make no edit and ask the returned question with a concise candidate list. Never settle the tie from visual similarity, current selection, or library order.
• After the user answers a tie, use that choice for the current task. Offer to save it with an appropriate project, document-type, or context scope; do not save unless the user explicitly confirms.
• Create or update a record with figma_set_user_preference only from explicit user guidance. Read first and pass expectedRevision. Use the same revision guard for delete or revert operations.
• Do not convert a one-off canvas choice into an ongoing preference. Do not silently infer taste from existing documents, generated layouts, or repeated tool calls.
• A linked library must already be enabled by the user in the Figma file. If an expected library is unavailable, explain that boundary rather than approximating its assets.

Delegated copy preparation

Use a capable subagent for copy analysis or source-to-Figma diffing when it will reduce context cost, especially across several pages. Do this before the live bridge session.

• Give the subagent the source copy and a compact, already-captured Figma copy snapshot with frame IDs and text-node IDs.
• Ask it to return a narrow diff packet: frame ID, node ID, exact current text, replacement text and a one-line rationale. Omit unchanged nodes.
• Keep the subagent read-only. It must not call the local bridge, edit the Figma file, or perform visual verification.
• The primary agent owns the live bridge connection, makes all mutations serially, and verifies the rendered result.

The bridge has one live plugin connection and Figma mutations are serial. Delegation improves preparation quality and token use; it does not make the live write path parallel or safer.

External copy-sync recipe

Use this flow only after the user identifies which source is authoritative and the intended sync direction:

1. Confirm the bridge/page and list artboards. Identify the exact target frame IDs.
2. Call figma_read_copy with those frame IDs and includeHidden: false. Use its text IDs and copy as the Figma side of the diff; do not request full hierarchy unless the compact result is ambiguous.
3. Fetch the latest external source, then diff it against the visible Figma text IDs in the user-requested direction. Omit unchanged nodes and preserve source-specific metadata that the user did not ask to replace.
4. Re-fetch or stop on a source conflict. Never overwrite a newer external or Figma change blindly.
5. Preserve expectedText from the compact Figma read for every proposed Figma update. Keep hidden text excluded unless the source explicitly targets a hidden variant.
6. For a small, known-safe Figma batch, call figma_apply_copy_updates. For longer copy, several frames or a bridge that has been slow, use serial figma_update_text calls instead.
7. Audit and inspect after layout-affecting Figma edits. Use a re-read and overflow audit for routine copy-only edits; use a screenshot for uncertain wraps and a PNG export for layout, imagery, full-page review or retained comparison.
8. Re-read compact copy when an expectedText guard fails or verification is incomplete. Never overwrite a concurrent edit from stale source data.

Timeout recovery

For a tracked composition, keep its operation ID and call figma_operation_status after interruption or caller timeout. If it is queued or running, wait; if it succeeded, use the returned result; if it failed, diagnose that error. Reuse the same operation ID to resume the request and never start a duplicate while its outcome remains available or unknown.

For an untracked mutation batch, do not retry immediately. Reconnect the plugin if needed, then re-read the affected visible text and determine which updates landed. Apply only the remaining changes with fresh expectedText guards. Do not create an alternate frame, hide the old one or issue a second blind batch to recover.

Re-layout a page recipe

Use this deterministic flow when replacing an existing brochure page or artboard layout:

1. Confirm the bridge/page, list artboards, read the exact target with detail: summary, and export its current PNG before changing anything.
2. Use figma_list_design_system_assets and figma_list_page_tokens to discover verified components, variables, styles, colours, and fonts. Prefer an appropriate component instance or named style; use figma_copy_style_from_node when a known source node is the clearest brand reference. Never approximate a value already present in the file.
3. Define one clearly named replacement frame. Use figma_start_composition for a potentially slow board, then poll figma_operation_status; use figma_compose_frame directly only when a blocking call is appropriate. Keep keys unique and declare parent elements before their children.
4. Build ordered native frame/rectangle/text elements and use styled spans for mixed emphasis. For an approved image already in Figma, set imageSourceNodeId on its composed frame or rectangle instead of duplicating and reparenting nodes. Set imageRequired: true wherever an image is necessary to call the board complete.
5. Prefer supplying explicit previous sibling IDs in archiveNodeIds. The composer archives them only after text/export/image verification succeeds. If verification is incomplete, inspect imageAudit, preserve the previous layout, and fix the replacement before retrying or archiving separately.
6. Inspect the compact audits and local PNG returned by the composer. Use a full read only when the summary lacks necessary hierarchy.
7. Re-read the replacement in summary mode and confirm the archive name/replacement relationship. Do not delete the archived group unless the user later identifies it for permanent removal.

Reference-board recipe

1. Call figma_inspect_canvas_layout without a target to read native sections and the occupied top-level canvas envelope. Figma pages are unbounded; do not mistake that envelope for a page boundary.
2. Collision-check the proposed section rectangle. Create it with figma_create_section only when the result is clear, or when the user explicitly accepts an intentional overlap.
3. Compose with the new section ID as frame.parentId; use figma_start_composition plus status polling when the board may be slow. Build panels from native frames/components and labels from editable natural-case Figma text with textCase styling.
4. Treat a blank response, COMPOSITION_EMPTY_OR_INCOMPLETE, or any other composition failure as a hard stop. Inspect and retry the native path; never switch to an SVG layout workaround.
5. Call figma_inspect_canvas_layout with the created node ID to verify sibling collisions. Use a targeted screenshot when adjacency or visual overlap still requires judgement.

Working rules

• Treat artboard IDs and text-node IDs returned by read tools as the source of truth.
• Read a whole frame or spread before changing individual text nodes; surrounding copy determines meaning and fit.
• Keep spread order explicit. Do not infer left/right order from node names.
• Treat copy as effectively visible text. Check allCopy, hiddenTextCount, and each text item's effectiveVisible value when hidden variants or conditional content matter.
• Before every text creation or replacement, distinguish stored content from visual casing. Author generated headings, labels, buttons and navigation copy in natural sentence/title case, then apply textCase during creation or call figma_set_text_case for an existing layer. Never send all-caps characters merely to make text look uppercase.
• Never put UI-label copy into SVG paths or SVG text. Keep it as native, editable Figma text in natural case and use textCase for presentation.
• Preserve exact all-caps characters only when they are semantically meaningful, supplied by an authoritative source, or explicitly requested as character-level copy. If an existing source is ambiguous, preserve it rather than guessing the natural capitalization.
• Treat emphasis, case, decoration, line height, letter spacing, font family/style, and size as typography—not copy. Prefer verified Figma text styles, figma_copy_style_from_node, or styled-span options over manually altering characters or splitting text into extra layers.
• Preserve design-system linkage. Prefer figma_create_component_instance, figma_apply_design_style, and bound variables over detached copies or hand-built imitations.
• Use figma_update_text only for an identified text node. If the intended change is presentation-only casing, do not call it; call figma_set_text_case and verify that the stored characters remain unchanged. Use structural tools only after inspecting hierarchy and bounds.
• Make small, reversible batches and verify each batch before continuing.
• For copy-only work, overwrite the existing visible text layers. Do not create duplicate layouts, hide existing layers, or reduce old nodes to zero opacity. Use replacement/archival only for an explicitly requested layout change, and state the result clearly.
• Prefer figma_archive_nodes or figma_supersede_layout over opacity-zero superseded layers. Archive only explicit siblings and always record the replacement when one exists.
• Use figma_start_composition plus figma_operation_status for a potentially slow board. Use figma_compose_frame for a bounded composition that is expected to finish within the blocking call. Treat text, export, and required-image audits as completion evidence.
• Reuse an existing approved Figma image with a composed element's imageSourceNodeId. Mark visually necessary image areas with imageRequired: true; never call a board finished or archive its predecessor while imageAudit.warningCount is non-zero.
• Before placing a new section or top-level frame, inspect canvas bounds and collision-check the proposed rectangle. After placement, collision-check the actual node and visually inspect any uncertain adjacency; coordinate assumptions alone are not verification.
• Use figma_place_local_image only for an absolute local image path the user explicitly placed in scope or an HTTPS image URL the user explicitly approved. URL fetches are limited to public IP destinations, revalidated across at most five redirects, capped at 25 MB, and checked by image signature. Prefer figma_copy_image_fill when an approved image already exists in Figma.
• Place images at their intended final dimensions before applying custom crops. If a CROP-filled node is resized to a different aspect ratio, the bridge switches that fill to centered FILL to prevent distortion and reports the change; review the new crop if the original focal point matters.
• Delete only a clearly stray element that the user identified. Otherwise preserve it, including superseded or hidden elements.
• Use figma_screenshot for a targeted, one-off visual check. Use figma_export_frame_png only for a full-page/layout review, imagery, comparison or an artefact that needs to be retained; do not export routine copy-only changes.
• Keep bridge calls serial and in one task. A newer open plugin deliberately takes over the single local connection; the displaced plugin stops retrying.
• If the figma_local tools are absent from the task, stop and report that Codex has not loaded the configured MCP server. Do not substitute the hosted Figma MCP without the user's permission.