feat(web): Figma 디자인 시스템 구축 — 완전 리디자인 + Phase별 점진 마이그레이션

[greenheadHQ]

Summary

Figma MCP를 활용하여 디자인 시스템을 완전히 새로 설계하고, Phase별로 코드에 반영한다. 현재 디자인 정의 없이 개발된 UI의 한계를 해소하고, Figma를 Single Source of Truth로 확립한다.

Context

• 현재 packages/web은 별도의 디자인 정의 없이 개발되어 일관성 한계에 봉착
• shadcn/ui 마이그레이션(refactor: shadcn/ui 기반 디자인 시스템 전면 교체 #19→feat(web): issue #19 shadcn UI 마이그레이션 + 디자인 시스템 구축 #27)으로 토큰 체계(CSS Custom Properties, oklch)는 갖춰졌으나:
  • 시맨틱 토큰(--success, --warning)이 있지만 text-green-500 등 하드코딩 색상 다수
  • StatusIcon 컴포넌트가 3개 파일에 중복 존재
  • 디자인 결정의 근거가 코드에만 존재하여 추적 불가
• Figma MCP 도구 확인 완료: use_figma(Plugin API JS 실행), create_new_file, Code Connect 등 활용 가능

Related Commits

• 60b7df6 — feat(web): issue refactor: shadcn/ui 기반 디자인 시스템 전면 교체 #19 shadcn UI 마이그레이션 + 디자인 시스템 구축 (feat(web): issue #19 shadcn UI 마이그레이션 + 디자인 시스템 구축 #27)
• bf7ee19 — fix(web): 모바일 UI/UX 전면 개선 (fix(web): 모바일 UI/UX 전면 개선 — 4개 페이지 반응형 레이아웃 #70)

Proposed Changes

Phase 1: 디자인 토큰

• whoami → create_new_file로 단일 Figma 파일 생성
• 색상 토큰 정의 (Primary, Secondary, Semantic 등 — LLM이 Anki 카드 분할 도구에 맞게 새로 제안)
• 타이포그래피 스케일 정의 (Pretendard Variable 기반 8단계)
• 간격(spacing) 및 반경(radius) 토큰 정의
• use_figma로 Figma 변수(Variables)에 등록

Phase 2: UI 프리미티브

• Button (6 variant × 4 size) Figma 컴포넌트 생성
• Card, Dialog, Select, Popover, Table 등 shadcn 기반 컴포넌트 Figma화
• BottomSheet, CompactSelector 등 커스텀 컴포넌트 Figma화
• ModelBadge, SyncStatusBadge 등 도메인 컴포넌트 Figma화

Phase 3: 페이지 레이아웃

• Layout(Sidebar + Main) 구조 — LLM이 대안 제안 후 사용자 선택
• Dashboard 페이지 레이아웃
• SplitWorkspace (3단 분할) 레이아웃
• ValidateWorkspace 레이아웃
• CardBrowser, SplitHistory, BackupManager, PromptManager 레이아웃
• 모바일 반응형 레이아웃 (useIsMobile 기반 패널 전환)

Phase 4: Code Connect 연동

• get_code_connect_suggestions로 Figma↔코드 매핑 후보 생성
• 매핑 검토 후 send_code_connect_mappings로 저장
• get_design_context 호출 시 코드 컴포넌트 자동 연결 확인

Notes

• 디자인 무드: LLM 자유도 부여. 'Anki 카드 분할 도구'에 맞는 새로운 디자인 언어를 제안
• 다크모드: 라이트만 Figma에 정의. 다크모드는 코드(CSS .dark 클래스)에서만 관리
• 기술 스택: shadcn/ui + Tailwind v4 + Radix UI 유지. Figma → 코드 반영 시 이 스택 기반
• 파일 구조: 단일 Figma 파일 (토큰+컴포넌트+레이아웃)
• use_figma 제약: 호출당 코드 50,000자 제한. 복잡한 컴포넌트는 여러 호출로 분할
• 브랜치: feat/figma (main에서 분기, 현재 빈 상태)
• 관련 이슈: refactor: shadcn/ui 기반 디자인 시스템 전면 교체 #19 (CLOSED — shadcn 마이그레이션 완료)

[greenheadHQ]

LLM 이행 가이드 — Figma 디자인 시스템 구축

대상: Figma MCP + packages/web 디자인 시스템
목표: Figma에 완전한 디자인 시스템(토큰+프리미티브+레이아웃)을 구축하고 Code Connect로 코드와 연동한다
예상 소요: Phase당 ~20-30분 (다중 세션, 총 6 Phase)
난이도: 복잡
관련 이슈: #111

핵심 원칙

1. Figma MCP 우선: 모든 Figma 작업은 MCP 도구(use_figma, create_new_file 등)를 통해 수행한다. 수동 Figma 작업 없이 LLM이 자율 실행한다.
2. 라이트 모드만: Figma에는 라이트 모드만 정의한다. 다크모드는 코드(CSS .dark)에서만 관리한다.
3. 기존 스택 존중: shadcn/ui + Tailwind v4 + Radix UI 기반을 유지한다. Figma→코드 반영 시 이 스택에 맞춘다.
4. Phase별 사용자 리뷰: 각 Phase 완료 후 get_screenshot으로 결과를 캡처하여 사용자에게 보여주고 승인을 받은 뒤 다음 Phase로 진행한다.

---

Phase 1: 사전 확인 + Figma 파일 생성

1-1. Figma 계정 확인

mcp__claude_ai_Figma__whoami

기대 결과: 사용자 정보 + planKey 반환. planKey는 Phase 1-2에서 파일 생성에 필요하다.

1-2. 현재 코드 토큰 확인 (병렬 가능)

다음을 확인하여 현재 디자인 토큰 현황을 파악한다:

# 1. CSS 토큰 정의 확인
grep -A 5 '@theme inline' packages/web/src/index.css

# 2. 타이포그래피 유틸리티 확인
grep 'typo-' packages/web/src/index.css

# 3. 하드코딩 색상 사용 현황
grep -rn 'text-green-\|text-yellow-\|text-red-\|bg-green-\|bg-yellow-\|bg-red-\|text-violet-\|bg-blue-\|bg-emerald-' packages/web/src/

# 4. shadcn components.json 확인
cat packages/web/components.json

# 5. 현재 컴포넌트 목록 확인
ls packages/web/src/components/ui/

기대 결과:

• index.css에 oklch 색공간 기반 CSS Custom Properties 존재 (--background, --primary, --success 등)
• 8단계 타이포 유틸리티 (typo-display ~ typo-caption)
• 하드코딩 색상이 ValidationPanel.tsx, ValidateWorkspace.tsx, CardBrowser.tsx 등에 대량 존재
• components.json: shadcn new-york 스타일
• UI 컴포넌트: button, card, dialog, popover, select, table, bottom-sheet, compact-selector, model-badge

1-3. Figma 파일 생성

mcp__claude_ai_Figma__create_new_file
  fileName: "Awesome Anki Design System"
  planKey: <1-1에서 확인한 planKey>
  editorType: "design"

기대 결과: 새 빈 Figma 파일 생성, fileKey 반환. 이후 모든 Phase에서 이 fileKey를 사용한다.

1-4. 페이지 구조 생성

mcp__claude_ai_Figma__use_figma
  fileKey: <1-3의 fileKey>
  description: "Create page structure for design system"
  code: |
    // 기본 Page 1을 "🎨 Tokens"로 이름 변경
    const tokensPage = figma.currentPage
    tokensPage.name = "🎨 Tokens"

    // 추가 페이지 생성
    const componentsPage = figma.createPage()
    componentsPage.name = "🧩 Components"

    const layoutsPage = figma.createPage()
    layoutsPage.name = "📐 Layouts"

    const playgroundPage = figma.createPage()
    playgroundPage.name = "🔬 Playground"

---

Phase 2: 디자인 토큰 정의

2-1. 색상 토큰 생성

LLM이 'Anki 카드 분할 도구'에 맞는 새로운 색상 팔레트를 제안한다.
현재 Blue/Slate 계열은 참고만 하고, 완전히 새로운 디자인 언어를 설계한다.

제안 시 고려사항:

• 도구의 성격: 학습 카드 분할 → 집중력/명확성/교육적 느낌
• 시맨틱 색상 필수: Primary, Secondary, Accent, Background, Foreground, Muted, Border
• 상태 색상 필수: Success, Warning, Destructive, Info
• 사이드바/차트 전용 색상
• WCAG AA 이상 대비율 준수

mcp__claude_ai_Figma__use_figma
  fileKey: <fileKey>
  description: "Create color token variables"
  code: |
    // Tokens 페이지로 이동
    const tokensPage = figma.root.children.find(p => p.name === "🎨 Tokens")
    await figma.setCurrentPageAsync(tokensPage)

    // 색상 변수 컬렉션 생성
    const colorCollection = figma.variables.createVariableCollection("Colors")
    // Light 모드만 (기본 모드 사용)

    // === Primary 색상 ===
    const primary = figma.variables.createVariable("primary", colorCollection, "COLOR")
    primary.setValueForMode(colorCollection.defaultModeId, {r: .., g: .., b: ..})
    // ... (LLM이 제안한 색상값으로 채운다)

    // === Semantic 색상 ===
    // success, warning, destructive, info 등

    // === 색상 스와치 프레임 시각화 ===
    // 각 색상을 시각적으로 보여주는 스와치 그리드 생성

2-2. 타이포그래피 토큰 생성

Pretendard Variable 기반 8단계 + JetBrains Mono (코드용).

mcp__claude_ai_Figma__use_figma
  fileKey: <fileKey>
  description: "Create typography tokens and specimens"
  code: |
    // 타이포그래피 스케일 정의 (현재 코드 기반)
    // display, h1, h2, h3, body-lg, body, body-sm, caption
    // 각 단계의 font-size, line-height, font-weight, letter-spacing 설정

    // Figma 텍스트 스타일로 등록
    // + 시각적 타이포 스펙시먼 프레임 생성

2-3. 간격 + 반경 토큰 생성

mcp__claude_ai_Figma__use_figma
  fileKey: <fileKey>
  description: "Create spacing and radius tokens"
  code: |
    // 간격 스케일: 4px 기반 (4, 8, 12, 16, 20, 24, 32, 40, 48, 64)
    // 반경 스케일: sm, md(기본), lg, xl, full
    // Figma 변수로 등록 + 시각적 시연 프레임

2-4. 토큰 검증

mcp__claude_ai_Figma__get_screenshot
  fileKey: <fileKey>
  nodeId: <Tokens 페이지의 nodeId>

스크린샷을 사용자에게 보여주고 색상/타이포/간격 승인을 받는다.

---

Phase 3: UI 프리미티브 컴포넌트

3-1. Button 컴포넌트

현재 코드: CVA 기반 6 variant(default, destructive, outline, secondary, ghost, link) × 4 size(default, sm, lg, icon).

mcp__claude_ai_Figma__use_figma
  fileKey: <fileKey>
  description: "Create Button component with variants"
  code: |
    // Components 페이지로 이동
    const componentsPage = figma.root.children.find(p => p.name === "🧩 Components")
    await figma.setCurrentPageAsync(componentsPage)

    // Button 컴포넌트 생성
    // - Component Set (variant property: variant × size)
    // - Auto Layout 적용
    // - Phase 2의 토큰 변수 바인딩
    // - 각 variant별 스타일 적용

3-2. Card 컴포넌트

Card / CardHeader / CardTitle / CardContent / CardFooter / CardAction 구조.

3-3. Dialog, Select, Popover, Table

각각 Radix 기반 shadcn 컴포넌트의 Figma 버전 생성.
use_figma 호출당 50,000자 제한이므로 컴포넌트별로 분리 호출한다.

3-4. 커스텀 컴포넌트

• BottomSheet: 모바일 전용 바텀시트
• CompactSelector: 모바일=BottomSheet / 데스크톱=Popover 자동 전환
• ModelBadge: LLM 프로바이더 뱃지 (Gemini/OpenAI 로고 + 비용)
• SyncStatusBadge: Anki 동기화 상태 (없음/미동기화/완료)
• ContentRenderer: 마크다운+KaTeX 카드 렌더러 (구조만 — 실제 렌더링은 코드)
• DiffViewer: 분할 전후 diff 뷰어

3-5. 컴포넌트 검증

mcp__claude_ai_Figma__get_screenshot
  fileKey: <fileKey>
  nodeId: <Components 페이지 nodeId>

사용자 리뷰 후 다음 Phase 진행.

---

Phase 4: 페이지 레이아웃

4-1. 레이아웃 구조 제안

LLM이 현재 사이드바+3단 분할 구조의 대안을 2-3개 제안한다.
각 대안의 장단점을 사용자에게 제시하고 선택을 받는다.

현재 구조 (참고용):

• 데스크톱: 고정 좌측 사이드바(w-64) + 메인 영역
• 작업 페이지: 3단 분할 (후보 목록 | 원본 | 결과)
• 모바일: 상단 헤더 + 햄버거 drawer + 패널 전환

4-2. Layout 프레임 생성

승인된 레이아웃 구조를 기반으로 Sidebar + Main 기본 구조를 Figma에 생성.
데스크톱(1440px)과 모바일(375px) 두 가지 뷰포트.

4-3. 각 페이지 레이아웃

7개 페이지를 Phase 2-3의 토큰/컴포넌트를 활용하여 구성:

1. Dashboard: 덱 선택, 통계 카드, 빠른 작업
2. SplitWorkspace: 카드 분할 3단 레이아웃
3. ValidateWorkspace: 카드 검증 3단 레이아웃
4. CardBrowser: 덱 내 카드 탐색
5. SplitHistory: 분할 이력 + 필터
6. BackupManager: 백업 목록 + 롤백
7. PromptManager: 프롬프트 버전 관리 (탭 구조)

각 페이지는 데스크톱 + 모바일 두 프레임으로 생성.
use_figma 호출을 페이지별로 분리한다 (50,000자 제한).

4-4. 레이아웃 검증

각 페이지별 get_screenshot으로 캡처 → 사용자 리뷰.

---

Phase 5: Code Connect 연동

5-1. 매핑 후보 생성

mcp__claude_ai_Figma__get_code_connect_suggestions
  fileKey: <fileKey>

Figma 컴포넌트와 코드 컴포넌트의 매핑 후보를 AI가 제안한다.

5-2. 매핑 검토

제안된 매핑을 사용자에게 보여주고 검토를 받는다.

예상 매핑:

Figma 컴포넌트	코드 컴포넌트
Button	packages/web/src/components/ui/button.tsx
Card	packages/web/src/components/ui/card.tsx
Dialog	packages/web/src/components/ui/dialog.tsx
Select	packages/web/src/components/ui/select.tsx
...	...

5-3. 매핑 저장

mcp__claude_ai_Figma__send_code_connect_mappings
  fileKey: <fileKey>
  mappings: <검토 완료된 매핑 목록>

5-4. 연동 확인

mcp__claude_ai_Figma__get_design_context
  fileKey: <fileKey>
  nodeId: <Button 컴포넌트 nodeId>

Code Connect가 적용된 상태에서 get_design_context 호출 시 코드 컴포넌트가 자동으로 반환되는지 확인한다.

---

Phase 6: 코드 반영 + 검증 + 커밋

6-1. 디자인 토큰 코드 반영

Phase 2에서 확정된 새 색상 팔레트를 packages/web/src/index.css에 반영한다.

파일: packages/web/src/index.css

BEFORE: 기존 oklch Blue/Slate 계열 CSS Custom Properties
AFTER: Phase 2에서 확정된 새 색상 토큰 (구체적 값은 Phase 2 완료 후 확정)

6-2. 하드코딩 색상 정리

text-green-500, bg-yellow-50 등 하드코딩된 날 색상을 시맨틱 토큰으로 교체.
StatusIcon 3중 중복을 단일 공통 컴포넌트로 통합.

6-3. 검증

# 빌드 확인
bun run build

# 하드코딩 색상 잔존 확인
grep -rn 'text-green-\|text-yellow-\|text-red-\|bg-green-\|bg-yellow-\|bg-red-' packages/web/src/

# 개발 서버에서 시각 확인
bun run dev:web

6-4. 커밋

git add packages/web/src/
git commit -m "$(cat <<'EOF'
feat(web): Figma 디자인 시스템 기반 리디자인 — 토큰 통합 + 하드코딩 제거

- 새 색상 팔레트 적용 (Figma SoT 기반)
- 하드코딩 색상(text-green-500 등)을 시맨틱 토큰으로 교체
- StatusIcon 3중 중복 → 단일 공통 컴포넌트로 통합
- 타이포/간격/반경 토큰 Figma 변수와 동기화

Closes #111
EOF
)"

DA 피드백 (권장)

구현 완료 후, /run-da for_pr 스킬을 실행하여 코드 품질을 검증하고,
/parallel-audit로 전수조사를 수행한 뒤 /create-pr로 PR을 생성한다.

---

주의사항

• use_figma 코드 제한: 호출당 50,000자. 복잡한 컴포넌트는 여러 호출로 분할한다.
• 폰트명 주의: Figma Plugin API에서 "Semi Bold", "Extra Bold" 등 공백 포함 형태를 사용해야 한다.
• figma.currentPage 설정: figma.currentPage = page 대신 await figma.setCurrentPageAsync(page) 사용 필수.
• Figma 변수 모드: 라이트만 정의하므로 defaultModeId 하나만 사용.
• Phase 독립성: 각 Phase는 이전 Phase의 fileKey만 알면 독립 실행 가능. 세션이 끊겨도 fileKey로 이어서 작업한다.
• 사용자 리뷰 필수: Phase 2-4 완료 시 반드시 get_screenshot으로 시각적 결과를 보여주고 승인을 받는다. 승인 없이 다음 Phase로 넘어가지 않는다.

[greenheadHQ]

Figma 디자인 시스템 구축 — 중간 결과 보고

진행 상황

Phase	상태	비고
Phase 1: 디자인 토큰	✅ 완료	Figma Variables 35개 등록 (색상 Core/State/Sidebar/Chart)
Phase 2: UI 컴포넌트	⚠️ 부분 완료	Component/ComponentSet 등록했으나 시각적 정리 필요
Phase 3: 페이지 레이아웃	✅ 완료	7개 페이지 (Dashboard, Clinic, Split, Browse, History, Backups, Prompts)
Phase 4: Code Connect	❌ 불가	Organization/Enterprise 플랜 전용
Phase 5: 코드 반영	미착수	DA 검증 완료, 계획 확정

Figma 파일

• URL: https://www.figma.com/design/XIYuDjF0U9JalcYkda8GrA
• planKey: team::1004002046063663570 (개인 계정 shren0812@gmail.com)
• 페이지: 🎨 Tokens / 🧩 Components / 📐 Layouts

Starter 플랜 제약 사항 (발견)

제약	영향	해결
3페이지 제한	4페이지(Playground) 생성 시 에러	Playground 제거, 3페이지로 운영
MCP 도구 호출 제한	4~5회 use_figma 호출 후 rate limit	Pro 시트로 업그레이드하여 해결
Code Connect 접근 불가	get_code_connect_suggestions 호출 시 플랜 에러	Organization/Enterprise 필요. 현재 불가
Variables API	✅ Starter에서도 작동 확인	직접 테스트로 검증 완료

Plugin API(use_figma) 코드 기반 디자인의 한계

잘 작동한 것

• Variables 등록: 단순 값 등록이라 정확하게 동작
• Rectangle + Text 절대 배치: 레이아웃 목업에 효과적
• 페이지/프레임 생성: 구조적 작업은 안정적

한계가 있었던 것

• Auto Layout 중첩: 프레임 크기, 클리핑, 콘텐츠 축소 등 시각적 결과 예측 어려움
• ComponentSet 생성: figma.combineAsVariants() 후 variant 배치가 겹치거나 깨짐
• 폰트 제한: Pretendard Variable 등 커스텀 폰트 사용 불가 (Inter로 대체)
• lucide 아이콘: SVG 직접 삽입 불가, placeholder 사각형으로 대체

교훈

1. Plugin API로 복잡한 UI를 코드만으로 만드는 것은 비효율적
2. 토큰(Variables) + 레이아웃 목업은 코드로, 컴포넌트 정리는 Figma GUI에서 수동으로 하는 것이 최적
3. 실제 UI 스크린샷을 반드시 참고해야 함 (코드 분석만으로는 부정확)

DA 검증 결과 요약 (Arbiter 완료)

15건 중 12건 CONFIRMED, 2건 NEEDS_MORE_INFO → 해소됨

Phase 5 반영 예정 사항 (HIGH)

• StatusIcon 통합: StatusIcon 2곳 + ValidationIcon 1곳 → ui/validation-icon.tsx, CardStatusIcon 분리 유지
• getStatusBg 통합: dark mode 포함 버전 기준 → lib/validation-styles.ts
• 토큰 교체 + 하드코딩 제거 동시: CSS 토큰 교체와 101건 하드코딩 색상 제거를 동일 범위로

Phase 5 반영 예정 사항 (MEDIUM)

• 유사도 임계값 매직넘버 70/90 상수 추출
• SyncStatusBadge 시맨틱 토큰 교체
• --success/--warning 시맨틱 토큰 실사용 연결

Phase 5 반영 예정 사항 (LOW)

• renderValidationDetails 타입 narrowing
• 미사용 타이포 단계(4개) 정리

UI 변경 사항 (계획 대비)

• Validate → Clinic: Validate 탭이 Clinic(카드 진단 올인원)으로 대체
• Split: deprecated 표시 추가
• Figma 레이아웃에 반영 완료

다음 단계

1. Phase 4: Code Connect — Organization 플랜 필요, 현재 불가
2. Phase 5: 코드 반영 — DA 검증 완료된 계획에 따라 실행
   • CSS 토큰 교체 (새 Teal 팔레트)
   • 하드코딩 색상 101건 → 시맨틱 토큰
   • ValidationIcon/getStatusBg 공통 컴포넌트 추출
   • 유사도 임계값 상수화
3. Figma 컴포넌트 시각적 정리 — GUI에서 수동 작업 권장