Docs

FAQ

Does my code leave my machine?

No. The server and the CLI run where you run them: they read your files with the TypeScript compiler and apply the rules, with no model calls, no API key and no network requests. Your agent sends its context to its own model, as it does with any tool. The playground is the one exception: it sends what you type to this site, which checks it and does not store it.

Is there a model behind it?

No. The agent is already the model; what it lacks is ground truth. Everything here is deterministic static analysis that takes milliseconds and can be tested rule by rule. The trade-off: it cannot judge intent, such as whether a Dialog was the right call. That stays with the agent and the reviewer.

How is it different from @shadcn/lint?

@shadcn/lint is a linter: it polices the classes written against a component and the theme, in React, Svelte and Vue, on Tailwind v4. design-system-mcp gives the agent the components, props, variants and tokens before it writes, and catches what does not exist (components, props, variant values), native elements the design system wraps and icon buttons without a name, on Tailwind v3 or v4. Running both in CI is a sensible setup.

Why not Storybook MCP?

It is a good fit if you run Storybook: it serves stories and a component manifest from a running instance, and can run component tests. design-system-mcp reads the source, so it works in projects without Storybook, and in CI.

Why not describe the design system in CLAUDE.md or AGENTS.md?

A static list goes stale, and agents still guess prop values and colors. Here the agent asks for the component it is about to use and gets checked afterwards. One line in CLAUDE.md, AGENTS.md or .cursor/rules still helps clients that ignore the server's instructions: "Before writing UI, use the design-system tools. Run check_ui on every file you change and fix all errors."

My components are not in components/ui. Do I need a config?

Not if the app has a shadcn/ui components.json, imports a workspace package named like a design system (@acme/ui), is the design-system package itself, or keeps its components in a flat src/ that wraps React Aria, Radix or another primitives library: zero config finds those. Otherwise a config file with a components glob is enough. npx -y @dgesteves/design-system-mcp inspect prints what was found.

Will check fail on my design system's own components?

No. check skips the files components matches: they implement the scale and the primitives the rules enforce. --include-design-system lints them too.

Is the Claude Code plugin safe to install everywhere?

Yes. The hook stays quiet in projects without a design system, only reports on what Claude just changed, and honours a baseline.

Does it work with Vue, Svelte or Angular?

Not yet: React only (.tsx and .jsx). Angular and Web Components extraction is first on the roadmap.

It flagged something that is fine. What now?

Turn the rule off or allow the value in the config, and please open an issue with the snippet and the output of inspect. A linter lives or dies on false positives, so those are the reports I most want.

What does it need to run?

Node.js 22.18 or later. On native Windows, wrap the command as cmd /c npx ....

Limits

React only (.tsx and .jsx): no Vue, Svelte or Angular yet.
Styling is checked in Tailwind classes, style objects (including style functions and each branch of a conditional value) and color attributes. CSS-in-JS (styled-components, Emotion), CSS Modules and plain stylesheets are not.
Fix suggestions are Tailwind classes when a Tailwind theme maps the token (@theme, or a v3 tailwind.config), otherwise var(--token) (hsl(var(--token)) for v3 channels). A v3 config is read without running it, so colors computed in code are not seen.
Colors are compared in the base theme and, for dark: classes, the dark mode. Other modes ([data-theme="brand"]) are listed by get_tokens but not used to match.
Linting is per file and syntactic. Class names built at runtime (` bg-${color}-500 `) are not checked, and spread props are trusted.
no-unknown-prop is skipped for components whose props type does not fully resolve (dependencies not installed).
Composition is inferred from naming and static members; other patterns need explicit exports.
A UI package imported by path is read from what the app already imports (in its first 5,000 source files), so components nobody imports yet are not offered.
While the server runs, it rebuilds on changes in the component, token and docs folders, the config file, the tsconfig and the tsconfigs it extends. An edit to another file the components import (a shared lib/types.ts) is picked up on the next start.
No typography or shadow rules yet, and stdio is the only transport.

Generated from the README when the site is built: #limits.