Skip to content
onsystemv0.12.1

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.

  1. From the app's folder or the monorepo root, with no install and no config:

    Shell
    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 add filled from other registries, such as components/ai-elements, are in code you did not write: Code from shadcn registries says how to set them apart.

    npx -y onsystem inspect shows what it read from your design system: 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 it found nothing, 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. Give 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.

    Prompt for your agent
    Read https://onsystem.vercel.app/setup.md and set up onsystem in this project.

    Or add it yourself. Pick one:

  3. 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. 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
    .github/workflows/onsystem.yml
    - 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, and the CLI reference every option.

  • UI code

    Supported
    React, in .tsx and .jsx files, and .js files with JSX that a glob names
    Not supported yet
    Vue, Svelte, Angular
  • Styling

    Supported
    Tailwind CSS v3 and v4 classes, style objects 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 :root variables), a Tailwind v3 tailwind.config, DTCG 2025.10 .tokens.json files, a DESIGN.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 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
    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
    —

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.