DTA-WI-Design-System 구현 계획서

1. 프로젝트 개요

1.1 목적

SleepQ 디자인 시스템 문서를 인터랙티브 웹 페이지로 구현하여, 개발자와 디자이너가 컴포넌트를 시각적으로 확인하고 코드를 쉽게 복사할 수 있도록 합니다.

1.2 참조

• Supabase Design System: /refs/supabase/apps/design-system - 구조 및 패턴 참조
• 기존 Design System 문서: /apps/dta-wi-doc/docs/application/dta-wide-app/design-system/ - 컨텐츠 소스

1.3 기술 스택

• Framework: Next.js 15+ (App Router)
• UI Components: shadcn/ui + Radix UI (Supabase 패턴 참조)
• Styling: Tailwind CSS + class-variance-authority (CVA)
• MDX Processing: Contentlayer2
• Code Highlighting: Shiki + rehype-pretty-code
• Monorepo: NX Workspace

Note: Supabase Design System은 자체 UI 컴포넌트와 함께 shadcn/ui 컴포넌트를 _Shadcn_ 접미사로 export하여 사용합니다. 우리도 동일한 패턴을 적용합니다.

---

2. 프로젝트 구조

2.1 디렉토리 구조

apps/dta-wi-design-system/
├── app/
│   ├── layout.tsx              # 루트 레이아웃
│   ├── Providers.tsx           # ThemeProvider, etc.
│   ├── globals.css             # 전역 스타일
│   ├── (app)/
│   │   ├── layout.tsx          # 앱 레이아웃 (사이드바 + 메인)
│   │   ├── page.tsx            # 홈페이지
│   │   └── docs/
│   │       └── [[...slug]]/
│   │           └── page.tsx    # 동적 문서 페이지
│   └── fonts/                  # Pretendard 폰트
├── components/
│   ├── mdx-components.tsx      # MDX 커스텀 컴포넌트
│   ├── component-preview.tsx   # 컴포넌트 프리뷰
│   ├── code-block.tsx          # 코드 블록
│   ├── color-palette.tsx       # 색상 팔레트 표시
│   ├── typography-table.tsx    # 타이포그래피 테이블
│   ├── side-navigation.tsx     # 사이드 네비게이션
│   ├── top-navigation.tsx      # 상단 네비게이션
│   ├── toc.tsx                 # 목차 (Table of Contents)
│   └── copy-button.tsx         # 코드 복사 버튼
├── config/
│   └── docs.ts                 # 사이드바 네비게이션 설정
├── content/
│   └── docs/                   # MDX 문서 파일들
│       ├── index.mdx
│       ├── foundation/
│       │   ├── colors.mdx
│       │   ├── typography.mdx
│       │   ├── spacing.mdx
│       │   ├── border-radius.mdx
│       │   └── shadows.mdx
│       ├── components/
│       │   ├── button.mdx
│       │   ├── input.mdx
│       │   └── ...
│       ├── patterns/
│       │   ├── form-validation.mdx
│       │   └── ...
│       └── icons/
│           ├── icon-library.mdx
│           └── usage-guidelines.mdx
├── lib/
│   ├── themes/
│   │   └── sleepq-theme.json   # Shiki 커스텀 테마
│   └── utils.ts                # 유틸리티 함수
├── registry/                   # 컴포넌트 레지스트리 (선택적)
│   ├── examples.ts
│   └── default/
│       └── example/
├── styles/
│   └── design-tokens.css       # 디자인 토큰 CSS 변수
├── types/
│   └── nav.d.ts
├── contentlayer.config.ts      # Contentlayer 설정
├── next.config.mjs
├── tailwind.config.js
├── tsconfig.json
├── project.json                # NX 프로젝트 설정
└── package.json                # 로컬 의존성 (선택적)

2.2 NX Project 설정

project.json

