Documentation

Complete guide to MatchKit design system skills. Installation, components, themes, tokens, and the self-expanding architecture.

Getting Started

MatchKit is an AI-powered design system skill generator. It works with Cursor, VS Code, Claude Code, and Windsurf — any MCP-compatible editor. It generates a complete, production-ready component library pre-configured to your brand aesthetic — 27 components, 6 layouts, design tokens, and a self-expanding rulebook.

Install a skill, prompt your AI editor, and get interfaces that look like they were built by a professional design team. No component gaps. No visual drift across sessions.

How it works

Configure — Pick a theme, choose your accent color, tune the style axes at matchkit.io/configure
Download — Purchase and download your personalized skill package (ZIP)
Install — Unzip into .claude/skills/ in your project
Prompt — Ask your AI editor to build your UI. It reads the skill and generates on-brand code.

Quick start

# Unzip your downloaded skill
unzip matchkit-clarity.zip

# Prompt your AI editor
"Build me a dashboard with sidebar nav, 4 KPI cards, a chart, and a data table"

Skills Overview

Every MatchKit skill uses a three-layer architecture designed for AI consumption:

SKILL.md = Rulebook — design philosophy, rules, component specs, self-expansion instructions
registry.json = Dictionary — what components exist and where to find them
.tsx files = Implementation reference — pinned code the AI reads when building

What's in the package

Skill package structure

your-skill/
├── SKILL.md              Rulebook (design philosophy, rules, specs)
├── registry.json         Component registry (27 components, 6 layouts)
├── manifest.json         Build manifest (ID, version, profile)
├── globals.css           CSS custom properties (light + dark mode)
├── components/           27 .tsx files (copy-paste ready)
├── layouts/              6 .tsx layout implementations
├── tokens/               6 .json token files
├── patterns/             5 .md cross-cutting guides
└── palettes/             4 .md palette selection guides

The 4 Themes

Four curated aesthetics, each positioned at different coordinates on MatchKit's 11-axis style system. All share the same 27 components and APIs — only the visual treatment differs.

Clarity UI

Sharp, structured B2B SaaS. Stripe/Linear quality.

Style: Medium radius, thin borders, subtle shadows, geometric fonts (Inter)
Best for: Fintech, enterprise SaaS, CRM, dev tools
Palettes: Indigo, Slate, Mono, Warm

Soft UI

Warm-minimal for AI tools and conversational products.

Style: Extra-large radius, no borders, muted accents, rounded fonts (Nunito)
Best for: AI tools, chat apps, creative platforms, consumer SaaS
Palettes: Teal, Sage, Lavender, Clay

Brutal UI

Neobrutalism. Bold, expressive, graphic.

Style: Hard-offset shadows, chunky borders, vibrant colors, bold typography
Best for: Creative agencies, portfolios, indie products
Palettes: Theme-specific vibrant accents

Glass UI

Technical, translucent, dev-grade aesthetic.

Style: Frosted glass surfaces, hairline borders, compact spacing, cool tones
Best for: Developer tools, terminal-adjacent dashboards
Palettes: Theme-specific cool accents

Installation

From matchkit.io (recommended)

Visit matchkit.io/configure and configure your theme
Purchase and download the ZIP package
Unzip into your project's .claude/skills/ directory

unzip matchkit-clarity.zip -d .claude/skills/clarity-ui/

Using a starter template

Starter templates include a pre-wired Next.js app shell with sidebar, topbar, and all design tokens configured.

# Clarity UI starter (B2B SaaS)
cp -r starters/default my-project
cd my-project && npm install && npm run dev

# Soft UI starter (AI/conversational)
cp -r starters/soft-default my-project
cd my-project && npm install && npm run dev

Prompt examples

Once installed, just prompt your AI editor naturally. The skill activates automatically.

Prompt	What you get
"Build an analytics dashboard"	KPI cards, charts, activity table, sidebar nav
"Build a user management page"	Data table with filters, list-detail view, status badges
"Build a settings page"	Multi-section form, toggles, danger zone
"Build a billing page"	Plan cards, invoice table, usage metrics
"Build a login page"	Centered auth card, social login, dark mode toggle

