1# Impeccable
  2
  3The vocabulary you didn't know you needed. 1 skill, 23 commands, and curated anti-patterns for impeccable frontend design.
  4
  5> **Quick start:** Visit [impeccable.style](https://impeccable.style) to download ready-to-use bundles.
  6
  7## Why Impeccable?
  8
  9Anthropic's [frontend-design](https://github.com/anthropics/skills/tree/main/skills/frontend-design) was the first widely-used design skill for Claude. Impeccable started from there.
 10
 11Every model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project: Inter for everything, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.
 12
 13Impeccable adds:
 14- **7 domain reference files** ([view source](skill/)). Typography, color, motion, spatial, interaction, responsive, UX writing. Load on every command, alongside a brand-vs-product register that adjusts the defaults.
 15- **23 commands.** A shared design vocabulary with your AI: `polish`, `audit`, `critique`, `distill`, `animate`, `bolder`, `quieter`, and more.
 16- **27 deterministic anti-pattern rules** plus a 12-rule LLM critique pass. CLI and browser extension run the deterministic ones with no LLM and no API key. Each is tied to specific design guidance the skill teaches against.
 17
 18## What's Included
 19
 20### The Skill: impeccable
 21
 22A comprehensive design skill with 7 domain-specific references ([view skill](skill/SKILL.md)):
 23
 24| Reference | Covers |
 25|-----------|--------|
 26| [typography](skill/reference/typography.md) | Type systems, font pairing, modular scales, OpenType |
 27| [color-and-contrast](skill/reference/color-and-contrast.md) | OKLCH, tinted neutrals, dark mode, accessibility |
 28| [spatial-design](skill/reference/spatial-design.md) | Spacing systems, grids, visual hierarchy |
 29| [motion-design](skill/reference/motion-design.md) | Easing curves, staggering, reduced motion |
 30| [interaction-design](skill/reference/interaction-design.md) | Forms, focus states, loading patterns |
 31| [responsive-design](skill/reference/responsive-design.md) | Mobile-first, fluid design, container queries |
 32| [ux-writing](skill/reference/ux-writing.md) | Button labels, error messages, empty states |
 33
 34### 23 Commands
 35
 36All commands are accessed through `/impeccable`:
 37
 38| Command | What it does |
 39|---------|--------------|
 40| `/impeccable craft` | Full shape-then-build flow with visual iteration |
 41| `/impeccable teach` | One-time setup: gather design context, write root PRODUCT.md and DESIGN.md |
 42| `/impeccable document` | Generate root DESIGN.md from existing project code |
 43| `/impeccable extract` | Pull reusable components and tokens into the design system |
 44| `/impeccable shape` | Plan UX/UI before writing code |
 45| `/impeccable critique` | UX design review: hierarchy, clarity, emotional resonance |
 46| `/impeccable audit` | Run technical quality checks (a11y, performance, responsive) |
 47| `/impeccable polish` | Final pass, design system alignment, and shipping readiness |
 48| `/impeccable bolder` | Amplify boring designs |
 49| `/impeccable quieter` | Tone down overly bold designs |
 50| `/impeccable distill` | Strip to essence |
 51| `/impeccable harden` | Error handling, i18n, text overflow, edge cases |
 52| `/impeccable onboard` | First-run flows, empty states, activation paths |
 53| `/impeccable animate` | Add purposeful motion |
 54| `/impeccable colorize` | Introduce strategic color |
 55| `/impeccable typeset` | Fix font choices, hierarchy, sizing |
 56| `/impeccable layout` | Fix layout, spacing, visual rhythm |
 57| `/impeccable delight` | Add moments of joy |
 58| `/impeccable overdrive` | Add technically extraordinary effects |
 59| `/impeccable clarify` | Improve unclear UX copy |
 60| `/impeccable adapt` | Adapt for different devices |
 61| `/impeccable optimize` | Performance improvements |
 62| `/impeccable live` | Visual variant mode: iterate on elements in the browser |
 63
 64Use `/impeccable pin <command>` to create standalone shortcuts (e.g., `pin audit` creates `/audit`).
 65
 66#### Usage Examples
 67
 68```
 69/impeccable audit blog           # Audit blog hub + post pages
 70/impeccable critique landing     # UX design review
 71/impeccable polish settings      # Final pass before shipping
 72/impeccable harden checkout      # Add error handling + edge cases
 73```
 74
 75Or use `/impeccable` directly with a description:
 76```
 77/impeccable redo this hero section
 78```
 79
 80### Anti-Patterns
 81
 82The skill includes explicit guidance on what to avoid:
 83
 84- Don't use overused fonts (Arial, Inter, system defaults)
 85- Don't use gray text on colored backgrounds
 86- Don't use pure black/gray (always tint)
 87- Don't wrap everything in cards or nest cards inside cards
 88- Don't use bounce/elastic easing (feels dated)
 89
 90## See It In Action
 91
 92Visit [impeccable.style](https://impeccable.style#casestudies) to see before/after case studies of real projects transformed with Impeccable commands.
 93
 94## Installation
 95
 96### Option 1: Download from Website (Recommended)
 97
 98Visit [impeccable.style](https://impeccable.style), download the ZIP for your tool, and extract to your project.
 99
100### Option 2: Copy from Repository
101
102**Cursor:**
103```bash
104cp -r dist/cursor/.cursor your-project/
105```
106
107> **Note:** Cursor skills require setup:
108> 1. Switch to Nightly channel in Cursor Settings → Beta
109> 2. Enable Agent Skills in Cursor Settings → Rules
110>
111> [Learn more about Cursor skills](https://cursor.com/docs/context/skills)
112
113**Claude Code:**
114```bash
115# Project-specific
116cp -r dist/claude-code/.claude your-project/
117
118# Or global (applies to all projects)
119cp -r dist/claude-code/.claude/* ~/.claude/
120```
121
122**OpenCode:**
123```bash
124cp -r dist/opencode/.opencode your-project/
125```
126
127**Pi:**
128```bash
129cp -r dist/pi/.pi your-project/
130```
131
132**Gemini CLI:**
133```bash
134cp -r dist/gemini/.gemini your-project/
135```
136
137> **Note:** Gemini CLI skills require setup:
138> 1. Install preview version: `npm i -g @google/gemini-cli@preview`
139> 2. Run `/settings` and enable "Skills"
140> 3. Run `/skills list` to verify installation
141>
142> [Learn more about Gemini CLI skills](https://geminicli.com/docs/cli/skills/)
143
144**Codex CLI:**
145```bash
146# Project-local
147cp -r dist/agents/.agents your-project/
148mkdir -p your-project/.codex
149cp -r dist/codex/.codex/agents your-project/.codex/
150
151# Or user-wide
152mkdir -p ~/.agents/skills
153cp -r dist/agents/.agents/skills/* ~/.agents/skills/
154mkdir -p ~/.codex
155cp -r dist/codex/.codex/agents ~/.codex/
156```
157
158**GitHub Copilot:**
159```bash
160cp -r dist/github/.github your-project/
161```
162
163**Trae:**
164```bash
165# Trae China (domestic version)
166cp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/
167
168# Trae International
169cp -r dist/trae/.trae/skills/* ~/.trae/skills/
170```
171
172> **Note:** Trae has two versions with different config directories:
173> - **Trae China**: `~/.trae-cn/skills/`
174> - **Trae International**: `~/.trae/skills/`
175>
176> After copying, restart Trae IDE to activate the skills.
177
178**Rovo Dev:**
179```bash
180# Project-specific
181cp -r dist/rovo-dev/.rovodev your-project/
182
183# Or global (applies to all projects)
184cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/
185```
186
187**Qoder:**
188```bash
189# Project-specific
190cp -r dist/qoder/.qoder your-project/
191
192# Or global (applies to all projects)
193cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/
194```
195
196## Usage
197
198Once installed, use commands in your AI harness:
199
200```
201/audit           # Find issues
202/normalize       # Fix inconsistencies
203/polish          # Final cleanup
204/distill         # Remove complexity
205```
206
207Most commands accept an optional argument to focus on a specific area:
208
209```
210/audit header
211/polish checkout-form
212```
213
214**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.
215
216## CLI
217
218Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness:
219
220```bash
221npx impeccable detect src/                   # scan a directory
222npx impeccable detect index.html             # scan an HTML file
223npx impeccable detect https://example.com    # scan a URL (Puppeteer)
224npx impeccable detect --fast --json .        # regex-only, JSON output
225```
226
227The 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).
228
229## Supported Tools
230
231- [Cursor](https://cursor.com)
232- [Claude Code](https://claude.ai/code)
233- [OpenCode](https://opencode.ai)
234- [Pi](https://pi.dev)
235- [Gemini CLI](https://github.com/google-gemini/gemini-cli)
236- [Codex CLI](https://github.com/openai/codex)
237- [VS Code Copilot](https://code.visualstudio.com)
238- [Kiro](https://kiro.dev)
239- [Trae](https://trae.ai)
240- [Rovo Dev](https://www.atlassian.com/software/rovo)
241- [Qoder](https://qoder.com)
242
243## Community & Ecosystem
244
245Join the community and ecosystem conversations:
246
247- GitHub Discussions: file bugs, request features, and help newcomers.
248- [Impeccable on npm](https://www.npmjs.com/package/impeccable): grab the CLI, follow releases, and star the package.
249- Follow @pbakaus on Twitter for release notes, sample lint reports, and video highlights of new rules.
250
251## Contributing
252
253See [DEVELOP.md](DEVELOP.md) for contributor guidelines and build instructions.
254
255## License
256
257Apache 2.0. See [LICENSE](LICENSE).
258
259The impeccable skill builds on [Anthropic's original frontend-design skill](https://github.com/anthropics/skills/tree/main/skills/frontend-design). See [NOTICE.md](NOTICE.md) for attribution.
260
261---
262
263Created by [Paul Bakaus](https://www.paulbakaus.com)