Config and ignores | Impeccable

Impeccable stores runtime settings under .impeccable/. Most users do not need to hand-edit those files. Use the CLI when you want to record a confirmed exception.

Use config for:

detector ignores shared by npx impeccable detect and the design hook;
private local ignores that should not be committed;
hook lifecycle settings such as enabled, quiet mode, and audit logging.

Use PRODUCT.md and DESIGN.md for product and design intent. See Design Context.

The usual path

List the current ignores:

npx impeccable ignores list

Add the narrowest exception that matches the real reason:

npx impeccable ignores add-value design-system-color "#ff00aa" --reason "Campaign accent"
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-rule side-tab

Remove an exception when the underlying code is fixed:

npx impeccable ignores remove-value design-system-color "#ff00aa"

The same detector config is used by the CLI and the hook, so an ignore behaves consistently in both places.

Shared or local

Default ignores go into .impeccable/config.json. Commit them when they represent team intent: a legacy folder, a confirmed brand exception, or a project-wide rule decision.

Use --local for private work:

npx impeccable ignores add-file "src/private-experiment/**" --local

Local settings go into .impeccable/config.local.json, which Impeccable keeps out of git.

Value ignores

Prefer value ignores when a rule reports a specific value:

npx impeccable ignores add-value overused-font Inter --reason "Brand font"

Fonts, colors, radii, and motion values should usually be suppressed by value, not by whole rule. That keeps the rule useful everywhere else.

Wildcard value ignores are allowed only when scoped to a file:

npx impeccable ignores add-value design-system-color "*" --file "src/demo.css"

That keeps one intentionally experimental file from teaching the whole project that every undocumented color is acceptable.

Inline ignore comments

Config ignores live in .impeccable/config.json, which is the right home for repo-wide policy. They do not follow a file out of the repo, though. When a waiver belongs to one file and needs to travel with it (a generated or exported standalone document, an emailed HTML file, a snippet scanned out of context), put the waiver in the file itself:

<!-- impeccable-disable overused-font: exported brand doc, font is first-party -->

The directive is comment-syntax-agnostic, so the same marker works in //, /* */, , #, and {/* */} comments across HTML, CSS, JSX, TSX, Vue, and Svelte. Three scopes are available:

/* impeccable-disable overused-font */            /* whole file */
.brand { font-family: Inter }  /* impeccable-disable-line overused-font */
/* impeccable-disable-next-line bounce-easing */

List one or more rule ids, comma-separated, or omit them (or use *) for every rule. A reason after : or -- is optional and recommended; it is for the diff, and the scanner discards it. Like config ignores, a matched directive suppresses the finding.

Static HTML findings have no line number, so only whole-file impeccable-disable applies to them. That is the standalone-document case this exists for. The line-scoped forms apply to CSS, JSX, TSX, Vue, and Svelte, where findings carry a line.

Inline directives apply by default. --no-inline-ignores turns them off for one run while keeping config ignores; --no-config turns off config and inline ignores together.

Details when the default path is not enough

What the config file looks like

The shared config lives at .impeccable/config.json. A typical file looks like this:

{
  "detector": {
    "ignoreRules": [],
    "ignoreFiles": [],
    "ignoreValues": [],
    "designSystem": {
      "enabled": true
    }
  },
  "hook": {
    "enabled": true,
    "quiet": false,
    "auditLog": ".impeccable/hook.ndjson"
  }
}

The detector section is shared by manual scans and hooks. The hook section only controls automatic hook execution and hook output.

Disable design-system checks

Design-aware rules run when DESIGN.md exists. Disable them for the project only when the design file is intentionally not authoritative yet:

{
  "detector": {
    "designSystem": {
      "enabled": false
    }
  }
}

For one manual run, keep config but skip the design-system rules:

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

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

Hook runtime settings

Use /impeccable hooks for normal lifecycle changes:

/impeccable hooks status
/impeccable hooks on
/impeccable hooks off

hook.quiet: true suppresses clean and pending acknowledgements while still surfacing new findings.

hook.auditLog writes one NDJSON line per hook invocation for debugging. Leave it off during normal work.

Environment variables still override config for one shell: IMPECCABLE_HOOK_DISABLED, IMPECCABLE_HOOK_QUIET, and IMPECCABLE_HOOK_LOG.