Get started
Quickstart
From nothing to an agent that is held to your design system, and pull requests that are checked against it. Four steps, a couple of minutes.
No config is needed in a shadcn/ui project (Tailwind v3 or v4), an app whose components live in a workspace package, or the design-system package itself (how it finds them). Other layouts take a config file. Run it from the app's folder, or from a monorepo root, where it finds every app and design-system package and checks each file against its own project.
Note
It needs Node.js 20.19 or later.
See what it found
Link to the section See what it foundFrom the app's folder or the monorepo root, with no install and no config:
npx -y onsystem check .It checks your UI code against the components, variants and tokens it found and prints each finding with what to write instead. It exits with code 1 when there are errors. Findings in folders that
npx shadcn addfilled from other registries, such ascomponents/ai-elements, are in code you did not write: Code from shadcn registries says how to set them apart.npx -y onsystem inspectshows what it read from your design system: the components with their props, variants and parts, and the tokens by category.inspect --explainadds every place it looked and why each was taken or not, the config it resolved to, tokens that did not resolve and components whose props did not. If it found nothing, see troubleshooting.To keep what it found in a file you can edit, run
npx -y onsystem init: it writesonsystem.config.jsonfrom it (or asks where the components and tokens are when it found nothing), checks the project once and offers to record the findings as a baseline.--yesanswers for you.Hold your agent to it
Link to the section Hold your agent to itGive your agent this prompt, and it does the rest of the setup itself: the config and the baseline, onsystem in the agent, and the CI check. setup.md has the steps it follows.
Read https://onsystem.vercel.app/setup.md and set up onsystem in this project.Or add it yourself. Pick one:
Claude Code: install the plugin. Its hook checks every UI file Claude writes and hands the errors back before Claude moves on; it also brings the MCP server and a skill that has Claude look components up first.
/plugin marketplace add dgesteves/onsystem/plugin install onsystem@dgestevesCursor or VS Code: use the one-click install links, or commit the config there to the repository.
Any other MCP client: run
npx -y onsystemas a stdio server. There are configs for Claude Desktop, Codex CLI, GitHub Copilot CLI, Windsurf, JetBrains IDEs, Zed, Gemini CLI, Antigravity and Grok Build.
Ask your agent for some UI, such as "Add a danger-zone card to the settings page." It looks the components, variants and tokens up before writing and runs
check_uion the result. In Claude Code the skill loads by itself for UI work (or run/onsystem:onsystem), and the hook checks each file as it is written.Gate your pull requests
Link to the section Gate your pull requestsInstall it as a dev dependency, record the findings the codebase already has, and fail CI only on new ones:
npm install --save-dev onsystemnpx onsystem check . --update-baseline # writes onsystem.baseline.json: commit itpnpm add -D onsystempnpm exec onsystem check . --update-baseline # writes onsystem.baseline.json: commit ityarn add -D onsystemyarn onsystem check . --update-baseline # writes onsystem.baseline.json: commit itbun add -d onsystembunx onsystem check . --update-baseline # writes onsystem.baseline.json: commit it- run: npx onsystem check . --format github --require-design-systemcheck .lints every.tsxand.jsxfile under the folder, whatever the layout, and leaves out the design system's own components, tests and stories, and what git ignores. CI and baselines has the whole workflow, and the CLI reference every option.
What it works with
Link to the section What it works withUI code
- Supported
- React, in
.tsxand.jsxfiles, and.jsfiles with JSX that a glob names - Not supported yet
- Vue, Svelte, Angular
Styling
- Supported
- Tailwind CSS v3 and v4 classes,
styleobjects and color attributes - Not supported yet
- CSS-in-JS (styled-components, Emotion), CSS Modules, plain stylesheets
Variants
- Supported
cva(),tv()(tailwind-variants), and props typed as unions of string literals- Not supported yet
- —
Components
- Supported
- Your own, such as shadcn/ui's or ones built on Radix, React Aria, Base UI or another primitives library, in the app or in a workspace package; a design-system package installed with its type declarations (design-system packages); MUI (
@mui/material) - Not supported yet
- Chakra UI, Mantine, HeroUI, Radix Themes, Ant Design, MUI's other packages
Tokens
- Supported
- CSS custom properties (Tailwind v4's
@theme, shadcn/ui's:rootvariables), a Tailwind v3tailwind.config, DTCG 2025.10.tokens.jsonfiles, aDESIGN.md(tokens) - Not supported yet
- Values computed in code
Monorepos
- Supported
- pnpm, npm, Yarn and Bun workspaces, Lerna, Nx and Turborepo (monorepo roots)
- Not supported yet
- —
Agents
- Supported
- Tested in the client: the Claude Code plugin (hook, MCP server and skill), the MCP server in Claude Code and Gemini CLI, and the skill through
npx skills add. Set up from each client's docs, not yet run in it: the hook in Codex CLI, and the MCP server in Cursor, VS Code and other clients (support tiers) - Not supported yet
- —
CI and editors
- Supported
onsystem checkin any CI with Node.js, the GitHub Action, and the ESLint plugin for ESLint 8.57, 9 and 10 with a flat config- Not supported yet
- —
Runtime
- Supported
- Node.js 20.19 or later (22.18 or later for a TypeScript config file), on macOS, Linux and Windows
- Not supported yet
- —
| Supported | Not supported yet | |
|---|---|---|
| UI code | React, in .tsx and .jsx files, and .js files with JSX that a glob names | Vue, Svelte, Angular |
| Styling | Tailwind CSS v3 and v4 classes, style objects and color attributes | CSS-in-JS (styled-components, Emotion), CSS Modules, plain stylesheets |
| Variants | cva(), tv() (tailwind-variants), and props typed as unions of string literals | — |
| Components | Your own, such as shadcn/ui's or ones built on Radix, React Aria, Base UI or another primitives library, in the app or in a workspace package; a design-system package installed with its type declarations (design-system packages); MUI (@mui/material) | Chakra UI, Mantine, HeroUI, Radix Themes, Ant Design, MUI's other packages |
| Tokens | CSS custom properties (Tailwind v4's @theme, shadcn/ui's :root variables), a Tailwind v3 tailwind.config, DTCG 2025.10 .tokens.json files, a DESIGN.md (tokens) | Values computed in code |
| Monorepos | pnpm, npm, Yarn and Bun workspaces, Lerna, Nx and Turborepo (monorepo roots) | — |
| Agents | Tested in the client: the Claude Code plugin (hook, MCP server and skill), the MCP server in Claude Code and Gemini CLI, and the skill through npx skills add. Set up from each client's docs, not yet run in it: the hook in Codex CLI, and the MCP server in Cursor, VS Code and other clients (support tiers) | — |
| CI and editors | onsystem check in any CI with Node.js, the GitHub Action, and the ESLint plugin for ESLint 8.57, 9 and 10 with a flat config | — |
| Runtime | Node.js 20.19 or later (22.18 or later for a TypeScript config file), on macOS, Linux and Windows | — |
Zero config finds the design system in the common layouts (how); the others take a config file with a components glob. How it works lists what it does not check yet.