Skip to content
design-system-mcp

Docs

Claude Code plugin

The plugin bundles the server, a skill that tells Claude to look components and tokens up before writing UI, and a hook that runs check on every .tsx/.jsx file Claude writes or edits and hands the errors back, so they get fixed in the same turn instead of in review:

/plugin marketplace add dgesteves/design-system-mcp/plugin install design-system@dgesteves
⏺ Write(app/promo/page.tsx)  ⎿  PostToolUse hook: app/promo/page.tsx breaks the project's design system     1:58 error [no-hardcoded-color] Hardcoded color `bg-[#f5f5f5]` → `bg-muted`.     1:77 error [prefer-design-system-component] Native <button> where the design system has <Button>.     …⏺ The hook flagged five issues. Looking up Button and the color tokens before fixing.⏺ design-system - get_component (MCP)(name: "Button")⏺ Write(app/promo/page.tsx)   →   <Button variant="destructive"> on bg-muted, hook passes

The hook only speaks up about what Claude just changed: after an Edit it lists the findings on the edited lines and only counts older ones, it honours a baseline, and it stays quiet in projects without a design system, so installing the plugin for every project is safe. Like check, it leaves the design system's own files alone: an edit to components/ui/button.tsx changes the design system, which is a call for you and your reviewers rather than a lint error. Warnings go to Claude as context without blocking. It runs the project's own install when there is one, else npx, and finds the project from the edited file, so it works in monorepos. If you added the server with claude mcp add before, remove that entry (claude mcp remove design-system) to avoid two copies of the tools.

What the skill tells Claude

Claude loads it by itself for UI work, or with /design-system:design-system. This is its text, from SKILL.md:

The design-system MCP server reads this project's components (props, cva variants, parts), design tokens and component docs. Use it as ground truth: training data does not know this project's Button variants or color tokens.

Before writing UI

  1. Find what exists: search_components with the intent ("confirm a destructive action", "status label"), or list_components.

  2. Read get_component for every component you use. Use only the props and variant values it lists, the import it shows, and its parts (CardHeader, not Card.Header, unless it lists the member).

  3. Style with tokens from get_tokens: semantic classes such as bg-destructive or text-muted-foreground, never hex or rgb values, arbitrary pixel values (p-[13px]) or Tailwind's default palette (bg-red-500).

  4. Prefer a variant over overriding a component's classes, and a design-system component over a native element (<Button>, not <button>).

  5. Give icon-only buttons an accessible name (aria-label).

After writing UI

Run check_ui on every file you changed and fix every error. Each finding has a rule id, a location and usually the exact fix. The plugin's hook also runs the same check after each edit and reports errors back to you; fix them before moving on rather than working around them.

If the project has a design-system-mcp.baseline.json, the command-line check (and the hook) report only findings the baseline does not already accept. check_ui shows everything in the file; fix what you introduced, and leave unrelated pre-existing findings alone unless asked.

Generated from the README when the site is built: #claude-code-plugin.