dss/docs/QUICKSTART.md

DSS Quick Start Guide

Get up and running with DSS in minutes.

Prerequisites

• Python 3.10+
• Node.js 18+ (for CLI)
• Figma account (optional, for Figma integration)

Installation

# Clone repository
git clone <repo-url>
cd dss

# Install Python dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Install CLI (optional)
cd cli
npm install
npm run build
npm link
cd ..

Basic Usage

1. Start the Servers

# Start REST API (port 3456)
python -m tools.api.server

# Start MCP server (port 3457) in another terminal
python -m tools.api.mcp_server

2. Ingest Design Tokens

From CSS

from tools.ingest.css import CSSTokenSource

parser = CSSTokenSource()
result = await parser.extract("""
:root {
    --color-primary: #3B82F6;
    --spacing-md: 16px;
}
""")

print(f"Extracted {len(result.tokens)} tokens")
for token in result.tokens:
    print(f"  {token.name}: {token.value}")

From SCSS

from tools.ingest.scss import SCSSTokenSource

parser = SCSSTokenSource()
result = await parser.extract("""
$primary: #3B82F6;
$spacing-md: 16px;
""")

From Tailwind Config

from tools.ingest.tailwind import TailwindTokenSource

parser = TailwindTokenSource()
result = await parser.extract("./tailwind.config.js")

From Figma

from tools.figma.figma_tools import FigmaToolSuite

# Set FIGMA_TOKEN environment variable first
suite = FigmaToolSuite(output_dir="./output")
result = await suite.extract_variables("YOUR_FILE_KEY")

3. Merge Tokens from Multiple Sources

from tools.ingest.merge import TokenMerger, MergeStrategy
from tools.ingest.base import TokenCollection, DesignToken, TokenType

# Create collections from different sources
css_tokens = TokenCollection([
    DesignToken(name="color.primary", value="#FF0000", type=TokenType.COLOR, source="css")
])

figma_tokens = TokenCollection([
    DesignToken(name="color.primary", value="#3B82F6", type=TokenType.COLOR, source="figma")
])

# Merge with PREFER_FIGMA strategy
merger = TokenMerger(strategy=MergeStrategy.PREFER_FIGMA)
result = merger.merge([css_tokens, figma_tokens])

print(f"Merged tokens: {len(result.collection.tokens)}")
print(f"Conflicts: {len(result.conflicts)}")

# Access the winning token
primary = result.collection.tokens[0]
print(f"Final color.primary: {primary.value}")  # #3B82F6 (from Figma)

4. Analyze React Project

from tools.analyze.scanner import ProjectScanner

scanner = ProjectScanner("./my-react-app")
analysis = await scanner.scan()

print(f"Framework: {analysis.framework}")
print(f"Styling: {analysis.styling_approach}")
print(f"Components: {len(analysis.components)}")

5. Find Quick Wins

from tools.analyze.quick_wins import QuickWinFinder

finder = QuickWinFinder("./my-react-app")
wins = await finder.find_all()

for win in wins.opportunities[:5]:
    print(f"{win.type.value}: {win.title}")
    print(f"  Impact: {win.impact.value}")
    print(f"  Effort: {win.effort.value}")

6. Generate Storybook Stories

from tools.storybook.generator import StoryGenerator
from tools.analyze.base import ComponentInfo

# Define component
component = ComponentInfo(
    name="Button",
    file_path="src/components/Button.tsx",
    props=[
        {"name": "variant", "type": "primary | secondary"},
        {"name": "children", "type": "ReactNode"}
    ]
)

# Generate story
generator = StoryGenerator(output_dir="./stories")
result = await generator.generate_story(component, template="csf3")

print(f"Story created: {result['file_path']}")

7. Generate Storybook Theme from Tokens

from tools.storybook.theme import ThemeGenerator
from tools.ingest.base import TokenCollection, DesignToken, TokenType

tokens = TokenCollection([
    DesignToken(name="color.primary.500", value="#3B82F6", type=TokenType.COLOR),
    DesignToken(name="spacing.md", value="16px", type=TokenType.SPACING),
    DesignToken(name="font.size.base", value="16px", type=TokenType.TYPOGRAPHY)
])

generator = ThemeGenerator()
theme = generator.generate_from_tokens(tokens)

print(theme)  # JavaScript theme object

Using the REST API

# Check status
curl http://localhost:3456/status

# List tokens
curl http://localhost:3456/tokens

# Ingest CSS tokens
curl -X POST http://localhost:3456/tokens/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "css",
    "content": ":root { --color: #FF0000; }"
  }'

# Analyze project
curl -X POST http://localhost:3456/analyze/project \
  -H "Content-Type: application/json" \
  -d '{"path": "./my-react-app"}'

# Get quick wins
curl http://localhost:3456/analyze/quick-wins?path=./my-react-app

Using the MCP Server (AI Agents)

The MCP server exposes 32 tools for AI agents. Connect via MCP client:

{
  "mcpServers": {
    "dss": {
      "command": "python",
      "args": ["-m", "tools.api.mcp_server"],
      "cwd": "/path/to/dss"
    }
  }
}

Available tool categories:

• Status & Discovery (4 tools): get_status, discover_project, etc.
• Token Ingestion (7 tools): ingest_figma_variables, ingest_css_tokens, etc.
• Analysis (11 tools): analyze_react_components, get_quick_wins, etc.
• Storybook (5 tools): generate_story, generate_storybook_theme, etc.
• Figma (5 tools): figma_extract_variables, figma_sync_tokens, etc.

Common Workflows

Workflow 1: Figma → DSS → Storybook

import asyncio
from tools.figma.figma_tools import FigmaToolSuite
from tools.storybook.theme import ThemeGenerator

async def figma_to_storybook(file_key: str):
    # 1. Extract from Figma
    suite = FigmaToolSuite(output_dir="./output")
    result = await suite.extract_variables(file_key)

    # 2. Convert to tokens
    tokens = result['tokens']  # TokenCollection

    # 3. Generate Storybook theme
    generator = ThemeGenerator()
    theme_code = generator.generate_theme_file(tokens, "./storybook/theme.js")

    print(f"✅ Generated Storybook theme with {len(tokens)} tokens")

asyncio.run(figma_to_storybook("YOUR_FILE_KEY"))

Workflow 2: Multi-Source Token Merge

import asyncio
from tools.ingest.css import CSSTokenSource
from tools.ingest.scss import SCSSTokenSource
from tools.figma.figma_tools import FigmaToolSuite
from tools.ingest.merge import TokenMerger, MergeStrategy

async def merge_all_sources():
    # 1. Ingest from CSS
    css_parser = CSSTokenSource()
    css_tokens = await css_parser.extract("./styles/tokens.css")

    # 2. Ingest from SCSS
    scss_parser = SCSSTokenSource()
    scss_tokens = await scss_parser.extract("./styles/variables.scss")

    # 3. Ingest from Figma
    figma = FigmaToolSuite()
    figma_result = await figma.extract_variables("YOUR_FILE_KEY")
    figma_tokens = figma_result['tokens']

    # 4. Merge with Figma as source of truth
    merger = TokenMerger(strategy=MergeStrategy.PREFER_FIGMA)
    result = merger.merge([css_tokens, scss_tokens, figma_tokens])

    print(f"✅ Merged {len(result.collection.tokens)} tokens")
    print(f"⚠️  Resolved {len(result.conflicts)} conflicts")

    return result.collection

asyncio.run(merge_all_sources())

Workflow 3: Analyze → Quick Wins → Fix

import asyncio
from tools.analyze.scanner import ProjectScanner
from tools.analyze.quick_wins import QuickWinFinder

async def analyze_project(path: str):
    # 1. Scan project
    scanner = ProjectScanner(path)
    analysis = await scanner.scan()

    print(f"Framework: {analysis.framework}")
    print(f"Components: {len(analysis.components)}")

    # 2. Find quick wins
    finder = QuickWinFinder(path)
    wins = await finder.find_all()

    # 3. Prioritize by ROI
    high_roi = [
        w for w in wins.opportunities
        if w.impact.value == "high" and w.effort.value in ["low", "medium"]
    ]

    print(f"\n🎯 Top Quick Wins ({len(high_roi)}):")
    for win in high_roi[:5]:
        print(f"  • {win.title}")
        print(f"    Impact: {win.impact.value} | Effort: {win.effort.value}")

asyncio.run(analyze_project("./my-react-app"))

Configuration

Environment Variables

# Figma integration
export FIGMA_TOKEN="your-figma-token"
export FIGMA_CACHE_TTL=300  # 5 minutes

# Server ports
export PORT=3456            # REST API
export DSS_MCP_PORT=3457   # MCP server
export DSS_MCP_HOST=127.0.0.1

# Database
export DSS_DB_PATH="./.dss/dss.db"

Figma Setup

1. Get Figma token: https://www.figma.com/developers/api#access-tokens
2. Set FIGMA_TOKEN environment variable
3. Get file key from Figma URL: https://figma.com/file/FILE_KEY/...

Troubleshooting

Figma API Returns Empty

Problem: extract_variables() returns 0 tokens

Solutions:

1. Check if file has Variables (requires paid plan)
2. Use extract_styles() for document-level styles (free)
3. Check file permissions and token validity

Module Import Errors

Problem: ModuleNotFoundError: No module named 'tools'

Solution: Ensure you're in the project root and virtual env is activated:

cd /path/to/dss
source .venv/bin/activate

Tailwind Parser Returns 0 Tokens

Known Issue: Tailwind parser regex doesn't match all config formats

Workaround: Use JSON tokens format:

from tools.ingest.json_tokens import JSONTokenSource
import json

# Convert Tailwind config to JSON tokens
tailwind_as_json = json.dumps({
    "color": {
        "primary": {"value": "#3B82F6", "type": "color"}
    }
})

parser = JSONTokenSource()
result = await parser.extract(tailwind_as_json)

Next Steps

• Read ARCHITECTURE.md for system design
• Check DSS_PRINCIPLES.md for design philosophy
• Review PROJECT_MEMORY.md for complete module inventory
• Explore examples/ for more code samples

Getting Help

• GitHub Issues: Report bugs
• Documentation: Check docs/ folder
• API Reference: See tools/api/mcp_server.py for all MCP tools