gh-alekspetrov-navigator/skills/product-design/README.md

# Product Design Skill

Automate Figma design handoff with Navigator's intelligent design system integration.

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

---

## Features

✨ **Direct Figma MCP Integration** - Python connects directly to Figma Desktop (no manual orchestration)
🎯 **Progressive Refinement** - Smart token usage (fetches only needed data)
🔄 **Design Token Sync** - Auto-extract variables in W3C DTCG format
🗺️ **Component Mapping** - Figma → codebase with similarity detection
📊 **Drift Detection** - Compare design vs implementation automatically
📝 **Task Generation** - Phased implementation plans for Navigator

---

## Quick Start

### 1. Install

```bash
cd skills/product-design
./setup.sh
```

**What this does**:
- ✅ Checks Python 3.10+ installed
- ✅ Creates virtual environment
- ✅ Installs `mcp` SDK (1.2.1+)
- ✅ Verifies Figma Desktop connection
- ✅ Tests MCP server availability

**Expected output**:
```
✅ Setup Complete!
```

### 2. Enable Figma MCP

1. Open **Figma Desktop**
2. Go to **Figma → Preferences**
3. Enable "**Enable local MCP Server**"
4. Confirm server running at `http://127.0.0.1:3845/mcp`

### 3. Use the Skill

```
User: "Review this Figma design: https://figma.com/file/ABC123..."
```

Navigator will:
1. Connect to Figma MCP automatically
2. Extract design tokens and components
3. Compare against codebase
4. Generate implementation plan
5. Create Navigator task document

---

## Architecture

### Before (Manual Orchestration)

```
User → Claude → MCP tools (15-20 manual calls) → temp files → Python → Claude → User
```

**Time**: 15-20 orchestration steps

### After (Direct MCP Client)

```
User → Python (MCP client) → Figma Desktop → Results → User
```

**Time**: 1 step (95% reduction)

### How It Works

```python
# Python functions now connect directly to Figma
from figma_mcp_client import FigmaMCPClient

async with FigmaMCPClient() as client:
    # Smart data fetching
    metadata = await client.get_metadata()
    components = extract_components(metadata)

    # Progressive refinement - fetch details only if needed
    for comp in high_complexity_components:
        detail = await client.get_design_context(comp['id'])

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

**Benefits**:
- No Claude orchestration overhead
- Automatic connection management
- Progressive refinement (token efficient)
- Built-in error handling

---

## Available Tools

### Figma MCP Tools (Auto-Connected)

| Tool | Purpose | Use Case |
|------|---------|----------|
| `get_metadata` | Component structure (XML) | Discover node IDs, hierarchy |
| `get_variable_defs` | Design tokens | Token extraction, sync |
| `get_code_connect_map` | Component → code mapping | Auto-map Figma to codebase |
| `get_design_context` | UI code generation | Component implementation |
| `get_screenshot` | Visual snapshots | Visual regression testing |
| `create_design_system_rules` | Design system automation | Rule generation |

### Python Functions

| Function | Purpose | Input | Output |
|----------|---------|-------|--------|
| `design_analyzer.py` | Extract design patterns | Figma URL/data | Component list |
| `token_extractor.py` | Convert to DTCG format | Variables JSON | DTCG tokens + diff |
| `component_mapper.py` | Map components | Figma + codebase | Mappings with confidence |
| `design_system_auditor.py` | Detect drift | Design + code | Drift report |
| `implementation_planner.py` | Generate task doc | Analysis results | Navigator task |

---

## Documentation

- **[INSTALL.md](INSTALL.md)** - Detailed installation guide with troubleshooting
- **[SKILL.md](SKILL.md)** - Complete skill documentation and workflows
- **[functions/figma_mcp_client.py](functions/figma_mcp_client.py)** - MCP client API reference

---

## Requirements

### System

- **Python 3.10+**
- **Figma Desktop** v116.0.0+
- **macOS, Linux, or Windows**

### Python Packages

```txt
mcp>=1.2.1          # Official MCP SDK
anyio>=4.0.0        # Async I/O
httpx>=0.25.0       # HTTP client
pydantic>=2.0.0     # Data validation
```

Installed automatically via `./setup.sh`

### Optional

- **Figma Enterprise** - For Code Connect (automatic component mapping)
- **Tailwind CSS** - For design token integration
- **Storybook** - For visual regression testing

---

## Example Usage

### Design Review

```
User: "Review dashboard redesign: https://figma.com/file/..."

