bruno/dss
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Initial commit: Clean DSS implementation

Browse Source 
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
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

255
README.md Normal file
View File

@@ -0,0 +1,255 @@
# DSS - Design System Server
> **Monolithic design system management platform with multi-source token ingestion, code intelligence, and Storybook integration**
[![Version](https://img.shields.io/badge/version-0.7.1-blue.svg)](CHANGELOG.md)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![Tests](https://img.shields.io/badge/tests-8%2F11%20passing-yellow.svg)](tests/)
[![Code Quality](https://img.shields.io/badge/code%20quality-A--brightgreen.svg)](docs/CODE_QUALITY.md)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](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
## 🧬 The DSS Organism Framework
DSS is conceived as a **living design system organism** - a biological system where different components are organ systems working together to maintain health and enable growth. This framework makes complex design system concepts intuitive and memorable:
```
🧬 The DSS Organism
├── ❤️ Heart (Database) - Stores all data and experiences
├── 🧠 Brain (Validators & Analysis) - Makes decisions, validates health
├── 🔌 Nervous System (API & Integration) - Communicates with external systems
├── 🍽️ Digestive System (Token Ingestion) - Breaks down design material into nutrients
├── 🩸 Circulatory System (Design Tokens) - Distributes nutrients throughout the body
├── ⚡ Metabolic System (Transformations) - Converts tokens to different formats
├── 🎛️ Endocrine System (Themes) - Regulates appearance and behavior
├── 🛡️ Immune System (Validators & QA) - Protects against bad data
├── 👁️ Sensory Organs (Figma, Assets) - Perceives external design systems
├── 🎨 Skin (Storybook & Docs) - The organism's external presentation
└── 🦴 Skeleton (Schemas & Structure) - Provides foundational framework
```
**Learn More:** See [DSS Organism Framework Documentation](docs/DSS_ORGANISM_GUIDE.md) for comprehensive guides, vocabulary glossary, and implementation patterns.
### 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