Configuration & ignores

Use config to save the build workflow, record intentional detector exceptions, and adjust how checks run. You can ask Impeccable to change the workflow default; detector exceptions can be managed through the CLI.

Settings live under .impeccable/. Keep the product’s purpose in PRODUCT.md and its visual decisions in DESIGN.md; see Context files.

Choose a build workflow

Set buildPath to comp for mockup first (comp-led) or code for build directly (code-led):

{
  "buildPath": "comp"
}

Merge this setting into your existing .impeccable/config.json; keep its other settings. Use .impeccable/config.local.json for a developer-specific override of the team default.

You can also ask Impeccable to change the default in plain language. The picker’s switch changes the current session only. With no saved preference, mockup first is the default when image generation is available; without it, Impeccable uses code-led regardless of the saved preference.

Compare the workflows or enable image generation. An API key belongs in the agent’s environment, never in these configuration files.

Record a specific exception

Suppose Inter is your confirmed brand font. Ignore that value while keeping the font rule active for everything else:

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

List the current exceptions, or remove this one later:

npx impeccable ignores list
npx impeccable ignores remove-value overused-font Inter

Manual scans and hooks use the same ignores. Fix a real issue; use an exception when the reported choice is intentional.

Limit the scope

For one rule in one file, use a file-scoped value ignore:

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

Here, "*" permits any color in that file. Other checks still run, and colors elsewhere are still checked. A wildcard value requires a file scope.

Exclude whole files or rules

Use a file exclusion when the entire file is outside design review, such as a deliberate bad-design fixture:

npx impeccable ignores add-file "tests/fixtures/bad-design/**"

This suppresses every rule for matching files, including future rules. To suppress one rule across the project:

npx impeccable ignores add-rule side-tab

For overused-font, whole-rule suppression also requires --all-values. Prefer a specific font exception when that is all you need.

Use remove-file or remove-rule with the same argument to reverse these choices. ignores clear removes all ignores from the selected config.

Shared by default: commands write to .impeccable/config.json. Commit this file for team decisions, such as a brand exception.
Private with --local: commands write to .impeccable/config.local.json. Impeccable excludes this file from git.

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

Use the same scope when removing an exception. Add --all to a remove or clear command to affect both shared and local config.

Inline ignore comments

If an exception needs to travel with a file outside the repository, put it in a comment:

<!-- impeccable-disable overused-font: exported brand document -->

Three forms are available:

Marker	Scope
`impeccable-disable`	Whole file
`impeccable-disable-line`	Current line
`impeccable-disable-next-line`	Next line

Static HTML findings have no line number, so use the whole-file form for them. Line scopes apply to findings with line numbers, such as source checks in CSS and JSX.

Comment syntax and bypassing inline ignores

Use the marker inside the file’s usual comment syntax: HTML, CSS, JavaScript, JSX, or another supported source format. Follow it with a rule ID or comma-separated IDs. Omitting the IDs, or using *, suppresses all rules in that scope.

A reason after : or -- helps someone reviewing the code; the scanner discards the reason.

/* impeccable-disable-next-line overused-font: brand font */
.brand { font-family: Inter; }

detect --no-inline-ignores bypasses these comments but keeps config ignores. detect --no-config bypasses both, along with project settings and local design-system context.

Server-side templates

Add extensions when your UI uses Blade, ERB, Twig, or another template format:

{
  "detector": {
    "extensions": [
      { "ext": ".blade.php", "engine": "html" },
      { "ext": ".html.erb", "engine": "html" }
    ]
  }
}

Merge this into .impeccable/config.json. Extensions match the end of a filename, including double extensions. html is the default analyzer; use text for JS-, TS-, or CSS-like source. Custom entries add to the built-in types used by the detector and hooks.

Project boundaries

Impeccable can discover nested projects from package.json workspaces, pnpm-workspace.yaml, or lerna.json. If your design boundaries differ, declare them with projectRoots:

{
  "projectRoots": ["docs/design/skins/*"]
}

Each matched folder can have its own PRODUCT.md and DESIGN.md and appear in the app picker. Missing context falls back to the repository root, separately for each file.

Pattern precedence and private roots

Patterns are relative to the repository root and support *, **, and ! exclusions. Local projectRoots entries extend the shared list.

For paths matched by a configured pattern, including an exclusion, projectRoots takes precedence over package workspaces. Package declarations govern other paths. For example, !apps/internal can exclude an app that the package manager includes; a package exclusion cannot remove a root explicitly included by Impeccable config.

Check your configuration

Run doctor if a setting seems to have no effect:

/impeccable doctor

It checks for unknown keys, outdated rule IDs, and project-root patterns that match nothing. These mistakes can otherwise leave the intended setting unused.

Config structure and hook settings

A minimal example:

{
  "detector": {
    "designSystem": { "enabled": true }
  },
  "hook": {
    "enabled": true,
    "quiet": false
  }
}

detector holds settings shared by manual scans and hooks, including ignoreRules, ignoreFiles, and ignoreValues. The ignore commands maintain those fields for you.

hook controls automatic checks. Quiet mode suppresses clean and pending acknowledgements while keeping new findings. See Design hooks for activation, per-edit checks, logging, and environment overrides.

The top-level "stalenessCheck": false setting turns off the session-start notice about stale context.

Turn off design-system checks

If the recorded system is outdated, update it with document. If it is intentionally not authoritative, set detector.designSystem.enabled to false.

To skip these checks for one scan without changing config:

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

This keeps other project settings and ignores. Use --no-config for a scan without those settings or local design-system context.