One Open Source Project a Day (No. 238): Impeccable — Teaching Every AI Coding Tool to Have Taste

Introduction

"The design language that makes your AI harness better at design."

This is the 238th article in the "One Open Source Project a Day" series. Today's project is Impeccable — a design language tool built specifically for AI coding assistants.

AI-generated frontend interfaces share a well-known problem: every model trained on the same SaaS templates. The result is a predictable set of "tells" — Inter font everywhere, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, and that rounded-square icon tile sitting above every heading. These "AI smell" features have become an open secret in the industry — a dead giveaway at a glance.

Impeccable's answer splits design judgment into two separate mechanisms: a set of 59 deterministic detection rules that don't depend on an LLM, runnable directly from the CLI or browser extension without needing an API key, and a set of LLM-driven critique checks, invoked through natural-language Skill commands that drive deeper UX review and polish. The project is upfront about its origin, acknowledging it grew out of Anthropic's frontend-design Skill. 81.3k Stars, Apache-2.0 License, created by Paul Bakaus.

What You Will Learn

• How Impeccable's "deterministic rules + LLM critique" two-track system tackles AI design homogenization
• The complete design workflow covered by its 24 commands, from init and craft to polish and audit
• Why PRODUCT.md and DESIGN.md are kept separate — durable product facts vs. visual systems
• The trade-off between comp-first and code-first build paths
• How a core engine binary plus lightweight launcher scripts adapt across a dozen different tools

Prerequisites

• Basic frontend development experience (HTML/CSS/JS)
• Having used Claude Code, Cursor, or a similar AI coding tool
• A basic awareness of the "AI-generated design homogenization" phenomenon

Project Background

What It Is

Impeccable's official positioning: "The design language that makes your AI harness better at design." The project names the root cause directly: every model is trained on the same SaaS templates, producing the same "tells" in AI-generated designs — Inter font everywhere, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.

The project's origin story is stated plainly: "Anthropic's frontend-design was the first widely-used design skill for Claude. Impeccable started from there."

Team and Background

• Author: Paul Bakaus (GitHub: pbakaus)
• License: Apache-2.0
• Tech stack: Rust (core engine) + Bun/Node (CLI install and adapters) + browser extension + VS Code plugin
• Engine distribution: a self-contained binary, downloaded to ~/.impeccable/bin/ on first run

Project Stats

• ⭐ GitHub Stars: 81,300+
• 🍴 Forks: 4,900+
• 👀 Watchers: 214
• 📄 License: Apache-2.0

What It Does

The Problem It Solves

Common symptoms of AI-generated frontends without Impeccable:
  All models trained on the same source data → design output
  converges heavily
  ↓ Inter font overuse, purple-blue gradients, cards nested in cards,
    gray text on colored backgrounds
  ↓ developers manually adjust by feel, with no systematic detection
    or polish workflow
  ↑ the "dead giveaway" AI design signature is hard to shake
 
Impeccable's approach:
  59 deterministic rules + LLM deep critique, running in parallel
  ↓ CLI/browser extension detects directly, no LLM dependency, no API
    key needed
  ↓ Skill commands drive the AI through the full workflow, from
    product-context gathering to final polish
  ↑ design judgment gets structured into reusable, auditable rules
    and processes

Use Cases

1. Developers building frontends with AI coding tools who want to shed "AI smell" design

   • Use deterministic rules to quickly flag typical AI slop signatures like purple-blue gradients and nested cards

2. Teams needing accessibility, performance, and responsive design review before launch

   • The audit command provides technical quality checks across accessibility, performance, and responsiveness

3. Teams that want to systematically document product context and visual systems

   • init generates PRODUCT.md recording product facts; document generates DESIGN.md from existing project code

4. Designers/developers who want to iterate on visuals live in the browser

   • live mode supports generating and selecting design variants live in the browser

5. Teams collaborating across multiple AI coding tools who need a unified design language

   • One engine adapts to Claude Code, Cursor, Codex, Gemini CLI, Grok Build, and a dozen other tools

Quick Start

Recommended installation:

npx impeccable install

Update:

npx impeccable update

Installing as a Git submodule (for teams that need version pinning):

git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor

Direct CLI detection (no Skill, no LLM needed):

npx impeccable detect src/
npx impeccable detect https://example.com
npx impeccable detect --json .

