[DOCS] 토큰 시스템 문서화 및 마이그레이션 가이드

[3o14]

목표

토큰 시스템 사용법과 기존 사용자의 마이그레이션 경로를 문서화합니다.

선행 조건

• [FEATRUE] Primitive 토큰 정의 #220, [FEATRUE] Semantic 토큰 초안 설계 #221, [FEATRUE] Style Dictionary 빌드 파이프라인 구축 #222, [FEATRUE] 샘플 컴포넌트 토큰 마이그레이션 #225 완료

작업 내용

README 업데이트

• 토큰 시스템 개요 섹션
• 설치 및 사용법
• vars.* import 및 사용 방법
• 현재 light 모드만 지원, 다크 모드는 로드맵에 명시

docs/tokens/usage.md

• Primitive vs Semantic 구분 설명
• 언제 어떤 토큰을 써야 하는가 가이드
• "컴포넌트 개발 시 semantic vars.*만 사용" 원칙 강조
• token-types.ts 유니온 타입을 props에 활용하는 방법

docs/tokens/migration-guide.md

• v1 → v2 마이그레이션 스텝

  // v1: raw 팔레트 직접 import
  import { color } from '@sipe-team/tokens';
  background: color.blue500
  
  // v2: generated vars 참조
  import { vars } from '@sipe-team/tokens';
  background: vars.color.blue[500]

• v1 하드코딩 → v2 semantic 토큰 대응표
• Breaking change 목록

docs/tokens/contributing.md

• 토큰 추가/수정 PR 프로세스
  a. tokens/**/*.json 수정
  b. pnpm build:tokens 실행 (codegen)
  c. VE 타입 체크 통과 확인
  d. PR 생성 → CI 자동 검증
• 네이밍 컨벤션 요약
• Semantic alias 원칙 (hex 직접 사용 금지)

docs/tokens/roadmap.md

• 다음 사이클: 다크 모드 (semantic/dark/ 채우기 + Tokens Studio Set 활성화)
• 전체 컴포넌트 마이그레이션 계획