Skip to content
onsystemv0.12.1

Gate PRs

CI and baselines

The check that runs after each edit in Claude Code also gates every pull request, whoever or whatever wrote it. onsystem check runs the same rules as check_ui and exits 1 on errors (or on more than --max-warnings warnings). It skips the design system's own component files, the ones components matches: they implement the scale and the primitives the rules enforce, so a fresh shadcn/ui project's p-[3px] is not a finding. --include-design-system, or "includeDesignSystem": true in the config, lints them too.

In folders and globs, check also leaves out tests and stories (*.test.tsx, *.spec.tsx, *.stories.tsx, and whatever is in __tests__, __stories__ and __mocks__ folders; --include-tests checks them), what the config's exclude adds to them (exclude), and what git ignores (through git check-ignore, so nested .gitignore files count); a file named outright is always checked. Only JS and TS files are (.tsx, .jsx, .ts, .js and their .mts, .cts, .mjs and .cjs forms): the CSS, Markdown and JSON that check $(git diff --name-only) names or check "**/*" matches are skipped, as check_ui refuses them. A file that renders an image or an email is not checked, since tokens and classes don't apply there: one that imports next/og, @vercel/og, satori or @react-email/*, a Next.js opengraph-image, twitter-image, icon or apple-icon route, or a file in an og folder. The summary line counts what was left out. Code that npx shadcn add copied into the folder of a registry components.json names is skipped like components/ui; other registry code is checked as your own until the config sets it apart: code from shadcn registries.

A folder stands for the .tsx and .jsx files in it. A JavaScript app can write its JSX in .js files (Next.js's JavaScript template has app/page.js): check names those it left out and gives the command that checks them, such as check . "**/*.js". A .js file over 512 KB or named *.min.js is taken for a bundle and not looked at. With the GitHub Action, list the glob in paths without quotes, paths: . **/*.js: the action passes each path as it is, with no shell.

Pin it as a dev dependency, so CI, the plugin's hook and everyone on the team run the same version:

npm install --save-dev onsystem

A GitHub Actions job, .github/workflows/onsystem.yml:

.github/workflows/onsystem.yml
name: Design systemon: pull_requestjobs:  onsystem:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: actions/setup-node@v7        with:          node-version: 24          cache: npm      - run: npm ci      - run: npx onsystem check . --format github --require-design-system

Or use the GitHub Action, uses: dgesteves/onsystem@v0, which runs the same check, honours the baseline and reports only the lines a pull request changed: Make it a required check on agent pull requests has the workflow and how to require it. The action runs the onsystem the project installed, in working-directory or the nearest folder above it up to the repository root, so the lockfile decides the version there too, and the log says so when that is not the action's own version. Without an install it runs npx onsystem@<the action's version>. Upgrade onsystem in a pull request of its own: findings a new version adds show up there, where check . --update-baseline can accept them.

Install the dependencies first: without them, the props of components that wrap a library (Radix, React Aria) are unknown, and no-unknown-prop skips those components (troubleshooting). --format github prints workflow commands, so findings show up as annotations on the pull request; their paths are relative to the repository root, so a job that runs in a folder (working-directory: apps/web) annotates the right files. --format json prints the raw results, and --format sarif a SARIF log for code scanning. A run that fails on more than --max-warnings warnings says so: in an error annotation with --format github, and on stderr with --format json and --format sarif, so stdout still parses. From a monorepo root, check . checks each file against its own project's design system and keeps one baseline at the root; there, --require-design-system fails only when no workspace package has components and color tokens (or a component library such as MUI), so a job per app (working-directory: apps/web) is the stricter gate.

When no components or no color tokens are found, check and check_ui say which rules could not run and link to the configuration docs, so a clean result is not mistaken for a checked one. In CI, --require-design-system turns that into a failure (exit code 2), for when the design system moves and the globs stop matching. It also fails when the folders and globs it is given leave no file to check, as in a JavaScript app whose pages are .js files, in a design-system package whose files are all its own components, or with a glob that matches only styles. Files named outright that are not JS or TS leave nothing to check without failing: a pull request that changes only styles has no UI code to check. An app whose components come from a published library (MUI) has a design system even when its theme's colors cannot be read, as with a palette from Sass variables: the check runs and says that no-hardcoded-color did not.

check and check_ui also say when the dependencies are not installed (no node_modules), since no-unknown-prop then skips the components whose props come from them, and plain inspect says it on stderr; --require-design-system does not fail on it. When a project without components of its own depends on a component library onsystem does not read yet (Chakra UI, Mantine, HeroUI, Radix Themes or Ant Design), they say that the library is not read, and inspect lists it on its library line.

