ClaBi Storybook

AI 에이전트 작업용 가이드 파일입니다. 아래 파일을 받아 프로젝트 루트폴더에 두고, 에이전트 컨텍스트에 포함하면 이 페이지의 Installation·복사 규칙을 바로 따릅니다.

# 1) 소비 앱(또는 작업) 루트에 저장
#    e.g. ~/my-app/UI_GUIDE.md

# 2) Cursor / Claude 등에 이 파일을 컨텍스트로 첨부·@ 멘션
#    또는 채팅에 "UI_GUIDE.md 규칙 따라 구현해줘" + 화면/요구사항

# 3) (선택) 최신을 다시 받을 때 — 카탈로그가 떠 있는 호스트 기준
# curl -fsSL "https://<storybook-host>/UI_GUIDE.md" -o UI_GUIDE.md

# 규칙 요약: Storybook 소스만 · tokens.json 기준
#            clabi_ds 클론 금지 · 컴포넌트는 src/components/ui/

우선순위: (1) 디자인 토큰 기본값 → (2) 소비 앱 globals에서 동일 변수명 재정의 → (3) 인스턴스 className 등. 컴포넌트 안의 변수명(--surface-primary 등)은 바꾸지 않습니다.

1. 앱 준비— React 19 · Tailwind CSS v4 · clsx. alias @/ 맞춤.
2. 디자인 토큰 확보— 컴포넌트가 쓰는 것은 tokens.css입니다. 만드는 방법은 둘 중 하나.
   • A. Storybook의 빌드된 src/styles/tokens.css를 복사 (가장 단순).
   • B. tokens.json을 직접 받았다면 scripts/build-tokens.mjs를 함께 두고, 앱 루트에서 node scripts/build-tokens.mjs --build→ src/styles/tokens.css생성. (JSON 위치: tokens/tokens.json. clabi_ds sync는 불필요.)
3. clabi-theme · components 복사— clabi-theme.css= 변수명 → Tailwind 매핑. 필요한 src/components/…· clsx(npm). Storybook app/globals.css· catalog/*는 복사하지 않음. 아래 Installation을 참고하세요.
4. 앱 globals에서 import (토큰 먼저)— 기본은 토큰. 바꿀 변수만 앱 globals에서 같은 이름으로 다시 정의하면 소비 앱 값이 이깁니다.

/* 소비 앱 app/globals.css (앱 소유 — Storybook globals 복사 금지) */
@import "tailwindcss";
@import "../styles/tokens.css";       /* ① 기본값 = 디자인 토큰 (A 복사 또는 B 빌드) */
@import "../styles/clabi-theme.css";  /* 변수명 → Tailwind 유틸 */

/* ② 같은 이름이 있으면 소비 앱이 우선 (필요할 때만) */
:root {
  --surface-primary: #0f766e;
  --text-primary: #0f766e;
  --border-primary: #0f766e;
  --action-primary-hover: #0d9488;
  --action-primary-pressed: #0f766e;
}

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

5. 사용— 변수 재정의가 없으면 Button 등은 토큰 기본색. 앱 globals에 --surface-primary를 넣었으면 그 색이 전역으로 적용. 한 인스턴스만 다를 때만 className 등.

import { Button } from "@/components/button";

{/* 앱이 변수를 안 덮으면 → tokens.css 기본값 */}
{/* 앱 globals에 --surface-primary가 있으면 → 그 값 */}
<Button>저장</Button>

{/* ③ 이 버튼만 예외 */}
<Button className="bg-emerald-500 hover:bg-emerald-600">예외</Button>

(선택) Pretendard가 필요하면 styles/fonts.css와 public/fonts를 복사하고 layout에서 fonts.css를 import합니다.

패키지 설치가 아니라 파일 복사입니다. GitLab 접근 권한이 있는 계정으로 clone한 뒤, 필요한 경로만 앱으로 옮기세요. 디자인 토큰은 A(빌드된 CSS)또는 B(tokens.json 직접 빌드)중 하나를 고르면 됩니다.

# HTTPS
git clone https://gitlab.clabi.co.kr/clabi/projects/storybook.git storybook

# 또는 SSH
git clone git@gitlab.clabi.co.kr:clabi/projects/storybook.git storybook

# 소비 앱 루트에서 (경로·컴포넌트명은 프로젝트에 맞게)
mkdir -p src/styles src/components
cp storybook/src/styles/tokens.css src/styles/
cp storybook/src/styles/clabi-theme.css src/styles/
cp -R storybook/src/components/button src/components/

# className 병합은 컴포넌트가 clsx를 직import합니다
# 소비 앱: npm i clsx

# 소비 앱 루트 기준 구조
#   scripts/build-tokens.mjs
#   tokens/tokens.json          ← Token Studio export
#   src/styles/clabi-theme.css
#   src/styles/tokens.css       ← 빌드 결과 (생성됨)

mkdir -p scripts tokens src/styles src/components
cp storybook/scripts/build-tokens.mjs scripts/
cp storybook/tokens/tokens.json tokens/   # 또는 디자인에서 받은 JSON
cp storybook/src/styles/clabi-theme.css src/styles/
cp -R storybook/src/components/button src/components/

# JSON → tokens.css
node scripts/build-tokens.mjs --build

# tokens.json을 갱신할 때마다 다시 --build

git clone --filter=blob:none --sparse https://gitlab.clabi.co.kr/clabi/projects/storybook.git storybook
cd storybook

# 경로 A용
git sparse-checkout set \
  src/styles/tokens.css \
  src/styles/clabi-theme.css \
  src/components/button

# 경로 B용 (JSON 빌드)
# git sparse-checkout set \
#   scripts/build-tokens.mjs \
#   tokens/tokens.json \
#   src/styles/clabi-theme.css \
#   src/components/button

# 이후 소비 앱으로 cp · npm i clsx

cd storybook
git pull
# 경로 A: tokens.css · clabi-theme · components 다시 cp
# 경로 B: tokens.json (또는 build-tokens.mjs) 갱신 후
#         node scripts/build-tokens.mjs --build

• 저장소: https://gitlab.clabi.co.kr/clabi/projects/storybook.git
• 복사/빌드 후 소비 앱 globals.css에 tokens → clabi-theme import를 연결합니다 (위 「사용 순서」).
• catalog/* · app/globals.css는 가져가지 않습니다. scripts/ 전체는 불필요 — 토큰 CSS만이면 build-tokens.mjs면 충분합니다.

컴포넌트·토큰 파일의 변수명은 유지합니다. 소비 앱 globals에서 동일한 변수를 다시 선언하면 CSS 캐스케이드상 앱 값이 우선합니다. 선언하지 않으면 tokens.css 기본값이 그대로 쓰입니다.

@import "../styles/tokens.css";      /* default */
@import "../styles/clabi-theme.css";

/* 덮을 변수만 — 이름 동일 */
:root {
  --surface-primary: #0f766e;
}

• import 순서: tokens → clabi-theme → (그 다음) 앱 :root 재정의.
• Light/Dark는 .dark 에서 같은 이름을 다르게 정의합니다.
• 한 인스턴스만 바꿀 때는 전역 변수 대신 className.

사이드바에서 컴포넌트 → Overview·Docs를 확인한 뒤, Installation대로 토큰(A: tokens.css 또는 B: tokens.json + build-tokens) · clabi-theme · 컴포넌트를 가져가세요. 이 카탈로그에 컴포넌트를 추가할 때는 스토리북 개발자들을 위한 내부 문서를 보세요.