접근성 내장

// accessibility/roles.ts

/**
 * 컴포넌트-ARIA Role 매핑
 * @ai-hint 컴포넌트 생성 시 자동으로 적절한 role 적용
 */
export const componentRoleMap = {
  // 인터랙티브
  Button: 'button',
  Link: 'link',
  Checkbox: 'checkbox',
  Radio: 'radio',
  Switch: 'switch',
  Slider: 'slider',

  // 컨테이너
  Dialog: 'dialog',
  AlertDialog: 'alertdialog',
  Menu: 'menu',
  Listbox: 'listbox',
  Combobox: 'combobox',
  TabList: 'tablist',
  Tab: 'tab',
  TabPanel: 'tabpanel',

  // 정보 표시
  Alert: 'alert',
  Status: 'status',
  Tooltip: 'tooltip',
  ProgressBar: 'progressbar',

  // 랜드마크
  Navigation: 'navigation',
  Main: 'main',
  Complementary: 'complementary',
  Region: 'region',
} as const

// accessibility/states.ts

interface AriaState {
  /** 확장/축소 상태 */
  'aria-expanded'?: boolean
  /** 선택 상태 (단일 선택) */
  'aria-selected'?: boolean
  /** 체크 상태 (true/false/mixed) */
  'aria-checked'?: boolean | 'mixed'
  /** 비활성화 */
  'aria-disabled'?: boolean
  /** 눌림 상태 (토글 버튼) */
  'aria-pressed'?: boolean | 'mixed'
  /** 숨김 (스크린리더에서) */
  'aria-hidden'?: boolean
  /** 현재 항목 */
  'aria-current'?: 'page' | 'step' | 'location' | 'date' | 'time' | true
  /** 유효하지 않은 입력 */
  'aria-invalid'?: boolean | 'grammar' | 'spelling'
  /** 필수 입력 */
  'aria-required'?: boolean
  /** 로딩/진행 중 */
  'aria-busy'?: boolean
}

// accessibility/relationships.ts

interface AriaRelationship {
  /** 설명하는 요소 ID */
  'aria-describedby'?: string
  /** 레이블하는 요소 ID */
  'aria-labelledby'?: string
  /** 제어하는 요소 ID */
  'aria-controls'?: string
  /** 소유하는 요소 ID */
  'aria-owns'?: string
  /** 활성 자손 요소 ID */
  'aria-activedescendant'?: string
  /** 에러 메시지 요소 ID */
  'aria-errormessage'?: string
}

/**
 * 관계 ID 생성 유틸리티
 * @ai-hint 컴포넌트 간 ARIA 관계 설정 시 사용
 */
export function createAriaIds(baseId: string) {
  return {
    root: baseId,
    label: `${baseId}-label`,
    description: `${baseId}-desc`,
    error: `${baseId}-error`,
    listbox: `${baseId}-listbox`,
    option: (index: number) => `${baseId}-option-${index}`,
  }
}

// accessibility/keyboard.ts

/**
 * 컴포넌트별 키보드 인터랙션 패턴
 * @ai-hint 컴포넌트 구현 시 해당 키 핸들링 필수
 */
export const keyboardPatterns = {
  Button: {
    Enter: 'activate',
    Space: 'activate',
  },

  Menu: {
    Enter: 'select',
    Space: 'select',
    ArrowDown: 'next',
    ArrowUp: 'previous',
    Home: 'first',
    End: 'last',
    Escape: 'close',
    Tab: 'close and move focus',
  },

  Tabs: {
    ArrowLeft: 'previous tab',
    ArrowRight: 'next tab',
    Home: 'first tab',
    End: 'last tab',
    Enter: 'activate (manual)',
    Space: 'activate (manual)',
  },

  Combobox: {
    ArrowDown: 'open or next',
    ArrowUp: 'previous',
    Enter: 'select',
    Escape: 'close',
    Home: 'first (open)',
    End: 'last (open)',
    // 문자 입력: typeahead
  },

  Dialog: {
    Tab: 'cycle focus within',
    Escape: 'close',
  },

  Slider: {
    ArrowRight: 'increase',
    ArrowUp: 'increase',
    ArrowLeft: 'decrease',
    ArrowDown: 'decrease',
    Home: 'minimum',
    End: 'maximum',
    PageUp: 'large increase',
    PageDown: 'large decrease',
  },
} as const

// components/focus-trap/index.tsx

interface FocusTrapProps {
  children: React.ReactNode
  /** 트랩 활성화 여부 */
  active?: boolean
  /** 최초 포커스 요소 선택자 */
  initialFocus?: string
  /** 비활성화 시 복원할 포커스 요소 */
  returnFocus?: boolean
}

/**
 * 포커스 트랩 컴포넌트
 * @ai-hint Dialog, Modal, Drawer 내부에서 사용
 * - Tab 순환 (마지막 → 첫 번째)
 * - Shift+Tab 역순환
 * - 외부 요소 포커스 방지
 */
