docs/figma-integration.md

Using the UX Writing Skill with Figma

Connect this skill to Figma so your agent can review and improve UX copy directly from your designs. Perfect for content designers, product designers, and anyone who needs to audit or enhance UX text in Figma mockups.

What You Can Do

Once connected, you can:

Share Figma frame links with your agent and get instant UX writing feedback
Audit existing designs for accessibility, clarity, and tone
Generate improved copy that follows best practices
Review entire flows for consistency and voice
Get specific suggestions based on the four quality standards (purposeful, concise, conversational, clear)

Quick Example

Here's my login screen: [Figma link]

Review all the UX copy using the UX Writing Skill. Check for:
- Accessibility (screen reader compatibility, plain language)
- Error message clarity
- Button labels
- Tone consistency

Your agent will analyze the design, identify all text elements, and provide detailed feedback with specific improvements.

Setup: Connect Figma to Your Agent

Choose the setup guide for your agent:

Claude Code
Codex
Cursor

Setup: Claude Code

There are two ways to connect Figma to Claude Code. Choose the Remote Server option unless you have specific requirements for the Desktop Server.

Option 1: Remote Server (Recommended)

Best for: Quick setup, working from anywhere, no Figma desktop app needed

Requirements:

Claude Code installed
Figma account (Starter, Professional, Organization, or Enterprise plan)
Internet connection

Step 1: Install Figma MCP

Open your terminal

Run this command:

claude mcp add --transport http figma https://mcp.figma.com/mcp

Step 2: Restart Claude Code

Completely quit Claude Code and reopen it.

Step 3: Authenticate with Figma

In Claude Code, type: /mcp
Find the "figma-remote-mcp" server
If it shows "disconnected", press Enter on that line
A browser window will open — click "Allow access"

Step 4: Verify

Ask Claude: Do you have access to Figma?

Claude should confirm the connection and describe what it can do.

Option 2: Desktop Server

Best for: Working locally, no internet dependency once set up

Requirements:

Figma desktop app (latest version)
Claude Code installed
Dev Mode access in Figma

Step 1: Enable MCP in Figma Desktop

Open the Figma desktop app
Open any design file
Press Shift + D to switch to Dev Mode
In the right panel, scroll to the MCP server section
Click "Enable desktop MCP server"

Step 2: Connect Claude Code

claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp

Step 3: Restart Claude Code and verify with: Do you have access to Figma?

Note: The Figma desktop app must be running with Dev Mode enabled whenever you use this integration.

Setup: Codex

Requirements:

Codex CLI or IDE extension installed
Figma account
Internet connection

Step 1: Configure Codex for MCP

Open ~/.codex/config.toml and add:

[features]
rmcp_client = true

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"

Step 2: Install Codex CLI (if not already installed)

npm i -g @openai/codex

Step 3: Authenticate with Figma

codex mcp login figma

This opens a browser window for authentication. Follow the prompts to allow Codex to access your Figma account.

Step 4: Restart your IDE

If using Codex in an IDE, completely restart it to activate the MCP connection.

Step 5: Verify

Paste a Figma Dev Mode section link into Codex and ask it to review the UX copy. Codex should access the frame and respond with feedback.

Setup: Cursor

Requirements:

Cursor installed
Figma account
Internet connection

Step 1: Add Figma MCP to Cursor

Open your Cursor MCP configuration (.cursor/mcp.json in your project, or the global config at ~/.cursor/mcp.json) and add:

{
  "mcpServers": {
    "figma": {
      "url": "https://mcp.figma.com/mcp",
      "transport": "http"
    }
  }
}

Step 2: Restart Cursor

Completely quit and reopen Cursor.

Step 3: Authenticate with Figma

Open the MCP panel in Cursor settings, find the Figma server, and follow the authentication prompts to connect your Figma account.

Step 4: Verify

Ask Cursor: Do you have access to Figma?

Cursor should confirm the connection.

How to Use

Step 1: Get the link

Open your design in Figma
Select the frame you want to review
Right-click and select "Copy link" (or copy the URL from your browser)
- For Codex, use the Dev Mode section link (Shift + D, then copy the section link)

Step 2: Share with your agent

Review the UX copy in this login screen:
https://www.figma.com/file/abc123/Design?node-id=123-456

Focus on:
- Button labels
- Error messages
- Form field labels

Step 3: Get feedback

Your agent will access the frame, extract all text elements, apply the UX Writing Skill, and provide specific, actionable feedback.

Review an Entire Flow

Review all UX copy in this onboarding flow:
https://www.figma.com/file/abc123/Onboarding-Flow

Check for:
- Tone consistency across all screens
- Reading level (target 7th-8th grade)
- Accessibility (screen reader compatibility)
- Button label clarity

Get Rewritten Copy

Here's my error state: [Figma link]

Rewrite all the copy following UX writing best practices:
- Make it more concise
- Add specific recovery steps
- Ensure screen reader accessibility
- Use empathetic tone

Example Workflows

1. Design Review (Quick Audit)

I need to review copy in this checkout flow before launch:
[Figma link to checkout screens]

Using the UX Writing Skill, audit for:
- Accessibility issues
- Sentence length (should be under 20 words)
- Button labels (should be specific, not generic)
- Error message clarity
- Consistency across screens

Provide a prioritized list of issues.

2. Voice and Tone Check

Review the tone in these empty states:
[Figma link]

Our voice is: helpful, friendly, professional
Check if the copy matches this voice and suggest improvements.
Use the tone adaptation framework from the UX Writing Skill.

