Design System Builder

A web platform for building, managing, and publishing design systems end-to-end.

Design System Builder lets product teams compose their own design system from a shared component catalog, customize tokens (colors, typography, spacing, etc.), preview the result in real time, and then generate, publish, and document the resulting npm package — all from a single UI.

It is the tooling layer behind several Salute design systems built on top of @salutejs/plasma.

What you can do with it

Compose a design system from a shared catalog of components and variations
Tweak tokens (colors, typography, spacing, shape, etc.) with live preview
Generate a ready-to-use npm package from your configuration
Publish that package to a private npm registry in one click
Generate documentation (Docusaurus site) and deploy it to S3
Inspect and query the underlying registry through an admin panel (tables, schema, OpenAPI, NL queries)

Architecture

The platform is a small set of independent services around a central registry. All services are deployed and orchestrated through Docker Compose.

                       ┌────────────────────┐
                       │       Admin        │  React SPA — registry inspector,
                       │   apps/admin :3004 │  schema browser, OpenAPI, NL queries
                       └─────────┬──────────┘
                                 │ REST (OpenAPI-typed)
                                 ▼
┌────────────────────┐  REST   ┌────────────────────┐    ┌──────────────────┐
│       Client       │ ──────▶ │     DS Registry    │◀──▶│  PostgreSQL      │
│  apps/client :3002 │         │   ds-registry :3008│    │  (postgres-      │
│  (DS builder UI)   │         │  Express + Drizzle │    │   registry :5433)│
└─────┬───────┬──────┘         └─────────┬──────────┘    └──────────────────┘
      │       │                          ▲
      │       │                          │ fetch DS data
      │       │                          │
      │       │                ┌─────────┴──────────┐    ┌──────────────────┐
      │       └──────REST─────▶│    DS Generator    │───▶│    Publisher     │
      │                        │  ds-generator :3005│    │  publisher :3007 │
      │                        │  Fastify + CLI     │    │  npm publish     │
      │                        └────────────────────┘    └──────────────────┘
      │
      │                        ┌────────────────────┐    ┌──────────────────┐
      └─────────REST──────────▶│  Docs Generator    │───▶│      AWS S3      │
                               │ docs-generator:3006│    │  (docs hosting)  │
                               │  NestJS+Docusaurus │    │                  │
                               └─────────┬──────────┘    └──────────────────┘
                                         │ fetch DS data
                                         ▼
                                  (DS Registry)

Services

Service	Path	Port	Stack	Purpose
DS Registry	services/ds-registry	3008	Express, Drizzle ORM, Postgres, Zod, OpenAPI	Source of truth. Stores design systems, components, variations, tokens. Exposes a typed REST API and an auto-generated OpenAPI spec.
DS Generator	services/ds-generator	3005	Fastify	Builds an npm package from a design system stored in the registry. Available both as a web service and as a CLI (`plasma-ds-generate`).
Publisher	services/publisher	3007	Express	Receives a packaged design system from the generator and publishes it to a configured npm registry.
Docs Generator	services/ds-documentation-generator	3006	NestJS, Handlebars, Docusaurus	Pulls a design system from the registry, renders a Docusaurus project from templates, builds the static site, and uploads it to S3.
Client	apps/client	3002	React 18, Vite, `@salutejs/plasma-*`	The end-user UI for composing a design system, editing tokens, and triggering generation/publication/documentation.
Admin	apps/admin	3004	React 18, Vite, OpenAPI types	Inspector for the registry: schema view, table browser, OpenAPI reference, saved/NL queries.

How a design system flows through the system

Authoring. A user opens the Client (apps/client) and composes a design system — picks components, edits tokens, previews the result. The client persists everything to the DS Registry over REST.
Generation. From the same UI the user triggers generate-download or generate-publish on the DS Generator. The generator fetches the design system from the registry, builds an npm package, and either streams it back to the client or hands it off to the Publisher.
Publication. The Publisher receives the tarball and pushes it to a configured npm registry, making the design system installable as @salutejs-ds/<name>.
Documentation. The user (still from the client UI) triggers documentation/generate on the Docs Generator. It fetches the design system from the registry, renders a Docusaurus project from Handlebars templates, builds the static site, and uploads the result to S3.
Inspection. The Admin app talks to the registry directly through its OpenAPI-typed client, used for debugging schema, browsing tables, and running ad-hoc queries.

