product-design

What this skill does

# 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 tool calls by Claude
- ✅ Progressive refinement (smart token usage)
- ✅ Automatic connection management
- ✅ Built-in error handling

**Requirements**:
- Figma Desktop running
- MCP enabled in preferences
- Python dependencies installed (`./setup.sh`)

#### Manual Workflow (No MCP)

```markdown
**Ask user for design information**:

What is the feature name? [e.g., "Dashboard Redesign"]

Figma link (optional): [figma.com/file/...]

**Design Tokens**:
List new or modified tokens:
- Colors (name: value, e.g., "primary-600: #2563EB")
- Spacing (e.g., "spacing-lg: 24px")
- Typography (e.g., "heading-xl: 36px/600")
- Other (radius, shadow, etc.)

**Components**:
List components in design:
- Component name
- Type (atom, molecule, organism)
- Variants (if any, e.g., "Button: primary/secondary, sm/md/lg")
- Similar to existing component? (name if known)

**Proceed to Step 2** after gathering information
```

#### Run design_analyzer.py

```bash
# Prepare input (MCP or manual JSON)
# MCP: Already have /tmp/figma_metadata.json
# Manual: Create JSON from user input

python3 functions/design_analyzer.py \
  --figma-data /tmp/figma_combined.json \
  --ui-kit-inventory .agent/design-system/ui-kit-inventory.json \
  --output /tmp/analysis_results.json
```

**Analysis Output**:
- New components not in UI kit
- Similar components (reuse opportunities)
- New design tokens
- Breaking changes (if any)

---

### Step 2: Codebase Audit

**Objective**: Compare design vs implementation, detect drift

#### Token Extraction

```bash
python3 functions/token_extractor.py \
  --figma-variables /tmp/figma_variables.json \
  --existing-tokens .agent/design-system/design-tokens.json \
  --output /tmp/token_extraction.json
```

**Output**: DTCG formatted tokens + diff summary

#### Component Mapping

```bash
python3 functions/component_mapper.py \
  --figma-components /tmp/analysis_results.json \
  --code-connect-map /tmp/figma_code_connect.json \
  --project-root . \
  --output /tmp/component_mappings.json
```

**Output**: Figma component → code component mappings with confidence scores

#### Design System Audit

```bash
# Combine data for auditor
python3 functions/design_system_auditor.py \
  --figma-data /tmp/combined_figma.json \
  --code-data /tmp/combined_code.json \
  --output /tmp/audit_results.json
```

**Audit Results**:
- Token alignment (in sync, drift, missing, unused)
- Component reuse opportunities
- Tailwind config recommendations
- Priority level (critical, high, medium, low)

---

### Step 3: Implementation Planning

**Objective**: Generate phased implementation task document

#### Generate Task Document

```bash
python3 functions/implementation_planner.py \
  --task-id "TASK-{{next_task_number}}" \
  --feature-name "{{feature_name}}" \
  --analysis-results /tmp/combined_analysis.json \
  --review-reference ".agent/design-system/reviews/{{date}}-{{feature-slug}}.md" \
  --output .agent/tasks/TASK-{{next_task_number}}-{{feature-slug}}.md
```

**Task Document Includes**:
- Phased implementation (tokens → atoms → molecules → organisms)
- Complexity estimates per phase
- Acceptance criteria checklist
- Files to modify
- Testing strategy
- Rollout plan

#### Create Design Review Report

**Use template**: `templates/design-review-report.md`

**Save to**: `.agent/design-system/reviews/YYYY-MM-DD-{{feature-name}}.md`

**Contents**:
- Design analysis summary
- Token changes (added/modified/removed)
- Component changes (new/extended/breaking)
- Design system impact
- Implementation recommendations

---

### Step 4: Task Assignment

**Objective**: Create task and assign context for implementation

#### Create PM Ticket (if configured)

```markdown
**If PM tool configured** (Linear, GitHub Issues, Jira):
- Create ticket with task summary
- Link to task document and design review
- Assign to frontend developer or team

**If no PM tool**:
- Skip ticket creation
- Task document serves as source of truth
```

#### Update Navigator Documentation

```markdown
**Update files**:
1. `.agent/tasks/TASK-{{number}}-{{feature}}.md` (created in Step 3)
2. `.agent/design-system/reviews/{{date}}-{{feature}}.md` (design review)
3. `.agent/DEVELOPMENT-README.md` (add task to index)

**Use TodoWrite** to track implementation phases
```

---

### Step 5: Implementation Handoff

**Objective**: Present results and get user decision

#### Present Summar