3. Accessibility Audit

Audit this form for accessibility:
[Figma link to form]

Using accessibility guidelines from the UX Writing Skill, check:
- Screen reader compatibility
- Form labels (visible, not just placeholders)
- Error messages (descriptive, actionable)
- Plain language (7th-8th grade reading level)
- Link text (descriptive, not "click here")

4. Before/After Improvements

Here's my current error screen: [Figma link]

Using the UX Writing Skill:
1. Score the current copy against the 4 quality standards
2. Identify specific problems
3. Provide a rewritten version
4. Explain what changed and why

5. Cross-Platform Consistency

Compare copy across these three platforms:
- Web: [Figma link 1]
- iOS: [Figma link 2]
- Android: [Figma link 3]

Check for:
- Terminology consistency
- Tone consistency
- Platform-specific conventions (e.g., "tap" vs "click")
- Character count appropriateness for each platform

6. Complete UX Audit Workflow

I'm reviewing our checkout flow before launch. Here are the 4 key frames:

1. Cart: [Figma link]
2. Shipping: [Figma link]
3. Payment: [Figma link]
4. Confirmation: [Figma link]

Using the UX Writing Skill, perform a complete audit:

Check for:
- All 4 quality standards (purposeful, concise, conversational, clear)
- Accessibility (screen readers, reading level, plain language)
- Error messages (empathetic, actionable, specific)
- Form labels (visible, descriptive, not placeholder-only)
- Button labels (specific verbs, not generic)
- Voice consistency across all screens
- Appropriate tone for context

Provide:
1. Overall score (1–10) with explanation
2. Critical issues (must fix before launch)
3. Recommended improvements (nice to have)
4. Rewritten copy for any critical issues
5. Summary of patterns used well

Format as a design review report.

Tips for Best Results

Be Specific About What You Want

❌ Too vague:

"Review this design: [link]"

✅ Better:

"Review the error messages in this form: [link]. Check for accessibility, clarity, and actionable guidance."

Reference Multiple Frames for Context

Review this 3-step onboarding flow:
1. Welcome screen: [link]
2. Account setup: [link]
3. Preferences: [link]

Check for consistent voice and progressive disclosure of information.

Ask for Specific Frameworks

Use the tone adaptation framework to suggest appropriate tone for this error state: [link]

Score this against the content usability checklist: [link]

Explicitly Mention the Skill

For best results, explicitly mention the UX Writing Skill in your prompts — especially in Codex and Cursor:

Using the UX Writing Skill, review this design: [link]

In Codex, you can also invoke it directly:

$ux-writing Review the UX copy in this design: [Figma link]

Or use the /skills command to select it from the list.

In Cursor, reference it in your prompt:

@ux-writing Review the copy in this design: [Figma link]

Troubleshooting

"I don't have access to that Figma file"

Make sure the file is set to "Anyone with the link can view"
Check that you're signed into the same Figma account you authenticated with
Try copying the link again — it may have been truncated or expired
For Codex, make sure you're using a Dev Mode section link, not just the file URL

MCP server is disconnected

Claude Code:

Type /mcp in Claude Code
Find the Figma server and press Enter to reconnect
Re-authenticate if prompted

Codex:

Verify ~/.codex/config.toml has the correct configuration
Re-run codex mcp login figma
Restart your IDE completely

Cursor:

Open Cursor settings and check the MCP panel
Reconnect or re-authenticate the Figma server
Restart Cursor if needed

"I can't see the MCP server section in Figma"

This applies to the Claude Code Desktop Server option only:

Update to the latest Figma desktop app version
Make sure you're in Dev Mode (Shift + D)
Check that your Figma plan includes Dev Mode access

The skill doesn't seem to activate

Explicitly mention it in your prompt:

Using the UX Writing Skill, review this design: [link]

Or ask your agent to apply specific frameworks:

Apply the four quality standards (purposeful, concise, conversational, clear) to this copy: [link]

Advanced Usage

Create Documentation from Designs

Review all copy in this feature: [link]

Create a content patterns document showing:
- Common patterns we use (buttons, errors, empty states)
- Voice characteristics
- Terminology conventions
- Do/don't examples

Format it as a content style guide section.

Build a Voice Chart from Existing Designs

Analyze the copy in these designs: [multiple Figma links]

Using the voice chart template from the UX Writing Skill, create a voice chart showing:
- 3–5 key brand concepts
- Voice characteristics for each
- Do/Don't examples from our actual product
- Tone variations for different contexts

Generate Test Copy

I need placeholder copy for this wireframe: [link]

Generate realistic UX copy for all text elements following our voice:
- Helpful, professional, encouraging
- Target reading level: 8th grade
- Keep button labels under 25 characters

Localization Prep

Review this design for translation readiness: [link]

Check:
- Text expansion space (German expands 30–40%)
- Idioms or cultural references to avoid
- Hard-coded text in buttons that should be dynamic
- Character limits that might break in other languages

Automated Copy Testing

Every week, I'll share new designs with you. For each design:
1. Extract all copy
2. Run it through the content usability checklist
3. Flag anything scoring below 7/10
4. Provide specific fixes
5. Track improvements over time

Resources

Figma MCP Documentation: developers.figma.com/docs/figma-mcp-server
UX Writing Skill: See the main README.md for installation and overview

Feedback

Have ideas for improving this integration? Open an issue or contribute to the repository. We'd especially love to hear:

Real-world workflows that work well for your team
Examples of great UX writing improvements from Figma designs
Tips for content design teams using this integration

On this page