AutoGineer
Generated banner for Impeccable
Generated logo for Impeccable

Impeccable

Paul BakausCommunityCreated by Paul Bakaus

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

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

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/pbakaus/impeccable/download

  2. 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

  1. 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.

  2. 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.

  3. 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

CommandCategoryDescriptionReference
craft [feature]BuildDeprecated alias for an ordinary new-work requestreference/craft.md
shape [feature]BuildPlan UX/UI before writing codereference/shape.md
initBuildCapture durable product context in PRODUCT.mdreference/init.md
documentBuildGenerate DESIGN.md from existing project codereference/document.md
extract [target]BuildPull reusable tokens and components into design systemreference/extract.md
critique [target]EvaluateUX design review with heuristic scoringreference/critique.md
audit [target]EvaluateTechnical quality checks (a11y, perf, responsive)reference/audit.md · native: reference/audit.native.md
polish [target]RefineFinal quality pass before shippingreference/polish.md
bolder [target]RefineAmplify safe or bland designsreference/bolder.md
quieter [target]RefineTone down aggressive or overstimulating designsreference/quieter.md
distill [target]RefineStrip to essence, remove complexityreference/distill.md
harden [target]RefineProduction-ready: errors, i18n, edge casesreference/harden.md
onboard [target]RefineDesign first-run flows, empty states, activationreference/onboard.md
animate [target]EnhanceAdd purposeful animations and motionreference/animate.md
colorize [target]EnhanceAdd strategic color to monochromatic UIsreference/colorize.md
typeset [target]EnhanceImprove typography hierarchy and fontsreference/typeset.md
layout [target]EnhanceFix spacing, rhythm, and visual hierarchyreference/layout.md
delight [target]EnhanceAdd personality and memorable touchesreference/delight.md
overdrive [target]EnhancePush past conventional limitsreference/overdrive.md
clarify [target]FixImprove UX copy, labels, and error messagesreference/clarify.md
adapt [target]FixAdapt for different devices and screen sizesreference/adapt.md · native: reference/adapt.native.md
optimize [target]FixDiagnose and fix UI performancereference/optimize.md
liveIterateVisual variant mode: pick elements in the browser, iterate on alternativesreference/live.md
generate [n] [action] [element]IterateVariants, versions, or alternatives of a named element to choose from in the live browser; no manual pickingreference/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.

Hooks: /impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset> manages the design detector hook for this project (auto-runs the detector after UI file edits and surfaces findings). Load reference/hooks.md when the user invokes it with any argument.

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

reference/optimize.md

Performance is a feature. Identify the actual bottleneck for THIS interface, fix it, then measure. Don't optimize what isn't slow.

Assess Performance Issues

Understand current performance and identify problems:

  1. Measure current state:

    • Core Web Vitals: LCP, INP, CLS scores

    • Load time: Time to interactive, first contentful paint

    • Bundle size: JavaScript, CSS, image sizes

    • Runtime performance: Frame rate, memory usage, CPU usage

    • Network: Request count, payload sizes, waterfall

  2. Identify bottlenecks:

    • What's slow? (Initial load? Interactions? Animations?)

    • What's causing it? (Large images? Expensive JavaScript? Layout thrashing?)

    • How bad is it? (Perceivable? Annoying? Blocking?)

    • Who's affected? (All users? Mobile only? Slow connections?)

Measure before and after. Optimizing without a measurement spends effort on things that do not matter.

Optimization Strategy

Create systematic improvement plan:

Loading Performance

Optimize Images:

  • Use modern formats (WebP, AVIF)

  • Proper sizing (don't load 3000px image for 300px display)

  • Lazy loading for below-fold images

  • Responsive images (srcset, picture element)

  • Compress images (80-85% quality is usually imperceptible)

  • Use CDN for faster delivery

<img 
  src="hero.webp"
  srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
  sizes="(max-width: 400px) 400px, (max-width: 800px) 800px, 1200px"
  alt="Hero image"
/>

Reduce JavaScript Bundle:

  • Code splitting (route-based, component-based)

  • Tree shaking (remove unused code)

  • Remove unused dependencies

  • Lazy load non-critical code

  • Use dynamic imports for large components

// Lazy load heavy component
const HeavyChart = lazy(() => import('./HeavyChart'));

Optimize CSS:

  • Remove unused CSS

  • Critical CSS inline, rest async

  • Minimize CSS files

  • Use CSS containment for independent regions

Optimize Fonts:

  • Use font-display: swap or optional

  • Subset fonts (only characters you need)

  • Preload critical fonts

  • Use system fonts when appropriate

  • Limit font weights loaded

@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/custom.woff2') format('woff2');
  font-display: swap; /* Show fallback immediately */
  unicode-range: U+0020-007F; /* Basic Latin only */
}

Optimize Loading Strategy:

  • Critical resources first (async/defer non-critical)

  • Preload critical assets

  • Prefetch likely next pages

  • Service worker for offline/caching

  • HTTP/2 or HTTP/3 for multiplexing

