Geruyang/agent-skills-library

shadcn/ui

당신은 shadcn/ui의 전문가입니다. shadcn/ui는 Radix UI 프리미티브와 Tailwind CSS 위에 구축된 아름답고 접근 가능하며 사용자 정의가 가능한 React 컴포넌트 모음입니다. 컴포넌트는 종속성으로 설치되지 않고 소스 코드로 코드베이스에 직접 추가됩니다.

핵심 개념

shadcn/ui는 전통적인 의미의 컴포넌트 라이브러리가 아닙니다. 패키지로 설치하는 것이 아닙니다. 대신 CLI가 컴포넌트 소스 코드를 프로젝트에 복사하여 완전한 소유권과 사용자 정의 기능을 제공합니다.

CLI 명령어

초기화 (비대화형 — 항상 사용)

중요: shadcn init은 기본적으로 대화형입니다. 비대화형 초기화를 위해 항상 -d (기본값)를 사용하세요:

# 기본값으로 비대화형 초기화 — 이 방법 사용
npx shadcn@latest init -d

# 프리셋으로 비대화형 초기화 (일관된 디자인 시스템에 권장)
npx shadcn@latest init --preset <code> -f

# 명시적 기본 라이브러리 선택으로 비대화형 초기화
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui

# 전체 프로젝트 템플릿 스캐폴딩 (CLI v4)

AI Elements 호환성: 프로젝트가 AI Elements를 사용하거나 사용할 가능성이 있는 경우 항상 --base radix(기본값)를 사용하세요. AI Elements 컴포넌트는 Radix API에 의존하며 Base UI에서 타입 오류가 발생합니다.

npx shadcn@latest init --template next -d
npx shadcn@latest init --template vite -d

옵션:

• -d, --defaults — 기본 설정을 사용하고 모든 대화형 프롬프트를 건너뜁니다 (CI/에이전트 사용에 필수)
• -y, --yes — 확인 프롬프트 건너뛰기 (라이브러리 선택은 건너뛰지 않음 — 대신 -d 사용)
• -f, --force — 기존 설정 강제 덮어쓰기
• -t, --template — 전체 프로젝트 템플릿 스캐폴딩 (next, vite, react-router, astro, laravel, tanstack-start)
• --preset — 단일 공유 가능 코드로 디자인 시스템 프리셋 (색상, 테마, 아이콘, 글꼴, 반경) 적용
• --base — 기본 라이브러리 선택: radix (기본값) 또는 base-ui
• --monorepo — 모노레포 구조 설정

경고: -y/--yes 만으로는 init이 완전히 비대화형이 되지 않습니다 — 여전히 컴포넌트 라이브러리 선택을 묻습니다. 모든 프롬프트를 건너뛰려면 항상 -d를 사용하세요.

CLI v4에서 더 이상 사용되지 않음: --style, --base-color, --src-dir, --no-base-style, --css-variables 플래그는 제거되었으며 오류가 발생합니다. registry:build 및 registry:mcp 레지스트리 유형도 더 이상 사용되지 않습니다. 대신 registry:base 및 registry:font를 사용하세요.

init 명령어는:

1. 프레임워크 감지 (Next.js, Vite, React Router, Astro, Laravel, TanStack Start)
2. 필수 종속성 설치 (Radix UI, tailwind-merge, class-variance-authority)
3. components.json 설정 파일 생성
4. cn() 유틸리티 함수 설정
5. 테마 설정을 위한 CSS 변수 구성

컴포넌트 추가

# 특정 컴포넌트 추가
npx shadcn@latest add button dialog card

# 모든 사용 가능한 컴포넌트 추가
npx shadcn@latest add --all

# 사용자 정의 레지스트리에서 추가
npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/custom-button

# AI Elements 레지스트리에서 추가
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

옵션:

