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 채팅에 넣으면 대화 기록에 남아 유출될 수 있습니다. 아래처럼 내 컴퓨터에만 저장하세요.
본인 컴퓨터의 운영체제를 고르고, 터미널을 열어 만들 프로젝트 폴더에서 명령을 붙여넣으세요 (받은토큰 자리만 받은 토큰으로 교체).
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 는 이미 만들어 뒀어)
2) 앱 진입점에서 '@wds/fonts/pretendard.css', '@wds/tokens/wds.css', '@wds/ui-web/styles.css' 를 순서대로 불러와줘.
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 컴포넌트와 토큰으로 만들게요. ✨

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

1. .npmrc 설정. 프로젝트 루트에 .npmrc 를 만들고 아래를 넣습니다(발급받은_토큰 교체).

@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. 설치.

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

3. CSS 불러오기 (앱 진입점에서 한 번, 토큰 → 컴포넌트 순서).

import '@wds/fonts/pretendard.css'; // 브랜드 폰트(Pretendard) — 가장 먼저
import '@wds/tokens/wds.css';
import '@wds/ui-web/styles.css';

테마는 루트 요소의 data-theme="light" 또는 data-theme="dark" 로 전환합니다 (다크 모드 참고).

4. 사용 예.

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

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

5. 업데이트. 새 버전이 나오면 두 패키지를 함께 올립니다(컴포넌트 CSS ↔ 토큰 정합).

pnpm up @wds/ui-web @wds/tokens

6. 문제 해결.

401 / 인증 오류 — 토큰이 틀렸거나 만료됨. 관리자에게 최신 토큰을 받아 .npmrc 갱신.
연결 안 됨 / 타임아웃 — 사내망(VPN) 연결 확인. 레지스트리는 사내에서만 접근됩니다.
패키지 못 찾음 (404) — .npmrc 의 @wds:registry 주소 확인.

Flutter 제품은 npm이 아니라 wiz_ui(git 의존)로 씁니다 — 개발자 리소스 참고.

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

준비물

토큰을 내 컴퓨터에 저장

AI에게 설치 시키기

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