synthesisui
The CLI for SynthesisUI - where your design system is born, scored against the classic design canon, and delivered to any coding agent.
Your AI writes UI. This gives it a design system to write it in: tokens, typed
components, whole pages and a CLAUDE.md manifest that Claude Code, Cursor,
Copilot or any coding agent reads before writing a single line.
This repository is a read-only mirror of
packages/cliin the SynthesisUI monorepo, published so you can audit exactly what runs in your repo. Issues and bug reports are very welcome here; pull requests can't land on a mirror - open an issue instead.
Quickstart
npx synthesisui@latest init --styles tailwind --ds <slug>
Pick any system from the gallery - or create your own in two minutes.
Commands
| Command | What it does |
|---|---|
init |
One-shot setup: materialize a system + wire your project for it |
login |
Connect to your account (device-flow in the browser) |
list |
List the design systems available to you |
add <slug> |
Materialize a system into _synthesisui/ds/<slug>/ |
use <slug> |
Generate the agent prompt to apply the system to your app |
component <slug> <name> |
Bring one typed component into your components dir |
template <slug> <name> |
Generate a whole page (landing, dashboard, onboarding…) |
generate |
Generate a page from a saved guide structure |
advise |
Grounded design advice for this repo, from your system's rules |
refit <file> |
Send an app component back into your design system |
upgrade <slug> |
Diff your .lock against the latest version and migrate |
clean |
Remove materialized files and the managed CLAUDE.md block |
doctor |
Audit the repo for drift: every design value written by hand, and the token your system already has for it |
doctor
Every tool in this space promises output that is brand consistent and free of drift. None of them checks. This checks, in the only place it can be true - the code that shipped.
npx synthesisui@latest doctor
── Doctor ────────────────────────────────────────────────────────
Aluna v1 - 91 tokens, 53 files read
Token coverage ████████████████████████ 98%
2019 from the system, 34 by hand
── Drift ─────────────────────────────────────────────────────────
26 colour
8 spacing
app/welcome2/_components/signature.tsx
19 #8b8bf1 → --ds-color-blue-500
21 #f1f3fa → --ds-color-gray-100
Overruled
With a system installed it runs a second pass that nothing else can:
── Overruled ─────────────────────────────────────────────────────
3 places where the code takes a component
the system defines, and then overrules it locally.
components/Hero.tsx
12 ds-button · border-radius: 4
the recipe binds {radius.md}
18 ds-button · padding: px-8
the recipe binds {spacing.2xs} {spacing.md}
It only flags a property the recipe actually binds. w-full beside a
button is layout; px-8 is drift, because the recipe already decided the
padding. A rule reading var(--ds-…) back is the opposite of overruling and
is left alone. This needs the recipes, which are only in the project because
add put them there - a linter has no idea what ds-button promised.
The last column is the point: not "you hardcoded a colour", but the name your own system already has for it. Exact matches only - a tool that guesses a near colour invites a silent visual change, and a diagnosis nobody trusts is worse than none.
With no system installed it still finds every hand-written value and counts the distinct ones. Runs offline, needs no account, writes nothing.
What your system says
── What your system says about what you use ──────────────────────
ds-badge · 3 places
Badges whisper status in periwinkle; danger appears only for money at risk.
ds-button · 3 places
One indigo action per view; gold is reserved for moments of ceremony, never buttons.
Buttons speak quietly - sentence case, no exclamation.
The usage laws your team wrote, for the components this project actually uses, ordered by how much you use them. They are prose, so nothing verifies them - the value is putting them in front of whoever is touching the component. No other tool is positioned to do it, because no other tool knows these laws exist.
--strict exits 1 when drift is found, for CI. --all lists every finding
instead of the loudest files. --laws shows every law instead of the busiest
components.
What add materializes
Inside _synthesisui/ds/<slug>/:
design-system.json- the canonical source of truthtokens.css- CSS custom properties scoped bydata-dstheme.css- optional Tailwind v4@themeadapter (bg-primary,p-md, …)GUIDE.md- agent instructions: semantic roles, mood, recipesrules.md- the governance your agent must follow.lock- pinned slug + version (reproducible upgrades)
Plus an idempotent <!-- synthesisui:start/end --> block in your root
CLAUDE.md listing every installed system and its component manifest.
Authentication
synthesisui login uses device-flow (RFC 8628): it opens the browser, you
confirm a code, and the token lands in ~/.synthesisui/credentials.json
(per machine, chmod 600). Logout = delete that file.
Registry
Defaults to https://www.synthesisui.com. Override with:
synthesisui list --registry http://localhost:3000
# or
SYNTHESISUI_REGISTRY_URL=http://localhost:3000 synthesisui list
License
MIT