Bigtablet의 공통 UI 컴포넌트 및 디자인 시스템입니다.
Foundation(디자인 토큰)과 Components(UI 컴포넌트)를 분리하여 관리하며,
Storybook 기반 문서화와 Chromatic을 통한 시각적 테스트를 제공합니다.
- Foundation / Components 구조 분리
- Storybook 8 기반 문서화
- Chromatic 시각적 회귀 테스트
- Pure React / Next.js 분리 번들
- SCSS 기반 Design Token 관리
- pnpm + GitHub Actions 자동 배포
| Category | Technology |
|---|---|
| Framework | React 19 |
| Styling | SCSS |
| Documentation | Storybook 8 |
| Visual Test | Chromatic |
| Build | tsup |
| Package Manager | pnpm |
| CI / CD | GitHub Actions |
src/
├── styles/
│ ├── ts/ # Foundation Tokens (TypeScript)
│ │ ├── colors.ts
│ │ ├── spacing.ts
│ │ ├── typography.ts
│ │ ├── radius.ts
│ │ ├── shadows.ts
│ │ ├── motion.ts
│ │ ├── z-index.ts
│ │ ├── breakpoints.ts
│ │ └── a11y.ts
│ └── scss/ # SCSS Token & Mixins
│
├── ui/
│ ├── form/ # TextField, Checkbox, Radio, Switch, FileInput
│ ├── feedback/ # Alert, Toast, Loading
│ ├── navigation/ # Pagination, Sidebar
│ ├── overlay/ # Modal
│ ├── display/ # Card
│ ├── general/ # Button, Select
│ ├── skeleton/ # SkeletonCard, SkeletonList
│ └── styles/ # Shared component styles
│
├── index.ts # Pure React exports
└── next.ts # Next.js specific exportsBigtablet Design System은 Foundation과 Components 두 레이어로 구성됩니다.
Foundation은 디자인의 기준과 규칙을 정의하고,
Components는 이 기준을 사용해 실제 UI를 구성합니다.
Storybook 경로:
src/styles/ts/colors.tsFoundation은 모든 컴포넌트에서 공통으로 사용하는 디자인 기준입니다.
컴포넌트 구현 시, 임의의 값 사용을 금지하고 반드시 Foundation 토큰을 사용해야 합니다.
- 브랜드, 배경, 텍스트, 상태(success / error / warning) 색상
- 직접 색상 값 사용 금지
파일:
src/styles/ts/colors.ts- margin, padding, gap 기준 스케일
- 레이아웃 일관성 유지 목적
파일:
src/styles/ts/spacing.ts- 폰트 패밀리
- 폰트 크기, 굵기, 줄 간격
- Heading / Body / Caption 기준
파일:
src/styles/ts/typography.ts- 컴포넌트 모서리 둥글기 기준
- 카드, 버튼, 입력 필드 등 공통 사용
파일:
src/styles/ts/radius.ts- elevation 레벨 정의
- 카드, 모달, 드롭다운 등 깊이 표현
파일:
src/styles/ts/shadows.ts- transition duration
- easing curve 기준
파일:
src/styles/ts/motion.ts- 레이어 우선순위 정의
- modal, toast, dropdown 등
파일:
src/styles/ts/z-index.ts- 반응형 기준 해상도
권장 구분:
- mobile
- tablet
- laptop
- desktop
파일:
src/styles/ts/breakpoints.ts- 포커스 링 스타일
- 최소 터치 영역 크기
- 접근성 기준 토큰
파일:
src/styles/ts/a11y.ts예시:
focusRing
focusRingError
tapMinSizeStorybook 경로 규칙:
src/stories/components/name.stoires.tsxComponents는 Foundation 토큰을 기반으로 구현된 실제 UI 컴포넌트 레이어입니다.
모든 컴포넌트는 다음 원칙을 따릅니다.
- Foundation 토큰(colors, spacing, typography 등)만 사용
- 상태(hover, active, disabled, error 등) 명확히 정의
- 접근성(a11y) 기본 고려
- Storybook 문서 필수 제공
사용자 입력을 담당하는 컴포넌트들입니다.
- 기본 액션 버튼
- variant: primary / secondary / ghost / danger
- size: sm / md / lg
- 텍스트 입력 필드
- label, helperText 지원
- error / success 상태 지원
- leftIcon / rightIcon 지원
- 다중 선택 입력
- indeterminate 상태 지원
- 단일 선택 입력
- 동일한 name으로 그룹 구성
- ON / OFF 토글 입력
- controlled / uncontrolled 모두 지원
- 드롭다운 선택 컴포넌트
- 키보드 및 마우스 인터랙션 지원
- controlled / uncontrolled 모두 지원
- 파일 선택 입력
- 커스텀 UI 제공
사용자에게 상태 및 피드백을 전달하는 컴포넌트들입니다.
- 모달 형태의 알림
- info / success / warning / error variant
- confirm / cancel 액션 지원
- useAlert 훅 기반
- 인라인 로딩 스피너
- 크기 조절 가능
- 전역 토스트 메시지
- success / error / warning / info / message 타입 제공
- 내부적으로 react-toastify 사용
페이지 이동 및 흐름 제어 컴포넌트입니다.
- Prev / Next 기반 페이지네이션
- controlled 방식으로 상태 관리
- 좌측 네비게이션 메뉴
- 활성 경로 표시
- match 모드 지원 (startsWith / exact)
- Next.js 전용 컴포넌트
콘텐츠 위에 표시되는 레이어 컴포넌트입니다.
- 중앙 정렬 오버레이
- ESC / 오버레이 클릭 닫기 지원
- 제목 영역 optional
정보를 시각적으로 표현하는 컴포넌트입니다.
- 콘텐츠 그룹화용 컨테이너
- elevation 및 padding 포함
로딩 중 UI를 표현하는 컴포넌트입니다.
- 카드 형태 스켈레톤
- 리스트 형태 스켈레톤
foundation/
components/- 기본 상태(Default) 반드시 포함
- size / variant / state 예제 포함
- 디자이너가 봐도 이해 가능한 설명 작성
- 실제 사용 예제 위주 구성
- 불필요한 control 노출 지양