shadcn/ui는 npm 패키지를 설치하는 방식이 아닌가요?

소스(컴포넌트 코드)를 프로젝트에 복사해 두는 방식이 기본이어서, Radix+Tailwind 기반으로 팀이 직접 수정·스타일을 조정하기 쉽습니다. CLI로 추가한 파일은 components/ui 등에 둡니다.

기존 디자인 시스템 색/폰트를 맞출 때는?

tailwind.config·CSS 변수(테마)와 shadcn의 components.json 경로·스타일 옵션을 맞추고, 생성된 컴포넌트의 className을 토큰에 맞게 조정합니다. globals.css에 프리미티브를 정의해 두는 패턴이 흔합니다.

다크 모드/테마 전환은 어떻게 연동하나요?

next-themes 등과 토글 상태를 맞추고, dark 클래스 또는 data 속성 기준으로 Tailwind dark: 변형이 적용되게 설정합니다. HTML 루트에 클래스를 붙이는 방식이 일반적입니다.

접근성·키보드 포커스는 shadcn이 알아서 해주나요?

Radix 프리밋이 포커스 트랩·ARIA 등을 많이 처리하지만, 커스텀 후엔 키보드 동작과 라벨을 직접 점검해야 합니다. Storybook/axe로 점검하는 것을 권장합니다.

shadcn/ui 완벽 가이드 | Radix UI·Tailwind·복사 가능한 컴포넌트·커스터마이징

2026년 4월 7일 · 4분 읽기 · 수정 2026년 4월 7일 초급

이 글의 핵심

shadcn/ui로 아름다운 UI를 빠르게 구축하는 완벽 가이드. 설치, 컴포넌트 추가, 커스터마이징, 테마, 다크모드까지 실전 예제로 정리. shadcn/ui·Radix UI·Tailwind CSS 중심으로 설명합니다.

이 글의 핵심

shadcn/ui로 아름다운 UI를 빠르게 구축하는 완벽 가이드입니다. 설치부터 컴포넌트 추가, 커스터마이징, 테마, 다크모드까지 실전 예제로 정리했습니다.

실무 경험 공유: 관리자 대시보드를 shadcn/ui로 구축하면서, UI 개발 시간을 70% 단축하고 일관된 디자인 시스템을 확립한 경험을 공유합니다.

들어가며: “UI 라이브러리가 불편해요”

실무 문제 시나리오

시나리오 1: 커스터마이징이 어려워요

Material-UI는 스타일 오버라이드가 복잡합니다. shadcn/ui는 코드를 직접 수정합니다. 시나리오 2: 번들이 너무 커요

전체 라이브러리를 설치해야 합니다. shadcn/ui는 필요한 컴포넌트만 복사합니다. 시나리오 3: 디자인이 획일적이에요

모든 사이트가 비슷해 보입니다. shadcn/ui는 완전히 커스터마이징 가능합니다.

1. shadcn/ui란?

핵심 특징

shadcn/ui는 복사 가능한 컴포넌트 컬렉션입니다. 주요 장점:

복사 가능: npm 패키지가 아닌 코드 복사
완전한 제어: 모든 코드를 직접 수정 가능
Radix UI 기반: 접근성 완벽 지원
Tailwind CSS: 유틸리티 우선 스타일링
TypeScript: 완벽한 타입 지원

2. 설치 및 설정

Next.js 프로젝트 생성

npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app

shadcn/ui 초기화

npx shadcn-ui@latest init

설정 옵션

✔ Which style would you like to use? › Default
✔ Which color would you like to use as base color? › Slate
✔ Would you like to use CSS variables for colors? › yes

생성된 파일

my-app/
├── components/
│   └── ui/           # 컴포넌트가 여기에 추가됨
├── lib/
│   └── utils.ts      # 유틸리티 함수
├── tailwind.config.ts
└── components.json   # shadcn/ui 설정

3. 컴포넌트 추가

단일 컴포넌트

npx shadcn-ui@latest add button

여러 컴포넌트

npx shadcn-ui@latest add button card input label

모든 컴포넌트

npx shadcn-ui@latest add --all

4. 기본 컴포넌트 사용

Button

import { Button } from '@/components/ui/button';
export default function Page() {
  return (
    <div className="space-x-2">
      <Button>Default</Button>
      <Button variant="destructive">Destructive</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="link">Link</Button>
    </div>
  );
}

Input

