Impeccable: A Structured Design Workflow for AI-Generated Websites
Impeccable is a design quality toolchain created by Paul Bakaus (creator of jQuery UI) that gives AI coding agents a structured framework for producing considered, non-generic web designs. It addresses a specific failure mode: AI agents tend to generate code that assembles familiar patterns into generic layouts rather than producing designs with a coherent visual identity.
The tool provides a shared vocabulary between developer and agent through 23 specialized commands encoding design disciplines, and it actively steers the agent away from 37 identified design anti-patterns related to layout, typography, color, and contrast.
The brand vs. product distinction
One of the first concepts Impeccable introduces is "register": whether a design is a brand surface or a product surface. This distinction shapes all subsequent design decisions.
Brand surfaces are where design is the product: marketing pages, landing pages, portfolios, editorial content. The priority is distinctiveness and emotional impact, typically through expressive typography, unique layouts, and motion.
Product surfaces are where design serves the product: app UIs, dashboards, admin panels, utility tools. The priority is clarity, familiarity, and efficiency, typically through clean sans-serif fonts, standard layouts, and predictable hierarchy.
Establishing this early prevents the agent from producing a design that is an awkward average of the two.
The four-stage workflow
Impeccable structures the process into four stages: Teach, Shape, Craft, and Iterate. Each stage produces an artifact that the next stage uses as input.
Stage 1: Teach
The /impeccable teach command runs a structured interview and saves the results to PRODUCT.md. This file becomes the persistent context for all subsequent commands, preventing the agent from losing track of the project's identity across long sessions.
The interview covers two rounds.
Round 1 establishes foundational decisions: - Register (brand or product surface) - What the site is for - The single thing a visitor should walk away with
Round 2 gathers nuanced details: - Brand personality in three words - References (sites whose aesthetic to emulate) and anti-references (aesthetics to avoid) - Audience definition with enough specificity to inform language, complexity, and visual metaphors
References and anti-references are more effective than abstract descriptors like "modern" or "clean." Naming specific sites like linear.app or raycast.com as references, and "AI-tool neon gradients" as an anti-reference, gives the agent concrete guidance.
The resulting PRODUCT.md captures register, audience, personality, references, and core design principles. Every subsequent command reads this file to stay aligned with the project's identity.
Stage 2: Shape
The /impeccable shape command reads PRODUCT.md and asks questions focused on visual execution. The output is a Design Brief that serves as the blueprint for the Craft stage.
A notable feature of this stage is probes: visual mockups generated by an image model to explore different aesthetic directions before committing to one. When using an agent without a native image model (such as Claude Code), the user can direct Impeccable to use an external API like gpt-image-2 to generate the probes. Impeccable generates several distinct visual concepts for the page.
After selecting a preferred probe and answering questions about color strategy, page scope, and tech stack, Impeccable compiles a Design Brief. This is a multi-part document specifying feature summary, primary call-to-action, color strategy with exact OKLCH values, surface and accent colors, typography choices, page section scope, and content notes including headlines and FAQ text.
Stage 3: Craft
The /impeccable craft command reads both PRODUCT.md and the Design Brief and generates the complete site. For a project using Astro and Tailwind CSS, it creates the project file structure, writes component code, configures astro.config.mjs and tailwind.config.mjs, installs dependencies, and starts a development server.
The full process from command to a running development server takes approximately five minutes for a complete homepage.
Stage 4: Iterate with Live mode
The /impeccable live command injects a script into the project, starts a proxy server between the browser and the dev server, and adds a UI overlay to the live site.
To make a change, click any element on the page. A purple outline confirms the selection and a small widget appears.
Type a natural language description of the desired change in the widget. Impeccable sends only the relevant code snippet and the instruction to the agent, not the entire project. The agent generates several variants. The widget displays them and lets you click through each to see the change rendered live.
Clicking Accept writes the change to the source files. The cycle is: select an element, describe the change, preview variants, accept. No terminal interaction or manual file editing is required.
Final thoughts
Impeccable's core contribution is workflow structure. Without it, prompting an AI to build a website produces one-off results whose quality depends entirely on prompt quality and the agent's training distribution. With it, each stage produces a concrete artifact (PRODUCT.md, Design Brief, source code, live site) that the next stage builds on, and each stage constrains the problem space in ways that reduce the probability of generic output.
The live editing mode is the most practically useful feature for iterative refinement. Targeting a specific element and generating variants without re-explaining the project context is meaningfully faster than the alternative of writing targeted prompts in a terminal and waiting for full re-renders.
The tool is model-agnostic. Any agent capable of running slash commands can be used, with the caveat that agents without native image generation require an external API for probe generation.
Documentation and installation instructions are at impeccable.design.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.