shadcn-ui/ui 딥다이브
— "설치하지 않는 컴포넌트"가 만드는 AI 시대의 UI 표준

1한 줄 정체

shadcn/ui는 npm 패키지가 아니다. 이 문장이 이 저장소를 이해하는 가장 중요한 출발점이다. Material UI(MUI)나 Chakra UI 같은 전통적인 컴포넌트 라이브러리는 npm install로 검은 상자(black box) 같은 완제품 패키지를 프로젝트에 얹고, 그 패키지의 API를 익혀 사용한다. 반면 shadcn/ui는 CLI가 컴포넌트의 실제 소스 코드 파일을 통째로 복사해 내 프로젝트의 components/ui 폴더에 붙여넣는다. 설치가 끝나는 순간 그 파일은 라이브러리의 일부가 아니라 내가 작성한 것처럼 자유롭게 고칠 수 있는 내 코드가 된다.

루트 README.md는 이 철학을 "Open Source. Open Code."라는 슬로건으로 못 박는다. 실제로 저장소 안에는 두 가지 큰 축이 공존한다. 하나는 레지스트리 — 버튼·다이얼로그·폼 같은 UI 조각과 대시보드·로그인 화면 같은 블록(block)의 소스 코드 및 메타데이터를 모아둔 JSON+파일 더미(apps/v4/registry, 컴파일 결과물 registry.json에 411개 항목). 다른 하나는 CLI(npm 패키지명 shadcn) — 그 레지스트리에서 필요한 항목을 골라, 내 프로젝트의 폴더 구조·별칭(alias)·Tailwind 설정에 맞게 코드를 변형(transform)해 옮겨 심는 엔진이다.

2왜 지금 뜨는가

shadcn/ui는 이미 여러 해 전부터 React 생태계의 사실상 표준으로 자리 잡았지만, 2026년 시점에 이 저장소를 다시 들여다볼 이유는 따로 있다. 코드 자체가 계속 구조적으로 진화하고 있고, 그 방향이 정확히 "AI 에이전트가 UI 코드를 직접 다루는 시대"를 정조준하고 있기 때문이다.

① Claude Code가 직접 읽는 공식 "스킬"이 저장소 안에 산다

저장소 안의 skills/shadcn/SKILL.md는 Claude Code 같은 코딩 에이전트가 이 프로젝트를 만질 때 지켜야 할 규칙을 담은 공식 에이전트 스킬 문서다. "기존 컴포넌트를 먼저 검색해라", "className은 레이아웃에만 써라, 색상은 시맨틱 토큰으로", "Dialog는 반드시 Title이 있어야 한다" 같은 실전 규칙이 Incorrect/Correct 코드 쌍과 함께 정리돼 있다. 즉 이 저장소 자체가 "AI가 UI를 짤 때 참고하는 교과서" 역할을 자처한다.

② 세 가지 헤드리스 프리미티브로 "Radix 종속"을 끊다

오랫동안 shadcn/ui는 사실상 Radix UI 위의 스타일링 레이어였다. 그런데 현재 저장소의 apps/v4/registry/bases/ 아래에는 radix · base · aria 세 개의 병렬 디렉터리가 있다. 같은 Button이라도 Radix UI 기반, Base UI(MUI 팀의 새 헤드리스 라이브러리) 기반, React Aria(Adobe) 기반 세 가지 소스가 따로 존재한다. 심지어 skills/migrate-radix-to-base라는 전용 마이그레이션 스킬까지 갖췄다. 특정 헤드리스 벤더에 락인(lock-in)되지 않겠다는 의지가 코드로 드러난다.

③ 프리셋 코드 한 줄로 "디자인 시스템 전체"를 공유한다

packages/shadcn/src/preset/preset.ts는 베이스(radix/base/aria) · 스타일(nova, vega, maia, lyra, mira, luma, sera, rhea 8종) · 기본 색상 · 테마 색상을 비트 단위로 압축해 하나의 base62 문자열로 인코딩한다. npx shadcn init --preset <코드> 한 줄이면 팀 전체가 똑같은 디자인 시스템 조합으로 시작할 수 있다. "우리 팀 스타일은 이 코드입니다"라고 URL처럼 공유하는 문화가 가능해진 것이다.

3무엇을 해결하나

