What Is a shadcn-Compatible Registry?

A registry is a catalog of components the shadcn CLI can copy into your codebase as source you own — not an npm dependency. Here's how the model works, how to consume any registry, and what separates a good one from a code dump.

The model: source distribution, not a package

Traditional UI libraries ship compiled code through npm; you configure them through props and fight them at the edges. The shadcn model inverts this: a registry serves each component as a JSON item — source files, dependency list, install target — and the CLI writes that source into your repository. From that moment it's your code: restyle it, rewrite it, delete half of it. No version bumps, no breaking changes, no waiting for a maintainer.

Installing from any registry

Point the CLI at an item URL — this works against any compatible registry:

npx shadcn@latest add https://ui.zyeon.ai/r/hold-to-confirm.json

For registries you use often (or ones that need authentication), register a namespace in components.json:

{
  "registries": {
    "@zyeon": {
      "url": "https://ui.zyeon.ai/r/{name}.json",
      "headers": { "Authorization": "Bearer ${ZYEON_TOKEN}" }
    }
  }
}

npx shadcn@latest add @zyeon/gantt-chart

What separates a good registry from a code dump

Semantic tokens, not hard-coded colors. Components styled with bg-primary and var(--chart-1) inherit your theme instantly; components full of hex values fight it forever.
Declared dependencies.A registry item lists every npm package and every sibling component it needs — if it doesn't, the install compiles broken.
States beyond the happy path. Data-driven components should handle loading, empty and error as first-class branches, not as an afterthought.
Material an AI agent can work with. Source alone tells an agent what the component is; a generation prompt and a concept map tell it why — which is what it needs to produce a correct variant for your project instead of a mutation.

How Zyeon UI implements this

Every one of the 353 components in the catalog ships as a four-piece kit: live preview, full source in semantic tokens, the generation prompt that produced it, and a concept map of the interaction. Free components (283) install with no account; Pro components add personal access tokens for the CLI and an MCP endpoint so agents can search the catalog by intent and install directly. Details on pricing.