Design Review
Design principles and quality standards for building and reviewing user interfaces.
When to Use
During Development:
- Building new UI components or pages
- Implementing design system elements
- Adding interactive features
- Working on responsive layouts
During Review:
- Evaluating PRs with visual changes
- Validating accessibility compliance
- Checking design system consistency
- Final QA before release
Core Principles
Users First
Every design decision should serve user needs. Prioritize clarity over cleverness, and optimize for the most common workflows. When in doubt, choose the option that reduces user effort.
Meticulous Craft
Small details compound into overall quality. Consistent spacing, aligned elements, and polished interactions signal care and build trust. Sweat the details that users feel but may not consciously notice.
Simplicity & Clarity
Remove everything that doesn't serve a purpose. Each element should earn its place on screen. Labels and instructions should be unambiguous — if users need to think about what something means, simplify it.
Speed & Performance
Perceived performance is part of design. Optimize for fast initial load, instant feedback on interactions, and smooth animations. Slow UI feels broken regardless of visual quality.
Consistency
Maintain uniform patterns across the entire product. Same actions should look and behave the same way everywhere. Consistency reduces cognitive load and makes interfaces predictable.
Accessibility
Design for the full spectrum of users. This includes sufficient color contrast, keyboard navigation, screen reader support, and respecting motion preferences. Accessibility is not optional polish — it's core quality.
Design Foundations
Color
Build a systematic palette rather than picking colors ad-hoc. Include a neutral scale for text and backgrounds, a primary brand color used strategically, and semantic colors for feedback states (success, error, warning, info). Every color combination should meet WCAG AA contrast requirements. Plan for dark mode from the start.
Typography
Choose a clean, legible typeface and establish a clear hierarchy. Define distinct sizes for headings, body text, and captions using a consistent scale. Limit font weights to maintain visual coherence. Generous line height improves readability, especially for body text.
Spacing
Use a consistent spacing scale based on a base unit. Apply the same spacing values throughout the interface for padding, margins, and gaps. Consistent spacing creates rhythm and makes layouts feel intentional rather than arbitrary.
Shape
Define a small set of border radius values and apply them consistently. Sharper corners typically feel more professional; rounder corners feel friendlier. Match the radius to the element's size and purpose.
Component Standards
Interactive States
Every interactive element needs clear visual states: default, hover, active, focus, and disabled. Focus states are critical for keyboard users — they must be clearly visible. Disabled states should look inactive but remain readable.
Buttons
Establish a clear hierarchy: primary for main actions, secondary for alternatives, tertiary/ghost for less prominent options. Destructive actions deserve distinct styling. Include consistent icon placement and sizing. Button text should describe the action ("Save Changes" not "Submit").
Form Elements
Labels should be visible and associated with inputs — don't rely on placeholders alone. Provide helper text for complex fields and clear error messages that explain how to fix problems. Group related fields logically and indicate required vs optional clearly.
Cards & Containers
Use cards to group related content and create visual separation. Maintain consistent internal padding and spacing. Cards can have subtle shadows or borders to establish hierarchy, but avoid over-decorating.
Data Display
Tables need clear headers, consistent alignment (left for text, right for numbers), and adequate row spacing. Consider how tables will handle empty states, loading, and many rows. Provide sorting and filtering for large datasets.
Feedback & Status
Use badges, tags, and indicators consistently. Color-code status information (but don't rely on color alone). Loading states should appear quickly — use skeleton screens for page loads and spinners for discrete actions. Success and error feedback should be immediate and clear.
Layout & Hierarchy
Visual Hierarchy
Guide attention through size, weight, color, and position. The most important content should be immediately obvious. Use typography scale and spacing to create clear relationships between elements.
White Space
Generous negative space improves comprehension and reduces cognitive load. Cramped interfaces feel overwhelming. White space is not wasted space — it's a tool for creating focus and breathing room.
Grid & Alignment
Use a consistent grid system for layout structure. Align elements deliberately — misalignment is visually jarring even when subtle. Responsive grids should adapt gracefully across breakpoints.
Responsive Behavior
Design for multiple viewport sizes. Establish breakpoints (typically mobile, tablet, desktop) and define how layouts adapt at each. Touch targets should be adequately sized on mobile. Avoid horizontal scrolling.
Accessibility Standards
Keyboard Navigation
All interactive elements must be reachable and operable via keyboard. Tab order should follow logical reading order. Focus must never become trapped. Provide skip links for navigation-heavy pages.
Focus Indicators
Focus states must be clearly visible — the default browser outline is often insufficient. Design custom focus styles that are obvious against all backgrounds. Never remove focus indicators without replacement.
Color & Contrast
Text must meet minimum contrast ratios against backgrounds (4.5:1 for normal text, 3:1 for large text). Don't convey information through color alone — pair with icons, text, or patterns. Test with color blindness simulators.
Semantic Structure
Use proper heading hierarchy (h1 → h2 → h3). Choose semantic HTML elements over generic divs. Form inputs need associated labels. Images need meaningful alt text (or empty alt for decorative images).
Motion
Respect prefers-reduced-motion for users who are sensitive to animation. Provide alternatives for motion-dependent interactions. Avoid flashing or rapidly changing content.
Common Patterns
Content Moderation Interfaces
When displaying items for review, make status immediately visible through consistent indicators. Group primary actions together and make them easy to reach. Support efficient workflows with bulk operations and keyboard shortcuts. For high-volume work, minimize visual noise to reduce fatigue.
Data-Heavy Interfaces
Prioritize scannability with clear alignment, adequate spacing, and visual groupings. Provide filtering and search for large collections. Support different view modes if useful (table vs cards). Loading and empty states need thoughtful design, not just afterthought placeholders.
Settings & Configuration
Group related options logically and label everything clearly. Progressive disclosure keeps simple cases simple while allowing access to advanced options. Provide sensible defaults. Confirm destructive changes. Give feedback when settings are saved.
Review Process
Live Environment First
Always assess the actual interface before reviewing code. Experience the user flow, test interactions, and feel the performance. Static code review misses issues that are obvious in use.
Systematic Evaluation
Work through the interface methodically rather than spot-checking. Cover the primary user flow, then edge cases. Test at multiple viewport sizes. Check keyboard navigation end-to-end.
Evidence-Based Feedback
Capture screenshots for visual issues. Be specific about what's wrong and where. Describe problems in terms of user impact, not just aesthetic preference.
Issue Prioritization
Blocker
Prevents core functionality or causes significant accessibility barriers. Must fix before release. Examples: broken interactions, keyboard traps, missing form labels, illegible text contrast.
High Priority
Significant quality issues that affect user experience but don't block functionality. Should fix before merge. Examples: confusing layouts, missing loading states, inconsistent patterns, poor mobile experience.
Medium Priority
Improvements that would enhance quality but aren't urgent. Good for follow-up. Examples: animation polish, minor spacing inconsistencies, suboptimal information hierarchy.
Nitpick
Minor aesthetic preferences or edge cases. Optional to address. Examples: subjective color tweaks, rare edge case handling, micro-copy improvements.
Report Structure
When documenting review findings, organize by priority:
## Summary
Brief overall assessment — what works well and key concerns.
## Blockers
Critical issues requiring immediate attention.
## High Priority
Significant issues to address before merge.
## Suggestions
Medium priority improvements for consideration.
## Nitpicks
Minor observations, prefix with "Nit:" to signal low priority.Lead with what's working well. Frame issues as problems to solve, not mistakes made. Focus on user impact rather than prescribing specific technical solutions — the implementer often knows the codebase better.
Integration Notes
This skill focuses on design principles and review methodology. For automated browser testing (screenshots, viewport testing, interaction verification), use the frontend-playwright skill which provides Playwright MCP tooling.
Adapt specific implementation details (CSS approach, component library, token values) to match the project's existing stack and conventions.