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

Major cleanup: Remove redundant code, consolidate knowledge base

Browse Source 
- Delete redundant directories: demo/, server/, orchestrator/, team-portal/, servers/
- Remove all human-readable documentation (docs/, .dss/*.md, admin-ui/*.md)
- Consolidate 4 knowledge JSON files into single DSS_CORE.json
- Clear browser logs (7.5MB), backups, temp files
- Remove obsolete configs (.cursorrules, .dss-boundaries.yaml, .ds-swarm/)
- Reduce project from 20MB to ~8MB

Kept: tools/, admin-ui/, cli/, dss-claude-plugin/, .dss/schema/

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Bruno Sarlo
2025-12-10 07:34:52 -03:00
parent 3e4295457d
commit 7a3044bccc
470 changed files with 233 additions and 252780 deletions
Download Patch File Download Diff File Expand all files Collapse all files

255
README.md
View File

@@ -1,255 +1,28 @@
# 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
## 🏗️ 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
Monolithic design system platform. Ingest tokens from Figma/CSS/SCSS/Tailwind, normalize to canonical format, generate outputs.
## 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
pip install -r requirements.txt
python tools/api/server.py # REST API on :3456
python tools/api/mcp_server.py # MCP server on :3457
```
### 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
## Structure
```
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
tools/ # Python backend (API, ingestion, analysis)
admin-ui/ # Web dashboard
cli/ # TypeScript CLI
dss-claude-plugin/ # Claude Code integration (skills, commands, agents)
.knowledge/ # AI knowledge base (DSS_CORE.json)
.dss/ # Runtime data, schemas, database
```
## Core Principles
## Core Concept
DSS follows a **monolithic design philosophy**:
DSS structure is immutable. External systems adapt TO DSS via translation dictionaries.
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
See `.knowledge/DSS_CORE.json` for complete specification.