Repository layout

design-system-builder/
├── apps/
│   ├── admin/                          # React admin (registry inspector)
│   │   ├── src/
│   │   │   ├── api/
│   │   │   │   ├── client.ts           # typed API client (openapi-fetch)
│   │   │   │   ├── openapi.json        # generated OpenAPI spec (artifact)
│   │   │   │   └── types.gen.ts        # generated TS types (artifact)
│   │   │   ├── pages/
│   │   │   │   ├── TablesPage.tsx      # /tables — DB table browser
│   │   │   │   ├── QueriesPage.tsx     # /queries — saved query catalog
│   │   │   │   ├── SchemaPage.tsx      # /schema — ER diagram
│   │   │   │   ├── DocsPage.tsx        # /docs — Scalar API reference
│   │   │   │   └── SettingsPage.tsx    # /settings
│   │   │   ├── App.tsx
│   │   │   └── main.tsx
│   │   ├── vite.config.ts
│   │   └── package.json
│   └── client/                         # React DS builder UI (Plasma-based)
│       ├── src/
│       ├── vite.config.ts
│       └── package.json
├── services/
│   ├── ds-registry/                    # Express + Drizzle, central registry API
│   │   ├── src/
│   │   │   ├── db/
│   │   │   │   ├── index.ts            # DB connection (postgres-js + Drizzle)
│   │   │   │   ├── schema.ts           # Drizzle schema
│   │   │   │   ├── seed-dev.ts         # dev seeding entry point
│   │   │   │   ├── seed-prod.ts        # prod seeding entry point
│   │   │   │   ├── reset.ts            # full schema reset
│   │   │   │   ├── clear.ts            # truncate tables
│   │   │   │   └── seeds/              # per-table seed files (data/dev/prod)
│   │   │   ├── routes/
│   │   │   │   ├── index.ts            # root router
│   │   │   │   ├── api/                # CRUD routes (one file per resource)
│   │   │   │   │   ├── utils.ts        # assertFound, tryCatch
│   │   │   │   │   ├── design-systems.ts
│   │   │   │   │   ├── components.ts
│   │   │   │   │   ├── tokens.ts
│   │   │   │   │   ├── legacy.ts       # /api/legacy/design-systems/:name/*
│   │   │   │   │   └── …               # the rest of the resources
│   │   │   │   └── misc/               # auxiliary routes
│   │   │   │       ├── tables.ts       # /api/tables
│   │   │   │       ├── queries.ts      # /api/queries
│   │   │   │       ├── nl-query.ts     # /api/nl-query
│   │   │   │       └── schema.ts       # /api/schema
│   │   │   ├── validation/
│   │   │   │   ├── schema.ts           # Zod schemas for all tables
│   │   │   │   └── middleware.ts       # validateBody, validateParams
│   │   │   ├── openapi/
│   │   │   │   ├── spec.ts             # OpenAPI 3 spec (auto-built from Drizzle + Zod)
│   │   │   │   └── generate.ts         # writes openapi.json
│   │   │   ├── queries/
│   │   │   │   └── catalog.ts          # named query catalog
│   │   │   ├── nl-query/
│   │   │   │   ├── llm-service.ts      # Z.AI API client
│   │   │   │   ├── schema-context.ts   # schema context for the LLM
│   │   │   │   └── sql-validator.ts    # validation (SELECT only)
│   │   │   ├── zod-extend.ts           # extendZodWithOpenApi (called once)
│   │   │   └── index.ts                # Express server entry
│   │   ├── drizzle/                    # generated SQL migrations
│   │   ├── drizzle.config.ts
│   │   ├── .env.example
│   │   └── package.json
│   ├── ds-generator/                   # Fastify, builds DS npm packages
│   ├── ds-documentation-generator/     # NestJS, builds Docusaurus + S3 deploy
│   └── publisher/                      # Express, npm publishing
├── docs/                               # Internal docs (schema, status, todo)
├── .github/
│   ├── workflows/                      # CI: build & deploy apps to S3
│   └── actions/
├── .claude/
│   └── skills/                         # Claude Code skills
│       ├── sync-all/                   # /sync-all — full sync
│       ├── sync-validation/            # /sync-validation — refresh Zod schemas
│       ├── sync-routes/                # /sync-routes — create/remove routes
│       ├── sync-spec/                  # /sync-spec — refresh OpenAPI spec
│       └── sync-api-types/             # /sync-api-types — regenerate TS types
├── docker-compose.yml                  # Production compose (subset)
├── docker-compose.dev.yml              # Development compose (full stack)
├── setup-docker.sh                     # One-command dev setup
└── package.json                        # Root scripts (dev / build / install:all)

