Initial commit
This commit is contained in:
Zhongwei Li
336
skills/product-design/README.md
Normal file
336
skills/product-design/README.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user