Analyzer
npx cia analyze audits a project’s stylesheets against the real, installed css-is-awesome API — not a snapshot or a guess — and prints a graded, categorized report with a suggested fix on every finding. Zero dependencies, filesystem only, same philosophy as the MCP server.
Run it
npx cia analyze # current directory, graded report npx cia analyze src/styles # a specific path npx cia analyze --json # machine-readable, for CI tooling npx cia analyze --strict # also exit 1 on warnings (default: errors only) npx cia analyze --verbose # flat per-file listing instead of the graded view
The health score
health = 100 − errors×10 − warnings×2 − info×1, floored at 0. It’s a within-version trend, not a cross-version constant — adding a rule can move a clean-ish project’s number on upgrade, which is why new rules land mostly at warn/info weight rather than error.
Rules
| Rule | Level | Category | What it catches |
|---|---|---|---|
unknown-symbol | ✗ error | API | A cia.* call that doesn't resolve — a typo or a symbol removed since your version. |
space-scale | ✗ error | Spacing | space(n) outside 1–9 — the numbered scale, so it emits a unitless number and the browser drops the declaration. |
off-contract-token | ⚠ warn | Contract | A var(--token) that's a near-miss of a real contract token — likely a typo. Your own custom tokens are left alone. |
off-scale-length | ⚠ warn | Spacing | A literal border-radius/padding/margin/gap value close to a scale step — probably meant to be that token. |
hard-coded-color | ⚠ warn | Color | A literal hex color outside a var() fallback or an @media print block — should come from a token. |
bem | ⚠ warn | Naming | A __ or -- class-name chain — BEM is forbidden in cia projects; use a semantic single-class name. |
hand-written-areas | ℹ info | Layout | A hand-written grid-template-areas — the layout mixins (page-layout / layout / area) own the maps. |
missing-focus-visible | ℹ info | Accessibility | Interactive :hover/:active styling with no :focus-visible or focus-ring anywhere in the file. |
error fails the build; warn fails only under --strict; info never fails it — it’s a hint, not a gate.
A note on off-scale-length
This rule suggests the nearest named step (e.g. --radius-md), not an exact value — themes are free to set their own numbers for every step (Terminal sets every --radius-* to 0, deliberately), so the suggestion is a hint toward using a token at all, not a claim about what your active theme’s pixel value actually is. A literal 0 is never flagged — it’s unambiguous.
Flags
| Flag | Effect |
|---|---|
--json | Machine-readable report: counts, health, and results with category and suggestion on every finding (additive fields). |
--verbose | The flat per-file listing instead of the graded, categorized report. |
--strict | Exit 1 on warnings too (default: only error-level findings fail the build). |
--namespace <ns> | Extra namespace(s) to treat as cia, comma-separated — for when @use 'css-is-awesome' is aliased through an intermediate file the auto-detector can’t see through. |
See it work
npx cia add <recipe> copies a pattern from the recipes book into a project so you own it; npx cia analyze is the health check that keeps the result honest as the project grows. Run npx cia --help for every verb, or read the MCP server page for the AI-agent side of the same API.