API Keys & CLI

MatchKit API keys authenticate the CLI and CI/CD pipelines. They're scoped to your account — one key works for all your projects. API keys are available for paid users only.

Managing API Keys

Create and manage API keys from your dashboard → API Keys. Keys remain active until you revoke them.

Visit /app/keys
Click "Create Key" and give it a name (e.g., "My laptop", "CI/CD")
Copy the key immediately — it won't be shown again
Store it securely (e.g., password manager, env vars)

Using the CLI

The MatchKit CLI lets you sync your design system from the command line. Perfect for pulling updates, adding components, and integrating with CI/CD.

Install the CLI globally

npm install -g @matchkit.io/cli

CLI Commands

Command	Description
matchkit login	Authenticate with your API key (opens browser)
matchkit init	Link a project to your MatchKit configuration
matchkit pull	Download latest resolved design system
matchkit add <component>	Install one component + dependencies
matchkit list	Show all 27 components with installed/available status
matchkit status	Show config ID, theme, version, sync status
matchkit diff	Show what changed since last pull

CLI Workflow

First-time setup

# 1. Install CLI globally
npm install -g @matchkit.io/cli

# 2. Authenticate (opens browser → signs you in → saves key)
matchkit login

# 3. Initialize your project (links to your MatchKit config)
matchkit init

# 4. Pull your design system
matchkit pull

Your design system files are installed to .claude/skills/[theme]-ui/. The CLI stores config in .matchkit/config.json and your API key in ~/.matchkit/credentials.

CI/CD Usage

For automated deployments, set the MATCHKIT_API_KEY environment variable instead of using matchkit login:

GitHub Actions example

name: Deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Pull MatchKit design system
        env:
          MATCHKIT_API_KEY: ${{ secrets.MATCHKIT_API_KEY }}
        run: |
          npm install -g @matchkit.io/cli
          matchkit pull

      - run: npm install
      - run: npm run build

API Key Scope

One key for all projects. API keys are scoped to your MatchKit account, not individual projects. You can use the same key across multiple repos and CI/CD pipelines.

Security best practices: Store keys in environment variables or secret managers. Never commit them to git. Rotate keys periodically. Use separate keys for development and CI/CD.

Components

Every skill includes 27 production-ready components. All are copy-paste ready .tsx files with full TypeScript types.

UI Primitives

Component	Description
Button	Primary, secondary, danger, ghost variants with loading state
Input	Text input with label, error, helper text, and icons
Select	Dropdown select built on Radix UI with search
Checkbox	Checkbox with label, indeterminate state
Switch	Toggle switch built on Radix UI
Status Badge	Colored badge for status indicators (success, warning, error, info)
Tabs	Tab group with panel content switching
Avatar	User avatar with fallback initials and status dot
Tooltip	Hover tooltip built on Radix UI
Progress Bar	Determinate and indeterminate progress indicator
Theme Toggle	Light/dark mode toggle with system preference detection

Data & Forms

Component	Description
Data Table	Sortable, filterable, paginated table with row selection
Stat Card	KPI card with value, label, change indicator, and optional chart
Filter Bar	Search input + filter dropdowns + active filter chips
Form Layouts	Single-column, two-column, and danger zone form patterns
Command Palette	Cmd+K search overlay with keyboard navigation

Containers

Component	Description
Modal Dialog	Overlay dialog built on Radix UI with close, confirm, cancel
Toast Notification	Non-blocking notification via Sonner with variants
Dropdown Menu	Context/action menu with keyboard nav and submenus
Page Header	Page title with breadcrumbs, description, and action buttons
Empty State	Placeholder for empty lists with icon, message, and CTA
Loading State	Skeleton loader and spinner for async content
Breadcrumbs	Navigation breadcrumb trail with separator

Layout

Component	Description
Sidebar Nav	Collapsible sidebar with grouped links, badges, and user profile
Top Bar	Fixed header with search, notifications, and user menu

