Contribution Guide

Contributing to Intent UI

Thanks for helping make Intent UI better. You can contribute bug fixes, new or improved components, examples, documentation, and accessibility improvements.

Before starting, search the existing issues and pull requests. For large features or breaking changes, open an issue first so we can agree on the direction.

The repository's CONTRIBUTING.md is the canonical reference for contribution policies and workflow details.

Local setup

Intent UI uses Node.js 20 or later and npm. Fork the repository, clone your fork, and create a descriptive branch from main. Then install the dependencies and start the documentation site:

npm install
npm run dev

Open http://localhost:3000 to preview your changes.

Find your way around

Most contributions touch one or more of these directories:

src/
├── app/pre-blocks/          # Block source files
├── components/
│   ├── examples/            # Examples shown in the documentation
│   └── ui/                  # Registry-distributed UI components
└── content/docs/            # MDX documentation

The registry is generated from source files. Do not edit generated files under __registry__/, public/r/, public/registry/, or public/stubs/ directly.

Contributing components

Intent UI components are built with React Aria Components and Tailwind CSS. Follow the patterns already used in src/components/ui/:

• Build on a React Aria primitive when an appropriate one exists.
• Preserve keyboard navigation, focus management, labeling, validation, and disabled states.
• Use existing semantic color tokens rather than hard-coded theme colors.
• Use intent for visual-purpose variants and keep APIs consistent with related components.
• Add or update an example in src/components/examples/ for visible behavior.
• Update the matching MDX documentation when public APIs or behavior change.

After changing registry-distributed components, examples, hooks, shared dependencies, blocks, or installation stubs, regenerate the registry:

npm run r

Validate your changes

Run the standard checks before opening a pull request:

npm run lint
npm run typecheck
npm run build

If formatting needs to be fixed, run npm run format, review the result, and then run the checks again. Registry-affecting changes should also run npm run r.

Prepare your pull request

• Keep the pull request focused and explain what changed and why.
• Link the relevant issue when one exists.
• Include screenshots or recordings for visual changes.
• Describe keyboard and screen-reader behavior for interaction changes.
• Call out breaking changes and migration steps clearly.

By participating, you agree to follow the project's Code of Conduct. Contributions are licensed under the MIT License.