Skip to main content
Every registry component follows the same shape. This page is what it takes to add one to mzizi-dev/mzizi-registry.
New work goes to Rust. Mzizi’s own components are being rebuilt in Rust as Mzizi Roots, and that is where new component work goes. The .tsx steps below are the React build, which keeps working but is deprioritised. A component with a Rust sibling lives beside its .tsx as a .rs file and has a contract test asserting the two agree. The design for Roots is still being written, so check the registry for its current conventions before starting a Rust component.

1. Create the component file

Components live under components/registry/n<number>-<name>/, filed by the node they sit on. See placing a component if you are unsure which that is.

2. Follow the mandatory patterns

Every component carries:
  • CVA variants — class-variance-authority for every visual variant, never inline conditional classes.
  • cn() composition — all className props go through it.
  • A data-slot attribute on the root element.
  • Named exports — the component and its variants. No default export.
  • Radix UI primitives for focus, keyboard and screen-reader behaviour where the component is interactive.
  • TypeScript types extending the appropriate HTML element props.

3. Add it to registry.json

An item with more than one source file where the schema expects exactly one is a manifest bug rather than a bad request, and the API says so — worth knowing when a component 500s and the source looks fine.

4. Run the generators

pnpm build is the registry’s whole build. There is no app to build: it runs every generator, and CI’s Build job fails if running it changes a committed file.

5. Check it resolves

There is no local server: the registry removed its app, /api/* included, on 2 October 2026. Once the change is on main and the API’s pin has moved to it, curl https://api.mzizi.dev/v1/ui/my-component returns the metadata and the inlined source.

6. Add tests

7. Run everything

pnpm check chains every CI gate locally.

Checklist

  • CVA + Radix + cn() throughout
  • CSS custom properties only — no hardcoded colours
  • data-slot on the root element
  • Named exports, no default export
  • Entry in registry.json with the right type and dependencies
  • pnpm registry:validate and pnpm registry:verify pass
  • pnpm build leaves no diff
  • Tests, lint and types pass
  • WCAG 7:1 / 4.5:1 / 3:1 and APCA 3.0 contrast, a hit region of 45px on touch and 24px on a desktop, 17px body on touch and 15px on a desktop, and nothing readable under 14px, keyboard navigation

How Mzizi is built and released

The organisation process is set in nyuchi/.github. This section states the rules as that repository gives them.

Versioning

Owner decision, 4 October 2026 (nyuchi/.github#80). The branch decides the bump. Nobody labels a pull request, and agents add nothing to a pull request to choose a version.
  • Minor and patch have no upper limit: patch 999 is followed by patch 1000, minor 999 by minor 1000. Versions compare as numbers. Only a major is manual.
  • Agents never release a major and never hand-edit a version to one. A major is the owner’s call, made from the Actions tab.
  • Released versions are never renumbered.

Pull requests and merges

  • Feature pull requests into staging are squashed. staging keeps linear history, and the pull request title becomes the commit message.
  • Promotion is a merge commit. A release (staging into the default branch) and a hotfix/* pull request are merged with a merge commit, so the default branch contains staging’s history. The default branch does not require linear history.
Source: nyuchi/.github, ORG_SETTINGS.md and settings/README.md (the promotion merge changed on 2026-11-02).

All checks green

The rule: nothing merges while any check is red or pending. This is the rule for Mzizi work. Making the all-checks-green gate required in every repository is still pending, so until it is, a repository can merge with a check that did not report.

Tooling order

Owner direction, as of 17 November 2026. It is not yet written into any repository.
Rust first, then Deno or Vite+ (vp), never Node by default.