--format sarif prints a SARIF 2.1.0 log: each rule with its description and a link to its entry in the rules catalog, and each finding with its level, message and location. Paths are relative to the repository root, wherever check runs from (the git top-level, or GITHUB_WORKSPACE where git is missing), and each finding carries a fingerprint built like a baseline entry (file, rule and the offending text), so an alert keeps its identity when the lines above it move. Findings in the baseline are left out. Upload it to GitHub code scanning, which shows the findings as alerts and, on a pull request, on the lines it changed:

YAML
name: Design systemon:  pull_request:  push:    branches: [main]jobs:  onsystem:    runs-on: ubuntu-latest    permissions:      contents: read      security-events: write    steps:      - uses: actions/checkout@v7      - uses: actions/setup-node@v7        with:          node-version: 24          cache: npm      - run: npm ci      - run: npx onsystem check . --format sarif --require-design-system > onsystem.sarif || test $? -eq 1      - uses: github/codeql-action/upload-sarif@v4        with:          sarif_file: onsystem.sarif          category: onsystem

|| test $? -eq 1 lets exit code 1 through: there are findings, and they are uploaded for code scanning to judge, through its own check on the pull request. Exit code 2 (no design system found, a broken config, a bad option) still fails the job, rather than uploading an empty log that passes. Code scanning is free for public repositories; private ones need GitHub Code Security.

An established app can start with hundreds of findings (midday's dashboard has 1,340). npx onsystem init offers to record them right after it writes the config (--yes does it without asking). Or record them yourself, once, and commit the file:

Shell
npx -y onsystem check src --update-baseline# Baseline: 1,340 findings in 272 files → onsystem.baseline.json

From then on, check reads onsystem.baseline.json from the root whenever it exists and fails only on new findings: No new problems in 569 files (1,340 in the baseline). Entries are keyed by file, rule and the offending text with a count, not by line, so edits elsewhere in a file do not invalidate them, while a second bg-[#f7f7f7] where the baseline accepts one is reported. When the GitHub Action checks the lines a pull request changed, it tells check which they are, and the baseline accepts the findings on the other lines first: a copy of a line it accepts is reported where it was added, not on the line that was there before. A file renamed or moved (git mv) keeps its entries: when a checked file has none of its own, and at least half of its findings match the entries of a file that no longer exists, and half of those entries match its findings, check accepts them in that file and says so, naming both files. That file need not be new: when a file with entries is deleted and its code pasted into a page that had none, the page takes them over, so the findings still count once. Until --prune-baseline records the new path, a copy of the file added later matches the old entries too, and one of the two takes them: the GitHub Action gives them to the file a pull request did not change and reports the copy, on the lines it added. check alone, like the Action with only-changed-lines: false, does not know what changed: after the file whose findings match the old entries most closely, it prefers a file that kept the old name (a folder moved), then one in the old folder (a file renamed), then goes by path order, so it can name the original rather than the copy, with the same count. So run check . --prune-baseline in the pull request that renames or moves the file. When findings get fixed, or files with entries are deleted from the folders it checks, check says so and prints the command that drops them, check src --prune-baseline, which locks in the progress: it only removes entries, and moves those of a moved file to its new path, while --update-baseline would also accept any new finding. Entries of a rule you turn off are kept rather than reported as fixed, a malformed baseline (a bad merge, say) is an error rather than something to overwrite, and paths are matched by their real spelling, so APP/ on macOS or a linked checkout finds the same entries. --ignore-baseline shows everything, and --baseline <file> uses another path, creating its folder; the commands check prints repeat it, with --root, --config and the other options that decide what is found. The baseline applies to the CLI only: check_ui still shows an agent every finding in the file it is editing.

The baseline also records the onsystem version that wrote it and the rules that ran. When a rule that did not run then reports findings, as when an upgrade finds tokens an older version missed, check says they are new to the baseline rather than to the code, and how many other new findings --update-baseline would accept with them. A baseline written before these fields existed is read as before, without that line, until an update from the root that checks every file it lists, such as check . --update-baseline, records them: an update of one folder cannot tell which rules ran over the rest. Give the baseline to code owners (CODEOWNERS), so that a pull request that accepts findings by rewriting it needs their review.

Hundreds of findings scroll by faster than they can be read. A run with 50 findings or more ends with what they add up to: the count per rule, and the Tailwind palette classes it found most, each with the token to use, marked (nearest token) when that token is another color, which reads as a plan for moving to the tokens:

Output
By rule: no-hardcoded-color 48, prefer-design-system-component 12.Tailwind palette classes: 48 in 12 files. The most common, with the token to use:  12× border-neutral-200 → border-border  12× hover:border-neutral-200 → hover:border-border  12× text-neutral-500 → text-muted-foreground  12× text-neutral-800 → text-primary (nearest token)

--format json, sarif and github print the findings alone.