React로 UI를 만들 때 개발자는 늘 두 가지 나쁜 선택지 사이에서 골랐다. 하나는 완제품 라이브러리를 설치하는 것 — 빠르지만, 디자인을 깊이 바꾸려면 라이브러리가 허용하는 테마 옵션 안에서만 움직여야 하고, 접근성(accessibility) 버그를 만나도 내가 고칠 수 없어 이슈 트래커에 줄을 서야 한다. 다른 하나는 Radix UI 같은 헤드리스 프리미티브 위에 처음부터 직접 스타일링하는 것 — 자유롭지만, 버튼 하나 다이얼로그 하나에도 접근성·포커스 트랩·애니메이션을 처음부터 다 챙겨야 해서 느리다.

shadcn/ui는 이 둘을 "이미 잘 만들어진 답을 받아서, 그 답을 내 것처럼 고친다"는 제3의 길로 풀었다. 컴포넌트는 이미 Radix UI/Base UI/React Aria라는 검증된 접근성 엔진 위에서 동작하도록 완성돼 있고, 스타일은 Tailwind 유틸리티 클래스로 눈에 훤히 보이게 짜여 있다. 개발자는 "접근성이 되는 컴포넌트를 밑바닥부터 만드는 시간"을 아끼면서도, "그 컴포넌트의 모든 코드 한 줄까지 내 마음대로 바꿀 자유"를 동시에 얻는다.

같은 문제의식이 CLI의 변형기(transformer) 파이프라인에도 이어진다. 컴포넌트를 그냥 복사만 하면 프로젝트마다 다른 import 별칭(@/components vs ~/ui 등), CSS 변수 사용 여부, Tailwind 접두사(prefix) 설정 때문에 코드가 그대로 동작하지 않는다. CLI는 이 지점을 ts-morph 기반 AST 변형으로 자동 보정해, "복사"가 아니라 "내 프로젝트에 맞게 재조립된 이식"이 되게 한다.

4전체 구조

저장소는 pnpm-workspace.yaml로 관리되는 모노레포이며, 빌드는 Turborepo, 릴리스는 Changesets가 맡는다. 최상위는 apps/와 packages/ 둘로 나뉘는데, 역할 분담이 뚜렷하다.

이 배치가 말해주는 것은 명확하다. apps/v4는 "레지스트리 데이터의 원천이자 문서 사이트"이고, packages/shadcn은 "그 데이터를 소비해 사용자 프로젝트에 이식하는 CLI"다. 이 두 축을 분리해 뒀기 때문에, 레지스트리 콘텐츠(컴포넌트 종류·스타일)와 CLI 엔진(변형·설치 로직)이 독립적으로 버전업된다 — 실제로 CLI는 v4.16.0인 반면 레지스트리 콘텐츠는 매일같이 커밋되며 계속 늘어난다.

5핵심 설계·동작 원리

설계 원리 ① — "add" 한 줄 뒤에 숨은 5단계 파이프라인

packages/shadcn/src/commands/add.ts는 npx shadcn add button 같은 명령이 들어왔을 때 실제로 일어나는 일을 조율하는 진입점이다. 핵심 흐름은 다음과 같다.

주목할 지점은 4단계가 단순 파일 복사가 아니라는 것이다. 컴포넌트 파일 하나를 옮기기 전에, CLI는 그 파일을 ts-morph로 AST(추상 구문 트리)까지 파싱해 15종의 변형기(transformer)를 순서대로 통과시킨다.

설계 원리 ② — AST 변형기: "복사"가 아니라 "재조립"

packages/shadcn/src/utils/transformers/ 폴더에는 transform-import.ts, transform-css-vars.ts, transform-tw-prefix.ts, transform-rsc.ts, transform-icons.ts, transform-jsx.ts 등 15개 파일이 있다. 각각이 컴포넌트 소스 코드의 특정 측면 하나씩을 프로젝트 사정에 맞춰 고쳐 쓴다.

설계 원리 ③ — "베이스 3종 × 스타일 8종"을 하나의 정수로 압축하는 프리셋

packages/shadcn/src/preset/preset.ts는 매우 실용적인 엔지니어링 트릭을 보여준다. 베이스(PRESET_BASES = ["radix","base","aria"]) · 스타일(PRESET_STYLES 8종: nova·vega·maia·lyra·mira·luma·sera·rhea) · 기본 색상 8종 · 테마 색상을 각각 배열의 인덱스로 표현하고, 이 인덱스들을 비트 단위로 이어붙여 JS의 안전 정수 범위(53비트) 안에서 하나의 숫자로 합친 뒤 base62 문자열로 인코딩한다. 파일 맨 위 주석에 못박힌 규칙이 인상적이다: "기존 값 배열은 절대 재정렬하지 말고 뒤에만 추가하라" — 한 번 배포된 프리셋 코드가 나중 버전에서도 똑같이 해석돼야 하기 때문에, 하위 호환을 위한 규율을 코드 주석으로 강제하고 있다.

