WIZ Design System

WIZ Design System은 사내 GitLab npm 레지스트리로 배포됩니다. 제품에 설치해 세 패키지를 함께 씁니다.

@wds/ui-web — React 컴포넌트 (Button, Input, Modal 등) · 아이콘 · 레이아웃
@wds/tokens — 디자인 토큰 (--wds-* CSS 변수: 색 · 간격 · radius · 그림자)
@wds/fonts — 브랜드 폰트 (Pretendard). 이게 있어야 글자가 브랜드 서체로 나옵니다 (없으면 시스템 폰트로 폴백)

설치 방법은 두 가지입니다. 아래 탭에서 본인에게 맞는 쪽을 고르세요.

공개 npm(npmjs.com)이 아니라 회사 전용 비공개 레지스트리입니다. 사내망 접근과 읽기 토큰(관리자에게 요청)이 필요합니다.

명령어를 직접 칠 필요 없습니다. AI 코딩 도구(Claude Code · Cursor 등)에게 한국어로 시키면 AI가 설치와 사용을 대신 합니다.

단계를 클릭하면 현재 진행 위치가 표시됩니다.

준비물
- AI 코딩 도구 (Claude Code · Cursor 등)
- 관리자에게 받은 읽기 토큰
토큰을 내 컴퓨터에 저장
토큰은 AI 대화에 붙여넣지 마세요
토큰을 AI 채팅에 넣으면 대화 기록에 남아 유출될 수 있습니다. 아래처럼 내 컴퓨터에만 저장하세요.
본인 컴퓨터의 운영체제를 고르고, 터미널을 열어 만들 프로젝트 폴더에서 명령을 붙여넣으세요 (받은토큰 자리만 받은 토큰으로 교체).
wds.wiz-factory.net은 문서 포털입니다. 패키지 설치는 사내 GitLab Package Registry 주소를 사용합니다.
Terminal — zsh
% printf '%s\n%s\n' \ '@wds:registry=http://175.126.123.151:8000/api/v4/projects/99/packages/npm/' \ '//175.126.123.151:8000/api/v4/projects/99/packages/npm/:_authToken=받은토큰' > .npmrc
터미널 여는 법: Spotlight(⌘ + Space)에서 "터미널" 검색 · 붙여넣고 Enter
→ 토큰이 프로젝트 폴더의 .npmrc 파일에만 저장됩니다. AI 대화에는 들어가지 않습니다.

AI에게 설치 시키기

AI 코딩 도구에 아래를 붙여넣으세요. 토큰이 없습니다(1단계에서 저장했으니까). 한 번 붙여넣으면 설치 · CSS 연결 · 규칙(AGENTS.md)까지 한꺼번에 끝납니다.

AI에게 붙여넣기

이 프로젝트에 우리 회사 디자인 시스템(WIZ Design System)을 설치하고 규칙을 설정해줘.

1) @wds/ui-web, @wds/tokens, @wds/fonts 를 설치해줘. (.npmrc 는 이미 만들어 뒀어. @wds/ui-web 은 React 19 가 필요해 — 프로젝트가 React 18 이하면 먼저 알려줘.)
2) 앱 진입점에서 '@wds/fonts/pretendard.css', '@wds/tokens/wds.css', '@wds/tokens/base.css', '@wds/ui-web/styles.css' 를 순서대로 불러오고, 앱 최상위 요소에 class="wds-root" 와 data-theme="light" 를 넣어줘. (이게 있어야 브랜드 폰트가 앱 전체에 적용돼.)
3) 아래 내용을 그대로 AGENTS.md 파일로 저장해줘:

# UI 규칙 (필수) — WIZ Design System(WDS)
위즈팩토리의 모든 솔루션 UI는 WDS로만 만든다. WDS는 컴포넌트·색·간격·타이포·radius·그림자·
레이아웃·모션까지 모든 디자인 요소를 정의한 단일 기준(SSOT)이다.
- 모든 화면 요소는 @wds/ui-web 컴포넌트로 만든다. 어떤 UI도 직접 만들지 않는다.
- 색·간격·radius·그림자·글꼴 등 모든 디자인 값은 @wds/tokens(--wds-* 변수)로만 쓴다. 하드코딩 금지.
- 레이아웃도 WDS 레이아웃 컴포넌트(Stack·Container·Grid·Split)로 구성한다.
- 다른 UI 라이브러리(shadcn·MUI·Chakra·Radix)·Tailwind·임의 CSS를 쓰지 않는다.
- 컴포넌트는 재구현하지 말고 import 한다. 전체 규칙은 https://wds.wiz-factory.net/llms.txt 를 따른다.

