← Cribsheets
pbakaus-impeccable
  1. Overview
  2. Why it exists
  3. Install
  4. Mental model
  5. Commands
  6. Detectors and hooks
  7. Findings
  8. What to use
  9. Pick one builder
  10. Sources
Design Skills · 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.

9368675commit, 23 Oct 2026
4.7.1skill version in repo
24commands
62detector rules (README count)
17harnesses listed

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.

Why It Exists

Every Model Learned The Same SaaS Template

1

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.

2

Anthropic's frontend-design was the first widely-used design skill for Claude. Impeccable started from there.1

Install

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
HarnessWhere it landsOne extra step
Claude Code.claude/skills/impeccable; hook in .claude/settings.local.jsonOr /plugin marketplace add pbakaus/impeccable
Cursor.cursor/skills/impeccable; hook in .cursor/hooks.jsonPost-edit hook only; no Stop deep pass
Codex CLI.agents/skills/; hook in .codex/hooks.jsonCodex 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 extensionThe 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.

Mental Model

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.

The Commands

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.

Detectors And Hooks

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.

Findings And Gotchas

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.

What To Use

Init Once, Then Audit, Critique, Polish

  1. Start: npx impeccable install, then /impeccable init, then /impeccable document if the app already has a look.

  2. Review: /impeccable critique <screen> for design, /impeccable audit <screen> for a11y and performance.

  3. Adjust: bolder, quieter, distill, animate on one named target at a time.

  4. Ship: /impeccable polish, then npx impeccable detect --json in CI.

  5. Pin your favourite: /impeccable pin audit gives you /audit.

Fleet Rule

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.

Sources

Read The Skill, Then The README

  1. SKILL.md
  2. README.md
  3. reference/hooks.md
  4. impeccable.style: docs, hooks and detector pages
  5. 1 Anthropic frontend-design: the skill Impeccable grew from. No separate sheet; Impeccable replaces it for this fleet.
  6. pbakaus/impeccable: the app and dashboard builder
  7. nutlope/hallmark: the landing page builder
  8. nextlevelbuilder/ui-ux-pro-max: the searchable lookup