Design-to-Code Review Checklist

What This Is

A checklist for reviewing AI-generated code from your designs. Whether you used Lovable, Cursor, Claude Code, or any vibe coding tool, run through this before shipping.

Token Usage

• No hardcoded hex colors (all colors reference tokens or CSS custom properties)
• No hardcoded spacing values (all spacing uses the spacing scale)
• No hardcoded font sizes (all typography uses the type scale)
• No hardcoded border radius (uses radius tokens)
• No hardcoded shadows (uses shadow tokens)
• Semantic tokens used, not primitives (e.g., color.bg.primary not blue-500)

Component Accuracy

• Correct component used for the context (Dialog vs Sheet, AlertBanner vs Toast)
• All variants present (not just the default state)
• States implemented: hover, active, disabled, focus, error, loading
• Component nesting matches the design (correct parent-child relationships)
• Props match the design spec (correct labels, icons, sizes)

Accessibility

• Color contrast meets WCAG AA (4.5:1 text, 3:1 UI elements)
• Focus indicators visible on all interactive elements
• Keyboard navigation works (Tab, Shift+Tab, Enter, Escape, Arrow keys)
• ARIA attributes present and correct (labels, roles, states)
• Screen reader tested (headings, landmarks, live regions)
• Touch targets minimum 44x44px on mobile
• Alt text on all images (or alt="" for decorative)
• Form inputs paired with visible labels

Responsiveness

• Layout works on mobile (320px+)
• Layout works on tablet (768px+)
• Layout works on desktop (1024px+)
• No horizontal scroll at any breakpoint
• Text readable without zooming on mobile
• Touch-friendly spacing between interactive elements on mobile

Common AI Mistakes

These are the errors AI makes most often. Check specifically for:

• Invented tokens: AI creates tokens that don’t exist in your system
• Wrong component: Uses a Sheet when the design shows a Dialog
• Missing states: Only builds the default/happy path
• Hardcoded strings: Text that should come from props or i18n
• Z-index chaos: Random z-index values instead of a managed scale
• Inline styles: Styles that should use utility classes or CSS custom properties
• Missing error states: Forms without validation feedback
• Broken dark mode: Colors that look wrong when theme switches
• Pixel-perfect trap: Exact pixel values instead of responsive units

Before Merging

• Tested in light mode and dark mode
• Tested with keyboard only (no mouse)
• Tested at 200% browser zoom
• No console errors or warnings
• Code follows project naming conventions
• No unnecessary dependencies added