Invoking via Skill inside an AI tool:

/impeccable init
/impeccable audit blog
/impeccable polish settings

Core Features

1. A Unified Skill Entry Point and 24 Commands

All capabilities are invoked through the unified /impeccable <command> <target> syntax, covering the full design lifecycle from planning to launch:

Also supports /impeccable pin <command> to create a standalone shortcut (e.g., pin audit creates /audit).

2. 59 Deterministic Detection Rules

Split into two categories: AI slop (side-tab borders, purple gradients, bounce easing, dark glows, etc.) and general design quality (line length, cramped padding, small touch targets, skipped headings, etc.). These rules run directly from the CLI and browser extension, with no LLM dependency and no API key required — meaning detection itself is deterministic, free, and can run in any CI pipeline.

3. Separation of Duties Between PRODUCT.md and DESIGN.md

• PRODUCT.md: records "durable product truth" — audience, purpose, operating context, constraints, tone, and evidence — generated by init, explicitly required to be kept separate from "surface-level visual direction"
• DESIGN.md: records the incumbent or newly built visual system, generated from existing project code via document

4. A Core Engine + Lightweight Launchers Architecture for Multi-Tool Support

The core is a self-contained "engine binary," downloaded to ~/.impeccable/bin/ on first run; tools like Claude Code, Cursor, and Codex each invoke it through a small launcher script. Node.js is only used during the npx install step, not as a runtime dependency. Supports a hook mechanism that triggers design detection after file edits or on Stop events.

5. A List of Anti-Patterns

The documentation directly lists specific practices to avoid: avoid overused fonts (Arial, Inter, system defaults); avoid gray text on colored backgrounds; avoid pure black/pure gray (should always carry a hue); avoid wrapping everything in cards, or nesting cards within cards; avoid bounce/elastic easing animations.

A Deeper Look

Splitting the Two Tracks: Deterministic Rules Solve "What Can Be Detected," LLM Review Solves "How It Should Change"

The most notable architectural decision in Impeccable is splitting "design judgment" into two independent tracks, rather than having a single LLM call shoulder all the work:

If all detection depended on an LLM:
  Every detection run requires a model call → cost and latency become
  unpredictable
  ↑ can't run freely and deterministically inside a CI pipeline
  ↑ results may vary unpredictably across model versions/prompt
    differences
 
Impeccable's two-track split:
  59 deterministic rules → run directly via CLI/browser extension, no
  LLM dependency
  ↓ free, deterministic, embeddable in CI, specifically catches fixed
    "AI slop" signatures
  LLM-only critique checks → driven by Skill commands, handle more
    subjective UX judgment
  ↓ handle questions like "is the hierarchy clear" or "does this
    resonate emotionally" that fixed rules can't capture
  ↑ the two tracks complement each other, instead of forcing one
    mechanism to cover every scenario

The logic behind this split is clear: the "homogenization signatures" of AI-generated design (purple-blue gradients, cards nested in cards) are fundamentally a pattern-recognition problem, which a rule engine solves more cheaply and reliably than an LLM; while questions like "is this design persuasive" or "is the copy clear" require contextual understanding, which is better left to an LLM. Separating the two preserves detection repeatability without sacrificing the flexibility needed for deeper review.

Separating PRODUCT.md from DESIGN.md: Preventing "Product Truth" From Being Contaminated by "Visual Trends"

The project explicitly requires that the "durable product truth" recorded in PRODUCT.md be kept separate from "surface-level visual direction" — visitor mode and visual direction are chosen per page/scenario, not written into PRODUCT.md. This is an easily overlooked but critical design decision:

If product context and visual direction were mixed in one file:
  Every visual style adjustment risks contaminating the product
  positioning description
  ↑ the AI might mistake "currently trendy visual choices" for
    "immutable product requirements" in later iterations
 
Impeccable's separation strategy:
  PRODUCT.md only records facts that don't change with visual
  trends — audience/purpose/constraints/tone
  ↓ DESIGN.md separately records the visual system, which can be torn
    down and rebuilt at any time
  ↑ when making design decisions, the AI won't mistake a "temporary
    visual choice" for an "immutable product constraint"

