Concepts

Installed source

The Circle Health Registry distributes source rather than a runtime component package. Installing an item copies files into the consumer. The consumer then owns those files and can change them without waiting for a central package release.

Reinstalling an item may replace local changes. Inspect the diff before accepting an update.

Components

Components are low-level UI with no product workflow attached. Each registry entry maps to one source module and uses the @circle-ui namespace.

Blocks

Blocks are product modules assembled from components. A block may pull in private hooks, types, or serialization helpers, but those implementation files are not separate catalog choices.

Install one focused block for one product capability. Use an umbrella entry only when the capability is intentionally shipped as a coordinated family.

Utilities

Utilities provide behavior without a visual primitive or product workflow. They use the @utilities namespace so consumers can distinguish instrumentation and browser helpers from UI blocks.

Localized copy

Optional locale dictionaries use the @i18n namespace. They stay separate from UI source so consumers own translation loading and locale boundaries. The owning block documents the relevant dictionary.

Themes

Themes are CSS-variable sets. Components and blocks refer to those variables rather than hard-coded product colors, so a consumer can change a surface without rewriting component logic.

Dependencies

Each registry item declares two dependency kinds:

Kind	Resolution
Registry dependency	The shadcn CLI installs another Registry item.
npm dependency	The consumer’s package manager installs a third-party package.

Registry dependencies use their full namespace in generated JSON. The docs show both dependency kinds on every reference page.

Authoring and generated output

Authoring source lives in packages/ui, packages/styles, and registry. Configuration lives in config/registry. pnpm registry:build produces the public JSON under apps/docs/public.

Treat generated JSON as build output. Change the authoring source or registry configuration, rebuild, and verify the generated diff.