design-system-mcp
A design-system MCP server that gives coding agents your real components, props, variants and tokens, then lints what they write.
List the design system (
list_components): every component with description, rendered native element, variants, parts and import path; at a monorepo root, passpathto scope to the right project or get all projects with their packages.Inspect a component contract (
get_component): props with types/defaults, cva variants and the classes they apply, compound variants, sub-components, inherited props, design tokens used, class names, CSS vars, usage guidelines and code examples. AcceptsButton,CardHeaderorCard.Header.Find the right component by intent (
search_components): natural-language queries like "confirm a destructive action" ranked locally with BM25, matched against names, descriptions, docs, props and variant values.Look up design tokens (
get_tokens): resolved and dark-mode values, Tailwind class or CSS variable usage, filterable by category (color, spacing, radius, typography, shadow, other) or substring.Lint UI code against the system (
check_ui): passcodefor unsaved snippets orpathfor a file; get errors and warnings for hardcoded colors/spacing/radius (with the nearest token), native elements that have a design-system component, unknown components/props/variants, and icon-only buttons lacking an accessible name.Actionable, IDE-style diagnostics: each finding carries a rule id, line/column range, message, suggestion and a concrete edit (
fixranges with replacement text), plus per-rule counts, truncated-result accounting (omitted) and notes on what could not be checked.Safe and local: all tools are read-only, idempotent and closed-world, with no API keys or network access required.
Reads a React design system and serves it to coding agents: lists components with their props, valid variant values, parts and imports, exposes design tokens with resolved values and usages, and provides a check_ui linter the agent can run on its own UI output to catch hardcoded colors, off-scale spacing/radius, invented components and native elements that should use a design-system component.
Works out of the box in shadcn/ui-style projects (components/ui/*.tsx, app/globals.css) with no configuration, extracting shadcn/ui components, cva variants and their classes, and flagging native elements that should use the corresponding shadcn/ui component.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@design-system-mcp run check_ui on app/settings/danger-zone.tsx and fix all errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
onsystem
Keeps coding agents on your design system: catches palette colors, native elements and APIs your system lacks, at every edit and pull request, with the fix. Set it up once in your design-system package; every app in your monorepo gets it. Runs locally and works alongside @shadcn/lint.
Built for design-system and platform teams with a React design-system package; a shadcn/ui app is the zero-config demo. Formerly @dgesteves/design-system-mcp (what changed).
Using the GitHub Action? uses: dgesteves/onsystem@v0 checks the lines a pull request changed: see CI and baselines.
Also works with
Website and docs: onsystem.vercel.app, with a playground that checks your own code.
Feedback wanted: say where it breaks in the launch feedback thread, see what's next in the roadmap, or pick up a good first issue. If onsystem is useful to you, a star helps other people find it.
https://github.com/user-attachments/assets/900cc1fa-387c-4e76-a524-a818521dd1a0
On the website, an agent drafts a settings card, check_ui finds 11 problems with a fix each, and the agent applies them. Then a real Claude Code session with the plugin: Claude looks the components up before writing, and check_ui passes. Last, the benchmark.
The problem
Coding agents write UI from their training data, not from your design system. Ask for a settings card and you get bg-[#ef4444], p-[13px], a native <button>, variant="danger" on a Button that only has destructive, and <Card.Header> where the system exports CardHeader. On the demo draft above, tsc reports 3 of the 11 problems, and review catches the rest when someone has the time. Describing the design system to the agent helps; what holds is checking what it actually wrote, at the edit and at the pull request.
Related MCP server: weave-design-system-mcp
What it checks
onsystem reads your components, cva and tv variants, parts and tokens from source with the TypeScript compiler, and checks .tsx and .jsx against them. Every finding has a rule id, a location and the fix. Tokens come from your stylesheets, DTCG 2025.10 files or a DESIGN.md, and onsystem export writes them out as either.
Rule | Default | Catches |
| error | Components and parts that don't exist ( |
| error | Props a component doesn't take ( |
| error | Values outside a variant ( |
| error | Native elements the design system has a component for ( |
| error | Hex, rgb, hsl, oklch and Tailwind palette colors ( |
| error | Icon-only buttons without an accessible name |
| warn | Arbitrary padding, margin and gap ( |
| warn | Arbitrary radius ( |
How often it is wrong. The corpus job runs check on 12 public repositories pinned by commit (Documenso, Dub, Cal.com, midday, Flowise and others: 24 runs, 14,539 distinct findings), without their dependencies installed (the two MUI apps get MUI). A seeded random sample of 80 of those findings, stratified by rule, was labelled from the code alone: blind labels by an AI reviewer (Claude Opus 5.5), not by a person. 57 are right, 14 debatable and 9 false positives: 11.2% (95% Wilson interval 6.0-20.0%), about the same when weighted by each rule's share of all findings (11.0%). Most come from no-hardcoded-color (7 of 65 sampled). Counting values a project's own design system already uses as debatable, 6 of 80 are false positives (7.5%, 3.5-15.4%). The sample has each label with its reason, the labeller's notes and the script behind these numbers. Shipped code rarely invents components, props or variants, and without dependencies no-unknown-prop skips components whose props do not resolve: those three rules have 56 findings in the corpus, 55 of them in Flowise, an MUI app, and 3 in the sample, all right but too few for a rate of their own. The corpus's older labels, made by an AI reviewer who could see the finding and so not blind, fail the job when one of their true positives stops being reported or a fixed false positive comes back. Code installed from a shadcn registry, such as the chatbot's components/ai-elements, has no labels yet (Code from shadcn registries). The rules reference shows each rule on an example and how to suppress a finding.
Quickstart
Run it from the app's folder or from the monorepo root, with Node.js 20.19 or later:
npx -y onsystem inspect # what it found; --explain says why
npx -y onsystem check . # the same check the agent and CI run
npx -y onsystem init # write the config, and offer a baselineAt a monorepo root, inspect lists every app and design-system package, and check checks each file by its own project's design system. In a design-system package, init sets it up for every app that depends on it, with no config in the apps: as a workspace package, or installed from npm. Installed apps read the components from the sources the package publishes, or from its type declarations (.d.ts) when it publishes only compiled dist/, and get every rule either way (init checks its files list). From a package that publishes compiled code and no type declarations, they get the token rules but no component, prop, variant or native-element checks.
In a new create-next-app, the template page's hardcoded colors already make the first check . fail; init offers to record them as a baseline, so only new findings fail. Folders installed from a shadcn registry, such as components/ai-elements, are someone else's code: Code from shadcn registries says how to check them or leave them out.
Claude Code. The plugin brings the hook, the MCP server and a skill:
/plugin marketplace add dgesteves/onsystem
/plugin install onsystem@dgestevesAfter each Write or Edit of a .tsx or .jsx file, the hook runs onsystem check on it. Errors go back to Claude as a blocking error with the fix, so Claude corrects the file before it moves on; warnings go as a note. It stays quiet in projects without a design system. Codex installs the same plugin, and the hook checks the files its apply_patch changes. What it runs and touches.
Cursor or VS Code.
, or commit the config. The agent gets the tools and runs
check_ui on what it writes.
Other agents. npx skills add dgesteves/onsystem adds the skill to any agent with Agent Skills, and there are plugins for Codex, GitHub Copilot CLI, VS Code and Cursor.
Any MCP client. Run npx -y onsystem as a stdio server. There are configs for Claude Desktop, Codex CLI, GitHub Copilot CLI, Windsurf, JetBrains IDEs, Zed, Gemini CLI, Antigravity and Grok Build.
CI. Install it as a dev dependency, accept the findings the codebase already has once, and fail pull requests only on new ones:
npm install --save-dev onsystem
npx onsystem check . --update-baseline # writes onsystem.baseline.json: commit it- run: npx onsystem check . --format github --require-design-systemFindings show up as annotations on the pull request, and --require-design-system fails the job when the design system is no longer found. CI and baselines has the whole workflow.
GitHub Action. The action runs the same check, honours the baseline and annotates only the lines a pull request changed. It goes after the checkout and the install, so it can read your design system:
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
- run: npm ci
- uses: dgesteves/onsystem@v0Make it a required check on agent pull requests has the whole workflow and its inputs.
ESLint. The same rules for ESLint 8.57, 9 and 10: add onsystem.configs.recommended from onsystem/eslint to eslint.config.mjs (ESLint plugin, with @shadcn/lint).
Works with @shadcn/lint
@shadcn/lint checks the Tailwind classes written against a component and the theme (restyling, raw colors, arbitrary and unknown classes) as ESLint or Oxlint rules on Tailwind v4. onsystem checks that the components, props and variant values exist and flags native elements and unnamed icon buttons, on Tailwind v3 or v4. Its MCP server shows the agent your components and tokens before it writes, and in Claude Code its hook checks every edit. Run both. Benchmark v2 also scores every output with @shadcn/lint: see the independent scorer's table.
Does it help?
Benchmark v2 gave 6 models from 3 providers (Anthropic, OpenAI and Google) 20 single-file UI tasks in 5 open-source repositories, without onsystem, with its skill, MCP server or hook, and with all three: 1,200 runs, 240 per arm. Counted by onsystem 0.5.0's own check, design-system errors per run went from 0.85 without onsystem to 0.00 with all three, with no measurable change in the tsc pass rate (93% → 92%).
That count is onsystem's own, and the MCP server and the hook show the agent the same errors to fix. In tasks that ask for a green status label in a design system with no success token, agents with onsystem often used chart-* tokens, which it counts as clean. The blind labels by an AI reviewer, 12 files per arm, are too few to confirm the count either way, and every violation they found with the hook or all three is a palette color in Dub, whose tokens 0.5.0 did not read. The benchmark page has every table, and bench/v2 the method, the per-run data and every generated file.
Compatibility
What package.json declares and CI runs:
With | Supported |
Node.js | Node.js 20.19 or later ( |
Operating system | Linux, macOS and Windows: CI runs the tests and the pack test on each |
ESLint | ESLint 8.57, 9 and 10, for the ESLint plugin only: |
TypeScript | Your project's TypeScript is not used, and a JavaScript project needs none: onsystem reads |
React | Components written for React 18 ( |
Tailwind CSS | v4 ( |
shadcn/ui | Both bases, Radix ( |
MCP clients | Any client that starts a stdio server; CI connects on the 2025-11-25 and 2026-07-28 protocols. Set up your agent has each client's config and support tier |
Docs
On the website, and as Markdown in docs/:
Quickstart, Claude Code plugin, CI and baselines and Set up your agent, with the config for each client
Contributing, security and the changelog are in the repository.
License
MIT © Diogo Esteves
Available Tools
5 toolscheck_uiCheck UI code against the design systemARead-onlyIdempotent
Lint TSX/JSX against the design system. Reports hardcoded colors, spacing and radius (with the nearest token), native elements that have a design-system component, unknown components, props and variant values, and icon-only buttons without an accessible name. Each diagnostic has line/column, a rule id, a message and a suggested fix. Run it on every snippet or file you write and fix all errors. Pass path for a file in the project, or code for unsaved code, with path (or filename) naming the file it is for or its project folder.
Inputs: code, path, limit, filename. Returns: ok, file, byRule, notice, +6 more
get_componentGet a component contractARead-onlyIdempotent
Get the full contract of one component: import, props with types and defaults, cva variants and the classes each applies, parts (sub-components), design tokens it uses, usage guidelines and examples from its docs. Call it before using a component. Accepts "Button", "CardHeader" or "Card.Header". At a monorepo root, pass path (the file you are editing) to get the component its project uses.
Inputs: name (required), path. Returns: docs, name, props, import, +23 more
get_tokensGet design tokensARead-onlyIdempotent
List design tokens with resolved values, dark-mode values and how to use each (Tailwind class or CSS variable). Filter by category (color, spacing, radius, typography, shadow, other) or a substring. Use these instead of hex codes, px values or Tailwind default palette classes. Chart and sidebar colors are listed under their own headings: they are for charts and the sidebar, not for status colors.
Inputs: path, query, category. Returns: tokens
list_componentsList design-system componentsARead-onlyIdempotent
List every component in the project design system with a one-line description, the native element it renders, its variant values, its parts and its import. Icons (components that render an ) are named on one line per import, or per folder for icons with a module each, five or more to a line. Call this before writing UI in this project. query, kind and limit narrow a long list. At a monorepo root, pass path for the project of the file you are editing; without it, every project is listed, each component with its package.
Inputs: kind, path, limit, query. Returns: icons, omitted, components
search_componentsSearch components by intentARead-onlyIdempotent
Find components by what you want to build, e.g. "confirm a destructive action", "status label", "text field with validation". Ranks names, descriptions, docs, props and variant values with BM25 (local, no API key). When no component clearly matches, it says so and lists the nearest, marked weak. Use it when you do not know which component fits.
Inputs: query (required), path, limit. Returns: results
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly stated role: enumerate components, fetch one component's contract, intent-based search, list tokens, and lint code. The only blur is between list_components' `query` filter and search_components, which both narrow a component list; descriptions mitigate this by framing search as BM25 ranking by build intent, but an agent could still reach for the wrong one.
All five tools follow a strict verb_noun snake_case pattern (list_components, get_component, search_components, get_tokens, check_ui). The get_* pair is parallel and the remaining verbs clearly differ in intent.
Five tools maps cleanly onto the domain's jobs: discover (list/search), inspect (get_component), style (get_tokens), and verify (check_ui). No tool looks redundant or padded, and nothing obvious is missing at this size.
The surface covers the full agent workflow of finding, reading, styling and validating components, including monorepo path handling. Minor gaps remain: there is no dedicated way to retrieve docs/guidelines or examples alone, and no reverse lookup from an arbitrary class or hex value back to a token outside the lint diagnostics.
Maintenance
Related MCP Connectors
Live React design-system APIs, patterns, and code validation so AI agents build real UI, not slop.
Serves your design system and coding standards to coding agents, so they stop guessing.
Design systems your AI agent builds with and you reshape, plus standalone React components.
Give your agent a real design system: tokens, measured WCAG contrast, and rules to follow.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for the Lando Labs Design System, enabling AI agents to introspect and generate code for React components, hooks, icons, design tokens, and theme presets via 15 tools.1513 npm1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to query a workspace's design system before writing UI and validate generated code against the same system afterward, using configurable token and component sources.13 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query a design system's components, tokens, icons, patterns, and usage or accessibility guidelines through standardized MCP tools, with pluggable adapters for different data sources.MIT
- AlicenseAqualityCmaintenanceA design harness for AI coding agents. Better Design gives an agent design systems, UI and UX principles, icons and UI review: it finds or creates a design system that fits the product and installs its components, explains how sign-up, forms and onboarding should work, and reviews finished screens for readability, accessibility and unclear copy.48586MIT