Charts

Component	Description
Area Chart	Filled area chart via Recharts with tooltip and legend
Bar Chart	Vertical/horizontal bar chart via Recharts
Donut Chart	Donut/pie chart via Recharts with center label

Layouts

Six reference layout implementations that combine components into complete page structures.

Layout	Description
App Shell	Sidebar + topbar + main content area. The foundation for all pages.
Dashboard	KPI stat cards, charts, and activity table in a responsive grid.
List-Detail	Two-panel layout: list on left, detail view on right.
Settings	Multi-section form with danger zone at the bottom.
Data Management	Full-page data table with filter bar, pagination, and bulk actions.
Auth	Centered card layout for login, register, and password reset.

Design Tokens

Design tokens are the source of truth for all visual values. They're stored as JSON files in the tokens/ directory and compiled into CSS custom properties in globals.css.

Token file	What it defines
colors.json	Semantic colors for backgrounds, text, accents, borders, status, and charts (light + dark)
typography.json	Font families, size scale (h1-h6, body, small, label, code), weights
borders.json	Border width and style for cards, inputs, tables, sidebar, dividers
shadows.json	Box-shadow values for cards, dropdowns, modals, buttons, tooltips
spacing.json	Spacing scale for padding, gaps, line-height, row-height
motion.json	Transition durations (fast, base, slow) and easing curves

How tokens flow

Tokens are generated from your profile's axis coordinates through MatchKit's resolution engine:

Profile (axis coordinates)
  → Mapping files (axis position → concrete values)
    → Token files (CSS custom properties + Tailwind classes)
      → Components (consume tokens, never hardcode)

Components never reference axis positions directly. They consume tokens. This means you can safely edit token values without breaking any component.

Color Palettes

Each theme ships with 4 pre-designed color palettes. All include light and dark mode variants. Tell Claude which palette to use, or let it default.

Clarity UI palettes

Palette	Vibe	Best for
clarity-indigo	Confident, trustworthy	Fintech, enterprise SaaS, CRM
clarity-slate	Minimal, engineering-grade	Dev tools, project management
clarity-mono	Technical, dark-first	Infrastructure, monitoring, CI/CD
clarity-warm	Approachable, collaborative	HR tech, knowledge bases, internal tools

Soft UI palettes

Palette	Vibe	Best for
soft-teal	Calm, modern	AI tools, chat apps, productivity
soft-sage	Natural, grounded	Creative platforms, wellness, green tech
soft-lavender	Gentle, expressive	Consumer SaaS, social, content tools
soft-clay	Warm, earthy	Community platforms, education

Switching palettes

# Just tell your AI editor which palette to use
"Use the clarity-slate palette for this project"
"Switch to soft-sage palette"

Self-Expanding Architecture

The skill library grows with your project. When your AI editor needs a component that doesn't exist in the registry, it creates one following the SKILL.md design rules, writes the file, and registers it. Future sessions reuse it.

Discovery protocol

Read registry.json in the skill directory to find curated components
Read .clarity-catalog.json in the project (if it exists) to find project-specific components
Merge both lists — never improvise if a matching component already exists
Copy .tsx files from the skill into the project, or read them as reference when building

Result: Every component in your app — whether from the curated library or generated during development — follows the same design rules. No drift across sessions.

Configuration Axes

MatchKit decomposes visual identity into 11 independent axes. Each axis has 3-6 positions. A theme is simply a coordinate point in this multi-dimensional style space.

Axis	Positions	What it controls
radius	none, sm, md, lg, xl, full	Corner rounding on all elements
border-weight	none, hairline, thin, medium	Border thickness and presence
shadow-style	none, subtle, soft, hard-offset	Depth and elevation
color-temp	cool, neutral, warm	Neutral tone hue
color-saturation	muted, medium, vibrant	Accent color intensity
font-personality	geometric, humanist, rounded	Font family character
font-weight-bias	light, regular, medium, bold	Heading/emphasis weight
spacing-density	compact, default, spacious	Padding, gaps, breathing room
motion-speed	snappy, default, smooth	Transition speed
button-style	filled, outline, ghost, soft-fill	Button visual treatment
element-separation	border, shadow, bg-color, spacing	How elements are separated

