Installation

스타일은 패키지에서 불러오고, 복사한 파일은 프로젝트 코드라서 자유롭게 수정할 수 있어요.

설치할 프레임워크를 고르세요.

요구 사항

요구 사항
이름	버전
Node	20.11 이상
react	19
react-dom	19
tailwindcss	4.0 이상

@base-ui/react, tailwind-variants는 @pantoia/ui와 함께 설치돼요. init이 @pantoia/ui를 설치하고, 글꼴 패키지 pretendard, @fontsource/jetbrains-mono는 설치할지 물어요. Tabs의 스크롤바 모양은 tailwindcss 4.3부터 적용돼요.

커스터마이징

값을 바꾸거나 새 이름을 더할 때는 전역 CSS의 두 @import 아래에 적어요. 토큰마다 적는 곳은 각 파운데이션 페이지의 추가 가이드에 있어요.

전역 CSS

@import "tailwindcss";@import "@pantoia/ui/tailwind.css";@import "pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css";/* 둥글기, 간격, 글자, 글꼴, 그림자, 곡선 */@theme { --radius-r18: 18px; }/* 색과 그림자 알파. 라이트와 다크에 같은 이름을 적어요 */:root, .light { --pds-bg-brand-solid: #9c63e4; }.dark { --pds-bg-brand-solid: #9c63e4; }/* 전환 시간처럼 모드와 무관한 값 */:root { --dur-state: 120ms; }/* 새 Surface, 새 전환 유틸리티 */@utility raised { @apply bg-bg-panel shadow-s2; }

직접 만드는 컴포넌트도 저장 위치의 tv.ts로 조립하면 className으로 덮어쓰는 동작이 같아져요. 토큰 이름을 더했으면 twMergeConfig의 그룹 목록에도 더하세요.

tv.ts

import { createTV } from 'tailwind-variants'export type { VariantProps } from 'tailwind-variants'export const tv = createTV({  twMergeConfig: {    theme: {      spacing: ['tight', 'stack', 'block', 'section', 'gutter'],      radius: [        'r2', 'r4', 'r6', 'r8', 'r10', 'r12', 'r14', 'r16', 'r20', 'r24',      ],      text: [        'display', 'title', 'section', 'subsection', 'prose', 'value',        'label', 'caption', 'micro',        't10', 't11', 't12', 't13', 't14', 't16', 't18', 't20',        't24', 't28', 't32', 't40', 't48', 't56', 't64',      ],      shadow: ['s1', 's2', 's3'],      ease: ['state', 'enter', 'exit'],    },  },})

업데이트하기

스타일은 패키지를 올리면 바로 바뀌고, 컴포넌트는 다시 추가해야 바뀌어요. --force로 다시 추가하면 직접 고친 줄이 사라지니 diff로 먼저 확인하세요.

npm install @pantoia/ui@latestnpx @pantoia/ui diffnpx @pantoia/ui add button --force

명령어

명령어
이름	설명
init [--path <경로>] [--css <경로>]	@pantoia/ui를 설치하고 저장 위치와 전역 CSS 파일을 물어 components.json에 저장해요. Claude Code 스킬도 연결해요. 옵션을 주면 저장 위치와 전역 CSS 질문을 건너뛰어요.
add <이름...> [--force]	컴포넌트와 함께 필요한 파일을 복사해요. --force를 주면 묻지 않고 덮어써요.
list	추가할 수 있는 이름과 함께 추가되는 컴포넌트를 보여 줘요.
diff [이름]	복사한 파일을 설치된 패키지의 파일과 비교해요. 이름을 생략하면 추가한 컴포넌트를 모두 비교해요.

터미널

components/ui/button/index.tsx 파일이 이미 있고 내용이 달라요. 덮어쓸까요? (y/N)

초기화하기

Tailwind CSS가 설치된 프로젝트에서 실행하세요. init이 @pantoia/ui를 설치하고 글꼴 패키지를 설치할지 물어요. 질문에 모두 엔터를 누르면 app/globals.css에 스타일과 글꼴을 불러오는 줄이 추가돼요.

npx @pantoia/ui init

터미널

컴포넌트를 저장할 위치를 입력하세요. (components/ui)전역 CSS 파일 위치를 입력하세요. (app/globals.css)글꼴 패키지 pretendard, @fontsource/jetbrains-mono를 설치할까요? (Y/n)app/globals.css를 이렇게 수정해요.  @import "tailwindcss";+ @import "@pantoia/ui/tailwind.css";+ @import "pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css";  ...+ @font-face {+   font-family: "JetBrains Mono";+   src: url("@fontsource/jetbrains-mono/files/jetbrains-mono-latin-400-normal.woff2") format("woff2");+   font-weight: 400;+   font-display: swap;+   unicode-range: U+0000-00FF, U+2000-206F;+ }수정할까요? (Y/n)Claude Code 스킬 .claude/skills/pantoia-design을 만들까요? (Y/n)

컴포넌트 추가하기

추가할 수 있는 컴포넌트는 Components에서 볼 수 있어요.

npx @pantoia/ui add button

사용하기

app/page.tsx

import { Button } from '@/components/ui/button'export default function Page() {  return <Button color="brand" emphasis="solid">저장하기</Button>}

앱 루트

플로팅 요소가 페이지의 z-index에 가려지지 않게 앱을 isolate로 감싸요. toast()로 띄운 알림은 Toast가 있어야 나타나서, Toast를 앱에 하나 둬요.

app/layout.tsx

<body>  <div className="isolate">{children}</div>  <Toast /></body>

다크 모드

html에 dark 클래스를 추가하면 다크 모드로 바뀌어요. 일부만 라이트로 두려면 그 요소에 light 클래스를 추가하세요.

app/layout.tsx

<html className="dark">

초기화하기

Tailwind CSS가 설치된 프로젝트에서 실행하세요. init이 @pantoia/ui를 설치하고 글꼴 패키지를 설치할지 물어요. 질문에 모두 엔터를 누르면 src/index.css에 스타일과 글꼴을 불러오는 줄이 추가돼요.

npx @pantoia/ui init

터미널

컴포넌트를 저장할 위치를 입력하세요. (src/components/ui)전역 CSS 파일 위치를 입력하세요. (src/index.css)글꼴 패키지 pretendard, @fontsource/jetbrains-mono를 설치할까요? (Y/n)src/index.css를 이렇게 수정해요.  @import "tailwindcss";+ @import "@pantoia/ui/tailwind.css";+ @import "pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css";  ...+ @font-face {+   font-family: "JetBrains Mono";+   src: url("@fontsource/jetbrains-mono/files/jetbrains-mono-latin-400-normal.woff2") format("woff2");+   font-weight: 400;+   font-display: swap;+   unicode-range: U+0000-00FF, U+2000-206F;+ }수정할까요? (Y/n)Claude Code 스킬 .claude/skills/pantoia-design을 만들까요? (Y/n)

컴포넌트 추가하기

추가할 수 있는 컴포넌트는 Components에서 볼 수 있어요.

npx @pantoia/ui add button

사용하기

src/App.tsx

import { Button } from './components/ui/button'export default function App() {  return <Button color="brand" emphasis="solid">저장하기</Button>}

앱 루트

플로팅 요소가 페이지의 z-index에 가려지지 않게 앱을 isolate로 감싸요. toast()로 띄운 알림은 Toast가 있어야 나타나서, Toast를 앱에 하나 둬요.

src/main.tsx

<StrictMode>  <div className="isolate">    <App />  </div>  <Toast /></StrictMode>

다크 모드

html에 dark 클래스를 추가하면 다크 모드로 바뀌어요. 일부만 라이트로 두려면 그 요소에 light 클래스를 추가하세요.

index.html

<html lang="ko" class="dark">

초기화하기

Tailwind CSS가 설치된 프로젝트에서 실행하세요. init이 @pantoia/ui를 설치하고 글꼴 패키지를 설치할지 물어요. 질문에 모두 엔터를 누르면 app/app.css에 스타일과 글꼴을 불러오는 줄이 추가돼요.

npx @pantoia/ui init

터미널

컴포넌트를 저장할 위치를 입력하세요. (app/components/ui)전역 CSS 파일 위치를 입력하세요. (app/app.css)글꼴 패키지 pretendard, @fontsource/jetbrains-mono를 설치할까요? (Y/n)app/app.css를 이렇게 수정해요.  @import "tailwindcss";+ @import "@pantoia/ui/tailwind.css";+ @import "pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css";  ...+ @font-face {+   font-family: "JetBrains Mono";+   src: url("@fontsource/jetbrains-mono/files/jetbrains-mono-latin-400-normal.woff2") format("woff2");+   font-weight: 400;+   font-display: swap;+   unicode-range: U+0000-00FF, U+2000-206F;+ }수정할까요? (Y/n)Claude Code 스킬 .claude/skills/pantoia-design을 만들까요? (Y/n)

의존성 미리 묶기

React Router는 개발 서버를 시작할 때 route의 의존성을 미리 묶지 않아요. 처음 여는 페이지에서 새 컴포넌트를 묶으면 페이지 전체가 새로고침되고 첫 페이지로 돌아가요. react-router.config.ts에 future 한 줄을 추가하세요.

react-router.config.ts

export default {  // ...  future: { unstable_optimizeDeps: true },} satisfies Config

컴포넌트 추가하기

추가할 수 있는 컴포넌트는 Components에서 볼 수 있어요.

npx @pantoia/ui add button

사용하기

app/routes/home.tsx

import { Button } from '~/components/ui/button'export default function Home() {  return <Button color="brand" emphasis="solid">저장하기</Button>}

앱 루트

플로팅 요소가 페이지의 z-index에 가려지지 않게 앱을 isolate로 감싸요. toast()로 띄운 알림은 Toast가 있어야 나타나서, Toast를 앱에 하나 둬요.

app/root.tsx

<body>  <div className="isolate">{children}</div>  <Toast />  <ScrollRestoration />  <Scripts /></body>

다크 모드

html에 dark 클래스를 추가하면 다크 모드로 바뀌어요. 일부만 라이트로 두려면 그 요소에 light 클래스를 추가하세요.

app/root.tsx

<html lang="ko" className="dark">