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

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 file at 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. 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 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:

pnpm dlx shadcn@latest add dropdown-menu

This writes the new component file into app/components/ui/ and updates components.json with the registry entry. The generated file at 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:

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:

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

Example implementation following Agent-Native conventions:

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):

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

Components can then reference these values via standard utilities like bg-primary or text-primary. The 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:

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, using the cn utility from 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.
• Follow the design rules in .agents/skills/shadcn-ui/SKILL.md: preserve Radix animations, use the cn function from 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). The 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}