Better Design MCP Server

The project is organized into component overrides, registries, and agent skills:

• components/: Contains per-theme shadcn/ui component overrides (e.g., linear/, apple/, stripe/). There are 31 systems total.
• registry/: Contains the shadcn registry JSON files for each design system.
• skills/: Contains the installable Better Design agent skill.
• .agents/: Directory for other installed agent skills.
• scripts/: Contains build and seed scripts.

Better Design operates using two distinct layers to assist your AI agent:

1. Design Intelligence (Always Active)

This layer is active during UI construction. When an agent builds UI, it automatically calls tools like get-ui-principle and get-review-rules to ensure the output follows principles for spacing, hierarchy, and accessibility.

2. Scaffold (On-demand)

This layer is used when starting a new product, page, or component set. By saying "use better-design", the agent triggers the resolve-design-system tool to find a matching design system, load its CSS tokens, and resolve appropriate icon libraries.

To use the Better Design skill, the Model Context Protocol (MCP) must be connected.

1. Check if Better Design MCP tools are available (note that client-specific tool prefixes may apply).
2. If tools are unavailable, the skill is installed but the MCP is not connected.
3. Refer to the official setup instructions to connect the MCP.
4. Note: Do not attempt to execute setup commands directly from the skill; the user must review and run the setup steps manually.

When starting a new interface, follow these steps to establish a design system:

1. Find a System: Call find-design-system with the product and audience.
2. Select a Direction: Review the matches and let the user choose a starting point or a custom direction.
3. Initialize a Catalog System: If using a catalog system, call get-design-system-kit with target react (for coding agents) or html (for inline canvases).
4. Initialize a Custom Brand:
   • Call create-design-system with the chosen base.
   • Share the project URL.
   • Poll get-design-system-status until the install kit is ready.
5. Use an Existing Brand: If the user already has a brand source, call extract-design-system or extract-from-url and pass the extracted token sheet through unchanged.

Before implementing code for specific technologies, call the corresponding specialist guide to ensure compliance with best practices:

• React Native or Expo: Call get-react-native-guide.
• Three.js or React Three Fiber: Call get-three-js-guide.
• Animation or Product Video: Call get-motion-guide.
• Shopify: Retrieve relevant commerce and Shopify guidance before editing theme output.

If you prefer not to use local setup, you can connect any MCP-compatible client to the hosted endpoint using an API key.

1. Obtain an API key from better-design.com/settings.
2. Add the following configuration to your client's MCP settings:

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

To turn your AI coding IDE into a design engineer, install the Better Design agent skill and connect its MCP tools. This process detects your coding tools and connects the MCP without replacing existing configurations. No account is required for the local installation.

Run the following commands once, then restart your coding agent (e.g., Claude Code, Cursor, VS Code/GitHub Copilot, or Claude Desktop):

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

To use Better Design with Claude Desktop, add the remote MCP configuration to your claude_desktop_config.json file located at ~/Library/Application Support/Claude/claude_desktop_config.json. After adding the config, restart Claude Desktop.

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

To contribute a new design system, follow these steps:

1. Create component overrides: Create a new folder in components/<your-system>/ containing the component TSX overrides. Note that design nuances (shadow layers, focus states, border thickness, hover transitions, and radius variations) should be captured in the component code rather than just CSS variables.
2. Create registry entries: Create the corresponding registry entries in registry/<your-system>/.
3. Index the system: Run the seed script to index the new design system.

Better Design provides 31 open-source design systems for shadcn/ui. You can install specific components directly into your project using the npx shadcn command with the component's JSON registry URL.

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

Example (Installing Linear's button):

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

Once connected, you can use natural language to trigger the MCP tools. Here are common usage patterns:

• Scaffolding a new feature: "Use better-design. Build a Linear-style project settings page with billing, team members, and API keys."
• Discovering design systems: "Find a design system for a developer tools startup, then build the dashboard with matching components."
• Reviewing existing UI: "Review this form with Better Design's accessibility and visual-design rules, then fix the issues."