Every team using Claude Code to generate UI runs into the same wall: the output works, but it doesn't match the product. Colors are close but wrong. Spacing is arbitrary. Components don't use your primitives. You spend the next thirty minutes fixing code that was supposed to save you time.
The underlying problem is that Claude Code has no access to your design system. It invents values from training data, producing code that is plausible but off-system. FramingUI's MCP server solves this by giving Claude direct, structured access to your tokens and components at generation time.
What You're Setting Up
By the end of this guide, Claude Code will query your design system before generating any UI. Instead of bg-blue-500, you get var(--bg-primary). Instead of p-6, your actual spacing scale. Token access is automatic — no manual pasting, no stale guidelines.
Step 1: Initialize FramingUI in Your Project
Run the init command from your project root:
npx -y @framingui/mcp-server@latest init
This single command does most of the work:
- Installs
@framingui/uiandtailwindcss-animate - Adds
@import '@framingui/ui/styles'to your global stylesheet - Mounts
FramingUIProviderin your app root - Creates a local
framingui-thememodule - Writes the MCP server entry to
.mcp.json - Generates
FRAMINGUI-GUIDE.mdand updatesCLAUDE.md
If you already have some of these set up, init is safe to re-run — it updates existing entries rather than duplicating them.
Step 2: Verify the MCP Configuration
After init, check that .mcp.json in your project root contains:
{
"mcpServers": {
"framingui": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@framingui/mcp-server@latest"]
}
}
}
The key is "framingui", not "tekton". The "-y" flag prevents interactive prompts during npx execution. Both are required for reliable Claude Code integration.
Step 3: Authenticate
The MCP server requires authentication to access licensed themes:
framingui-mcp login
This opens a browser prompt. Credentials are stored in ~/.framingui/credentials.json. Alternatively, set FRAMINGUI_API_KEY as an environment variable if you're working in a CI or shared environment.
Step 4: Restart Claude Code and Test
Restart Claude Code so it picks up the new .mcp.json. Then verify the connection with a direct question:
What design tokens are available in this project?
Claude should respond with your token list from the MCP server. If it can't, confirm the .mcp.json path and that init completed without errors.
Step 5: Generate UI with Design System Context
With the MCP server connected, prompt Claude Code with explicit constraints:
Build a pricing card component.
Use semantic tokens only. Do not invent new color values.
Include hover and focus states.
Claude will query the MCP server for available tokens and generate code that uses your actual design system. The difference is immediate.
Without MCP
<div className="bg-blue-600 p-4 rounded-lg">
<h3 className="text-white text-xl font-bold">Pro Plan</h3>
<p className="text-gray-200">$29/month</p>
</div>
With MCP
<div className="bg-[var(--bg-primary)] p-[var(--spacing-4)] rounded-[var(--radius-md)]">
<h3 className="text-[var(--text-primary-foreground)] text-heading-sm font-semibold">Pro Plan</h3>
<p className="text-[var(--text-primary-foreground)]/80">$29/month</p>
</div>
The second version uses tokens from your actual design system. No manual fixes needed.
Prompting for Better Results
Token access is necessary but not sufficient. The quality of generated code also depends on how you prompt. Constrained prompts consistently produce better output than open-ended ones.
Effective pattern:
Build a settings form with email and password fields.
Use existing form primitives from @framingui/ui.
Use semantic tokens only.
Include validation error states.
The more constraints you provide, the more Claude Code leverages MCP context rather than falling back on training data patterns.
Troubleshooting
"MCP server not found" — Confirm .mcp.json exists in the project root and has the correct "framingui" key. Restart Claude Code after any config changes.
"No tokens available" — Verify that init completed successfully. Check that @framingui/ui/styles is imported in your global stylesheet and FramingUIProvider is mounted in the app root.
"Claude ignores tokens" — Be explicit in prompts: "Use semantic tokens only. Do not invent new color values." Then ask Claude to list available tokens to confirm the MCP connection is active.
Migrating Existing Code
Once connected, you can use Claude Code to clean up previously generated components:
Review src/components/ui/ and replace any hardcoded color or spacing values with semantic tokens from the FramingUI design system.
This works well as a one-time migration pass before switching to token-first generation going forward.
The five minutes it takes to run init and configure the MCP server pays back on the first component you no longer have to fix by hand.