dss/docs

DSS Documentation (Human)

This directory contains human-facing documentation for DSS.

If you’re looking for AI/agent-oriented notes, see docs/ai.md.

What DSS Is

DSS (Design System Server) is a toolkit that can run in two modes:

1. Local developer tool: analyze any project on disk, extract tokens, generate Storybook stories, and expose dss_* tools to Claude Code via MCP.
2. Headless server: run a FastAPI backend that teams (UX/QA/Admin) can access through the web Admin UI, and that AI assistants can interact with via the /api/claude/chat endpoint and MCP tool endpoints.

MCP across clients

DSS exposes the same dss_* toolset to multiple AI clients via MCP:

• Recommended: ./scripts/enable-mcp-clients.sh
• Claude Code: ./scripts/setup-mcp.sh generates .claude/mcp.json.
• Codex CLI: codex mcp add dss -- /absolute/path/to/dss/scripts/dss-mcp
• Gemini CLI: gemini mcp add dss /absolute/path/to/dss/scripts/dss-mcp

The Claude plugin system (commands/skills under dss-claude-plugin/) is Claude-specific, but DSS makes those guides/hooks available to any MCP client via:

• dss_list_guides (use include_meta=true for hook metadata)
• dss_get_guide
• dss_match_skills

Documentation Map

• docs/quickstart.md — install + run locally, and run the headless server.
• docs/architecture.md — how CLI, API, Admin UI, and MCP fit together.
• docs/configuration.md — environment variables, ports, and operational knobs.
• docs/storage.md — JSON-only storage layout and DSS_HOME rules.
• docs/upgrade-notes.md — recent upgrades and migration notes.
• docs/ai.md — where the AI/agent documentation lives.