This separation lets "what the product is" and "what the product currently looks like" evolve as two independent concepts — a key design choice for preventing long-term semantic drift in a document system meant to be read and referenced repeatedly by an AI.

Comp-First vs. Code-First: Choosing the Build Path by Content Type, Not One-Size-Fits-All

The documentation distinguishes between two build paths: "composing a full comp first, then building to match it" (comp-first) and "writing code directly, encoding the direction contract into development state and validating it on completion" (code-first). The documented trade-off: "Comp-first composes bolder and takes longer; code-first is leaner and faster."

Notably, app interfaces and documentation-style pages always use code-first, with the stated reason being "they come out better built than pictured." This reflects a pragmatic judgment: not every design task is worth comping out before building — highly structured content with clear interaction logic (apps, docs) benefits more from direct coding, while content requiring bold visual expression is where exploring direction via comp pays off.

From Anthropic's frontend-design to an Independent Project: Honestly Acknowledging the Origin Instead of Obscuring the Lineage

Impeccable's documentation opens by acknowledging it grew out of Anthropic's frontend-design Skill — a commendable detail of open-source collaboration etiquette. Many projects absorb design ideas from elsewhere without systematically documenting "where this idea originally came from" in their own docs. Impeccable puts that lineage out in the open, which both respects the original creators and makes it easier for users to understand where this project sits within the broader "AI design Skill" ecosystem — it didn't appear out of nowhere, but built out a more complete engineering capability — a deterministic rule engine, multi-tool adaptation, live browser iteration — on top of an already-validated design pattern.

Multi-Tool Adaptation: Decoupling the Core Engine From the Adapter Layer, Instead of Rewriting Per Tool

The project supports Cursor, Claude Code, GitHub Copilot, Gemini CLI, Codex CLI, Grok Build, Hermes Agent, OpenCode, Trae, Rovo Dev, Qoder, Mistral Vibe, and more — but there's only one implementation of the core logic: the self-contained engine binary. Each tool just needs a small launcher script to invoke this engine, while hook configuration is adapted per tool's own mechanism (different tools use different hook config file formats). This "one core implementation, adapter layer expands as needed" architecture avoids the maintenance burden of re-implementing the same design detection logic across a dozen-plus tool ecosystems.

Project Links and Resources

Official Resources

• 🌟 GitHub: pbakaus/impeccable
• 📄 License: Apache-2.0

Related Resources

• Anthropic's frontend-design Skill — the starting point for Impeccable's design thinking
• Supported tool ecosystem: Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex CLI, Grok Build, Hermes Agent, OpenCode, Trae, Rovo Dev, Qoder, Mistral Vibe

Summary

Key Takeaways

1. A deterministic-rules-plus-LLM-review two-track mechanism: 59 rules catch AI slop signatures for free and deterministically, while LLM review handles more subjective UX judgment — the two complement rather than replace each other
2. PRODUCT.md and DESIGN.md are kept separate by design: product truth and visual systems are documented independently, preventing visual trends from contaminating the long-term semantics of product positioning
3. Comp-first vs. code-first chosen by content type: app and documentation interfaces favor code-first for reliability; only content requiring bold visual expression is worth comping out first
4. Honest acknowledgment of the design lineage's starting point: grew out of Anthropic's frontend-design rather than obscuring that lineage and claiming pure originality
5. The core engine is decoupled from the multi-tool adapter layer: one engine implementation, reused across a dozen-plus tools through lightweight launchers, avoiding duplicated maintenance

Who This Is For

• Developers building frontends with AI coding tools who want to shed "AI smell" design: deterministic rules can quickly flag typical homogenization signatures
• Teams that need to walk through the full design process systematically: 24 commands cover the full lifecycle, from product-context gathering to accessibility/performance review
• Teams using multiple AI coding tools simultaneously: one engine adapts to a dozen-plus tools, keeping the design language consistent across all of them
• Developers tracking the evolution of design patterns in the AI tooling ecosystem: can reference its architecture of splitting a deterministic rule engine from LLM review

One-Line Verdict

Instead of trying to solve "AI design homogenization" with a smarter LLM call, Impeccable hands the parts that can be detected deterministically to a free, repeatable rule engine, and leaves the parts that require contextual understanding to LLM review — this "divide the labor instead of throwing more compute at it" approach may be more realistic than simply relying on a stronger model.

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage