FigmaMCP

Run a design QA pass on a Figma file with an AI agent

This tutorial shows how to let Claude Code or Codex check one frame in your Figma file and fix what it finds. The agent scores the frame against a written rubric, fixes the lowest categories, looks at the frame again and repeats until every category scores 9 or more. It works on the live file through FigmaMCP and the Figma desktop app on your Mac.

What you will do

You will copy one skill, open the FigmaMCP plugin in your file and ask for design QA on one frame. The agent then runs a loop: look, score, fix, look again. You get a table with the scores for each round and the fix the agent applied in it.

The six categories

Design QA rubric categories
CategoryWhat loses points
AlignmentChildren of a stack with different left edges; labels that are not centered in their button
SpacingGaps that are not a multiple of 4; more than two gap sizes in one stack; uneven padding
Type scaleFont sizes off the scale 12, 14, 16, 20, 24, 32, or the scale your file uses
ContrastText below 4.5:1 against its background, or below 3:1 for large text
NamingDefault layer names such as Frame 12, Text or Rectangle 3
Auto layoutStacks, inputs and buttons laid out by hand instead of with auto layout

Each category starts at 10 and loses points for each problem. The full penalties are in the skill’s rubric.

Steps

  1. Set up FigmaMCP

    Install the FigmaMCP Mac app and connect Claude Code or Codex. If you have not done this yet, follow the tutorial Edit a Figma file with Claude Code in 5 minutes first.

    Setup is the same for every task. See Edit a Figma file with Claude Code in 5 minutes or Figma MCP setup for Mac.

  2. Copy the figma-design-qa skill

    Copy the skills/figma-design-qa folder from the FigmaMCP releases page into ~/.claude/skills/ for Claude Code, or ~/.codex/skills/ for Codex. Then start a new agent session.

    A skill is a short instruction file. This one tells the agent how to score a frame and which tools fix which problem. The FigmaMCP app installs only the base figmamcp skill, so you copy this one yourself. Get it from skills/figma-design-qa; the rubric is in references/rubric.md.

  3. Open the plugin and check the switch

    Open the file in the Figma desktop app, then choose Plugins, Development, FigmaMCP. Make sure the AI can edit this file switch is on. Work on a duplicate of the file or frame if you want to keep the original.

    FigmaMCP plugin panel showing Connected to a file, the AI can edit this file switch turned on, and 1 AI session connected
    The FigmaMCP panel in Figma. With the switch off, the agent can only read.
  4. Ask for design QA on one frame

    Name one frame and a target, for example: “Run design QA on the frame Sign-up card until every category scores 9 or more.” The agent says which frame it will edit, by name and ID, before it writes.

    You can also set the round limit (the default is 5), or give the type scale your file already uses.

  5. Let the agent score the frame

    In round 0 the agent reads the frame with node_info and exports it with node_export_visual as a picture. It scores six categories from 0 to 10: alignment, spacing, type scale, contrast, naming and auto layout. The overall score is the mean of the six.

    The scores come from numbers, such as left edges, gaps, font sizes and contrast ratios, not from the picture alone. The agent writes down each problem with the number that proves it.

  6. Let it fix and score again

    In each round the agent fixes the one or two lowest categories, exports the frame again and scores all six again. It stops when every category is 9 or more, at the round limit, or when a round raises no score.

    Fixing one or two categories per round keeps each change small enough to review in Figma.

  7. Review the result

    The agent reports one table row per round, with the fix it applied and the six scores, then anything it could not fix and why. Check the frame in Figma, and use version history to undo a round you do not want.

Example result: 1.7 to 10.0 in three rounds

This is the worked example in the skill’s rubric, from a live run on 2026-11-20. The frame was a sign-up card built messy on purpose: a title, a subtitle, two input frames, a button frame and a log-in line.

Design QA scores per round
RoundFix appliedAlignSpacingTypeContrastNamesAuto layoutOverall
0(none)0042041.7
1Card: vertical auto layout, padding 32, gap 16, hug height; fields and button fill width81042075.2
2Sizes 27/15/13/14/17/11 → 24/16/14/14/16/12; three greys to #64748B/#6B73809101010077.7
3Fields and button: horizontal auto layout, padding 16, centered; button height 46 → 48; 10 layers renamed10101010101010.0

A frame from a real project will start from a different score, and some problems may be outside what the rubric or the tools can fix. The agent then stops and tells you what is left.

What the agent will not do

Notes

Next: auto layout tools, export a frame as an image, use cases, or all tools.

Last updated: