How to Stop AI Agents Building Generic UIs with Impeccable

Impeccable is a free, Apache-2.0 design skill and command-line tool that stops AI coding agents from shipping the same purple-gradient, Inter-font, card-inside-a-card interface every time, and it ships a detector that flags 61 of those patterns with no LLM and no API key. It gained 1,170 GitHub stars today on the way to about 76,000 in total, and if you have Node.js 22.18 or newer you can scan a page in under a minute and have the skill running inside Claude Code, Codex or Cursor in about ten.

The detector is the part worth trying first, because it works on any project whether or not an agent wrote it. We pointed it at a deliberately bland test page on Windows and it returned 15 findings in a few seconds, from a "side-tab" card border to a skipped heading level.

RelatedHow to Give Claude Code a Memory with Claude-Mem

• Two tools in one package: a skill with 24 /impeccable commands for your agent, and a standalone npx impeccable detect scanner for files, folders or live URLs.
• The scanner is deterministic. Its 61 rules run locally without a model, so it fits in CI: exit code 0 is clean, 2 means findings, 1 means a target could not be scanned.
• One installer covers most agents. npx impeccable install detects Claude Code, Codex, Cursor, Grok Build, Hermes and others, then adds a design hook that re-checks every UI file the agent edits.
• Current versions: skill release v4.5.0 (2 October 2026, a 16 MB universal zip) and npm CLI 4.1.0, which requires Node 22.18.0 or later.

The exact steps, start to finish

1. Check your prerequisites. You need Node 22.18 or newer for npx, plus the AI coding tool you plan to use. Check whichever of the last two you have.

   node --version
   npm --version
   # Claude Code users
   claude --version
   # Codex users
   codex --version

2. Scan something before installing anything. From your project root, point the detector at a folder or a single HTML file. Findings print to stderr.

   npx impeccable detect src/
   npx impeccable detect index.html

3. Install the skill and hook into the project. The interactive installer lists the agents it found and asks for project or global scope. The flag version skips both questions.

   npx impeccable install
   # or, non-interactive, Claude Code only, this project only
   npx impeccable install --providers=claude --scope=project

4. Approve the hook and reload your agent. In Codex, open /hooks and approve the project hook. In Grok Build, trust the folder with /hooks-trust. Then restart or reload your agent so it sees the new skill.
5. Keep working files out of git. Copy the # impeccable-ignore-start to # impeccable-ignore-end block from the project README into your .gitignore, so screenshots and live-mode state stay local.
6. Sign in to your coding agent. Impeccable needs no account or key of its own, but the /impeccable commands run through your agent, so Claude Code, Codex or Cursor must already be logged in and working.
7. Record your product context. Type this in the agent's chat, not in the terminal. It asks a few questions and writes PRODUCT.md.

   /impeccable init

8. Run your first real review. Ask for an audit or a critique of a named part of the app, then let the agent apply the fixes.

   /impeccable audit blog
   /impeccable critique landing

What does the Impeccable detector flag on a typical AI-built page?

Paul Bakaus, who built Impeccable, starts from a blunt observation in the README: every model learned from the same SaaS templates, so without guidance you get the same tells on every project. The detector turns that list into rules. Our test page had a violet-to-blue hero gradient, Inter as the only font, a card nested inside a card with a thick left border, gray text on a purple background and an h1 followed straight by an h4. Running npx impeccable detect index.html named every one of those, along with a WCAG contrast failure of 1.7:1 against the 4.5:1 target, a zero-offset purple glow, a flat type scale where h1 and body were both 16px, and the word "Supercharge" as a marketing buzzword.

Each finding comes with a rule id in brackets, such as [side-tab], [nested-cards] or [overused-font], and one line on what to do instead. The scan took about 4.5 seconds cold, including the time npx spent resolving the package. Two flags matter for real projects. --json sends machine-readable results to stdout for CI, and a URL target scans the rendered page through an installed Chrome, Chromium or Edge:

npx impeccable detect https://example.com
npx impeccable detect --json .

We then rewrote the page by hand: one dark green hero, a serif face, white text that passes contrast, no nested cards. The rescan still found one thing, a [cream-palette] flag for the warm off-white page background, which the rule calls the default "tasteful" AI surface. Switching to white produced no output at all and exit code 0. That is a useful calibration: the rules are opinionated, and a flag is a prompt to make a deliberate choice, not a bug report.

