Impeccable Turns AI Design Taste Into a Linter You Can Run in CI

Coding agents build pages that all look alike. Impeccable catches the tells with plain rules, no model required.

You can spot an AI-built landing page from across the room. A pill-shaped "Introducing" badge above the headline. One word in the headline set in italic serif. Cards nested inside cards. A purple gradient. A "01 Discover, 02 Design, 03 Deliver" row. None of these is wrong on its own. Together they read as "nobody decided anything here."

The usual fix is to ask the agent for better taste: a longer prompt, a design skill, a second model to critique the first. That approach has a weakness. The judge is another model, so the same page can pass on Monday and fail on Tuesday.

Impeccable, a design toolkit for coding agents by Paul Bakaus, ships something more boring and more useful alongside its design skill: 62 detector rules that run as an ordinary command-line check, "with no LLM and no API key," per its README. That means design review can run in CI (the automated checks that run on every pull request) like a linter, the kind of tool that flags style problems in code, and give the same answer every time.

The project is near the top of GitHub's trending boards this week (Trendshift's live daily board had it at #7 when read around 3:15 PM ET on October 26; the board moves through the day), with about 88.9k stars on its repo page and an engine release, engine-v0.1.17, on October 23.

What Impeccable is

Two things share one repo.

The first is a skill, a packaged set of instructions an AI coding agent loads before it works. Impeccable's skill gives agents like Claude Code, Cursor, Codex CLI, GitHub Copilot and Gemini CLI (the README lists 18) a single /impeccable command with 24 subcommands (in Codex you invoke the skill as $impeccable instead). Some plan (shape, craft), some review (critique, audit, polish), and some nudge a design in a direction (bolder, quieter, typeset, layout). The README says it began as an extension of Anthropic's frontend-design skill, and the project is Apache-2.0 licensed.

The second is the detector, and it's the part worth your attention. It's a set of fixed rules that read your HTML and CSS, or a live URL, and flag patterns. Per the README, they catch things like side-tab borders, purple gradients, bounce easing, dark glows, line length, cramped padding, small touch targets and skipped heading levels. The project site names more, including the italic-serif display word, the thin-border-wide-shadow card, the hero eyebrow chip, nested cards and numbered section labels.

Some of those are taste. Some are accessibility. Touch targets that are too small and skipped heading levels hurt real users, not just aesthetics.

What the rules catch, in plain terms

It helps to sort the findings into three piles, because you'll treat each pile differently.

Usability problems. A touch target is the area you can tap on a phone. When an agent shrinks buttons and links to make a layout look tidy, people miss them with their thumbs. A skipped heading level (jumping from a main heading straight to a third-level one) confuses screen readers, which use headings to let blind users jump around a page. Long lines of text, the line-length check, are tiring to read because your eye loses its place on the way back to the left edge. These findings are worth failing a build over.

Craft problems. Cramped padding and bounce easing (an animation that overshoots and wobbles into place) make a page feel cheap without breaking it. They're worth fixing, but a human should decide how strict to be.

Fingerprints. The purple gradient, the italic serif word, the "Introducing" chip, the numbered section row. None of these hurts a user. They just announce that a model picked the defaults. Whether they matter depends on your audience. A developer tool's landing page that looks like every other AI-built page loses a little trust before anyone reads a word.

The sample audit on the project site tags findings with priorities from P0 to P3, a missing field label at the top and a skipped heading level near the bottom. That ordering is a decent starting point for your own policy.

Sorting findings this way also stops the most common mistake with any linter: turning everything on as a hard failure on day one, getting buried in noise, and switching the whole thing off by Friday.

Why a rule beats a reviewer here

The idea worth taking away is simple: when you can describe a problem precisely, stop asking a model to notice it.

A model reviewer is a judgment call each run. It costs tokens, needs an API key, and can disagree with itself. A rule is a fixed check. It runs in milliseconds, costs nothing, and gives the same answer for the same input, so you can fail a build on it and nobody argues about whether the reviewer was in a mood.

This is the same move teams made with code style years ago. Nobody asks a senior engineer to eyeball indentation anymore; a formatter and a linter do it, and humans review what's left. Impeccable applies that to the visual habits coding agents fall into. The model still does the creative work. The rules catch the defaults it reaches for.

