SMA Design System MCP Guide

Getting Started

New to this workflow? Do these five steps once, then reuse the Prompt Library for every screen after.

5 steps

Copy the design system link — you don't need to open the file. Paste the published ⚡SMA Design System URL into your agent once. It's the source of truth for every component, token, and text style, and your agent can read it directly from the link.

https://www.figma.com/design/6nZOWSVAFMs75dMSW8k5P1/%E2%9A%A1SMA-Design-System?node-id=42-467&t=MGw1ssi90jFYpZ2e-1

Connect Figma MCP. Pick your tool in the Setup section (Claude, Cursor, Codex, or a raw Figma MCP endpoint) and confirm it's connected before you ask for code.

Run the Global Setup Prompt once. Paste it into a fresh agent session — it hands the agent the design system link and every rule it needs. The agent remembers this for the rest of the session, so you never paste it again mid-project.

Then just copy a frame link. In your agent, you can now copy any frame, screen, or component link straight from 🔵SMA Client File and drop it into the short per-screen prompt — no need to keep the file open or repeat the rules.

Compare, reconnect, optimize. Run the QA prompt against Figma, the token-reconnect prompt to catch anything hardcoded, then the optimize prompt before you ship.

🎯

Pixel-accurate

Every spacing, color, radius, and state matches the Figma frame — not an approximation of it.

🔗

Linked to the design system

Values are bound to real tokens and components instead of hardcoded copies, so a token update in Figma updates the code too.

🧹

Clean to maintain

No duplicate components, no dead code, and no one-off styles left behind after export — production-ready from the first pass.

File Rules

These are the rules agents should follow before reading, writing, or exporting UI.

Important

Use the published system first

Import existing SMA components, variables, icons, and text styles before creating anything new.

Use exact frame links

For code export, link the selected screen frame from the Client File's Design page.

Ignore archive by default

Archived and unused components should not be used for new builds unless you explicitly request them.

MCP Setup

Remote Figma MCP is the best default. Desktop MCP is useful when a client needs local Figma desktop context or selected nodes.

Claude Code preferred install

claude plugin install figma@claude-plugins-official

Restart Claude Code after install.

Run /mcp, choose Figma, authenticate, and confirm the server is connected.

Paste the exact SMA Client File frame link and ask Claude to reuse the published SMA Design System.

If Claude flags a structure as unusual, ask it to check the Design Notes section before treating it as a bug.

Cursor preferred install

/add-plugin figma

Manual desktop fallback:

{
  "mcpServers": {
    "figma-desktop": {
      "url": "http://127.0.0.1:3845/mcp"
    }
  }
}

Codex CLI remote MCP

codex mcp add figma --url https://mcp.figma.com/mcp
codex mcp login figma
codex mcp list

Codex config lives in ~/.codex/config.toml. Project-only config can live in .codex/config.toml for trusted projects.

Figma MCP endpoints

Remote MCP

https://mcp.figma.com/mcp

Preferred for most clients and broadest workflow support.

Desktop MCP

http://127.0.0.1:3845/mcp

Use when the Figma desktop app and local selection context are required.

Prompt Library

Run the Global Setup Prompt once per agent session — your agent remembers the rules. After that, just paste a new frame link using the short per-screen prompt for your tool.

Do I need to paste this every time?

No. The Global Setup Prompt below only needs to run once — at the start of a new agent session or project. Your agent keeps the design system link and every rule in memory for the rest of that conversation. For every screen after that, copy the short "per-screen" prompt for your tool and just drop in a new frame link.

Global Setup Prompt — run this once Paste first in a new agent session. Works for Claude, Cursor, or Codex.

Run once

This is a one-time setup for this project. Remember these rules for every screen I ask you to build in this session — I won't repeat them.

Design system (source of truth for components, tokens, icons, and text styles):
https://www.figma.com/design/6nZOWSVAFMs75dMSW8k5P1/%E2%9A%A1SMA-Design-System?node-id=42-467&t=MGw1ssi90jFYpZ2e-1

Screens and components live in the SMA Client File. I'll paste individual frame, screen, or component links from its `Design` page for each request — you don't need to open the whole file.

Rules for every export, every time:
1. Reuse existing production components before creating new ones. Never build a parallel component library.
2. Connect every value to its matching design-system variable instead of hardcoding it — color to the matching color variable, spacing to the matching space variable (e.g. 16px → space/16), radius to the matching radius variable (e.g. 16px → radius/16), and typography to the matching text style. Do this for every variant property, not just the default state.
3. If a component looks detached from its main component but its inner elements are still linked instances, treat it as an intentional flexibility pattern — check the Design Notes / Guides page before "fixing" it.
4. Ignore the Archive page entirely unless I explicitly ask for something from it.
5. After implementing, run the app and compare the result against the Figma frame: spacing, typography, color, radius, and every interactive state.
6. Keep the codebase clean — no duplicate components, no dead code, no unused styles. Every export should read like it was written by someone who owns this codebase long-term.
7. If anything doesn't map cleanly to the design system, tell me instead of guessing.