The README is careful to call a clean scan "evidence, not proof" of quality, and that is the right way to read it.

Installing Impeccable into Claude Code, Codex or Cursor

Run npx impeccable install from the root of the project, not from your home folder. It looks for harness folders such as ~/.claude, ~/.codex or a project-local .cursor, lets you keep or change that list, and asks whether to install into this project or globally. In scripts, --providers=claude,codex,cursor and --scope=project answer those questions up front.

On our Windows machine the Claude Code install wrote four things into the project's .claude folder: the impeccable skill, four helper agents (an asset producer, a documenter, a finish reviewer and a manual-edit applier), a hook entry in settings.local.json, and a native engine binary, v0.1.11 for windows-x64, inside the skill's scripts/bin folder. That last part explains why the hook needs no Node at runtime. Node is only there to run npx.

If you would rather not touch the installer, the README lists other routes: a Claude Code plugin through /plugin marketplace add pbakaus/impeccable, a VS Code extension for GitHub Copilot, a git submodule linked with npx impeccable link, or copying the right folder out of the 16 MB universal.zip from the releases page. When a new version lands, refresh with:

npx impeccable update

Does Impeccable work on Windows, macOS and Linux?

Yes. The skill ships a launcher in two forms, scripts/impeccable for macOS and Linux and impeccable.cmd for Windows, and the engine is a platform-specific binary that either sits next to the launcher or downloads once into ~/.impeccable/bin/. Our run used plain npx from Git Bash on Windows 10 with Node 24 and needed nothing extra. Codex gets a commandWindows entry in its .codex/hooks.json that calls the .cmd launcher, so its design hook also works from cmd.exe.

Which of the 24 Impeccable commands to learn first

All of them run through one skill, /impeccable <command> <target>, and typing /impeccable alone lists them. Start with init, because every later command reads the PRODUCT.md it writes: audience, purpose, constraints and voice. After that, audit runs the technical checks (accessibility, performance, responsive), critique does a UX review of hierarchy and clarity, and polish is the final pass before you ship. shape plans a screen before any code exists, and craft runs the full shape-then-build flow.

The tone commands are where the "design vocabulary" idea pays off. bolder and quieter push a design in opposite directions, distill strips it back, and typeset, layout and colorize each fix one dimension. If you use one constantly, /impeccable pin audit gives you a standalone /audit.

RelatedCloudflare Security Audit Skill Setup: AI Pen Test Any Repo

Impeccable next to Anthropic's frontend-design skill and Lighthouse

The README credits Anthropic's frontend-design skill as its starting point, and that is the closest comparison.

Our view: install the detector today on any frontend that an agent touched, and wire --json into CI, because it costs nothing and catches the tells people now spot instantly. Adopt the full skill and hook if an agent writes most of your UI. If a human designer owns the look and agents only fix bugs, the 24 commands are more ceremony than you need, and Lighthouse plus a design review will serve you better.

Fixing a Codex hook that never fires, and other setup snags

Codex shows no findings after edits. Codex tracks trust per hook definition. Open /hooks after every install or update and approve the project hook again, because an update that changes .codex/hooks.json can require approval again.

Grok Build ignores the hook. Project hooks under .grok/hooks/ only run in a trusted folder. Run /hooks-trust once, or start Grok with --trust. Findings reach the model on Stop, not after each edit.

npx complains about the Node version. The npm package declares Node 22.18.0 or later. Upgrade Node, or skip npx entirely and use the Git submodule or the manual copy from universal.zip, since the hook and skill do not need Node.

CI fails on a scan that "worked". Exit code 2 means the scan finished and found something, which most CI runners treat as failure. That is the point, but you can waive a known case with npx impeccable ignores add-value overused-font Inter --reason "Brand font" or an inline impeccable-disable comment in the file.

The hook ran even though you denied a command. The README warns that Claude Code hooks run independently of model-tool approval, so the first edit can download the engine anyway. Review the hook before unattended runs, or pass --settings '{"disableAllHooks": true}' to disable hooks for that session.