The README keeps the claim honest: a clean run "is evidence, not proof of visual or accessibility quality." A page can pass every rule and still be bland. The detector removes known tells. It does not supply judgment.

Put this into practice

Start with the detector alone. You don't need the skill, an agent or an API key to get value from it. The README says Node is only needed for the npx shim.

1. Turn telemetry off first. More on why below.

npx impeccable telemetry off
npx impeccable telemetry status

2. Scan a folder, a file or a live page.

npx impeccable detect src/
npx impeccable detect index.html
npx impeccable detect https://your-site.example

Scanning a URL needs Chrome, Chromium or Edge installed, per the README. To see what it checks:

npx impeccable detect --list-rules

3. Wire it into CI. Two output modes exist for this. --json gives machine-readable results, and --github writes GitHub Actions annotations so findings show up inline on the pull request.

npx impeccable detect --github src/

The exit codes are what make it a real gate: 0 means the scan finished clean, 2 means it finished with findings, and 1 means at least one target couldn't be scanned. Per the README, an operational failure (1) takes precedence when you scan several targets and only some fail. So a build step that fails on any non-zero code catches both bad design and a broken scan. For reproducible results, pin the package version in CI (npx impeccable@<version> detect ...) so a rules update doesn't change your build overnight.

What to expect on a page an agent built without guidance: some findings. Read them before you fail the build on them. If your brand really is purple, that rule is noise for you. Record the exception in .impeccable/config.json (the detector docs cover ignoring specific rules, files or values), and use --no-config only when you want a raw scan that bypasses those exceptions. One CI detail: GitHub shows a limited number of annotations per step, so on a noisy first run the rest live in the workflow log.

4. Add the skill if you want the agent to fix things.

npx impeccable install

Then, inside your coding agent, /impeccable init writes a PRODUCT.md describing your product, and commands like /impeccable audit blog or /impeccable critique landing run the agent-side review. The README also lists plugin installs for Claude Code (/plugin marketplace add pbakaus/impeccable) and others.

A good loop: the agent builds, npx impeccable detect runs in CI, and the agent gets the findings back as a task. The rules do the catching, the model does the fixing, and a human reviews what's left.

Honest limitations

Telemetry is on by default. When you start a design, Impeccable sends a request to its service along with an anonymous record of the options shown and the one chosen. The README lists the fields (a roll key, scope, the winning card's kind and position, client version, a random choice ID) and says project names, files, code and PRODUCT.md are never sent. That's a fairly narrow set, but on-by-default is still a choice your security team should know about. Turn it off with npx impeccable telemetry off, DO_NOT_TRACK=1, IMPECCABLE_NO_TELEMETRY=1, or "telemetry": false in the project's .impeccable/config.json. Opting out doesn't stop the request itself, since the roll feature needs it. The README says the roll still works and the API is told not to record it.

Live mode runs code on your machine. The live command lets you iterate in the browser, and applying copy edits can run a validation script from your package.json in a shell with your user permissions. The README says to use live mode only on projects you trust to run locally, to review that script first, and not to inject its helper into a production site or weaken a site's security settings to make it work. For production pages, use detect on the URL, which doesn't write back to your source.

Rules encode someone's taste. Purple gradients and italic serifs aren't bugs. They're overused defaults. Treat those findings as prompts to decide, not orders, and keep hard failures for the accessibility rules where the harm is clear.

A clean scan is a floor. The detector removes known tells. It can't tell you whether the page is clear, whether the copy works, or whether the layout fits your product. That still takes a person.

The star count is huge and moving. About 88.9k on the repo page as of October 26. Treat it as momentum, not a quality score.

What to take from it

The interesting thing about Impeccable isn't that it makes AI design prettier. It's that it draws a line between the parts of design review a machine can check the same way every time and the parts that need judgment, and it hands the first part to a command with an exit code.

That line is worth copying for anything your agents produce. If you can write the rule down, write it as a check. Save the model, and your own attention, for what's left. Run npx impeccable detect on the last page your agent built and see how many of the tells you'd stopped noticing.

Sources: pbakaus/impeccable README (main, engine-v0.1.17 current as of Oct 26, 2026); Impeccable releases; impeccable.style; Impeccable detector docs; Trendshift daily board.