Impeccable Review: Design Skill for AI Coding Agents

TL;DR

Impeccable (pbakaus/impeccable) is a design skill for AI coding agents written by Paul Bakaus. It gives Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI and a dozen other harnesses one skill with 24 commands (/impeccable polish, audit, critique, typeset, bolder, quieter and so on), and ships a standalone detector with 62 deterministic rules that flags AI-generated design tells — purple-to-blue gradients, nested cards, gray text on colored panels, bounce easing, Inter everywhere — without calling a model.

Facts as of October 28, 2026:

91,245 GitHub stars, 5,399 forks — about 6,700 of those stars arrived in the past week, which put it on GitHub’s weekly trending list.
26 open issues (issues only, not pull requests).
License: Apache-2.0. The repository was created on November 16, 2025.
Latest releases: Skill 4.8.0 and CLI 4.8.0, both published October 26, 2026, on top of engine v0.1.18. The npm package impeccable is at 4.8.0.
The engine behind the detector and hooks is a self-contained binary; GitHub lists the repository’s main language as Rust.

Not run by us: our hands-on lab (a throwaway GitHub Actions container) could not start today because GitHub refused the job over a billing limit on the account. Everything below comes from the README, the official docs at impeccable.style, the 4.8.0 release notes, the npm registry and public discussion. We did not install Impeccable or run its detector.

Our verdict: Impeccable is the most complete design toolkit for coding agents right now, and its best idea is not the prompts — it is the detector. Rules that run as code catch the slop the model forgets, in CI, the same way every time. The 24-command vocabulary is genuinely useful if you can name what is wrong with a page. Budget for its costs, though: hooks that add text to every UI edit, a telemetry call when it deals visual directions, and a lot of surface area for one skill. If you only want a linter for AI-made UI, the CLI alone is worth installing.

What Impeccable actually is

The project describes itself as “the design vocabulary for your coding agent”, and the framing is accurate. Bakaus’s argument, from the README: every model was trained on the same SaaS templates, so without guidance you get the same handful of tells on every project. Anthropic’s own frontend-design skill was the first widely used fix; Impeccable says it started from there and grew in three directions.

Layer	What it is	Needs a model?
The skill	One `SKILL.md` plus reference files that load only for the command you run	Yes — your agent reads it
24 commands	A shared vocabulary: `craft`, `shape`, `critique`, `audit`, `polish`, `distill`, `harden`, `typeset`, `layout`, `colorize`, `animate`…	Yes
Detector	62 deterministic rules, run by `npx impeccable detect` or the browser extension	No
Hooks	Run the detector after the agent edits a UI file and feed findings back	No (but the findings land in the model’s context)
Live mode	Iterate on variants of an element in the browser against a local dev server	Yes

There is also a product-context layer. /impeccable init inspects the project, asks only for the gaps, and writes PRODUCT.md — audience, purpose, constraints, voice. Visual direction is decided later, per surface, and an existing visual system is recorded separately in DESIGN.md. That split matters: “who is this for” stops getting mixed up with “make it teal”.

The 24 commands

All commands run through one skill as /impeccable <command> <target>. The groups below are ours; the commands and descriptions are the project’s.

Purpose	Commands
Set up and plan	`init`, `document` (write `DESIGN.md` from existing code), `extract` (pull tokens and components into the design system), `shape` (plan UX before code), `craft` (shape-then-build with visual iteration)
Review	`critique` (hierarchy, clarity, emotional resonance), `audit` (accessibility, performance, responsive)
Steer the whole page	`polish`, `bolder`, `quieter`, `distill`, `delight`, `overdrive`
Fix one dimension	`typeset`, `layout`, `colorize`, `animate`, `clarify` (UX copy), `adapt` (devices), `optimize` (performance)
Make it robust	`harden` (errors, i18n, overflow), `onboard` (first-run, empty states)
Browser	`live`, `generate` (variants of a named element, no manual picking)

Plain English works too (/impeccable redo this hero section), and /impeccable pin audit creates a standalone /audit shortcut.

The value is less the instructions than the naming. Most developers cannot tell an agent “the type scale is flat and the leading is tight”; they can type typeset. As one Hacker News commenter put it, mentioning the right words is often enough to prime a model.

The detector is the real product

Prompts are suggestions. A model can read “don’t nest cards” and nest cards anyway. The detector checks the result as code, so it does not depend on the model remembering anything.

