Contributing

• A bug: open an issue with a link to a reproduction, the browser and the package version.
• A new component or variant: open a New component issue first. Every component starts from a spec, so the behaviour is agreed before any code.
• A question: ask in Discussions.
• A security problem: report it privately through the repository's Security tab, never in a public issue.

You need Node.js 24 and pnpm 10.

git clone https://github.com/booleanpress/ui.git
cd ui
git switch dev
pnpm install
pnpm docs:dev   # this site, at http://127.0.0.1:5180/

Work on a branch from dev, and open your pull request against dev. main holds released versions only.

1. Spec first. Read specs/000_component-spec-standard.md. A new variant, prop or string needs a short mini-spec; a new component or a change of behaviour needs a full spec, agreed in its issue.
2. Stock first. Components come from the shadcn/ui command-line tool at the version the repository pins. A deviation from stock carries a // boolean-ui patch: comment and a row in PATCHES.md.
3. Examples and tests. Each state gets an example in examples/<component>/, which is also its preview here, and each keyboard row gets a test in tests/components/.
4. No English inside components. Built-in text comes from the provider; a new string is a new provider key with an English default.
5. Tokens only. Colours come from the theme's tokens, and motion from its motion tokens.
6. Changelog. Add a line under ## Unreleased in CHANGELOG.md: what changed, and what consumers must do.

pnpm check

It runs everything the pull request's checks run and prints one line per step: lint, types, licences, tests with axe, the build, the packed package, a Vite app and a Next.js app built from it, and this site built from it and tested in a browser. Every line must be green.