끝나면 WDS의 Button 컴포넌트로 버튼 하나를 화면에 띄워 잘 됐는지 확인해줘.

이제 한국어로 말하면 됩니다
설치가 끝나면 AI에게 평소 말하듯 시키세요. AI가 알아서 WDS 컴포넌트와 토큰으로 만들어 줍니다.
로그인 화면 만들어줘
카드 3개로 대시보드 만들어줘
이 버튼을 경고용 빨간 버튼으로 바꿔줘
알겠습니다 — WDS 컴포넌트와 토큰으로 만들게요. ✨

나중에: 최신으로 업데이트

디자인 시스템은 계속 고도화됩니다. 최신 버전으로 올리고 싶을 때 아래 프롬프트를 그대로 붙여넣으면, AI가 세 패키지(@wds/ui-web · @wds/tokens · @wds/fonts)를 함께 올리고 화면이 깨지지 않는지 확인해 줍니다.

AI에게 붙여넣기 (업데이트)

우리 회사 디자인 시스템(WIZ Design System) 패키지를 최신 버전으로 업데이트해줘.

1) @wds/ui-web, @wds/tokens, @wds/fonts 세 개를 함께 최신으로 올려줘. 이 프로젝트가 쓰는 패키지 매니저(npm·pnpm·yarn)를 그대로 써. 0.x 버전이라 캐럿(^)이 마이너 업을 막으니 반드시 @latest 를 붙여야 올라가. (npm → npm i @wds/ui-web@latest @wds/tokens@latest @wds/fonts@latest · pnpm → pnpm up @wds/ui-web@latest @wds/tokens@latest @wds/fonts@latest)
2) 올린 뒤 설치된 버전을 확인해서 알려줘(npm: npm ls · pnpm: pnpm ls). 만약 버전이 그대로면 캐시 때문일 수 있으니 캐시를 비우고(npm: npm cache clean --force · pnpm: pnpm store prune) 1)을 다시 해줘.
3) 화면이 깨지지 않는지 빌드해서 확인하고, 새로 올라간 버전과 바뀐 점을 알려줘. (무엇이 바뀌었는지는 https://wds.wiz-factory.net/docs/changelog 에서 확인할 수 있어.)

혹시 설치 중 401 인증 오류가 나면 .npmrc 의 토큰이 만료된 거야 — 관리자에게 새 토큰을 받아 .npmrc 의 _authToken 을 교체해야 한다고 알려줘.

무엇이 바뀌었는지는 체인지로그에서 봅니다. 설치할 때와 똑같이, 토큰은 AI 대화에 붙여넣지 않습니다.

0. 사전 준비. 비공개 레지스트리라 읽기 전용 토큰이 필요합니다(관리자에게 요청). 사내망(또는 VPN)에서 설치하세요.

1. .npmrc 설정. 프로젝트 루트에 .npmrc 를 만들고 아래를 넣습니다(발급받은_토큰 교체). https://wds.wiz-factory.net은 포털/문서 도메인이고, npm 패키지는 아래 self-hosted GitLab Package Registry 엔드포인트에서 내려받습니다.

@wds:registry=http://175.126.123.151:8000/api/v4/projects/99/packages/npm/
//175.126.123.151:8000/api/v4/projects/99/packages/npm/:_authToken=발급받은_토큰

실제 토큰을 넣은 .npmrc 는 git 에 커밋하지 마세요(.gitignore 에 추가). 더 안전하게는 토큰을 환경변수로 두고 _authToken=${WDS_NPM_TOKEN} 으로 참조합니다.

2. 설치. 컴포넌트는 React 19가 필요합니다 (React 18은 미지원 — ref-as-prop 계약).

pnpm add @wds/ui-web @wds/tokens @wds/fonts react@^19 react-dom@^19
# 또는: npm install @wds/ui-web @wds/tokens @wds/fonts react@^19 react-dom@^19

3. CSS 불러오기 + 루트 설정 (앱 진입점에서 한 번).

import '@wds/fonts/pretendard.css'; // 1) 브랜드 폰트 로드(@font-face)
import '@wds/tokens/wds.css'; // 2) --wds-* 토큰 변수
import '@wds/tokens/base.css'; // 3) .wds-root 베이스(box-sizing·타이포·폰트 적용)
import '@wds/ui-web/styles.css'; // 4) 컴포넌트 스타일

앱 최상위 요소에 class="wds-root" 를 주고, 테마는 같은(또는 상위) 요소의 data-theme 로 정합니다.

<body class="wds-root" data-theme="light">
  <!-- 앱 -->
</body>

⚠️ wds-root 가 있어야 박스 모델 · 타이포 기준선 · 브랜드 폰트(Pretendard)가 앱 전체에 적용됩니다. 없으면 WDS 컴포넌트만 브랜드 폰트로 나오고, 앱 셸·커스텀 텍스트는 시스템 폰트로 남습니다. 다크/브랜드 전환은 data-theme="dark" (+ 선택 data-brand) — 다크 모드 참고.

4. 사용 예 · 확인.

import { Button } from '@wds/ui-web';

export function Example() {
  return <Button variant="primary">시작하기</Button>;
}

✅ 잘 됐는지 확인: 이 버튼이 브랜드 색(WDS primary) 으로 보이고, 페이지 글자가 Pretendard(둥근 고딕)면 토큰 · 폰트 · wds-root 가 모두 적용된 것입니다.

5. 업데이트 (이미 설치한 솔루션). 세 패키지를 함께 올립니다(컴포넌트 CSS ↔ 토큰 ↔ 폰트 정합).

# 1) 현재 설치 버전 확인
pnpm ls @wds/ui-web @wds/tokens @wds/fonts
# 또는: npm ls @wds/ui-web @wds/tokens @wds/fonts

# 2) 최신으로 올리기 (0.x라 @latest 필수)
pnpm up @wds/ui-web@latest @wds/tokens@latest @wds/fonts@latest
# 또는: npm i @wds/ui-web@latest @wds/tokens@latest @wds/fonts@latest

# 3) 실제로 올라갔는지 재확인 — 버전이 그대로면 아래 캐시 안내 참고
pnpm ls @wds/ui-web @wds/tokens @wds/fonts
# 또는: npm ls @wds/ui-web @wds/tokens @wds/fonts

올린 뒤 한 번 빌드·확인하세요(버튼이 브랜드 색, 글자가 Pretendard로 보이면 정상). 어느 버전으로 올랐고 무엇이 바뀌었는지는 체인지로그에서 봅니다(패키지별 릴리스 노트 포함).

🔄 올렸는데 버전이 그대로면 pnpm 메타데이터 캐시 때문일 수 있습니다 — pnpm store prune 후 위 2)를 다시 실행하세요(게시 직후엔 @latest 메타가 캐시에 늦게 반영될 수 있음).

