Set up Better Design

Install

Run these commands in your project:

npx skills add marvkr/better-design --skill better-design
npx better-design

The first installs the agent skill. The second connects Better Design to your coding tools. Restart your agent after setup. The install guide has the steps for each coding tool.

Rerunning setup preserves existing connections. If setup reports a manual step, finish it first. Then ask your agent to list Better Design's design systems and confirm that a tool returns a result.

Your free key

If you have no account, setup creates a free key for you. Using that key accepts the Terms of Service at the version setup prints. Setup saves the key in ~/.better-design/key and reuses it when you run it again on the same machine. To start over, delete that file.

A key the installer creates for you is free for a limited number of queries. To keep it on a free account, open the claim link it gives you and sign in. The page shows a line with a code; paste that line into your AI tool. confirm-claim first names the account the key would join and asks you to confirm it, then links the key and emails that account. Only the tool that holds the key can confirm it, and the code works for ten minutes.

Ask in the session that ran setup

Your AI client loads Better Design at its next start. To get an answer in the session that ran setup, run npx better-design ask "<question>", or add --ux for the UX principles.

Record where you found Better Design

Install links can record where you found Better Design with npx better-design --source docs. Supported source labels are docs, github, claude_directory, openai_catalog, campaign, and unknown (the default).

The installer sends this label when creating a free key and records npm as the install method. It does not infer your referral source or active client from the editors installed on your computer.

Ready a project for a design system

To ready a project for a design system install, run npx better-design init in its root. In a Vite project it adds Tailwind v4 and the @/* alias, then runs shadcn init. It does nothing when components.json exists.

Fix a problem

If something does not work, run npx better-design doctor. It checks your key, the connection to the server, each client's configuration, the review hook in this project and your version, and prints the command that fixes each problem. It changes nothing.