dss/dss-claude-plugin/README.md

# DSS Claude Plugin

Design System Swarm (DSS) integration for Claude Code - A comprehensive plugin for analyzing, extracting, and generating design system tokens and components.

## Overview

The DSS Claude Plugin brings the power of DSS directly into Claude Code, enabling:

- **Project Analysis**: Scan codebases for design patterns and tokenization opportunities
- **Token Extraction**: Extract design tokens from CSS, SCSS, Tailwind, and JSON
- **Theme Generation**: Generate theme files using style-dictionary
- **Component Auditing**: Audit components for design system adoption
- **Storybook Integration**: Set up and configure Storybook
- **Figma Sync**: Import tokens directly from Figma files
- **Quick Wins**: Find low-effort, high-impact improvements

## Installation

### Local Development Setup

For local machines with GUI (desktop/laptop):

```bash
# 1. Clone the repository
git clone https://github.com/overbits/dss.git
cd dss

# 2. Run the setup script
./setup.sh

# 3. Install the plugin in Claude Code
claude /plugin install ./dss-claude-plugin
```

Or manually:

```bash
# 1. Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt
playwright install chromium

# 3. Install the plugin
claude /plugin install ./dss-claude-plugin
```

### Remote/Headless Server Setup

For remote servers, VPS, Docker, or CI/CD environments:

```bash
# 1. Clone the repository
git clone https://github.com/overbits/dss.git
cd dss

# 2. Install dependencies (headless mode)
pip install -r requirements.txt
playwright install chromium --with-deps  # Installs system dependencies

# 3. Install the plugin in Claude Code
claude /plugin install ./dss-claude-plugin
```

**Docker Setup:**

```dockerfile
FROM python:3.10-slim

# Install system dependencies for Playwright
RUN apt-get update && apt-get install -y \
    libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
    libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
    libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2

WORKDIR /app
COPY . .

RUN pip install -r requirements.txt
RUN playwright install chromium

# DSS MCP server runs on stdio
CMD ["python3", "dss-claude-plugin/servers/dss-mcp-server.py"]
```

### Claude Code Configuration

After installing the plugin, Claude Code automatically configures the MCP server. The configuration is stored in `.mcp.json`:

```json
{
  "mcpServers": {
    "dss": {
      "command": "python3",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/dss-mcp-server.py"],
      "env": {
        "PYTHONPATH": "/path/to/dss/dss-mvp1",
        "DSS_HOME": "~/.dss"
      }
    }
  }
}
```

### Connecting Local Claude Code to Remote Server

You can run Claude Code locally while connecting to a DSS MCP server running on a remote machine.

#### Option 1: SSH Tunnel (Recommended)

Create an SSH tunnel to forward the remote MCP server:

```bash
# On local machine - tunnel remote MCP server
ssh -L 9222:localhost:9222 -L 3456:localhost:3456 user@remote-server
```

This forwards:
- Port 9222: Chrome DevTools Protocol
- Port 3456: Your web application

Then use `devtools_connect(port=9222)` as if it were local.

#### Option 2: Remote MCP via SSH

Configure Claude Code to run the MCP server over SSH. Add to your local `~/.claude/settings.json` or project `.mcp.json`:

```json
{
  "mcpServers": {
    "dss-remote": {
      "command": "ssh",
      "args": [
        "user@remote-server",
        "python3",
        "/home/user/dss/dss-claude-plugin/servers/dss-mcp-server.py"
      ],
      "env": {
        "PYTHONPATH": "/home/user/dss/dss-mvp1"
      },
      "description": "Remote DSS MCP server via SSH"
    }
  }
}
```

#### Option 3: HTTP Proxy (Advanced)

For shared team access, run the MCP server behind an HTTP proxy:

```bash
# On remote server - start MCP with HTTP transport
# (Requires mcp-proxy or similar)
python3 -m mcp.server.http --port 8080 dss-claude-plugin/servers/dss-mcp-server.py
```

Then configure Claude Code to connect via HTTP:

```json
{
  "mcpServers": {
    "dss-remote": {
      "url": "http://remote-server:8080",
      "transport": "http"
    }
  }
}
```

#### Option 4: VS Code Remote / SSH Workspace

If using Claude Code in VS Code with Remote SSH extension:

1. Connect VS Code to remote server via Remote SSH
2. Install Claude Code extension in remote context
3. DSS plugin runs natively on remote - no tunneling needed

### Verify Installation

```bash
# Check DSS tools are available
claude --list-tools | grep dss

# Check DevTools are available (requires Playwright)
claude --list-tools | grep devtools

# Test the MCP server directly
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python3 dss-claude-plugin/servers/dss-mcp-server.py
```