Confirm you've understood these rules, then wait for my first frame link.

Claude — per-screen build Use after the Global Setup Prompt

Every screen

Already ran the Global Setup Prompt in this session? Just paste this for each new screen — no need to repeat the rules.

Implement this frame:
<PASTE SMA CLIENT FILE DESIGN FRAME LINK>

Follow the rules from setup: reuse components, connect every value to its matching token, treat intentional flexibility patterns correctly, ignore Archive, and verify against the Figma frame before you're done. List anything you couldn't map exactly.

New session and skipped setup? Run the Global Setup Prompt above first.

Claude — optimize after export Run once the screen matches Figma

Review the code you just exported for this screen and optimize it without changing anything visual.

Check for:
- component reuse — merge near-duplicate components instead of leaving copies
- dead code — unused props, styles, imports, and CSS classes
- consistent token usage instead of hardcoded colors, spacing, or radius values
- accessible markup — landmarks, labels, alt text, and a sensible focus order
- performance — avoid unnecessary re-renders and lazy-load heavy assets
- responsive correctness at desktop, tablet, and mobile widths

Do not change the visual output. List every optimization you made and why.

Reconnect disconnected tokens Run before shipping any variant

Audit this component/frame export for values that got disconnected from the design system instead of bound to a variable or style.

For every value you find, check the SMA Design System variables first, then reconnect it — don't leave it hardcoded:
- Color: if a fill/stroke is a raw hex, find the matching color variable (e.g. bg/accent-500) and bind it.
- Spacing: if a gap/padding is a raw number, check for a matching space variable — e.g. a hardcoded 16px gap should connect to the space/16 variable if it's available.
- Radius: if a corner radius is a raw number, check for a matching radius variable — e.g. a hardcoded 16px radius should connect to the radius/16 variable if it's available.
- Typography: if font-size, weight, or line-height are set manually, bind the matching text style instead.
- States: if hover, focus, disabled, error, or selected is faked with an inline color or opacity tweak, map it to that state's real variant/token instead.

Do this for every variant property, not just the default state. Return two lists: every value you reconnected, and every value that had no matching variable so I know to add one.

Cursor — per-screen build Use after the Global Setup Prompt

Every screen

Already ran the Global Setup Prompt in this session? Just paste this for each new screen.

Use Figma MCP and implement this frame:
<PASTE SMA CLIENT FILE DESIGN FRAME LINK>

Reuse existing components, connect every value to its matching design token, and verify responsively at desktop and mobile widths.

New session and skipped setup? Run the Global Setup Prompt above first.

Codex — per-screen build Use after the Global Setup Prompt

Every screen

Already ran the Global Setup Prompt in this session? Just paste this for each new screen.

Use Figma MCP to inspect this SMA Client File frame:
<PASTE FRAME LINK FROM DESIGN PAGE>

Implement it in this repo. Keep changes scoped, reuse existing components and token files, and verify with screenshots at 1440px, 768px, and 390px widths.

New session and skipped setup? Run the Global Setup Prompt above first.

Figma to code QA Use after implementation

Compare the current implementation against this Figma frame:
<PASTE SMA CLIENT FILE DESIGN FRAME LINK>

Check:
- spacing and alignment
- typography size, weight, and line-height
- colors and token usage
- radius and elevation
- icons and imagery
- hover, focus, disabled, loading, and error states
- mobile and desktop layout

Before flagging a difference as a bug, check this guide's Design Notes / Guides Page section for a documented design-intent note. Return only actionable, genuine differences with file/line references and suggested fixes.

Check intent before "fixing" Use when a structure looks inconsistent

Before flagging anything in this Figma frame as an inconsistency or bug:
<PASTE FRAME LINK>

1. Check whether the component is detached from its main component but its inner elements are still linked instances with tokens bound.
2. Check the Design Notes / Guides Page of the SMA Client File for a matching note.
3. If a note exists, treat the structure as intentional and implement it exactly as designed — do not reattach, realign, or simplify it.
4. Only report it as a genuine issue if no design-intent note exists and the inner elements are also broken or hardcoded.

Add guide notes to Figma For the Client File Guides page

Use Figma MCP to add/update a guide section on the `Guides` page of the SMA Client File.

