사례 연구

// shadcn/ui의 Button variant 정의
const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md text-sm font-medium...',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        outline: 'border border-input bg-background hover:bg-accent...',
        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'text-primary underline-offset-4 hover:underline',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 rounded-md px-3',
        lg: 'h-11 rounded-md px-8',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
)

/* shadcn/ui의 CSS 변수 */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  /* ... */
}

// Card 컴포넌트 구조
<Card>
  <CardHeader>
    <CardTitle>제목</CardTitle>
    <CardDescription>설명</CardDescription>
  </CardHeader>
  <CardContent>본문</CardContent>
  <CardFooter>
    <Button>액션</Button>
  </CardFooter>
</Card>

// Radix Dialog - 접근성 자동 처리
<Dialog.Root>
  <Dialog.Trigger asChild>
    <Button>열기</Button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      {/*
        자동 처리:
        - role="dialog"
        - aria-modal="true"
        - 포커스 트랩
        - Escape로 닫기
        - 외부 클릭 닫기
      */}
      <Dialog.Title>제목</Dialog.Title>
      <Dialog.Description>설명</Dialog.Description>
      <Dialog.Close asChild>
        <Button>닫기</Button>
      </Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

// Radix의 내부 상태 머신 (예시)
const dialogMachine = {
  initial: 'closed',
  states: {
    closed: {
      on: {
        OPEN: 'open',
      },
    },
    open: {
      entry: ['focusTrap', 'lockScroll'],
      exit: ['releaseFocusTrap', 'unlockScroll'],
      on: {
        CLOSE: 'closed',
        ESCAPE: 'closed',
        OUTSIDE_CLICK: { target: 'closed', cond: 'modal' },
      },
    },
  },
}

## 프로젝트: 기업용 대시보드

- 팀: 프론트엔드 5명, 디자이너 2명
- 기간: 3개월
- 목표: 신규 디자인 시스템 도입 + AI 코드 생성

## 기존 상태

- 하드코딩된 스타일 다수
- 일관성 없는 컴포넌트
- 접근성 미준수

// 감사 결과
const auditResult = {
  hardcodedColors: 127, // #hexcode 직접 사용
  hardcodedSpacing: 89, // px 직접 사용
  inconsistentVariants: 23, // 같은 역할 다른 스타일
}

// 정의한 토큰 구조
const tokens = {
  colors: {
    // 12가지 시맨틱 색상
  },
  spacing: {
    // 4px 기반 12단계
  },
  typography: {
    // 6가지 텍스트 스타일
  },
}

// 마이그레이션한 컴포넌트 (우선순위순)
const coreComponents = [
  'Button', // 가장 많이 사용
  'Input', // 폼의 기본
  'Card', // 레이아웃 기본
  'Dialog', // 모달 통합
  'Table', // 데이터 표시
  'Dropdown', // 네비게이션
]

// 각 컴포넌트에 추가한 것
interface EnhancedComponent {
  types: 'strict TypeScript props'
  docs: 'structured MDX'
  tests: 'unit + a11y + visual'
  examples: 'minimal + variations'
}

## CLAUDE.md 핵심 내용

### 컴포넌트 선택

{15개 컴포넌트 가이드 테이블}

### 토큰 사용

{Good/Bad 예시}

### 패턴

{로그인 폼, 대시보드 카드, 데이터 테이블}

// MCP 서버
const tools = [
  'get_component', // 컴포넌트 문서
  'find_pattern', // 패턴 검색
  'validate_code', // 코드 검증
  'suggest_fix', // 수정 제안
]

## 교육 세션

### Session 1: 기본 (2시간)

- 토큰 시스템 이해
- 컴포넌트 사용법
- AI와 함께 코딩

### Session 2: 실습 (4시간)

- 실제 기능 구현
- 코드 리뷰
- 피드백 반영

## 피드백 수집

- "토큰 찾기 어려움" → 검색 도구 개선
- "예시 부족" → 예시 추가
- "AI가 잘못된 컴포넌트 선택" → CLAUDE.md 보강

## Day 1

1. 현황 감사 (토큰, 컴포넌트)
2. 핵심 토큰 10개 정의
3. 버튼 컴포넌트 마이그레이션

## Week 1

1. 코어 컴포넌트 5개 완성
2. 기본 CLAUDE.md 작성
3. 첫 번째 AI 코드 생성 테스트

## Month 1

1. 모든 코어 컴포넌트 완성
2. MCP 서버 구축
3. CI 파이프라인
4. 팀 온보딩 시작

// Material 3 Expressive 토큰 예시
const m3eTokens = {
  color: {
    primary: 'md.sys.color.primary',
    onPrimary: 'md.sys.color.on-primary',
    surface: 'md.sys.color.surface',
    // Dynamic Color: 사용자 배경에서 추출
    dynamicPrimary: 'md.sys.color.dynamic.primary',
  },
  motion: {
    // M3E 신규: Expressive 모션 커브
    expressiveStandard: 'md.sys.motion.easing.expressive',
    expressiveFling: 'md.sys.motion.easing.expressive-fling',
    duration: {
      short: 'md.sys.motion.duration.short3',  // 250ms
      medium: 'md.sys.motion.duration.medium2', // 400ms
    },
  },
  typography: {
    // M3E 신규: 임팩트 있는 디스플레이 폰트
    displayLarge: 'md.sys.typescale.display-large',
    expressiveHeadline: 'md.sys.typescale.expressive-headline',
  },
}

## Apple HIG — AI 통합 원칙 (요약)

### 1. 투명성 (Transparency)
- AI가 생성한 콘텐츠임을 사용자에게 명확히 표시
- 생성 과정에서 사용자에게 피드백 제공

### 2. 사용자 통제 (User Control)
- AI 결과물의 편집/거부 항상 가능
- 자동 적용 대신 사용자 확인 단계 필수

### 3. 기대 관리 (Setting Expectations)
- AI 기능의 한계를 솔직하게 전달
- 생성 결과의 품질 수준을 미리 안내

### 4. 접근성 (Accessibility)
- AI 기능이 보조 기술과 완전히 호환
- VoiceOver, Switch Control 등에서 동등한 경험

// Fluent 2 + Copilot 컴포넌트 구조 예시
const copilotPatterns = {
  // 대화 인터페이스 구성
  conversationUI: {
    inputArea: 'FluentTextarea + ActionBar',
    messageList: 'ChatMessage + ContextCards',
    suggestions: 'SuggestedActions (최대 3개)',
  },
  // 에이전트 상태 표시
  agentStatus: {
    thinking: 'ProgressBar + StatusLabel',
    acting: 'ActionCard + StepIndicator',
    complete: 'ResultCard + FeedbackButtons',
  },
  // 컨텍스트 카드: AI 응답에 참조 소스 표시
  contextCard: {
    source: 'DocumentReference',
    preview: 'ContentSnippet',
    action: 'OpenInApp | CopyToClipboard',
  },
}