Better Design

Better Design: Open source Claude Design

Turn your AI coding IDE into a design engineer. Better Design works with MCP-compatible agents and editors like Claude Code, Cursor, VS Code/GitHub Copilot, Claude Desktop, and claude.ai. It is a design MCP server, AI design-system registry, and UI review layer for generating polished product interfaces from prompts.

Website · Design systems · Setup · Contributing

What is Better Design?

Better Design gives AI coding agents the design context they usually miss: design tokens, component code, UI principles, icon direction, accessibility checks, and visual-design review rules.

Think of it as a Claude Design-style workflow for your own codebase:

1. Pick the product direction: Linear, Supabase, Vercel, Airbnb, Stripe, Apple, Notion, Figma, or another curated design system.
2. Feed your AI agent the right globals.css, semantic tokens, component overrides, icon set, spacing, typography, shadows, radius, and motion language.
3. Ask Claude Code, Cursor, VS Code/GitHub Copilot, Claude Desktop, claude.ai, or another MCP-compatible coding agent to build the interface.
4. Have the MCP review the output against accessibility and design principles before you ship it.

Instead of "AI-looking UI," you get interfaces that look like they were built from a real product design system.

Why Better Design?

• Claude Design-style workflow, open MCP. Bring the artifact-first design loop people expect from Claude Design into Claude Code, Cursor, VS Code/GitHub Copilot, Claude Desktop, claude.ai, and any MCP-compatible client.
• Design systems, not vague vibes. Each system includes semantic CSS tokens plus production component code, so generated UI uses real implementation details instead of guessed colors.
• AI UI generation with guardrails. The MCP can load principles for hierarchy, spacing, typography, depth, motion, forms, and accessibility exactly when the agent needs them.
• Self-review before handoff. get-review-rules gives your agent a WCAG and visual-design checklist so it can catch missing focus states, weak hierarchy, bad contrast, and inconsistent spacing.

How it works

Better Design has two layers: an always-on Design Intelligence layer and an on-demand Scaffold layer.

Design Intelligence — always active for UI work

When your agent builds UI, Better Design loads the relevant product-design principles and review rules automatically:

You: "Add a settings page with a form"

AI: calls get-ui-principle("spacing") + get-ui-principle("hierarchy")
 → writes the page
 → calls get-review-rules("accessibility") + get-review-rules("visual-design")
 → fixes contrast, labels, focus states, spacing, and hierarchy

Scaffold — design-system matching for new UI

When starting a product, page, or component set, say "use better-design" and the MCP finds a matching design system:

You: "Build a fintech dashboard in the style of Stripe. use better-design"

AI: calls resolve-design-system("fintech dashboard, Stripe")
 → loads design-system docs, CSS tokens, and component code
 → resolves a matching icon library
 → builds with semantic tokens instead of raw colors

What the MCP gives your agent

Available Design Systems

31 open-source design systems for shadcn/ui. Browse and preview them all at better-design.com.

Each design system includes a full globals.css token layer plus component overrides. Install any component into your shadcn/ui project:

npx shadcn@latest add https://www.better-design.com/registry/<design-system>/<component>.json

Example — install Linear's button:

npx shadcn@latest add https://www.better-design.com/registry/linear/button.json

Or grab all 9 transitions.dev ports at once (notification-badge, menu-dropdown, panel-reveal, card-resize, icon-swap, text-swap, modal-transition, page-slide, number-pop-in):

npx shadcn@latest add https://www.better-design.com/registry/linear/transitions.json

The transitions come from one source, scripts/transitions-src/. After you edit it, run node scripts/generate-transitions.mjs to rewrite every design system, then run the tests:

cd tests && bun install && bun run test

Usage examples

Once connected to your MCP client, ask your agent for design help directly:

"Use better-design. Build a Linear-style project settings page with billing, team members, and API keys."

"Find a design system for a developer tools startup, then build the dashboard with matching components."

"Review this form with Better Design's accessibility and visual-design rules, then fix the issues."

Setup

Install the Better Design agent skill, then connect its MCP tools:

npx skills add marvkr/better-design --skill better-design
npx better-design

Run each command once, then restart your coding agent. The skill tells supported agents when to use Better Design. The installer detects your coding tools and connects the MCP without replacing their existing configuration. No account is required.

Connect via Remote MCP manually

Connect any MCP-compatible client to the hosted endpoint — no local setup needed.

1. Go to better-design.com/settings to get an API key.
2. Add the remote MCP to your client config:

{
  "mcpServers": {
    "better-design": {
      "url": "https://better-design.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Connect via Claude Desktop (remote MCP)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "better-design": {
      "url": "https://better-design.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Restart Claude Desktop. You can now ask Claude to use Better Design while building UI.

Project Structure

better-design/
├── components/          # Per-theme shadcn/ui component overrides
│   ├── linear/
│   ├── apple/
│   ├── stripe/
│   └── ...              # 31 systems total
├── registry/            # shadcn registry JSON for each design system
│   ├── linear/
│   ├── apple/
│   └── ...
├── scripts/             # Build and seed scripts
├── skills/              # Installable Better Design agent skill
├── .agents/             # Other installed agent skills
└── README.md

Contributing

To add a new design system:

1. Create a folder in components/<your-system>/ with component TSX overrides.
2. Create the corresponding registry entries in registry/<your-system>/.
3. Run the seed script to index the new system.

Design nuances live in the components, not just CSS variables — shadow layers, focus states, border thickness, hover transitions, and radius variations by context all need to be captured in component code.

License

MIT