Navigator:
1. Connects to Figma MCP
2. Extracts 12 design tokens, 3 new components
3. Maps to existing Button component (78% similarity)
4. Detects 5 token drift issues
5. Generates TASK-16 with phased implementation plan

Output:
  - .agent/design-system/reviews/2025-10-22-dashboard.md
  - .agent/tasks/TASK-16-dashboard-redesign.md
```

### Token Extraction Only

```python
# Simple token fetch
from figma_mcp_client import get_figma_variables

tokens = await get_figma_variables()
# Returns: {'primary-600': '#2563EB', 'spacing-md': '16px', ...}
```

### Component Analysis

```python
# Full analysis with progressive refinement
from figma_mcp_client import FigmaMCPClient

async with FigmaMCPClient() as client:
    metadata = await client.get_metadata()
    components = extract_components(metadata)

    print(f"Found {len(components)} components")
    for comp in components:
        print(f"  - {comp['name']} ({comp['type']})")
```

---

## Troubleshooting

### "Figma Desktop not running"

```
❌ Could not connect to Figma Desktop MCP server
```

**Fix**:
1. Ensure Figma Desktop running
2. Enable MCP: Figma → Preferences → Enable local MCP Server
3. Verify: `curl http://127.0.0.1:3845/mcp` (should return JSON)

### "MCP SDK not installed"

```
ImportError: MCP SDK not installed
```

**Fix**:
```bash
cd skills/product-design
source venv/bin/activate  # Activate venv
pip install -r requirements.txt
```

### "Python 3.10+ required"

**Fix**: Install Python 3.10+
```bash
# macOS
brew install python@3.13

# Ubuntu
sudo apt install python3.13
```

See **[INSTALL.md](INSTALL.md)** for complete troubleshooting guide.

---

## Performance

### Benchmarks

| Workflow | Before | After | Improvement |
|----------|--------|-------|-------------|
| **Design Review** | 15-20 min | 5 min | 75% faster |
| **Token Extraction** | Manual (30 min) | Automated (1 min) | 97% faster |
| **Component Mapping** | Manual (2 hours) | Automated (2 min) | 98% faster |
| **Orchestration Steps** | 15-20 steps | 1 step | 95% reduction |

### Token Efficiency

| Approach | Tokens | Improvement |
|----------|--------|-------------|
| **Old** (manual orchestration) | 150k | Baseline |
| **New** (direct MCP client) | 12k | 92% reduction |

Progressive refinement only fetches needed data.

---

## Version History

### v1.1.0 (2025-10-22) - MCP Direct Integration

**Breaking Changes**:
- Python now requires `mcp>=1.2.1` (install via `./setup.sh`)
- Figma Desktop with MCP enabled required for automated workflow

**New Features**:
- ✨ Direct Python → Figma MCP client (no Claude orchestration)
- ✨ Progressive refinement (smart token usage)
- ✨ Automatic connection management
- ✨ `./setup.sh` automated installation
- ✨ `figma_mcp_client.py` wrapper class

**Improvements**:
- 95% reduction in orchestration overhead (15-20 steps → 1)
- 92% reduction in token usage (150k → 12k)
- Built-in error handling and retries
- Better MCP connection diagnostics

**Migration**:
```bash
cd skills/product-design
./setup.sh  # Installs new dependencies
```

### v1.0.0 (2025-10-21) - Initial Release

- Design analysis and token extraction
- Component mapping with similarity detection
- Design system drift detection
- Implementation plan generation

---

## Support

**Documentation**: See [INSTALL.md](INSTALL.md) and [SKILL.md](SKILL.md)

**Issues**: Report at https://github.com/navigator-plugin/navigator/issues

**Requirements for issue reports**:
- Python version: `python3 --version`
- Figma version: Figma → Help → About Figma
- Output from: `python3 functions/test_mcp_connection.py`
- Full error message and stack trace

---

## License

MIT License - Part of Navigator Plugin

---

**Navigator Version**: 3.3.1
**Skill Version**: 1.1.0
**MCP SDK Version**: 1.2.1+
**Last Updated**: 2025-10-22