이 덕분에 npx shadcn init --preset <62진수 코드> 한 줄로 "Base UI 베이스 + vega 스타일 + zinc 기본색 + amber 테마"라는 조합 전체를 순식간에 복원할 수 있다. parsePresetStyle()은 반대로 "radix-nova" 같은 문자열에서 베이스와 스타일 이름을 다시 분리해낸다.

설계 원리 ④ — 헤드리스 베이스 3종: 같은 API, 다른 엔진

apps/v4/registry/bases/radix/ui/button.tsx와 bases/base/ui/button.tsx, bases/aria/ui/button.tsx를 나란히 열어 보면, Radix 버전은 import { Slot } from "radix-ui"를, Base 버전은 Base UI의 프리미티브를, Aria 버전은 React Aria의 훅을 각각 가져다 쓴다. 겉으로 드러나는 Button의 props와 사용법은 거의 동일하게 맞춰져 있지만, 내부에서 접근성·포커스·이벤트를 처리하는 엔진 자체가 다르다. 그래서 프로젝트가 이미 Base UI 생태계를 쓰고 있다면 Radix 의존성을 하나도 늘리지 않고 shadcn 컴포넌트를 쓸 수 있다.

설계 원리 ⑤ — 신규 프리셋 스타일은 클래스가 아니라 "이름"만 컴포넌트에 남긴다

더 미묘하지만 중요한 변화가 하나 더 있다. 클래식 new-york-v4 스타일은 지금도 bg-primary text-primary-foreground hover:bg-primary/90처럼 Tailwind 유틸리티 클래스를 컴포넌트 파일 안에 그대로 박아 둔다("보이는 그대로가 전부"라는 원조 철학). 반면 새 프리셋 베이스(radix/base/aria)의 Button은 "cn-button cn-button-variant-default"처럼 의미만 담은 클래스 이름을 쓰고, 실제 Tailwind 유틸리티는 apps/v4/registry/styles/style-nova.css 같은 별도 스타일시트 안에 @apply로 정의돼 있다. 스타일 이름(nova·vega 등)을 갈아 끼우면 컴포넌트 코드를 한 글자도 안 건드리고 룩앤필 전체가 바뀌는 구조다.

설계 원리 ⑥ — MCP 서버: 에이전트가 레지스트리를 직접 검색하게 하기

packages/shadcn/src/mcp/index.ts(576줄)는 MCP(Model Context Protocol) 서버를 구현한다. get_project_registries(components.json에 등록된 레지스트리 목록 조회), list_items_in_registries, search_items_in_registries(퍼지 검색), get_item_examples_from_registries 같은 도구를 노출해, Claude 같은 에이전트가 "이 프로젝트에 데이터 테이블 컴포넌트가 있나?"를 코드를 뒤지지 않고 구조화된 도구 호출로 바로 물어볼 수 있게 한다. 실제 설치는 여전히 npxShadcn() 헬퍼가 내부적으로 npx shadcn add를 실행해 처리한다 — MCP는 "탐색"을, CLI는 "실행"을 맡는 분업이다.

6기술 스택 · 의존성

버전의 진실원(source of truth)은 하나가 아니라 세 갈래라는 점이 헷갈리기 쉽다. CLI 자체(packages/shadcn/package.json)는 npm에 "shadcn"이라는 이름으로 배포되며 버전은 4.16.0이다. 헤드리스 전용 패키지 @shadcn/react는 별도로 0.2.1, AI 채팅 UI 헬퍼 @shadcn/helpers는 0.1.0이다. 반면 컴포넌트 그 자체(레지스트리 콘텐츠)는 npm 버전이 없다 — 복사된 순간의 스냅샷이 곧 버전이고, 최신화는 shadcn diff로 수동 비교하는 방식이다.

7설치 · 요구사항

8실제 사용 흐름

9함정 · 오해 방지

함정 ① "npm install이 아니니 버전 관리를 신경 안 써도 된다"