Document:
- source design-system file
- `Design` page usage for screens
- `Guides` page usage for handoff notes
- `Archive` page usage for deleted/unused components
- exact prompt templates for Claude, Cursor, and Codex, including the Global Setup Prompt
- design-intent notes for any component that is intentionally detached or structured non-standardly, and why (for example, a card that needs per-item badge or label placement, an auto-layout element that was never componentized, or a one-off color used outside the token set)
- rules for ignoring Archive by default

Use clean auto-layout, readable headings, and reusable SMA typography styles.

MCP health check Confirm tools before coding

Before starting, verify Figma MCP is connected.

Check:
- Can you read the published SMA Design System?
- Can you read this SMA Client File frame?
- Can you list variables, text styles, and component variants?
- Can you identify whether the selected node is from `Design`, `Guides`, or `Archive`?

If MCP is not connected, stop and tell me exactly which setup step is missing.

Design Notes / Guides Page

Some structures look inconsistent at a glance. This section mirrors the `Guides` page in the SMA Client File and documents why they're built that way, so agents and reviewers implement them as designed instead of "fixing" them.

Read before flagging issues

Discover Staff cards

Intentional

What it looks like: the outer card is detached from its main component, while every inner piece — photo, name, role, and badge — is still a live component instance bound to tokens.

Why: each staff type needs its selected/highlighted label in a different spot depending on the name and role length. A featured card shows the badge top-right; a standard card shows it inline next to the name. One locked main component can't hold two different label positions at once, so the outer frame is detached to allow per-card placement, while the inner content stays connected to the system.

Agent instruction: keep this as a layout variant. Reuse this pattern only for cards that genuinely need per-item label placement — do not reattach the outer frame to the main component or force a single fixed layout.

Any card with content-driven badge or tag placement

Intentional

What it looks like: a detached wrapper frame around otherwise normal, still-linked component instances.

Why: the badge, tag, or price position shifts based on the length or type of content inside the card. Detaching the wrapper is what allows each card independent placement while every inner element stays mapped to the design system.

Agent instruction: treat spacing or position differences between these cards as content-driven, not accidental drift. Build a flexible layout in code (conditional positioning, not fixed coordinates) rather than one rigid layout copied from a single card.

Auto-layout-only elements (not componentized)

Intentional

What it looks like: a plain auto-layout frame with no variants, not registered as a reusable component in the library.

Why: this element is only used in one or two places across the product. Turning every single-use layout into a full component with variants adds maintenance overhead without real reuse benefit, so it's intentionally left as a plain auto-layout frame instead of a master component.

Agent instruction: implement it as a simple, local UI block rather than a shared component, unless I ask you to promote it into the design system. If you start seeing this exact layout reused in more places, flag it — that's a sign it should become a real component.

One-off colors outside the token set

Intentional

What it looks like: a fill or stroke uses a raw color value that isn't bound to any SMA color variable.

Why: the color is used in a very small number of places — sometimes just once, like a rare accent or illustration exception. Adding a permanent token for a color used once would bloat the token set, so it was intentionally left unbound.

Agent instruction: use the exact raw value from Figma for this instance. Don't invent a new token for it and don't substitute the nearest existing token color — flag it to me if you see the same color reused elsewhere, since that would mean it should become a real token.

How to tell "intentional" from "actually a mistake"

✅

Inner instances are still linked to design-system components — not fully detached.

✅

Colors, spacing, and radius still resolve to bound variables, not hardcoded values — unless it's a documented one-off exception like the ones above.

✅

A note exists here (Design Notes / Guides Page) explaining the reason for the structure.

✅

It's used in very few places — a rare, deliberate exception, not a spreading pattern. The same "exception" showing up across many components is a sign it should become a real token or component instead.

⚠️

If none of the above are true, don't assume intent — flag it as an unresolved issue and route it back to design for review.

MCP Readiness Checklist

Tick these before asking an agent to export final UI code.

0% complete

Published SMA Design System is linked in the prompt. Exact frame link from the Client File `Design` page is provided. Archive page is excluded unless explicitly requested. Variables use scoped color, spacing, and radius bindings. Major components have semantic variant names. Typography styles have explicit line-height values. Design Notes / Guides page checked before treating an unusual structure as a mistake. Code implementation is checked at desktop, tablet, and mobile widths.

Sources and setup notes

Figma recommends the remote MCP server for most users and provides a desktop MCP option for local Figma desktop workflows.

Figma remote endpoint: https://mcp.figma.com/mcp. Desktop endpoint: http://127.0.0.1:3845/mcp.

Official docs: Figma remote MCP, Figma desktop MCP, Codex MCP, Cursor MCP.