dss/README.md

DSS (Design System Server)

DSS is a design-system toolkit that works both as:

• a local developer tool (run analysis and generation across many repos), and
• a headless server (so UX/QA/Admin teams can use the web Admin UI and AI-assisted workflows without a local dev environment).

What DSS does

• Ingest tokens from Figma / CSS / SCSS / Tailwind, normalize them, and generate outputs
• Analyze codebases (components, styles, dependency graph, quick wins)
• Automate Storybook setup (scan/generate/configure)
• Expose a consistent set of dss_* tools via:
  • local MCP (Claude Code)
  • headless server MCP endpoints (/api/mcp/*)
  • Claude chat/tool-calling (/api/claude/chat)

Docs

Human docs live in docs/README.md.

AI/agent-oriented docs live in docs/ai.md (entry points include CLAUDE.md and admin-ui/AI-REFERENCE.md).

Quickstart (local + server)

1) Python setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2) Run the headless API

source .venv/bin/activate
PYTHONPATH="$PWD:$PWD/apps/api" uvicorn apps.api.server:app --host 0.0.0.0 --port 6220

If you want a single-port server that serves the built Admin UI too, see docs/quickstart.md (Option B) or run ./scripts/dss start after building admin-ui.

3) Run the Admin UI (dev mode)

cd admin-ui
npm install
npm run dev

Admin UI: http://localhost:6221
API: http://localhost:6220

4) Run analysis on any project

./dss-cli.py analyze --project-path /absolute/path/to/your-project

This writes <project>/.dss/analysis_graph.json (portable JSON output).

5) Claude Code MCP setup

./scripts/setup-mcp.sh

Enable MCP for Claude + Codex + Gemini (when installed):

./scripts/enable-mcp-clients.sh

See docs/configuration.md for proxy mode (--api-url) and environment variables.

Storage (JSON-only)

By default DSS stores data under:

• DSS_HOME (if set), else
• ./.dss (if present), else
• ~/.dss

See docs/storage.md for layout and guidance on what to commit.

Repo layout

dss/                 # Core Python library (analysis/ingest/storage/mcp)
apps/api/            # FastAPI headless server
admin-ui/            # Preact Admin UI (Vite dev server + build output)
dss-claude-plugin/   # Claude Code plugin assets (commands/skills)
scripts/             # Setup and operational scripts
docs/                # Human documentation
.knowledge/          # Internal knowledge base (AI-oriented)