pbakaus-impeccable
pbakaus/impeccable
One skill, 24 commands and a detector that catches AI design tells without an LLM.
Design guidance for AI coding agents. 1 skill, 24 commands, live browser iteration, and 62 deterministic detector rules for AI-generated frontend design. Use it for app UI, dashboards, settings and existing product screens.
Who it is for
Anand and the fleet (Ellie FSE, Usha UX) when an agent builds or reviews app screens.
What you get
PRODUCT.md (product truth), DESIGN.md (visual system), one /impeccable command, and a hook that lints UI edits.
Every Model Learned The Same SaaS Template
Every model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project: Inter for everything, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.
Anthropic's frontend-design was the first widely-used design skill for Claude. Impeccable started from there.1
One Installer, Then Init Inside Your Agent
Run these from the project root. The npx step copies files; init is the part that thinks.
# 1. copy the skill + hook into every harness it detects (asks project vs global) npx impeccable install # scripted: pick harnesses and scope up front npx impeccable install --providers=claude,codex,cursor,grok --scope=project # 2. inside Claude Code / Cursor / Grok Build (Codex: $impeccable) /impeccable init # later: refresh skill + hook npx impeccable update
| Harness | Where it lands | One extra step |
|---|---|---|
| Claude Code | .claude/skills/impeccable; hook in .claude/settings.local.json | Or /plugin marketplace add pbakaus/impeccable |
| Cursor | .cursor/skills/impeccable; hook in .cursor/hooks.json | Post-edit hook only; no Stop deep pass |
| Codex CLI | .agents/skills/; hook in .codex/hooks.json | Codex users should open /hooks after install or update and approve the project hook when prompted. |
| Grok Build | .grok/skills/; .grok/hooks/impeccable.json | /hooks-trust or launch with --trust |
| Copilot (VS Code) | .github/skills/ or the Marketplace extension | The extension installs no hooks |
Why npx at all
Node is only involved if you use the npx impeccable installer, which is a shim around the same binary. The skill itself runs a self-contained engine binary.
Keep the noise out of git
Paste the README's # impeccable-ignore-start block into .gitignore. Keep .impeccable/config.json, design.json, surfaces/*.md and critique/*.md tracked.
Telemetry
Theme "rolls" call impeccable.style. Turn off recording with npx impeccable telemetry off or DO_NOT_TRACK=1.
PRODUCT.md Is Truth, DESIGN.md Is Look
Two files, written by two different commands, read by every other command.
PRODUCT.md, from init
init captures durable product truth in PRODUCT.md. It does not invent a visual world and does not write DESIGN.md. Audience, purpose, constraints, voice.
DESIGN.md, from document
Generate a DESIGN.md file at the project root that captures the current visual design system, so AI agents generating new screens stay on-brand. YAML tokens up top, then prose. Tokens are normative; prose provides context for how to apply them.
Modes pick the ambition
The mode names what the visitor's success looks like on this surface. Persuade, Operate, Read, Experience. Dashboards are Operate: Scanability, consistency, native expectations, and the real usage scene outrank expression.
Refine vs redesign
Refinement preserves; redesign replaces. Polish keeps the incumbent look. A redesign replaces DESIGN.md.
Ten Commands Do Most Of The Work
The other 14 (shape, harden, onboard, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, extract, generate, craft) follow the same pattern. Quotes are checked against the reference file under each.
The Linter Runs With No LLM And No API Key
npx impeccable detect src/ # scan a folder (findings on stderr) npx impeccable detect --json . # CI: JSON on stdout npx impeccable detect --github src/ # GitHub Actions annotations npx impeccable detect https://example.com # rendered page, needs local Chrome npx impeccable ignores add-value overused-font Inter --reason "Brand font" # exit 0 clean · 2 findings · 1 could not scan
What it catches
The detector catches 62 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
The hook
The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow.
Two tiers
The per-edit hook surfaces only the immediate tier: mechanical, unambiguous problems worth interrupting an edit for. Taste findings wait for a deeper pass on Stop (Claude Code, Codex, Grok Build; not Cursor).
Read it right
A clean detector run is evidence, not proof of visual or accessibility quality.
The README Lags The Skill In Places
From reading the repo at 9368675 and running the published CLI on the box (Node 20.19, 24 Oct 2026).
Gap craft is described two ways
README: "Full shape-then-build flow with visual iteration". SKILL.md: "Deprecated alias for an ordinary new-work request". Trust SKILL.md.
Gap npm is a release behind
The repo says 4.7.1; npm view impeccable version returned 4.7.0. npx impeccable gets 4.7.0.
Bug Silent on old Node
package.json requires Node 22.18 or later. On Node 20.19, npx impeccable detect --list-rules printed nothing and exited 0, with no warning. Check node -v first.
Gap Cursor note may be stale
The README still says Cursor skills need the Nightly channel. That may be out of date; check before you follow it.
Cost Hooks run outside model approval
In Claude Code, installed command hooks run independently of model-tool approval. The first edit can download the engine binary.
Copy Reporter vs fixer
audit documents and never fixes; critique runs its two assessments isolated so the linter cannot anchor the judgment.
Init Once, Then Audit, Critique, Polish
Start:
npx impeccable install, then/impeccable init, then/impeccable documentif the app already has a look.Review:
/impeccable critique <screen>for design,/impeccable audit <screen>for a11y and performance.Adjust:
bolder,quieter,distill,animateon one named target at a time.Ship:
/impeccable polish, thennpx impeccable detect --jsonin CI.Pin your favourite:
/impeccable pin auditgives you/audit.
Pick One Builder Per Project
This rule sits on all three Design Skills sheets.
The rule
Never load Impeccable, Hallmark and Taste Skill together on one project. Pick one builder.
Why
Each ships its own floor, bans and stamp. Impeccable writes PRODUCT.md, DESIGN.md and .impeccable/. Hallmark writes .hallmark/ and a CSS stamp. Two builders on one page argue: one deals a theme, the other rolls a visual world, and the agent splits the difference.
Rule of thumb
App, dashboard, settings, existing product UI: Impeccable. New landing or marketing page: Hallmark. Need a palette, font pair or UX rule: UI/UX Pro Max. It is a lookup, so it can sit next to either builder.
You are here
Impeccable is the builder for apps and dashboards. Choose it, and leave Hallmark and Taste Skill unloaded.
Read The Skill, Then The README
- SKILL.md
- README.md
- reference/hooks.md
- impeccable.style: docs, hooks and detector pages
- 1 Anthropic frontend-design: the skill Impeccable grew from. No separate sheet; Impeccable replaces it for this fleet.
- pbakaus/impeccable: the app and dashboard builder
- nutlope/hallmark: the landing page builder
- nextlevelbuilder/ui-ux-pro-max: the searchable lookup