전략기획실 Design System

테크랩스 전략기획실에서 운영하는 사내 웹 어플리케이션 디자인 시스템. AI 자동화 도구 등 사내 프로젝트에 일관된 UI/UX를 적용하기 위해 사용한다.

| 항목 | 값 | |------|-----| | 디자인 톤 | Soft Bold (부드러운 그림자 + 강한 타이포) | | Primary | Teal (#14b8a6) | | Secondary | Indigo (#6366f1) | | Tertiary | Blue (#3b82f6) | | 스택 | React + Tailwind CSS | | 폰트 | Manrope | | 아이콘 | Material Symbols Outlined |

프리뷰

open preview/index.html

브라우저에서 모든 컴포넌트/토큰/레이아웃을 실제 렌더링으로 확인할 수 있다.

파일 구조 & 역할

이 프로젝트의 파일은 크게 2가지 용도로 나뉜다.

1) 참고 문서 — 이 프로젝트에서 읽고 확인하는 파일

디자인 시스템의 상세 스펙. 컴포넌트를 만들거나 수정할 때 참고한다.

design-system/
├── tokens/                          # 디자인 토큰 (시스템의 기초 값)
│   ├── colors.md                    # 컬러 팔레트 — Primary/Secondary/Tertiary/Semantic/Surface/Text 전체 정의
│   ├── typography.md                # 타이포그래피 — Manrope 폰트, 7단계 스케일 (Display~Caption)
│   ├── spacing.md                   # 간격 — 4px 기반 스케일 (4/8/12/16/24/32)
│   ├── radius.md                    # 라운딩 — 6px(뱃지) / 10px(버튼) / 14px(카드) / full(아바타)
│   ├── shadows.md                   # 그림자 — teal 틴트 4단계 (soft-sm ~ soft-xl)
│   └── tailwind-config.md           # Tailwind 설정 — 프로젝트에 복사할 수 있는 완전한 config
│
├── components/                      # UI 컴포넌트 (각각 Tailwind 클래스 + React 코드 예시 포함)
│   ├── buttons.md                   # 버튼 — Primary/Secondary/Outline/Ghost/Danger, 3사이즈, 아이콘, 로딩
│   ├── badges.md                    # 뱃지 — 상태 뱃지 5종, dot 라벨, 카운트 뱃지
│   ├── inputs.md                    # 인풋 — 텍스트, Number, 검색, 셀렉트, 토글, 체크박스, 라디오, Slider, 텍스트에리어
│   ├── cards.md                     # 카드 — Stat(KPI), Tool(도구 목록), Empty(빈 상태)
│   ├── table.md                     # 테이블 — Toolbar + Header + Row + Pagination 전체 구조 + 독립 Pagination
│   ├── modal.md                     # 모달 — 일반 + Confirm(위험 액션) 변형, 접근성
│   ├── toast.md                     # 토스트 — Success/Error/Warning/Info 4종, duration override, 자동 dismiss 규칙
│   ├── avatar.md                    # Avatar — 프로필 이미지/fallback initials, size/status 표시
│   ├── dropdown-menu.md             # Dropdown Menu — 계정/액션 메뉴, 키보드 접근성, viewport 위치 보정
│   ├── user-menu.md                 # User Menu — Avatar + DropdownMenu 기반 계정 메뉴 패턴
│   ├── integration-status-card.md   # Integration Status Card — 외부 연동 상태와 재연결/해제 액션
│   ├── tooltip.md                   # 툴팁 — hover 트리거, 위치 변형, group-hover 통일
│   ├── description-list.md          # Description List — Key-Value 수직/2열 그리드
│   ├── upload.md                    # Upload — 드래그 앤 드롭, 상태별 스타일
│   ├── callout.md                   # Callout — 인라인 맥락 알림 4종 (info/warning/error/tip)
│   └── bulk-action-bar.md           # Bulk Action Bar — 다중 선택 시 등장하는 sticky 액션 바
│
├── patterns/                        # 레이아웃 & 패턴
│   ├── layout-shell.md              # 레이아웃 셸 — 사이드바(220px) + 탑바(48px) + 콘텐츠 전체 코드
│   ├── page-templates.md            # 페이지 템플릿 — Dashboard/List/Detail/Form/Empty 5종
│   ├── navigation.md                # 네비게이션 — Breadcrumb, Tabs, Pill Tabs/Segmented Control
│   └── stepper.md                   # Stepper — 다단계 진행 표시 (기본 + 컴팩트)
│
└── guidelines/                      # UX 가이드라인
    ├── ux-principles.md             # UX 원칙 — 5대 원칙 (명확한 위계, 즉각적 피드백, 비개발자 우선, 일관된 패턴, 안전한 실행)
    ├── interaction.md               # 인터랙션 — 트랜지션, Hover/Focus, Skeleton/Spinner, Collapsible 애니메이션
    ├── accessibility.md             # 접근성 — WCAG AA 대비율, 키보드 네비게이션, ARIA, focus trap
    ├── responsive.md                # 반응형 — Desktop 우선, 4단계 breakpoint, 테이블→카드 변환
    ├── icons.md                     # 아이콘 — Material Symbols 설정, 3사이즈(16/20/24), 자주 쓰는 아이콘 목록
    └── data-display.md              # 데이터 표현 — 숫자(콤마+변화율), 시간(상대/절대), 비율(progress bar), 상태(뱃지)

