How to Use Matchkit with Claude Code: Step-by-Step Setup

Matchkit + Claude Code is the tightest integration for design systems in AI coding. Claude Code reads Matchkit directly through MCP, so your design system is always available to Claude without manual context passing.

This guide walks you through the setup in 90 seconds, then shows you a real example.

Prerequisites

You'll need:

• Claude Code installed (terminal, VS Code, or Cursor). Get it from https://code.claude.com/docs/en/getting-started
• A project directory (doesn't need to exist yet; Matchkit can scaffold one)
• Node.js 18+ (for running the Matchkit CLI)
• A Matchkit Pro account (€9/mo) for CLI sync. The free tier is a static ZIP download.

If you're on the Matchkit free tier, you can still follow this guide. You'll download a ZIP instead of using the CLI, and the file structure will be the same.

Step 1: Configure Your Style

Go to https://matchkit.io/configure.

You'll see four presets: Clarity (sharp, structured), Soft (rounded, warm), Glass (translucent, modern), and Brutal (bold, angular).

Pick the closest match to your vibe. For this example, let's say you're building a project management tool, so you pick Clarity.

Now you'll see 11 sliders:

• Radius: Currently at sharp, move it slightly right for soft corners
• Button-style: Keep it solid
• Element-separation: Move it to add breathing room
• Spacing-density: Adjust based on how packed you want your UI
• Shadow-style: Pick soft or hard
• Color-temp: Warm or cool
• Color-saturation: Muted or vibrant
• Font-personality: Geometric or serif
• Font-weight-bias: Light or bold
• Motion-speed: Slow or fast
• Border-weight: Thin or thick

Adjust each slider until the preview looks right. You don't need to overthink it. The point is to create a starting point that's intentional.

Once you're happy, click "Download" if you're on the free tier, or "Connect to Project" if you're on Pro.

Step 2: Install via MCP

If you're on Pro, Matchkit gives you a command:

matchkit install-mcp

Run this in your project root:

cd your-project
matchkit install-mcp

Matchkit will:

1. Create the directory structure (src/components/ui/, src/globals.css, .claude/)
2. Generate your design tokens in globals.css based on your configuration
3. Create pre-styled React components (Button, Card, Input, Checkbox, etc.) in src/components/ui/
4. Write the .claude/SKILL.md file with your design constraints
5. Scaffold a package.json with React and Tailwind v4

This takes about 15 seconds.

Then, Claude Code will prompt: "Allow Matchkit MCP to access your project?" Click "Allow."

Claude Code now has live access to your Matchkit design system. When Claude generates UI, it can query your components and tokens directly.

If you're on the free tier, download the ZIP from the configurator and extract it into your project root. The file structure is identical; you're just not syncing live updates.

Step 3: Build Something

Now ask Claude Code to build something. Here's a real prompt:

Build a dashboard page with:
- Header with title and user avatar
- Sidebar with navigation links (Dashboard, Projects, Settings)
- Main content area with a stats card showing active projects
- Use the design system. No hardcoded colors.

Claude Code will read your SKILL.md file (through MCP if you're on Pro), see your component library, and generate a page that uses your Button, Card, Input, and other components. The colors will come from your tokens in globals.css.

The output will look something like this:

"use client"

import { Card } from "@/components/ui/card"
import { Button } from "@/components/ui/button"

export default function DashboardPage() {
  return (
    <div className="min-h-screen bg-background">
      <header className="border-b border-border px-6 py-4">
        <h1 className="text-2xl font-bold text-foreground">Dashboard</h1>
      </header>

      <div className="flex">
        <aside className="w-64 border-r border-border p-6">
          <nav className="space-y-2">
            <Button variant="ghost" className="w-full justify-start">Dashboard</Button>
            <Button variant="ghost" className="w-full justify-start">Projects</Button>
            <Button variant="ghost" className="w-full justify-start">Settings</Button>
          </nav>
        </aside>

        <main className="flex-1 p-6">
          <Card className="p-6">
            <h2 className="text-lg font-semibold text-foreground">Active Projects</h2>
            <p className="text-sm text-muted-foreground">12 projects in progress</p>
          </Card>
        </main>
      </div>
    </div>
  )
}

Notice: Claude imported from @/components/ui/, used your Button and Card components, and referenced token classes like text-foreground, bg-background, border-border. This is your design system working.

If you ask Claude to build another page (say, a settings page), it'll use the same components and tokens. Your whole app stays visually consistent.

Step 4: Customize and Iterate

Your design system isn't locked in. You can change it anytime.

Go back to the Matchkit configurator and adjust the sliders. Rerun:

matchkit install-mcp --update

Or download a new ZIP if you're on the free tier. Claude Code will pick up the updated globals.css and component definitions on your next prompt.

You can also edit the components directly. Open src/components/ui/button.tsx and tweak the styling. Claude Code will use your modified version.

Or edit SKILL.md to add custom rules. For example, add:

- Always use spacing from the spacing scale (xs, sm, md, lg, xl). No custom padding.
- Buttons should never exceed lg size unless explicitly requested.

Claude Code will respect these additions on the next prompt.

Troubleshooting Common Issues

MCP Not Connecting

If Claude Code doesn't ask for MCP permission, check:

1. Did you run matchkit install-mcp in the correct project?
2. Is your Matchkit account Pro tier? (Free tier is ZIP-only.)
3. Restart Claude Code. Sometimes it needs a moment to detect the new MCP server.

If it still doesn't connect, manually add the MCP configuration to .claude/claude.json:

{
  "mcpServers": {
    "matchkit": {
      "command": "matchkit",
      "args": ["mcp"]
    }
  }
}

Then restart Claude Code.

SKILL.md Not Loading

If Claude Code generates UI but ignores your design system, the SKILL.md file might be in the wrong place or malformed.

Check:

1. File is at .claude/SKILL.md (not .clauderc or other names)
2. The YAML frontmatter is valid. Run yaml .claude/SKILL.md to validate.
3. The triggers in the frontmatter are correct. If you wrote triggers: ["prompt contains: button"], Claude Code will only load the skill when you mention "button". Change it to triggers: [] to always load.

Components Not Importing

If Claude Code generates a page but tries to import from src/components/ instead of @/components/ui/, check:

1. Your tsconfig.json has the path alias configured:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

2. Your SKILL.md explicitly states the import path. Add a line like "Always import components from @/components/ui/, never from src/."

3. You've actually run npm install or yarn install so Node knows the package structure.

If components still aren't importing, ask Claude Code: "Show me your last import statements." Claude will display the imports from the previous generation, and you can see where it's looking.

Frequently Asked Questions

How long does the Matchkit Claude Code setup take?

About 90 seconds for the core setup: 60 seconds configuring your visual preferences in the Matchkit configurator, 15 seconds running the MCP install command, and 15 seconds verifying the installation. After that, every prompt Claude processes uses your design system automatically. No per-page configuration needed. You just ask Claude to build, and it uses your tokens and components.

Does Matchkit work with Claude Code in VS Code and Cursor?

Yes. Claude Code runs identically in the terminal, VS Code, and Cursor. The MCP installation is the same across all environments. The SKILL.md file and components are placed in your project directory, which Claude Code reads regardless of which editor hosts it. If you use Cursor's own AI (not Claude Code), see the Cursor-specific setup guide instead.

Is the Matchkit free tier sufficient for a real project?

The free tier gives you all themes and all components as a static ZIP download. That's a complete design system for any visual style. You can build a production app with it. The limitation: no sync. If you update your design choices in the Matchkit configurator, you re-download and extract the ZIP again. Pro (€9/mo) adds CLI sync so your AI agent pulls updates automatically, plus URL extraction for matching existing sites and logo upload for brand color extraction. Most teams prefer Pro for the workflow friction reduction.

Can I use a different component library (like shadcn/ui or Material-UI) instead of Matchkit components?

Yes. Matchkit generates components, but you can replace them with any library. Just update your SKILL.md to reference your library's import paths. Instead of "import Button from @/components/ui/button", tell Claude Code to "import Button from @shadcn/ui". The design system is the rules, not the components. You can layer Matchkit's design constraints on top of any component library.

What if I want to use Tailwind config instead of CSS variables?

You can. Matchkit generates both. Edit your tailwind.config.ts to reference the CSS variables from globals.css:

export default {
  theme: {
    extend: {
      colors: {
        primary: "var(--color-primary)",
        secondary: "var(--color-secondary)",
      },
    },
  },
}

Then tell Claude Code to use Tailwind classes instead of CSS variables. Both approaches work.

What's the difference between free and Pro tiers?

Free tier: all themes, all components, all design axes. Static ZIP download. You re-download when you want updates. Great for proofs of concept and side projects. Pro tier (€9/mo): same everything, plus CLI sync (your AI agent automatically pulls updates), URL extraction (paste your existing site's URL, Matchkit scans it and builds a matching design system), and logo upload (Matchkit extracts brand colors from your logo). Team tier (€29/mo) adds 5 seats and shared organization configs. Most teams upgrade to Pro after the first project because the sync workflow removes friction.

How does Matchkit's URL extraction work?

Upload your website's URL in the Matchkit configurator (Pro tier). Matchkit runs a headless browser, scans your site's computed styles (colors, border-radius, fonts, spacing, shadows), and maps them to design system axes. It generates a matching design system in under 2 minutes. This is useful if you have an existing website and want your new AI-coded project to match its visual style. The extraction is accurate for colors and spacing, moderately accurate for typography, and you can always tweak the values after extraction.