# 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