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/audit.md

Run systematic technical quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.

This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.

Web only. Native platforms (ios / android / adaptive) route to audit.native.md instead; if the project is native, switch to it now.

Diagnostic Scan

Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.

Check for:

Contrast issues: Text contrast ratios < 4.5:1, or < 3:1 for large text (or 7:1 for AAA)
Motion sensitivity: prefers-reduced-motion needs an intentional alternative that preserves state change and hierarchy; flag a global 0.01ms kill that destroys useful feedback, flashing above threshold, and motion that blocks focus, reading, or task completion
Missing ARIA: Interactive elements without proper roles, labels, or states
Keyboard navigation: Missing focus indicators, illogical tab order, keyboard traps
Semantic HTML: Improper heading hierarchy, missing landmarks, divs instead of buttons
Alt text: Missing or poor image descriptions
Form issues: Inputs without labels, poor error messaging, missing required indicators

Score 0-4: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA)

2. Performance

Check for:

Layout thrashing: Reading/writing layout properties in loops
Expensive animations: Casual layout-property animation, unbounded blur/filter/shadow effects, or effects that visibly drop frames
Missing optimization: Images without lazy loading, unoptimized assets
will-change overuse: will-change applied broadly or left on at rest (it is a targeted hint for known expensive animations, not a baseline requirement)
Bundle size: Unnecessary imports, unused dependencies
Render performance: Unnecessary re-renders, missing memoization

Score 0-4: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized)

3. Theming

Check for:

Hard-coded colors: Colors not using design tokens
Broken dark mode: Missing dark mode variants, poor contrast in dark theme
Inconsistent tokens: Using wrong tokens, mixing token types
Theme switching issues: Values that don't update on theme change

Score 0-4: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly)

4. Responsive Design

Check for:

Fixed widths: Hard-coded widths that break on mobile
Touch targets: Interactive elements < 44x44px. WCAG AA (SC 2.5.8) requires at least 24x24 CSS px unless an exception applies: spacing, an equivalent control, inline text, user-agent styling, or an essential size. Spacing passes when a 24 CSS px circle centered on the target's bounding box overlaps no other target and no other undersized target's circle
Broken touch interaction: Custom sliders, drag surfaces, and scrollable control strips whose primary gesture fails under touch, that swallow page scroll or lose the drag to it, or that stay stuck after an interrupted gesture. Code tells: mouse-only handlers, no touch-action on a pointer-event drag surface, drag state that nothing clears on cancel, lost capture, or blur. Exercise the gesture when a browser tool can synthesize touch (a rendered viewport proves layout, not the gesture), then say what produced the evidence (emulated viewport, synthesized touch, which engine, physical device) and what stayed untested
Horizontal scroll: Content overflow on narrow viewports
Text scaling: Layouts that break when text size increases
Missing breakpoints: No mobile/tablet variants

Score 0-4: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets, gestures work under touch)

5. Implementation Integrity (CRITICAL)

Run the bundled detector and verify each finding in context. Look for repeated implementation shortcuts, design-system drift, misleading or decorative content, and structure that is interchangeable with an unrelated product. Keep deterministic findings separate from visual judgment and call out false positives.

Desktop apps (Electron, NW.js, CEF, WebView2): launch the app with a local DevTools port (--remote-debugging-port=9222, or WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222 for WebView2; keep it on 127.0.0.1, never exposed), seed the state to audit, keep the window on screen (a hidden one skips the pixel contrast reads), then run "<skill-base-dir>/scripts/impeccable" detect --cdp 9222 --target <part of the page URL or title> --json. It returns the same JSON as a URL scan and leaves the window as found. Take screenshots through the harness's CDP tooling, and leave the window as you found it too. Tauri on macOS (WKWebView) and on Linux (WebKitGTK) expose no CDP: scan the source and say the rendered check did not run.

Score 0-4: 0=systemic drift, 1=major repeated failures, 2=several verified issues, 3=minor isolated issues, 4=coherent and intentional

Generate Report

Audit Health Score

#	Dimension	Score	Key Finding
1	Accessibility	?	[most critical a11y issue or "--"]
2	Performance	?
3	Theming	?
4	Responsive Design	?
5	Implementation Integrity	?
Total		??/20	[Rating band]

Rating bands: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)

Implementation Integrity Verdict

Start here. Pass/fail: does the implementation express a coherent product-specific system? Cite verified evidence and detector findings.

Executive Summary

Audit Health Score: ??/20 ([rating band])
Total issues found (count by severity: P0/P1/P2/P3)
Top 3-5 critical issues
Recommended next steps

Detailed Findings by Severity

Tag every issue with P0-P3 severity:

P0 Blocking: Prevents task completion. Fix immediately
P1 Major: Significant difficulty or WCAG AA violation. Fix before release
P2 Minor: Annoyance, workaround exists. Fix in next pass
P3 Polish: Nice-to-fix, no real user impact. Fix if time permits

For each issue, document:

[P?] Issue name
Location: Component, file, line
Category: Accessibility / Performance / Theming / Responsive / Implementation Integrity
Impact: How it affects users
WCAG/Standard: Which standard it violates (if applicable)
Recommendation: How to fix it
Suggested command: Which command to use (prefer: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)

Patterns & Systemic Issues

Identify recurring problems that indicate systemic gaps rather than one-off mistakes:

"Hard-coded colors appear in 15+ components, should use design tokens"
"Touch targets consistently too small (<44px) throughout mobile experience"

Positive Findings

Note what's working well: good practices to maintain and replicate.

Recommended Actions

List recommended commands in priority order (P0 first, then P1, then P2):

[P?] /command-name: Brief description (specific context from audit findings)
[P?] /command-name: Brief description (specific context)

Rules: Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset. Map findings to the most appropriate command. End with /impeccable polish as the final step if any fixes were recommended.

After presenting the summary, tell the user:

You can ask me to run these one at a time, all at once, or in any order you prefer.
Re-run /impeccable audit after fixes to see your score improve.

Keep P3s few: a long tail of minor issues buries the ones that matter.

Avoid:

Report issues without explaining impact (why does this matter?)
Provide generic recommendations (be specific and actionable)
Skip positive findings (celebrate what works)
Forget to prioritize (everything can't be P0)
Report false positives without verification

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

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Paul Bakaus

Setup

How to design

Modes

Commands

Files

reference/audit.md

Diagnostic Scan

1. Accessibility (A11y)

2. Performance

3. Theming

4. Responsive Design

5. Implementation Integrity (CRITICAL)

Generate Report

Audit Health Score

Implementation Integrity Verdict

Executive Summary

Detailed Findings by Severity

Patterns & Systemic Issues

Positive Findings

Recommended Actions

Requirements and compatibility

Security

Attribution and licence

Related skills

Theme Factory

Brand Guidelines

Frontend Design

Diagram Design

Choreograph

Apple Design

Download ZIP