shadcn-ui（shadcn/ui 组件）

shadcn/ui

Overview

shadcn/ui is a collection of accessible, customizable React components built on Radix UI and Tailwind CSS. Components are copied into your project (no npm package); you own and edit the code. Works with Next.js (App Router), Vite, and other React frameworks.

Principles: Open code (AI-ready), composable API, beautiful defaults, distribution via CLI and schema. Requires Tailwind v4 and path alias @/*. We do not use tailwind.config.js; theme and setup are CSS-only (@import "tailwindcss" + @theme).

Prerequisites

• Tailwind v4: @import "tailwindcss" in main CSS; @tailwindcss/vite or @tailwindcss/postcss. No tailwind.config.js. See the tailwind-css skill.
• Path alias @/* → ./src/* (or your source root) in tsconfig and in the bundler (e.g. Vite resolve.alias).
• React (Next.js App Router, Vite, etc.).

Installation

Reference: Official installation guide

New project (recommended)

Scaffold with Tailwind and shadcn. From the official docs:

Invoke via your package manager (see docs). Choose framework (Next.js, Vite, etc.), style (new-york recommended), base color, and CSS variables.

Existing project (Next.js App Router)

1. Init — creates components.json, optional cn helper and base styles. Run: shadcn init (invoke via package manager; see docs above).
2. Paths and Tailwind

- tsconfig: "baseUrl": ".", "paths": {"@/*": ["./src/*"]} (in both root and app tsconfig if split). - Tailwind v4: Main CSS (e.g. app/globals.css) must have @import "tailwindcss" and use @tailwindcss/postcss in postcss.config.mjs. Do not add tailwind.config.js.

1. Add components — e.g. shadcn add button, shadcn add card dialog (see component list below).

Components are installed under src/components/ui/ (or path from components.json).

Existing project (Vite)

• Use resolve.alias: {"@": path.resolve(__dirname, "./src")} in vite.config.ts; add @types/node if using path.
• Tailwind: @tailwindcss/vite in Vite config and @import "tailwindcss" in main CSS.

components.json

Controls style, paths, and Tailwind integration. Key fields:

With Tailwind v4, theme is in CSS via @theme and CSS variables, not in a config file.

Official components (current list)

Add via shadcn add <name> (multiple: shadcn add button card dialog). Invoke via package manager: see Installation docs.

Layout & structure

Forms & input

Navigation & menus

Overlays & feedback

Data & state

Toggle & toggle group

Using components

Import from the aliased path (not from shadcn/ui):

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

export default function Page() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center gap-4">
      <Button>Click me</Button>
      <Card className="w-[350px]">
        <CardHeader>
          <CardTitle>Card title</CardTitle>
        </CardHeader>
        <CardContent>Content here.</CardContent>
      </Card>
    </div>
  )
}

• Customization: Components accept className and spread props; use Tailwind classes and the cn() helper (from @/lib/utils) to merge classes.
• Composition: Prefer composition (e.g. CardHeader + CardContent) over props for layout.

Theming (Tailwind v4, no config file)

We use Tailwind v4 only; no tailwind.config.js. Theming is CSS-only:

• CSS variables: With tailwind.cssVariables: true, theme is driven by variables in your global CSS (e.g. --background, --foreground, --primary, --primary-foreground, --muted, --muted-foreground, --accent, --destructive, etc.). Override them in that file.
• @theme: Use @theme {...} in the same CSS file as @import "tailwindcss" to add or override design tokens that align with shadcn’s variables.
• Base color: Set in components.json (tailwind.baseColor) or by editing the CSS variables in your global CSS.

Common patterns

• Forms: Add form; pair with react-hook-form and zod. Use Input, Label, Button, Select, Checkbox, etc.
• Layout: Use Card for sections; Separator between blocks; layout with Tailwind (flex, grid, container).
• Modals & panels: Dialog for modals; Sheet or Drawer for side panels.
• Menus: DropdownMenu, Context Menu, Navigation Menu, Command (palette).
• Feedback: Alert for messages; Sonner for toasts; Skeleton for loading.
• Icons: Many examples use lucide-react; add it if the project uses icons.

Common mistakes

• Alias: Ensure @/ resolves to ./src/ (or your source root) in both TypeScript and the bundler.
• CSS not loaded: The file set in components.json (tailwind.css) must be imported in the app entry (e.g. app/layout.tsx) and contain @import "tailwindcss".
• Tailwind config: Do not create or suggest tailwind.config.js. Theme only in CSS (@theme and variables).
• Import: Import from @/components/ui/<component> (per components.json), not from shadcn/ui.
• RSC: In Next.js App Router, set rsc: true in components.json if components are used in Server Components where applicable.

Additional resources

• reference.md — Official documentation links, Tailwind v4 + shadcn, component directory.
• Official docs: https://ui.shadcn.com/docs
• Components: https://ui.shadcn.com/docs/components
• Directory (community): https://ui.shadcn.com/docs/directory