pbakaus_impeccable/site/content/reference/detector.md

title, tagline, description, section, order

title	tagline	description	section	order
Detector CLI	Run Impeccable's deterministic design checks without an AI harness.	Use npx impeccable detect on files, directories, stdin, and URLs; understand findings, exit codes, ignores, and design-system-aware checks.	automation	1

npx impeccable detect runs Impeccable's deterministic design checks directly from the terminal. Use it when you want a fast signal without asking an AI command to review the work.

Fast path

Scan the source folder:

npx impeccable detect src/

Scan one file:

npx impeccable detect src/components/Card.tsx

Scan a rendered page:

npx impeccable detect https://example.com

Use JSON when another script or CI job needs to read the result:

npx impeccable detect --json src/

What it checks

The detector looks for design and implementation patterns that are usually visible to users: contrast problems, typography drift, layout overflow, generic AI-design tells, brittle motion, and design-system violations when DESIGN.md exists.

Directories are walked for design-relevant files. HTML files include linked local CSS. Framework files such as JSX, TSX, Vue, Svelte, Astro, and CSS modules get source-text checks. URL targets use a browser and inspect the rendered page.

How to read results

Plain output groups findings by file and prints the rule id, snippet, and explanation. Exit codes are:

Code	Meaning
0	No findings.
2	Findings were detected.
1	The command failed.

That makes CI usage straightforward: fail the job on 2, then decide whether to fix the issue or add a narrow ignore.

DESIGN.md awareness

When a local DESIGN.md exists, detect loads it by default and enables design-system checks for fonts, literal colors, and border radii. The generated .impeccable/design.json sidecar gives those checks richer token and ramp data.

If the design file is stale, refresh it:

/impeccable document

If you need one scan without design-system checks:

npx impeccable detect --no-design-system src/

Managing intentional findings

Detector ignores are shared with the design hook:

npx impeccable ignores list
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
npx impeccable ignores add-file "src/legacy/**"

Use Config and ignores for the full ignore workflow.

Details when the default path is not enough

Scan stdin

If you pipe text into the command with no target, it scans stdin:

cat component.css | npx impeccable detect

Project config and raw scans

By default, detect reads .impeccable/config.json and .impeccable/config.local.json.

It respects detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues, and detector.designSystem.enabled.

It does not respect hook.enabled; manual scans still run when the automatic hook is disabled.

Use --no-config only when you want a raw detector run with no project config, no detector ignores, and no DESIGN.md context.

Provider-specific checks

Some rules are provider-specific and opt in:

npx impeccable detect --gpt src/
npx impeccable detect --gemini src/

Leave them off for normal project quality checks. Turn them on when you specifically want to catch model-family fingerprints.

Where the detector fits

The same detector also powers the design hook, /impeccable audit, the public slop catalog, the browser extension, and the local detector lab.

Use Design hooks when you want findings inside the agent flow. Use detect when you want a direct terminal signal.