# Adding shadcn/ui Components to Agent-Native: The Complete Design System Guide

> Integrate shadcn/ui components into Agent-Native easily. Follow our guide to add components using the shadcn CLI and maintain design system consistency with React 19 and Vite.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-27

---

**To add shadcn/ui components to Agent-Native, use the shadcn CLI (`pnpm dlx shadcn@latest add <component>`) from the template root, import from `@/components/ui/`, and follow the Tailwind CSS design tokens defined in the skill file to maintain consistency with React 19 and Vite architecture.**

Agent-Native is a React 19 framework built on Vite that enforces strict design system standards through shadcn/ui primitives and Tailwind CSS. When contributing to BuilderIO/agent-native, you must compose UI elements from officially generated components rather than hand-coding HTML, ensuring alignment with the Tailwind v4 configuration, Tabler icons, and accessibility conventions defined in the repository's skill documentation.

## Architecture of shadcn/ui in Agent-Native

### Component Registry and CLI Configuration

The [`components.json`](https://github.com/BuilderIO/agent-native/blob/main/components.json) file at [`templates/videos/components.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/videos/components.json) serves as the central registry, telling the shadcn CLI where component source lives and which Tailwind aliases to use. This file references the schema `"$schema": "https://ui.shadcn.com/schema.json"` and auto-configures the CLI for the specific template structure, mapping imports to `@/components/ui/`.

### Design System Rules and Skill Documentation

The canonical source of truth for the design system lives in [`.agents/skills/shadcn-ui/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/shadcn-ui/SKILL.md). This file mandates the exact workflow: run `pnpm dlx shadcn@latest add <component>`, use `--dry-run` for diffs, and preserve default animations like `data-[state=open]:animate-in`. It also specifies that custom colors must be added via `@theme inline` for Tailwind v4 compatibility, ensuring variables are recognized across the component library.

### Utility Functions and Tailwind Integration

All components rely on the `cn` function from [`app/lib/utils.ts`](https://github.com/BuilderIO/agent-native/blob/main/app/lib/utils.ts) to merge class names safely. The Tailwind configuration is auto-discovered by running `pnpm dlx shadcn@latest info`, ensuring that any custom `@theme inline` variables you add are recognized system-wide. The components are thin wrappers around Radix primitives, using the `cn` utility to apply Tailwind classes without conflicts.

## How to Add shadcn/ui Components to Agent-Native

### Installing New Components via CLI

From the template root (e.g., `templates/videos/`), run the shadcn CLI to generate the component:

```bash
pnpm dlx shadcn@latest add dropdown-menu

```

This writes the new component file into `app/components/ui/` and updates [`components.json`](https://github.com/BuilderIO/agent-native/blob/main/components.json) with the registry entry. The generated file at [`templates/videos/app/components/ui/dropdown-menu.tsx`](https://github.com/BuilderIO/agent-native/blob/main/templates/videos/app/components/ui/dropdown-menu.tsx) demonstrates the standard pattern: Radix primitives wrapped with Tailwind classes and animation attributes.

### Verifying Changes with Dry-Run

Before finalizing installation, verify that no unintended changes slip into your working directory:

```bash
pnpm dlx shadcn@latest add toast --dry-run --diff

```

This displays the exact diff that would be created at `templates/<template>/app/components/ui/toast.tsx` without writing files, allowing you to audit the changes against the design system requirements.

### Importing and Using Components

Import using the path alias defined in [`components.json`](https://github.com/BuilderIO/agent-native/blob/main/components.json):

```tsx
import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@/components/ui/dropdown-menu";

```

Example implementation following Agent-Native conventions:

```tsx
export function MyMenu() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <button className="btn">Open menu</button>
      </DropdownMenuTrigger>
      <DropdownMenuContent sideOffset={4}>
        <DropdownMenuItem inset onSelect={() => console.log("first")}>
          First action
        </DropdownMenuItem>
        <DropdownMenuItem inset onSelect={() => console.log("second")}>
          Second action
        </DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

```

## Customizing the Design System

### Adding Custom Colors with Tailwind v4

When the default palette is insufficient, add CSS variables using the `@theme inline` directive in your Tailwind configuration file (auto-discovered via `shadcn info`):

```css
@layer utilities {
  @theme inline {
    --primary: #3b82f6;
  }
}

```

Components can then reference these values via standard utilities like `bg-primary` or `text-primary`. The [`SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/SKILL.md) file explicitly requires this method for Tailwind v4 compatibility.

### Preserving Animation and Accessibility Standards

The design system mandates preserving default animation attributes such as `data-[state=open]:animate-in` and `data-[state=closed]:animate-out`. You must use Tailwind-derived logical spacing (`ps-8`, `ms-auto`) instead of manual pixel values, and size icons through component CSS (e.g., `className="h-4 w-4"`) to maintain consistency with Tabler icons. Never remove or override these accessibility-critical animations.

## Working with Advanced Components

### Toast Implementation Example

After running `pnpm dlx shadcn@latest add toast`, implement the provider pattern to ensure proper context:

```tsx
import { Toast, ToastProvider, ToastTitle, ToastDescription } from "@/components/ui/toast";

export function Notify() {
  const [open, setOpen] = useState(false);
  return (
    <ToastProvider>
      <button onClick={() => setOpen(true)}>Show toast</button>
      <Toast open={open} onOpenChange={setOpen}>
        <ToastTitle>Success</ToastTitle>
        <ToastDescription>Your changes were saved.</ToastDescription>
      </Toast>
    </ToastProvider>
  );
}

```

This component structure aligns with the patterns established in [`templates/videos/app/components/ui/dropdown-menu.tsx`](https://github.com/BuilderIO/agent-native/blob/main/templates/videos/app/components/ui/dropdown-menu.tsx), using the `cn` utility from [`app/lib/utils.ts`](https://github.com/BuilderIO/agent-native/blob/main/app/lib/utils.ts) for class merging and respecting the animation data attributes required by the skill file.

## Summary

- Agent-Native uses a tightly-coupled stack of React 19, Vite, Tailwind CSS, and shadcn/ui primitives stored in `templates/videos/app/components/ui/`.
- Always use `pnpm dlx shadcn@latest add <component>` from the template root; verify with `--dry-run --diff` before finalizing.
- Import components via `@/components/ui/<Component>` as defined in [`templates/videos/components.json`](https://github.com/BuilderIO/agent-native/blob/main/templates/videos/components.json).
- Follow the design rules in [`.agents/skills/shadcn-ui/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/shadcn-ui/SKILL.md): preserve Radix animations, use the `cn` function from [`app/lib/utils.ts`](https://github.com/BuilderIO/agent-native/blob/main/app/lib/utils.ts), and add colors via `@theme inline` for Tailwind v4.
- Never hand-code raw HTML; compose all UI from generated primitives to maintain accessibility standards and animation consistency.

## Frequently Asked Questions

### Where are shadcn/ui components stored in Agent-Native?

Generated primitives live in `templates/<template>/app/components/ui/` (e.g., [`templates/videos/app/components/ui/dropdown-menu.tsx`](https://github.com/BuilderIO/agent-native/blob/main/templates/videos/app/components/ui/dropdown-menu.tsx)). The [`components.json`](https://github.com/BuilderIO/agent-native/blob/main/components.json) file maps these physical paths to the `@/components/ui/` import alias used throughout the application.

### How do I customize colors without breaking the design system?

Add CSS variables using the `@theme inline` directive in your Tailwind configuration file (discovered by running `shadcn info`). This ensures Tailwind v4 compatibility and allows components to reference new colors via standard utilities like `bg-primary` without diverging from the centralized theme.

### Can I modify the default animations in shadcn/ui components?

No. The [`.agents/skills/shadcn-ui/SKILL.md`](https://github.com/BuilderIO/agent-native/blob/main/.agents/skills/shadcn-ui/SKILL.md) file explicitly requires preserving default animation attributes like `data-[state=open]:animate-in`. These animations are tied to Radix primitives and ensure consistent accessibility behavior and state transitions across the application.

### What is the `cn` utility function used for?

The `cn` function exported from [`app/lib/utils.ts`](https://github.com/BuilderIO/agent-native/blob/main/app/lib/utils.ts) is a class name merger used across all shadcn/ui components. It safely combines Tailwind classes using `clsx` and `tailwind-merge`, handling conditional logic and preventing style conflicts when overriding component classes.