절반만 맞다. 컴포넌트 코드 자체는 복사된 순간의 스냅샷이라 자동 업데이트가 없는 게 맞지만, 그 컴포넌트가 쓰는 진짜 npm 패키지(@radix-ui/react-slot, class-variance-authority 등)는 package.json에 그대로 등록돼 일반적인 npm 의존성처럼 버전이 올라간다. 그리고 shadcn 쪽 원본 코드가 나중에 버그를 고쳐도 내 프로젝트엔 자동 반영되지 않으므로, shadcn diff로 주기적으로 비교하는 습관이 필요하다.

함정 ② "shadcn/ui는 Radix UI 래퍼다"

한때는 정확한 설명이었지만 지금은 절반만 맞다. apps/v4/registry/bases/에 radix·base·aria 세 베이스가 나란히 존재하고, 심지어 Radix에서 Base UI로 옮겨가도록 돕는 skills/migrate-radix-to-base 공식 마이그레이션 스킬까지 있다. "전부 Radix 위에서 돈다"는 설명은 클래식 new-york-v4 스타일에는 아직 맞지만, 신규 프리셋 시스템 전체를 대표하지 않는다.

함정 ③ "복사된 파일 하나만 보면 스타일을 전부 파악할 수 있다"

클래식 new-york-v4 스타일은 맞는 말이다 — bg-primary hover:bg-primary/90 같은 Tailwind 클래스가 컴포넌트 파일 안에 그대로 보인다. 하지만 신규 프리셋 베이스(radix/base/aria)의 컴포넌트는 cn-button-variant-default처럼 의미만 담은 이름을 쓰고, 실제 색상·간격 값은 style-nova.css 같은 별도 스타일시트의 @apply 규칙 안에 있다. "컴포넌트 파일 하나가 스타일의 전부"라는 원조 철학이 이 신규 시스템에서는 스타일시트 파일까지 함께 봐야 하는 형태로 바뀌었다.

함정 ④ "패키지 이름이 shadcn-ui다"

GitHub 조직·저장소 이름은 여전히 shadcn-ui/ui이지만, 실제로 npx로 실행하고 npm에 배포되는 CLI 패키지 이름은 "shadcn"이다(packages/shadcn/package.json의 name 필드). 예전 자료에서 npx shadcn-ui@latest 같은 명령을 본 적이 있다면 구버전 이름이며, 현재는 npx shadcn@latest가 맞는 표기다.

함정 ⑤ "asChild만 알면 커스텀 트리거를 다 만들 수 있다"

Radix 기반 컴포넌트는 asChild prop으로 렌더링 요소를 갈아 끼우지만, Base UI 기반 컴포넌트는 같은 목적에 render prop을 쓴다. 저장소의 스킬 문서(skills/shadcn/rules/base-vs-radix.md)가 이 차이를 별도 문서로 떼어 다룰 만큼, 어떤 베이스를 쓰는 프로젝트인지 먼저 확인하지 않으면 다른 베이스의 문법을 그대로 갖다 써서 타입 에러를 만나기 쉽다.

10대안 비교

선택 기준을 한 문장으로 요약하면 이렇다. "빠르게 완제품을 쓰고 싶고 깊은 커스터마이징은 드물다"면 MUI·Chakra·Mantine 같은 전통 라이브러리가 유지보수 부담이 적다. "디자인을 세밀하게 통제하고 싶고, 컴포넌트 내부 구현까지 언제든 고칠 각오가 있다"면 shadcn/ui의 "코드를 내가 소유한다"는 모델이 압도적으로 유리하다. daisyUI는 애초에 React 컴포넌트 레이어가 없으므로 비교 대상이라기보다 "Tailwind 클래스 프리셋"이라는 다른 층위의 도구다.

11정리 · 누가 쓰면 좋은가

shadcn/ui를 한 문장으로 다시 정리하면: "검증된 헤드리스 접근성 엔진 위에, 내가 100% 소유하고 고칠 수 있는 스타일 코드를 CLI가 대신 재단해 붙여주는 레지스트리 시스템"이다. npm 라이브러리처럼 설치해서 쓰는 게 아니라, 목공소에서 치수 맞춰 받은 가구처럼 "완성된 내 코드"로 프로젝트에 들어온다는 점이 다른 모든 특징의 출발점이다.

