Impeccable

What It Does

Impeccable is a design fluency skill for AI coding agents, built by Paul Bakaus (creator of anime.js and an ex-Google Chrome team member). It installs one skill that exposes 23 design commands through a single /impeccable entry point (polish, audit, critique, bolder, quieter, distill, animate, layout, typeset, and more), plus a deterministic anti-pattern detector that scans HTML and CSS for the visual tells of AI-generated interfaces. The detector runs as a standalone CLI with no LLM and no API key, as a browser extension, and as an inline edit hook that runs inside Cursor, Claude Code, GitHub Copilot, Codex, and Grok Build. The project started from Anthropic's frontend-design skill and extends it with a shared design vocabulary, a setup flow that writes project context, and a live browser mode for iterating on UI elements. The audience is frontend developers and designers whose AI coding agents keep shipping the same handful of overused fonts, purple gradients, and card-in-card layouts.

The Good

The deterministic detector catches AI design tells, with zero false positives in testing. I wrote an HTML page planted with the exact patterns the README warns about: an Inter font stack, a purple-to-blue gradient hero, gray text on the gradient, a rounded-square icon tile above the heading, a skipped heading level (h1 then h3), a zero-offset colored box-shadow glow, and a white-on-indigo button that misses WCAG AA by a hair. Running node cli/bin/cli.js detect returned 9 anti-patterns, every one of them a real hit: gray-on-color, two low-contrast findings (1.4:1 and 4.47:1 against the 4.5:1 threshold), dark-glow, icon-tile-stack, overused-font (Inter), skipped-heading, and ai-color-palette. On a clean control page using a warm stone palette, Fraunces, generous padding, and correct contrast, the detector reported exactly one finding: overused-font for Fraunces, which is on its banned list. That is a true positive by the project's own rules, not a false alarm. The detector is consistent and the rules are real.

The rule set is large, specific, and names model-level failure modes you do not see elsewhere. The registry holds roughly 58 named anti-patterns, matching the claimed 59. Alongside the expected design-quality checks (low-contrast, cramped-padding, line-length, tiny-text, skipped-heading, nested-cards, justified-text, tight-leading), there is a layer of AI-slop forensics: codex-grid-background, gpt-thin-border-wide-shadow, theater-slop-phrase, marketing-buzzword, aphoristic-cadence, em-dash-overuse, hero-eyebrow-chip, numbered-section-labels, and shape-assembled-illustration. These are content and composition tells that target specific generators, not generic design advice. Each finding in the CI JSON output carries antipattern (rule id), name, description, severity, category (either slop or quality), file, and snippet, which is clean enough to gate a pull request on.

The test discipline is exceptional for a skill repository. The default suite (node scripts/run-tests.mjs default) ran 1817 tests across five suites with 1815 pass, 0 fail, and 2 skip: core 654 of 654, detector 121 of 121, live 820 of 822 (2 skip), framework 216 of 216, and plugin-e2e 4 of 4. The plugin-e2e suite installs the committed ./plugin subtree into a real sandboxed Claude Code and asserts the skill parses, every shipped agent auto-discovers, and the hooks load. This is far beyond the typical skill repo, where a README and a SKILL.md are the entire deliverable. Three GitHub workflows back it up (ci.yml, sheriff.yml, sync-generated-output.yml).

The provider surface is the broadest of any design skill reviewed, and the install flow is honest about platform steps. The installer supports 14 tools: Cursor, Claude Code, GitHub Copilot, Gemini CLI, Codex CLI, Grok Build, OpenCode, Pi, Kiro, Trae (both China and International variants), Rovo Dev, Qoder, Mistral Vibe, and Google Antigravity. npx impeccable install detects harness folders, lets you keep or customize the provider set, and writes provider-native hook manifests. The README is unusually candid about the steps the installer cannot automate: Codex needs a manual /hooks approval after install, Grok Build needs folder trust (/hooks-trust or --trust), and Cursor needs Nightly channel plus Agent Skills enabled in settings. That candor is more useful than a flat "it just works" claim.

