design-guide

name	design-guide
description	Extract comprehensive design language from websites including colors, typography, animations, interactive states, shadows, gradients, component patterns, and UX behaviors. Generates pixel-perfect design guides with responsive screenshots and complete design system documentation. Use when analyzing website design, creating design systems, or rebuilding sites.

Comprehensive Design Guide Generator

Extract the complete design language from any website with automated analysis of colors, typography, animations, interactions, and UX patterns. Goes far beyond basic CSS extraction to capture the full design system.

When to Use This Skill

Use this skill when you want to:

• Analyze a website's complete design system - Not just colors and fonts, but the entire design language
• Extract interactive design patterns - Hover states, transitions, animations, micro-interactions
• Document component libraries - Buttons, cards, forms, navigation patterns
• Create pixel-perfect recreations - Comprehensive data for exact replicas
• Build design systems - Complete token systems with all design decisions documented
• Understand UX patterns - Interaction patterns, accessibility features, responsive behavior
• Reverse-engineer designs - Full extraction of design decisions from live websites

What This Skill Extracts

🎨 Visual Design

Colors & Gradients

• Text colors (all variations)
• Background colors
• Border colors
• Shadow colors (extracted from box-shadow)
• Linear and radial gradients
• Complete color palette with CSS custom properties

Typography System

• Font families and fallback stacks
• Complete type scale (all font sizes used)
• Font weights (100-900)
• Line heights
• Letter spacing
• Text transforms
• Heading hierarchy (H1-H6) with exact styles
• Body text specifications

Visual Effects

• Box shadows (all variations)
• Text shadows
• CSS filters (blur, brightness, contrast, etc.)
• Transform properties
• Opacity values
• Border radius values

⚡ Interactive Design

Interactive States

• Hover effects (color, transform, shadow changes)
• Focus states
• Active states
• Transition properties
• Before/after comparisons for hover states
• Screenshots of interactive elements in hover state

Animations

• CSS transitions (timing, easing, duration)
• Keyframe animations
• Animated element detection
• Animation names and rules

📐 Layout & Spacing

Spacing System

• Margin values (sorted scale)
• Padding values (sorted scale)
• Gap values (Flexbox/Grid)
• Complete spacing token system

Layout Patterns

• Container max-widths
• Centered container patterns
• Flexbox configurations
• Grid layouts
• Sticky/fixed positioning

🧩 Component Patterns

UI Components Identified

• Buttons (with exact styling)
• Cards (background, shadow, radius, padding)
• Navigation bars
• Forms and inputs
• Modals
• Badges
• Alerts

Component Documentation

• Exact CSS for each component variant
• Component text content
• Visual hierarchy

🎭 UX & Behavior

Interaction Patterns

• Scroll behavior
• Cursor styles used
• Interactive element count
• Sticky/fixed element patterns

Accessibility Features

• ARIA labels count
• ARIA descriptions count
• Role attributes count
• Image alt text usage

📱 Responsive Design

Multi-Device Analysis

• Mobile screenshots (375x812)
• Tablet screenshots (768x1024)
• Desktop screenshots (1920x1080)
• Layout metrics at each breakpoint
• Viewport-specific behaviors

Instructions for Claude

Step 1: Verify Setup

Navigate to the skill directory:

cd /Users/tchen/projects/mycode/claude-skills/design-guide

Ensure dependencies are installed (first time only):

uv sync
playwright install chromium

Step 2: Gather Requirements

Ask the user for:

• URL (required): The website to analyze
• Output directory (optional): Where to save results (default: ./output)
• Viewport size (optional): Custom viewport dimensions (default: 1600x1200)

Step 3: Run the Enhanced Extractor

Execute the comprehensive extraction:

uv run main.py --url <URL> [OPTIONS]

Available Options:

• --url, -u: Website URL to analyze (required)
• --output, -o: Output directory (default: ./output)
• --viewport-width: Viewport width in pixels (default: 1600)
• --viewport-height: Viewport height in pixels (default: 1200)

What happens during extraction:

The tool will:

1. 📄 Load the page and wait for network idle
2. 📸 Take viewport and full-page screenshots
3. 🔍 Extract HTML structure
4. 💅 Extract all CSS (linked and inline)
5. 🎯 Compute styles for every element
6. ⚡ Capture interactive states (hover 10 elements)
7. 🎨 Analyze complete color palette
8. 📝 Extract typography system
9. 📐 Analyze layout and spacing
10. ✨ Detect animations and transitions
11. 🌟 Extract shadows and visual effects
12. 🧩 Identify component patterns
13. 🎭 Analyze UX patterns
14. 📱 Test responsive behavior (3 breakpoints)
15. 💾 Save all data and generate design guide

Step 4: Review Generated Assets

