Impeccable: Not Teaching AI Taste — Giving AI a Vocabulary: 24 Commands

> Source: pbakaus/impeccable — https://github.com/pbakaus/impeccable > Language: Rust | Stars today: 733 | License: MIT > In one sentence: 1 skill, 24 commands, 62 deterministic detection rules — turning "don't generate ugly UI" from a vague aesthetic judgment into an executable engineering instruction.

---

Aesthetics Is Not a Score, It's a Vocabulary

Give an AI an aesthetic scorer and it gives you a number. Then what? You're stuck holding a score with no idea what to change.

Impeccable's first design decision: don't give the AI a scorer — give it a vocabulary.

24 commands, each one a concrete design action:

• polish — final pass, align to the design system, ready for release
• audit — run technical quality checks (a11y, performance, responsiveness)
• critique — UX design review: hierarchy, clarity, emotional resonance
• distill — strip down to the essence
• bolder — amplify a boring design
• quieter — rein in an overly aggressive design
• harden — error handling, i18n, text overflow, edge cases
• animate — add purposeful motion
• typeset — fix fonts, hierarchy, sizing
• layout — fix layout, spacing, visual rhythm

These commands don't "ask the AI to score" — they "ask the AI to execute a specific action." The difference: a score tells you "7/10"; a command tells you "bump the hero section font size by 2px, drop that bounce easing."

The latter can be executed directly; the former just gives you anxiety.

62 Deterministic Rules

Impeccable's second design is 62 "deterministic detection rules."

The keyword is "deterministic" — these rules can be detected without an LLM. The CLI and browser extension run them directly, with no API key, no model calls.

What do they detect? The "tells" of AI-generated frontend:

• Inter font (used by every SaaS template)
• Purple-to-blue gradients (AI's favorite palette)
• Cards nested in cards (AI's missing sense of hierarchy)
• Gray text on colored backgrounds (insufficient contrast)
• Rounded-square icons above headings (AI's "decorative icons")
• Bounce/elastic easing (dated motion design)

The value of these rules isn't in "what they detect" but in "detection needs no LLM." A regex can find "you used the Inter font" — no need to call GPT-4 to judge.

That's an important engineering choice: hand the determinable things to deterministic code, and give only the indeterminable things to the LLM. Impeccable's critique command does use an LLM for subjective judgments like "UX emotional resonance," but objective violations like "gray text on a colored background" are handled by regex alone.

PRODUCT.md vs DESIGN.md Layering

Impeccable's third — and deepest — design: splitting "durable product truth" from "surface visual direction" into two files.

• PRODUCT.md — audience, purpose, runtime environment, constraints, tone, evidence. These are facts that "don't change when you swap the skin."
• DESIGN.md — visual direction, component system, design tokens. These are the swappable surface layer.

Why does this layering matter? Because the biggest problem in AI-generated UI isn't "the AI doesn't know what looks good" — it's "the AI conflates product facts with visual preferences."

You tell the AI "this is a docs site for a developer CLI tool," and the AI binds that fact to "so use a dark theme + monospace font." But a dark theme is a visual choice, not a product fact — the same developer docs site could use a light theme.

Impeccable's init command asks only "product facts," never "visual preferences." Visual preferences are decided later on specific surfaces via the shape command. This forces the AI to decouple "what this is" from "what this looks like."

Inheritance from Anthropic's frontend-design

Impeccable explicitly says it started from Anthropic's frontend-design skill — the first widely adopted Claude design skill.

But Impeccable added three things:

1. A vocabulary of 24 commands — Anthropic's skill was "give the AI a style guide and let it judge"; Impeccable is "give the AI a set of executable commands" 2. 62 deterministic rules — Anthropic's skill relies entirely on LLM judgment; Impeccable hands objective violations to deterministic code 3. PRODUCT.md / DESIGN.md layering — Anthropic's skill makes no explicit distinction between product facts and visual direction

All three additions point in the same direction: decompose vague aesthetic judgment into executable engineering actions.

The "Harness-Agnostic" Ambition

Impeccable's supported harness list is long: Claude Code, Cursor, Codex CLI, Gemini CLI, GitHub Copilot, Grok Build, Hermes Agent, Veto, Opencode, Pi, Qoder, Trae, Trae-CN, Rovo Dev, Vibe.

This isn't a "supports a few major ones" list — it's "supports nearly every existing harness."

How? Impeccable's core is a self-contained binary (compiled Rust), adapted to different harnesses through a launcher script. Each harness has its own hook format (Claude Code's .claude/hooks, Codex's .codex/hooks.json, Cursor's .cursor), and Impeccable generates the matching hook manifest at install time.

This continues the "harness-agnostic design" concept discussed previously with Free Claude Code: a skill shouldn't be bound to a specific harness. But Impeccable pushes it further — not just the skill is portable, even the hook mechanism is portable.

Live Mode: Iterating Inside the Browser

Impeccable's live command is "visual variant mode" — iterating on elements in real time in the browser. The generate command goes further — automatically producing multiple variants of an element, no manual selection needed.

This turns AI design from "generate once and see" into "generate many and pick the best." Similar to traditional design tools' "version compare" feature, but with millisecond-level iteration speed.

The cost: live mode requires the browser extension and a local server. Not every harness supports it. This is Impeccable's trade-off — deep features need deep integration.

A Signal Worth Heeding

There's a line in Impeccable's README: "Every model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project."

That's true — AI-generated UI does have tells (Inter font, purple-blue gradients, cards in cards). But Impeccable's solution is "detect these tells and fix them."

The question: if 62 rules detect "typical traits of AI generation," won't models learn to "avoid those traits" and evade detection? It's an arms race like antivirus vs. malware — detection rules are static, models evolve.

Impeccable's rules do get updated (the CHANGELOG shows active maintenance), but fundamentally this is "rules vs. models." In the long run, the better solution might be "don't let models generate these tells in the first place during training" — but that's up to model vendors, not skill authors.

Closing

Impeccable's core insight: aesthetic problems are often engineering problems.

"This UI is ugly" is an aesthetic judgment. "This UI uses the Inter font + a purple-blue gradient + cards nested in cards" is an engineering judgment. The former is unexecutable; the latter can be executed.

24 commands + 62 rules + PRODUCT/DESIGN layering — together these three do one thing: turn "get the AI to generate good-looking UI" from "teach AI taste" into "give AI an executable design engineering practice."

This isn't the ultimate solution — rules age, models evolve, new tells will appear. But at least today, Impeccable offers a far better framework than "give the AI a scorer": give the AI a vocabulary so it knows which action to take, instead of giving it a score and letting it guess what to change.