이 저장소에서 배울 게 많은 사람은 다음과 같다. 첫째, 사내 디자인 시스템을 처음부터 만들어야 하는 팀 — Radix/Base UI/React Aria 위에서 접근성을 걱정하지 않고 스타일링부터 시작할 수 있는 뼈대로 쓰기 좋다. 둘째, AI 코드 생성 도구를 실무에 쓰는 개발자 — v0·Claude Code 같은 도구가 사실상 표준 출력으로 삼는 형식이라, 이 저장소의 CLI 변형 로직과 MCP 서버를 이해해 두면 에이전트가 왜 이런 파일 구조로 코드를 내놓는지 납득할 수 있다. 셋째, ts-morph를 이용한 AST 코드 변형이나 CLI 설계를 공부하려는 개발자 — transform-import.ts·preset.ts는 "설정에 따라 소스 코드를 안전하게 재작성하는" 실전 패턴의 좋은 교재다.

반대로 "설치 한 번으로 끝내고 다시는 그 코드를 보고 싶지 않다"는 팀에는 맞지 않는다. 컴포넌트가 내 코드가 됐다는 건 결국 그 코드의 유지보수 책임도 내가 진다는 뜻이며, 이 트레이드오프를 받아들일 준비가 됐을 때 shadcn/ui의 진짜 가치가 드러난다.

12직접 해볼 수 있는 실습 과제

아래 과제는 독자가 별도 학습용 복사본에서 수행한다. 명령은 저장소 루트 기준이며, 해당 워크스페이스의 의존성이 이미 설치되어 있어야 한다. 원격 레지스트리 조회 없이 로컬 코드와 테스트로 결과를 확인할 수 있다.

경로는 제공된 소스를 기준으로 적었다. 원문에서 CLI 내부로 설명한 변형기와 프리셋 구현은 이 소스에서 packages/registry/src/ 아래에 있으므로, packages/shadcn/과 함께 읽는다.

brand: "bg-primary text-primary-foreground underline underline-offset-4",

pnpm --filter=v4 exec tsx -e 'import { buttonVariants } from "./registry/new-york-v4/ui/button.tsx"; console.log(buttonVariants({ variant: "brand", size: "sm" }))'

it("학습: 내부 별칭만 바꾸고 외부 패키지는 유지한다", async () => {
  const result = await transform({
    filename: "learning.tsx",
    raw: `import { Button } from "@/registry/new-york-v4/ui/button"
import { useState } from "react"
`,
    config: {
      tsx: true,
      aliases: {
        components: "~/components",
        ui: "~/ui",
        utils: "~/lib/utils",
      },
    } as Config,
  })

  expect(result).toContain('from "~/ui/button"')
  expect(result).toContain('from "react"')
  expect(result).not.toContain("@/registry/")
})

pnpm --filter=@shadcn/registry test src/transformers/transform-import.test.ts

it("학습용 프리셋을 같은 설정으로 복원한다", () => {
  const config: PresetConfig = {
    ...DEFAULT_PRESET_CONFIG,
    style: "vega",
    baseColor: "zinc",
    theme: "amber",
  }

  const code = encodePreset(config)
  expect(decodePreset(code)).toEqual(config)
})

pnpm --filter=@shadcn/registry test src/preset/preset.test.ts

it("학습 카드를 로컬 레지스트리 JSON으로 만든다", async () => {
  const source =
    'export function LearningCard() { return <div>학습 카드</div> }'

  const cwd = await createFixture({
    "registry.json": JSON.stringify({
      name: "learning",
      homepage: "http://localhost",
      items: [
        {
          name: "learning-card",
          type: "registry:ui",
          files: [
            {
              path: "components/ui/learning-card.tsx",
              type: "registry:ui",
            },
          ],
        },
      ],
    }),
    "components/ui/learning-card.tsx": source,
  })

  await build.parseAsync(
    ["node", "shadcn", "registry.json", "--cwd", cwd, "--output", "public/r"],
    { from: "node" }
  )

  const item = JSON.parse(
    await fs.readFile(
      path.join(cwd, "public/r/learning-card.json"),
      "utf-8"
    )
  )

  expect(item.files[0].path).toBe("components/ui/learning-card.tsx")
  expect(item.files[0].content).toBe(source)
})

pnpm --filter=shadcn test src/commands/build.test.ts

13관련 기술 심화 학습 로드맵

매주 하나의 결과물을 남기며 진행한다. 화면을 만드는 기술을 먼저 익히고, 그 화면의 소스를 프로젝트에 맞게 옮기는 CLI와 레지스트리로 범위를 넓힌다.

14핵심 키워드 사전