npx impeccable detect src/                      # scan a folder
npx impeccable detect index.html                # one file (includes linked local CSS)
npx impeccable detect http://localhost:3000     # rendered page, uses an installed Chrome/Chromium/Edge
npx impeccable detect --json . > findings.json  # machine-readable, stdout
npx impeccable detect --github src/             # GitHub Actions annotations
npx impeccable detect --list-rules              # the full catalog

According to the docs, the rules cover both AI tells and general design quality:

AI slop: gradient text, purple and cyan palettes, glowing accents on dark themes, side-tab accent borders, nested cards, decorative grid-line backgrounds, bounce or elastic easing, pulsing status dots, overused fonts.
Quality: contrast below WCAG AA, body text under 16px, tight line height, skipped heading levels, cramped padding, small touch targets, line length.
Copy: repeated text in one container, generic marketing claims, em-dash overuse.
Your own system: with a DESIGN.md present, any font, color, corner radius or font size the file does not list.

Exit codes are CI-friendly: 0 means no primary findings (advisories may still print), 2 means findings, 1 means a target could not be scanned. Human-readable output goes to stderr and JSON to stdout, so 2> findings.txt and --json > findings.json both work. A minimal GitHub Actions step looks like this:

- name: Design lint
  run: npx [email protected] detect --github src/

When a rule is right in general but wrong for your brand, record the exception once instead of arguing with the agent every session:

npx impeccable ignores add-value overused-font Inter --reason "Brand font"
npx impeccable ignores add-file "src/legacy/**"

Or waive it for one file with an inline comment: . Commit .impeccable/config.json so every teammate and every CI run uses the same waivers.

The README is careful about what a clean run means: “A clean detector run is evidence, not proof of visual or accessibility quality.”

Installing it

The normal path is one command from the project root:

npx impeccable install

It detects which harnesses you have (~/.claude, ~/.codex, project-local .cursor and so on), lets you pick, and asks whether to install into the project or globally. For scripts, skip the prompts:

npx impeccable install --providers=claude,codex,cursor --scope=project
npx impeccable update     # later

Then run /impeccable init inside your agent. Alternatives: a Claude Code plugin (/plugin marketplace add pbakaus/impeccable), a VS Code extension for Copilot, grok plugin install pbakaus/impeccable#plugin --trust for Grok Build, a Git submodule linked with npx impeccable link, or a manual copy from dist/ for the other harnesses.

The skill itself needs no runtime. Each copy ships a small launcher that runs the engine binary next to it or downloads it once into ~/.impeccable/bin/. Node is only needed for the npx installer; npm lists >=18.19.0 as the engine requirement for 4.8.0. Since 4.8.0, the launcher and installer check each engine download against digests committed alongside the skill and refuse a binary that does not match — a sensible answer to “this thing downloads executables”.

Pick one route. The plugin and the npx installer each bring their own copy of the skill and their own hooks, so running both means every edit gets scanned twice.

Hooks: automatic, and not free

On Claude Code, Cursor, Codex, GitHub Copilot and Grok Build, install also adds a provider-native hook. After the agent edits a UI file, the detector runs and its findings go back into the conversation; on Stop, a deeper pass runs where supported. In 4.8.0, Cursor moved from gating writes to checking after each edit, and the Stop pass suppresses findings that existed before the session when a verified baseline is available.

That is the feature that makes Impeccable more than a prompt pack, and also its biggest cost. Every finding is text the model has to read, and a long session of small CSS edits adds that output again and again. Two warnings from the README itself:

Claude Code hooks run independently of tool approval. The first edit or Stop can download and cache the engine even if you denied the model’s launcher command. For unattended runs, review installed hooks, or disable them for a run with --settings '{"disableAllHooks": true}'.
Codex tracks hook trust by definition, so an update that changes .codex/hooks.json can need approval again in /hooks. Grok Build needs /hooks-trust once per folder.

Telemetry and live mode

When a new design starts, the skill asks the roll API at impeccable.style to deal a hand of “visual worlds” from its catalog. That request always happens — it is the feature. By default it also records, anonymously, which hand was shown and which card won. Per the README, your project name, files, code and PRODUCT.md are never sent. Opt out with npx impeccable telemetry off, DO_NOT_TRACK=1 or IMPECCABLE_NO_TELEMETRY=1, or for a whole project with "telemetry": false in .impeccable/config.json. The roll still works when you opt out.

Live mode is for local checkouts only. The README warns that applying copy edits runs the optional impeccable:manual-edit-validate script from package.json with your permissions — read it before using live mode in an unfamiliar repository.

What people are saying