After extraction, the output directory contains:

Documentation

• design-guide.md - Comprehensive design guide (main deliverable)
• design_data.json - Complete structured data

Visual Assets

• viewport_screenshot.png - Desktop viewport capture
• fullpage_screenshot.png - Complete page capture
• interactive_hover.png - Hover state demonstrations
• responsive_mobile.png - Mobile view (375x812)
• responsive_tablet.png - Tablet view (768x1024)
• responsive_desktop.png - Large desktop view (1920x1080)

Source Code

• extracted.html - Original HTML
• extracted.css - All CSS (can be 2-3MB for complex sites)
• computed_styles.json - Computed styles for every element (can be large)

Step 5: Explore the Design Guide

The generated design-guide.md contains:

1. Visual Assets - All screenshots with descriptions
2. Color System - Complete palette with CSS variables
3. Typography System - Font stacks, type scale, heading hierarchy
4. Spacing & Layout - Complete spacing tokens and container patterns
5. Visual Effects - Shadows, filters, transforms, opacity
6. Animations & Transitions - All transitions and keyframe animations
7. Interactive States - Hover effects with before/after comparisons
8. Component Patterns - Button, card, form, nav styling
9. UX Patterns - Accessibility, cursor styles, sticky elements
10. Responsive Design - Breakpoint analysis
11. Implementation Guide - Step-by-step recreation instructions

Step 6: Analyze Design Patterns

Use the extracted data to understand:

Design System Maturity

• Consistent spacing scale? (Check margin/padding variations)
• Defined type scale? (Check font size progression)
• Component library? (Check identified components)
• Accessibility? (Check ARIA features)

Design Decisions

• Color choices and usage patterns
• Typography hierarchy clarity
• Animation smoothness (check transition timings)
• Shadow depth system
• Border radius consistency

Step 7: Pixel-Perfect Recreation (Advanced)

For recreating the design:

1. Use Design Tokens: Copy CSS variables from design guide
2. Match Typography: Use exact font stacks and sizes
3. Implement Spacing: Follow extracted spacing scale
4. Apply Effects: Use exact shadow and border-radius values
5. Add Interactions: Implement hover/focus states as documented
6. Test Responsive: Match layouts at all breakpoints
7. Verify Visually: Compare with extracted screenshots

Step 8: Interactive Exploration with Playwright MCP (Optional)

If you need deeper interaction analysis:

# Use Playwright MCP to:
1. Navigate to specific pages/states
2. Test form interactions
3. Trigger modals/dropdowns
4. Capture specific UI states
5. Test animations manually
6. Explore navigation flows

Usage Examples

Basic Usage - Any Website

uv run main.py --url https://stripe.com

E-commerce Site Analysis

uv run main.py --url https://shopify.com --output ./shopify-design

Custom Viewport

uv run main.py --url https://github.com --viewport-width 1920 --viewport-height 1080

Design System Extraction

# Extract from design system documentation
uv run main.py --url https://primer.style --output ./primer-system

Example Output

After analyzing GitHub.com, you get:

Colors:

• 100+ unique colors cataloged
• Dark theme palette (rgb(13, 17, 23) backgrounds)
• Brand colors (rgb(31, 111, 235))
• 5+ gradient variations
• Shadow color system

Typography:

• Mona Sans font family
• 10-level type scale (12px to 72px)
• 5 font weights (400, 450, 500, 600, 700)
• Heading hierarchy

Components:

• 5+ button variations
• Card patterns with exact shadows
• Navigation bar styles
• Form input specifications

Interactive:

• Hover state transitions
• Animation keyframes
• Transform effects

Responsive:

• Mobile, tablet, desktop screenshots
• Layout adaptations documented

Advanced Features

Component Pattern Recognition

The skill automatically identifies:

• Buttons: Searches for button, [role="button"], .btn, input[type="button"]
• Cards: Searches for [class*="card"], article, [class*="post"]
• Nav: Searches for nav, [role="navigation"], header nav
• Forms: Extracts input, select, textarea styling

Interactive State Capture

• Hovers over first 10 interactive elements
• Captures computed styles before and after hover
• Takes screenshot in hover state
• Documents changes in design guide

Responsive Testing

Automatically tests at:

• Mobile: 375x812 (iPhone X/11/12/13/14 size)
• Tablet: 768x1024 (iPad portrait)
• Desktop: 1920x1080 (Full HD)

Animation Detection

• Scans all elements for CSS animations
• Extracts keyframe rules from stylesheets
• Identifies animated elements
• Documents transition properties

Tips for Best Results

Choosing the Right URL

✅ Good URLs:

• Homepage (comprehensive overview)
• Marketing pages (best design work)
• Component libraries (design system docs)
• Login/signup pages (form patterns)

