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 .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.
<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"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@dgestevesWith your workspace as its root. The config to commit
With your workspace as its root. The config to commit
The MCP server and the skill, from the same marketplace as the Claude Code plugin. Other agents
codex plugin marketplace add dgesteves/onsystemcodex plugin add onsystem@dgestevesAny client that starts servers over stdio. A config for each
$ npx -y onsystemChecks the lines each pull request changes, and fails on errors. The workflow
- uses: dgesteves/onsystem@v0- 2.4 ms to check the demo file. No model calls.
- Checked nightly on 12 public repos, pinned by commit.
- shadcn/ui, your own package, or MUI.
- MCP Registry · GitHub Marketplace
- Benchmark: 1,200 agent runs, 6 models
~/acme-app — agent session
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
- Write app/settings/danger-zone.tsx +29 lines
- onsystem · check_ui(path: "app/settings/danger-zone.tsx")
8 errors·3 warningseach with a rule id, a location and a fix
- 9:22errorno-hardcoded-colorborder-[#ef4444] → border-destructive
- 9:39warnno-hardcoded-spacingp-[13px] → p-3
- 12:10errorno-unknown-component<Card.Description> → <CardDescription>
- 15:16errorno-unknown-proptone= → variant=
- 16:25errorno-unknown-variantvariant="danger" → variant="destructive"
- 19:10erroricon-button-accessible-name<Button size="icon"> → aria-label="Delete"
- 22:10errorprefer-design-system-component<button> → <Button>
- 22:28warnno-hardcoded-radiusrounded-[7px] → rounded-sm
- 22:42errorno-hardcoded-colorbg-gray-100 → bg-muted
- 25:29errorno-hardcoded-colorcolor: "#737373" → text-muted-foreground
- 25:50warnno-hardcoded-spacingmarginTop: 6 → mt-1.5
- Edit app/settings/danger-zone.tsx resolved all 11 findings
- check_ui No design-system problems
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.
| In the draft | tsc | check_ui |
|---|---|---|
| border-[#ef4444]no-hardcoded-color | tsc misses it | check_ui reports it |
| p-[13px]no-hardcoded-spacing | tsc misses it | check_ui reports it |
| <Card.Description>no-unknown-component | tsc reports it | check_ui reports it |
| tone=no-unknown-prop | tsc reports it | check_ui reports it |
| variant="danger"no-unknown-variant | tsc reports it | check_ui reports it |
| <Button size="icon">icon-button-accessible-name | tsc misses it | check_ui reports it |
| <button>prefer-design-system-component | tsc misses it | check_ui reports it |
| rounded-[7px]no-hardcoded-radius | tsc misses it | check_ui reports it |
| bg-gray-100no-hardcoded-color | tsc misses it | check_ui reports it |
| color: "#737373"no-hardcoded-color | tsc misses it | check_ui reports it |
| marginTop: 6no-hardcoded-spacing | tsc misses it | check_ui reports it |
| Reported | 3/11 | 11/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]
tscpasses- 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 tokenscheckfindings- 73 in
app/andcomponents/: 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 checkfindings- 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
uialias → 68 components checkfindings- 124 in
app/andcomponents/, 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()andtv()variants, and the classes each applies- Parts:
CardHeadernext toCard, orCard.Header - The native element each component wraps
- Tokens from CSS variables, Tailwind v4
@themeor 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.
| Check | onsystem | @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 name | onsystem: yes | @shadcn/lint: no |
| Restyling a component with classes it should not take | onsystem: no | @shadcn/lint: yes |
| Unknown and dynamic classes | onsystem: no | @shadcn/lint: yes |
| Per-component contracts you write | onsystem: no | @shadcn/lint: yes |
| Each edit in Claude Code, and your components and tokens for the agent over MCP | onsystem: yes | @shadcn/lint: no |
| Tailwind v3, design-system packages, and apps that import one from a workspace package | onsystem: yes | @shadcn/lint: no |
| Svelte and Vue | onsystem: no | @shadcn/lint: yes |
Reads a shadcn/ui project through components.json | onsystem: yes | @shadcn/lint: yes |
| Runs as | ESLint 9 and 10 | ESLint 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.
/plugin marketplace add dgesteves/onsystem/plugin install onsystem@dgesteves$ npx -y onsystem