The launch on Hacker News in January 2026 (103 points) was rough, and instructive. Several commenters said the “after” examples on the landing page looked worse than the “before” — one noted a metrics dashboard had been replaced with text, another that the landing-page “after” lost the usage numbers and customer rating that sold the product. Others couldn’t tell what they were downloading (“It’s a bunch of markdown files”, one answered). Bakaus replied throughout, agreed the case studies were rushed, removed them, and toned down the landing page copy. A few users reported useful critique feedback on their own projects.

Ten months and about 91,000 stars later, the project has a compiled engine, the detector, hooks and frequent releases with named community contributors. The lesson from that thread still applies: the skill improves a page only as far as someone judges the result. A walkthrough by SSD Nodes recommends that discipline: baseline with the detector, run one command per pass, diff, scan again.

How it compares

If you have read our reviews of Taste Skill, Hallmark, DESIGN.md and shadcn-lint, here is where Impeccable sits:

Tool	Approach	Deterministic check?
Impeccable	24-command vocabulary + product context + detector + hooks	Yes, 62 rules, CLI and CI
Taste Skill	One instruction set against pixel-level AI tells	No
Hallmark	Rules for structural variety in page layout, self-critique before output	No (model-run gates)
DESIGN.md	A static design-system file the agent reads	No (Impeccable can write one and check against it)
shadcn-lint	Linter for Tailwind/shadcn class strings	Yes, narrower scope

The practical rule from the SSD Nodes guide is worth repeating: one design skill per project. Two skills whose descriptions both match “make this page better” will both load, give conflicting rules, and the page flips between styles from edit to edit.

Who it is for

Developers shipping UI with an agent and no designer — the command names give you words for problems you can see but not describe.
Teams that want a design gate in CI — detect --github plus committed ignores stops contrast failures and purple gradients merging.
Designers working with agents who need PRODUCT.md and DESIGN.md followed consistently.

It is less useful for native mobile apps (the detector checks web interfaces only) and one-off prototypes.

Honest limitations

Rules are not taste. The detector finds known tells; it cannot tell you a page is good. The launch-day examples showed a model following the rules into a worse design.
Context cost. The skill’s description matches almost any frontend request, and hook output accumulates over long sessions. Check what it adds before leaving it on everywhere.
Opinionated defaults. Rules against Inter, pure black and gray-on-color will fire on legitimate brand choices. Waivers exist; you will need them.
Surface area. A skill, an engine binary, hooks, live mode, a browser extension and a telemetry endpoint is a lot of moving parts — four releases landed between October 23 and 26 alone.
Downloads a binary. Digest-checked since 4.8.0, but still an executable fetched on first run; vendor it if your policy requires.

FAQ

What is Impeccable?

Impeccable is an open-source (Apache-2.0) design skill for AI coding agents by Paul Bakaus. It adds one skill with 24 design commands, such as /impeccable polish and /impeccable audit, plus a detector with 62 deterministic rules that flags common AI-generated design patterns and design-quality problems in HTML, CSS and component files.

Does the Impeccable detector need an API key?

No. npx impeccable detect runs fixed rules in a local engine binary, with no model and no API key. The same input always gives the same findings. Rules that need judgment, such as identical card grids, are applied by your agent when you run a command like critique.

Which coding agents does Impeccable support?

Claude Code, Cursor, Codex CLI, GitHub Copilot, Gemini CLI, OpenCode, Grok Build, Devin, Hermes Agent, Replit Agent, Trae, Qoder, Rovo Dev, Mistral Vibe, Kiro, Pi and others. Automatic design hooks are installed for Claude Code, Cursor, Codex, GitHub Copilot and Grok Build.

Can I use Impeccable in CI?

Yes. npx impeccable detect --github src/ writes GitHub Actions annotations, and --json gives machine-readable output. Exit code 2 means findings and fails the job; exit code 1 means a target could not be scanned. Record intentional exceptions with npx impeccable ignores add-value and commit .impeccable/config.json.

Does Impeccable send my code anywhere?

According to the README, no. When a new design starts it asks the impeccable.style API for a hand of visual directions and, unless you opt out, records which hand was shown and which won. Project names, files, code and PRODUCT.md are never sent. Turn it off with npx impeccable telemetry off or DO_NOT_TRACK=1.

Verdict

Impeccable earns its stars by doing the one thing most design skills skip: it checks the agent’s work with code. Install the CLI and put detect in CI even if you never use the commands. Adopt the full skill if you build UI with an agent every day, start every project with init, and run one command per pass with a diff in between. Skip the hooks on long, unattended sessions until you have seen what they add to context — and keep a human eye on the result, because a page can pass all 62 rules and still be worse than what you started with.