onsystem 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -22
- package/dist/cli.js +629 -221
- package/dist/{config-lbfW91qB.d.ts → config-kYGiD5oW.d.ts} +15 -0
- package/dist/{design-system-A3pRX3Ka.js → design-system-Dmcv7eHR.js} +2641 -331
- package/dist/eslint-worker.d.ts +1 -1
- package/dist/eslint-worker.js +3 -5
- package/dist/eslint.js +66 -5
- package/dist/index.d.ts +35 -3
- package/dist/index.js +2 -2
- package/dist/{stdio-CEChNFLR.js → stdio-MTS6QAgo.js} +241 -9
- package/dist/{workspace-CHvUwgz9.js → workspace-CM1RyqZA.js} +1 -1
- package/package.json +9 -9
- package/schema.json +1 -1
package/README.md
CHANGED
|
@@ -1,24 +1,36 @@
|
|
|
1
1
|
# onsystem
|
|
2
2
|
|
|
3
|
-
**Keeps coding agents on your design system:**
|
|
3
|
+
**Keeps coding agents on your design system:** catches palette colors, native elements and APIs your system lacks, 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. Runs locally and works alongside [@shadcn/lint](https://github.com/shadcn-ui/lint).
|
|
4
4
|
|
|
5
5
|
Built for design-system and platform teams with a React design-system package; a shadcn/ui app is the zero-config demo. Formerly `@dgesteves/design-system-mcp` ([what changed](https://onsystem.vercel.app/docs/migrating)).
|
|
6
6
|
|
|
7
|
+
Using the GitHub Action? `uses: dgesteves/onsystem@v0` checks the lines a pull request changed: see [CI and baselines](https://onsystem.vercel.app/docs/ci).
|
|
8
|
+
|
|
7
9
|
[](https://github.com/dgesteves/onsystem/actions/workflows/ci.yml)
|
|
8
|
-
[](https://registry.modelcontextprotocol.io/?q=io.github.dgesteves%2Fonsystem)
|
|
10
|
+
[](https://www.npmjs.com/package/onsystem)
|
|
11
|
+
[](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.dgesteves%2Fonsystem/versions/latest)
|
|
11
12
|
[](https://cursor.directory/plugins/design-system-mcp)
|
|
12
|
-
[](LICENSE)
|
|
13
14
|
|
|
14
15
|
[](https://cursor.com/en/install-mcp?name=onsystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9uc3lzdGVtIiwiLS1yb290IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9Il19)
|
|
15
|
-
[](https://insiders.vscode.dev/redirect/mcp/install?name=onsystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22onsystem%22%2C%22--root%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D)
|
|
17
|
+
[](https://onsystem.vercel.app/docs/plugin)
|
|
18
|
+
[](https://github.com/marketplace/actions/onsystem-design-system-check)
|
|
19
|
+
|
|
20
|
+
**Also works with**
|
|
21
|
+
[](https://onsystem.vercel.app/docs/clients#codex-cli)
|
|
22
|
+
[](https://onsystem.vercel.app/docs/clients#gemini-cli)
|
|
23
|
+
[](https://onsystem.vercel.app/docs/clients#grok-build)
|
|
24
|
+
[](https://onsystem.vercel.app/docs/clients#github-copilot-cli)
|
|
25
|
+
[](https://onsystem.vercel.app/docs/clients#claude-desktop)
|
|
26
|
+
[](https://onsystem.vercel.app/docs/clients#windsurf-devin-desktop)
|
|
27
|
+
[](https://onsystem.vercel.app/docs/clients#jetbrains-ides-ai-assistant-and-junie)
|
|
28
|
+
[](https://onsystem.vercel.app/docs/clients#zed)
|
|
17
29
|
|
|
18
30
|
**Website and docs:** [onsystem.vercel.app](https://onsystem.vercel.app), with a [playground](https://onsystem.vercel.app/playground) that checks your own code.
|
|
19
31
|
|
|
20
32
|
<p align="center">
|
|
21
|
-
<a href="https://onsystem.vercel.app"><img src=".github/assets/demo.webp" width="100%" alt="On the website, an agent drafts a settings card, check_ui finds 11 problems with a fix each and the agent applies them. Then a real Claude Code session with the plugin, where Claude looks the components up before writing and check_ui passes. Last, the benchmark
|
|
33
|
+
<a href="https://onsystem.vercel.app"><img src=".github/assets/demo.webp" width="100%" alt="On the website, an agent drafts a settings card, check_ui finds 11 problems with a fix each and the agent applies them. Then a real Claude Code session with the plugin, where Claude looks the components up before writing and check_ui passes. Last, the benchmark."></a>
|
|
22
34
|
</p>
|
|
23
35
|
|
|
24
36
|
<sub>On the <a href="https://onsystem.vercel.app">website</a>, an agent drafts a settings card, <code>check_ui</code> finds 11 problems with a fix each, and the agent applies them. Then a real Claude Code session with the plugin: Claude looks the components up before writing, and <code>check_ui</code> passes. Last, the benchmark.</sub>
|
|
@@ -42,7 +54,7 @@ onsystem reads your components, `cva` and `tv` variants, parts and tokens from s
|
|
|
42
54
|
| `no-hardcoded-spacing` | warn | Arbitrary padding, margin and gap (`p-[13px]` → `p-3`) |
|
|
43
55
|
| `no-hardcoded-radius` | warn | Arbitrary radius (`rounded-[7px]` → `rounded-sm`) |
|
|
44
56
|
|
|
45
|
-
**How often it is wrong.** The [corpus](corpus) job runs `check` on 12 public repositories pinned by commit (Documenso, Dub, Cal.com, midday, Flowise and others,
|
|
57
|
+
**How often it is wrong.** The [corpus](corpus) job runs `check` on 12 public repositories pinned by commit (Documenso, Dub, Cal.com, midday, Flowise and others: 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](corpus/fp-sample-20261016) has each label with its reason, the labeller's notes and the script behind these numbers. Shipped code rarely invents components, props or variants, and without dependencies `no-unknown-prop` skips components whose props do not resolve: those three rules have 56 findings in the corpus, 55 of them in Flowise, an MUI app, and 3 in the sample, all right but too few for a rate of their own. The corpus's older labels, made by an AI reviewer who could see the finding and so not blind, fail the job when one of their true positives stops being reported or a fixed false positive comes back. Code installed from a shadcn registry, such as the chatbot's `components/ai-elements`, has no labels yet ([Code from shadcn registries](https://onsystem.vercel.app/docs/configuration#code-from-shadcn-registries)). The [rules reference](https://onsystem.vercel.app/rules) shows each rule on an example and how to [suppress a finding](https://onsystem.vercel.app/rules#suppressing-findings).
|
|
46
58
|
|
|
47
59
|
## Quickstart
|
|
48
60
|
|
|
@@ -54,9 +66,9 @@ npx -y onsystem check . # the same check the agent and CI run
|
|
|
54
66
|
npx -y onsystem init # write the config, and offer a baseline
|
|
55
67
|
```
|
|
56
68
|
|
|
57
|
-
At a [monorepo root](https://onsystem.vercel.app/docs/configuration#monorepo-roots), `inspect` lists every app and design-system package, and `check` checks each file by its own project's design system. In a [design-system package](https://onsystem.vercel.app/docs/design-system-packages), `init` sets it up for every app that depends on it, workspace or npm,
|
|
69
|
+
At a [monorepo root](https://onsystem.vercel.app/docs/configuration#monorepo-roots), `inspect` lists every app and design-system package, and `check` checks each file by its own project's design system. In a [design-system package](https://onsystem.vercel.app/docs/design-system-packages), `init` sets it up for every app that depends on it, with no config in the apps: as a workspace package, or installed from npm when it publishes its component sources (`init` checks its `files` list). From a package that publishes only compiled code, installed apps get the token rules but no component, prop, variant or native-element checks.
|
|
58
70
|
|
|
59
|
-
In a new create-next-app, the template page's hardcoded colors already make the first `check .` fail; `init` offers to record them as a baseline, so only new findings fail.
|
|
71
|
+
In a new create-next-app, the template page's hardcoded colors already make the first `check .` fail; `init` offers to record them as a baseline, so only new findings fail. Folders installed from a shadcn registry, such as `components/ai-elements`, are someone else's code: [Code from shadcn registries](https://onsystem.vercel.app/docs/configuration#code-from-shadcn-registries) says how to check them or leave them out.
|
|
60
72
|
|
|
61
73
|
**Claude Code.** The plugin brings the hook, the MCP server and a skill:
|
|
62
74
|
|
|
@@ -65,9 +77,9 @@ In a new create-next-app, the template page's hardcoded colors already make the
|
|
|
65
77
|
/plugin install onsystem@dgesteves
|
|
66
78
|
```
|
|
67
79
|
|
|
68
|
-
After each Write or Edit of a `.tsx` or `.jsx` file, the hook runs `onsystem check` on it. Errors go back to Claude as a blocking error with the fix, so Claude corrects the file before it moves on; warnings go as a note. It stays quiet in projects without a design system. [What it runs and touches](https://onsystem.vercel.app/docs/plugin).
|
|
80
|
+
After each Write or Edit of a `.tsx` or `.jsx` file, the hook runs `onsystem check` on it. Errors go back to Claude as a blocking error with the fix, so Claude corrects the file before it moves on; warnings go as a note. It stays quiet in projects without a design system. Codex installs the same plugin, and the hook checks the files its `apply_patch` changes. [What it runs and touches](https://onsystem.vercel.app/docs/plugin).
|
|
69
81
|
|
|
70
|
-
**Cursor or VS Code.** [](https://cursor.com/en/install-mcp?name=onsystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9uc3lzdGVtIiwiLS1yb290IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9Il19) [](https://cursor.com/en/install-mcp?name=onsystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9uc3lzdGVtIiwiLS1yb290IiwiJHt3b3Jrc3BhY2VGb2xkZXJ9Il19) [](https://insiders.vscode.dev/redirect/mcp/install?name=onsystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22onsystem%22%2C%22--root%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D), or commit the [config](https://onsystem.vercel.app/docs/clients#cursor-and-vs-code). The agent gets the tools and runs `check_ui` on what it writes.
|
|
71
83
|
|
|
72
84
|
**Other agents.** `npx skills add dgesteves/onsystem` adds the skill to any agent with Agent Skills, and there are [plugins for Codex, GitHub Copilot CLI, VS Code and Cursor](https://onsystem.vercel.app/docs/clients#plugins-for-other-agents).
|
|
73
85
|
|
|
@@ -86,22 +98,17 @@ npx onsystem check . --update-baseline # writes onsystem.baseline.json: commit
|
|
|
86
98
|
|
|
87
99
|
Findings show up as annotations on the pull request, and `--require-design-system` fails the job when the design system is no longer found. [CI and baselines](https://onsystem.vercel.app/docs/ci) has the whole workflow. The GitHub Action, `uses: dgesteves/onsystem@v0`, annotates only the lines a pull request changed: [make it a required check on agent pull requests](https://onsystem.vercel.app/docs/required-check).
|
|
88
100
|
|
|
89
|
-
**ESLint.** The same rules for ESLint 9 and 10: add `onsystem.configs.recommended` from `onsystem/eslint` to `eslint.config.mjs` ([ESLint plugin](https://onsystem.vercel.app/docs/eslint), with @shadcn/lint).
|
|
101
|
+
**ESLint.** The same rules for ESLint 8.57, 9 and 10: add `onsystem.configs.recommended` from `onsystem/eslint` to `eslint.config.mjs` ([ESLint plugin](https://onsystem.vercel.app/docs/eslint), with @shadcn/lint).
|
|
90
102
|
|
|
91
103
|
## Works with @shadcn/lint
|
|
92
104
|
|
|
93
|
-
[@shadcn/lint](https://github.com/shadcn-ui/lint) checks the Tailwind classes written against a component and the theme (restyling, raw colors, arbitrary and unknown classes) as ESLint or Oxlint rules on Tailwind v4. onsystem checks that the components, props and variant values exist
|
|
105
|
+
[@shadcn/lint](https://github.com/shadcn-ui/lint) checks the Tailwind classes written against a component and the theme (restyling, raw colors, arbitrary and unknown classes) as ESLint or Oxlint rules on Tailwind v4. onsystem checks that the components, props and variant values exist and flags native elements and unnamed icon buttons, on Tailwind v3 or v4. Its MCP server shows the agent your components and tokens before it writes, and in Claude Code its hook checks every edit. Run both. Benchmark v2 also scores every output with @shadcn/lint: see [the independent scorer's table](bench/v2/results/standard/results.md#independent-scorer-shadcnlint).
|
|
94
106
|
|
|
95
107
|
## Does it help?
|
|
96
108
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
| Model | Clean without | Clean with the plugin | Design-system errors | Cost |
|
|
100
|
-
| ---------------- | ------------: | --------------------: | -------------------: | ---: |
|
|
101
|
-
| Claude Haiku 4.5 | 6 / 10 | **10 / 10** | 13 → 0 | −11% |
|
|
102
|
-
| Claude Opus 5 | 8 / 10 | **10 / 10** | 5 → 0 | +7% |
|
|
109
|
+
[Benchmark v2](bench/v2) gave 6 models from 3 providers (Anthropic, OpenAI and Google) 20 single-file UI tasks in 5 open-source repositories, without onsystem, with its skill, MCP server or hook, and with all three: 1,200 runs, 240 per arm. Counted by onsystem 0.5.0's own check, design-system errors per run went from 0.85 without onsystem to 0.00 with all three, with no measurable change in the `tsc` pass rate (93% → 92%).
|
|
103
110
|
|
|
104
|
-
|
|
111
|
+
That count is onsystem's own, and the MCP server and the hook show the agent the same errors to fix. In tasks that ask for a green status label in a design system with no success token, agents with onsystem often used `chart-*` tokens, which it counts as clean. The blind labels by an AI reviewer, 12 files per arm, are too few to confirm the count either way, and every violation they found with the hook or all three is a palette color in Dub, whose tokens 0.5.0 did not read. The [benchmark page](https://onsystem.vercel.app/benchmark) has every table, and [bench/v2](bench/v2) the method, the per-run data and every generated file.
|
|
105
112
|
|
|
106
113
|
## Docs
|
|
107
114
|
|