❌ Challenging URLs:

• Authenticated content (may redirect)
• Dynamic SPAs (may need extra wait time)
• Sites with aggressive anti-bot measures

Viewport Selection

• 1600x1200 - Default, good for most sites
• 1920x1080 - Large desktop analysis
• 1280x720 - Smaller desktop
• Custom - Match specific design requirements

Multiple Page Analysis

For complete design systems, run on multiple pages:

# Homepage
uv run main.py --url https://example.com -o ./design/home

# Product page
uv run main.py --url https://example.com/product -o ./design/product

# About page
uv run main.py --url https://example.com/about -o ./design/about

# Then compare to find:
# - Consistent design tokens
# - Page-specific variations
# - Component reuse patterns

Performance Notes

Extraction Time:

• Simple sites: 30-60 seconds
• Complex sites (GitHub, Stripe): 60-120 seconds
• Includes responsive testing at 3 breakpoints

Output Size:

• Design guide: 5-20KB (markdown)
• Screenshots: 500KB - 3MB total
• CSS file: 10KB - 5MB (complex sites)
• Computed styles: 100KB - 10MB
• Design data JSON: 50KB - 500KB

Troubleshooting

Browser Not Installed

playwright install chromium

Page Load Timeout

• Increase timeout in code if needed
• Some SPAs may need extra wait time
• Check network connectivity

Missing Interactive States

• Some sites block mouse events
• Screenshot may capture only first few hovers
• Manual Playwright MCP can capture more

Empty Design Guide Sections

• Page may not use certain features (animations, shadows, etc.)
• This is normal for minimalist designs
• Check design_data.json for raw data

CORS Errors for CSS

• External stylesheets may be blocked
• Tool extracts what it can access
• Check extracted.css for completeness
• Use browser DevTools to manually inspect

Cost Considerations

Resource Usage:

• Local Playwright (free)
• No external APIs (free)
• CPU: Moderate (page rendering)
• Memory: 500MB-2GB (complex sites)
• Disk: 5-50MB per extraction

No API Keys Required!

Design Guide Quality

The generated design guide is:

• ✅ Comprehensive - Covers all design aspects
• ✅ Actionable - Ready to use for implementation
• ✅ Organized - Clear sections and categories
• ✅ Visual - References screenshots throughout
• ✅ Technical - Exact CSS values and code
• ✅ Accessible - Documents accessibility features

Integration with Claude Code Workflow

Typical Usage Flow

1. User Request: "Analyze the design of stripe.com"

2. Claude Uses Skill:

   cd /Users/tchen/projects/mycode/claude-skills/design-guide
   uv run main.py --url https://stripe.com --output ./stripe-design
   

3. Claude Reviews Output: Reads design-guide.md

4. Claude Presents Findings:

   • Color system overview
   • Typography hierarchy
   • Key components identified
   • Interactive patterns found
   • Accessibility score

5. User Follow-up: "Recreate the hero section"

6. Claude Implements: Uses extracted design tokens to build pixel-perfect HTML/CSS

Example User Interactions

User: "What design system does Shopify use?"

Claude:

# Runs extraction
uv run main.py --url https://shopify.com -o ./shopify-design

# Analyzes output
# Reports findings:

"Shopify uses:

• Polaris design system
• Typography: Inter font family
• Colors: Green primary (rgb(0, 128, 96))
• Spacing: 4px base unit
• Components: Identified 12 button variants, card system, navigation
• Shadows: 3-level depth system
• Responsive: Mobile-first approach"

---

User: "Extract the button styles from GitHub"

Claude:

uv run main.py --url https://github.com -o ./github-design

"Found 5 button variants on GitHub:

1. Primary Button:
   • Background: rgb(31, 111, 235)
   • Color: white
   • Padding: 5px 16px
   • Border-radius: 6px
   • Hover: Transforms darker

[Shows exact CSS from design guide]"

---

Advanced: Claude-Driven Analysis

When using this skill, Claude should:

1. Run extraction automatically
2. Read design-guide.md to understand design
3. Analyze patterns for insights
4. Present findings in structured format
5. Offer to recreate components if requested
6. Use Playwright MCP for deeper interaction testing if needed

Deliverables

After running this skill, deliver to user:

✅ design-guide.md - Main comprehensive guide ✅ All screenshots - Visual reference ✅ design_data.json - Structured data for programmatic use ✅ Source files - HTML, CSS, computed styles

Optional: ✅ Recreated components - If requested ✅ Comparison analysis - If analyzing multiple sites ✅ Token library - CSS/SCSS variables file

---

Skill Version: 2.0 (Enhanced - Full Design Language Extraction) Last Updated: 2025-11-16 Extraction Depth: Comprehensive (11+ analysis types)