shadcn-core-stack

name	shadcn-core-stack
description	Use when reading or writing any shadcn ui component, especially when figuring out which library owns which concern (a11y, variants, class composition, icons), when a prop or class string is not behaving as expected, when picking between raw Radix and the shadcn-wrapped component, when adding tailwind-merge or cva to an existing project, when an LLM is asked to "rebuild a shadcn-style component" and needs to know the exact runtime layers, and when migrating from Tailwind v3 to v4 inside a shadcn project. Prevents the common mistakes of (a) concatenating className strings without `cn()`, causing duplicate utility classes to leak through, (b) bypassing the shadcn-copied component to import Radix primitives directly, losing the project's styling, (c) defining `cva` variants in the wrong order so that `compoundVariants` never trigger, (d) installing wrong package versions (radix-ui unified vs @radix-ui/react-* legacy, cva 1.0 beta vs 0.7 stable, tailwind-merge v2 for Tailwind v3 vs v3 for Tailwind v4), and (e) treating shadcn ui as a runtime dependency when it is a code-generation CLI. Covers the complete runtime stack composition (Radix UI for headless primitives, class-variance-authority for type-safe variants, tailwind-merge for class conflict resolution, clsx for conditional composition, Tailwind CSS v3.4 or v4 for styling, lucide-react for icons), the canonical `cn()` helper, the cva variant signature with TypeScript inference via `VariantProps`, what each layer owns and where it lives in the consumer project, the ownership-model implications (open code, no runtime shadcn import), and the per-component Radix-primitive mapping for the 39 Radix-backed components in the catalog. Keywords: shadcn stack, cva, class-variance-authority, tailwind-merge, twMerge, clsx, cn helper, lib/utils, Radix UI primitives, radix-ui unified package, lucide-react, class composition, why className not applied, duplicate classes Tailwind, variant ordering, compoundVariants not firing, shadcn under the hood, runtime dependencies, ownership model, open code, how does shadcn work, what is cva, how do I merge tailwind classes, shadcn vs radix, why does my override not work, p-3 px-2 conflict.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui Core: Stack Composition

shadcn ui is not a runtime component library : it is a CLI that copies TypeScript source files into your project. Once shadcn add button finishes, your project owns components/ui/button.tsx outright, and the only things that remain at runtime are the underlying primitives (Radix, cva, tailwind-merge, clsx, lucide-react, Tailwind). Understanding this stack is the foundation for every other shadcn skill.

Quick Reference

Stack layers (every shadcn project has these)

Layer : owns : package : runtime cost
Headless behaviour + a11y : focus-trap, ARIA, keyboard, RTL, controlled state : radix-ui (unified, Feb 2026) or @radix-ui/react-* (legacy per-component) : small (component-scoped, tree-shaken)
Variant API : type-safe variant + size composition : class-variance-authority (cva) : tiny (~1 KB gzipped)
Class conflict resolution : twMerge('px-2 p-3') returns p-3, dropping px-2 : tailwind-merge v3.x (Tailwind v4) or v2.x (Tailwind v3) : ~6 KB gzipped, cached per call site
Conditional class composition : clsx('a', cond && 'b', { c: enabled }) : clsx : ~250 bytes
Utility CSS : every visible style : tailwindcss v3.4 or v4.0+ : build-time
Icons : default icon set : lucide-react : tree-shaken per icon

Top-3 most-used patterns

// 1. The cn() helper : single merge primitive used by every shadcn component.
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"
export function cn(...inputs: ClassValue[]) { return ((inputs)) }


 { cva,   }  
 { cn }  

 buttonVariants = (
  ,
  {
    : {
      : {
        : ,
        : ,
        : ,
      },
      : {
        : ,
        : ,
        : ,
        : ,
      },
    },
    : { : , :  },
  }
)

  
   .<>,
    <typeof buttonVariants> { ?:  }

  () {
   
}



 *     
 { cn }  

   = .
   = .

   = .<
  .< .>,
  .< .>
>( (
  
))