design-guide

What this skill does

# 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:
```bash
cd /Users/tchen/projects/mycode/claude-skills/design-guide
```

Ensure dependencies are installed (first time only):
```bash
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:

```bash
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:

```python
# 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
```bash
uv run main.py --url https://stripe.com
```

### E-commerce Site Analysis
```bash
uv run main.py --url https://shopify.com --output ./shopify-design
```

### Custom Viewport
```bash
uv run main.py --url https://github.com --viewport-width 1920 --viewport-height 1080
```

### Design System Extraction
```bash
# Extract from design system documentation
uv run main.p