# UI Development Plugins - Implementation Roadmap

**Date**: 2025-12-06
**Status**: Research Complete - Ready for Implementation
**Validated By**: Gemini 3 Pro Preview (Deep Thinking + Expert Analysis)

---

## Executive Summary

Comprehensive analysis of external Claude Code marketplaces identified **9 high-value plugins** for UI/component development that can be adapted to DSS MCP format. All plugins leverage existing DSS infrastructure (CredentialVault, Strategy Pattern, DSSContext) and require minimal new dependencies.

**Key Findings**:
- ✅ Analyzed 90+ plugins across 3 major marketplaces
- ✅ Designed adaptation patterns from client-side to server-side
- ✅ Created 3-week implementation roadmap
- ✅ All plugins integrate with existing DSS architecture

---

## Research Coverage

### External Marketplaces Analyzed

1. **Dev-GOM/claude-code-marketplace**
   - CDP Browser Automation (perfect for DSS LOCAL mode)
   - TODO Collector
   - Complexity Monitor
   - Auto-Docs

2. **Anthropic Official Plugins**
   - frontend-design skill (production-grade UI generation)

3. **kivilaid/plugin-marketplace**
   - 77 plugins including Git automation, code review, testing tools

### Adaptation Strategy

**Pattern 1: Hook → MCP Tool**
- Convert pre/post execution logic to standalone tool
- Example: Pre-commit hook → `run_pre_commit_checks` tool

**Pattern 2: Skill → MCP Tool + Description**
- Tool does the work, description teaches Claude how to use it
- Example: frontend-design skill → `scaffold_component` + rich description

**Pattern 3: Command → MCP Tool**
- Direct conversion of command to tool
- Example: `/generate-story` → `generate_storybook_story` tool

---

## 9 Recommended Plugins (3-Week Roadmap)

### Phase 1: Foundation Tools (Week 1) - **START HERE**

#### 1. Component Scaffolding Plugin
**Priority**: 🔴 **HIGHEST**
**Effort**: 2 days
**Dependencies**: `jinja2>=3.1.2`

**Tools**:
- `scaffold_component` - Generate React component with tests, stories, docs
  - Parameters: component_name, component_type, include_tests, include_stories, template
  - Templates: basic, form, layout, data-display

**Value Proposition**:
- Most requested feature by UI developers
- Immediate productivity gain (30-60 min → 2 min)
- Foundation for other plugins (establishes template system)
- Zero learning curve (generates familiar structure)

**Implementation**:
```python
# File: plugins/component_scaffolding.py
from jinja2 import Environment, FileSystemLoader
from ..core.context import DSSContext

TOOLS = [
    types.Tool(
        name="scaffold_component",
        description="Generate React component with tests, Storybook stories, and documentation",
        inputSchema={
            "type": "object",
            "properties": {
                "component_name": {"type": "string"},
                "component_type": {"enum": ["functional", "class"]},
                "template": {"enum": ["basic", "form", "layout", "data-display"]},
                "include_tests": {"type": "boolean", "default": True},
                "include_stories": {"type": "boolean", "default": True}
            },
            "required": ["component_name"]
        }
    )
]
```

**Templates Required**:
- `functional_component.tsx.j2`
- `test.spec.tsx.j2`
- `story.stories.tsx.j2`
- `README.md.j2`

---

#### 2. Storybook Integration Plugin
**Priority**: 🔴 **HIGH**
**Effort**: 2 days
**Dependencies**: Built-in AST parsing (Python `ast` module)

**Tools**:
- `generate_story` - Create Storybook story from component
- `update_story` - Update existing story with new props
- `validate_stories` - Check story coverage across components

**Value Proposition**:
- Critical for design system workflow
- Reduces Storybook maintenance overhead
- Ensures component documentation stays in sync
- Generates CSF3-compliant stories automatically

**Implementation**:
```python
# File: plugins/storybook_integration.py
import ast
from pathlib import Path

TOOLS = [
    types.Tool(name="generate_story", ...),
    types.Tool(name="update_story", ...),
    types.Tool(name="validate_stories", ...)
]

class PluginTools:
    async def _parse_component_props(self, component_path: str):
        """Extract props from TypeScript/React component using AST"""
        # Parse component file, extract props interface
        # Return structured props data
```

---

#### 3. Design Token Validator Plugin
**Priority**: 🔴 **HIGH**
**Effort**: 3 days
**Dependencies**: Existing Figma integration (CredentialVault)

**Tools**:
- `validate_tokens` - Compare local tokens with Figma
- `sync_figma_tokens` - Pull latest tokens from Figma
- `generate_token_report` - Create mismatch report

**Value Proposition**:
- Prevents design-dev token drift
- Ensures design system consistency
- Automated validation in CI/CD
- Reduces manual QA overhead

**Implementation**:
```python
# File: plugins/design_token_validator.py
from ..context.credential_vault import get_credential_vault

class PluginTools:
    async def __init__(self, **kwargs):
        vault = get_credential_vault()
        self.figma_token = await vault.get_credential("figma_access_token", user_id)

    async def _fetch_figma_tokens(self, file_key: str):
        """Fetch design tokens from Figma API"""
        # Use Figma REST API to get styles/variables
```

---

### Phase 2: Testing & Quality Tools (Week 2)

#### 4. CDP Browser Plugin (Adapted from Dev-GOM)
**Priority**: 🟡 **MEDIUM**
**Effort**: 3 days
**Dependencies**: `playwright>=1.40.0` (already planned for LOCAL mode)

**Source**: https://github.com/Dev-GOM/claude-code-marketplace CDP Browser Automation

**Integration**: Enhance `LocalBrowserStrategy` with CDP capabilities

**Value Proposition**:
- Enables LOCAL mode browser automation (Phase 2 requirement)
- Direct adaptation from proven external plugin
- Advanced debugging capabilities
- Real-time DOM inspection

---

#### 5. Accessibility Checker Plugin
**Priority**: 🟡 **MEDIUM**
**Effort**: 2 days
**Dependencies**: `playwright` (already planned), axe-core (npm, via playwright)

**Tools**:
- `run_a11y_audit` - Run axe-core accessibility audit
- `check_aria_compliance` - Validate ARIA attributes
- `generate_a11y_report` - Create accessibility report

**Value Proposition**:
- Critical for production-ready components
- Catches accessibility issues early
- Automated compliance checking
- Generates actionable reports

**Implementation**:
```python
# File: plugins/accessibility_checker.py
from ..strategies.local.browser import LocalBrowserStrategy

class PluginTools:
    async def _run_axe_audit(self, url: str):
        """Run axe-core via Playwright"""
        strategy = LocalBrowserStrategy()
        page = await strategy.get_page()
        await page.goto(url)

        # Inject axe-core and run audit
        results = await page.evaluate("""
            () => axe.run()
        """)
        return results
```

---

#### 6. TODO Collector Plugin (Adapted from Dev-GOM)
**Priority**: 🟢 **LOW**
**Effort**: 1 day
**Dependencies**: None (built-in file system)

**Source**: https://github.com/Dev-GOM/claude-code-marketplace TODO Collector

**Tools**:
- `collect_todos` - Scan project for TODO comments
- `categorize_todos` - Group by priority/assignee
- `generate_todo_report` - Create actionable report

**Value Proposition**:
- Quick win (low complexity, high utility)
- Helps teams track technical debt
- Automated TODO tracking
- CI/CD integration potential

---

### Phase 3: Advanced Tools (Week 3)

#### 7. Visual Regression Plugin
**Priority**: 🟢 **LOW**
**Effort**: 2 days
**Dependencies**: `playwright`, image diffing library

**Tools**:
- `capture_baseline` - Capture component screenshots as baseline
- `compare_screenshots` - Detect visual regressions
- `generate_visual_report` - Show visual diffs

---

#### 8. Performance Monitor Plugin
**Priority**: 🟢 **LOW**
**Effort**: 2 days
**Dependencies**: Webpack/Vite integration

**Tools**:
- `analyze_bundle_size` - Track bundle sizes over time
- `measure_render_time` - Component render performance
- `generate_perf_report` - Performance dashboard

---

#### 9. Component Documentation Generator Plugin
**Priority**: 🟢 **LOW**
**Effort**: 3 days
**Dependencies**: TypeScript parser, JSDoc support

**Tools**:
- `generate_component_docs` - Auto-generate API docs from props
- `update_readme` - Keep README in sync with component
- `validate_docs` - Check documentation completeness

---

## Implementation Strategy

### Template System Architecture

