96 lines
2.5 KiB
Markdown
96 lines
2.5 KiB
Markdown
# 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)
|
|
```
|