Impeccable

Design vocabulary for production-grade frontend interfaces. Adapted from https://impeccable.style/ by Paul Bakaus (Apache 2.0).

When to use

• User asks for UI/UX work: landing page, dashboard, component, app shell, form, settings, onboarding, empty state.
• Existing UI looks bland, loud, inconsistent, or like a default template.
• Need to audit, polish, or iterate a frontend surface.
• Not for backend-only or non-UI tasks.

Core protocol

1. Gather design context first. If the project lacks PRODUCT.md and DESIGN.md (or .impeccable.md) with the required context, ask the user or infer from existing code. Required context:
   • Target audience and use cases.
   • Brand personality/tone (bolder vs quieter, warm vs cold, playful vs serious).
   • Anti-references (styles to avoid).
   • Color, typography, and component constraints.
   • Surface type: brand (marketing/landing/portfolio) or product (app/dashboard/tool).
2. Pick one command that matches the goal. Do not chain passes unless the user asks.
3. Implement real working code with attention to spacing, hierarchy, typography, color, motion, and edge cases. Use browser_preview to verify visual output when possible.
4. Audit before declaring done. Check against common slop patterns:
   • Generic gradients, purple-to-blue, beige body background, cards nested in cards.
   • Rounded-square icon tiles above every heading.
   • Gray text on colored backgrounds, Inter for everything.
   • Vague headlines like "Unlock your potential".
   • Equal visual weight on unrelated metrics.

Push vs Pull for Design Patterns

• Push (to critique/audit): the reviewer or audit pass receives the design context — PRODUCT.md, DESIGN.md or .impeccable.md, anti-references, brand tone, surface type, and the slop checklist. Push these constraints before the critique so the reviewer can verify the surface against them.
• Pull (by implementer): the implementer reaches for the right impeccable command (shape, layout, harden, etc.) and the slop checklist before writing UI, instead of waiting for the critique to catch generic design. Pull the relevant command for the pass you are about to run, then push the resulting constraints into the next review.

Command vocabulary

Frontend loop

Use this loop when the user says something like "fix the design" without naming a specific command. Run the passes in order. Stop when the result is good enough; otherwise write a short plan, fix, then move to the next pass.

1. audit — Technical quality check.
   • Run the page in browser_preview.
   • Check for: accessibility labels, focus rings, color contrast, motion preference, no-JS fallbacks, layout overflow, and component misuse.
   • Output: findings list in .devin/plans/impeccable-<surface>-audit.md.
2. critique — Design review.
   • Look for slop and score the page. List the top 3 issues.
   • Output: .devin/plans/impeccable-<surface>-critique.md.
3. distill (optional) — Strip non-essential elements that do not support the task.
4. layout — Fix spacing, rhythm, alignment, and responsive breakpoints.
5. typeset — Check hierarchy, line-height, font weights, and label casing.
6. colorize — Verify all color uses map to the project theme tokens (primary, on-primary, surface, etc.). Fix mismatched tokens like bg-primary-container text-on-primary.
7. harden — Test reduced motion, keyboard navigation, screen-reader labels, error states, long text, small viewports, and dark mode.
8. polish — Final pass on shadows, transitions, border radius consistency, and icon sizing.

Output rule

After each pass that produces code changes:

• Run php artisan test if PHP/Blade changed.
• Run npm run build if CSS/JS changed.
• Commit with a focused message.

Verification checklist

• No generic template aesthetics.
• Color tokens are correct for each surface.
• Focus states are visible.
• Motion respects prefers-reduced-motion.
• No-JS fallback works where applicable.
• Tests and build pass.

Implementation notes

• Prefer real data and concrete labels over lorem ipsum.
• Use browser_preview after significant UI changes.
• If the user names a UI framework (React, Vue, Svelte, Tailwind, shadcn, etc.), invoke context7 before proposing implementation details.
• If a local npx impeccable CLI is installed and trusted, prefer its detector output for audit and critique; otherwise apply the principles above.
• Keep files small and focused; do not let design context leak into backend logic.

Cross-skills

• a11y-audit — when polish touches interaction/markup, verify WCAG (contrast, focus, labels) before shipping.
• creative-engineering — when the user names a visual style/archetype (CRT, dither, brutalist, vaporwave…), load its technical anatomy instead of improvising.

References

• https://impeccable.style/docs/ — full command reference.
• https://impeccable.style/slop/ — anti-pattern gallery.
• https://impeccable.style/designing/ — design principles.