DSS - Design System Server

Monolithic design system management platform with multi-source token ingestion, code intelligence, and Storybook integration

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 - Three-tier architecture (Router, Messaging, Workflows)
• dss-principles.json - Core design principles and translation dictionaries
• mcp-tools.json - MCP-first tool specifications

For detailed natural language documentation, see:

• ARCHITECTURE.md - Enterprise architecture overview
• DSS_PRINCIPLES.md - Design system principles
• 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

# 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

# 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 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

# Python tests
pytest tools/

# TypeScript tests
cd cli && npm test

Configuration

Environment variables (see .env.example):

# 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 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 file for details.

Links

• Documentation
• Principles
• MVP Plan
• Architecture Details

Acknowledgments

Built with:

• FastAPI - REST API framework
• FastMCP - MCP server framework
• SQLite - Database
• Figma API - Design integration