• -o, --overwrite — 기존 파일 덮어쓰기
• -p, --path — 사용자 정의 설치 경로
• -a, --all — 모든 컴포넌트 설치
• --dry-run — 파일을 쓰지 않고 추가될 내용 미리보기
• --diff — 기존 컴포넌트 업데이트 시 변경 사항 차이점 표시
• --view — 레지스트리 항목의 소스 코드를 인라인으로 표시

검색 및 목록

npx shadcn@latest search button
npx shadcn@latest list @v0

빌드 (사용자 정의 레지스트리)

npx shadcn@latest build
npx shadcn@latest build ./registry.json -o ./public/r

보기, 정보 및 문서 (CLI v4)

# 설치 전 레지스트리 항목의 소스 보기
npx shadcn@latest view button

# 프로젝트 진단 정보 표시 — 설정, 설치된 컴포넌트, 종속성
npx shadcn@latest info

# 모든 컴포넌트에 대한 문서, 코드 및 예제 가져오기 (에이전트 친화적 출력)
npx shadcn@latest docs button
npx shadcn@latest docs dialog

**shadcn docs**는 코딩 에이전트가 프리미티브를 올바르게 사용할 수 있는 컨텍스트를 제공합니다 — 코드 예제, API 참조 및 사용 패턴을 인라인으로 반환합니다.

마이그레이션

npx shadcn@latest migrate rtl    # RTL 지원 마이그레이션
npx shadcn@latest migrate radix  # 통합 radix-ui 패키지로 마이그레이션
npx shadcn@latest migrate icons  # 아이콘 라이브러리 변경 사항

# 기본 ui 디렉토리 외부의 컴포넌트 마이그레이션
npx shadcn@latest migrate radix src/components/custom

shadcn/skills (CLI v4)

shadcn/skills는 코딩 에이전트가 컴포넌트 및 레지스트리로 올바르게 작업하는 데 필요한 컨텍스트를 제공합니다. Radix 및 Base UI 프리미티브, 업데이트된 API, 컴포넌트 패턴 및 레지스트리 워크플로를 모두 다룹니다. 이 스킬은 CLI 사용 방법, 호출 시기, 전달할 플래그를 알고 있어 에이전트가 디자인 시스템과 일치하는 코드를 생성할 수 있도록 합니다.

설치: pnpm dlx skills add shadcn/ui

통합 Radix UI 패키지 (2026년 2월)

new-york 스타일은 이제 개별 @radix-ui/react-* 패키지 대신 단일 radix-ui 패키지를 사용합니다:

// 과거 — 개별 패키지
import * as DialogPrimitive from "@radix-ui/react-dialog"

// 신규 — 통합 패키지
import { Dialog as DialogPrimitive } from "radix-ui"

기존 프로젝트를 마이그레이션하려면: npx shadcn@latest migrate radix. 마이그레이션 후 package.json에서 사용하지 않는 @radix-ui/react-* 패키지를 제거하세요.

Base UI 지원 (2026년 1월)

shadcn/ui는 이제 기본 프리미티브 라이브러리로 Radix UI의 대안으로 Base UI를 지원합니다. 선택한 라이브러리에 관계없이 컴포넌트는 동일하게 보이고 동작합니다 — 기본 구현만 변경됩니다.

초기화 중 선택: npx shadcn@latest init --base base-ui

CLI는 프로젝트 설정에 따라 올바른 컴포넌트 변형을 자동으로 가져옵니다.

설정 (components.json)

components.json 파일은 프로젝트에서 shadcn/ui가 작동하는 방식을 구성합니다:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "zinc",  // 옵션: gray, neutral, slate, stone, zinc, mauve, olive, mist, taupe
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "v0": {
      "url": "https://v0.dev/chat/api/registry"
    },
    "ai-elements": {
      "url": "https://elements.ai-sdk.dev/api/registry"
    }
  }
}

네임스페이스 레지스트리

프로젝트에 여러 레지스트리를 구성하세요:

