product-design

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: product-design
description: Automates design review, token extraction, component mapping, and implementation planning. Reduces design handoff from 6-10 hours to 5 minutes via direct Figma MCP integration. Auto-invoke when user mentions design review, Figma mockup, or design handoff.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task, TodoWrite
version: 1.1.0
---

# Product Design Skill

Automate design handoff from Figma to code with design system intelligence. Extract tokens, map components, detect drift, generate implementation plans.

## When to Invoke

Auto-invoke when user says:
- "Review this design"
- "Analyze Figma mockup"
- "Design handoff for [feature]"
- "Check design system impact"
- "Plan implementation for design"
- "Extract tokens from Figma"
- "What changed in the design?"

## What This Does

**5-Step Workflow**:
1. **Design Analysis**: Extract patterns, components, tokens from Figma
2. **Codebase Audit**: Compare design vs implementation, find drift
3. **Implementation Planning**: Generate phased task breakdown
4. **Task Assignment**: Create Navigator task document
5. **Handoff**: Ask user to review or start implementation

**Time Savings**: 6-10 hours → 15-20 minutes (95% reduction)

## Prerequisites

### Required

1. **Python Dependencies**
   ```bash
   cd skills/product-design
   ./setup.sh  # Automated installation
   # OR manually: pip install -r requirements.txt
   ```

2. **Figma Desktop** (for automated workflow)
   - Download: https://www.figma.com/downloads/
   - Enable MCP: Figma → Preferences → Enable local MCP Server
   - Must be running during design reviews

3. **Project Structure**
   - `.agent/design-system/` directory (created on first run)
   - Project with components (React/Vue/Svelte)

### Optional (Enhanced Features)
- **Figma Enterprise**: Code Connect for automatic component mapping
- **Tailwind CSS**: Design token integration via @theme
- **Storybook**: Component documentation and visual regression

### Installation

**Quick start**:
```bash
cd skills/product-design
./setup.sh
```

See `INSTALL.md` for detailed installation guide and troubleshooting.

## Workflow Protocol

### Step 0: Check Setup (Auto-Run)

**Before starting, verify Python dependencies installed**:

```bash
# Get Navigator plugin path
PLUGIN_PATH=$(dirname "$(dirname "$(dirname "$PWD")")")

# Check if venv exists
if [ ! -d "$PLUGIN_PATH/skills/product-design/venv" ]; then
  echo "❌ product-design skill not set up"
  echo ""
  echo "Run setup (30 seconds):"
  echo "  cd $PLUGIN_PATH/skills/product-design && ./setup.sh"
  echo ""
  echo "Or use manual workflow (no Python needed)"
  exit 1
fi
```

**If setup missing**:
- Show setup instructions
- Offer manual workflow as alternative
- **Do not proceed** with automated Figma workflow

**If setup complete**:
- Continue to Step 1 (Design Analysis)

---

### Step 1: Design Analysis

**Objective**: Extract design patterns from Figma or manual description

#### With Figma MCP (Automated) ✨ SIMPLIFIED

**New Architecture** (v1.1.0+): Python directly connects to Figma MCP - no manual orchestration!

```python
# Python functions now handle MCP connection automatically
from figma_mcp_client import FigmaMCPClient

async with FigmaMCPClient() as client:
    # Progressive refinement - fetch only what's needed
    metadata = await client.get_metadata()
    components = extract_components(metadata)

    # Fetch details only for complex components
    for comp in components:
        if comp['complexity'] == 'high':
            comp['detail'] = await client.get_design_context(comp['id'])

    # Get design tokens
    variables = await client.get_variable_defs()
```

**Workflow** (fully automated):
1. User provides Figma URL
2. Run `python3 functions/design_analyzer.py --figma-url <URL>`
3. Python connects to Figma MCP (http://127.0.0.1:3845/mcp)
4. Fetches metadata → analyzes → fetches details only if needed
5. Returns complete analysis

**Benefits**:
- ✅ No manual MCP to