Learn how to install and use adn-ui components via the shadcn CLI registry system.

Installing adn-ui Components

adn-ui is built as a custom shadcn registry. Instead of installing a heavy NPM package dependency, you copy components directly into your codebase using the official shadcn CLI.

🚀 Quick Start

You can install adn-ui components in three simple ways:

Configure the @adn-ui namespace once in your project, then install any component by name.

Initialize `shadcn` in your project

If you haven't already initialized shadcn in your project, run:

npx shadcn@latest init

Add `@adn-ui` to `components.json`

Open your project's components.json file and add the @adn-ui registry mapping under registries:

components.json

{
  "registries": {
    "@adn-ui": "https://ui.awaiden.com/r/{name}.json"
  }
}

Add components to your project

Now you can add any adn-ui component using the namespace alias:

npx shadcn@latest add @adn-ui/button

🛠️ How the Registry Works

The shadcn registry architecture operates as a decentralized distribution system (see shadcn registry docs):

Manifest Fetching: When you run npx shadcn@latest add @adn-ui/button, the CLI fetches the JSON item manifest from https://ui.awaiden.com/r/button.json.
Dependency Resolution: The CLI inspects the manifest's dependencies (such as @base-ui/react, tailwind-variants, tailwind-merge) and installs them into your package.json.
File Placement: The CLI places component files (.tsx, .variants.ts, .css, .context.ts) directly into your project's src/components/ui/button/ directory.
Full Ownership: You own the code! Modify, theme, or extend component variants directly in your repository.

⚙️ Project Setup for Tailwind CSS v4 Component CSS Files

adn-ui uses modular .css files per component (e.g., card.css, button.css) which utilize @apply directives. In Tailwind CSS v4, standalone CSS files with @apply rules require an explicit @reference to your main CSS file.

Preventing @apply / unknown directive Errors

Without auto-reference plugins, PostCSS will throw runtime or build errors such as: Unknown directive @apply ... (did you forget @reference?) Configure auto-referencing in your build setup so PostCSS resolves utility classes automatically:

Configure postcss-tw-auto-reference in your postcss.config.mjs:

postcss.config.mjs

const config = {
  plugins: {
    "postcss-tw-auto-reference": {
      globalCssPath: "app/globals.css", // or "src/app/global.css"
    },
    "@tailwindcss/postcss": {},
  },
};

export default config;

Useful CLI Commands

Here are essential commands for managing your components:

Command	Description
`npx shadcn@latest add @adn-ui/button`	Installs the specified component and its required npm dependencies.
`npx shadcn@latest add @adn-ui/card @adn-ui/dialog`	Installs multiple components in a single command.
`npx shadcn@latest view @adn-ui/button`	Inspects a component's JSON manifest and file list before adding.
`npx shadcn@latest add --overwrite @adn-ui/button`	Overwrites existing component files in your project with the latest version.

Example Usage in Code

Once installed, import and use the component compound objects or named exports in your application:

src/app/page.tsx

import { Button } from "@/components/ui/button";
import { CardRoot, CardHeader, CardTitle, CardContent } from "@/components/ui/card";

export default function ExamplePage() {
  return (
    <CardRoot className="max-w-md mx-auto my-8">
      <CardHeader>
        <CardTitle>Welcome to adn-ui</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <p className="text-muted-foreground">
          Accessible Base UI primitives styled with Tailwind CSS v4 OKLCH tokens.
        </p>
        <Button variant="primary" size="md">
          Get Started
        </Button>
      </CardContent>
    </CardRoot>
  );
}

🤖 AI-Friendly JSDoc & MCP Server Integration

All adn-ui components include JSDoc @see annotations linking directly to raw markdown documentation URLs (powered by the /llms.mdx/docs/... route):

/**
 * @see https://ui.awaiden.com/llms.mdx/docs/components/button/content.md
 */
export const Button = ...

When using AI coding assistants (such as Antigravity, Cursor, Claude Code, or GitHub Copilot), the AI model reads the JSDoc @see link on hover or definition inspection to fetch component specifications.

🔌 Model Context Protocol (MCP) Server

adn-ui includes a built-in Model Context Protocol (MCP) server endpoint that allows AI tools to query, search, inspect code, and install components automatically.

SSE Endpoint: https://ui.awaiden.com/api/mcp/sse

For detailed setup instructions for Cursor, Claude Code, and Antigravity, refer to the MCP Server Integration Guide.

❓ Frequently Asked Questions

Do I need to install an adn-ui npm package?

No package installation is required! adn-ui components are copy-and-paste primitives installed straight into your codebase so you have 100% control over design and implementation.

How do I connect AI tools to adn-ui via MCP?

Add https://ui.awaiden.com/api/mcp/sse to your editor's MCP server settings (Cursor, Claude Desktop, Antigravity). Check out the MCP Integration Guide for client configs.

What if I get 'Unknown registry @adn-ui'?

Ensure "registries": { "@adn-ui": "https://ui.awaiden.com/r/{name}.json" } is included in your components.json file.

What if I get 'Unknown directive @apply' or 'did you forget @reference?'

This happens because Tailwind v4 needs to know where global theme definitions are located when compiling standalone component .css files. See the PostCSS / Vite setup section above to configure postcss-tw-auto-reference or vite-plugin-tw-auto-reference.

Usage Guide