Impeccable

Paul BakausCommunityCreated by Paul Bakaus

Skill
Workflow
Design and creative
Apache-2.0
Low risk
Has scripts

From the author

Use to design, redesign, critique, audit, polish or animate a frontend: websites, landing pages, dashboards, app UI, components, native iOS/Android screens, or a design system (DESIGN.md).

— the description by Paul Bakaus

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Impeccable provides a structured approach to designing, auditing, and refining frontend interfaces including websites, dashboards, and mobile applications. It operates by establishing product context through documentation and applying specific design modes—Persuade, Operate, Read, and Experience—to guide the visual and functional direction of a project. The skill supports a wide range of tasks from initial planning and documentation to technical audits, visual refinements, and animation, ensuring that design changes remain consistent with the established visual world.

What it does

Audits UI for accessibility, performance, and responsive behavior.
Generates design documentation from existing project code.
Refines visual elements through commands like colorize, typeset, and layout.
Provides tools to plan UX and UI before implementation.
Manages design system tokens and component extraction.
Supports iterative design through live variant generation and testing.

When to use it

When you need to perform a UX critique or technical audit of an existing interface.
When starting a new design surface or defining a new visual world.
When you need to polish or refine UI components before a release.
When you need to adapt an interface for different screen sizes or platforms.
When you need to add purposeful animations or improve typography hierarchy.

Advantages

Provides a consistent framework for design decisions across different project types.
Integrates technical audits directly into the design workflow.
Supports specific modes to align design output with user intent.
Enables structured documentation of product and design context.
Offers granular control over UI refinements through specialized commands.

Usage examples

“impeccable audit src/components/Dashboard.tsx”: The agent performs a technical quality check on the dashboard component, reporting on accessibility, performance, and responsiveness.
“impeccable polish src/landing-page.css”: The agent executes a final quality pass on the landing page styles to ensure visual consistency and adherence to the design system.
“impeccable animate hero-section”: The agent applies purposeful motion and animation to the specified hero section based on the project's design mode.
“impeccable init”: The agent captures the current project context and creates a PRODUCT.md file to serve as the foundation for future design work.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/pbakaus/impeccable/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip impeccable.zip -d .agents/skills

Documentation by Paul Bakaus

This skill gives you the tools and permission to make design that earns the name out-of-distribution craft. Work as an award-winning design director would: production-grade code, a clear POV, a deep grasp of what the client and its users need, and exceptional craft.

Core principles:

Finish the job. No hedging, no shortcuts: the deliverable is complete, except assets the user must provide.
Scale ambition to the surface's mode (see Modes). Persuade and Experience get full commitment: bold, distinct work with a point of view. On Operate and Read, ambition shows as precision and restraint, and patterns the visitor already knows earn their place.
Verify by looking at the rendered result at the sizes it ships at, and batch the checks: fix what one look shows before looking again, rather than screenshotting after every tweak.

Setup

Run "${CLAUDE_SKILL_DIR}/scripts/impeccable" context once per session, where ${CLAUDE_SKILL_DIR} is the directory that contains this SKILL.md (the skill folder, not a plugin root two levels above it); keep cwd at the user's project. Every "${CLAUDE_SKILL_DIR}/scripts/impeccable" <verb> command in this skill and its references resolves against that base directory. In reference files, replace the skill-base-dir placeholder with this directory before running commands; it is not a shell variable. On a Windows shell without sh, call & "${CLAUDE_SKILL_DIR}/scripts/impeccable.cmd" instead. The launcher runs a self-contained binary that ships next to it or is downloaded once on first run; no Node or other runtime is required. Pass a named source file or route as --target <path>. It loads PRODUCT.md, DESIGN.md, the matching surface brief, and native-platform guidance when applicable; follow its directives and do not rerun it.
Load the request's playbook: its Commands-table reference for an explicit/implied sub-command, or reference/new-work.md for a new surface or replacement visual world. Inspect target and incumbent visual truth before editing. When the app cannot run, start with committed visual-regression goldens or screenshot fixtures; verify target and freshness against current tokens, CSS, components, or assets, resolve conflicts, and compare theme/variant captures.
After resolving analysis and direction, read reference/craft-floor.md immediately before any UI edit, including small refinements. It carries the quality floor, the absolute bans, and the reflexes no detector catches. Do not load it for planning-only work.