## Requirements

- Claude Code >= 1.0.0
- Python 3.10+
- Node.js 18+ (for style-dictionary)
- DSS MVP1 installed at `/path/to/dss/dss-mvp1`

### Python Dependencies

```bash
pip install mcp pydantic pydantic-settings playwright aiohttp
playwright install chromium
```

Or run the full setup:
```bash
./setup.sh
```

### Optional: Figma Integration

Set your Figma personal access token:
```bash
export FIGMA_TOKEN=your-figma-token
```

## Commands

| Command | Description |
|---------|-------------|
| `/dss-analyze [path]` | Analyze project for design system patterns |
| `/dss-extract [path] [sources]` | Extract design tokens |
| `/dss-generate <format> [name]` | Generate theme files |
| `/dss-audit [path]` | Audit components for DS adoption |
| `/dss-storybook <action> [path]` | Storybook setup and configuration |
| `/dss-figma <file_key>` | Sync tokens from Figma |
| `/dss-quick-wins [path]` | Find quick win opportunities |

## Skills

The plugin includes 7 procedural skills:

1. **design-system-analysis** - Comprehensive codebase analysis
2. **token-extraction** - Multi-source token extraction
3. **theme-generation** - Style-dictionary theme generation
4. **component-audit** - React component auditing
5. **storybook-integration** - Storybook setup and stories
6. **figma-sync** - Figma API integration
7. **quick-wins** - Quick win identification

## Agents

Two specialized agents for complex tasks:

### DSS Architect
Planning and designing design system implementations.
```
"Help me plan a design system for our React application"
```

### DSS Migrator
Migrating existing codebases to design systems.
```
"Help me migrate our button components to use design tokens"
```

## MCP Tools

The plugin exposes DSS tools and Chrome DevTools tools:

### DSS Tools

| Tool | Description |
|------|-------------|
| `dss_analyze_project` | Full project analysis |
| `dss_extract_tokens` | Extract tokens from sources |
| `dss_generate_theme` | Generate theme files |
| `dss_list_themes` | List available themes |
| `dss_get_status` | Get DSS system status |
| `dss_audit_components` | Component audit |
| `dss_setup_storybook` | Storybook configuration |
| `dss_sync_figma` | Figma token sync |
| `dss_find_quick_wins` | Quick win analysis |
| `dss_transform_tokens` | Token format transformation |

### Chrome DevTools Tools

| Tool | Description |
|------|-------------|
| `devtools_launch` | Launch headless Chromium (for remote/headless servers) |
| `devtools_connect` | Connect to running Chrome with CDP (port 9222) |
| `devtools_disconnect` | Disconnect and clean up resources |
| `devtools_list_pages` | List all browser tabs/pages |
| `devtools_select_page` | Select active page for operations |
| `devtools_goto` | Navigate to a URL |
| `devtools_console_logs` | Get captured console messages |
| `devtools_network_requests` | Get captured network activity |
| `devtools_evaluate` | Execute JavaScript in page context |
| `devtools_query_dom` | Query DOM elements with CSS selector |
| `devtools_screenshot` | Capture page/element screenshots (base64 PNG) |
| `devtools_performance` | Get Core Web Vitals and performance metrics |

## Hooks

The plugin includes hooks for automation:

- **PreToolUse**: Validates Figma token before sync
- **PostToolUse**: Logs completion of major operations

## Usage Examples

### Analyze a Project

```
/dss-analyze /path/to/project
```

Returns comprehensive analysis including:
- File counts and types
- Style patterns discovered
- Component analysis
- Recommendations

### Extract and Generate Tokens

```
/dss-extract /path/to/styles css,scss
/dss-generate css my-theme
```

### Audit Components

```
/dss-audit /path/to/components
```

Identifies:
- Hardcoded values
- Consolidation opportunities
- Refactoring suggestions

### Sync from Figma

```
/dss-figma abc123xyz456
```

Extracts:
- Colors from fill styles
- Typography from text styles
- Spacing from auto-layout
- Effects and shadows

## Chrome DevTools Integration

The plugin includes Chrome DevTools Protocol (CDP) integration for browser debugging, console capture, network monitoring, and performance analysis.

### Remote/Headless Server Setup

For remote or headless servers (no GUI), use the `devtools_launch` tool to spawn a headless Chromium instance:

