Contributing
@audtai/judit

Contributing

Set up the Judit repository, follow its curated-fork workflow, and validate a contribution.

Before You Start

Judit is maintained by audt.ai as an independent, curated fork of Cloudflare Kumo. Contributions to Judit target audtai/judit, not the upstream Cloudflare repository.

For a non-trivial change, open or join an issue before implementation so maintainers can align on API direction and migration impact. Small fixes and documentation changes can go directly to a pull request.

Set Up the Repository

git clone https://github.com/audtai/judit.git
cd judit
pnpm install
pnpm build

Requirements:

  • Node ^24.12.0
  • pnpm >=10.21.0

External contributors can fork audtai/judit, push a topic branch to that fork, and open a pull request back to Judit.

Respect the Curated Fork

Cloudflare Kumo is an upstream source, not a branch to merge wholesale. Automated intake opens one downstream pull request for each new upstream commit.

  • Do not merge or pull upstream/main into Judit’s main.
  • Keep an imported upstream commit intact.
  • Put conflict resolutions and Judit adaptations in separate follow-up commits.
  • Preserve upstream authorship, historical changelog entries, and Cloudflare’s copyright notice.
  • Do not imply that Judit is affiliated with, sponsored by, or endorsed by Cloudflare.

Use Names Deliberately

  • Judit is the product.
  • audt.ai is the publisher and maintainer.
  • @audtai/judit is the npm package.
  • Kumo is the upstream project and inherited compatibility namespace.

The physical packages/kumo* paths, Kumo* APIs, KUMO_* constants, and kumo-* semantic tokens remain intentionally. Do not rename them mechanically. New public prose, examples, and package metadata should use Judit.

Pick the Right Location

  • Components: packages/kumo/src/components/
  • Blocks: packages/kumo/src/blocks/
  • Demos: packages/kumo-docs-astro/src/components/demos/
  • Documentation: packages/kumo-docs-astro/src/pages/

Scaffold new components through the repository command:

pnpm --filter @audtai/judit new:component

Demo extraction is name-sensitive: demo filenames and exported functions must end in Demo.

Run the Development Loop

Use separate terminals when changing both the library and docs:

# Terminal 1: package watcher
pnpm --filter @audtai/judit dev

# Terminal 2: docs site
pnpm dev

Implementation expectations:

  • Preserve accessibility semantics and keyboard behavior.
  • Follow existing component patterns for variants, props, and composition.
  • Use semantic kumo-* tokens instead of raw Tailwind color classes.
  • Compose class names with cn(...).
  • Add or update demos and tests with behavior changes.

Validate the Change

pnpm lint
pnpm typecheck
pnpm --filter @audtai/judit test

For export or build changes, also run:

pnpm --filter @audtai/judit build

Changesets and Publishing

Add a changeset for a user-visible change to the published library:

pnpm changeset

Use patch for fixes, minor for backward-compatible features, and major for breaking changes. Documentation-only changes usually do not need a changeset.

Publishing @audtai/judit is a manual, maintainer-controlled operation. Contributors and AI agents must not run version or publish commands.

Open the Pull Request

  • Branch from Judit’s main branch.
  • Use [package] short description, for example [judit] add meter warning variant.
  • Fill in the PR template with review and testing details.
  • Keep commits readable and avoid rewriting commits after review begins.

For deeper implementation guidance, see the repository AGENTS.md, component package guide, and changeset guide.