Launcher unavailable: On refusal or failure, send a separate message before the next tool call: “Context loading did not run; I’ll read the existing project context directly.” Then read existing PRODUCT.md and DESIGN.md without inventing missing context, follow applicable steps 2–3, including reading reference/craft-floor.md immediately before any UI edit, and continue through permitted tools. This applies to planning and editing; launcher failure alone does not block either.

How to design

The brief wins. Honor pinned aesthetics, eras, materials, fonts, and palettes even when they conflict with a saturated-pattern warning. Redirecting a clear brief toward your taste is failure.
Refinement preserves; redesign replaces. Refinement keeps the incumbent identity, behavior, copy, and everything outside scope. Ask before replacing factual copy or adding claims. Redesign keeps product truth, content, function, native affordances, and constraints, but treats the old look as evidence and anti-reference; choose a replacement world in new-work and replace DESIGN.md. Never split the difference into polish on the discarded look.
Loaded symbols stay out of the decoration. A subject's world does not license emblems tied to militarism, supremacy, or hate movements as motifs, badges, or ornament, such as the Rising Sun flag's rays, the Confederate battle flag, or Nazi-era insignia and their stylised variants; reach for that world's neutral forms instead. Content that documents such a symbol as fact stays as it is.
Visual authority is evidence, not a filename. Missing DESIGN.md alone does not make a project greenfield; new-work decides whether to preserve, expand, or replace the incumbent world.

Modes

The mode names what the visitor's success looks like on this surface.

Persuade: the visitor decides and acts; design is the product. Landing pages, marketing, campaigns, pricing. Earn attention and action. Ship real imagery when the brief needs it; follow the committed world, not category habit.
Operate: the visitor completes a task. App UI, dashboards, editors, admin, settings, tools. Scanability, consistency, native expectations, and the real usage scene outrank expression. Brand lives in precise details.
Read: the visitor understands something. Docs, articles, guides, help, changelogs. Structure for comprehension, then make the reading experience worth staying in.
Experience: the visitor is inside the work itself. Portfolios, galleries, showcases. Let the artifact lead from the first viewport; the interface recedes.

Choose the mode from the requested surface, not the product, and persist it only in that surface brief. A tool's landing page is still Persuade; a fashion house's documentation is still Read; a docs index is Read, not Persuade. See new-work.md for new surfaces and operate.md for deeper Operate/Read guidance.

Commands

Command	Category	Description	Reference
`craft [feature]`	Build	Deprecated alias for an ordinary new-work request	reference/craft.md
`shape [feature]`	Build	Plan UX/UI before writing code	reference/shape.md
`init`	Build	Capture durable product context in PRODUCT.md	reference/init.md
`document`	Build	Generate DESIGN.md from existing project code	reference/document.md
`extract [target]`	Build	Pull reusable tokens and components into design system	reference/extract.md
`critique [target]`	Evaluate	UX design review with heuristic scoring	reference/critique.md
`audit [target]`	Evaluate	Technical quality checks (a11y, perf, responsive)	reference/audit.md · native: reference/audit.native.md
`polish [target]`	Refine	Final quality pass before shipping	reference/polish.md
`bolder [target]`	Refine	Amplify safe or bland designs	reference/bolder.md
`quieter [target]`	Refine	Tone down aggressive or overstimulating designs	reference/quieter.md
`distill [target]`	Refine	Strip to essence, remove complexity	reference/distill.md
`harden [target]`	Refine	Production-ready: errors, i18n, edge cases	reference/harden.md
`onboard [target]`	Refine	Design first-run flows, empty states, activation	reference/onboard.md
`animate [target]`	Enhance	Add purposeful animations and motion	reference/animate.md
`colorize [target]`	Enhance	Add strategic color to monochromatic UIs	reference/colorize.md
`typeset [target]`	Enhance	Improve typography hierarchy and fonts	reference/typeset.md
`layout [target]`	Enhance	Fix spacing, rhythm, and visual hierarchy	reference/layout.md
`delight [target]`	Enhance	Add personality and memorable touches	reference/delight.md
`overdrive [target]`	Enhance	Push past conventional limits	reference/overdrive.md
`clarify [target]`	Fix	Improve UX copy, labels, and error messages	reference/clarify.md
`adapt [target]`	Fix	Adapt for different devices and screen sizes	reference/adapt.md · native: reference/adapt.native.md
`optimize [target]`	Fix	Diagnose and fix UI performance	reference/optimize.md
`live`	Iterate	Visual variant mode: pick elements in the browser, iterate on alternatives	reference/live.md
`generate [n] [action] [element]`	Iterate	Variants, versions, or alternatives of a named element to choose from in the live browser; no manual picking	reference/generate.md