export function FocusTrap({
  children,
  active = true,
  initialFocus,
  returnFocus = true,
}: FocusTrapProps) {
  // 구현 생략
}

// components/visually-hidden/index.tsx

/**
 * 시각적으로 숨기되 스크린리더에는 노출
 * @ai-hint 아이콘 버튼, 복잡한 시각 요소에 레이블 추가 시 사용
 */
export function VisuallyHidden({ children }: { children: React.ReactNode }) {
  return (
    <span
      style={{
        position: 'absolute',
        width: '1px',
        height: '1px',
        padding: 0,
        margin: '-1px',
        overflow: 'hidden',
        clip: 'rect(0, 0, 0, 0)',
        whiteSpace: 'nowrap',
        border: 0,
      }}
    >
      {children}
    </span>
  )
}

// 사용 예시
<Button>
  <SearchIcon aria-hidden="true" />
  <VisuallyHidden>검색</VisuallyHidden>
</Button>

// components/announcer/index.tsx

interface AnnouncerProps {
  /** 알림 메시지 */
  message: string
  /** 긴급도: polite(대기) | assertive(즉시) */
  politeness?: 'polite' | 'assertive'
}

/**
 * 스크린리더 알림 컴포넌트
 * @ai-hint 동적 콘텐츠 변경, 폼 제출 결과 등에서 사용
 */
export function Announcer({ message, politeness = 'polite' }: AnnouncerProps) {
  return (
    <div
      role="status"
      aria-live={politeness}
      aria-atomic="true"
      className="sr-only"
    >
      {message}
    </div>
  )
}

// tokens/colors.contrast.ts

/**
 * 전경-배경 페어링 정의
 * @ai-hint 이 페어링만 사용하면 WCAG AA 보장
 */
export const contrastPairs = {
  // 기본 텍스트
  'foreground.default': {
    on: ['background.default', 'background.surface'],
    contrast: 7.2, // AAA
  },
  'foreground.muted': {
    on: ['background.default', 'background.surface'],
    contrast: 4.5, // AA
  },

  // 인터랙티브
  primary: {
    on: ['background.default'],
    contrast: 4.5,
    foreground: 'foreground.inverted', // 위에 올라갈 텍스트
    foregroundContrast: 4.8,
  },
  destructive: {
    on: ['background.default'],
    contrast: 4.5,
    foreground: 'foreground.inverted',
    foregroundContrast: 5.1,
  },

  // 보더
  'border.default': {
    on: ['background.default'],
    contrast: 3.0, // UI 컴포넌트 기준
  },
} as const

// scripts/check-contrast.ts

import { getContrastRatio } from './utils'
import { colors, contrastPairs } from '../tokens'

function checkAllContrasts() {
  const failures: string[] = []

  for (const [fg, config] of Object.entries(contrastPairs)) {
    for (const bg of config.on) {
      const ratio = getContrastRatio(colors[fg], colors[bg])
      if (ratio < config.contrast) {
        failures.push(`${fg} on ${bg}: ${ratio.toFixed(2)} < ${config.contrast}`)
      }
    }
  }

  if (failures.length > 0) {
    console.error('Contrast check failed:')
    failures.forEach((f) => console.error(`  - ${f}`))
    process.exit(1)
  }

  console.log('✓ All contrast ratios pass WCAG criteria')
}

// tests/accessibility.test.ts

import { axe, toHaveNoViolations } from 'jest-axe'
import { render } from '@testing-library/react'

expect.extend(toHaveNoViolations)

describe('Button Accessibility', () => {
  it('기본 버튼은 접근성 위반 없음', async () => {
    const { container } = render(
      <Button onClick={() => {}}>클릭</Button>
    )
    const results = await axe(container)
    expect(results).toHaveNoViolations()
  })

  it('아이콘 버튼은 aria-label 필수', async () => {
    const { container } = render(
      <Button size="icon" aria-label="설정">
        <SettingsIcon />
      </Button>
    )
    const results = await axe(container)
    expect(results).toHaveNoViolations()
  })
})

// e2e/accessibility.spec.ts

import { test, expect } from '@playwright/test'
import AxeBuilder from '@axe-core/playwright'

test.describe('Homepage Accessibility', () => {
  test('전체 페이지 WCAG 2.1 AA 준수', async ({ page }) => {
    await page.goto('/')

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
      .analyze()

    expect(results.violations).toEqual([])
  })

  test('키보드로 모든 인터랙티브 요소 접근 가능', async ({ page }) => {
    await page.goto('/')

    // Tab으로 순회
    const focusableElements = await page
      .locator('button, a, input, select, textarea, [tabindex="0"]')
      .all()

    for (const el of focusableElements) {
      await page.keyboard.press('Tab')
      await expect(el).toBeFocused()
    }
  })
})