name: frontend-aesthetic
description: UI/UX visual design, styling, and aesthetic validation
requires_mcp: playwright
integrates_with:
- web-design-guidelines
- playwright-automation
- react-best-practices

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 MCP

Use the actual Playwright MCP tools to validate visual design:

Step 1: Navigate and Screenshot

mcp__playwright__browser_navigate(url: "http://localhost:3000")
mcp__playwright__browser_take_screenshot(fullPage: true, filename: "full-page.png")

Step 2: Check Spacing & Alignment

mcp__playwright__browser_evaluate(function: `
  // Check computed margins/paddings
  const elements = document.querySelectorAll('*');
  const spacings = new Set();
  elements.forEach(el => {
    const style = getComputedStyle(el);
    ['margin', 'padding'].forEach(prop => {
      ['Top', 'Right', 'Bottom', 'Left'].forEach(dir => {
        const val = parseInt(style[prop + dir]);
        if (val > 0) spacings.add(val);
      });
    });
  });
  return [...spacings].sort((a,b) => a-b);
`)

Check: Does it follow 4px/8px grid?

Step 3: Check Color Palette

mcp__playwright__browser_evaluate(function: `
  const colors = new Set();
  document.querySelectorAll('*').forEach(el => {
    const style = getComputedStyle(el);
    colors.add(style.color);
    colors.add(style.backgroundColor);
  });
  return [...colors].filter(c => c !== 'rgba(0, 0, 0, 0)');
`)

Check: Limited palette? Consistent use?

Step 4: Check Typography

mcp__playwright__browser_evaluate(function: `
  const fonts = new Set();
  document.querySelectorAll('*').forEach(el => {
    fonts.add(getComputedStyle(el).fontFamily);
  });
  return [...fonts];
`)

Check: Max 2-3 font families?

Step 5: Responsive Test

mcp__playwright__browser_resize(width: 375, height: 667)
mcp__playwright__browser_take_screenshot(filename: "mobile.png")
mcp__playwright__browser_resize(width: 1280, height: 800)
mcp__playwright__browser_take_screenshot(filename: "desktop.png")

Step 6: Check Console for Errors

mcp__playwright__browser_console_messages(level: "error")

Common Anti-Patterns

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

1. Audit: Screenshot current state
2. Identify: List aesthetic issues
3. Prioritize: Fix high-impact items first
4. Implement: Make CSS/component changes
5. Validate: Screenshot after, compare

Integration

• playwright-automation: Take screenshots, inspect DOM
• web-design-guidelines: Technical accessibility rules
• react-best-practices: Component architecture