The design vocabulary is coherent and the routing prevents command sprawl. A single /impeccable entry point with no argument loads routing.md and presents a context-aware menu rather than auto-running. The 23 commands are categorized (Build, Evaluate, Refine, Enhance, Fix, Iterate) and most accept a target (/impeccable polish the checkout form). The init command captures whether a surface is brand (marketing, landing) or product (app UI, dashboard) into a PRODUCT.md and optional DESIGN.md, and later commands read that context. The /impeccable pin shortcut lets you promote a frequent command to a standalone slash command. This is a designed system, not a pile of prompts.

The Bad

There is no Hermes or OpenClaw install path, which is a real gap for this audience. The installer lists 14 providers and none of them is Hermes Agent or OpenClaw. The repo ships a generic .agents/skills/ directory (the open agentskills format that Hermes can consume), but the README's Supported Tools section, the --providers flag values, and the copy-from-repository instructions all omit Hermes and OpenClaw by name. A Hermes user can hand-copy .agents/skills/impeccable/ into ~/.hermes/skills/, but they are on their own: there is no npx impeccable install --providers=hermes, no documented hook manifest for Hermes, and no mention in the README. For a skill this large and this design-focused, that is the most significant ecosystem miss.

The skill version and the npm CLI version drift apart, and there are no git tags to pin either. The SKILL.md frontmatter and the Claude Code plugin marketplace manifest both declare version 4.0.4, while the published npm package and the CLI's --version report 3.5.0. This split is coherent (the skill payload and the detector CLI are versioned independently), but a reader checking npm view impeccable version and the skill frontmatter in the same project sees two different numbers with no explanation. There is no CHANGELOG file and no git tags at all, so there is nothing to pin an audit to and no release history to diff. The package has 30 npm releases, but the version trail lives only on the registry, not in the repository.

The static HTML analyzer reports line 0 for every finding, which limits its value as a strict CI gate. In the JSON output from detect --json, the line field is 0 for all 9 findings on the test page. The text-mode and static-HTML engines parse the document and identify the offending value or structure, but they do not map it back to a source line. A developer running this in CI gets the rule, the snippet, and the file, but not the line to jump to. The browser path (Puppeteer) may resolve this against a live DOM, but the zero-dependency static path that most CI setups will use does not.

Several planted anti-patterns did not trigger in the static engine, even though their rules exist. My test page included a .card .card nesting, a bounce easing curve (cubic-bezier(0.68, -0.55, 0.265, 1.55)), a left-and-right side-tab border, a pure black #000000 footer, and an undersized touch target. The registry defines nested-cards, bounce-easing, side-tab, and cramped-padding as rules, but none of them fired on my markup through the static engine. Some of these likely require the browser path or more specific structural conditions, and the partial coverage is honest (the rules exist, they are just narrower than a naive reading suggests). A user who expects all 59 rules to fire on a static file will be surprised that a meaningful subset is browser-only.

Smoke Test Results

Tested on macOS host (aarch64), Node v24.13.1, bun 1.3.14 (installed via Homebrew for the bun-runner test suites), npm 11.8.0. The repo was shallow-cloned (depth 1) into an isolated directory, dependencies installed with bun install (225 packages), and the published npm package checked against the registry. The detector was exercised against two hand-written HTML files: one planted with AI-slop patterns and one clean control.

Run A. Fresh clone, deps installed

$ cd /tmp/impeccable-rev && bun install

+ css-select, css-tree, domutils, fflate, htmlparser2, marked

225 packages installed

PASS (clean install, no peer warnings)

$ node cli/bin/cli.js --version

3.5.0

PASS (CLI loads, version matches package.json)

$ node cli/bin/cli.js --help

Usage: impeccable [options] (detect, ignores, help, install, link, update, check)

PASS (CLI surface documented)

$ node .agents/skills/impeccable/scripts/context.mjs --help 2>&1 | head -3

exits cleanly (context loader present)

PASS

Pass rate: 4 of 4. Clean install, the CLI and the skill's context script both load, and the version is consistent with the npm package.

Run B. Sandbox with deps preinstalled

$ node scripts/run-tests.mjs default

test:core tests 654 pass 654 fail 0 skipped 0

test:detector tests 121 pass 121 fail 0 skipped 0

