This directory is the source of truth for the v4 component registry. The build pipeline (../scripts/build-registry.mts) reads the authored source here and generates the runtime indexes, the local styles/ consumed by the docs app, and the installable output under public/r/.

Source of truth (authored by hand)

bases/base/, bases/radix/ — the two authored base registries (Base UI and Radix). Each holds a registry.ts plus ui/, lib/, hooks/, blocks/, examples/, and internal/. Shared surfaces should stay in sync across both bases — see bases/README.md.
styles/style-*.css — the style token files (nova, sera, vega, …). Each defines the design tokens for one style.
new-york-v4/ — the legacy source registry. Unlike the generated combinations below, its registry.ts and component files are authored directly and committed.
../examples/base, ../examples/radix — authored component demos. See ../examples/README.md.

Generated output (do not edit by hand)

Persistent (committed):

bases/__index__.tsx — runtime lookup for the authored bases.
__index__.tsx — runtime lookup across legacy styles and every base/style combination.
__blocks__.json — block metadata index.
../examples/__index__.tsx — runtime lookup for demos.
../styles/<style>/ui/* — compiled components for each base/style combination, imported by the docs app.
../styles/<style>/ui-rtl/* — RTL variants, generated for base-nova and radix-nova only.
../public/r/* — installable registry JSON served by the website and the CLI.

Temporary (created during the build, then cleaned up):

<style>/* — per-combination registries (e.g. base-nova/).
../registry-<style>.json

The style model

There are two kinds of "styles", and the distinction drives the build flags:

Generated combinations — every base (base, radix) crossed with every style token (nova, sera, …) produces a combination like base-nova or radix-sera. These are generated from the authored bases plus the style CSS; nothing under registry/<combination>/ is committed.
Legacy source registry — new-york-v4 is authored directly and committed. It is not generated from a base/style combination.

Building

Run from apps/v4:

pnpm registry:build

This runs the full pipeline: build the bases, generate every combination, write the runtime indexes, export public/r/ for every style, copy the compiled UI into styles/, and build the RTL styles. It is the canonical build — generated output is prettier-formatted. Run this before committing or for production.

Fast targeted builds

The targeted flags below are for quick local iteration. To stay fast they skip formatting the generated output, so they can leave generated files unformatted (and produce large but harmless git diff churn). The full pnpm registry:build above re-canonicalizes everything, so run it before you commit.

For local iteration you can rebuild only the artifact you changed:

pnpm registry:build --examples            # examples/__index__.tsx
pnpm registry:build --indexes             # runtime registry indexes
pnpm registry:build --style base-nova     # styles/base-nova/ui (+ ui-rtl)
pnpm registry:build --style all           # every generated combination
pnpm registry:build --registry base-nova  # public/r/styles/base-nova
pnpm registry:build --registry all        # every style, incl. new-york-v4

Flag	Rebuilds	Run after
`--examples`	`../examples/__index__.tsx`	adding, removing, or renaming a demo
`--indexes`	`bases/__index__.tsx`, `__index__.tsx`, `__blocks__.json`, `public/r/index.json`	changing registry or block metadata
`--style <style\|all>`	`../styles/<style>/ui` and `ui-rtl`	editing authored base UI/components
`--registry <style\|all>`	`../public/r/styles/<style>`	changing what the CLI installs

Notes:

Flags can be combined, e.g. --style base-nova --registry base-nova.
all targets every supported style.
Editing an existing example file usually does not need a rebuild — only adding, removing, or renaming one (which changes the index) does.
--style new-york-v4 is rejected because it is a legacy source registry, not a generated combination. Use --registry new-york-v4 instead.
Unknown targets fail with the list of valid style ids.