Connecting Figma

Figma is REVETOOL's most powerful connector. With OAuth granted, REVETOOL can pull frames as screens, fetch design tokens (variables), generate HTML from frames using AI vision multimodal, and post comments back to Figma.

What REVETOOL needs from Figma

REVETOOL uses Figma OAuth with 14 scopes for full integration potential:

• file_read — read frames and file metadata
• file_comments:read/write — read and post Figma comments
• file_dev_resources:read/write — Dev Mode resources sync
• library_content:read + library_assets:read + team_library_content:read — design system access
• file_versions:read — version history
• projects:read — project listing
• webhooks:read/write — file update notifications (Sprint G)

How to connect

1. Open Workspace settings → Connectors.
2. Click Connect Figma.
3. You are redirected to Figma OAuth consent screen.
4. Review the 14 scopes, click Allow.
5. You are redirected back to REVETOOL with a green check.

Importing a frame

Inside any project, click Add a screen → URL tab.

1. Paste a Figma frame URL (must include ?node-id=X-Y).
2. REVETOOL detects it's a Figma URL and switches to Design env.
3. If no node-id is present, you get a warning and can pick a frame from the file.
4. Click Import. REVETOOL fetches the image (PNG up to 5MB) + JSON tree.

What gets imported

• Image — PNG render at 1x (with 7-fallback chain for complex frames: PNG/JPG × 1x/0.5x/0.25x × +/- absolute bounds + SVG)
• JSON tree — layout, colors, typography, components (compressed to ~500 chars for AI prompts)
• Design tokens — Figma variables (colors / spacing / typography) injected into AI HTML generation prompts
• Link back — REVETOOL stores file_key + node_id for live re-sync

Figma → HTML AI

The signature feature: ask REVETOOL AI to generate an interactive HTML version of a Figma frame.

1. Open a Figma-imported screen in the Review surface.
2. Click Generate HTML with AI.
3. AI reads the image + JSON + design tokens + linked specs and tickets.
4. It returns an interactive HTML screen attached as a child of the Figma parent.
5. Compare design vs generated HTML side-by-side in Review.

Troubleshooting

Image is blank

Complex frames sometimes return empty PNG from Figma API. REVETOOL applies a 7-fallback chain (PNG → JPG → lower resolution → SVG). If all 7 fail, you get a clean placeholder + instructions to simplify the frame.

OAuth fails with "incorrect client credentials"

Your FIGMA_CLIENT_SECRET may be invalid. Workspace admins can regenerate via Figma developer settings and update REVETOOL config.

I lost access to the file

REVETOOL uses your personal token. If you lose access to a file in Figma, you lose access in REVETOOL too. The screen stays cached (image + JSON) but live re-sync will fail until access is restored.