mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-12 06:06:37 +03:00
Paul BakausandClaude Opus 4.7
c7ee722472
Surfaced during hands-on testing against a real Next 16 + Turbopack app (EACManagement). All four compound to produce unusable live iteration for React users; fixed bottom-up because each one blocked testing the next. ## 1. Picker bar snaps to (0,0) on first variant arrival In startVariantObserver, `showVariantInDOM(sessionId, 1)` hides the original via display:none but we never re-pointed selectedElement. Next frame, getBoundingClientRect() on the hidden original returns a zero rect and the bar positions at (0,0). Clicking Next masked the bug because cycleVariant already calls updateSelectedElement. Fix: after showVariantInDOM, re-point selectedElement via pickVariantContent(wrapper, visibleVariant) — same call the no-HMR fallback and updateSelectedElement already use. ## 2. React NotFoundError on accept/discard (Next 16 / Turbopack) handleAccept and cleanup both called `wrapper.parentElement.replaceChild(...)` eagerly, before the agent's source rewrite had propagated through HMR. That yanks children out from under React's reconciler; when React later tries to remove/replace the wrapper, its fiber tree no longer matches the DOM and it throws. Fix, both paths: - cleanup (discard): `wrapper.style.display = 'none'` so variants disappear immediately, no structural DOM mutation. - handleAccept: skip the eager replaceChild entirely. The accepted variant is already the only visible child of the wrapper thanks to the display: contents pattern; HMR cleans up the wrapper itself. - Both paths schedule a 2s fallback replaceChild that runs only if HMR hasn't cleaned up — keeps static-server / no-HMR flows working. - Capture sessionId + visibleVariant in closure variables before the 1800ms cleanup timer zeros them, so the fallback still has context. ## 3. Server serves stale live.js forever loadBrowserScripts() read live-browser.js once at startup into a liveScript string. The /live.js handler served that cached string with no cache headers. Every edit to the browser script was invisible until a full server restart — silently broke the iteration loop on fixes #1 and #2 for the user. Fix: - loadBrowserScripts returns { detectScript, livePath } — existence check only, no caching. - /live.js handler re-reads livePath on every request and prepends __IMPECCABLE_TOKEN__ / __IMPECCABLE_PORT__ each time. - Response headers: Cache-Control: no-store, no-cache, must-revalidate, max-age=0 + Pragma: no-cache. detect.js stays cached — it rarely changes during a session. ## 4. Picker stuck in GENERATING when HMR doesn't fire The only 'done' fallback fired when arrivedVariants === 0 and called injectVariantsFromSource, which parses raw source via DOMParser. That can't work for TSX/JSX/Vue/Svelte — JSX expressions aren't valid HTML. If HMR flaked or was slow (500+ line inserts on Next 16 are prone to this), state stayed in GENERATING and the spinner ran forever. Fix: give HMR a 2s grace window, then `window.location.reload()`. resumeSession already counts variants off the rendered DOM on load and transitions straight to CYCLING — reload is the universal recovery path that works for any framework, HTML, static server, anything. injectVariantsFromSource is now dead code on the 'done' path. Kept for potential pure-HTML-no-HMR future use. ## Credit Precise repro + root-cause diagnosis from the other agent in the EACManagement session. #2 and #4 are the high-impact ones for Next 16 / Turbopack; #3 is the meta-fix that made iterating on #1 and #2 possible at all. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Impeccable
The vocabulary you didn't know you needed. 1 skill, 23 commands, and curated anti-patterns for impeccable frontend design.
Quick start: Visit impeccable.style to download ready-to-use bundles.
Why Impeccable?
Anthropic created frontend-design, a skill that guides Claude toward better UI design. Impeccable builds on that foundation with deeper expertise and more control.
Every LLM learned from the same generic templates. Without guidance, you get the same predictable mistakes: Inter font, purple gradients, cards nested in cards, gray text on colored backgrounds.
Impeccable fights that bias with:
- An expanded skill with 7 domain-specific reference files (view source)
- 23 commands to audit, review, polish, distill, animate, and more
- Curated anti-patterns that explicitly tell the AI what NOT to do
What's Included
The Skill: impeccable
A comprehensive design skill with 7 domain-specific references (view skill):
| Reference | Covers |
|---|---|
| typography | Type systems, font pairing, modular scales, OpenType |
| color-and-contrast | OKLCH, tinted neutrals, dark mode, accessibility |
| spatial-design | Spacing systems, grids, visual hierarchy |
| motion-design | Easing curves, staggering, reduced motion |
| interaction-design | Forms, focus states, loading patterns |
| responsive-design | Mobile-first, fluid design, container queries |
| ux-writing | Button labels, error messages, empty states |
23 Commands
All commands are accessed through /impeccable:
| Command | What it does |
|---|---|
/impeccable craft |
Full shape-then-build flow with visual iteration |
/impeccable teach |
One-time setup: gather design context, write PRODUCT.md and DESIGN.md |
/impeccable document |
Generate DESIGN.md from existing project code |
/impeccable extract |
Pull reusable components and tokens into the design system |
/impeccable shape |
Plan UX/UI before writing code |
/impeccable critique |
UX design review: hierarchy, clarity, emotional resonance |
/impeccable audit |
Run technical quality checks (a11y, performance, responsive) |
/impeccable polish |
Final pass, design system alignment, and shipping readiness |
/impeccable bolder |
Amplify boring designs |
/impeccable quieter |
Tone down overly bold designs |
/impeccable distill |
Strip to essence |
/impeccable harden |
Error handling, i18n, text overflow, edge cases |
/impeccable onboard |
First-run flows, empty states, activation paths |
/impeccable animate |
Add purposeful motion |
/impeccable colorize |
Introduce strategic color |
/impeccable typeset |
Fix font choices, hierarchy, sizing |
/impeccable layout |
Fix layout, spacing, visual rhythm |
/impeccable delight |
Add moments of joy |
/impeccable overdrive |
Add technically extraordinary effects |
/impeccable clarify |
Improve unclear UX copy |
/impeccable adapt |
Adapt for different devices |
/impeccable optimize |
Performance improvements |
/impeccable live |
Visual variant mode: iterate on elements in the browser |
Use /impeccable pin <command> to create standalone shortcuts (e.g., pin audit creates /audit).
Usage Examples
/impeccable audit blog # Audit blog hub + post pages
/impeccable critique landing # UX design review
/impeccable polish settings # Final pass before shipping
/impeccable harden checkout # Add error handling + edge cases
Or use /impeccable directly with a description:
/impeccable redo this hero section
Anti-Patterns
The skill includes explicit guidance on what to avoid:
- Don't use overused fonts (Arial, Inter, system defaults)
- Don't use gray text on colored backgrounds
- Don't use pure black/gray (always tint)
- Don't wrap everything in cards or nest cards inside cards
- Don't use bounce/elastic easing (feels dated)
See It In Action
Visit impeccable.style to see before/after case studies of real projects transformed with Impeccable commands.
Installation
Option 1: Download from Website (Recommended)
Visit impeccable.style, download the ZIP for your tool, and extract to your project.
Option 2: Copy from Repository
Cursor:
cp -r dist/cursor/.cursor your-project/
Note: Cursor skills require setup:
- Switch to Nightly channel in Cursor Settings → Beta
- Enable Agent Skills in Cursor Settings → Rules
Claude Code:
# Project-specific
cp -r dist/claude-code/.claude your-project/
# Or global (applies to all projects)
cp -r dist/claude-code/.claude/* ~/.claude/
OpenCode:
cp -r dist/opencode/.opencode your-project/
Pi:
cp -r dist/pi/.pi your-project/
Gemini CLI:
cp -r dist/gemini/.gemini your-project/
Note: Gemini CLI skills require setup:
- Install preview version:
npm i -g @google/gemini-cli@preview- Run
/settingsand enable "Skills"- Run
/skills listto verify installation
Codex CLI:
# Project-local
cp -r dist/agents/.agents your-project/
# Or user-wide
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/
GitHub Copilot:
cp -r dist/github/.github your-project/
Trae:
# Trae China (domestic version)
cp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/
# Trae International
cp -r dist/trae/.trae/skills/* ~/.trae/skills/
Note: Trae has two versions with different config directories:
- Trae China:
~/.trae-cn/skills/- Trae International:
~/.trae/skills/After copying, restart Trae IDE to activate the skills.
Rovo Dev:
# Project-specific
cp -r dist/rovo-dev/.rovodev your-project/
# Or global (applies to all projects)
cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/
Usage
Once installed, use commands in your AI harness:
/audit # Find issues
/normalize # Fix inconsistencies
/polish # Final cleanup
/distill # Remove complexity
Most commands accept an optional argument to focus on a specific area:
/audit header
/polish checkout-form
Note: Codex uses skills here, not /prompts: commands. Open /skills or type $impeccable. Repo-local installs live in .agents/skills/; user-wide installs live in ~/.agents/skills/. GitHub Copilot uses .github/skills/. Restart the tool if a newly installed skill does not appear.
CLI
Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness:
npx impeccable detect src/ # scan a directory
npx impeccable detect index.html # scan an HTML file
npx impeccable detect https://example.com # scan a URL (Puppeteer)
npx impeccable detect --fast --json . # regex-only, JSON output
The detector catches 24 issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
Supported Tools
Contributing
See DEVELOP.md for contributor guidelines and build instructions.
License
Apache 2.0. See LICENSE.
The impeccable skill builds on Anthropic's original frontend-design skill. See NOTICE.md for attribution.
Created by Paul Bakaus