test:live tests 822 pass 820 fail 0 skipped 2

test:framework tests 216 pass 216 fail 0 skipped 0

test:plugin-e2e tests 4 pass 4 fail 0 skipped 0

PASS (1817 tests, 1815 pass, 0 fail, 2 skip)

Pass rate: 5 of 5 suites green. The badge number is 1815 of 1817. The two skips are in the live suite and are environment-specific. The plugin-e2e suite loaded the committed plugin into a real Claude Code and asserted skills, agents, and hooks all resolve.

Run C. Functional verification (does it do what it claims?)

$ node cli/bin/cli.js detect /tmp/sloppy-saas.html

9 anti-patterns found: gray-on-color, low-contrast (x2), dark-glow (x2),

icon-tile-stack, overused-font (inter), skipped-heading, ai-color-palette

PASS (every finding is a real planted tell)

$ node cli/bin/cli.js detect --json /tmp/sloppy-saas.html

[ {antipattern, name, description, severity, category, file, snippet} x9 ]

categories split: slop (5) + quality (4)

PASS (structured CI JSON, slop vs quality categorization)

$ node cli/bin/cli.js detect /tmp/clean-design.html

1 anti-pattern found: overused-font (fraunces)

PASS (true positive, not a false alarm: Fraunces is on the banned list)

Functional pass rate: 3 of 3. The core claim (deterministic detection of AI design tells with no API key) is verified end to end, with structured output and a clean control confirming no false positives.

What the runs tell you

The deterministic detector, which is the differentiator that separates Impeccable from prompt-only design skills, works as advertised on the static path: it catches the visual and content tells of AI-generated UI without calling a model, and its CI JSON is clean enough to gate a build on. The full test suite is green and unusually large for a skill repo. The 23 design commands and the live browser mode are prompt and runtime contracts that an agent executes, so they were verified structurally and via the plugin-e2e loader rather than by running a model, which is the honest limit of a no-API-key review. The static engine's line-0 reporting and its partial coverage of some rules (nested-cards, bounce-easing) are the practical ceilings to keep in mind.

Setup Walkthrough

1. From your project root, run npx impeccable install. It lists the harness folders it detected (for example ~/.claude, ~/.codex, .cursor), lets you keep them or customize with --providers=claude,codex,cursor,grok, and asks whether to install project-local or global (--scope=project|global). On supported hosts it also writes the provider-native hook manifest.
2. Reload your AI coding tool, then run /impeccable init inside it. init asks whether the surface is brand or product and writes PRODUCT.md (and offers DESIGN.md) so later commands know the audience, color, type, and component context.
3. To run the detector without any harness, use npx impeccable detect src/ for a directory, npx impeccable detect index.html for a file, or npx impeccable detect https://example.com for a URL (the URL path needs Puppeteer, an optional dependency). Add --json for CI output.
4. If you use Codex, open /hooks after install and approve the project hook. If you use Grok Build, run /hooks-trust or launch with --trust so the hook scripts can run. Cursor needs Nightly channel plus Agent Skills enabled in Settings.
5. Add the documented .gitignore block to keep the ephemeral .impeccable/ working files (screenshots, live-mode sessions, per-dev config) out of version control while keeping the shared artifacts (config.json, design.json, critique/*.md) tracked.

Alternatives

1. anthropics/frontend-design - the Anthropic skill Impeccable started from. Smaller, prompt-only, no detector, no CLI. Prefer it if you want a minimal, first-party design skill with no dependencies. Prefer Impeccable if you want deterministic linting and a deeper command set.
2. Leonxlnx/taste-skill - the conceptual sibling in the design-taste tier (71K stars). Also targets AI-generated slop, also a skill. It is a different philosophy (a single taste skill vs a 23-command system with a detector), so the choice is breadth-plus-linting (Impeccable) against focus (taste-skill).
3. A CSS or a11y linter (Stylelint, axe-core, Pa11y) - covers accessibility and CSS correctness with precise line numbers, but does not know about AI-slop tells (overused fonts, purple palettes, icon-tile stacks). Use them together: a11y linters for compliance, Impeccable for taste and slop.