Get started

Find your situation, copy the prompt, and paste it into your AI agent (Claude Code, Cursor). It runs the commands and asks you the questions.

Start a design system in this repo

This repo is (or will be) our source of truth, and other repos should follow it.

Set up ChoiceUI in this repo and make it our shared design system.

1. Run `npx @jlist/choiceui login`, then `npx @jlist/choiceui init`. Init extracts our Tailwind tokens and components into choiceui.manifest.json and links a cloud project.
2. Run `npx @jlist/choiceui publish` to publish this repo as the design system other repos follow.
3. Run `npx @jlist/choiceui guard` to generate the enforcement kit (CI gate, ESLint, a Claude Code skill, CLAUDE.md, MCP), and commit it.

Report the system ID that publish prints, so I can connect our other repos.

Or run the commands yourself

$ npx @jlist/choiceui login
$ npx @jlist/choiceui init
$ npx @jlist/choiceui publish
$ npx @jlist/choiceui guard

Connect this repo to our shared system

Another repo owns the design system, and this repo should follow it.

Connect this repo to our shared ChoiceUI design system.

1. Run `npx @jlist/choiceui login`.
2. Run `npx @jlist/choiceui link --system <SYSTEM_ID>` to follow our system, then `npx @jlist/choiceui pull` to fetch it.
3. Run `npx @jlist/choiceui doctor` to check this repo against the system.

Replace <SYSTEM_ID> with our design system's ID (from the owner repo's publish output, or the ChoiceUI dashboard).

Or run the commands yourself

$ npx @jlist/choiceui login
$ npx @jlist/choiceui link --system <SYSTEM_ID>
$ npx @jlist/choiceui pull
$ npx @jlist/choiceui doctor

Set up an empty design-system repo

You made a repo to be the design system, but there is nothing in it yet.

This repo is meant to be our design system but is empty. Set it up and ask me for direction.

1. Run `npx @jlist/choiceui init --scaffold` to lay down the structure.
2. Run `npx @jlist/choiceui direction --json` to see what ChoiceUI needs from me (brand colors, fonts, first components).
3. Ask me each question, then apply my answers with `npx @jlist/choiceui direction --set <id>=<value>` (for example `--set brand.primary=#227C9D`).

Or run the commands yourself

$ npx @jlist/choiceui init --scaffold
$ npx @jlist/choiceui direction --json
$ npx @jlist/choiceui direction --set brand.primary=#227C9D

Clean up a messy repo

The UI is a mess: several buttons, a few fonts, lots of near-identical greys.

Our UI is inconsistent. Help me turn it into one coherent design system.

1. Run `npx @jlist/choiceui init`.
2. Run `npx @jlist/choiceui canonicalize --json` to find the competing components, fonts, and near-duplicate colors.
3. Show me each conflict and ask which one is canonical, then record my choices with `npx @jlist/choiceui canonicalize --set <id>=<value>`. The ones I pick become the system, the rest become drift.

Or run the commands yourself

$ npx @jlist/choiceui init
$ npx @jlist/choiceui canonicalize --json
$ npx @jlist/choiceui canonicalize --set canonical.component.Button=src/components/ui/button.tsx

Govern an existing design system

You already have a solid design system here. You just want to enforce it.

We already have a design system in this repo. Set up ChoiceUI to govern it.

1. Run `npx @jlist/choiceui init` to capture our tokens and components into a manifest.
2. Run `npx @jlist/choiceui guard` to generate the enforcement kit (CI gate, ESLint, a Claude Code skill, CLAUDE.md, MCP).
3. Run `npx @jlist/choiceui doctor` to show where the code is off-system, and commit the enforcement kit so CI blocks drift from here on.

Or run the commands yourself

$ npx @jlist/choiceui init
$ npx @jlist/choiceui guard
$ npx @jlist/choiceui doctor

Everything runs in your repo. Only publishing and the dashboard need an account.