Use shadcn registries with AI coding tools

Why agents need a registry

Ask a coding agent for a date picker and it will write one from memory. It usually works, it rarely handles the keyboard well, and it looks like every other generated date picker. The agent has no way to know that your team already chose a date picker, or that a better one exists.

A shadcn registry fixes that. It is a set of JSON files that describe components: their source, their npm dependencies, and the other registry items they need. The shadcn CLI installs them into your project as source code you own. Once your agent can see a registry, “add a date picker” becomes a search and an install instead of a guess.

This guide uses Arc as the example registry. Every step works the same way with any shadcn-compatible registry, including a private one for your company.

Add a registry namespace

Registries are listed in components.json, the file npx shadcn@latest init creates. Each entry maps a namespace to a URL template, where {name} is replaced by the item name.

{  "$schema": "https://ui.shadcn.com/schema.json",  "style": "new-york",  "tsx": true,  "aliases": { "components": "@/components", "utils": "@/lib/utils" },  "registries": {    "@uiarc": "https://uiarc.dev/r/{name}.json"  }}

Commit this file. It is how teammates, CI and every agent working in the repository find the same components. You can list several namespaces side by side, and private registries can take auth headers from environment variables.

Browse and install from the CLI

Install by name with the namespace prefix. The CLI fetches the item, installs its npm packages, pulls in any registry items it depends on, and writes the files.

# One itemnpx shadcn@latest add @uiarc/button # Several at once; shared dependencies are resolved oncenpx shadcn@latest add @uiarc/button @uiarc/dialog @uiarc/signup-form # Or a full URL, with no namespace set upnpx shadcn@latest add https://uiarc.dev/r/button.json

The CLI can also browse a namespace. These commands are useful to an agent that runs shell commands, and to you when you want to check what it is about to add.

# See what a namespace offersnpx shadcn@latest list @uiarc # Search itnpx shadcn@latest search @uiarc -q "date" # Read an item's files and dependencies before installingnpx shadcn@latest view @uiarc/date-picker

The shadcn MCP server

The CLI is enough for agents that can run commands, but they still have to know what to search for. The shadcn MCP server gives the agent tools to browse, search and install from every registry in your components.json, so you can ask in plain language: “find a toast in the Arc registry and add it”.

# Writes the config for your clientnpx shadcn@latest mcp init --client claudenpx shadcn@latest mcp init --client cursornpx shadcn@latest mcp init --client vscodenpx shadcn@latest mcp init --client codex

Restart the client after running the command. The server reads the namespaces from the project, so adding @uiarc to components.json is all it takes to make Arc searchable.

Arc’s own MCP server

A registry describes files. It does not say when to use a component, which keys it handles, or how it behaves with reduced motion. Arc also runs a read only MCP server that answers those questions. It needs no account or key.

• search_components finds components and blocks by intent, like “confirm a destructive action”.
• list_components browses by category, tag, tier or kind.
• get_component returns usage, props, keyboard behavior, accessibility and motion notes, and the install command.
• get_install_command builds one shadcn command for several items, with setup notes.

claude mcp add --transport http arc https://uiarc.dev/api/mcp

The two servers work well together: Arc’s explains what to use and why, and the shadcn server or the CLI installs it.

Skills, llms.txt and markdown

MCP tools are called on demand. Some context is better loaded up front, and some agents cannot use MCP at all. Arc publishes the same knowledge in plain files:

• An agent skill. It teaches Claude Code when to reach for Arc, how to install it, and the design rules to follow. Other agents can read SKILL.md directly or keep it in AGENTS.md.
• llms.txt indexes every component and block with a link to its markdown. llms-full.txt is the whole library in one file.
• Markdown per component. Add /markdown to any component URL, like /components/button/markdown, and paste the link into a chat.

# Installs the Arc skill into .claude/skills/arcnpx shadcn@latest add https://uiarc.dev/r/arc-skill.json

Prompts that work

Agents follow the path of least resistance. Unless you say otherwise, writing a component is easier for them than looking one up. A few habits change that:

• Name the job, not the markup. “Let people confirm deleting a member” finds a hold to confirm button. “Add a red button” gets a red button.
• Ask it to search the registry first and to read a component before using it. Most wrong props come from skipping this step.
• Forbid rewrites. Say that anything available in the registry must be installed, not recreated.
• Ask for a check at the end: light and dark themes, a narrow width, and the keyboard path.

Build a settings page for workspace members with Arc. 1. Use the Arc MCP server to search for components for a profile   form, notification switches, and a destructive "remove member"   action. Read each component before you use it.2. Install what you pick with the shadcn CLI (@uiarc namespace).   Do not write your own version of anything Arc already has.3. Use only documented props and the semantic color tokens.4. When you are done, list the components you used and check the   page in light and dark themes and at 375 px wide.

Review what the agent wrote

Installed components are tested code, but the agent still writes the glue. Read the diff with these questions in mind:

• Did it install from the registry, or quietly write its own version of something that exists?
• Are the props it passes in the component’s documentation, and are required ones set?
• Does it use semantic tokens like --foreground and --border instead of raw colors that break in dark mode?
• Does every control that looks clickable do something, with a visible result?
• Can you reach and use everything with the keyboard, and does it still make sense with reduced motion?
• Did it change installed component source? That is fine when intended, but it should be a decision, not a side effect.

Then open the page. Agents are good at code that compiles and weaker at spacing, empty states and long names. Those are faster to spot than to describe in a prompt.