import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
export default function Page() {
  return (
    <div className="space-y-2">
      <Label htmlFor="email">Email</Label>
      <Input id="email" type="email" placeholder="Email" />
    </div>
  );
}

Card

import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import { Button } from '@/components/ui/button';
export default function Page() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Card Title</CardTitle>
        <CardDescription>Card Description</CardDescription>
      </CardHeader>
      <CardContent>
        <p>Card Content</p>
      </CardContent>
      <CardFooter>
        <Button>Footer button</Button>
      </CardFooter>
    </Card>
  );
}

5. Form 구축

설치

npm install react-hook-form @hookform/resolvers zod
npx shadcn-ui@latest add form

Form 예제

'use client';
import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import * as z from 'zod';
import { Button } from '@/components/ui/button';
import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form';
import { Input } from '@/components/ui/input';
const formSchema = z.object({
  username: z.string().min(2, {
    message: 'Username must be at least 2 characters.',
  }),
  email: z.string().email({
    message: 'Please enter a valid email address.',
  }),
});
export function ProfileForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      username: ',
      email: ',
    },
  });
  function onSubmit(values: z.infer<typeof formSchema>) {
    console.log(values);
  }
  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-8">
        <FormField
          control={form.control}
          name="username"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Username</FormLabel>
              <FormControl>
                <Input placeholder="johndoe" {...field} />
              </FormControl>
              <FormDescription>
                This is your public display name.
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
        
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl>
                <Input placeholder="[email protected]" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  );
}

6. 다크모드

설치

npm install next-themes

Provider 설정

// app/providers.tsx
'use client';
import { ThemeProvider } from 'next-themes';
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      {children}
    </ThemeProvider>
  );
}

// app/layout.tsx
// 필요한 모듈 import
import { Providers } from './providers';
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

테마 토글

'use client';
import { Moon, Sun } from 'lucide-react';
import { useTheme } from 'next-themes';
import { Button } from '@/components/ui/button';
export function ThemeToggle() {
  const { theme, setTheme } = useTheme();
  return (
    <Button
      variant="ghost"
      size="icon"
      onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}
    >
      <Sun className="h-5 w-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
      <Moon className="absolute h-5 w-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
      <span className="sr-only">Toggle theme</span>
    </Button>
  );
}

7. 커스터마이징

색상 변경

/* app/globals.css */
@layer base {
  :root {
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
  }
  .dark {
    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 11.2%;
  }
}

컴포넌트 수정

// components/ui/button.tsx
// 이 파일을 직접 수정할 수 있습니다!
const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        // 새로운 variant 추가
        success: 'bg-green-500 text-white hover:bg-green-600',
      },
    },
  }
);

8. 실전 예제: 대시보드

// app/dashboard/page.tsx
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import {
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from '@/components/ui/table';
export default function Dashboard() {
  return (
    <div className="container mx-auto p-6 space-y-6">
      <div className="flex justify-between items-center">
        <h1 className="text-3xl font-bold">Dashboard</h1>
        <Button>Add New</Button>
      </div>
      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-4">
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">
              Total Revenue
            </CardTitle>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">$45,231.89</div>
            <p className="text-xs text-muted-foreground">
              +20.1% from last month
            </p>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">
              Subscriptions
            </CardTitle>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">+2350</div>
            <p className="text-xs text-muted-foreground">
              +180.1% from last month
            </p>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">Sales</CardTitle>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">+12,234</div>
            <p className="text-xs text-muted-foreground">
              +19% from last month
            </p>
          </CardContent>
        </Card>
        <Card>
          <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
            <CardTitle className="text-sm font-medium">
              Active Now
            </CardTitle>
          </CardHeader>
          <CardContent>
            <div className="text-2xl font-bold">+573</div>
            <p className="text-xs text-muted-foreground">
              +201 since last hour
            </p>
          </CardContent>
        </Card>
      </div>
      <Card>
        <CardHeader>
          <CardTitle>Recent Sales</CardTitle>
          <CardDescription>
            You made 265 sales this month.
          </CardDescription>
        </CardHeader>
        <CardContent>
          <Table>
            <TableHeader>
              <TableRow>
                <TableHead>Customer</TableHead>
                <TableHead>Email</TableHead>
                <TableHead>Amount</TableHead>
              </TableRow>
            </TableHeader>
            <TableBody>
              <TableRow>
                <TableCell>John Doe</TableCell>
                <TableCell>[email protected]</TableCell>
                <TableCell>$250.00</TableCell>
              </TableRow>
              <TableRow>
                <TableCell>Jane Smith</TableCell>
                <TableCell>[email protected]</TableCell>
                <TableCell>$150.00</TableCell>
              </TableRow>
            </TableBody>
          </Table>
        </CardContent>
      </Card>
    </div>
  );
}

9. 고급 컴포넌트

Dialog

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@/components/ui/dialog';
import { Button } from '@/components/ui/button';
export function DialogDemo() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>Open Dialog</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Are you sure?</DialogTitle>
          <DialogDescription>
            This action cannot be undone.
          </DialogDescription>
        </DialogHeader>
      </DialogContent>
    </Dialog>
  );
}