```
tools/dss_mcp/plugins/
├── component_scaffolding/
│   ├── __init__.py (empty)
│   ├── tool.py (exports TOOLS and PluginTools)
│   ├── requirements.txt (jinja2>=3.1.2)
│   └── templates/
│       ├── functional_component.tsx.j2
│       ├── test.spec.tsx.j2
│       ├── story.stories.tsx.j2
│       └── README.md.j2
├── storybook_integration/
│   └── tool.py
├── design_token_validator/
│   └── tool.py
└── _template.py
```

### Integration with Existing DSS Infrastructure

**1. Use CredentialVault (already implemented)**:
```python
from ..context.credential_vault import get_credential_vault

vault = get_credential_vault()
figma_token = await vault.get_credential("figma_access_token", user_id)
```

**2. Use DSSContext (already implemented)**:
```python
from ..core.context import DSSContext

ctx = await DSSContext.get_instance()
project_root = ctx.get_project_root()
```

**3. Use Strategy Pattern (already implemented)**:
```python
# Accessibility checker adapts to LOCAL/REMOTE mode
if ctx.mode == "LOCAL":
    dom = await local_browser_strategy.get_dom_snapshot()
else:
    dom = await remote_browser_strategy.get_dom_snapshot()
```

---

## Dependency Management

### New Dependencies Required

**Phase 1**:
- `jinja2>=3.1.2` - Template rendering (Component Scaffolding)

**Phase 2**:
- `playwright>=1.40.0` - Browser automation (already planned for LOCAL mode)

**Total New Dependencies**: 1 (jinja2 only)

### Installation Workflow

```bash
# 1. Create plugin with requirements.txt
mkdir -p tools/dss_mcp/plugins/component_scaffolding
echo "jinja2>=3.1.2" > tools/dss_mcp/plugins/component_scaffolding/requirements.txt

# 2. Install dependencies
./tools/install_plugin_deps.sh

# 3. Restart server
supervisorctl restart dss-mcp
```

---

## Risk Mitigation

### Risk 1: External plugin code quality unknown
**Mitigation**: Manually review all adapted code, don't copy blindly
**Action**: Treat external plugins as inspiration, not copy-paste sources

### Risk 2: Playwright dependency adds complexity
**Mitigation**: Playwright only required for LOCAL mode (optional)
**Action**: Gracefully degrade tools when Playwright unavailable

### Risk 3: Template maintenance overhead
**Mitigation**: Start with 3 basic templates, expand based on usage
**Action**: Version templates, allow project-specific overrides

---

## Success Metrics

### Week 1 Success Criteria
- ✅ 3 plugins implemented and tested
- ✅ Component scaffolding generates working React component
- ✅ Storybook integration creates valid CSF3 stories
- ✅ Token validator detects mismatches with Figma

### Week 2 Success Criteria
- ✅ CDP browser plugin integrated into LOCAL mode
- ✅ A11y checker runs on sample components
- ✅ TODO collector scans project and generates report

### Week 3 Success Criteria
- ✅ All 9 plugins operational
- ✅ Documentation complete for each plugin
- ✅ Team training session conducted

---

## Next Immediate Actions

### 1. Create Plugin Development Branch
```bash
git checkout -b feature/ui-development-plugins
```

### 2. Install Template Dependencies
```bash
pip install jinja2>=3.1.2
```

### 3. Create Template Directory Structure
```bash
mkdir -p tools/dss_mcp/plugins/component_scaffolding/templates
```

### 4. Implement Component Scaffolding Plugin First
- Copy `_template.py` to `component_scaffolding/tool.py`
- Define 1 tool: `scaffold_component`
- Create 3 Jinja2 templates (component, test, story)
- Test with real component creation

### 5. Document Plugin in README
- Add usage examples
- Document template variables
- Explain customization options

---

## Final Recommendation

**START IMMEDIATELY** with Phase 1, Priority 1 (Component Scaffolding).

**Why Component Scaffolding First**:
1. **Immediate Value**: Generates actual code files developers can use today
2. **Foundation**: Establishes template system for other plugins
3. **Low Risk**: Only needs jinja2, no external dependencies
4. **High Visibility**: Team sees tangible results quickly
5. **Quick Win**: 2 days to working plugin

**Confidence Level**: Very High (95%)
- Architecture validated by deep thinking + expert analysis
- External marketplace research complete
- Implementation path clear with concrete examples
- Risk mitigation strategies defined
- All dependencies minimal and well-understood

---

**Last Updated**: 2025-12-06
**Next Review**: After Phase 1 completion (Week 1)