⚠️ 0.x 마이너는 수동 명시. 0.x 동안은 마이너(0.3→0.4)가 호환 깨짐 취급이라 일반 pnpm up은 ^0.3 범위를 넘지 않습니다. 마이너를 올릴 땐 위처럼 @latest(또는 @^0.4)로 명시하세요.

🔑 토큰이 갱신(순환)됐을 때. 이미 돌아가는 솔루션은 멈추지 않습니다 — 설치된 코드(node_modules)는 로컬에 있어 런타임 영향이 없습니다. 단 다음 설치/업데이트 때 옛 토큰이면 401이 납니다. 그땐 .npmrc의 _authToken만 새 토큰으로 교체(관리자에게 최신 토큰 요청)한 뒤 위 명령을 실행하세요.

🤖 더 자동화하려면(새 버전 게시 시 업데이트 MR 자동 생성) 의존성 봇(Renovate)을 붙일 수 있습니다 — 소비 레포 인프라 영역이며 별도 설정이 필요합니다.

6. 문제 해결.

401 / 인증 오류 — 토큰이 틀렸거나 만료됨. 관리자에게 최신 토큰을 받아 .npmrc 갱신.
연결 안 됨 / 타임아웃 — 사내망(VPN) 연결 확인. 레지스트리는 사내에서만 접근됩니다.
패키지 못 찾음 (404) — .npmrc 의 @wds:registry 주소 확인.
@wds/tokens/base.css 없음 — base.css export 는 @wds/tokens 0.4.0+ 부터입니다. pnpm up @wds/tokens@latest 로 올리세요.
CI/CD — 토큰을 .npmrc 에 직접 넣지 말고 ${WDS_NPM_TOKEN} 으로 두고 CI 환경변수/시크릿에 주입합니다(.npmrc 커밋 금지).
모노레포 — .npmrc 는 워크스페이스 루트에 한 번만 두면 하위 패키지 전체에 적용됩니다.

Flutter 제품은 npm이 아니라 wiz_ui(git 의존)로 씁니다 — Flutter 설치 가이드 참고.

자세한 소비 규칙(ref 전달 · 테스트 게이트 등)은 개발자 리소스를 참고하세요.

준비물

토큰을 내 컴퓨터에 저장

AI에게 설치 시키기

이제 한국어로 말하면 됩니다

나중에: 최신으로 업데이트