Impeccable — the frontend design plugin

One install gives you three cooperating surfaces: a skill you drive with commands, a hook that watches edits, and a detector you can run on its own.

1. 1

   Run the installer

   From your project root, run the installer. It detects which agent folders you have (.claude, .cursor, .codex, …), lets you pick providers and scope, and installs the skill plus the hook manifest.

   bashCopy

   npx impeccable install
   # update an existing install later:
   npx impeccable update

2. 2

   Reload the agent

   Reload so the new skill and hook register. In Claude Code the /impeccable command appears.
3. 3

   Set up the project once

   Run /impeccable init so every other command has context to work from (see the workflow below).

Works across a wide range of agents:

Everything starts at init, which writes the context files the rest of the commands read before they act.

You invoke any command as /impeccable <command> [target], and the target narrows the scope — /impeccable audit the header. Pin a command you use often to get a top-level shortcut:

/impeccable pin audit     # now /audit runs /impeccable audit
/impeccable unpin audit   # remove it

Grouped by intent. Most take an optional [target] to focus on one feature, page, or component.

Plus three management commands: pin / unpin <command> for shortcuts, and hooks <on|off|status|…> to manage the design detector hook.

The skill carries a compact rulebook the agent must satisfy. The essentials:

Match-and-refuse patterns. If the agent is about to write one of these, it rewrites the element with different structure instead.

Underneath the skill is a detector: roughly 44 deterministic rules plus LLM-only critique checks, spanning AI-slop patterns (side-stripe borders, purple gradients, bounce easing), general quality (line length, cramped padding, small touch targets, skipped headings, overused fonts, contrast), and responsive/accessibility. When a DESIGN.md exists, it also checks fonts, colors and radii against it.

Run it standalone on files, folders, or a URL:

npx impeccable detect src/                 # scan a directory
npx impeccable detect https://example.com  # scan a live URL
npx impeccable detect --fast --json src/   # regex-only, machine-readable (CI)

The hook wires that same detector into the agent: it runs automatically after UI edits and surfaces findings as you work. Configure it per project in .impeccable/config.json:

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

Suppress noise precisely — per rule, per file, or per value — from the CLI or with an inline comment, and keep machine-local settings (like hook consent) out of git in config.local.json:

npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
# or inline, in any file:
# <!-- impeccable-disable overused-font: brand requirement -->

For reference, here is the actual Impeccable config committed to this project — one file is exempted from the detector, and hook consent is stored locally:

{
  "detector": {
    "ignoreRules": [],
    "ignoreFiles": ["components/shell/sidebar.tsx"],
    "ignoreValues": []
  }
}