Quick start

Recommended path: Docker. It is the only setup that's actively used and tested. Local (non-Docker) development still works for individual services but you have to wire ports and env vars yourself.

Prerequisites

Docker and Docker Compose
Node.js ≥ 18 (only if you want to run services outside of Docker)

Run everything with Docker (recommended)

# Clone
git clone <repo-url>
cd design-system-builder

# Start everything (postgres + registry + admin + client + generator + publisher + docs-generator)
./setup-docker.sh

The script builds the dev images, starts the stack via docker-compose.dev.yml, runs the registry migrations, seeds dev data, and prints a health summary.

Once it's done:

Service	URL
Client (DS builder UI)	http://localhost:3002
Admin (registry inspector)	http://localhost:3004
DS Registry API	http://localhost:3008/api
DS Generator	http://localhost:3005
Docs Generator	http://localhost:3006
Publisher	http://localhost:3007
Postgres (ds-registry)	localhost:5433

Common commands:

# Logs
docker-compose -f docker-compose.dev.yml logs -f

# Stop (data persists)
docker-compose -f docker-compose.dev.yml down

# Stop and wipe data
docker-compose -f docker-compose.dev.yml down -v

# Re-run migrations / re-seed manually
docker-compose -f docker-compose.dev.yml exec ds-registry npx drizzle-kit migrate
docker-compose -f docker-compose.dev.yml exec ds-registry npx tsx src/db/seed-dev.ts

Run locally without Docker

You'll need a Postgres instance reachable from ds-registry and the right env vars in each service.

# 1. Start Postgres (you can still use the dev compose for the DB only)
docker-compose -f docker-compose.dev.yml up -d postgres-registry

# 2. Configure ds-registry
cp services/ds-registry/.env.example services/ds-registry/.env
# default values already point at localhost:5433/ds_registry

# 3. Install dependencies for every workspace
npm run install:all

# 4. Apply migrations and seed
cd services/ds-registry
npm run db:migrate
npm run db:seed:dev
cd ../..

# 5. Start everything in parallel
npm run dev

The root package.json exposes per-service scripts so you can also start them one by one:

Script	What it runs
`npm run dev`	All services and apps in parallel
`npm run dev:services`	Backend services only (registry, generator, publisher, docs-generator)
`npm run dev:ds-registry`	DS Registry only (port 3008)
`npm run dev:ds-generator`	DS Generator only (port 3005)
`npm run dev:publisher`	Publisher only (port 3007)
`npm run dev:ds-documentation-generator`	Docs Generator only (port 3006)
`npm run dev:client`	Client app only (port 3002)
`npm run dev:admin`	Admin app only (port 3004)
`npm run build`	Production build of every service and app
`npm run install:all`	Install dependencies in every workspace

DS Registry: database

Postgres lives in the dev compose as postgres-registry (host port 5433). The registry connects with:

DATABASE_URL=postgresql://postgres:postgres@localhost:5433/ds_registry
PORT=3008
ZAI_API_KEY=your-zai-api-key-here   # for /api/nl-query

Inside Docker the host becomes postgres-registry:5432. See services/ds-registry/.env.example.

Drizzle ORM commands

Run from services/ds-registry:

