Design Research

Design Research

Research and analyze website design, styling, and frontend implementation to help engineers understand and replicate design patterns.

Overview

This skill uses Playwright CLI to systematically capture screenshots, inspect HTML structure, analyze CSS styling, and document design systems. It produces a comprehensive report covering layout, typography, colors, spacing, components, and implementation recommendations.

Prerequisites

Playwright CLI must be available. If not installed:

# Check if available
npx playwright --version

# Install if needed (user should approve)
npm install -D playwright
npx playwright install chromium

Instructions

When this skill is activated, follow this research workflow:

1. Validate Target URL

• Confirm the URL with the user if not provided
• Check if the site is publicly accessible
• Note: This skill works best with public websites; authentication flows require additional setup

2. Screenshot Capture Strategy

Use Playwright CLI to capture multiple views:

# Full page screenshot
npx playwright screenshot --full-page <URL> full-page.png

# Viewport screenshot (above the fold)
npx playwright screenshot <URL> viewport.png

# Mobile viewport
npx playwright screenshot --viewport-size=375,667 <URL> mobile.png

# Tablet viewport
npx playwright screenshot --viewport-size=768,1024 <URL> tablet.png

# Dark mode (if supported)
npx playwright screenshot --color-scheme=dark <URL> dark-mode.png

Save all screenshots to a design-research-output/ directory.

2.5. Bot Protection Handling (Automatic)

The skill automatically detects and handles bot protection using a feedback loop:

Detection:

• Screenshot file size < 50KB
• HTML content contains "Cloudflare", "checking your browser", "captcha"
• Page redirects to /cdn-cgi/challenge-platform/*

Automatic Retry Strategy:

1. Standard Playwright (default, fast)

   • No stealth overhead
   • Works for most public sites
   • If blocked, automatically tries strategy 2

2. Camoufox Stealth Mode (if blocked)

   • Firefox-based anti-detect browser (0% detection score normally)
   • Automatically installed via UV: uv run capture-stealth.py
   • Adds human-like behavior and realistic fingerprints
   • Modifies browser at C++ level (not patchable JS)
   • Success rate: ~70% against moderate Cloudflare protection

3. Manual Fallback (if stealth fails)

   • Provides clear instructions for manual browser capture
   • Includes DevTools extraction scripts (CSS, colors, typography)
   • Documents manual screenshot workflow
   • See MANUAL-FALLBACK.md for complete instructions

User Communication:

• Clearly indicate which strategy is being used
• Show progress and retry attempts
• Provide actionable manual instructions if automated methods fail
• Never silently fail - always explain what happened and why

Note: The capture script uses UV-based Python scripts with inline dependencies (no package.json needed). UV must be available (already in dotfiles Nix flake).

3. HTML Structure Analysis

Use Playwright to extract and analyze structure:

# Get full HTML
npx playwright open <URL> --save-trace=trace.zip

# Or use WebFetch to get HTML content

Analyze:

• Semantic HTML usage (header, nav, main, article, section, footer)
• Component hierarchy and nesting patterns
• Class naming conventions (BEM, utility-first, CSS modules, etc.)
• Data attributes and JavaScript hooks
• Accessibility landmarks and ARIA attributes

4. CSS & Styling Analysis

Examine styling patterns:

# Extract stylesheets
npx playwright evaluate <URL> --expression "Array.from(document.styleSheets).map(s => s.href)"

# Get computed styles for key elements
npx playwright evaluate <URL> --expression "
  const nav = document.querySelector('nav');
  window.getComputedStyle(nav);
"

Document:

• Color palette: Primary, secondary, accent, neutral colors
• Typography: Font families, sizes, weights, line heights, letter spacing
• Spacing system: Margins, padding, gaps (check for consistent scale like 4px/8px grid)
• Breakpoints: Media query values for responsive design
• Shadows & effects: Box shadows, border radius, transitions, animations
• Layout patterns: Flexbox, Grid, positioning strategies

5. Component Inventory

Identify reusable components:

• Navigation (header, sidebar, mobile menu)
• Buttons (primary, secondary, ghost, icon buttons)
• Forms (inputs, selects, checkboxes, validation states)
• Cards (content cards, product cards, feature cards)
• Modals/Dialogs
• Alerts/Notifications
• Loading states
• Icons (icon system/library used)

For each component, note:

• Visual appearance (from screenshots)
• HTML structure
• CSS patterns
• Interactive states (hover, active, focus, disabled)

6. Design System Detection

Check for design system indicators:

• CSS custom properties (CSS variables): --color-primary, --spacing-md
• Utility class patterns: Tailwind, UnoCSS, custom utilities
• Component library: Material UI, Chakra UI, Ant Design, shadcn/ui, etc.
• CSS framework: Bootstrap, Bulma, Foundation
• CSS-in-JS: Styled Components, Emotion, vanilla-extract

# Check for CSS custom properties
npx playwright evaluate <URL> --expression "
  Array.from(document.styleSheets)
    .flatMap(sheet => Array.from(sheet.cssRules))
    .filter(rule => rule.cssText.includes('--'))
    .map(rule => rule.cssText)
    .slice(0, 20)
"

7. Technology Stack Detection

Identify frontend technologies:

# Check for framework signatures
npx playwright evaluate <URL> --expression "
  ({
    react: !!document.querySelector('[data-reactroot], #root'),
    vue: !!window.Vue,
    angular: !!window.ng,
    svelte: !!document.querySelector('[data-svelte]'),
    nextjs: !!window.__NEXT_DATA__,
    gatsby: !!window.___gatsby,
    astro: !!document.querySelector('[data-astro-cid]')
  })
"

8. Performance & Optimization Notes

Observe:

• Image formats (WebP, AVIF, responsive images)
• Font loading strategies (FOUT, FOIT, preload)
• Code splitting / lazy loading patterns
• CSS delivery (critical CSS, async loading)

9. Generate Research Report

Create a markdown report (design-research-report.md) with:

# Design Research Report: [Site Name]

**URL:** <target-url>
**Date:** <current-date>
**Purpose:** [Briefly state what the engineer wants to implement]

## Visual Overview

[Reference screenshots with brief descriptions]
- Full page: `full-page.png`
- Viewport: `viewport.png`
- Mobile: `mobile.png`
- Dark mode: `dark-mode.png` (if applicable)

## Design System

### Color Palette
- Primary: #XXXXXX
- Secondary: #XXXXXX
- Accent: #XXXXXX
- Neutral: #XXXXXX (shades: 50, 100, 200, ..., 900)
- Success/Error/Warning/Info states

### Typography
- Headings: [Font family, sizes, weights]
  - H1: ...
  - H2: ...
- Body: [Font family, size, line-height, weight]
- Code: [Monospace font]
- Font loading: [Strategy used]

### Spacing System
- Base unit: Xpx
- Scale: [e.g., 4, 8, 16, 24, 32, 48, 64]
- Grid: [If using grid system]

### Components
[For each major component:]
- **Component Name**
  - Visual: [Screenshot reference or description]
  - HTML structure: [Simplified markup]
  - Key styles: [Important CSS patterns]
  - States: [hover, active, disabled, etc.]
  - Accessibility: [ARIA attributes, keyboard navigation]

## Layout Patterns

- Page layout: [Flexbox/Grid/Float/etc.]
- Container widths: [max-width values, breakpoints]
- Responsive strategy: [Mobile-first, desktop-first, fluid]
- Breakpoints:
  - Mobile: Xpx
  - Tablet: Xpx
  - Desktop: Xpx
  - Wide: Xpx

## Technology Stack

- Framework: [React/Vue/Svelte/etc.]
- Meta-framework: [Next.js/Nuxt/SvelteKit/etc.]
- Component library: [Material UI/shadcn/etc.]
- CSS approach: [Tailwind/CSS Modules/Styled Components/etc.]
- Animation library: [Framer Motion/GSAP/etc.]
- Icons: [Heroicons/Lucide/Font Awesome/etc.]

## Implementation Recommendations

### Quick Start
[Recommended tools and libraries to replicate the design]

### Key Patterns to Replicate
1. [Pattern 1]: [Implementation approach]
2. [Pattern 2]: [Implementation approach]
3. [Pattern 3]: [Implementation approach]

### Suggested Component Structure

/components /ui Button.tsx Card.tsx Input.tsx ... /layout Header.tsx Footer.tsx Navigation.tsx /features ...

### Design Tokens (if applicable)
```css
/* colors.css */
:root {
  --color-primary: #XXXXXX;
  ...
}

/* spacing.css */
:root {
  --spacing-xs: 4px;
  ...
}

Additional Notes

[Any unique patterns, gotchas, or interesting implementation details]

Next Steps

1. Set up project with recommended stack
2. Implement design tokens/theme configuration
3. Build core UI components
4. Implement layout structure
5. Apply responsive patterns
6. Add interactions and animations
7. Optimize for performance

Screenshots and detailed analysis available in: design-research-output/

## Output

The skill produces:

1. **`design-research-output/`** directory containing:
   - `full-page.png` - Full page screenshot
   - `viewport.png` - Above-the-fold screenshot
   - `mobile.png` - Mobile viewport screenshot
   - `tablet.png` - Tablet viewport screenshot
   - `dark-mode.png` - Dark mode screenshot (if applicable)
   - Any additional screenshots captured

2. **`design-research-report.md`** - Comprehensive markdown report covering:
   - Visual overview with screenshot references
   - Design system documentation (colors, typography, spacing)
   - Component inventory with implementation details
   - Layout patterns and responsive strategies
   - Technology stack detection
   - Implementation recommendations

3. **Summary to user** - Brief overview of findings with actionable next steps

## Tips

- For complex sites, focus on the specific page/section the user wants to replicate
- If a design system is detected, prioritize documenting the system over individual components
- Include code snippets for unique patterns worth replicating
- Cross-reference similar open-source component libraries that match the style
- Note any accessibility patterns worth adopting
- If authentication is required, guide the user to use Playwright's interactive mode

## Error Handling

- If Playwright is not installed, prompt user to install it
- If site requires authentication, note it in the report and suggest manual exploration
- If screenshots fail, continue with HTML/CSS analysis and note the limitation
- For rate-limited or blocked sites, use WebFetch as fallback for HTML analysis