Rendering Performance

Avoid Layout Thrashing:

// ❌ Bad: Alternating reads and writes (causes reflows)
elements.forEach(el => {
  const height = el.offsetHeight; // Read (forces layout)
  el.style.height = height * 2; // Write
});

// ✅ Good: Batch reads, then batch writes
const heights = elements.map(el => el.offsetHeight); // All reads
elements.forEach((el, i) => {
  el.style.height = heights[i] * 2; // All writes
});

Optimize Rendering:

  • Use CSS contain property for independent regions

  • Minimize DOM depth (flatter is faster)

  • Reduce DOM size (fewer elements)

  • Use content-visibility: auto for long lists

  • Virtual scrolling for very long lists (react-window, TanStack Virtual)

Reduce Paint & Composite:

  • Use transform and opacity for reliable movement, but allow blur, filters, masks, clip paths, shadows, and color shifts when they create meaningful polish

  • Avoid casual animation of layout-driving properties (width, height, top, left, margins)

  • Use will-change sparingly for known expensive operations

  • Bound expensive paint areas for blur/filter/shadow effects (smaller and isolated is faster)

Animation Performance

GPU Acceleration:

/* ✅ GPU-accelerated (fast) */
.animated {
  transform: translateX(100px);
  opacity: 0.5;
}

/* ❌ CPU-bound (slow) */
.animated {
  left: 100px;
  width: 300px;
}

Smooth 60fps:

  • Target 16ms per frame (60fps)

  • Use requestAnimationFrame for JS animations

  • Debounce/throttle scroll handlers

  • Use CSS animations when possible

  • Avoid long-running JavaScript during animations

Intersection Observer:

// Efficiently detect when elements enter viewport
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      // Element is visible, lazy load or animate
    }
  });
});
React/Framework Optimization

React-specific:

  • Use memo() for expensive components

  • useMemo() and useCallback() for expensive computations

  • Virtualize long lists

  • Code split routes

  • Avoid inline function creation in render

  • Use React DevTools Profiler

Framework-agnostic:

  • Minimize re-renders

  • Debounce expensive operations

  • Memoize computed values

  • Lazy load routes and components

Network Optimization

Reduce Requests:

  • Combine small files

  • Use SVG sprites for icons

  • Inline small critical assets

  • Remove unused third-party scripts

Optimize APIs:

  • Use pagination (don't load everything)

  • GraphQL to request only needed fields

  • Response compression (gzip, brotli)

  • HTTP caching headers

  • CDN for static assets

Optimize for Slow Connections:

  • Adaptive loading based on connection (navigator.connection)

  • Optimistic UI updates

  • Request prioritization

  • Progressive enhancement

Core Web Vitals Optimization

Largest Contentful Paint (LCP < 2.5s)

  • Optimize hero images

  • Inline critical CSS

  • Preload key resources

  • Use CDN

  • Server-side rendering

Interaction to Next Paint (INP < 200ms)

  • Break up long tasks

  • Defer non-critical JavaScript

  • Use web workers for heavy computation

  • Reduce JavaScript execution time

Cumulative Layout Shift (CLS < 0.1)

  • Set dimensions on images and videos

  • Don't inject content above existing content

  • Use aspect-ratio CSS property

  • Reserve space for ads/embeds

  • Avoid animations that cause layout shifts

/* Reserve space for image */
.image-container {
  aspect-ratio: 16 / 9;
}

Performance Monitoring

Tools to use:

  • Chrome DevTools (Lighthouse, Performance panel)

  • WebPageTest

  • Core Web Vitals (Chrome UX Report)

  • Bundle analyzers (webpack-bundle-analyzer)

  • Performance monitoring (Sentry, DataDog, New Relic)

Key metrics:

  • LCP, INP, CLS (Core Web Vitals; INP replaced FID in March 2024)

  • Time to Interactive (TTI)

  • First Contentful Paint (FCP)

  • Total Blocking Time (TBT)

  • Bundle size

  • Request count

Measure on real devices with real network conditions. Desktop Chrome on a fast connection isn't representative.

Avoid:

  • Optimize without measuring (premature optimization)

  • Sacrifice accessibility for performance

  • Break functionality while optimizing

  • Use will-change everywhere (creates new layers, uses memory)

  • Lazy load above-fold content

  • Optimize micro-optimizations while ignoring major issues (optimize the biggest bottleneck first)

  • Forget about mobile performance (often slower devices, slower connections)

Verify Improvements

Test that optimizations worked:

  • Before/after metrics: Compare Lighthouse scores

  • Real user monitoring: Track improvements for real users

  • Different devices: Test on low-end Android, not just flagship iPhone

  • Slow connections: Throttle to 3G, test experience

  • No regressions: Ensure functionality still works

  • User perception: Does it feel faster?

When the user-facing numbers move, hand off to /impeccable polish for the final pass.

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

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