Governance for AI

Stop AI agents from breaking your design system.

Your design system already lives in your repo as real Tailwind and components. ChoiceUI makes it the enforced source of truth, so your codebase, and every AI agent working in it, cannot drift off system without a decision you actually made.

$ npx @jlist/choiceui init

Runs locally. No account needed to start. Pick your exact setup below.

Detect: Reads your components and tokens into one manifest, and sees what is in the code but not in the system.
Decide: Anything ungoverned gets a decision: adopt it, allow a one-off, or reject it. Recorded, so it sticks.
Enforce: A CI gate blocks drift. A Claude Code skill and an MCP server keep humans and AI on system by default.

Get started

Find your setup. Copy it. Paste it into your agent.

Each block is a prompt for your AI agent (Claude Code, Cursor). It runs the commands and asks you the questions. Or run the commands yourself.

Build a design system out of this repo's code

Pick this if: You have UI code here but nothing that defines it. No token file everyone agrees on, no rules, no single Button.
You end up with: The tokens and components you already use, captured as one manifest, the conflicts settled the way you chose, and CI that blocks anything off-system.

Set up ChoiceUI in this repo and build our design system out of the code we already have.

1. Run `npx @jlist/choiceui login`, then `npx @jlist/choiceui init`. Init reads our Tailwind tokens and components and writes choiceui.manifest.json. If the repo turns out to be empty, run `npx @jlist/choiceui init --scaffold` instead.
2. Run `npx @jlist/choiceui status` and tell me plainly what state we are in.
3. If there are competing components, fonts, or near-identical colors, run `npx @jlist/choiceui canonicalize --json`, show me each conflict, and record my answers with `npx @jlist/choiceui canonicalize --set <id>=<value>`. What I pick becomes the system, the rest becomes drift.
4. If ChoiceUI is waiting on direction (an empty repo), run `npx @jlist/choiceui direction --json`, ask me each question, and apply my answers with `npx @jlist/choiceui direction --set <id>=<value>`.
5. Run `npx @jlist/choiceui guard` to generate the enforcement kit (CI gate, ESLint, a Claude Code skill, CLAUDE.md, MCP), and commit it.
6. If other repos should follow this system, run `npx @jlist/choiceui publish` and give me the system ID it prints.

Ask me before deciding anything that is mine to decide. Never guess our brand colors.

Or run the commands yourself

$ npx @jlist/choiceui login
$ npx @jlist/choiceui init
$ npx @jlist/choiceui status
$ npx @jlist/choiceui canonicalize --json
$ npx @jlist/choiceui direction --json
$ npx @jlist/choiceui guard
$ npx @jlist/choiceui publish

Enforce the design system this repo already has

Pick this if: The system already exists here and you are happy with it. You just want the code to stop drifting away from it.
You end up with: Your existing tokens and components as the written rules, a report of everywhere the code already breaks them, and CI that stops the next one.

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

1. Run `npx @jlist/choiceui login`, then `npx @jlist/choiceui init` to capture our tokens and components into choiceui.manifest.json.
2. Run `npx @jlist/choiceui doctor` and show me where the code is already off-system. Do not fix anything yet, I want to see the size of it first.
3. Run `npx @jlist/choiceui guard` to generate the enforcement kit (CI gate, ESLint, a Claude Code skill, CLAUDE.md, MCP), and commit it so CI blocks drift from here on.
4. If other repos should follow this system, run `npx @jlist/choiceui publish` and give me the system ID it prints.

Or run the commands yourself

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

Follow a design system that lives in another repo

Pick this if: Another repo is the source of truth. This one should match it, and keep matching it.
You end up with: The shared tokens and components pulled into this repo, a report of where this repo disagrees with them, and CI that keeps it honest.

Connect this repo to our shared ChoiceUI design system, so it follows the system instead of defining its own.

1. Run `npx @jlist/choiceui login`.
2. Run `npx @jlist/choiceui link --system <SYSTEM_ID>`. That one command follows the system, pulls it down, and generates the enforcement kit. Commit the files it writes.
3. Run `npx @jlist/choiceui doctor` and show me where this repo disagrees with the system.

<SYSTEM_ID> is our design system's ID, from the owner repo's publish output or the ChoiceUI dashboard. Ask me for it if you do not have it, do not guess.

Or run the commands yourself

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

Day to day

Once it is set up, these are the only three things you do.

Check what has drifted

Any time, and in CI on every PR once the kit is committed.

Check this repo against our ChoiceUI design system and summarize it for me in plain English.

1. Run `npx @jlist/choiceui status` to confirm what state the repo is in.
2. Run `npx @jlist/choiceui doctor --components` and group what it finds: hardcoded values, off-system colors, and components that re-create something we already have.
3. Tell me which ones are worth fixing and which are noise. Do not change any code.

Or run the commands yourself

$ npx @jlist/choiceui status
$ npx @jlist/choiceui doctor --components

Fix the drift

After a check, or when CI blocks a PR for going off-system.

Bring this repo back onto our ChoiceUI design system.

1. Run `npx @jlist/choiceui reconcile`. It fixes what is safe on its own and asks about the rest.
2. For anything it cannot decide, show me the choice and let me answer. If something genuinely belongs off-system, say so rather than forcing it.
3. Run `npx @jlist/choiceui doctor` again and show me the before and after count.

Or run the commands yourself

$ npx @jlist/choiceui reconcile
$ npx @jlist/choiceui doctor

Change the system and roll it out

You changed a token or a component and the other repos need it.

We changed our design system. Publish it and tell me how to roll it out.

In the repo that owns the system:
1. Run `npx @jlist/choiceui manifest` to refresh choiceui.manifest.json, and show me the diff before anything is published.
2. Run `npx @jlist/choiceui publish` to make it the version other repos follow.

Then, in each repo that follows the system:
3. Run `npx @jlist/choiceui upgrade` to move to the new version, then `npx @jlist/choiceui doctor` to see what the change broke.

Or run the commands yourself

$ npx @jlist/choiceui manifest
$ npx @jlist/choiceui publish
$ npx @jlist/choiceui upgrade
$ npx @jlist/choiceui doctor

Everything runs in your repo. Only publishing and the dashboard need an account. See a live design system →