2c9f52c029
Systematic replacement of 'swarm' and 'organism' terminology across codebase: AUTOMATED REPLACEMENTS: - 'Design System Swarm' → 'Design System Server' (all files) - 'swarm' → 'DSS' (markdown, JSON, comments) - 'organism' → 'component' (markdown, atomic design refs) FILES UPDATED: 60+ files across: - Documentation (.md files) - Configuration (.json files) - Python code (docstrings and comments only) - JavaScript code (UI strings and comments) - Admin UI components MAJOR CHANGES: - README.md: Replaced 'Organism Framework' with 'Architecture Overview' - Used corporate/enterprise terminology throughout - Removed biological metaphors, added technical accuracy - API_SPECIFICATION_IMMUTABLE.md: Terminology updates - dss-claude-plugin/.mcp.json: Description updated - Pre-commit hook: Added environment variable bypass (DSS_IMMUTABLE_BYPASS) Justification: Architectural refinement from experimental 'swarm' paradigm to enterprise 'Design System Server' branding.
256 lines
8.5 KiB
Markdown
256 lines
8.5 KiB
Markdown
# DSS - Design System Server
|
|
|
|
> **Monolithic design system management platform with multi-source token ingestion, code intelligence, and Storybook integration**
|
|
|
|
[](CHANGELOG.md)
|
|
[](https://python.org)
|
|
[](tests/)
|
|
[](docs/CODE_QUALITY.md)
|
|
[](LICENSE)
|
|
[](CONTRIBUTING.md)
|
|
|
|
## Overview
|
|
|
|
DSS (Design System Server) is an MCP-first platform that helps teams modernize legacy UI by ingesting design tokens from multiple sources (Figma, CSS, SCSS, Tailwind), standardizing them, and generating production-ready outputs.
|
|
|
|
## 📚 Knowledge Base
|
|
|
|
Structured knowledge is stored in `.knowledge/` directory for AI agent consumption:
|
|
- **[dss-architecture.json](.knowledge/dss-architecture.json)** - Three-tier architecture (Router, Messaging, Workflows)
|
|
- **[dss-principles.json](.knowledge/dss-principles.json)** - Core design principles and translation dictionaries
|
|
- **[mcp-tools.json](.knowledge/mcp-tools.json)** - MCP-first tool specifications
|
|
|
|
For detailed natural language documentation, see:
|
|
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Enterprise architecture overview
|
|
- **[DSS_PRINCIPLES.md](DSS_PRINCIPLES.md)** - Design system principles
|
|
- **[MCP_TOOLS_SPEC.md](MCP_TOOLS_SPEC.md)** - MCP tool specifications
|
|
|
|
## 🏗️ Architecture Overview
|
|
|
|
DSS follows enterprise-grade architectural patterns with clear separation of concerns:
|
|
|
|
```
|
|
🏗️ DSS Architecture
|
|
├── 💾 Data Layer - Persistent storage and caching
|
|
├── 🔍 Analysis Engine - Code intelligence and validation
|
|
├── 🔌 Integration Layer - External system APIs (Figma, GitHub)
|
|
├── 📥 Ingestion Pipeline - Multi-source token extraction
|
|
├── 🎨 Token Management - Design token storage and distribution
|
|
├── 🔄 Transformation Engine - Format conversion and generation
|
|
├── 🎯 Theme System - Multi-theme configuration management
|
|
├── ✅ Validation Layer - Schema and quality enforcement
|
|
├── 📊 Reporting & Analytics - Metrics and insights
|
|
├── 📚 Documentation Engine - Storybook and API docs
|
|
└── 🏛️ Core Infrastructure - Schemas, types, and foundational components
|
|
```
|
|
|
|
**Architecture Pattern:** Layered architecture with bounded contexts, dependency injection, and immutable core configuration.
|
|
|
|
### Key Features
|
|
|
|
- 🎨 **Multi-Source Ingestion** - Extract tokens from Figma, CSS, SCSS, Tailwind, JSON
|
|
- 🔄 **Smart Token Merging** - 6 merge strategies with conflict resolution
|
|
- 📊 **Code Intelligence** - Analyze React projects, find quick-wins, build dependency graphs
|
|
- 📚 **Storybook Integration** - Auto-generate themed stories and configurations
|
|
- 🤖 **MCP Server** - 32 AI tools for design system workflows
|
|
- 🌐 **REST API** - 34 endpoints for programmatic access
|
|
- 🎯 **Monolithic Design** - Immutable core with per-project translation dictionaries
|
|
- 💬 **Claude Chat Integration** - AI assistant connected via MCP for design system guidance
|
|
- 🎛️ **Admin Dashboard** - Production-ready UI with services catalog, quick wins, and settings
|
|
- 📝 **Centralized Logging** - Color-coded debug console with export functionality
|
|
- 👥 **Team-Based Dashboards** - Tailored views for UI, UX, and QA teams with relevant tools and metrics
|
|
|
|
## Quick Start
|
|
|
|
### Production URLs
|
|
- **Admin UI**: https://dss.overbits.luz.uy/
|
|
- **Storybook**: http://storybook.dss.overbits.luz.uy (pending SSL)
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/yourusername/dss.git
|
|
cd dss
|
|
|
|
# Install Python dependencies
|
|
pip install -r tools/api/requirements.txt
|
|
|
|
# Install CLI
|
|
cd cli
|
|
npm install
|
|
npm link
|
|
|
|
# Start MCP server
|
|
cd ../tools/api
|
|
python mcp_server.py
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```bash
|
|
# Initialize DSS in your project
|
|
dss init
|
|
|
|
# Ingest tokens from Figma
|
|
dss ingest figma <file-key>
|
|
|
|
# Analyze your React codebase
|
|
dss analyze ./src
|
|
|
|
# Generate Storybook theme
|
|
dss storybook theme --output ./storybook/theme.js
|
|
|
|
# Start the MCP server
|
|
dss start
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
DSS (Design System Server)
|
|
├── Backend (Python)
|
|
│ ├── API Layer
|
|
│ │ ├── REST API (34 endpoints)
|
|
│ │ └── MCP Server (32 tools)
|
|
│ ├── Core Modules
|
|
│ │ ├── Ingestion - Multi-source token parsers
|
|
│ │ ├── Analysis - Code intelligence & quick-wins
|
|
│ │ ├── Storybook - Story & theme generation
|
|
│ │ ├── Figma - API integration with fallbacks
|
|
│ │ └── Storage - SQLite cache & activity log
|
|
│ └── Configuration - Environment-based settings
|
|
├── Frontend
|
|
│ ├── Admin UI (Vanilla JS) - Web dashboard
|
|
│ └── CLI (TypeScript) - Command-line tools
|
|
└── Documentation
|
|
├── Principles - Monolithic design philosophy
|
|
├── MVP Plan - 5-phase roadmap
|
|
└── Technical Guides - Implementation details
|
|
```
|
|
|
|
## Core Principles
|
|
|
|
DSS follows a **monolithic design philosophy**:
|
|
|
|
1. **Immutable Core** - DSS canonical structure never changes
|
|
2. **Translation Dictionaries** - Per-project mappings from external systems to DSS
|
|
3. **Custom Props** - Isolated namespaces for client-specific tokens
|
|
4. **Multi-System Ingestion** - All external systems translate TO DSS
|
|
5. **Token Merge Strategies** - Smart conflict resolution (FIRST, LAST, PREFER_FIGMA, etc.)
|
|
|
|
See [DSS_PRINCIPLES.md](DSS_PRINCIPLES.md) for complete design philosophy.
|
|
|
|
## API Reference
|
|
|
|
### MCP Tools (32 total)
|
|
|
|
**Status & Discovery**
|
|
- `get_status` - Server health and statistics
|
|
- `discover_project` - Scan codebase for UI framework and styles
|
|
- `build_source_graph` - Create dependency graph
|
|
- `get_quick_wins` - Identify easy improvements
|
|
|
|
**Token Ingestion (7 tools)**
|
|
- `ingest_figma_variables`, `ingest_figma_components`, `ingest_figma_styles`
|
|
- `ingest_css_tokens`, `ingest_scss_tokens`, `ingest_tailwind_tokens`
|
|
- `ingest_json_tokens`
|
|
|
|
**Analysis (11 tools)**
|
|
- `discover_project`, `analyze_react_components`, `find_inline_styles`
|
|
- `find_style_patterns`, `analyze_style_values`, `find_unused_styles`
|
|
- `build_source_graph`, `get_quick_wins`, `check_naming_consistency`
|
|
- And more...
|
|
|
|
**Storybook (5 tools)**
|
|
- `scan_storybook`, `generate_story`, `generate_stories_batch`
|
|
- `generate_storybook_theme`, `get_story_coverage`
|
|
|
|
### REST API (34 endpoints)
|
|
|
|
See `tools/api/server.py` for complete endpoint documentation.
|
|
|
|
## Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
/tools/
|
|
├── api/ # REST & MCP servers
|
|
├── ingest/ # Token ingestion parsers
|
|
├── analyze/ # Code intelligence
|
|
├── storybook/ # Storybook integration
|
|
├── figma/ # Figma API client
|
|
└── storage/ # SQLite persistence
|
|
|
|
/admin-ui/ # Web dashboard
|
|
/cli/ # TypeScript CLI
|
|
/docs/ # Documentation
|
|
/examples/ # Usage examples
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Python tests
|
|
pytest tools/
|
|
|
|
# TypeScript tests
|
|
cd cli && npm test
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Environment variables (see `.env.example`):
|
|
|
|
```bash
|
|
# Server
|
|
PORT=3456
|
|
DSS_MCP_HOST=127.0.0.1 # MCP server host
|
|
DSS_MCP_PORT=3457 # MCP server port
|
|
|
|
# Figma API
|
|
FIGMA_TOKEN=your_token_here
|
|
|
|
# Database
|
|
DATABASE_PATH=.dss/dss.db
|
|
FIGMA_CACHE_TTL=300
|
|
```
|
|
|
|
## Implementation Status
|
|
|
|
- ✅ **Phase 1**: Token Ingestion (Complete)
|
|
- ✅ **Phase 2**: Code Intelligence (Complete)
|
|
- ✅ **Phase 3**: Storybook Integration (Complete)
|
|
- ⏳ **Phase 4**: Migration Engine (Planned)
|
|
- ⏳ **Phase 5**: UI Library Compatibility (Planned)
|
|
|
|
See [DSS_MVP_PLAN_V2.md](DSS_MVP_PLAN_V2.md) for detailed roadmap.
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](LICENSE) file for details.
|
|
|
|
## Links
|
|
|
|
- [Documentation](docs/)
|
|
- [Principles](DSS_PRINCIPLES.md)
|
|
- [MVP Plan](DSS_MVP_PLAN_V2.md)
|
|
- [Architecture Details](PROJECT_MEMORY.md)
|
|
|
|
## Acknowledgments
|
|
|
|
Built with:
|
|
- [FastAPI](https://fastapi.tiangolo.com/) - REST API framework
|
|
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
|
|
- [SQLite](https://www.sqlite.org/) - Database
|
|
- [Figma API](https://www.figma.com/developers/api) - Design integration
|