Design Base

Define a brand and design system once, and have every project and every AI coding agent follow it. Design Base stores design tokens in the W3C DTCG format, previews them on real components, pins them to a tech stack, and serves them to tools like Claude Code and Cursor over MCP.

Status: early development. Milestones 1 to 4 are in place: accounts, organisations, invitations, roles, design systems and projects with sharing; the token core (DTCG tokens with modes and validation, guidelines, drafts, published versions, projects that pin a version and override tokens); and the token editor with a live canvas of shadcn/ui and daisyUI examples; and exports (token formats, AI rules files, starter projects, a public read API). MCP and AI assistance follow; see the roadmap.

Stack

• TypeScript (strict) everywhere, pnpm workspaces + Turborepo
• Web: React, Vite, TanStack Router and Query, Tailwind CSS, daisyUI, Radix UI, Tabler Icons
• API: Node 24, Fastify, Zod, Better Auth
• Data: PostgreSQL 18, Drizzle ORM
• Tests: Vitest, Testing Library, MSW, Testcontainers
• Tooling: Biome, Docker Compose, Nix devShell

Quick start

Docker (self-hosting, nothing else required):

docker compose up -d

Open http://localhost:3000 and create an account.

Local tooling (Node 24, pnpm 10, Docker or Postgres 18):

corepack enable && pnpm install
cp .env.example .env                 # set AUTH_SECRET
docker compose up -d postgres
pnpm db:migrate && pnpm db:seed
pnpm dev

Open http://localhost:5173 and sign in as demo@designbase.local / designbase-demo.

Nix:

nix develop        # or: direnv allow
pnpm install

then continue as with local tooling. Details per platform are in docs/installation.md.

Environment

Every variable is listed with a safe default in .env.example.

Variable	Purpose	Example
DATABASE_URL	Postgres 18 connection for the API and migrations	postgres://designbase:designbase@localhost:5432/designbase
PUBLIC_URL	URL users open; used for auth and invitation links	http://localhost:5173
AUTH_SECRET	Session signing secret, 32+ characters (or AUTH_SECRET_FILE)	openssl rand -base64 48
TRUSTED_ORIGINS	Extra origins allowed to call the API with credentials	http://localhost:4000
GITHUB_CLIENT_ID/SECRET, GOOGLE_CLIENT_ID/SECRET	Optional OAuth sign-in
API_URL	Where the Vite dev server proxies /api	http://localhost:8080
SITE_URL, WEB_PORT, DOCKER_*	Compose-only settings for self-hosting	https://design.example.com

Commands

Command	What it does
pnpm dev	API on :8080 and web on :5173 with reload
pnpm build	Production builds
pnpm test	All test suites (API tests need Docker or TEST_DATABASE_URL)
pnpm typecheck	TypeScript in every package
pnpm lint / pnpm format	Biome check / write
pnpm db:generate	Create a migration from schema changes
pnpm db:migrate	Apply migrations
pnpm db:seed	Development demo data

Layout

apps/
  api/          Fastify API: auth, organisations, design systems, projects
  web/          React app
packages/
  shared/       Zod schemas shared by client and server
  core/         Pure domain logic (roles today; token resolution next)
  db/           Drizzle schema, migrations, connection
docs/           Installation, development, deployment, architecture, ADRs
compose.yaml    Self-hosted stack; compose.dev.yaml adds hot reload
flake.nix       Nix devShell

Documentation

• Installation
• Development
• Deployment
• Architecture
• Database
• Tokens, versions and projects
• Exports and the public API
• Architecture decision records
• Remaining v1 work
• Contributing

Roadmap

1. Foundation - monorepo, Docker, schema, auth, organisations, CRUD. Done.
2. Token core - DTCG model, validation, aliases, modes, project overrides, drafts, versions. Done.
3. Editor and canvas - token editor, live iframe preview, shadcn/ui and daisyUI examples, contrast checks. Done.
4. Exports - Style Dictionary pipeline, AI rules files, starter-project zip. Done.
5. MCP server - read tools, proposal-based write tools, API tokens.
6. AI assistant - provider layer, assistant panel, proposal review with diffs.
7. CLI, webhooks, Figma import/export, polish.

License

MIT