What Maddox Engine actually checks, and how to run it

Getting started

No account needed to try it. Point the CLI at your source and the CSS file holding your @theme block:

npx maddox-engine ./src ./src/app/globals.css

That's the whole install — no SDK, no build-step changes, nothing to configure beyond the path to your own tokens. It prints a text report to the terminal. To upload results to a dashboard account (scan history, drift trends over time), set MADDOX_API_KEY from your dashboard first — that step is optional, the scan itself never requires an account.

No tokens handy yet? Try the public quick-scan first — paste a URL and it'll detect your real tokens from the page's own deployed CSS, no local checkout required.

How it works

Your design system has a rulebook: a real color is #2563EB, a real body size is 16px. Nothing stops a hardcoded #2563ec from creeping into a file six months later — it renders fine, nobody notices in review. Maddox scans your source code (or a live URL) and diffs every hardcoded color, font-size, and motion value against that rulebook, then tells you exactly which ones drifted and by how much.

Every checked value lands in exactly one of three buckets:

This is a source-code and rendered-output scanner, not a pixel/DOM visual-regression tool. It checks the values a page actually ships against the tokens that are supposed to govern them, so it catches drift that renders identically to a real token (zero visual diff) but was never written as one.

Ground truth sources

Maddox reads your real tokens from one or more of these. When more than one is given, precedence runs Figma Variables > Tokens Studio > @theme CSS — Figma sits earliest in a real design-to-code pipeline, so a later step is more likely to be the stale one.

Running a scan

Source scan — checks your local files:

npx maddox-engine ./src ./src/app/globals.css --project my-app --fail-below 80

Live URL scan — checks what's actually deployed, not what's in the repo:

npx maddox-engine - ./src/app/globals.css --url https://example.com

--url fetches the page's rendered HTML plus every same-origin <link rel="stylesheet">. A stale CDN cache, a build step that silently drops a token, or a config typo can all make a deployed page diverge from what the source says — only a live-URL scan catches that. Third-party stylesheets (a different origin) are never fetched, so findings only ever point at code the project actually owns.

Two things don't carry over to --url mode:

• Motion — real motion libraries animate via the JS runtime, not static HTML/CSS literals, so motion findings are dropped from every URL scan rather than surfaced as noise.
• Component states — state-completeness checks whether an identifier is referenced in source; a fetched, already-rendered page has no source to check.

Suggested fixes

Every near-miss finding with a resolved nearest token gets a suggestion — the concrete replacement text (var(--token-name) for a CSS value, or motionTokens.path.to.value for a motion token). An unrecognized value with no close match, and a missing-state finding, never get a suggestion — there's no safe mechanical fix for either.

By default this is advisory text for you to apply yourself. Pass --apply-fixes to write it straight into the file:

npx maddox-engine ./src ./src/app/globals.css --apply-fixes

Scoped deliberately narrow:

• Only color/font-size/spacing suggestions are ever applied. Motion suggestions assume a motionTokens import exists in that file's scope — that can't be verified per-file, so applying it blind could silently break the build. Motion stays advisory-only.
• If a finding's line no longer contains its reported value, it's skipped rather than guessed at.
• Not available with --url — a fetched page has no local file to write to.
• This is a real edit to your working tree — review the diff before committing.

CI / GitHub Action

omrdev1/maddox-cli runs a scan, posts the markdown report as a PR comment (updating the same comment on later pushes rather than piling up new ones), and optionally fails the build via fail-below.

- uses: actions/checkout@v4
- uses: omrdev1/maddox-cli@main
  with:
    target-dir: src
    theme-css: src/app/globals.css
    github-token: ${{ secrets.GITHUB_TOKEN }}
    fail-below: "80"

Pin @main to a specific commit SHA if you want reproducible CI runs immune to changes on this branch.

CLI reference

npx maddox-engine <target-source-dir> <path-to-globals.css-with-@theme-block> [options]