저장소 밖 앱에 설치

@werft-ai/ui를 이 저장소 밖의 React 앱에서 쓰는 방법이다. 저장소에서 패키지를 빌드해 tarball로 묶고, 앱에서 그 파일을 npm install한다. 앱에 Tailwind는 없어도 된다.

tarball 만들기제목 링크 복사

저장소 루트에서 실행한다. 저장소가 고정한 Bun 1.3.14(루트 package.json의 packageManager)와 npm이 필요하다.

bun install
bun run --cwd packages/ui build:package
npm pack ./packages/ui/dist

build:package가 packages/ui/dist에 빌드된 JavaScript와 타입 선언, CSS, 배포용 package.json, LICENSE를 만든다. npm pack은 그 디렉터리를 묶어 현재 디렉터리에 werft-ai-ui-<버전>.tgz를 둔다. 버전은 packages/ui/package.json의 version이다.

앱에 설치하기제목 링크 복사

Vite + React + TypeScript 앱을 예로 든다. 앱이 없으면 npm create vite@latest my-app -- --template react-ts로 만든다.

@werft-ai/ui는 react와 react-dom ^19.3.0을 peer dependency로 받는다. 앱의 React가 이보다 낮으면 먼저 올리고, 만든 tarball을 설치한다.

npm install react@^19.3.0 react-dom@^19.3.0
npm install <저장소 경로>/werft-ai-ui-0.0.0.tgz

Radix, class-variance-authority, clsx, tailwind-merge, lucide-react는 패키지의 dependency라서 함께 설치된다.

CSS 가져오기제목 링크 복사

미리 빌드한 styles.css를 한 번 import한다. 토큰, 키트 요소의 규칙, 키트가 쓰는 유틸리티 클래스가 모두 들어 있어서 Tailwind 없이 그려진다.

import "@werft-ai/ui/styles.css";
import { Button, Card } from "@werft-ai/ui";

styles.css에는 Tailwind의 preflight(전역 리셋)가 없다. 전역에 거는 규칙은 하나뿐이다. 모든 요소의 기본 border-color를 --werft-color-border로 둬서, 앱이 border-width와 border-style만 주고 색을 정하지 않은 요소는 이 색으로 그려진다(border 단축 속성은 색도 정하므로 해당하지 않는다). 키트가 기대하는 리셋(테두리, margin, 버튼 배경, 링크 밑줄 등)은 키트 요소와 그 안쪽에만 specificity 0으로 걸린다. 그래서 키트 안에 넣은 앱 마크업도 브라우저 기본 margin과 밑줄이 빠진다. 키트 규칙은 cascade layer 안에 있어서 layer 밖에 쓴 앱의 CSS가 항상 이긴다.

Tailwind v4 앱제목 링크 복사

앱의 마크업에서도 키트의 유틸리티 이름(bg-primary, text-control, rounded-control 등)을 쓰려면 앱 CSS에서 styles.css 뒤에 theme.css를 import한다. theme.css가 토큰을 Tailwind 유틸리티에 잇는다.

@import "tailwindcss";
@import "@werft-ai/ui/styles.css";
@import "@werft-ai/ui/theme.css";

키트 컴포넌트가 쓰는 클래스는 styles.css에 이미 있어서 node_modules를 @source로 스캔하지 않아도 된다.

폰트제목 링크 복사

패키지는 폰트를 싣지 않는다. 글꼴 목록은 --werft-font-sans(Geist, Pretendard Variable 순)와 --werft-font-mono(Geist Mono부터)에 있지만, styles.css는 이 변수를 키트의 werft-* 요소에만 건다. 버튼·세그먼트 컨트롤 같은 컨트롤은 앱의 글꼴을 물려받으므로, 앱이 body(또는 :root)에 글꼴을 주지 않으면 브라우저 기본 글꼴(대개 Times 같은 serif)로 그려진다. 앱 CSS에 한 줄을 둔다.

body { font-family: var(--werft-font-sans); }

이렇게 두면 앱이 Geist·Pretendard를 로드하지 않아도 목록 끝의 시스템 폰트로 그려진다. 한글을 Pretendard로 보이려면 앱이 직접 로드한다. 이 저장소의 웹 콘솔은 pretendard 패키지의 dynamic subset을 쓴다.

npm install pretendard

import "pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css";

테마제목 링크 복사

라이트가 기본이다. 어두운 테마를 켜는 방법은 테마 적용과 같다.

가져올 수 있는 경로제목 링크 복사

다음 단계제목 링크 복사

• 테마 적용: 어두운 테마와 덮어쓰기 규칙