import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from '@/components/ui/dropdown-menu';
import { Button } from '@/components/ui/button';
export function DropdownMenuDemo() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <Button variant="outline">Open</Button>
      </DropdownMenuTrigger>
      <DropdownMenuContent>
        <DropdownMenuLabel>My Account</DropdownMenuLabel>
        <DropdownMenuSeparator />
        <DropdownMenuItem>Profile</DropdownMenuItem>
        <DropdownMenuItem>Settings</DropdownMenuItem>
        <DropdownMenuItem>Logout</DropdownMenuItem>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

정리 및 체크리스트

핵심 요약

shadcn/ui: 복사 가능한 컴포넌트 컬렉션
완전한 제어: 모든 코드를 직접 수정 가능
Radix UI: 접근성 완벽 지원
Tailwind CSS: 유틸리티 우선 스타일링
다크모드: 내장 지원

구현 체크리스트

같이 보면 좋은 글

Tailwind CSS 완벽 가이드
React 18 심화 가이드
Next.js 15 완벽 가이드

이 글에서 다루는 키워드

shadcn/ui, Radix UI, Tailwind CSS, React, UI Components, Design System

자주 묻는 질문 (FAQ)

Q. shadcn/ui vs Material-UI, 어떤 게 나은가요?

A. shadcn/ui는 더 가볍고 커스터마이징이 쉽습니다. Material-UI는 더 많은 컴포넌트를 제공하지만 무겁습니다.

Q. 왜 npm 패키지가 아닌가요?

A. 코드를 직접 소유하고 수정할 수 있게 하기 위함입니다. 의존성 지옥을 피할 수 있습니다.

Q. 접근성은 어떤가요?

A. Radix UI 기반이므로 접근성이 완벽합니다. ARIA 속성, 키보드 네비게이션 등을 모두 지원합니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, 많은 기업에서 프로덕션 환경에서 사용하고 있습니다. Vercel도 사용합니다.

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「shadcn/ui 완벽 가이드 | Radix UI·Tailwind·복사 가능한 컴포넌트·커스터마이징」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「shadcn/ui 완벽 가이드 | Radix UI·Tailwind·복사 가능한 컴포넌트·커스터마이징」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

이 글의 핵심

이 글의 핵심

들어가며: “UI 라이브러리가 불편해요”

실무 문제 시나리오

모든 사이트가 비슷해 보입니다. shadcn/ui는 완전히 커스터마이징 가능합니다.

1. shadcn/ui란?

핵심 특징

2. 설치 및 설정

Next.js 프로젝트 생성

shadcn/ui 초기화

설정 옵션

생성된 파일

3. 컴포넌트 추가

단일 컴포넌트

여러 컴포넌트

모든 컴포넌트

4. 기본 컴포넌트 사용

Button

Input

Card

5. Form 구축

설치

Form 예제

6. 다크모드

설치

Provider 설정

테마 토글

7. 커스터마이징

색상 변경

컴포넌트 수정

8. 실전 예제: 대시보드

9. 고급 컴포넌트

Dialog

Dropdown Menu

정리 및 체크리스트

핵심 요약

구현 체크리스트

같이 보면 좋은 글

이 글에서 다루는 키워드

자주 묻는 질문 (FAQ)

Q. shadcn/ui vs Material-UI, 어떤 게 나은가요?

Q. 왜 npm 패키지가 아닌가요?

Q. 접근성은 어떤가요?

Q. 프로덕션에서 사용해도 되나요?

심화 부록: 구현·운영 관점

내부 동작과 핵심 메커니즘

프로덕션 운영 패턴

확장 예시: 엔드투엔드 미니 시나리오

문제 해결(Troubleshooting)

이 글이 도움이 되셨나요?