The configurator at matchkit.io/configure exposes 5 of these axes (radius, button-style, element-separation, density, shadow-depth). All 11 are tunable in the generated tokens.

Axes are orthogonal — changing one does not require changes to another. Profiles capture curated combinations that have been tested together.

MCP Server

Your download includes ready-to-go MCP configs for Cursor and VS Code. Unzip into your project root and your editor connects to the design system automatically. The MCP server runs 100% offline.

Quick Install

Click to install the MatchKit MCP server in your editor — no configuration needed.

Claude Code reads .claude/skills/ natively. No MCP server needed — your skill works the moment you unzip it.

No setup required

# That's it. No config needed.
"Build me a dashboard with sidebar nav, KPI cards, and a data table"

Available tools

The MCP server exposes 8 tools that any connected editor can call:

Tool	Description
list_skills	List all installed skills
get_skill_section	Read a section from SKILL.md by topic
list_components	List all components, layouts, and patterns
get_component	Read a component’s source code
get_layout	Read a layout’s source code
get_pattern	Read a pattern’s content
get_tokens	Read design token JSON files
search_components	Search by name, description, or tag

Skill discovery

The MCP server automatically discovers installed skills by scanning these locations (in priority order):

MATCHKIT_SKILLS_DIR environment variable (if set)
.claude/skills/ in your project root
skills/ in your project root (for development)

A valid skill directory must contain both registry.json and SKILL.md to be discovered.

Tech Stack

Required

Package	Version	Why
Next.js	^15.2.0	App Router, React Server Components
React	^19.0.0	Component rendering
Tailwind CSS	v4	Utility classes + CSS custom properties

Package	Purpose
@radix-ui/react-*	Accessible primitives (Select, Dialog, Popover, Tooltip, Switch)
lucide-react	Icon library used in all components
class-variance-authority	Component variant management (CVA)
clsx + tailwind-merge	Conditional class merging
recharts	Charts (Area, Bar, Donut)
sonner	Toast notifications

Install all recommended deps

npm install lucide-react class-variance-authority clsx tailwind-merge \
  @radix-ui/react-select @radix-ui/react-dialog @radix-ui/react-slot \
  @radix-ui/react-popover @radix-ui/react-tooltip @radix-ui/react-switch \
  recharts sonner

FAQ

Does it work with existing projects?

Yes. Unzip at your project root — files land in .claude/skills/. Your AI editor will discover them automatically on the next session.

Can I customize the components?

Absolutely. All components are plain .tsx files with Tailwind classes. Edit them directly — they're yours. Token values in tokens/*.json can also be adjusted.

What if the AI needs a component that doesn't exist?

The skill is self-expanding. The AI reads the SKILL.md rulebook, creates a new component following the design rules, writes the file, and registers it. Future sessions reuse it.

Do I need Tailwind v4?

Yes. MatchKit skills use Tailwind CSS v4's native CSS custom properties for theming. Tailwind v3 is not supported.

Can I use it with Vue or Svelte?

Not yet. MatchKit currently generates React/Next.js components only. Framework support for Vue and Svelte is on the roadmap.

Does it work with Cursor, Copilot, or Windsurf?

Yes. Your download includes MCP config files for Cursor and VS Code — just unzip and they connect automatically. For Windsurf, copy one config block. See the MCP Server section above.

How do I update my skill?

Re-download from matchkit.io/configure with the same configuration. Subscribers get access to all future updates.

Does it support dark mode?

Yes. Every palette includes both light and dark mode tokens. Dark mode is class-based — add the 'dark' class to your HTML element.

Is the generated code production-ready?

Yes. Components are fully typed, accessible (WCAG AA), responsive, and use established patterns from Radix UI and Recharts.

Pricing Terms Privacy Cookies