Figma Ai Bridge

Figma AI Bridge

Use this skill for the local workflow:

textCopy code
Figma Desktop plugin -> localhost bridge -> lean handoff bundle -> Codex implementation

Do not use Figma REST API, Dev Mode MCP, access tokens, or Figma mutation.

Preflight

From the repo root:

bashCopy code
./figma-ai-bridge doctor
./figma-ai-bridge status

If the bridge is stopped or stale:

bashCopy code
./figma-ai-bridge restart

Health endpoint:

bashCopy code
curl http://localhost:4778/health

Capture Boundary

Fully automatic capture from Figma requires the Figma Desktop plugin UI. Codex can automate post-capture work once a bundle exists.

For plugin setup and user-facing troubleshooting, read references/figma-plugin-setup.md.

Bundle Workflow

Prefer commands over manual JSON inspection:

bashCopy code
./figma-ai-bridge summary latest
./figma-ai-bridge validate latest

For a specific bundle:

bashCopy code
./figma-ai-bridge summary out/figma-bundle_YYYY-MM-DD_HH-mm-ss
./figma-ai-bridge validate out/figma-bundle_YYYY-MM-DD_HH-mm-ss

Read references/bundle-contract.md before judging missing or extra generated files.

Post-Capture Automation

Default automation is Codex-first and batches 3 captures per task section:

bashCopy code
./figma-ai-bridge auto latest

This validates the bundle and writes portable Codex task files:

• codex-visual-brief-task.md
• codex-enrichment-task.md

Manual alternatives:

bashCopy code
./figma-ai-bridge brief latest
./figma-ai-bridge codex latest --batch-size 3
./figma-ai-bridge enrich latest --batch-size 3

./figma-ai-bridge brief latest creates a Codex task by default. Generated public artifacts use English headings by default. External vision providers are opt-in:

bashCopy code
./figma-ai-bridge brief latest --provider omp --command 'omp -p --model gpt-5.1 {image_refs} {prompt}'

Read references/automation.md when the user asks for end-to-end automatic operation.

Implementation Reading Order

1. prompt.md
2. page-map.md
3. links-report.md if present
4. ./figma-ai-bridge summary <bundle>
5. Each relevant capture's visual-brief.md if present
6. Each relevant capture's preview.png
7. Each relevant capture's implementation.md
8. Each relevant capture's ai-notes.md if present
9. texts.json only for exact strings omitted from the higher-signal files
10. design-context.json only for exact geometry, colors, typography, autolayout, effects, and hierarchy

Do not load manifest.json, every texts.json, or full design-context.json files by default. Work only with captures relevant to the requested implementation.

Enrichment Rules

• Use preview.png once to write visual-brief.md; do not try to replace image inspection with JSON-only analysis when visual fidelity matters.
• Write generated public artifacts in English by default unless the user explicitly asks for another language.
• Use existing visual-brief.md and implementation.md first. Inspect preview.png again only when the brief is missing or ambiguous; open texts.json and design-context.json selectively.
• Keep assumptions explicit. Do not invent business logic.
• After enrichment, index/visual-briefs.md should link every generated visual-brief.md and ai-notes.md.
• Index-level reports should be concrete, not placeholders:
  • index/ai-summary.md
  • index/screen-inventory.md
  • index/component-candidates.md
  • index/implementation-risks.md

Failure Modes

• Bridge unavailable: run ./figma-ai-bridge restart, then ./figma-ai-bridge status.
• Stale bridge warning: restart before capture; otherwise Figma may use old generator code.
• No latest bundle: ask the user to run the Figma Desktop plugin or provide a bundle path.
• Validation errors: fix generator bugs before trusting the bundle for implementation.
• Cross-file links unresolved: the target file must be open in Figma Desktop; this workflow intentionally avoids Figma REST API.