마이그레이션 전략

// scripts/analyze-tokens.ts

interface TokenAuditResult {
  hardcodedColors: Array<{ file: string; line: number; value: string }>
  hardcodedSpacing: Array<{ file: string; line: number; value: string }>
  inconsistentNaming: Array<{ token: string; suggested: string }>
  missingTokens: string[]
}

async function auditTokenUsage(srcDir: string): Promise<TokenAuditResult> {
  const files = await glob(`${srcDir}/**/*.{tsx,ts,css}`)
  const result: TokenAuditResult = {
    hardcodedColors: [],
    hardcodedSpacing: [],
    inconsistentNaming: [],
    missingTokens: [],
  }

  for (const file of files) {
    const content = await readFile(file, 'utf-8')
    const lines = content.split('\n')

    lines.forEach((line, index) => {
      // 하드코딩된 색상 감지
      const colorMatches = line.match(/#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)/g)
      if (colorMatches) {
        colorMatches.forEach((value) => {
          result.hardcodedColors.push({ file, line: index + 1, value })
        })
      }

      // 하드코딩된 간격 감지
      const spacingMatches = line.match(/\b\d+px\b/g)
      if (spacingMatches) {
        spacingMatches.forEach((value) => {
          result.hardcodedSpacing.push({ file, line: index + 1, value })
        })
      }
    })
  }

  return result
}

// 실행
const audit = await auditTokenUsage('./src')
console.log(`하드코딩된 색상: ${audit.hardcodedColors.length}개`)
console.log(`하드코딩된 간격: ${audit.hardcodedSpacing.length}개`)

// scripts/migrate-tokens.ts

// 1. 색상 매핑 생성
const colorMap = new Map([
  ['#3B82F6', 'colors.primary'],
  ['#EF4444', 'colors.destructive'],
  ['#F3F4F6', 'colors.muted'],
  // ...기존 색상 → 토큰 매핑
])

// 2. 간격 매핑 생성
const spacingMap = new Map([
  ['4px', 'spacing.1'],
  ['8px', 'spacing.2'],
  ['16px', 'spacing.4'],
  // ...
])

// 3. 자동 변환 (codemod)
function transformHardcodedValues(code: string): string {
  let result = code

  colorMap.forEach((token, value) => {
    const regex = new RegExp(escapeRegex(value), 'g')
    result = result.replace(regex, `var(--${token.replace('.', '-')})`)
  })

  return result
}

// 기존: 느슨한 타입
interface ButtonProps {
  variant?: string
  size?: string
}

// 목표: 엄격한 타입
type ButtonVariant = 'default' | 'destructive' | 'outline' | 'ghost' | 'link'
type ButtonSize = 'default' | 'sm' | 'lg' | 'icon'

interface ButtonProps {
  /** 시각적 스타일 @default "default" */
  variant?: ButtonVariant
  /** 버튼 크기 @default "default" */
  size?: ButtonSize
}

// scripts/migrate-types.ts

// 1. 기존 Props 분석
interface PropsAnalysis {
  component: string
  props: Array<{
    name: string
    currentType: string
    suggestedType: string
    values: string[] // 실제 사용된 값들
  }>
}

// 2. 타입 생성
function generateStrictTypes(analysis: PropsAnalysis): string {
  return analysis.props
    .map((prop) => {
      if (prop.values.length <= 10) {
        const union = prop.values.map((v) => `'${v}'`).join(' | ')
        return `type ${capitalize(prop.name)} = ${union}`
      }
      return null
    })
    .filter(Boolean)
    .join('\n')
}

## 기존 문서 구조

- README.md (산문형)
- 코드 주석 (비일관적)

## 목표 문서 구조

components/
└── button/
├── button.tsx # 컴포넌트
├── button.types.ts # 타입 정의
├── button.stories.tsx # Storybook
├── button.test.tsx # 테스트
└── button.docs.mdx # 구조화된 문서

# Design System CLAUDE.md

## 컴포넌트 사용 규칙

### 필수 규칙

1. 모든 스타일링은 디자인 시스템 컴포넌트/토큰 사용
2. 하드코딩된 색상/간격 금지
3. 모든 인터랙티브 요소에 접근성 속성 필수

### 컴포넌트 선택 가이드

{자동 생성된 가이드 테이블}

### 토큰 참조

{토큰 문서 링크 또는 인라인 참조}

// scripts/generate-claude-md.ts

async function generateClaudeMd(componentsDir: string): Promise<string> {
  const components = await loadComponents(componentsDir)

  const sections = [
    generateHeader(),
    generateComponentGuide(components),
    generateTokenReference(),
    generatePatterns(),
    generateDosAndDonts(),
  ]

  return sections.join('\n\n')
}

function generateComponentGuide(components: Component[]): string {
  const table = components.map((c) => ({
    name: c.name,
    useFor: c.metadata.useFor,
    avoidFor: c.metadata.avoidFor,
    example: c.examples[0]?.code,
  }))

  return formatMarkdownTable(table)
}

# .github/workflows/design-system-ci.yml

name: Design System CI

on:
  pull_request:
    paths:
      - 'packages/ui/**'
      - 'tokens/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Type Check
        run: yarn tsc --noEmit

      - name: Lint (Design System Rules)
        run: yarn lint:ds

      - name: Accessibility Audit
        run: yarn test:a11y

      - name: Visual Regression
        run: yarn test:visual

      - name: Token Validation
        run: yarn validate:tokens

## 개발자 온보딩

### Day 1: 기본 이해

- [ ] 디자인 시스템 문서 읽기
- [ ] Storybook 둘러보기
- [ ] CLAUDE.md 규칙 숙지

### Day 2: 실습

- [ ] 간단한 컴포넌트 구현 (AI 활용)
- [ ] 코드 리뷰 받기
- [ ] 피드백 반영

### Day 3-5: 심화

- [ ] 복잡한 패턴 구현
- [ ] 커스텀 컴포넌트 작성
- [ ] 문서 기여

## AI + 디자인 시스템 워크숍

### Session 1: 컴포넌트 선택 (30분)

- AI에게 "버튼 만들어줘" vs "폼 제출 버튼 필요"
- 명확한 컨텍스트 제공의 중요성
- 실습: 다양한 UI 시나리오

### Session 2: 토큰 활용 (30분)

- 토큰 시스템 이해
- AI가 토큰을 올바르게 선택하도록 하기
- 실습: 커스텀 테마 적용

### Session 3: 복잡한 패턴 (45분)

- 폼, 테이블, 대시보드 패턴
- AI와 함께 점진적 구축
- 실습: 실제 기능 구현

// 피드백 수집 시스템

interface DesignSystemFeedback {
  type: 'bug' | 'improvement' | 'question' | 'ai-issue'
  component?: string
  description: string
  aiContext?: {
    prompt: string
    generatedCode: string
    issue: string
  }
  priority: 'low' | 'medium' | 'high'
}

// AI 관련 이슈 자동 수집
function collectAIFeedback(event: { prompt: string; output: string; validationErrors: string[] }) {
  if (event.validationErrors.length > 0) {
    submitFeedback({
      type: 'ai-issue',
      description: '검증 실패',
      aiContext: {
        prompt: event.prompt,
        generatedCode: event.output,
        issue: event.validationErrors.join(', '),
      },
      priority: 'medium',
    })
  }
}

// 새 컴포넌트와 기존 컴포넌트 공존

// components/button/index.ts
import { LegacyButton } from './legacy-button'
import { Button as NewButton } from './button'
import { useFeatureFlag } from '@/lib/feature-flags'

export function Button(props: ButtonProps) {
  const useNewDesignSystem = useFeatureFlag('new-design-system')

  if (useNewDesignSystem) {
    return <NewButton {...props} />
  }

  // 기존 props를 새 props로 매핑
  return <LegacyButton {...mapLegacyProps(props)} />
}