preview/
└── index.html                       # 라이브 프리뷰 — 브라우저에서 열면 모든 컴포넌트 확인 가능

2) 주입 파일 — 다른 프로젝트에 복사하여 사용하는 파일

skills/
└── SKILL.md                         # Claude Code 주입용 축약 가이드
                                     #   → 위 참고 문서의 핵심만 추출한 단일 파일
                                     #   → 다른 프로젝트의 .claude/skills/에 복사하면
                                     #      Claude Code가 UI 작업 시 자동으로 디자인 시스템을 따름

design-system/tokens/tailwind-config.md  # Tailwind 설정 참조
                                     #   → 안의 config를 대상 프로젝트의 tailwind.config.js에 복사

기타 파일

CLAUDE.md                            # Claude Code가 이 프로젝트에서 작업할 때 따르는 규칙
README.md                            # 이 파일
vitest.config.mts                    # Vitest 테스트 설정
src/                                 # React 컴포넌트 라이브러리 소스와 단위 테스트

다른 프로젝트에 적용하기

Step 1. SKILL.md 복사

mkdir -p /path/to/your-project/.claude/skills
cp skills/SKILL.md /path/to/your-project/.claude/skills/SKILL.md

Step 2. Claude Code에 프롬프트 (아래 상황에 맞게 사용)

프롬프트에 @.claude/skills/SKILL.md를 포함하면 Claude Code가 디자인 시스템을 확실히 인식한다. SKILL.md가 .claude/skills/에 있으면 자동 로드되지만, 첫 적용 시에는 @로 명시적 지정을 권장.

새 프로젝트 or 전체 적용

@.claude/skills/SKILL.md 를 참고해서 이 프로젝트 전체에 CP 디자인 시스템을 적용해줘.

1. tailwind.config에 CP 디자인 시스템 설정 반영
2. 폰트(Manrope)와 아이콘(Material Symbols) CDN 추가
3. 레이아웃을 CP 디자인 시스템의 Layout Shell로 교체 (사이드바 220px + 탑바 48px)
4. 모든 컴포넌트를 CP 디자인 시스템 스타일로 교체
5. 기존 기능과 데이터는 모두 유지하고 UI만 변경

기존 디자인이 있는 프로젝트 — 단계적 적용 (권장)

1단계: 기반 설정

@.claude/skills/SKILL.md 를 참고해서 기반 설정부터 적용해줘.
1. tailwind.config에 CP 디자인 시스템의 fontFamily와 boxShadow 설정을 추가해줘 (기존 설정 유지하면서 extend)
2. HTML head에 Manrope 폰트와 Material Symbols Outlined CDN을 추가해줘
3. 기존 코드는 아직 건드리지 마

2단계: 레이아웃 셸

@.claude/skills/SKILL.md 를 참고해서 레이아웃 셸을 적용해줘.
- 사이드바(220px) + 탑바(48px) + 콘텐츠 영역 구조로 변경
- 기존 페이지 콘텐츠는 콘텐츠 영역 안에 유지
- 기존 네비게이션 메뉴 항목은 그대로 사이드바로 옮겨줘

3단계: 페이지별 적용

@.claude/skills/SKILL.md 를 참고해서 [페이지명] 페이지를 리디자인해줘.
- 기존 기능/데이터는 모두 유지
- CP 디자인 시스템의 컴포넌트(버튼, 카드, 테이블 등)로 교체
- 컬러는 Primary(Teal), Success(Green) 등 시맨틱 컬러 체계 적용

업데이트 시

cd /path/to/CP-design-system && git pull
cp skills/SKILL.md /path/to/your-project/.claude/skills/cp-design-system.md

Tailwind 설정이 바뀌었다면 tailwind-config.md도 다시 확인.

버전 관리

태그 규칙

git tag -a v1.0.0 -m "Initial design system release"     # 최초 릴리즈
git tag -a v1.1.0 -m "Add card component variant"         # 컴포넌트/토큰 추가
git tag -a v1.0.1 -m "Fix button hover class"             # 오타/클래스 수정
git tag -a v2.0.0 -m "Change primary color to blue"       # 컬러 체계 등 대규모 변경

변경 시 동기화 체크리스트

이 프로젝트의 어떤 파일이든 변경할 때, 반드시 아래 파일들을 함께 확인/업데이트해야 한다.

| 내가 변경한 것 | 반드시 함께 업데이트 | |--------------|-------------------| | 컬러 (colors.md) | shadows.md, tailwind-config.md, SKILL.md, preview/index.html | | 타이포 (typography.md) | tailwind-config.md, SKILL.md, preview/index.html | | 간격/라운딩/그림자 | tailwind-config.md, SKILL.md, preview/index.html | | 컴포넌트 (buttons.md 등) | SKILL.md, preview/index.html | | 레이아웃/패턴 | SKILL.md | | 가이드라인 | SKILL.md |

핵심: SKILL.md와 preview/index.html은 거의 모든 변경에 함께 업데이트해야 한다.

Claude Code를 사용하면 CLAUDE.md의 규칙에 따라 이 동기화가 자동으로 이루어진다.