Contributing to helixui

helixui is an AI-friendly design system. The bar we hold ourselves to:

Anything a human can pick up by reading the code, an LLM should be able to pick up by reading llms.txt, the DTCG token JSON, and each component’s spec.md.

If your change preserves that property, we want it.

This section mirrors the root CONTRIBUTING.md and the site /contributing page so that everything you need is reachable from the docs sidebar.

Quick start

pnpm install
pnpm build:tokens     # generate CSS vars + TS types from DTCG JSON
pnpm dev:site         # http://localhost:4323
pnpm dev:docs         # http://localhost:4321

Requirements:

• Node >=20 (the repo pins it via .nvmrc)
• pnpm 10.x (the repo pins it via packageManager)

What this section covers

• Repo layout — every package and what it owns.
• The two contracts — tokens-as-JSON and spec.md-per-component. Every PR has to respect both.
• Adding a component — the five steps from scaffold to docs.
• Pull request conventions — branch from main, one logical change, typecheck and format clean.
• Reporting bugs — what to include so we can reproduce.

Code of conduct

Participation is governed by the Code of Conduct. By contributing you agree your contributions will be licensed under the MIT License.