Impeccable Design

impeccable-design

Overview

Hard QA design review checklist consisting of 50 deterministic rules covering typography (T1-T10), color systems (C1-C12), layout constraints (L1-L11), component contracts (K1-K11), and micro-animations (A1-A8).

When to Use

Activate during the REVIEW phase of all frontend tasks as a strict visual and functional QA gate before marking UI work complete.

Rules & Patterns

Based on pbakaus/impeccable — deterministic detector rules for AI-generated frontend design.

Core Principle

Every model is trained on the same SaaS templates. Skip this guidance and you get the same handful of tells on every project. Impeccable eliminates them.

Role in the Pipeline

This skill acts as a QA-designer at the /review phase. ui-ux-pro is the planning guideline; impeccable-design is the hard checklist that runs before merge.

Anti-Pattern Rules

Typography (Rules T1–T10)

Tailwind typography utilities:

• text-balance — for headlines (prevents orphan words)
• text-pretty — for body paragraphs (smart line-breaks)
• tabular-nums — for numerical data tables

Color (Rules C1–C12)

Layout & Spacing (Rules L1–L11)

Components (Rules K1–K11)

Animation (Rules A1–A8)

Images & Icons (Rules I1–I8)

Design Initialization Checklist

Start every new design with:

## Design Context

**Surface type**: [brand/marketing OR product/app]
**Target audience**: [who are they? what do they value?]
**Brand tone**: [professional/playful/bold/minimal/technical]
**Anti-references**: [designs this should NOT look like]
**Primary font**: [chosen font + why + Framer Motion / shadcn pairing]
**Color palette**: [3 semantic colors + HSL values for light AND dark]
**Component library**: [shadcn/ui | radix | custom]
**Animation library**: [CSS only | Framer Motion | GSAP]

Design Review Audits

Quick Audit (before PR)

• Typography: Is there clear visual hierarchy? Are fonts intentional? Is Inter paired properly?
• Color: Any pure black/white? Contrast failures? Too many colors? Dark mode?
• Spacing: Consistent Tailwind scale? No arbitrary values? Enough whitespace?
• Animation: Any CSS bounce/elastic? Too slow (>400ms)? Too many simultaneous?
• Components: Any native <select> or <input type="date"> that should be shadcn?
• Z-index: Any hardcoded z-[999] or z-50?

Full Audit (before release)

• Accessibility: Run axe DevTools or Lighthouse — target 90+ score
• Responsiveness: Test at 375px, 768px, 1280px, 1440px
• Dark mode: Does the full palette hold up? No inverted-only shortcuts?
• Empty states: Does every list/table have a designed empty state?
• Edge cases: Loading states, error states, long text overflow, RTL

Premium Design Markers

These details separate premium from mediocre:

1. Consistent border radius — pick one and use it everywhere (rounded-md = 6px, rounded-lg = 8px)
2. Intentional drop shadows — darker near surface, lighter for floating elements
3. Micro-copy quality — button labels are verbs: "Save changes" not "Submit"
4. Focus ring styling — focus-visible:ring-2 focus-visible:ring-primary matching brand
5. Smooth color transitions — transition-colors duration-150 on all interactive elements
6. Optical alignment — icon + text optically centered, not mathematically (items-center gap-1.5)

Code Examples

See EXAMPLES.md for detailed code examples.

Validation Checklist

What to verify during the review phase before completing the task.

Common Mistakes

Anti-patterns and things to explicitly avoid. See TROUBLESHOOTING.md.

Integration Notes

How this skill interacts with other skills.

impeccable-design Examples — Anti-patterns vs ContextOS Standard

Example 1: Dark Mode Surfaces & Elevation

Anti-pattern: Pure Black with Flat Cards

/* BAD: Pure #000000 background with harsh pure white borders and flat cards */
body { background-color: #000000; color: #ffffff; }
.card { background-color: #111111; border: 1px solid #ffffff; }

Best practice: ContextOS Standard (Atmospheric Depth & Tinted Surfaces)

/* GOOD: Tinted dark background with layered elevation surfaces and subtle border */
body {
  background-color: #0B0D13; /* Tinted with subtle deep blue */
  color: #E2E8F0;
}
.surface-1 {
  background-color: #111522;
  border: 1px solid rgba(255, 255, 255, 0.08);
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25);
}

impeccable-design Troubleshooting & Common Mistakes

1. Nested Border Radius Mismatch

• Symptom: Corners of an inner element poke out or look visually awkward inside a container.
• Root Cause: Using the same border-radius on both outer container and inner child.
• Fix: Inner radius formula: r_inner = max(0, r_outer - padding).

2. Animation Performance Stutter

• Symptom: Janky animations and dropped frames during transitions.
• Root Cause: Animating layout properties (width, height, top, margin).
• Fix: Animate only composited GPU-accelerated properties: transform and opacity.

3. Cluttered Visual Density

• Symptom: Interface feels overwhelming, cramped, and cheap.
• Root Cause: Cramming too many borders, dividers, badges, and icons into one view.
• Fix: Replace borders with generous whitespace; let alignment and typography hierarchy define grouping.