{
  "name": "dta-wi-design-system",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "apps/dta-wi-design-system",
  "projectType": "application",
  "tags": ["scope:web", "type:docs"],
  "targets": {
    "build": {
      "executor": "@nx/next:build",
      "outputs": ["{options.outputPath}"],
      "defaultConfiguration": "production",
      "options": {
        "root": "apps/dta-wi-design-system",
        "outputPath": "dist/apps/dta-wi-design-system"
      },
      "configurations": {
        "development": {
          "dev": true
        },
        "production": {
          "dev": false
        }
      }
    },
    "serve": {
      "executor": "@nx/next:server",
      "defaultConfiguration": "development",
      "options": {
        "buildTarget": "dta-wi-design-system:build",
        "port": 3030
      },
      "configurations": {
        "development": {
          "buildTarget": "dta-wi-design-system:build:development"
        },
        "production": {
          "buildTarget": "dta-wi-design-system:build:production"
        }
      }
    },
    "content:dev": {
      "executor": "nx:run-commands",
      "options": {
        "command": "contentlayer2 dev",
        "cwd": "apps/dta-wi-design-system"
      }
    },
    "content:build": {
      "executor": "nx:run-commands",
      "options": {
        "command": "contentlayer2 build",
        "cwd": "apps/dta-wi-design-system"
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "outputs": ["{options.outputFile}"],
      "options": {
        "lintFilePatterns": ["apps/dta-wi-design-system/**/*.{ts,tsx,js,jsx}"]
      }
    }
  }
}

---

3. 핵심 기능 구현

3.1 컨텐츠 변환 (MD → MDX)

기존 마크다운 문서를 MDX로 변환하고 인터랙티브 요소 추가:

기존 (colors.md)

## 1. Primitive Colors (기본 색상 팔레트)

| Token Name | Hex       | sRGB               | 용도          |
| ---------- | --------- | ------------------ | ------------- |
| `blue50`   | `#E0EAFF` | rgb(224, 234, 255) | 브랜드 액센트 |

변환 후 (colors.mdx)

---
title: Colors (색상)
description: SleepQ 앱에서 사용하는 색상 시스템입니다.
---

## Primitive Colors (기본 색상 팔레트)

<ColorPalette
  colors={[
    { name: 'blue50', hex: '#E0EAFF', usage: '브랜드 액센트, 하이라이트 배경' },
    { name: 'blue500', hex: '#6993E3', usage: '보조 브랜드 컬러, 서브 액션' },
    { name: 'blue700', hex: '#3651B2', usage: '메인 브랜드 컬러, CTA 버튼' },
  ]}
/>

3.2 주요 MDX 컴포넌트

3.2.1 ColorPalette

색상을 시각적으로 표시하고 복사 기능 제공

interface ColorPaletteProps {
  colors: Array<{
    name: string;
    hex: string;
    usage: string;
  }>;
}

3.2.2 TypographyTable

타이포그래피 스케일을 실제 렌더링과 함께 표시

interface TypographyTableProps {
  styles: Array<{
    token: string;
    size: string;
    weight: string;
    lineHeight: string;
    usage: string;
  }>;
}

3.2.3 ComponentPreview

컴포넌트를 렌더링하고 코드 표시

interface ComponentPreviewProps {
  name: string; // 컴포넌트 이름
  align?: 'center' | 'start' | 'end';
  showCode?: boolean;
  platforms?: ('web' | 'ios' | 'android')[];
}

3.2.4 SpacingScale

간격 토큰을 시각적으로 표시

3.2.5 IconGrid

아이콘 라이브러리 표시 및 검색

---

4. 네비게이션 구조

4.1 사이드바 구성 (config/docs.ts)

export const docsConfig = {
  sidebarNav: [
    {
      title: 'Getting Started',
      items: [
        { title: 'Introduction', href: '/docs', items: [] },
        { title: 'Design Principles', href: '/docs/principles', items: [] },
        { title: 'Brand Identity', href: '/docs/brand', items: [] },
      ],
    },
    {
      title: 'Foundation',
      items: [
        { title: 'Colors', href: '/docs/foundation/colors', items: [] },
        { title: 'Typography', href: '/docs/foundation/typography', items: [] },
        { title: 'Spacing', href: '/docs/foundation/spacing', items: [] },
        { title: 'Border Radius', href: '/docs/foundation/border-radius', items: [] },
        { title: 'Shadows', href: '/docs/foundation/shadows', items: [] },
      ],
    },
    {
      title: 'Components',
      items: [
        { title: 'Button', href: '/docs/components/button', items: [] },
        { title: 'Input', href: '/docs/components/input', items: [] },
        { title: 'Card', href: '/docs/components/card', items: [] },
        { title: 'Checkbox', href: '/docs/components/checkbox', items: [] },
        { title: 'Radio', href: '/docs/components/radio', items: [] },
        { title: 'Modal', href: '/docs/components/modal', items: [] },
        { title: 'Bottom Sheet', href: '/docs/components/bottom-sheet', items: [] },
        { title: 'Navigation Bar', href: '/docs/components/navigation-bar', items: [] },
        { title: 'Tab', href: '/docs/components/tab', items: [] },
        { title: 'Topbar', href: '/docs/components/topbar', items: [] },
        { title: 'Topboard', href: '/docs/components/topboard', items: [] },
        { title: 'Progress Bar', href: '/docs/components/progress-bar', items: [] },
        { title: 'Tooltip', href: '/docs/components/tooltip', items: [] },
        { title: 'List', href: '/docs/components/list', items: [] },
        { title: 'Chip', href: '/docs/components/chip', items: [] },
        { title: 'Info Box', href: '/docs/components/info-box', items: [] },
        { title: 'Chart', href: '/docs/components/chart', items: [] },
        // ... 추가 컴포넌트들
      ],
    },
    {
      title: 'Patterns',
      items: [
        { title: 'Form Validation', href: '/docs/patterns/form-validation', items: [] },
        { title: 'Loading States', href: '/docs/patterns/loading-states', items: [] },
        { title: 'Error Handling', href: '/docs/patterns/error-handling', items: [] },
        { title: 'Settings Screen', href: '/docs/patterns/settings-screen', items: [] },
        // ... 추가 패턴들
      ],
    },
    {
      title: 'Icons',
      items: [
        { title: 'Icon Library', href: '/docs/icons/library', items: [] },
        { title: 'Usage Guidelines', href: '/docs/icons/guidelines', items: [] },
      ],
    },
  ],
};

---

5. 디자인 토큰 CSS 변수

5.1 styles/design-tokens.css

:root {
  /* ===== Primitive Colors ===== */
  --color-blue-50: #e0eaff;
  --color-blue-500: #6993e3;
  --color-blue-700: #3651b2;

  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-200: #e5e6eb;
  --color-gray-300: #d1d3db;
  --color-gray-400: #9e9fad;
  --color-gray-500: #6e717d;
  --color-gray-900: #1a1b1e;

  --color-red-500: #ff176a;
  --color-yellow-500: #ffba33;

  /* ===== Semantic Colors ===== */
  --color-bg-primary: var(--color-gray-50);
  --color-bg-secondary: var(--color-gray-100);
  --color-bg-tertiary: #ffffff;
  --color-bg-highlighted: var(--color-blue-700);

  --color-text-primary: var(--color-gray-900);
  --color-text-secondary: var(--color-gray-500);
  --color-text-tertiary: var(--color-gray-300);
  --color-text-inverse: #ffffff;
  --color-text-highlighted: var(--color-blue-700);
  --color-text-error: var(--color-red-500);

  /* ===== Typography ===== */
  --font-family-primary: 'Pretendard', -apple-system, BlinkMacSystemFont, sans-serif;

  --font-size-xs: 12px;
  --font-size-sm: 14px;
  --font-size-md: 16px;
  --font-size-lg: 18px;
  --font-size-xl: 20px;
  --font-size-2xl: 24px;
  --font-size-3xl: 32px;

  --font-weight-regular: 400;
  --font-weight-medium: 500;
  --font-weight-bold: 700;

  --line-height-tight: 1.2;
  --line-height-normal: 1.44;
  --line-height-relaxed: 1.74;

  /* ===== Spacing ===== */
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-3: 12px;
  --spacing-4: 16px;
  --spacing-5: 20px;
  --spacing-6: 24px;
  --spacing-8: 32px;
  --spacing-10: 40px;

  /* ===== Border Radius ===== */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-xl: 16px;
  --radius-full: 9999px;

  /* ===== Shadows ===== */
  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
  --shadow-lg: 0 10px 25px rgba(0, 0, 0, 0.1);
}

---

6. 구현 단계 (Phase)

Phase 1: 프로젝트 초기 설정 ⏱️ ~2시간 ✅ COMPLETED

1. ✅ NX로 Next.js 애플리케이션 생성
2. ✅ project.json 설정 (포트 3030, tags 추가)
3. ✅ shadcn/ui 초기화 및 기본 컴포넌트 설치
   • globals.css (CSS 변수, Tailwind v4 @import 문법)
   • lib/utils.ts (cn 유틸리티)
   • UI 컴포넌트: button, card, badge, tabs, scroll-area, separator, tooltip
   • Radix UI 의존성 설치
4. ✅ Contentlayer2 설정
   • contentlayer.config.ts (MDX 문서 타입 정의)
   • next.config.js (createContentlayerPlugin 통합)
   • content/docs/ 디렉토리 및 샘플 MDX 파일 생성
   • .gitignore에 .contentlayer 추가
   • next-mdx-remote RSC 방식으로 MDX 렌더링
5. ✅ Tailwind CSS 설정 (SleepQ 디자인 토큰 적용)
   • Tailwind CSS v4 사용 (@tailwindcss/postcss 플러그인)
   • styles/design-tokens.css (CSS 변수로 디자인 토큰 정의)
   • @tailwindcss/typography, tailwindcss-animate 플러그인 설치
   • globals.css에 design-tokens import
6. ✅ 기본 레이아웃 구성
   • config/docs.ts (사이드바 네비게이션 설정)
   • components/side-navigation.tsx (좌측 사이드바)
   • components/top-navigation.tsx (상단 네비게이션)
   • components/mdx-components.tsx (MDX 커스텀 컴포넌트)
   • app/docs/layout.tsx (문서 레이아웃)
   • app/docs/[[...slug]]/page.tsx (동적 문서 페이지)
   • app/page.tsx (홈페이지)

Phase 2: 핵심 컴포넌트 개발 ⏱️ ~4시간 ✅ COMPLETED

1. ✅ shadcn/ui 기반 UI 컴포넌트 커스터마이징
   • Button, Card, Tabs, ScrollArea, Badge, Separator, Tooltip, Collapsible
2. ✅ MDX 기본 컴포넌트 (heading, code, table 등) - components/mdx-components.tsx
3. ✅ ColorPalette 컴포넌트 - components/color-palette.tsx
   • ColorPalette, ColorGroup, SemanticColorCard, SemanticColorGroup
4. ✅ TypographyTable 컴포넌트 - components/typography-table.tsx
   • TypographyTable, TypographyScale, TypographyShowcase
5. ✅ ComponentPreview 컴포넌트 - components/component-preview.tsx
   • ComponentPreview (with iOS/Android/Web tabs), PreviewCard, StatePreview
6. ✅ CodeBlock with Copy 버튼 - components/code-block.tsx
   • CodeBlock, InlineCode, CopyButton, CommandLine
7. ✅ SpacingScale, ShadowScale 컴포넌트 - components/spacing-scale.tsx
   • SpacingScale, SpacingGrid, BorderRadiusScale, ShadowScale

Phase 3: 네비게이션 구현 ⏱️ ~2시간 ✅ COMPLETED

1. ✅ SideNavigation 컴포넌트 (ScrollArea 활용) - Phase 1에서 완료
2. ✅ TopNavigation 컴포넌트 - Phase 1에서 완료
3. ✅ TableOfContents (TOC) 컴포넌트 - components/toc.tsx
   • TableOfContents, TocFromContent, DynamicToc
4. ✅ 모바일 반응형 네비게이션 (Sheet 컴포넌트 활용)
   • components/ui/sheet.tsx (Radix Dialog 기반)
   • components/mobile-nav.tsx (모바일 사이드바)
5. ✅ Command 팔레트 검색 (cmdk 활용)
   • components/ui/command.tsx (cmdk 기반)
   • components/ui/dialog.tsx (Radix Dialog)
   • components/command-menu.tsx (⌘K로 검색 가능)

Phase 4: Foundation 문서 변환 ⏱️ ~3시간 ✅ COMPLETED

1. ✅ Colors 페이지 - ColorPalette, SemanticColorGroup 컴포넌트 활용
2. ✅ Typography 페이지 - TypographyShowcase, TypographyTable 컴포넌트 활용
3. ✅ Spacing 페이지 - SpacingScale 컴포넌트 활용
4. ✅ Border Radius 페이지 - BorderRadiusScale 컴포넌트 활용
5. ✅ Shadows 페이지 - ShadowScale 컴포넌트 활용

Phase 5: Components 문서 변환 ⏱️ ~6시간 🔄 IN PROGRESS

1. ✅ 기본 컴포넌트 (Button, Input, Card, Checkbox, Radio, Modal) - 6개 완료
2. 네비게이션 컴포넌트 (Tab, Topbar, NavigationBar 등) - 5개
3. 피드백 컴포넌트 (BottomSheet, Tooltip 등) - 4개
4. 데이터 표시 컴포넌트 (Chart, List, Chip 등) - 10개
5. 특수 컴포넌트 (Quiz, Relaxation 등) - 8개

Phase 6: Patterns & Icons 문서 변환 ⏱️ ~2시간

1. Patterns 문서 변환 (8개)
2. Icons 문서 변환 (2개)

Phase 7: 폴리싱 및 최적화 ⏱️ ~2시간

1. 검색 기능 (선택적)
2. SEO 최적화
3. 성능 최적화
4. 접근성 검토

---

7. 의존성 목록

7.1 필수 의존성

{
  "dependencies": {
    // Framework
    "next": "^15.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",

    // MDX & Content
    "contentlayer2": "^0.4.6",
    "next-contentlayer2": "^0.4.6",
    "rehype-autolink-headings": "^7.1.0",
    "rehype-pretty-code": "^0.9.0",
    "rehype-slug": "^6.0.0",
    "remark-gfm": "^4.0.0",

    // UI Components (shadcn/ui 기반)
    "@radix-ui/react-accordion": "^1.2.0",
    "@radix-ui/react-alert-dialog": "^1.1.0",
    "@radix-ui/react-collapsible": "^1.0.3",
    "@radix-ui/react-dialog": "^1.1.0",
    "@radix-ui/react-dropdown-menu": "^2.1.0",
    "@radix-ui/react-popover": "^1.1.0",
    "@radix-ui/react-scroll-area": "^1.2.0",
    "@radix-ui/react-select": "^2.1.0",
    "@radix-ui/react-separator": "^1.1.0",
    "@radix-ui/react-slot": "^1.1.0",
    "@radix-ui/react-tabs": "^1.1.0",
    "@radix-ui/react-tooltip": "^1.1.0",

    // Styling & Utilities
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^2.0.0",
    "next-themes": "^0.3.0",

    // Icons & UI
    "lucide-react": "^0.436.0",
    "cmdk": "^1.0.0",
    "sonner": "^1.5.0",
    "vaul": "^0.9.0"
  },
  "devDependencies": {
    "@shikijs/compat": "^1.1.7",
    "shiki": "^1.1.7",
    "tailwindcss": "^3.4.0",
    "@tailwindcss/typography": "^0.5.9",
    "postcss": "^8.5.0",
    "typescript": "^5.0.0"
  }
}

7.2 shadcn/ui 컴포넌트 설치 계획

Design System 문서 사이트에서 사용할 shadcn/ui 컴포넌트:

컴포넌트	용도
accordion	FAQ, 접을 수 있는 섹션
alert	정보/경고 메시지
button	버튼 (코드 복사 등)
card	컴포넌트 프리뷰 카드
collapsible	코드 블록 접기/펼치기
command	검색 팔레트
dialog	모달
dropdown-menu	드롭다운 메뉴
popover	팝오버
scroll-area	스크롤 영역
select	셀렉트 박스
separator	구분선
sheet	사이드 시트 (모바일 메뉴)
tabs	플랫폼별 코드 탭 (iOS/Android/Web)
tooltip	툴팁

# shadcn/ui 컴포넌트 초기화 및 설치
npx shadcn-ui@latest init
npx shadcn-ui@latest add accordion button card collapsible command dialog dropdown-menu popover scroll-area select separator sheet tabs tooltip

---

8. 홈페이지 디자인

8.1 레이아웃 구성

┌─────────────────────────────────────────────────────────────────┐
│  SleepQ Design System                              [Search] ☰  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│     SleepQ Design System                                       │
│     일관된 사용자 경험을 위한 디자인 리소스                        │
│                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐                       │
│  │   Foundation    │  │   Components    │                       │
│  │   색상, 타이포   │  │   UI 컴포넌트   │                       │
│  └─────────────────┘  └─────────────────┘                       │
│                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐                       │
│  │    Patterns     │  │     Icons       │                       │
│  │   UI 패턴 가이드 │  │   아이콘 라이브러리│                       │
│  └─────────────────┘  └─────────────────┘                       │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│  Footer: WELT Corporation | Version 2.0.0                       │
└─────────────────────────────────────────────────────────────────┘

---

9. 고려사항 및 결정 필요 항목

9.1 결정 필요 사항

항목	옵션	권장
검색 기능	없음 / Algolia / 로컬 검색	Phase 7에서 로컬 검색 추가
다크 모드	지원 / 미지원	미지원 (앱과 동일)
컴포넌트 실제 렌더링	정적 이미지 / React 컴포넌트	정적 이미지 + 코드 (초기)
플랫폼 탭	iOS/Android/Web 탭	탭으로 분리 표시

9.2 제외 사항 (MVP 이후)

• 실시간 컴포넌트 에디터
• Figma 플러그인 연동
• 자동 변경 감지 및 배포

---

10. 성공 기준

1. 완전성: 모든 기존 디자인 시스템 문서가 웹 페이지로 변환됨
2. 사용성: 개발자가 3클릭 이내에 원하는 컴포넌트 코드를 복사 가능
3. 유지보수성: MDX 파일만 수정하여 문서 업데이트 가능
4. 접근성: WCAG 2.1 AA 기준 준수
5. 성능: Lighthouse Performance 점수 90점 이상

---

11. 다음 단계

검토 후 승인 시:

1. Phase 1 시작 - NX 프로젝트 생성
2. 기본 레이아웃 및 Contentlayer 설정
3. 우선순위가 높은 Foundation 문서부터 변환 시작

---

문서 작성일: 2025-12-05 버전: 1.0.0 작성자: Claude Code