shadcn/ui: Copy-Paste Components as an Architecture

Every few years a component library ships a major version, and every team that depended on it inherits the same afternoon: reading a changelog, rewriting theme overrides, and discovering that the button they never touched now renders two pixels off. That is the cost of installing someone else's design decisions as a dependency.

shadcn/ui takes a different position. Instead of shipping a package you import, it hands you the actual source of each component and lets a CLI copy that source into your own repository. The result is not a smaller library, it is a different architecture entirely, one built on Radix UI primitives for behavior and Tailwind CSS tokens for theming, and it changes how a design system scales as a codebase grows.

Not a Component Library, a Distribution Model

The shadcn/ui documentation states its position plainly: it is not a component library, it is how you build your own component library. Running the CLI's add command does not add an entry to package.json that resolves to a compiled bundle. It writes a plain TypeScript file into your components folder, fully readable, fully yours, with no version to track and no black box to fight when a design requirement does not match the library's assumptions.

Traditional libraries like Material UI or Ant Design solve a different problem: consistent behavior across thousands of consumers, achieved through prop APIs and theme objects that must stay backward compatible. That backward compatibility constraint is exactly why upgrades hurt. shadcn/ui sidesteps the constraint by never promising compatibility in the first place, because after the copy step there is no shared package left to be compatible with.

• Open code: components land as ordinary source files under components/ui, so any editor, linter, or code review tool treats them like the rest of your codebase instead of like opaque node_modules output.
• No version to fight: the code is frozen at the moment you copy it. A future shadcn/ui release cannot silently change how your button renders, because your button is no longer shadcn/ui's button.
• Composition first: every primitive shares predictable conventions, an asChild prop for polymorphism and class-variance-authority for variants, so once a team learns one component the rest read the same way.

Built on Radix Primitives for Accessibility

Interaction logic is the hardest part of a component to get right, not the visual styling. Radix UI Primitives supply that logic as unstyled, accessible building blocks that follow WAI-ARIA authoring patterns, handling keyboard navigation, focus trapping inside dialogs, and correct roles for screen readers. shadcn/ui wraps each Radix primitive in Tailwind utility classes, so the accessibility work is inherited rather than reimplemented, while the visual layer stays fully editable.

The button below shows the pattern in miniature. It is not wired to a Radix primitive directly, but it demonstrates the two pieces every shadcn/ui component leans on: Slot from Radix, which lets the component render as a different underlying element without an extra wrapper node, and class-variance-authority, which turns variant props into a typed lookup of Tailwind class strings instead of a pile of conditional expressions.

// components/ui/button.tsx (installed via CLI, then edited freely)
import { Slot } from "@radix-ui/react-slot"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        outline: "border border-input bg-background hover:bg-accent",
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 px-3",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
)

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean
}

function Button({ className, variant, size, asChild = false, ...props }: ButtonProps) {
  const Comp = asChild ? Slot : "button"
  return (
    <Comp className={cn(buttonVariants({ variant, size, className }))} {...props} />
  )
}

export { Button, buttonVariants }

Because this file lives in your repository, adding a new variant, say a destructive-outline combination the original design never shipped, is a local edit and a pull request, not a feature request against someone else's roadmap. The same applies to removing dependencies you do not want: strip out class-variance-authority and hardcode the class strings if a team prefers fewer moving pieces.

Theming With CSS Variables and Design Tokens

shadcn/ui components never hardcode a hex color. Every visual property routes through a small set of CSS variables, background, foreground, primary, primary foreground, and a handful more, expressed as HSL triples so they can be referenced inside a Tailwind color function. Tailwind's config then maps a class like bg-primary to hsl(var(--primary)), which means the same class name resolves to different pixels depending on which variables are active.

/* app/globals.css — tokens consumed by every shadcn/ui component */
:root {
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
  --primary: 240 5.9% 10%;
  --primary-foreground: 0 0% 98%;
  --radius: 0.5rem;
}

.dark {
  --background: 240 10% 3.9%;
  --foreground: 0 0% 98%;
  --primary: 0 0% 98%;
  --primary-foreground: 240 5.9% 10%;
}

That single indirection layer is what makes rebranding tractable at scale. Changing a product's accent color means editing one CSS variable once, not searching every component file for a stray hex code. Dark mode works the same way: toggling a dark class on the html element swaps the active variable set, and every component that already reads var(--background) picks up the new palette with zero component-level code changes.

What You Actually Trade Off

The honest comparison against a traditional dependency model is not library versus no library, it is who carries the maintenance cost and where the bundle weight goes. The table below lines up the three dimensions that matter most in practice.

The tradeoff is that maintenance responsibility moves from the library maintainer to your own team. A security-relevant fix in Radix still arrives through your package manager, but a fix to shadcn/ui's own wrapper code has to be applied by hand, file by file, across however many components you copied it into. That is a reasonable price for a team with code review discipline and a design system owner, and a real risk for a solo project with neither.

A Practical Workflow for Scaling a Design System

Copy-paste ownership only stays manageable if a team treats the copied code with the same discipline as any other internal library. A few habits keep it from turning into unmanaged drift across dozens of components.

1. Install each primitive once through the CLI into components/ui and treat that folder as generated scaffolding, the same mental model as a codegen output you are allowed to hand-edit but do not casually reformat.
2. Wrap installed primitives in a separate application-level layer for product-specific props and copy, so a one-off marketing page requirement never forces an edit to the shared primitive that every other screen also renders.
3. Keep every design token in a single CSS file and document what each variable name means, so a new component always composes from the same palette instead of introducing a slightly different shade of the same color.
4. Add a code review checklist item, or a lightweight lint rule, that flags direct edits inside components/ui, so a change to shared primitives is always a deliberate decision made by someone accountable for the design system, not an accidental side effect of a feature branch.

When Copy-Paste Ownership Is, and Isn't, the Right Call

This architecture is a genuine tradeoff, not a strictly better option, and it fits some situations far better than others.

• Good fit: product teams that expect deep, ongoing visual customization and already have a design system owner reviewing component changes.
• Good fit: organizations shipping several similar applications that can share one internal component registry instead of duplicating effort per repo.
• Poor fit: teams that need a security or accessibility fix to propagate to every consuming application the moment it ships upstream, since a dependency-based library delivers that through a simple version bump while copied code needs a manual pass per repository.

In practice, most product teams land somewhere in between: they copy shadcn/ui's primitives for full control over the visual layer, while still pulling Radix UI itself as a real npm dependency for the accessibility-critical interaction logic underneath. Ownership where customization matters, dependency where correctness matters.