Skip to content
onsystemv0.12.1

Keeps coding agents on your design system.

Catches palette colors, native elements and APIs your design system lacks in agent-written React, 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.

npx -y onsystem check .
Get started

See what it finds in your app. No install, no config. Items from other shadcn registries count as your code until you set them apart: Code from shadcn registries.

Try it in the browser
app/settings/danger-zone.tsxcheck_ui
<Card className="border-[#ef4444] p-[13px]">errorno-hardcoded-colorborder-[#ef4444] → border-destructiveimport { Button } from "@/components/ui/button"<button className="rounded-[7px] bg-gray-100 px-3 text-sm">errorprefer-design-system-component<button> → <Button><Button variant="danger" onClick={onDelete}>errorno-unknown-variantvariant="danger" → variant="destructive"
tsc 3/11 · onsystem 11/11 on this draft

Installs the MCP server (shows the agent your components and tokens) and hook (checks every edit), with the skill. The plugin

/plugin marketplace add dgesteves/onsystem/plugin install onsystem@dgesteves

~/acme-app — agent session

app/settings/danger-zone.tsx29 lines, unchecked
import { Trash2 } from "lucide-react"import { Badge } from "@/components/ui/badge"import { Button } from "@/components/ui/button"import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"export function DangerZone({ onDelete }: { onDelete: () => void }) {  return (    <Card className="border-[#ef4444] p-[13px]">      <CardHeader>        <CardTitle>Delete workspace</CardTitle>        <Card.Description>This cannot be undone.</Card.Description>      </CardHeader>      <CardContent className="flex items-center gap-3">        <Badge tone="warning">Irreversible</Badge>        <Button variant="danger" onClick={onDelete}>          Delete workspace        </Button>        <Button variant="ghost" size="icon">          <Trash2 />        </Button>        <button className="rounded-[7px] bg-gray-100 px-3 text-sm">          Cancel        </button>        <p style={{ color: "#737373", marginTop: 6 }}>Owners only.</p>      </CardContent>    </Card>  )}

Add a danger-zone card to the workspace settings page

  1. Write app/settings/danger-zone.tsx +29 lines

The agent writes the card from what it learned in training.

Real output: the findings and fixes are what check_ui returns for this file against the demo design system, generated when this site was built. Try it on your own code

The problem

Your agent can't see your Storybook. TypeScript only catches part of it.

Ask for a settings card in a shadcn/ui project and you get bg-[#ef4444], p-[13px], a native <button> with hand-rolled classes, variant="danger" on a Button that only knows destructive, and an icon button nobody can name with a screen reader.

On the draft above, tsc reports 3 of the 11 problems: the invalid variant, the unknown prop and the missing member. It has no opinion on hex colors, off-scale spacing, native elements or accessible names. Review catches the rest, when someone has the time.

The draft, checked by each
In the drafttsccheck_ui
border-[#ef4444]no-hardcoded-colortsc misses itcheck_ui reports it
p-[13px]no-hardcoded-spacingtsc misses itcheck_ui reports it
<Card.Description>no-unknown-componenttsc reports itcheck_ui reports it
tone=no-unknown-proptsc reports itcheck_ui reports it
variant="danger"no-unknown-varianttsc reports itcheck_ui reports it
<Button size="icon">icon-button-accessible-nametsc misses itcheck_ui reports it
<button>prefer-design-system-componenttsc misses itcheck_ui reports it
rounded-[7px]no-hardcoded-radiustsc misses itcheck_ui reports it
bg-gray-100no-hardcoded-colortsc misses itcheck_ui reports it
color: "#737373"no-hardcoded-colortsc misses itcheck_ui reports it
marginTop: 6no-hardcoded-spacingtsc misses itcheck_ui reports it
Reported3/1111/11

Does it help?

The same tasks, with and without onsystem.

In the benchmark of 2026-10-12, design-system rule violations per run, as onsystem 0.5.0's own check counts them, went from 0.85 to 0.00 with onsystem's skill, MCP server and hook, with no measurable change in tsc pass rate or cost per run (240 runs per arm, 6 models, 3 providers, 5 repositories).

No onsystem → skill, MCP server and hook, all 6 models pooled, with 95% intervals.

onsystem 0.5.0 errors per run
0.85→0.00
difference −0.85 [−1.38, −0.40]; without onsystem [0.40, 1.38]
tsc passes
93%→92%
difference 0 points [−4, +3]
Cost per run
$0.0464→$0.0454
without onsystem [$0.0432, $0.0497]

The tables by arm and model, the blind labels, the method and how to reproduce it

On real codebases, with zero config

Run as is, with no config, on public apps: the counts the corpus snapshot records, rechecked on every pull request that changes the rules. These counts are not a judgement of the teams: hardcoded values and unlabeled icon buttons slip through review everywhere, and agents copy what they see.

How often it is wrong: the corpus runs check on 12 public repositories pinned by commit (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.

  • vercel/ai-chatbot c2f8235

    Found with zero config
    components.json → 23 components, 52 tokens
    check findings
    73 in app/ and components/: 41 raw colors, 19 native elements the design system wraps, 12 icon-only buttons without an accessible name, 1 arbitrary radius
  • midday 5158731, apps/dashboard

    Found with zero config
    workspace package @midday/ui → 79 components
    check findings
    1,340 in src/, including 98 icon-only buttons without an accessible name. Adopted with a baseline
  • shadcn/ui website 0132174

    Found with zero config
    custom ui alias → 68 components
    check findings
    124 in app/ and components/, mostly raw colors (105)

How it works

Reads your source. Checks every edit. Gates the pull request.

Static analysis from start to finish: no model calls, no API key, and it runs offline. One check of the demo file takes 2.4 ms, so it can run after every edit.

01

Reads your design system

One TypeScript program over your component files, with your tsconfig, so path aliases and dependency types resolve.

  • Props, with types, defaults and JSDoc
  • cva() and tv() variants, and the classes each applies
  • Parts: CardHeader next to Card, or Card.Header
  • The native element each component wraps
  • Tokens from CSS variables, Tailwind v4 @theme or a v3 config, and DTCG JSON
  • Docs and examples from Markdown next to the components

No config for a shadcn/ui components.json, an app whose components live in a workspace package (@acme/ui), or the design-system package itself. How it finds them.

02

Checks every edit and every pull request

In Claude Code, the plugin's hook runs these rules right after each file is written and hands the errors back for Claude to fix. In CI, check or the GitHub Action runs them on every pull request, and the ESLint plugin runs them wherever ESLint 9 or 10 runs.

  • no-hardcoded-colorerror
  • no-hardcoded-spacingwarn
  • no-hardcoded-radiuswarn
  • prefer-design-system-componenterror
  • no-unknown-componenterror
  • no-unknown-properror
  • no-unknown-varianterror
  • icon-button-accessible-nameerror

Any agent can run them itself as check_ui, which parses the code on its own, so it works on fragments the agent has not saved.

03

Answers the agent over MCP

  • list_components

    List design-system components

  • get_component

    Get a component contract

  • search_components

    Search components by intent

  • get_tokens

    Get design tokens

  • check_ui

    Check UI code against the design system

Plus ds://tokens and ds://components/{name} as resources, and a build-with-design-system prompt. Every tool is read-only.

What the agent sees: each tool's response on the demo design system

Alongside @shadcn/lint

Different layers. Run both.

@shadcn/lint is a linter: it polices the classes written against a component and the theme, in React, Svelte and Vue, on Tailwind v4. onsystem checks agent-written React against your design system at the edit and in CI, and hands the agent the fix.

What onsystem and @shadcn/lint each check
Checkonsystem@shadcn/lint
Raw colors in classes and inline styles (bg-[#ef4444])onsystem: yes@shadcn/lint: yes
Arbitrary values (p-[13px], rounded-[7px])onsystem: yes@shadcn/lint: yes
Native elements the design system wraps (<button> → <Button>)onsystem: yes@shadcn/lint: no
Components, props and variant values your design system lacks (<Card.Header>, tone, "danger")onsystem: yes@shadcn/lint: no
Icon-only buttons without an accessible nameonsystem: yes@shadcn/lint: no
Restyling a component with classes it should not takeonsystem: no@shadcn/lint: yes
Unknown and dynamic classesonsystem: no@shadcn/lint: yes
Per-component contracts you writeonsystem: no@shadcn/lint: yes
Each edit in Claude Code, and your components and tokens for the agent over MCPonsystem: yes@shadcn/lint: no
Tailwind v3, design-system packages, and apps that import one from a workspace packageonsystem: yes@shadcn/lint: no
Svelte and Vueonsystem: no@shadcn/lint: yes
Reads a shadcn/ui project through components.jsononsystem: yes@shadcn/lint: yes
Runs asESLint 9 and 10ESLint 9.30+, Oxlint

Works with

Your agent, your stack.

React only (.tsx and .jsx), with Node.js 20.19 or later. Styling is checked in Tailwind classes, style objects and color attributes, not in CSS-in-JS or CSS Modules. The full list of limits is in the docs.

Agents and editors

  • Claude Code
  • Cursor
  • VS Code
  • Claude Desktop
  • Codex CLI
  • GitHub Copilot CLI
  • Windsurf
  • JetBrains IDEs
  • Zed
  • Gemini CLI
  • Antigravity
  • Grok Build
  • Any stdio MCP client

Configs for each are in the setup guide. The same rules run in ESLint 9 and 10 with the ESLint plugin, and on pull requests with the GitHub Action.

Codebases

  • shadcn/ui
  • Radix
  • Base UI
  • React Aria Components
  • Tailwind v3 and v4
  • pnpm, npm, Yarn and Bun workspaces
  • Design-system packages
  • W3C DTCG tokens

Other layouts take a config file with a few globs.

Adopting it

An existing codebase fails only on new findings.

Record the findings already there in a baseline once (midday's dashboard has 1,340), and check fails only on new ones: rolling it out to a team.

Hold your agent to the design system you already have.

Run npx -y onsystem check . in your app to see what it finds, with no install and no config. If it gets something wrong on your codebase, an issue with the snippet is the most useful thing you can send.

Claude Code pluginhook, server, skill
/plugin marketplace add dgesteves/onsystem/plugin install onsystem@dgesteves
Any MCP client, over stdio
$ npx -y onsystem