Routing:

No argument: read routing.md and present its context-aware menu; never auto-run a command.
Explicit or clearly implied request to run a command: load its reference (native variant on native platforms) and follow it. Ask once if two commands fit.
Workflow or command-selection question: read Workflow questions.
Otherwise: treat the request as general design work. Missing PRODUCT.md routes a new surface or replacement world through init, then new-work; a narrow refinement of existing code proceeds on the incumbent implementation as impeccable context directs, offering init afterward rather than blocking on it.
teach aliases init. craft is a deprecated alias for ordinary new-work and adds nothing. shape owns task discovery, then enters new-work only for visual-world and surface-concept decisions.

After init writes PRODUCT.md, resume without rerunning impeccable context; init loads the native platform reference itself when the platform it recorded is ios, android, or adaptive.

Pin / Unpin: "${CLAUDE_SKILL_DIR}/scripts/impeccable" pin <pin|unpin> <command> creates or removes a standalone /<command> shortcut. Report the script's result concisely; relay stderr verbatim on error.

Doctor: /impeccable doctor reports and repairs drift between this project's Impeccable artifacts (PRODUCT.md, DESIGN.md and its sidecar, config, surface briefs, the hook) and what this version reads. Load reference/doctor.md when the user invokes it, or when they ask what is out of date, stale, or needs refreshing. A CONTEXT_STALE directive in Setup's output is the cheap subset of the same report; act on it there per its own instructions rather than running doctor unasked.

Never repair drift as a side effect of a design task. A CONTEXT_STALE finding is reported, not acted on, unless the user asks. The one exception is a finding marked auto, which the next write to that file performs anyway.

Files

ATTRIBUTION.mdAdded by AutoGineer866 B
LICENSELicence file added by AutoGineer10.5 KiB
NOTICELicence file added by AutoGineer503 B
SKILL.md11.4 KiB
reference/adapt.md11.0 KiB
reference/adapt.native.md3.8 KiB
reference/android.md4.1 KiB
reference/animate.md5.1 KiB
reference/audit.md9.4 KiB
reference/audit.native.md8.1 KiB
reference/bolder.md3.4 KiB
reference/clarify.md4.5 KiB
reference/colorize.md4.4 KiB
reference/component-review.md7.8 KiB
reference/craft-floor.md4.4 KiB
reference/craft.md555 B
reference/critique.md44.5 KiB
reference/degraded/asset-producer.md8.3 KiB
reference/degraded/documenter.md3.6 KiB
reference/degraded/finish-reviewer.md15.5 KiB
reference/degraded/manual-edit-applier.md7.5 KiB
reference/delight.md3.6 KiB
reference/distill.md5.4 KiB
reference/doctor.md5.5 KiB
reference/document.md26.8 KiB
reference/extract.md3.3 KiB
reference/generate.md12.8 KiB
reference/harden.md10.5 KiB
reference/hooks.md16.9 KiB
reference/init.md11.9 KiB
reference/ios.md3.7 KiB
reference/layout.md5.0 KiB
reference/live-setup.md8.0 KiB
reference/live.md36.4 KiB
reference/mode-operate.md4.6 KiB
reference/mode-persuade.md3.6 KiB
reference/mode-read.md4.3 KiB
reference/new-work.md62.0 KiB
reference/onboard.md7.5 KiB
reference/operate.md4.0 KiB
reference/optimize.md7.4 KiB
reference/overdrive.md8.8 KiB
reference/polish.md6.5 KiB
reference/quieter.md4.8 KiB
reference/region-map.md3.3 KiB
reference/routing.md3.2 KiB
reference/shape.md3.5 KiB
reference/typeset.md6.1 KiB
reference/visualize.md13.6 KiB
scripts/VERSION7 B
scripts/command-metadata.json8.1 KiB
scripts/data/font-index-failures.json2.4 KiB
scripts/data/font-index.json1.0 MiB
scripts/engine-checksums.txt787 B
scripts/impeccableScript11.1 KiB
scripts/impeccable.cmdScript11.9 KiB
scripts/live-browser-dom.jsScript12.0 KiB
scripts/live-browser-ignores.jsScript10.2 KiB
scripts/live-browser-session.jsScript5.7 KiB
scripts/live-browser.jsScript550.0 KiB
scripts/modern-screenshot.umd.jsScript28.6 KiB

