Docs

Connecting Figma

Heuristics reads your frames through Figma's official API — the same permission model that powers the Figma MCP server used by AI design tools. Nothing is scraped from a web page and your Figma password is never entered here.

For designers: two ways to connect

Option A — Sign in with Figma (OAuth)

Go to Settings (or the Figma step of a new evaluation) and click Continue with Figma.
Figma opens. Sign in if needed and pick the account that has access to your files.
Approve the requested read-only scopes: file content, file metadata, and current user.
You're redirected back and the connection shows as active. Tokens refresh automatically.

If the button says sign-in isn't enabled, your administrator hasn't registered the OAuth app yet — see the operator section below, or use Option B.

Option B — Personal access token

In Figma, click your avatar (top-left) → Settings → Security tab.
Under Personal access tokens, choose Generate new token.
Name it “Heuristics”, pick an expiration, and set File content → Read-only and File metadata → Read-only. Leave write scopes off.
Copy the token immediately (Figma shows it once) and paste it into the app.

The token is encrypted before it is stored and is only used to fetch frames from links you paste. Revoke it in Figma or disconnect in Settings at any time.

Which links work

Link	Result
figma.com/design/…?node-id=…	Link to a frame → that screen. Link to a section or a frame that contains screens → every screen inside it, in flow order.
figma.com/design/… (no node-id)	All top-level frames on the first page that has a prototype flow (else the first page).
figma.com/proto/…	The prototype's screens, ordered by following its connections from the starting frame.
<iframe src="embed.figma.com/…">	Embed snippets are accepted — the real link is extracted from the iframe.
Folder / project / team URLs	Not supported — open the file and copy a design or prototype link instead.
.fig files, Figma Make, FigJam, Slides	Not readable through the API. Import into a Figma Design file and share its link, or export PNG/PDF.

How flow order is detected

Prototype connections first. If frames are linked with interactions (“On click → Navigate to”), we start at the flow's starting point (or the frame in your link) and follow the connections.
Canvas position otherwise. Frames are read like a page: row by row, left to right — the way most flows are laid out.
You have the final say. Before running, you can reorder, deselect, or rename screens. Numbers and arrows drawn in the mock-ups are also read by the evaluator.

For operators: enable “Sign in with Figma”

Personal access tokens work with no setup. To offer the one-click OAuth option, register the app with Figma once per deployment:

Open figma.com/developers/apps and click Create a new app. Give it a name and logo.
Under OAuth 2.0, add the redirect URL https://<your-domain>/api/figma/oauth/callback (add http://localhost:3000/api/figma/oauth/callback for local development).
Enable the scopes file_content:read, file_metadata:read, and current_user:read.
Copy the Client ID and Client secret into the environment variables FIGMA_CLIENT_ID and FIGMA_CLIENT_SECRET, and set NEXT_PUBLIC_APP_URL to your public origin. Redeploy.

FIGMA_TOKEN_ENCRYPTION_KEY must also be set (any long random string) so users' tokens are encrypted at rest. The Settings page shows the current status of each variable.

FAQ

Why can't the app just open my Figma link?

Figma renders designs on a canvas inside a logged-in browser session. There is no design content in the page HTML, so a link alone can't be read — the API (via OAuth or a token) is the only reliable way.

Can I evaluate a whole folder of files?

Run one evaluation per file or flow. Inside a file, a section or container frame link brings in every screen at once.

What if my screens aren't connected as a prototype?

Lay them out left-to-right (or in rows) and we'll read them in that order. You can still drag screens into the right sequence before running.

Is my data shared with anyone?

Frames are exported as images into your private storage and sent to Claude only to generate your report. Disconnecting Figma removes the stored token.