Frontend Aesthetic
Visual design guidance for beautiful, consistent, and accessible UIs.
Core Principles
1. Visual Hierarchy
- Size, color, contrast guide the eye
- Primary actions should be obvious
- Group related elements visually
2. Spacing & Layout
- Use consistent spacing scale (4px, 8px, 16px, 24px, 32px, 48px, 64px)
- Whitespace is a design element, not empty space
- Align elements to a grid
3. Typography
- Limit to 2-3 font families max
- Use font weight for hierarchy (not just size)
- Line height: 1.4-1.6 for body, 1.2 for headings
- Max line length: 60-80 characters
4. Color
- Primary, secondary, accent colors
- Semantic colors: success (green), warning (yellow), error (red), info (blue)
- Ensure 4.5:1 contrast ratio for accessibility
- Dark mode: don't just invert, redesign
5. Motion & Animation
- Subtle, purposeful animations (200-300ms)
- Ease-out for entrances, ease-in for exits
- Reduce motion for accessibility preference
Component Patterns
Buttons
/* Primary */
background: var(--primary);
color: white;
padding: 12px 24px;
border-radius: 8px;
font-weight: 600;
/* Hover: slight brightness change */
/* Active: scale(0.98) */
/* Disabled: opacity 0.5, cursor not-allowed */
Cards
background: var(--surface);
border-radius: 12px;
padding: 24px;
box-shadow: 0 2px 8px rgba(0,0,0,0.08);
/* Hover: elevate shadow */
Forms
- Labels above inputs (not placeholder-only)
- Clear focus states (outline, not just color)
- Error states: red border + icon + message
- Success feedback on submission
Navigation
- Current page indicator
- Consistent iconography
- Mobile: bottom nav or hamburger (not both)
Aesthetic Validation with Playwright
Use Playwright MCP to validate visual design:
1. Navigate to the page
2. Take full-page screenshot
3. Check for:
- Consistent spacing
- Color contrast issues
- Typography hierarchy
- Alignment problems
- Responsive breakpoints
Common Anti-Patterns
| Don't |
Do Instead |
| Rainbow of colors |
Limited, intentional palette |
| Tiny click targets |
Min 44x44px touch targets |
| Text on busy backgrounds |
Overlay or solid backgrounds |
| Inconsistent border-radius |
Pick one: 4px, 8px, or 12px |
| Auto-playing animations |
User-triggered or subtle loops |
| Placeholder-only labels |
Visible labels always |
Design System Integration
When working with existing design systems:
- Tailwind: Use config theme values
- Material UI: Follow MD3 guidelines
- Chakra: Use theme tokens
- Custom: Document tokens in CSS variables
Workflow
- Audit: Screenshot current state
- Identify: List aesthetic issues
- Prioritize: Fix high-impact items first
- Implement: Make CSS/component changes
- Validate: Screenshot after, compare
Integration
- playwright-automation: Take screenshots, inspect DOM
- web-design-guidelines: Technical accessibility rules
- react-best-practices: Component architecture
1---2name: frontend-aesthetic-23description: UI/UX visual design, styling, and aesthetic validation4---56# Frontend Aesthetic78Visual design guidance for beautiful, consistent, and accessible UIs.910## Core Principles1112### 1. Visual Hierarchy13- Size, color, contrast guide the eye14- Primary actions should be obvious15- Group related elements visually1617### 2. Spacing & Layout18- Use consistent spacing scale (4px, 8px, 16px, 24px, 32px, 48px, 64px)19- Whitespace is a design element, not empty space20- Align elements to a grid2122### 3. Typography23- Limit to 2-3 font families max24- Use font weight for hierarchy (not just size)25- Line height: 1.4-1.6 for body, 1.2 for headings26- Max line length: 60-80 characters2728### 4. Color29- Primary, secondary, accent colors30- Semantic colors: success (green), warning (yellow), error (red), info (blue)31- Ensure 4.5:1 contrast ratio for accessibility32- Dark mode: don't just invert, redesign3334### 5. Motion & Animation35- Subtle, purposeful animations (200-300ms)36- Ease-out for entrances, ease-in for exits37- Reduce motion for accessibility preference3839## Component Patterns4041### Buttons42```css43/* Primary */44background: var(--primary);45color: white;46padding: 12px 24px;47border-radius: 8px;48font-weight: 600;4950/* Hover: slight brightness change */51/* Active: scale(0.98) */52/* Disabled: opacity 0.5, cursor not-allowed */53```5455### Cards56```css57background: var(--surface);58border-radius: 12px;59padding: 24px;60box-shadow: 0 2px 8px rgba(0,0,0,0.08);61/* Hover: elevate shadow */62```6364### Forms65- Labels above inputs (not placeholder-only)66- Clear focus states (outline, not just color)67- Error states: red border + icon + message68- Success feedback on submission6970### Navigation71- Current page indicator72- Consistent iconography73- Mobile: bottom nav or hamburger (not both)7475## Aesthetic Validation with Playwright7677Use Playwright MCP to validate visual design:7879```801. Navigate to the page812. Take full-page screenshot823. Check for:83 - Consistent spacing84 - Color contrast issues85 - Typography hierarchy86 - Alignment problems87 - Responsive breakpoints88```8990## Common Anti-Patterns9192| Don't | Do Instead |93|-------|------------|94| Rainbow of colors | Limited, intentional palette |95| Tiny click targets | Min 44x44px touch targets |96| Text on busy backgrounds | Overlay or solid backgrounds |97| Inconsistent border-radius | Pick one: 4px, 8px, or 12px |98| Auto-playing animations | User-triggered or subtle loops |99| Placeholder-only labels | Visible labels always |100101## Design System Integration102103When working with existing design systems:104- Tailwind: Use config theme values105- Material UI: Follow MD3 guidelines106- Chakra: Use theme tokens107- Custom: Document tokens in CSS variables108109## Workflow1101111. **Audit**: Screenshot current state1122. **Identify**: List aesthetic issues1133. **Prioritize**: Fix high-impact items first1144. **Implement**: Make CSS/component changes1155. **Validate**: Screenshot after, compare116117## Integration118119- **playwright-automation**: Take screenshots, inspect DOM120- **web-design-guidelines**: Technical accessibility rules121- **react-best-practices**: Component architecture
majiayu000