reference/generate.md

Additional context needed: only the target element, when the request does not name one that resolves uniquely on the page.

Generate is the fast lane into live mode: the user names an element, a direction, and a count in one sentence, and within a minute they are cycling through variants in their browser. One command boots the helper, hands the element to the overlay in the page your harness already shows (it scrolls to it, selects it, and fires the same Go a click fires) and returns the generate event; one edit writes the variants; one call replies and waits for the user's choice, which the helper bakes into source itself. This file owns the lane's plumbing; from the event onward the design work is live.md's, unchanged, so read it in full now if you have not this session.

Web only. Live mode's browser overlay has no native equivalent; on ios / android / adaptive projects, decline this command and offer bolder or quieter on the source instead.

The plumbing is where the lane saves time: one command starts the session around the page your harness already shows, one call replies and waits, and nothing here is a browser you have to babysit. The design work is not where it saves time. Setup runs as for any command (impeccable context, this reference, craft-floor.md before the edit), and the variants are planned, written, and accepted exactly the way a live session plans, writes, and accepts them.

Three prohibitions cover the known ways this command goes wrong:

Never run init or document, and never ask for PRODUCT.md or DESIGN.md. When they exist, the start command prints them under boot and you use them. When they do not, it says so (contextMissing, contextNote) and you extract the identity from the event (Step 3). A missing file is never a reason to interview the user inside this command; offer init in one line after the session ends.
Never hand-write a variants wrapper or invent a session id. Only the browser mints session ids (8 hex characters, at Go). A missing event is fixed by rerunning Step 2, never with a direct source edit.
Do not act on hook findings while live markers are in the file, and do not restyle variants to appease them; the accept verifies the file once the variant is permanent.

Step 1: Parse the request

Three parts, all from the user's sentence:

A number in the request: that is the count. No number: 3. The protocol caps count at 8.
The direction wording maps onto the live action vocabulary; never invent a new action value:
- bold, bolder, stronger, punchier: bolder
- quiet, calmer, softer, toned down: quieter
- simpler, minimal, stripped: distill
- refined, tightened, polished: polish
- font and type words: typeset
- color words: colorize
- arrangement and spacing words: layout
- device and breakpoint words: adapt
- motion words: animate
- playful words: delight
- rule-breaking words: overdrive
- Wording that carries intent but no vocabulary word ("make it feel like a bank", "warmer", "more premium"): impeccable, with the user's wording passed as the prompt.
- An action fits AND extra intent rides along ("bolder, but keep it monochrome"): that action, with the rest as the prompt.
- The wording names no direction at all ("better", "improve", "nicer", "different", "fresh", "new", "redesign", "fix", "some options", "ideas", "alternatives", or just "variants" with nothing else): Ask with the AskUserQuestion tool and wait for the answer before continuing. Ask one question, offering the vocabulary: "Which direction should the variants take? bolder, quieter, simpler (distill), polished, typography (typeset), color (colorize), layout, motion (animate), playful (delight), or rule-breaking (overdrive)." Map the answer with this list; an answer that is still open ("surprise me", "you pick") is impeccable with the user's original wording as the prompt, and Step 2 starts on that answer.
The element description ("the pricing cards", "the hero heading"): Step 2 resolves it to a selector.

