Impeccable
Design rules for AI coding agents. Catches the specific tells that mark output as AI-generated.
The 23 commands (overview)
| Command |
What it does |
craft |
Full shape-then-build flow with visual iteration |
init |
One-time setup: gather design context, write PRODUCT.md and DESIGN.md |
document |
Generate root DESIGN.md from existing project code |
extract |
Pull reusable components and tokens into the design system |
shape |
Plan UX/UI before writing code |
critique |
UX design review: hierarchy, clarity, emotional resonance |
audit |
Run technical quality checks (a11y, performance, responsive) |
polish |
Final pass, design system alignment, and shipping readiness |
bolder |
Amplify boring designs |
quieter |
Tone down overly bold designs |
distill |
Strip to essence |
harden |
Error handling, i18n, text overflow, edge cases |
onboard |
First-run flows, empty states, activation paths |
animate |
Add purposeful motion |
colorize |
Introduce strategic color |
typeset |
Fix font choices, hierarchy, sizing |
layout |
Fix layout, spacing, visual rhythm |
delight |
Add moments of joy |
overdrive |
Add technically extraordinary effects |
clarify |
Improve unclear UX copy |
adapt |
Adapt for different devices |
optimize |
Performance improvements |
live |
Visual variant mode: iterate on elements in the browser |
44 deterministic detector rules
These are the most common AI-generated UI mistakes. Check for each before shipping.
Typography tells
- Inter for everything — replace with a font that has character (Geist, Outfit, Satoshi, Cabinet Grotesk)
- Only 400 and 700 weights — add 500 and 600 for hierarchy
- Headlines too small — display text should feel heavy
- No letter-spacing on large text — use negative tracking
- System font fallbacks visible — explicitly set the font stack
- Mixed serif/sans usage — pick one family for body, one for display
- Numbers in proportional font in tables — use tabular figures
- All-caps everything — sentence case or italics, not all-caps
Color tells
- Pure
#000 or #fff — use off-black (#0a0a0a) and off-white (#fafafa)
- Two accent colors — pick one, remove the rest
- Purple-to-blue gradient — the most common AI gradient tell
- Saturated accent at 100% — desaturate to 70-80%
- Mixing warm and cool grays — pick one gray family, tint consistently
- Gray text on colored backgrounds — low contrast fails WCAG
- Random dark sections in light pages — commit to one mode
- Identical hex values across components — should be design tokens, not magic numbers
Layout tells
- Three equal card columns — the #1 AI layout tell
- Centered everything — break symmetry with offsets
height: 100vh — use min-height: 100dvh
- No max-width on body — content stretches edge-to-edge
- Cards forced to equal height — allow variable heights
- Uniform border-radius — vary the radius by element type
- No overlap or layering — flat, flat, flat
- Top and bottom padding always equal — adjust optically
- Left sidebar on every dashboard — try top nav, floating menu, collapsible
- Dense layouts with no whitespace — let it breathe
Interactivity tells
- No hover states — add background shift or transform
- No active/pressed feedback — add
scale(0.98) on click
- Zero-duration transitions — use 200-300ms
- No focus ring — accessibility blocker, fix with
:focus-visible
- Generic spinners — use skeleton loaders that match layout shape
- No empty states — design a "getting started" view
window.alert() for errors — use inline error messages
- Buttons linking to
# — link to real destinations or disable
- No current-page indicator in nav — style the active link differently
- Instant scroll on anchor click — add
scroll-behavior: smooth
- Animating
top/left/width/height — use transform and opacity
Content tells
- "John Doe" or "Jane Smith" — use diverse, realistic names
- Round numbers everywhere — use messy data: 47.2%, $99.00
- Lorem ipsum — use realistic placeholder content
- Buzzword overload — "synergy", "leverage", "transformative"
- Inconsistent date formats — pick one (ISO 8601 recommended)
Code quality tells
- Magic numbers in CSS — use design tokens / CSS variables
- No
:focus-visible for keyboard nav — accessibility requirement
Anti-patterns (don't do these)
- 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)
- Don't animate non-transform properties
- Don't use
window.alert() for inline errors
- Don't link to
# in production code
- Don't use
Lorem ipsum in real product copy
Usage pattern
1. Run /impeccable init — set up PRODUCT.md and DESIGN.md
2. Build the feature
3. Run /impeccable audit — check this list
4. Run /impeccable polish — final pass
5. Ship
Installation (for reference)
This skill ships inside the custodian-kernel package under
custodian/bundled_skills/design-impeccable/SKILL.md.
Your AI agent (Hermes, Claude Code, Codex) will load this file when working on frontend tasks. No additional install steps required.
1---2name: design-impeccable3description: "Anti-pattern detector and design rules for AI coding agents. Catches the specific mistakes AI makes when generating UI: gray text on color, nested cards, broken buttons, missing states. Use before shipping any frontend."4version: 1.0.05metadata:6 source: https://skillmd.com/skills/keyargo/design-impeccable7 hermes:8 tags: [Design, Frontend, Audit]9 custodian:10 band: L011 cost_usd: 0.0012 configured: true13---1415# Impeccable1617Design rules for AI coding agents. Catches the specific tells that mark output as AI-generated.1819## The 23 commands (overview)2021| Command | What it does |22|---------|--------------|23| `craft` | Full shape-then-build flow with visual iteration |24| `init` | One-time setup: gather design context, write PRODUCT.md and DESIGN.md |25| `document` | Generate root DESIGN.md from existing project code |26| `extract` | Pull reusable components and tokens into the design system |27| `shape` | Plan UX/UI before writing code |28| `critique` | UX design review: hierarchy, clarity, emotional resonance |29| `audit` | Run technical quality checks (a11y, performance, responsive) |30| `polish` | Final pass, design system alignment, and shipping readiness |31| `bolder` | Amplify boring designs |32| `quieter` | Tone down overly bold designs |33| `distill` | Strip to essence |34| `harden` | Error handling, i18n, text overflow, edge cases |35| `onboard` | First-run flows, empty states, activation paths |36| `animate` | Add purposeful motion |37| `colorize` | Introduce strategic color |38| `typeset` | Fix font choices, hierarchy, sizing |39| `layout` | Fix layout, spacing, visual rhythm |40| `delight` | Add moments of joy |41| `overdrive` | Add technically extraordinary effects |42| `clarify` | Improve unclear UX copy |43| `adapt` | Adapt for different devices |44| `optimize` | Performance improvements |45| `live` | Visual variant mode: iterate on elements in the browser |4647## 44 deterministic detector rules4849These are the most common AI-generated UI mistakes. Check for each before shipping.5051### Typography tells52531. **Inter for everything** — replace with a font that has character (Geist, Outfit, Satoshi, Cabinet Grotesk)542. **Only 400 and 700 weights** — add 500 and 600 for hierarchy553. **Headlines too small** — display text should feel heavy564. **No letter-spacing on large text** — use negative tracking575. **System font fallbacks visible** — explicitly set the font stack586. **Mixed serif/sans usage** — pick one family for body, one for display597. **Numbers in proportional font in tables** — use tabular figures608. **All-caps everything** — sentence case or italics, not all-caps6162### Color tells63649. **Pure `#000` or `#fff`** — use off-black (`#0a0a0a`) and off-white (`#fafafa`)6510. **Two accent colors** — pick one, remove the rest6611. **Purple-to-blue gradient** — the most common AI gradient tell6712. **Saturated accent at 100%** — desaturate to 70-80%6813. **Mixing warm and cool grays** — pick one gray family, tint consistently6914. **Gray text on colored backgrounds** — low contrast fails WCAG7015. **Random dark sections in light pages** — commit to one mode7116. **Identical hex values across components** — should be design tokens, not magic numbers7273### Layout tells747517. **Three equal card columns** — the #1 AI layout tell7618. **Centered everything** — break symmetry with offsets7719. **`height: 100vh`** — use `min-height: 100dvh`7820. **No max-width on body** — content stretches edge-to-edge7921. **Cards forced to equal height** — allow variable heights8022. **Uniform border-radius** — vary the radius by element type8123. **No overlap or layering** — flat, flat, flat8224. **Top and bottom padding always equal** — adjust optically8325. **Left sidebar on every dashboard** — try top nav, floating menu, collapsible8426. **Dense layouts with no whitespace** — let it breathe8586### Interactivity tells878827. **No hover states** — add background shift or transform8928. **No active/pressed feedback** — add `scale(0.98)` on click9029. **Zero-duration transitions** — use 200-300ms9130. **No focus ring** — accessibility blocker, fix with `:focus-visible`9231. **Generic spinners** — use skeleton loaders that match layout shape9332. **No empty states** — design a "getting started" view9433. **`window.alert()` for errors** — use inline error messages9534. **Buttons linking to `#`** — link to real destinations or disable9635. **No current-page indicator in nav** — style the active link differently9736. **Instant scroll on anchor click** — add `scroll-behavior: smooth`9837. **Animating `top`/`left`/`width`/`height`** — use `transform` and `opacity`99100### Content tells10110238. **"John Doe" or "Jane Smith"** — use diverse, realistic names10339. **Round numbers everywhere** — use messy data: 47.2%, $99.0010440. **Lorem ipsum** — use realistic placeholder content10541. **Buzzword overload** — "synergy", "leverage", "transformative"10642. **Inconsistent date formats** — pick one (ISO 8601 recommended)107108### Code quality tells10911043. **Magic numbers in CSS** — use design tokens / CSS variables11144. **No `:focus-visible` for keyboard nav** — accessibility requirement112113## Anti-patterns (don't do these)114115- Don't use overused fonts (Arial, Inter, system defaults)116- Don't use gray text on colored backgrounds117- Don't use pure black/gray (always tint)118- Don't wrap everything in cards or nest cards inside cards119- Don't use bounce/elastic easing (feels dated)120- Don't animate non-transform properties121- Don't use `window.alert()` for inline errors122- Don't link to `#` in production code123- Don't use `Lorem ipsum` in real product copy124125## Usage pattern126127```1281. Run /impeccable init — set up PRODUCT.md and DESIGN.md1292. Build the feature1303. Run /impeccable audit — check this list1314. Run /impeccable polish — final pass1325. Ship133```134135## Installation (for reference)136137This skill ships inside the `custodian-kernel` package under138`custodian/bundled_skills/design-impeccable/SKILL.md`.139140Your AI agent (Hermes, Claude Code, Codex) will load this file when working on frontend tasks. No additional install steps required.