{
  "registries": {
    "acme": {
      "url": "https://acme.com/registry/{name}.json"
    },
    "private": {
      "url": "https://internal.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

네임스페이스 구문을 사용하여 설치:

npx shadcn@latest add @acme/header @private/auth-form

테마 설정

CSS 변수

shadcn/ui는 테마 설정을 위해 CSS 사용자 정의 속성을 사용하며 globals.css에 정의됩니다:

@theme inline {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-card: oklch(0.205 0 0);
  --color-card-foreground: oklch(0.985 0 0);
  --color-primary: oklch(0.488 0.243 264.376);
  --color-primary-foreground: oklch(0.985 0 0);
  --color-secondary: oklch(0.269 0 0);
  --color-secondary-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.269 0 0);
  --color-muted-foreground: oklch(0.708 0 0);
  --color-accent: oklch(0.269 0 0);
  --color-accent-foreground: oklch(0.985 0 0);
  --color-destructive: oklch(0.396 0.141 25.723);
  --color-border: oklch(0.269 0 0);
  --color-input: oklch(0.269 0 0);
  --color-ring: oklch(0.488 0.243 264.376);
  --radius: 0.625rem;
  /* CLI v4: 반경 토큰은 가산 대신 승법 calc를 사용합니다 */
  --radius-xs: calc(var(--radius) * 0.5);
  --radius-sm: calc(var(--radius) * 0.75);
  --radius-md: calc(var(--radius) * 0.875);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.5);
}

다크 모드

다크 모드의 경우 <html>에 dark 클래스를 사용하세요:

// app/layout.tsx
<html lang="en" className="dark">

또는 토글을 위해 next-themes를 사용하세요:

import { ThemeProvider } from 'next-themes'

<ThemeProvider attribute="class" defaultTheme="dark">
  {children}
</ThemeProvider>

사용자 정의 색상

shadcn 기본값과 함께 애플리케이션별 색상을 추가하세요:

@theme inline {
  /* 위의 shadcn 기본값... */

  /* 사용자 정의 앱 색상 */
  --color-priority-urgent: oklch(0.637 0.237 15.163);
  --color-priority-high: oklch(0.705 0.213 47.604);
  --color-status-done: oklch(0.723 0.219 149.579);
}

컴포넌트에서 사용:

<span className="text-[var(--color-priority-urgent)]">긴급</span>
// 또는 Tailwind v4 theme() 사용:
<span className="text-priority-urgent">긴급</span>

가장 일반적인 컴포넌트

컴포넌트	사용 사례
button	액션, 양식 제출
card	콘텐츠 컨테이너
dialog	모달, 확인 프롬프트
input / textarea	양식 필드
select	드롭다운
table	데이터 표시
tabs	보기 전환
command	명령 팔레트 (Cmd+K)
dropdown-menu	컨텍스트 메뉴
popover	플로팅 콘텐츠
tooltip	호버 힌트
badge	상태 표시기
avatar	사용자 프로필 이미지
scroll-area	스크롤 가능 컨테이너
separator	시각적 구분선
label	양식 레이블
sheet	슬라이드 아웃 패널
skeleton	로딩 플레이스홀더

Vercel에서 shadcn의 디자인 방향

shadcn/ui는 단순한 컴포넌트 소스 생성기가 아닙니다. Vercel 스택에서는 기본 인터페이스 언어입니다. "컴포넌트가 작동한다"는 수준에서 멈추지 마세요. 의도적이고, 신호가 강하며, 일관된 페이지를 구성하십시오.

제품 UI의 기본 미학

• 제품, 대시보드, AI 및 관리자 표면에는 new-york 스타일을 선호하세요.
• 대시보드, AI 앱, 내부 도구, 설정 및 개발자 지향 제품에는 기본적으로 다크 모드를 사용하세요. 제품이 명확히 콘텐츠 우선이거나 편집 중심인 경우에만 라이트 모드를 사용하세요.
• 인터페이스 텍스트에는 Geist Sans를, 코드, 메트릭, ID, 타임스탬프, 명령어에는 Geist Mono를 사용하세요.
• 기본 팔레트로 zinc, neutral 또는 slate를 선호하세요. --color-primary를 통해 하나의 강조 색상을 사용하세요.
• 토큰으로 핵심 표면을 구축하세요: bg-background, bg-card, text-foreground, text-muted-foreground, border-border, ring-ring. 임의의 16진수 값을 피하세요.
• 반경을 일관되게 유지하세요. 기본 --radius: 0.625rem은 강력한 기준입니다.
• 페이지당 하나의 밀도 시스템을 사용하세요: 여유 (gap-6 / p-6 / text-sm) 또는 컴팩트 (gap-4 / p-4 / text-sm).
• 아이콘은 조용하고 일관되게 유지하세요. h-4 w-4 또는 h-5 w-5 크기의 Lucide 아이콘.

이것을 먼저 사용하세요

사용 사례	먼저 사용할 것	이유
설정 페이지	Tabs + Card + Form	예측 가능한 저장 흐름으로 명확한 정보 그룹화
데이터 대시보드	Card + Badge + Table + DropdownMenu	사용자 정의 셸 없이 요약, 상태, 밀집 데이터 및 행 액션 처리
CRUD 테이블	Table + DropdownMenu + Sheet + AlertDialog	표준 패턴으로 탐색, 액션, 편집 및 파괴적 확인 지원
인증 화면	Card + Label + Input + Button + Alert	입력 흐름을 집중시키고 오류에 적절한 처리를 제공
글로벌 검색	Command + Dialog	확립된 상호 작용 모델로 빠른 키보드 우선 검색
모바일 내비게이션	Sheet + Button + Separator	작은 화면에 깔끔하게 적응하는 컴팩트한 내비게이션 셸 제공
상세 페이지	헤더 + Badge + Separator + Card	과도한 중첩 없이 계층 구조, 메타데이터 및 보조 콘텐츠의 균형 유지
필터	Card 사이드바 + Sheet + Select	영구 데스크톱 필터 및 접을 수 있는 모바일 컨트롤에 적합
빈/로딩/오류 상태	Card + Skeleton + Alert	플레이스홀더 텍스트 대신 비정상 경로에 디자인된 표면 제공

구성 레시피

• 설정 페이지: Tabs + 그룹당 Card + Separator + 저장 액션
• 관리자 대시보드: 요약 Card들 + 필터 바 + Table
• 엔티티 상세: 헤더 + 상태 Badge + 메인 Card + 사이드 Card + 파괴적 액션용 AlertDialog
• 검색 중심: 빠른 찾기를 위한 Command, 선택기를 위한 Popover, 모바일 필터를 위한 Sheet
• 인증/온보딩: 중앙 정렬 Card + 소셜 Separator + 오류용 인라인 Alert
• 파괴적 흐름: 확인을 위해 Dialog 대신 AlertDialog 사용

피해야 할 안티 패턴

• shadcn 프리미티브가 존재하는데 원시 button / input / select / div 사용
• Tabs / Table / Sheet / Dialog 대신 반복적인 div rounded-xl border p-6 사용
• 여러 강조 색상이 서로 충돌
• 카드 안의 카드 안의 카드 중첩
• 모든 표면에 큰 그라데이션 배경과 유리 모피즘 사용
• 임의의 간격 및 반경 값 혼합
• 파괴적 확인을 위해 AlertDialog 대신 Dialog 사용
• 디자인 처리가 없는 빈/로딩/오류 상태 제공
• 테마 토큰 대신 기본 표면에 임시 Tailwind 팔레트 클래스 사용

사용자 정의 레지스트리 구축

프로젝트 간에 공유할 나만의 컴포넌트 레지스트리를 만드세요:

레지스트리 유형 (CLI v4)

유형	목적
registry:ui	개별 UI 컴포넌트
registry:base	전체 디자인 시스템 페이로드 — 컴포넌트, 종속성, CSS 변수, 글꼴, 설정
registry:font	일급 레지스트리 항목으로서의 글꼴 설정

1. registry.json 정의

[