---
title: "Figma MCP — Custom Rules and Instructions"
aliases: [figma-mcp-rules, figma-claude-md, figma-mcp-integration-rules]
tags: [claude-code, figma, mcp, rules, claude-md, design-to-code]
sources: [raw/Add custom rules and instructions.md]
created: 2026-05-15
updated: 2026-05-15
---

# Figma MCP — Custom Rules and Instructions

Project-level rules that guide AI toward consistent, high-quality output when translating Figma designs into code. Think: the "unwritten rules" experienced devs know — written down once so agents follow them every time.

## Why Add Rules

- Eliminates repetitive prompting ("use our design system components")
- Ensures teammates and agents follow the same conventions
- Reduces back-and-forth with the AI
- Enforces design fidelity and accessibility from the start

## General-Purpose Rules (starter set)

```markdown
- IMPORTANT: Always use components from `/path_to_your_design_system` when possible
- Prioritize Figma fidelity to match designs exactly
- Avoid hardcoded values, use design tokens from Figma where available
- Follow WCAG requirements for accessibility
- Add component documentation
- Place UI components in `/path_to_your_design_system`; avoid inline styles unless truly necessary
```

## Required Figma MCP Flow (do not skip)

Add this to your CLAUDE.md to enforce the correct tool call sequence:

```markdown
## Figma MCP Integration Rules

### Required flow
1. Run get_design_context first — fetch structured representation for the exact node(s)
2. If response too large/truncated → run get_metadata for node map, then re-fetch specific node(s)
3. Run get_screenshot for a visual reference of the variant being implemented
4. Only after get_design_context + get_screenshot — download assets and start implementation
5. Translate output (usually React + Tailwind) into project conventions, styles, and framework
6. Validate against Figma for 1:1 look and behavior before marking complete

### Implementation rules
- Treat Figma MCP output as a representation of design/behavior, NOT as final code style
- Replace Tailwind utilities with project's preferred utilities/design-system tokens
- Reuse existing components (buttons, inputs, typography, icon wrappers) — no duplicates
- Use project's color system, typography scale, and spacing tokens consistently
- Respect existing routing, state management, and data-fetch patterns
- Strive for 1:1 visual parity; when conflicts arise → prefer design-system tokens
- Validate final UI against Figma screenshot for both look and behavior
```

## Assets Rules (Claude Code CLAUDE.md)

```markdown
# MCP Servers
## Figma MCP server rules
- The Figma MCP server provides an assets endpoint which can serve image and SVG assets
- IMPORTANT: If the Figma MCP server returns a localhost source for an image or an SVG, use that source directly
- IMPORTANT: DO NOT import/add new icon packages — all assets should be in the Figma payload
- IMPORTANT: do NOT use or create placeholders if a localhost source is provided
```

## Prompt: Generate Your Own Rules

Run this against your codebase to auto-generate a tailored rules doc:

```markdown
Please analyze this codebase thoroughly and provide a comprehensive rules doc (e.g. CLAUDE.md) 
on the following aspects to help integrate Figma designs using MCP:

1. Token Definitions — where defined, format, transformation systems
2. Component Library — where components live, architecture, storybook
3. Frameworks & Libraries — UI framework, styling, build system
4. Asset Management — storage, CDN, optimization
5. Icon System — storage, import pattern, naming convention
6. Styling Approach — CSS methodology, global styles, responsive patterns
7. Project Structure — overall org, feature patterns

Provide analysis as structured markdown with code snippets and file paths.
```

## Key Takeaways

- Write rules once in CLAUDE.md → all agents and teammates follow them automatically
- The required Figma MCP flow is: `get_design_context` → `get_screenshot` → implement → validate
- Never hardcode values — always pull from design tokens
- Always reuse existing project components, never duplicate functionality
- Figma MCP serves assets via localhost URLs — use them directly, skip icon packages
- Use the codebase-analysis prompt to auto-generate project-specific rules

## Related

- [[wiki/claude-code/dot-claude-folder|dot-claude-folder]] — full .claude folder reference including CLAUDE.md structure
- [[wiki/claude-code/mcp-integration|mcp-integration]] — MCP setup, transports, scopes
- [[wiki/claude-code/skills|skills]] — skills system for reusable AI workflows
- [[wiki/claude-code/overview|overview]] — Claude Code full product overview

## Sources

- [Figma Docs — Add custom rules and instructions](https://developers.figma.com/docs/figma-mcp-server/add-custom-rules/)