Done when you hold an action from the vocabulary (asked for, when the request named no direction), a count from 1 to 8, and the element description.

Step 2: Reuse the page, then start

Reuse the dev server already running and the tab your harness already shows it in; a second server or a second browser window is the failure this step prevents.

Find the dev server, cheapest source first, and stop at the first hit: the user's message, a browser tab already on the app (Claude Code: an origin in tabs_context), a server your harness started (Claude Code: preview_list), a terminal that printed its URL. Its origin is your --dev-url. No hit: leave --dev-url off and run the start command with no wait; the boot probes for a running server and its verdict names the move. browser_needed carries the devUrl it found: open it as in 2, then rerun with --dev-url <devUrl> --wait-for-browser 60000. no_dev_server means nothing serves the app: start the dev script the way the verdict says (Claude Code: preview_start; Cursor: a background terminal; Codex: an exec you yield from), wait for its URL, then rerun with --dev-url <url>.
Open the page that renders the element in your browser, then start. The route the request names, else the one --target serves; --dev-url takes only the origin.
- Cursor (browser_navigate) and Claude Code (navigate, which opens the Browser pane when it is closed and takes the tabId from tabs_context when a tab is already on that origin): open the URL, then run the start command with --dev-url <url> --wait-for-browser 60000. The boot injects the overlay and the page reloads into it while the command waits. Your browser tool is the only opener on these harnesses; the engine ignores --open there.
- No browser tool (Codex, others): run the start command with --open --wait-for-browser 120000; it opens the system browser, and the longer wait covers the user finding the tab. browser_open_failed back: tell the user the url in one line and rerun with --wait-for-browser 120000.

"<skill-base-dir>/scripts/impeccable" live-generate --target src/App.jsx --dev-url http://127.0.0.1:5173/ --selector ".pricing-grid" --action bolder --count 3 --boot --wait-for-browser 60000

Run it in the foreground in Cursor and Claude Code (it returns within the wait); on Codex, in an exec you yield from, the way Step 3 runs the poll.

--target: the file that renders the element when the request or the project makes it obvious; skip it otherwise.
--dev-url: the origin from 1; omit it and the boot probes.
--selector: a unique class first, then a landmark tag plus class, an id last (every variant mounts a copy of the element, so an id repeats in the DOM). The request names a repeated component in plural ("the pricing cards"): target the container that holds the set, so one scoped stylesheet restyles every instance. One read of the source file that renders the element is allowed when the selector is not obvious; --dry-run resolves and reports without starting anything when it is not certain.
--boot: runs the lane's boot (PRODUCT.md and DESIGN.md loaded again for the helper, missing files tolerated, dev URL found, bottom bar hidden for the helper's lifetime) and reuses a helper that is already running. Its result rides along as boot.
Also available: --prompt, --text (keep only matches whose visible text contains a snippet), --index (1-based pick among matches).

Read the output in this order: boot (or boot.contextMissing with boot.contextNote: the page is the source of truth, per the note), then event, the generate event for sessionId, with the same _instructions a user's Go gets. Every verdict carries _instructions, and they win over your recollection of this file; the ones whose move is a decision of yours:

ambiguous: the candidates are listed; target their common container, or rerun with --text "<visible text>" or --index <n>.
dev_server_gone: the dev server stopped answering while the command waited for the page (on Cursor, a server another chat started dies with that chat). Start it the way the verdict says, then rerun with --dev-url <url>.
no_match: the tab is on a route that does not render the element (navigate to the right route, rerun), or the selector is wrong (derive a better one from the source, or add --text).
config_missing / config_invalid under bootError: follow live-setup.md first, then rerun.
event: null with ok: true: the event was slower than the wait; run "<skill-base-dir>/scripts/impeccable" live-poll once to collect it, then continue.

