Initial commit: Clean DSS implementation
Migrated from design-system-swarm with fresh git history.
Old project history preserved in /home/overbits/apps/design-system-swarm
Core components:
- MCP Server (Python FastAPI with mcp 1.23.1)
- Claude Plugin (agents, commands, skills, strategies, hooks, core)
- DSS Backend (dss-mvp1 - token translation, Figma sync)
- Admin UI (Node.js/React)
- Server (Node.js/Express)
- Storybook integration (dss-mvp1/.storybook)
Self-contained configuration:
- All paths relative or use DSS_BASE_PATH=/home/overbits/dss
- PYTHONPATH configured for dss-mvp1 and dss-claude-plugin
- .env file with all configuration
- Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability
Migration completed: $(date)
🤖 Clean migration with full functionality preserved
This commit is contained in:
Digital Production Factory
395
tools/dss_mcp/STRATEGIC_ANALYSIS.md
Normal file
395
tools/dss_mcp/STRATEGIC_ANALYSIS.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# DSS MCP Plugin - Strategic Analysis & Architecture Review
|
||||
|
||||
**Date:** December 9, 2024
|
||||
**Phase:** Post-Phase 1 Implementation (Storybook Integration Complete)
|
||||
**Purpose:** Deep thinking on architecture alignment, workflow validation, and next steps
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
After completing Phase 1 (Storybook Integration) via Zen Swarm methodology, a deep architectural review reveals critical insights that should inform our path forward:
|
||||
|
||||
###🔍 Key Findings:
|
||||
|
||||
1. **Translation Dictionaries are NOT implemented** in DSS Python core (only documented in principles)
|
||||
2. **"Skins" concept may be misaligned** with actual DSS architecture
|
||||
3. **Phase 2/3 implementation plan needs refinement** based on what's actually in the codebase
|
||||
4. **Workflow validation is critical** before proceeding to Phase 2
|
||||
|
||||
---
|
||||
|
||||
## 1. Current Architecture State
|
||||
|
||||
### DSS Python Core (`dss-mvp1/dss/`)
|
||||
|
||||
```
|
||||
dss/
|
||||
├── ✅ storybook/ # Scanner, generator, theme (MCP Phase 1 COMPLETE)
|
||||
│ ├── scanner.py # StorybookScanner - scan existing stories
|
||||
│ ├── generator.py # StoryGenerator - generate CSF3/CSF2/MDX stories
|
||||
│ ├── theme.py # ThemeGenerator - create Storybook themes
|
||||
│ └── config.py # Configuration utilities
|
||||
│
|
||||
├── ✅ themes/ # Default light/dark themes (FULLY IMPLEMENTED)
|
||||
│ └── default_themes.py # get_default_light_theme(), get_default_dark_theme()
|
||||
│
|
||||
├── ✅ ingest/ # Multi-source token extraction (COMPLETE)
|
||||
│ ├── css.py # CSSTokenSource
|
||||
│ ├── scss.py # SCSSTokenSource
|
||||
│ ├── tailwind.py # TailwindTokenSource
|
||||
│ ├── json_tokens.py # JSONTokenSource
|
||||
│ └── merge.py # TokenMerger
|
||||
│
|
||||
├── ✅ tools/ # External tool integrations
|
||||
│ ├── figma.py # FigmaWrapper (MCP tools exist)
|
||||
│ ├── shadcn.py # ShadcnWrapper (no MCP tools yet)
|
||||
│ └── style_dictionary.py # StyleDictionaryWrapper (no MCP tools yet)
|
||||
│
|
||||
├── ✅ analyze/ # Code analysis and scanning
|
||||
│ ├── scanner.py # ProjectScanner
|
||||
│ ├── react.py # ReactAnalyzer
|
||||
│ ├── quick_wins.py # QuickWinFinder
|
||||
│ └── styles.py # StyleAnalyzer
|
||||
│
|
||||
├── ✅ export_import/ # Project export/import
|
||||
│ ├── exporter.py # Export project data
|
||||
│ ├── importer.py # Import project data
|
||||
│ └── merger.py # Merge strategies
|
||||
│
|
||||
├── ✅ models/ # Data structures
|
||||
│ ├── theme.py # Theme, DesignToken, TokenCategory
|
||||
│ ├── component.py # Component, ComponentVariant
|
||||
│ └── project.py # Project, ProjectMetadata
|
||||
│
|
||||
├── ❌ translations/ # MISSING - Not implemented!
|
||||
│ └── (no files) # Translation dictionaries are documented but not coded
|
||||
│
|
||||
└── ✅ storage/ # SQLite persistence
|
||||
└── database.py # get_connection(), Project/Token storage
|
||||
```
|
||||
|
||||
### MCP Plugin Layer (`tools/dss_mcp/`)
|
||||
|
||||
```
|
||||
tools/dss_mcp/
|
||||
├── server.py # FastAPI + SSE server
|
||||
├── handler.py # Unified tool router
|
||||
├── integrations/
|
||||
│ ├── base.py # BaseIntegration, CircuitBreaker
|
||||
│ ├── figma.py # ✅ 5 Figma tools (COMPLETE)
|
||||
│ └── storybook.py # ✅ 5 Storybook tools (Phase 1 COMPLETE)
|
||||
├── tools/
|
||||
│ ├── project_tools.py # ✅ 7 project management tools
|
||||
│ ├── workflow_tools.py # ✅ Workflow orchestration
|
||||
│ └── debug_tools.py # ✅ Debug utilities
|
||||
└── context/
|
||||
└── project_context.py # Project context management
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Critical Discovery: Translation Dictionaries Don't Exist
|
||||
|
||||
### What the Principles Document Says:
|
||||
|
||||
From `DSS_PRINCIPLES.md`:
|
||||
|
||||
```
|
||||
project-acme/
|
||||
├── .dss/
|
||||
│ ├── config.json
|
||||
│ └── translations/
|
||||
│ ├── figma.json # Figma → DSS mappings
|
||||
│ ├── legacy-css.json # Legacy CSS → DSS mappings
|
||||
│ └── custom.json # Custom props specific to ACME
|
||||
```
|
||||
|
||||
### What Actually Exists:
|
||||
|
||||
**NOTHING.** There is no Python module for:
|
||||
- Reading translation dictionaries
|
||||
- Writing translation dictionaries
|
||||
- Applying translation dictionaries
|
||||
- Validating translation dictionaries
|
||||
- Merging custom props
|
||||
|
||||
**Impact:** Phase 2 "Skin Management" tools cannot be implemented as planned because the underlying Python functionality doesn't exist.
|
||||
|
||||
---
|
||||
|
||||
## 3. The "Skin" vs "Theme" Confusion
|
||||
|
||||
### What the Implementation Plan Assumes:
|
||||
|
||||
**Phase 2: Skin/Theme Management**
|
||||
- `theme_list_skins` - List available skins
|
||||
- `theme_get_skin` - Get skin details
|
||||
- `theme_create_skin` - Create new skin
|
||||
- `theme_apply_skin` - Apply skin to project
|
||||
- `theme_export_tokens` - Export tokens
|
||||
|
||||
**Assumption:** "Skins" are first-class objects stored somewhere.
|
||||
|
||||
### What the Codebase Actually Has:
|
||||
|
||||
**Themes:** Only 2 base themes exist:
|
||||
- `get_default_light_theme()` - Returns `Theme` object
|
||||
- `get_default_dark_theme()` - Returns `Theme` object
|
||||
|
||||
**No "Skins":** The concept of client-specific "skins" is NOT implemented.
|
||||
|
||||
### What "Skins" SHOULD Be (Based on Principles):
|
||||
|
||||
A "skin" is:
|
||||
1. **Base Theme** (light or dark)
|
||||
2. **+ Translation Dictionary** (legacy → DSS mappings)
|
||||
3. **+ Custom Props** (client-specific extensions)
|
||||
|
||||
**Reality:** Without translation dictionary implementation, "skins" cannot be created.
|
||||
|
||||
---
|
||||
|
||||
## 4. Workflow Validation Analysis
|
||||
|
||||
### Target Workflow 1: Import from Figma ✅
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ WORKFLOW 1: Import from Figma │
|
||||
├──────────────────────────────────────────────────┤
|
||||
│ 1. figma_fetch_file(fileKey) ✅ Works │
|
||||
│ 2. figma_extract_tokens(fileId) ✅ Works │
|
||||
│ 3. figma_import_components(fileId) ✅ Works │
|
||||
│ 4. Store tokens in database ✅ Works │
|
||||
└──────────────────────────────────────────────────┘
|
||||
Status: FULLY FUNCTIONAL
|
||||
Gaps: None
|
||||
```
|
||||
|
||||
### Target Workflow 2: Load Skins into Storybook 🟡
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ WORKFLOW 2: Load Skins into Storybook │
|
||||
├──────────────────────────────────────────────────┤
|
||||
│ 1. storybook_scan(projectId) ✅ Phase 1│
|
||||
│ 2. Get client "skin" configuration ❌ BLOCKED│
|
||||
│ → No translation dictionary support │
|
||||
│ 3. Merge base theme + custom props ❌ BLOCKED│
|
||||
│ → No merge logic exists │
|
||||
│ 4. storybook_generate_theme(tokens) ✅ Phase 1│
|
||||
│ 5. Load Storybook with theme ✅ Phase 1│
|
||||
└──────────────────────────────────────────────────┘
|
||||
Status: 60% FUNCTIONAL
|
||||
Gaps: Translation dictionary system, custom props merger
|
||||
```
|
||||
|
||||
**Current Capability:** Can generate Storybook theme from base DSS theme
|
||||
**Missing:** Cannot apply client-specific customizations
|
||||
|
||||
### Target Workflow 3: Apply Design to Project ❌
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────┐
|
||||
│ WORKFLOW 3: Apply Design to Project │
|
||||
├──────────────────────────────────────────────────┤
|
||||
│ 1. Load project configuration ❌ BLOCKED│
|
||||
│ → No translation dictionary support │
|
||||
│ 2. Resolve tokens (DSS + custom) ❌ BLOCKED│
|
||||
│ → No token resolution logic │
|
||||
│ 3. Generate output files (CSS/SCSS) 🟡 PARTIAL│
|
||||
│ → style-dictionary exists but no MCP tools │
|
||||
│ 4. Update component imports ❌ BLOCKED│
|
||||
│ → No component rewrite logic │
|
||||
│ 5. Validate application ❌ BLOCKED│
|
||||
│ → No validation against translations │
|
||||
└──────────────────────────────────────────────────┘
|
||||
Status: 10% FUNCTIONAL
|
||||
Gaps: Complete translation dictionary system, token resolution, code generation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. What Needs to Be Built
|
||||
|
||||
### Foundation Layer (Critical - Build First)
|
||||
|
||||
**Translation Dictionary System** - NOT IMPLEMENTED
|
||||
|
||||
```python
|
||||
# Needs to be created in dss-mvp1/dss/translations/
|
||||
|
||||
dss/translations/
|
||||
├── __init__.py
|
||||
├── dictionary.py # TranslationDictionary class
|
||||
├── mapping.py # TokenMapping, ComponentMapping
|
||||
├── loader.py # Load from .dss/translations/*.json
|
||||
├── writer.py # Write dictionary files
|
||||
├── merger.py # Merge base theme + custom props
|
||||
├── validator.py # Validate dictionary schema
|
||||
└── resolver.py # Resolve token paths (e.g., "color.primary.500")
|
||||
|
||||
Core Functionality:
|
||||
- Load translation dictionaries from project .dss/translations/
|
||||
- Parse mappings: { "--brand-blue": "color.primary.500" }
|
||||
- Resolve token references
|
||||
- Merge custom props into base theme
|
||||
- Validate mappings against DSS canonical structure
|
||||
- Write/update dictionary files
|
||||
```
|
||||
|
||||
**Without this, Phase 2 and Phase 3 cannot be completed.**
|
||||
|
||||
### Phase 2 (Depends on Translation Dictionary System)
|
||||
|
||||
**Skin/Theme Management** - Should be renamed to **"Project Theme Configuration"**
|
||||
|
||||
Tools should actually do:
|
||||
1. `theme_list_themes` - List available base themes (light/dark)
|
||||
2. `theme_get_config` - Get project's theme configuration (.dss/config.json)
|
||||
3. `theme_set_base` - Set project's base theme (light/dark)
|
||||
4. `theme_add_custom_prop` - Add custom token to project (.dss/translations/custom.json)
|
||||
5. `theme_export_resolved` - Export fully resolved tokens (base + custom + translations)
|
||||
|
||||
### Phase 3 (Depends on Both Above)
|
||||
|
||||
**Design Application** - Generate output files
|
||||
|
||||
Tools need:
|
||||
1. `design_resolve_tokens` - Resolve all tokens for project (DSS + translations + custom)
|
||||
2. `design_generate_css` - Generate CSS variables file
|
||||
3. `design_generate_scss` - Generate SCSS variables file
|
||||
4. `design_update_imports` - Rewrite component imports
|
||||
5. `design_validate` - Validate that all tokens are mapped
|
||||
|
||||
---
|
||||
|
||||
## 6. Strategic Options
|
||||
|
||||
### Option A: Build Translation Dictionary System First ⭐ RECOMMENDED
|
||||
|
||||
**Approach:**
|
||||
1. Pause MCP tool development
|
||||
2. Build `dss.translations` Python module (foundation layer)
|
||||
3. Test translation dictionary loading/merging
|
||||
4. Then resume MCP tool implementation with correct architecture
|
||||
|
||||
**Pros:**
|
||||
- Aligns with DSS core principles
|
||||
- Enables real workflows
|
||||
- Solid foundation for Phase 2/3
|
||||
|
||||
**Cons:**
|
||||
- Delays MCP completion by 2-3 days
|
||||
- Requires core DSS architecture work
|
||||
|
||||
### Option B: Simplified Phase 2 (No Translation Dictionaries)
|
||||
|
||||
**Approach:**
|
||||
1. Implement Phase 2 tools WITHOUT translation dictionary support
|
||||
2. Tools only work with base themes
|
||||
3. Custom props come later
|
||||
|
||||
**Pros:**
|
||||
- Faster MCP completion
|
||||
- Some functionality better than none
|
||||
|
||||
**Cons:**
|
||||
- Doesn't align with DSS principles
|
||||
- Will need refactoring later
|
||||
- Can't achieve target workflows
|
||||
|
||||
### Option C: Skip to Phase 3 (Code Generation Only)
|
||||
|
||||
**Approach:**
|
||||
1. Skip Phase 2 entirely
|
||||
2. Implement Phase 3 code generation tools
|
||||
3. Generate CSS/SCSS from base themes only
|
||||
|
||||
**Pros:**
|
||||
- Tangible output (actual CSS files)
|
||||
- Tests style-dictionary integration
|
||||
|
||||
**Cons:**
|
||||
- Still blocked by translation dictionary gap
|
||||
- Workflows incomplete
|
||||
|
||||
---
|
||||
|
||||
## 7. Recommendations
|
||||
|
||||
### Immediate Actions:
|
||||
|
||||
1. **Validate Phase 1 with Simple Test**
|
||||
- Test storybook_scan on dss-mvp1 project
|
||||
- Test storybook_generate_theme with base light theme
|
||||
- Confirm tools actually work end-to-end
|
||||
|
||||
2. **Decide on Translation Dictionary Architecture**
|
||||
- Should it be Python module or keep as JSON-only?
|
||||
- Who owns the schema validation?
|
||||
- How do custom props extend base themes?
|
||||
|
||||
3. **Refine Phase 2/3 Plan**
|
||||
- Update tool definitions based on actual DSS architecture
|
||||
- Remove "skin" terminology, use "project theme configuration"
|
||||
- Add translation dictionary tools if we build that module
|
||||
|
||||
### Long-term Strategy:
|
||||
|
||||
**Path 1: Minimal MCP (Fast)**
|
||||
- Complete Phase 2/3 without translation dictionaries
|
||||
- Basic theme application only
|
||||
- Good for demo, limited for production
|
||||
|
||||
**Path 2: Complete DSS (Correct)** ⭐ RECOMMENDED
|
||||
- Build translation dictionary foundation
|
||||
- Implement Phase 2/3 properly aligned with principles
|
||||
- Full workflow support, production-ready
|
||||
|
||||
---
|
||||
|
||||
## 8. Questions for Architectural Decision
|
||||
|
||||
1. **Should we build the translation dictionary Python module?**
|
||||
- If yes: Who implements it? (Core team vs. MCP team)
|
||||
- If no: How do we achieve the documented DSS principles?
|
||||
|
||||
2. **What is the actual definition of a "skin"?**
|
||||
- Is it base theme + translation dictionary?
|
||||
- Or is it just a preset of custom props?
|
||||
- Should we rename to avoid confusion?
|
||||
|
||||
3. **Can we ship Phase 1 alone as MVP?**
|
||||
- Figma import + Storybook generation works
|
||||
- Workflow 1 is complete
|
||||
- Is that enough value?
|
||||
|
||||
4. **Should Phases 2/3 wait for translation dictionary implementation?**
|
||||
- Or build simplified versions now?
|
||||
- Trade-offs between speed and correctness?
|
||||
|
||||
---
|
||||
|
||||
## 9. Conclusion
|
||||
|
||||
**We're at a critical architectural decision point.**
|
||||
|
||||
Phase 1 (Storybook) is production-ready, but Phases 2-3 cannot be properly implemented without the translation dictionary foundation layer that's documented in principles but not coded.
|
||||
|
||||
**Two Paths Forward:**
|
||||
|
||||
1. **Fast Path:** Complete MCP with simplified tools (no translation dictionaries)
|
||||
- Timeline: 2-3 days
|
||||
- Result: Partial workflow support, will need refactoring
|
||||
|
||||
2. **Correct Path:** Build translation dictionary system first, then complete MCP
|
||||
- Timeline: 5-7 days
|
||||
- Result: Full workflow support, aligned with DSS principles
|
||||
|
||||
**My Recommendation:** Choose the Correct Path. Build the foundation right.
|
||||
|
||||
---
|
||||
|
||||
**Next Step:** User decision on which path to take.
|
||||
Reference in New Issue
Block a user