```python
# 1. Launch headless browser and navigate to your app
devtools_launch(url="http://localhost:3456")

# 2. Get console logs
devtools_console_logs()

# 3. Navigate to another page
devtools_goto(url="http://localhost:3456/dashboard")

# 4. Capture screenshot
devtools_screenshot(full_page=True)

# 5. Get performance metrics
devtools_performance()

# 6. Execute JavaScript
devtools_evaluate(expression="document.title")

# 7. Query DOM
devtools_query_dom(selector=".error-message")

# 8. Clean up
devtools_disconnect()
```

### Local Desktop Setup

For local development with Chrome GUI, launch Chrome with remote debugging enabled:

```bash
# Linux
google-chrome --remote-debugging-port=9222

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
```

Then connect using the `devtools_connect` tool:

```python
# 1. Connect to running Chrome
devtools_connect(port=9222)

# 2. List available tabs
devtools_list_pages()

# 3. Select a tab
devtools_select_page(page_id="...")

# 4. Capture console logs, network, etc.
devtools_console_logs()
devtools_network_requests()

# 5. Disconnect when done
devtools_disconnect()
```

### DevTools Configuration

The MCP server includes configurable limits:

```python
DEVTOOLS_CONSOLE_MAX_ENTRIES = 1000    # Max console messages stored
DEVTOOLS_NETWORK_MAX_ENTRIES = 500     # Max network requests stored
DEVTOOLS_CONNECTION_TIMEOUT_MS = 30000 # Connection timeout (30s)
```

### Common Use Cases

**Debug Console Errors:**
```python
devtools_launch(url="http://localhost:3000")
devtools_console_logs(level="error")
```

**Monitor Network Requests:**
```python
devtools_launch(url="http://localhost:3000")
devtools_network_requests(filter_url="api/")
```

**Performance Analysis:**
```python
devtools_launch(url="http://localhost:3000")
devtools_performance()
# Returns: FCP, LCP, TTFB, DOM metrics
```

**Visual Regression Testing:**
```python
devtools_launch(url="http://localhost:3000")
devtools_screenshot(full_page=True)
# Returns: base64 PNG image
```

## Architecture

```
dss-claude-plugin/
├── .claude-plugin/
│   └── plugin.json           # Plugin metadata
├── commands/                  # 7 slash commands
├── skills/                    # 7 procedural skills
├── agents/                    # 2 specialized agents
├── hooks/
│   └── hooks.json            # Event hooks
├── servers/
│   └── dss-mcp-server.py     # Python MCP server
├── .mcp.json                 # MCP configuration
└── README.md
```

## Configuration

### Environment Variables

| Variable | Description |
|----------|-------------|
| `FIGMA_TOKEN` | Figma personal access token |
| `DSS_HOME` | DSS home directory (default: ~/.dss) |
| `PYTHONPATH` | Path to DSS MVP1 modules |

### Timeouts

The MCP server includes configurable timeouts:

```python
TIMEOUT_CONFIG = {
    "analyze": 60,           # Large project scanning
    "extract": 30,           # Token extraction
    "generate": 30,          # Theme generation
    "figma_api": 15,         # Figma API calls
    "storybook": 60,         # Storybook operations
    "devtools_connect": 20,  # DevTools CDP connection
    "devtools_default": 10,  # DevTools operations
}
```

## Development

### Running the MCP Server Directly

```bash
cd /home/overbits/dss/dss-claude-plugin
python3 servers/dss-mcp-server.py
```

### Testing

```bash
# Test MCP server
echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python3 servers/dss-mcp-server.py
```

## Troubleshooting

### DSS Modules Not Found

Ensure PYTHONPATH is set correctly:
```bash
export PYTHONPATH=/home/overbits/dss/dss-mvp1
```

### Figma Sync Fails

1. Check FIGMA_TOKEN is set
2. Verify file key is correct
3. Check API rate limits

### Slow Analysis

For large projects, analysis may take longer. The timeout is set to 60 seconds by default.

### DevTools Launch Fails

1. Ensure Playwright is installed: `pip install playwright`
2. Install Chromium browser: `playwright install chromium`
3. On Docker/remote: ensure `--no-sandbox` flag is used (handled automatically)

### DevTools Connect Fails

1. Ensure Chrome is running with: `--remote-debugging-port=9222`
2. Check the port is not blocked by firewall
3. Verify connection: `curl http://localhost:9222/json`

### DevTools Playwright Not Available

The server gracefully degrades if Playwright isn't installed. DevTools tools will not appear in the tool list. Install with:

```bash
pip install playwright aiohttp
playwright install chromium
```

## License

MIT License - See LICENSE file for details.

## Author

overbits - https://overbits.luz.uy

## Links

- [DSS Homepage](https://dss.overbits.luz.uy)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Claude Code](https://claude.ai/code)
- [Style Dictionary](https://amzn.github.io/style-dictionary)