Command	Description
`npm run db:generate`	Generate a SQL migration after changing `schema.ts`
`npm run db:migrate`	Apply migrations to the database
`npm run db:seed:dev`	Seed the DB with dev fixtures
`npm run db:seed:prod`	Seed the DB with prod fixtures
`npm run db:reset`	Drop the schema (run migrate + seed afterwards)
`npm run db:clear`	Truncate tables (keeps the schema)
`npm run db:studio`	Open Drizzle Studio

Common scenarios

First run (without Docker):

docker-compose -f docker-compose.dev.yml up -d postgres-registry
cd services/ds-registry
npm run db:migrate
npm run db:seed:dev

Schema (schema.ts) or routes (routes/api/) changed:

# Inside services/ds-registry
npm run db:generate   # only if schema.ts changed
npm run db:migrate    # only if schema.ts changed

# From the repo root, via Claude Code
/sync-all             # updates validation, routes, openapi spec, and admin types

Reset to a clean state:

cd services/ds-registry
npm run db:reset
npm run db:migrate
npm run db:seed:dev

Admin: API types

The admin app uses a typed OpenAPI client. Types are generated from the registry's OpenAPI spec — no running backend required:

# Inside apps/admin
npm run api:gen        # uses the spec checked into apps/admin/src/api/openapi.json
npm run api:gen:live   # fetches it from http://localhost:3008/api/openapi.json

After regeneration the typed client in apps/admin/src/api/client.ts is good to use:

import { api } from "../api/client";

const { data } = await api.GET("/users");
const { data: user } = await api.GET("/users/{id}", {
  params: { path: { id: "..." } },
});

Run this after any schema/route changes — or just use /sync-all, which does it for you.

Admin: pages

Route	Description
`/tables`	Browse all DB tables, paginated
`/queries`	Saved query catalog with parameters
`/schema`	Interactive ER diagram
`/docs`	Scalar API reference (OpenAPI)
`/settings`	Admin settings

Claude Code skills

Skills for keeping the registry's generated artifacts in sync with the schema and routes. Live in .claude/skills/.

Skill	What it does
`/sync-all`	Runs the four skills below in order
`/sync-validation`	Updates `services/ds-registry/src/validation/schema.ts`
`/sync-routes`	Creates/removes files in `services/ds-registry/src/routes/api/`, updates `routes/index.ts`
`/sync-spec`	Updates `services/ds-registry/src/openapi/spec.ts`
`/sync-api-types`	Regenerates `apps/admin/src/api/openapi.json` and `types.gen.ts`

CI / Deployment

GitHub Actions in .github/workflows/ build the two frontend apps and sync them to S3:

design-system-builder.yml — runs on master, builds apps/client and apps/admin and uploads the dists to the production S3 bucket.
design-system-builder-pr.yml — same flow for pull requests.

Backend services (ds-registry, ds-generator, publisher, ds-documentation-generator) are deployed separately from this repo's CI.

Documentation

docs/database-schema.md — registry database schema
docs/component creation.md — how to create a component
services/ds-documentation-generator/README.md — docs-generator deep-dive

License

See repository for license information.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Design System Builder

What you can do with it

Architecture

Services

How a design system flows through the system

Repository layout

Quick start

Prerequisites

Run everything with Docker (recommended)

Run locally without Docker

DS Registry: database

Drizzle ORM commands

Common scenarios

Admin: API types

Admin: pages

Claude Code skills

CI / Deployment

Documentation

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 259 Commits
.claude/skills		.claude/skills
.github		.github
apps		apps
docs		docs
services		services
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
CLAUDE.md		CLAUDE.md
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
setup-docker.sh		setup-docker.sh

Folders and files

Latest commit

History

Repository files navigation

Design System Builder

What you can do with it

Architecture

Services

How a design system flows through the system

Repository layout

Quick start

Prerequisites

Run everything with Docker (recommended)

Run locally without Docker

DS Registry: database

Drizzle ORM commands

Common scenarios

Admin: API types

Admin: pages

Claude Code skills

CI / Deployment

Documentation

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages