Impeccable

Overview

Impeccable, by Paul Bakaus, grew out of Anthropic's frontend-design skill. It installs a single impeccable skill into your coding agent. You drive it with /impeccable <command> <target>, using 24 commands such as init, audit, critique, polish, typeset, layout, harden and distill. init records durable product facts (audience, purpose, constraints, voice) in PRODUCT.md, and document captures an existing visual system in DESIGN.md, so later commands work from the same context.

The pack also contains a standalone detector engine. It runs 61 deterministic rules with no LLM and no API key: side-tab accent borders, purple/blue gradients, nested cards, gray text on colored backgrounds, low contrast, flat type hierarchy, skipped headings, overused fonts and more. You can run it three ways: from the terminal (npx impeccable detect), in CI, or as an agent hook that checks each UI file edit.

Instructions

Install into the agent

Run the installer from the project root. It detects your agent folders, asks which providers to install and whether to install per project or globally, and adds the provider's hook manifest:

npx impeccable install

For non-interactive setups, pass the choices as flags:

npx impeccable install --providers=claude,cursor,codex --scope=project -y
npx impeccable install --providers=claude --scope=project --no-hooks -y   # skill only, no edit hook

Reload the agent afterwards. For Claude Code, a project install writes .claude/skills/impeccable/, four helper subagents in .claude/agents/, and a PostToolUse + Stop hook in .claude/settings.local.json. Other install routes:

npx impeccable check     # are installed skills out of date?
npx impeccable update    # refresh skills and hook manifests

• Claude Code plugin: /plugin marketplace add pbakaus/impeccable, then install it from /plugin.
• VS Code + Copilot: code --install-extension renaissance-geek.impeccable (skill only, no hook).
• Codex: after install or update, open /hooks and approve the project hook. Codex runs the skill as $impeccable or through /skills, not as /prompts:.

Set up design context once

Inside the agent chat (not the terminal):

/impeccable init

init inspects the project, asks only about gaps, writes PRODUCT.md, configures live mode where applicable, and may ask you to choose a build path: comp (generate a comp first, then build to match it) or code (build straight in code). The answer is saved as buildPath in .impeccable/config.json. For an existing codebase, also run:

/impeccable document

This generates a root DESIGN.md from the tokens and components already in the code.

Steer design work with commands

Every command runs through the one skill and takes an optional target in plain words:

/impeccable shape onboarding checklist   # plan UX/UI before any code
/impeccable build the pricing page       # ordinary new work, no subcommand needed
/impeccable critique landing             # UX review: hierarchy, clarity, resonance
/impeccable audit the header             # a11y, performance, responsive checks
/impeccable typeset blog post template   # font choice, hierarchy, sizing
/impeccable layout settings              # spacing and visual rhythm
/impeccable harden checkout              # errors, i18n, text overflow, edge cases
/impeccable polish settings              # final pass before shipping

Tone commands adjust intensity: bolder, quieter, distill, colorize, animate, delight, overdrive. adapt handles other devices, optimize performance, clarify UX copy, onboard empty states and first-run flows, and extract moves reusable components and tokens into the design system. /impeccable live and /impeccable generate iterate on element variants in a local browser session. Type /impeccable alone for the full list, or free-form: /impeccable redo this hero section. Older docs mention craft; in current skill versions it is a deprecated alias for a plain new-work request, so skip it.

Pin commands you use often:

/impeccable pin audit

This creates a standalone /audit shortcut.

Run the detector from the terminal or CI

npx impeccable detect src/                       # directory: HTML statically, CSS/JSX/TSX by pattern
npx impeccable detect --json src/ > impeccable-report.json
npx impeccable detect --quiet src/               # print only the findings count
npx impeccable detect --scope type src/          # only typography rules (type, layout)
npx impeccable detect --viewport 390x844 http://localhost:3000/pricing

Human-readable findings go to stderr, so redirect with 2> findings.txt. --json goes to stdout. Exit codes: 0 means no primary findings, 2 means findings, and 1 means a target could not be scanned. URL scans render the page in an installed Chrome, Chromium or Edge. A GitHub Actions step:

- name: Design lint
  run: npx impeccable detect --json src/ > impeccable-report.json

Waive intentional choices

Ignores live under detector in .impeccable/config.json (shared). Use --local to write them to the gitignored .impeccable/config.local.json instead:

npx impeccable ignores add-value overused-font Inter --reason "Licensed brand font"
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-rule side-tab
npx impeccable ignores list

To waive a finding in one file only, add an inline comment:

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

