Contributing

Nesra UI uses pnpm workspaces. Work on a short-lived branch from main and keep each pull request focused on one change.

Set up the repository

From the repository root, use Node.js 24 or newer and pnpm 12.3.4:

pnpm install
pnpm hooks:install
pnpm build:ui

build:ui creates the package output consumed by the docs. Rebuild it after changing exports or styles. Start the docs and Storybook together:

pnpm dev

Use pnpm dev:docs or pnpm dev:storybook when you only need one development surface.

Check ROADMAP.md and existing work before starting a new component. Small documentation fixes can proceed directly; align the API and scope of larger changes before implementation.

Choose the right location

• Published components and styles belong in packages/ui.
• Design and developer reference documentation belongs in apps/docs.
• Interactive component stories belong beside component source and are rendered by apps/storybook.
• Contributor policies and engineering decisions belong in docs/contributing.

For a docs change, follow docs/contributing/writing-documentation.md. It defines page structure, exact terminology, and examples that designers, developers, and agents can verify.

Component implementation, tests, and stories stay together under packages/ui/src/components/<name>/. See docs/contributing/adding-a-component.md for the full file, export, and example workflow.

Implement a component change

1. Start from the approved Figma anatomy, variants, states, and tokens.
2. Use the relevant Base UI primitive for interactive behavior.
3. Expose a focused, composable API and preserve native or primitive props.
4. Style with semantic tokens and forward consumer className values.
5. Update colocated tests and stories, public exports, and consumer documentation together.

Validate the change

Run the complete local quality suite before requesting review:

pnpm fmt:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm package:check

Tests cover observable behavior, keyboard interaction where relevant, and representative axe-core scans. Use Storybook to review visual states, focus visibility, and narrow layouts. For docs-only changes, verify the rendered page and links in the local docs site.

Add a Changeset

Add a Changeset when a change affects what package consumers install, import, render, style, or type-check:

pnpm changeset

Use patch for backwards-compatible fixes, minor for new backwards-compatible capabilities, and major for breaking changes. Documentation-only, test-only, tooling, and internal refactors normally do not require a Changeset.

Prepare the pull request

Branch from main and describe the problem, the API or documentation change, relevant design specification, verification, and Changeset decision. For component changes, include the states reviewed in Storybook. Update the PR with follow-up commits as review feedback arrives.

GitHub Actions are manual-only during the current development phase. Contributors are responsible for running the complete local checks unless manual CI is deliberately requested.