Table of Contents
Figma + Claude Code Setup Guide
Get a new machine set up to clone the repo, connect Figma to Claude Code, and turn a Figma screen into real code
- Install Node.js, set up your git identity, then clone the repo.
- Generate a Figma personal access token (read-only) and register the Figma MCP server with Claude Code.
- Day to day: give Claude Code a Figma frame URL plus a description. It reads the design via MCP and writes code into
frontend/(orbackend/). - Pushing finished frontend work follows the same rule as everywhere else in this project: push directly to staging, never to main.
1. Prerequisites
- Install Node.js (LTS) from https://nodejs.org.
- Run the installer with default options. It adds Node to your system PATH automatically.
- If Windows SmartScreen blocks the installer, that's normal caution about a new .msi file. As long as you downloaded it from nodejs.org directly, click Run anyway.
- After installing, close and reopen your terminal. PATH only updates in new terminal sessions.
- Then verify both tools are installed:
node --version npm --version
Both commands should print a version number. If they say “not recognized,” your terminal session is stale. Open a brand new one.
2. Set your git identity (one-time)
- Before you can commit or push anything, git needs to know who you are.
- If you skip this step, your first commit will fail with an error telling you to set your identity.
- Run these two commands once, using the email tied to your GitHub account:
git config --global user.email "[email protected]" git config --global user.name "Your Name"
This is local identity only. It is separate from logging into GitHub, which happens in the next section.
3. Clone the repo and log into GitHub
git clone https://github.com/testing-22487/test.git cd test git checkout staging
stagingis the default working branch. All dev work happens here. See the branching rules below.- The first time you run
git pushfrom a new machine, Git or Windows will likely open a browser window asking you to log into GitHub. - It may instead prompt for a username and personal access token in the terminal, depending on how git is configured.
- Log in once. After that, your credentials are cached locally, so future pushes won't ask again.
Do not overwrite the original(from Github) CLAUDE.md after cloning. It's the project's real, git-tracked rules file covering roles, branching, and security. It does not need editing as part of this setup.
4. Generate a Figma personal access token
- In Figma, click your profile picture, then Settings.
- Go to Personal access tokens, then Generate new token.
- Name: anything descriptive, e.g. Claude Code MCP.
- Expiration: 90 days. You'll regenerate and swap it in when it expires. Short-lived tokens are safer than permanent ones.
- Scopes: turn on File content, Read only only.
- Leave every other scope (Variables, Dev resources, Webhooks, Library content, Comments) set to No access.
- This token only needs to read designs. It should never be able to write or delete anything in Figma.
- Copy the token now. Figma only shows it once.
Never paste this token into a chat with Claude, a Slack message, or commit it to git. Anything pasted into a chat can end up logged permanently. If a token is ever exposed, treat it as compromised: revoke it on Figma's Personal access tokens page and generate a new one.
5. Connect the Figma MCP server to Claude Code
- Open a terminal in the repo folder. This matters: the registration is scoped to whatever folder you're in.
- Run this command, replacing YOUR_TOKEN_HERE with the real token from step 4:
claude mcp add figma --env FIGMA_API_KEY=YOUR_TOKEN_HERE -- npx -y figma-developer-mcp --stdio
- The output should say something like this:
Added stdio MCP server figma for project path
If the project path shown is wrong (for example, system32), your terminal wasn't in the repo folder when you ran the command. Fix it by running cd into the repo folder first, then re-running the claude mcp add command above.
6. Restart and verify
- Restart your terminal first.
- Then restart VS Code, or start a fresh Claude Code session, so the new MCP server loads.
- Restarting the terminal refreshes your PATH. Restarting VS Code is what makes Claude Code pick up the new figma MCP server registration. Do both, in that order.
- Then check the connection:
claude mcp list
- You should see the figma server listed as connected.
If it says “Failed to connect” on the very first check, it's usually just npx downloading the package for the first time. Wait a few seconds and run the list command again.
7. Day-to-day workflow
Once connected, the loop is:
- Give Claude Code a Figma file or frame URL and describe what to build, e.g. “implement the Login screen from this Figma frame.”
- Claude reads the design via the MCP connection and writes the matching code into
frontend/(orbackend/for server-side work). - Review the code, then commit and push directly to
staging. See section 8 below for the exact push steps.
Never push or merge into main. Only the project admin or owner promotes staging into main, via a pull request, once staging has been tested.
8. Pushing completed frontend work back to GitHub
Figma is a frontend/UI-only tool, so the backend dev never touches the Figma MCP connection. This section covers getting finished frontend/ work from your machine back onto GitHub.
- Check what changed. This confirms which files under
frontend/were modified or added:
git status
- Pull latest first, in case the backend dev pushed to staging since you last synced. This avoids an avoidable merge conflict later:
git pull origin staging
- Stage your frontend changes, scoped to
frontend/so you don't accidentally stage unrelated files:
git add frontend/
- Commit with a clear message:
git commit -m "what you did"
Replace “what you did” with your own plain description of the change, e.g. “Add login screen component from Figma design.” Git stores whatever text you put after -m as-is; it's a label for humans reading history later, not something git parses or validates.
- Push directly to staging. No feature branch or PR needed for this step, per this project's rules:
git push origin staging
- Verify on GitHub: open the repo in a browser, switch to the staging branch, and confirm your commit and files appear under
frontend/.
If the pull in the second step reports a conflict, stop and resolve it manually. Don't force-push. Since frontend/ and backend/ are separate folders, conflicts should be rare; if one shows up, check with the backend dev before resolving.
Reference: roles and branches
| Branch | Who touches it | How |
|---|---|---|
| staging | Frontend + backend devs | Push directly, no PR needed |
| main | Admin/owner only | PR from staging, after testing |
See CLAUDE.md at the repo root for the full project rules: team roles, security notes on payment/client data, and tech stack once decided.