--no-config ignores all of this config and inline comments, which is useful for a raw baseline scan.

Examples

Example 1: Lint a pricing page an agent just generated

Request: "Claude built our Northwind Freight pricing page and it looks like every other SaaS template. Tell me exactly what's wrong before I ask for fixes."

npx impeccable detect src/pricing.html 2> pricing-findings.txt
echo $?          # 2 = findings present

Result (output from impeccable 4.1.0 on a page with a purple hero gradient, Inter, a 4px left border on two rounded cards (one nested in the other), and an h1 followed by an h4; the file-path header and the → fix hint under each finding are left out here):

  [side-tab] border-left: 4px + border-radius: 12px
  [side-tab] border-left: 4px + border-radius: 12px
  [low-contrast] 3.7:1 (need 4.5:1) — text #000000 on #7c3aed
  [gray-on-color] text #9ca3af on bg gradient(#7c3aed, #3b82f6)
  [low-contrast] 1.4:1 (need 4.5:1) — text #9ca3af on #3b82f6
  [overused-font] Primary font: inter
  [flat-type-hierarchy] Role sizes: body 16px, h1 16px, h4 16px (largest adjacent step 1.00:1; target 1.25:1)
  [nested-cards] Card inside card (div)
  [skipped-heading] <h1> "Plans for Northwind Freight" followed by <h4> "Starter" (missing h2)
  [ai-color-palette] Purple/violet accent colors detected

10 anti-patterns found.

Each finding is followed by a one-line fix hint. In the agent, /impeccable typeset pricing page and /impeccable polish pricing page then fix these against PRODUCT.md and DESIGN.md.

Example 2: Keep the brand font, gate the rest in CI

Request: "Inter is our licensed brand font, so stop flagging it. Fail the build on anything else in the marketing site."

npx impeccable ignores add-value overused-font Inter --reason "Licensed brand font"
npx impeccable detect --quiet apps/marketing/src/

The ignore is stored in .impeccable/config.json (commit it, so teammates and CI share it):

{
  "detector": {
    "ignoreRules": [],
    "ignoreFiles": [],
    "ignoreValues": [
      {
        "rule": "overused-font",
        "value": "inter",
        "createdAt": "2026-09-30T21:34:50.464Z",
        "reason": "Licensed brand font"
      }
    ]
  }
}

The same page now reports 9 anti-patterns found.. The step still exits 2 and fails CI until the remaining findings are fixed or waived.

Example 3: Pre-launch review of a settings screen

Request: "Before Friday's release, review the account settings screen and tighten it up."

/impeccable critique account settings
/impeccable harden account settings
/impeccable polish account settings

critique delivers its review in chat and saves it to .impeccable/critique/, where polish picks up the priority issues. harden adds error states and overflow handling. polish does the final alignment pass. With the Claude Code hook installed, each edit is re-checked by the detector, and a deeper pass runs when the agent stops.

Guidelines

• Commands run in the agent, the CLI runs in the shell. /impeccable ... typed into a terminal does nothing. The shell CLI has only install, update, check, link, detect and ignores.
• A clean scan is evidence, not proof. The detector does not replace looking at the rendered page at desktop and mobile widths. Rules run on static HTML/CSS or by pattern matching on CSS/JSX/TSX. URL scans cannot read cross-origin CSS without CORS.
• The brief wins. If a brand deliberately uses a flagged font or palette, record the exception with ignores add-value and a reason instead of letting the agent "fix" the brand.
• Hooks run outside model approval. In Claude Code, installed hooks fire on Edit/Write and Stop even if you deny the model's own commands, and the first run may download the engine into ~/.impeccable/bin/. Review .claude/settings.local.json before unattended runs.
• Live mode is for local checkouts only. Do not inject it into a deployed site or weaken CSP for it. Applying copy edits runs package.json's impeccable:manual-edit-validate script with your permissions, so read that script first in an unfamiliar repo. For production pages use detect on the URL instead.
• Gitignore the working files. .impeccable/ collects screenshots, live-mode state and caches. Ignore those (the README has a ready-made block between # impeccable-ignore-start and # impeccable-ignore-end). Keep config.json, design.json, live/config.json, surfaces/*.md and critique/*.md tracked.
• One copy per workspace. Do not combine the VS Code extension, the Claude Code plugin and an npx install in the same project. Duplicate skills confuse the agent.
• When not to use it: backend-only or non-UI work, native apps without a web surface you can scan (the commands still help, but detect targets HTML/CSS/JSX), or when you only need a token file and no agent guidance. In that case a plain DESIGN.md is lighter.