/product-design

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**

   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**:

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**:

# 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 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)

**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

# 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

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

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