Quickstart

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. It needs Node.js 20.19 or later. 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.

1. See what it found, from the app's folder or the monorepo root:

npx -y onsystem inspect

It lists the components with their props, variants and parts, and the tokens by category. inspect --explain adds 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 the list is empty, see troubleshooting.

To keep what it found in a file you can edit, run npx -y onsystem init: it writes onsystem.config.json from 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. --yes answers for you.

2. Hold your agent to it. 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@dgesteves

• Cursor or VS Code: use the one-click install links, or commit the config there to the repository.

• Any other 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 and Grok Build.

3. Try it. 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_ui on 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.

4. Gate your pull requests. Install 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 it

- run: npx onsystem check . --format github --require-design-system

check . lints every .tsx and .jsx file 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.