Audit a Figma file with AI
FigmaMCP lets Claude Code or Codex audit a Figma file with reads only: unnamed frames, text with no style, hard-coded colors and components with no properties. Reads never change the file, so an audit is a safe first job. You can switch off edits while it runs. Notes are the only write, and they are optional.
What to ask for
| Question | Reads |
|---|---|
| Which layers are still named “Frame 12”? | page_info, node_info |
| Which text uses no text style? | node_info, style_list |
| Which fills are hard-coded, not variables? | node_info, variable_list |
| Which components have no description or properties? | component_list |
How the agent reads a file
FigmaMCP’s page_info lists the pages, and with page IDs it returns each page’s top-level layers, up to 25 pages per call. node_info reads layers and their children. You choose the properties, a filter and a depth. For an audit, useful properties are boundVariables, fillStyleId, strokeStyleId, effectStyleId and textStyleId. A layer with no style or no bound variable shows up as a finding.
style_list returns the local paint, text, effect and grid styles. variable_list returns local variables and collections. With a variable ID and includeConsumers, it also lists which layers use that variable. component_list can filter by local or remote, and by page or whole document. Styles and variables from shared libraries do not appear in these lists. The agent finds them through a layer that uses them.
Check that the read was complete
A read that returns without an error can still be partial. FigmaMCP’s multi-page reads return a coverage object. Read coverage.complete before you say that a page is clean. coverage.pageErrors names each page that failed and gives a reason.
| Code | Meaning | What to do |
|---|---|---|
PAGE_LOAD_FAILED | One page refused to load. | Retry once. If it fails again, continue with the other pages and report that page. |
PAGE_SCAN_FAILED | The page loaded, but reading it failed. | Narrow the read to one page, one layer or fewer properties. |
PAGE_LOAD_TIMEOUT | A page did not load in time. | Retry once, then continue without it and say so. |
PAGE_NOT_FOUND | The page ID does not exist. | Get fresh IDs from page_info. |
Write the findings into the file
The agent can report in chat. It can also write each finding as a native annotation with annotation_set. That tool needs the layer ID, the exact layer name and a Markdown label. This is a write, so the AI can edit this file switch must be on. Without it you get READ_ONLY_MODE. Annotations are appended. Run annotation_list first, so a second audit does not add the same note again.
A sensible order
- Ask for one page at a time. Large files take many calls.
- Ask for a short report that groups findings by type.
- Fix what you agree with using bulk edits.
Download for Mac Version 0.1.20 macOS 14+ · Intel & Apple Silicon · ~155 MB
Related: All tools · Design system · Variables
Questions
Can an audit change my file?
Can it read a very large file?
How do I know the audit covered every page?
Does it list styles and variables from shared libraries?
Last updated: