# 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

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

### 2) Run the headless API

```bash
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)

```bash
cd admin-ui
npm install
npm run dev
```

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

### 4) Run analysis on any project

```bash
./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

```bash
./scripts/setup-mcp.sh
```

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

```bash
./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)
```