keyargo/custodian-kernel/design-impeccable

Impeccable

Design rules for AI coding agents. Catches the specific tells that mark output as AI-generated.

The 23 commands (overview)

44 deterministic detector rules

These are the most common AI-generated UI mistakes. Check for each before shipping.

Typography tells

1. Inter for everything — replace with a font that has character (Geist, Outfit, Satoshi, Cabinet Grotesk)
2. Only 400 and 700 weights — add 500 and 600 for hierarchy
3. Headlines too small — display text should feel heavy
4. No letter-spacing on large text — use negative tracking
5. System font fallbacks visible — explicitly set the font stack
6. Mixed serif/sans usage — pick one family for body, one for display
7. Numbers in proportional font in tables — use tabular figures
8. All-caps everything — sentence case or italics, not all-caps

Color tells

1. Pure `#000` or `#fff` — use off-black (#0a0a0a) and off-white (#fafafa)
2. Two accent colors — pick one, remove the rest
3. Purple-to-blue gradient — the most common AI gradient tell
4. Saturated accent at 100% — desaturate to 70-80%
5. Mixing warm and cool grays — pick one gray family, tint consistently
6. Gray text on colored backgrounds — low contrast fails WCAG
7. Random dark sections in light pages — commit to one mode
8. Identical hex values across components — should be design tokens, not magic numbers

Layout tells

1. Three equal card columns — the #1 AI layout tell
2. Centered everything — break symmetry with offsets
3. `height: 100vh` — use min-height: 100dvh
4. No max-width on body — content stretches edge-to-edge
5. Cards forced to equal height — allow variable heights
6. Uniform border-radius — vary the radius by element type
7. No overlap or layering — flat, flat, flat
8. Top and bottom padding always equal — adjust optically
9. Left sidebar on every dashboard — try top nav, floating menu, collapsible
10. Dense layouts with no whitespace — let it breathe

Interactivity tells

1. No hover states — add background shift or transform
2. No active/pressed feedback — add scale(0.98) on click
3. Zero-duration transitions — use 200-300ms
4. No focus ring — accessibility blocker, fix with :focus-visible
5. Generic spinners — use skeleton loaders that match layout shape
6. No empty states — design a "getting started" view
7. `window.alert()` for errors — use inline error messages
8. Buttons linking to `#` — link to real destinations or disable
9. No current-page indicator in nav — style the active link differently
10. Instant scroll on anchor click — add scroll-behavior: smooth
11. Animating `top`/`left`/`width`/`height` — use transform and opacity

Content tells

1. "John Doe" or "Jane Smith" — use diverse, realistic names
2. Round numbers everywhere — use messy data: 47.2%, $99.00
3. Lorem ipsum — use realistic placeholder content
4. Buzzword overload — "synergy", "leverage", "transformative"
5. Inconsistent date formats — pick one (ISO 8601 recommended)

Code quality tells

1. Magic numbers in CSS — use design tokens / CSS variables
2. 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.