Done when the output shows ok: true, a sessionId, and an event, reached with at most one server started and one tab opened by you.

Step 3: Generate

The event is a standard generate event: the picked element's context, a preflighted scaffold, and _instructions naming the action's reference, the planning section, and the exact splice. Handle it exactly per live.md's Handle generate, which owns everything from the identity lock to the done reply: read the action's reference and craft-floor.md as it says, plan per section 4 (identity first, then mode, then three different primary axes, then the squint test), declare knobs per section 7, and deliver per section 6 (a complete replacement of the element per variant, the preview CSS plus every variant in one edit at the scaffold's splice). The lane changes nothing about what a variant may be: the moves a live session would make on this element (a promoted tier, a restructured set, a reordered card, a different surface) are open here too. Never screenshot the page; the overlay preview is the review channel until accept.

Reply and wait in one call, with the file you wrote:

"<skill-base-dir>/scripts/impeccable" live-poll --reply EVENT_ID done --file src/App.jsx --then-poll

This replies done (the browser mounts the variants) and then blocks until the user's choice arrives, so run it the way your harness runs a long wait: Claude Code in the foreground with your tool's longest timeout (600000 ms), so you are paused until the choice arrives; Codex in a yielded foreground exec; Cursor in a background terminal with notify on "type":"(accept|discard|variant_mount_failed|exit)". Never pass a short --timeout=. While it runs there is nothing else to do: never sleep and never poll its output on a timer; a harness that backgrounds it wakes you when it returns. {"type":"timeout"} means the user has not chosen yet: run live-poll again and keep waiting. If the edit fails after the browser flipped to GENERATING, --reply EVENT_ID error "Short reason" (without --then-poll) so the bar resets.

Then tell the user, in one line, where their variants are: "Three [bolder] variants are live on [the pricing cards]: cycle with the floating bar's arrows, adjust the Tune knobs, and Accept the keeper."

Outside the replace path, read the matching live.md section before acting: scaffold.previewMode: "svelte-component" (Svelte previews are edited as components, and their accept is mechanical), mode: "insert", variant_mount_failed, steer, manual_edit_apply, and any fallback: "agent-driven" wrap error.

Step 4: Accept and close

The call from Step 3 returns the user's choice. discard: nothing to do. accept: _acceptResult.carbonize: true is the normal case, and the cleanup is live.md's Required after accept, unchanged: move the accepted variant's rules into the stylesheet that already owns the element with real selectors, bake the chosen knob values in, unwrap the element and drop every data-impeccable-* attribute, delete the inline <style> block and both impeccable-carbonize markers, then "<skill-base-dir>/scripts/impeccable" live-complete --id SESSION_ID and confirm phase: "completed". (baked: true appears only when the accept was run with --bake; then the helper already made the variant permanent and no live-complete is owed.)

Close without being asked, the moment the choice is handled:

"<skill-base-dir>/scripts/impeccable" live-server stop

Stopping removes the injected script and reloads the page once: the user sees the accepted design with no overlay chrome, still served by their dev server. Never kill or restart the dev server, including one you started in Step 2.

The user asks for more variants before you closed: skip the close, run Step 2 again for the next element (the helper is reused), and close after the last choice.
Interrupted or unsure of the state: "<skill-base-dir>/scripts/impeccable" live-status, then live-resume; the journal under .impeccable/live/sessions/ is canonical.

Done when the helper is stopped and the dev site still answers with the accepted design.

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Claude Code frontmatter, Needs Node.js

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Paul Bakaus

Publisher

Paul Bakaus (Community)

Source

pbakaus/impeccable · plugin/skills/impeccable · commit 687bc38

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
NOTICE (added by AutoGineer from NOTICE.md)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by Paul Bakaus.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download impeccable.zip