Inside pbakaus/impeccable: Eliminating AI Frontend Slop with 24 Design Commands and 62 Deterministic Rules
Anyone who has used an AI coding agent to build a web interface can spot an unguided LLM layout from across the room. Because frontier models were trained on the same SaaS templates and Tailwind snippets, they default to the exact same visual clichés on every project:
Inter or system fonts with flat typographic hierarchy,- Purple-to-blue gradients and neon dark-mode glows,
- Cards nested inside cards,
- Rounded-square icon tiles floating above every heading,
- Low-contrast gray text on colored backgrounds, and
- Dated bounce or elastic easing on every transition.
Prompting "make it look clean and modern" only makes the model lean harder into those exact patterns.
Created by Paul Bakaus, pbakaus/impeccable (now past 90,000 stars on GitHub) solves this problem by combining 1 unified design skill, 24 specialized commands, live browser variant iteration, and 62 deterministic detector rules that run as a zero-LLM native binary and automatic post-edit agent hook.
Let's dive into how Impeccable works, how it separates product context from visual tokens, and how to integrate its CLI and hooks into your frontend workflow.
1. Separating Durable Product Truth (PRODUCT.md) from Visual Systems (DESIGN.md)
One reason AI coding agents ruin existing interfaces is that they conflate what a product does with how a single screen should look.
Impeccable starts with a one-time setup command inside your coding harness:
/impeccable init
/impeccable init inspects your existing codebase, asks only for material gaps, and writes PRODUCT.md—recording your audience, purpose, operating context, constraints, and product voice.
Separately, your visual design system (typography, color tokens, spacing scales, and reusable components) is captured in DESIGN.md and .impeccable/design.json using /impeccable document and /impeccable extract. Whether you choose a comp-first ("buildPath": "comp") or code-first ("buildPath": "code") workflow, every subsequent command respects your established tokens instead of inventing random utility classes.
2. A Shared Vocabulary: All 24 /impeccable Commands
Instead of writing paragraphs of CSS instructions in chat, Impeccable gives you and your coding agent a structured vocabulary accessed via /impeccable <command> <target> (plus /impeccable pin <command> to create top-level shortcuts like /audit or /polish):
| Category | Commands | Purpose |
|---|
| Setup & System | init, document, extract, shape, craft | Initialize PRODUCT.md, extract DESIGN.md tokens from code, plan UX before coding, or run a full shape-then-build flow |
| Critique & QA | critique, audit, polish, harden, optimize | Run UX hierarchy reviews, technical a11y/responsive audits, edge-case hardening (i18n, text overflow), and final shipping checks |
| Visual Tuning | typeset, layout, colorize, animate, clarify, adapt, onboard | Fix typographic scale, spacing rhythm, strategic color, purposeful motion, UX copy, responsive adaptation, and empty/onboarding states |
| Direction Shifts | bolder, quieter, distill, delight, overdrive | Amplify flat designs, tone down noisy layouts, strip UI to its essence, or add micro-delight and high-craft visual effects |
| Live Browser Mode | live, generate | Iterate on visual variants directly in the live browser or generate variants of a named element without manual picking |
For example, you can target specific routes or components directly:
/impeccable critique landing # UX hierarchy and anti-pattern review
/impeccable typeset blog # Fix font pairings, measure, and type scale
/impeccable harden checkout # Patch text overflow, i18n, and error states
/impeccable polish settings # Final alignment pass before shipping
3. The 62-Rule Deterministic Detector Engine (Zero LLM, Zero API Key)
Prompt instructions alone can drift during long coding sessions. To guarantee hard guardrails, Impeccable ships a self-contained native binary engine that evaluates 62 deterministic rules with no LLM calls and no API keys required.
The detector catches both AI design slop (purple gradients, side-tab borders, nested cards, pure untinted blacks/grays, bounce easing, dark glows, overused fonts) and structural UI defects (cramped padding, excessive line lengths, small touch targets, skipped heading levels, and low contrast).
Running the Standalone Detector in CLI or CI/CD
You can run the detector against source directories, static HTML files, or even live rendered URLs (via headless Chrome, Chromium, or Edge):
# Scan a local source tree or HTML file
npx impeccable detect src/
npx impeccable detect index.html
# Scan a live rendered URL (inspects DOM, computed layout, and CSS)
npx impeccable detect https://example.com
# Output machine-readable JSON or GitHub Actions workflow annotations
npx impeccable detect --json .
npx impeccable detect --github src/
# List all 62 detector rule IDs and descriptions
npx impeccable detect --list-rules
And when a rule flags an intentional brand choice (such as using Inter as an official brand font), you can record a structured project waiver or inline comment:
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
4. Automatic Post-Edit Hooks Across 18+ AI Harnesses
When you run the interactive installer from your project root:
npx impeccable install
Impeccable automatically detects your installed coding harnesses and configures both the skill bundle and provider-native edit hooks:
- Claude Code (
.claude/settings.local.json): Runs the Impeccable detector hook after UI file edits and performs a deeper delta-aware pass on Stop.
- Cursor (
.cursor/hooks.json): Runs the detector on postToolUse for file writes and feeds findings directly back to the agent.
- Codex CLI (
.codex/hooks.json): Wires the detector hook alongside the .agents/skills/impeccable skill and nested asset-producer subagent.
- GitHub Copilot (
.github/hooks/impeccable.json): Shared hook configuration for both Copilot CLI and cloud agents.
- Grok Build (
.grok/hooks/impeccable.json): Scans on edit and surfaces findings to the model on Stop.
In total, Impeccable ships ready-to-use distributions for 18 tools: Cursor, Claude Code, GitHub Copilot, Codex CLI, Gemini CLI, Google Antigravity, OpenCode, Devin, DeepSeek Harness, Grok Build, Hermes Agent, Pi, Kiro, Trae, Rovo Dev, Qoder, Mistral Vibe, and Veto.
Key Takeaways
pbakaus/impeccable bridges the gap between generative UI speed and senior design engineering craft:
- Context BeforePixels: Separate durable product facts (
PRODUCT.md) from visual tokens (DESIGN.md).
- Actionable Critique: Replace vague aesthetic adjectives with 24 concrete design operations (
typeset, distill, harden, audit).
- Deterministic Enforcement: Back up LLM prompt guidance with 62 zero-cost mechanical rules (
npx impeccable detect) wired directly into your coding agent's file-edit hooks.
Explore the full documentation and rule catalog at impeccable.style and star the repository on GitHub: https://github.com/pbakaus/impeccable