@kood/claude-code 0.1.0

package/templates/tanstack-start/docs/design/accessibility.md

@@ -0,0 +1,433 @@
+# 접근성 (Accessibility)
+
+> **상위 문서**: [UI/UX 디자인 가이드](./index.md)
+
+접근성(A11y)은 장애가 있는 사용자도 웹사이트를 사용할 수 있게 만드는 것입니다. 이는 윤리적 의무이자 법적 요구사항이기도 합니다.
+
+## 왜 접근성이 중요한가?
+
+### 접근성이 필요한 사용자
+
+| 유형 | 예시 | 필요한 지원 |
+|------|------|------------|
+| **시각 장애** | 전맹, 저시력, 색맹 | 스크린 리더, 고대비, 큰 텍스트 |
+| **청각 장애** | 난청, 전농 | 자막, 시각적 알림 |
+| **운동 장애** | 손떨림, 마비 | 키보드 네비게이션, 큰 클릭 영역 |
+| **인지 장애** | 읽기 장애, 집중력 장애 | 단순한 언어, 명확한 구조 |
+
+### 접근성의 이점
+
+- 법적 준수 (ADA, 장애인차별금지법)
+- 더 넓은 사용자층
+- SEO 개선 (검색 엔진도 접근성 기준 활용)
+- 전반적인 UX 향상 (모든 사용자에게 도움)
+
+## WCAG 기준
+
+WCAG(Web Content Accessibility Guidelines)는 웹 접근성의 국제 표준입니다.
+
+### 준수 수준
+
+```
+Level A   - 최소 기준 (필수)
+Level AA  - 권장 기준 (일반적 목표)
+Level AAA - 최고 기준 (특수한 경우)
+```
+
+### 4가지 원칙 (POUR)
+
+```
+P - Perceivable   (인식 가능)  모든 정보를 인식할 수 있어야 함
+O - Operable      (조작 가능)  모든 기능을 조작할 수 있어야 함
+U - Understandable (이해 가능)  내용을 이해할 수 있어야 함
+R - Robust        (견고함)     다양한 기술에서 동작해야 함
+```
+
+## 색상 접근성
+
+### 색상 대비 요구사항
+
+| 텍스트 유형 | 최소 대비 (AA) | 권장 대비 (AAA) |
+|------------|---------------|----------------|
+| 일반 텍스트 (< 18px) | 4.5:1 | 7:1 |
+| 큰 텍스트 (≥ 18px bold, ≥ 24px) | 3:1 | 4.5:1 |
+| UI 컴포넌트, 그래픽 | 3:1 | - |
+
+### 안전한 색상 조합
+
+```tsx
+// ✅ 좋은 대비
+<p className="text-gray-900 bg-white">검정 on 흰색 (21:1)</p>
+<p className="text-white bg-blue-700">흰색 on 진한 파랑 (8.6:1)</p>
+<p className="text-gray-700 bg-gray-100">진한 회색 on 밝은 회색 (5.4:1)</p>
+
+// ❌ 나쁜 대비
+<p className="text-gray-400 bg-white">밝은 회색 on 흰색 (2.7:1)</p>
+<p className="text-yellow-500 bg-white">노란색 on 흰색 (1.3:1)</p>
+```
+
+### 색상만으로 정보 전달 금지
+
+```tsx
+// ❌ 나쁜 예 - 색상만으로 구분
+<span className="text-red-600">오류</span>
+<span className="text-green-600">성공</span>
+
+// ✅ 좋은 예 - 아이콘/텍스트 병행
+<span className="text-red-600 flex items-center gap-1">
+  <XCircleIcon className="w-4 h-4" />
+  오류가 발생했습니다
+</span>
+<span className="text-green-600 flex items-center gap-1">
+  <CheckCircleIcon className="w-4 h-4" />
+  성공적으로 저장됨
+</span>
+```
+
+## 키보드 접근성
+
+### 모든 기능은 키보드로 가능해야 함
+
+```
+Tab       다음 요소로 이동
+Shift+Tab 이전 요소로 이동
+Enter     버튼 클릭, 링크 이동
+Space     체크박스 토글, 버튼 클릭
+Escape    모달 닫기, 취소
+Arrow     드롭다운, 슬라이더 조작
+```
+
+### 포커스 표시
+
+```tsx
+// ✅ 명확한 포커스 스타일
+<button className="focus:outline-none focus:ring-2 focus:ring-blue-500
+                   focus:ring-offset-2">
+  버튼
+</button>
+
+// 입력 필드
+<input className="focus:outline-none focus:ring-2 focus:ring-blue-500
+                  focus:border-blue-500" />
+
+// ❌ 포커스 제거 금지
+<button className="outline-none focus:outline-none">
+  {/* 접근성 위반! */}
+</button>
+```
+
+### 포커스 순서
+
+```tsx
+// 논리적인 탭 순서 유지
+<form>
+  <input tabIndex={0} /> {/* 1번째 */}
+  <input tabIndex={0} /> {/* 2번째 */}
+  <button tabIndex={0}>취소</button> {/* 3번째 */}
+  <button tabIndex={0}>저장</button> {/* 4번째 */}
+</form>
+
+// ❌ tabIndex로 순서 강제 변경 피하기
+<button tabIndex={2}>저장</button>
+<button tabIndex={1}>취소</button>
+```
+
+### 포커스 트랩 (모달)
+
+```tsx
+// 모달이 열리면 포커스가 모달 안에만 머물러야 함
+const Modal = ({ isOpen, onClose }) => {
+  const modalRef = useRef(null)
+
+  useEffect(() => {
+    if (isOpen) {
+      // 모달 열릴 때 첫 번째 요소에 포커스
+      modalRef.current?.querySelector('button')?.focus()
+    }
+  }, [isOpen])
+
+  const handleKeyDown = (e) => {
+    if (e.key === 'Escape') onClose()
+  }
+
+  return (
+    <div
+      ref={modalRef}
+      role="dialog"
+      aria-modal="true"
+      onKeyDown={handleKeyDown}
+    >
+      {/* 모달 내용 */}
+    </div>
+  )
+}
+```
+
+## 시맨틱 HTML
+
+### 올바른 HTML 요소 사용
+
+```tsx
+// ✅ 시맨틱 HTML
+<header>...</header>
+<nav>...</nav>
+<main>
+  <article>
+    <h1>제목</h1>
+    <section>...</section>
+  </article>
+</main>
+<footer>...</footer>
+
+// ❌ div 남용
+<div className="header">...</div>
+<div className="nav">...</div>
+<div className="main">...</div>
+```
+
+### 제목 계층
+
+```tsx
+// ✅ 올바른 제목 순서
+<h1>페이지 제목</h1>
+  <h2>섹션 1</h2>
+    <h3>하위 섹션 1-1</h3>
+  <h2>섹션 2</h2>
+
+// ❌ 제목 레벨 건너뛰기
+<h1>페이지 제목</h1>
+  <h3>섹션</h3>  {/* h2를 건너뜀 */}
+```
+
+### 버튼 vs 링크
+
+```tsx
+// 버튼: 동작 수행
+<button onClick={handleSave}>저장</button>
+
+// 링크: 페이지 이동
+<a href="/about">소개 페이지</a>
+
+// ❌ 잘못된 사용
+<div onClick={handleSave}>저장</div>  {/* div를 버튼처럼 */}
+<a onClick={handleAction}>클릭</a>    {/* 링크를 버튼처럼 */}
+```
+
+## ARIA 속성
+
+### 필수 ARIA 사용
+
+```tsx
+// 레이블 연결
+<label htmlFor="email">이메일</label>
+<input id="email" type="email" />
+
+// 또는 aria-label 사용
+<input aria-label="검색어 입력" type="search" />
+
+// 설명 연결
+<input aria-describedby="email-hint" />
+<p id="email-hint">업무용 이메일을 입력하세요</p>
+
+// 에러 상태
+<input aria-invalid="true" aria-describedby="email-error" />
+<p id="email-error" role="alert">올바른 이메일을 입력하세요</p>
+```
+
+### 상태 알림
+
+```tsx
+// 동적 콘텐츠 변경 알림
+<div aria-live="polite">
+  {/* 변경되면 스크린 리더가 읽어줌 */}
+  {message}
+</div>
+
+// 긴급 알림
+<div aria-live="assertive" role="alert">
+  {errorMessage}
+</div>
+```
+
+### 숨김 처리
+
+```tsx
+// 시각적으로만 숨김 (스크린 리더는 읽음)
+<span className="sr-only">메뉴 열기</span>
+
+// Tailwind의 sr-only 클래스
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  border: 0;
+}
+
+// 스크린 리더에서도 숨김
+<div aria-hidden="true">장식용 아이콘</div>
+```
+
+## 폼 접근성
+
+### 레이블 필수
+
+```tsx
+// ✅ 명시적 레이블
+<label htmlFor="name">이름</label>
+<input id="name" type="text" />
+
+// ✅ 암묵적 레이블
+<label>
+  이름
+  <input type="text" />
+</label>
+
+// ✅ aria-label (시각적 레이블 없을 때)
+<input type="search" aria-label="사이트 검색" />
+```
+
+### 에러 처리
+
+```tsx
+<div>
+  <label htmlFor="email">이메일</label>
+  <input
+    id="email"
+    type="email"
+    aria-invalid={hasError}
+    aria-describedby={hasError ? "email-error" : undefined}
+    className={hasError ? "border-red-500" : "border-gray-300"}
+  />
+  {hasError && (
+    <p id="email-error" className="text-red-600 text-sm mt-1" role="alert">
+      올바른 이메일 형식을 입력하세요
+    </p>
+  )}
+</div>
+```
+
+### 필수 필드 표시
+
+```tsx
+<label htmlFor="email">
+  이메일 <span className="text-red-600" aria-hidden="true">*</span>
+  <span className="sr-only">(필수)</span>
+</label>
+<input id="email" required aria-required="true" />
+```
+
+## 이미지 접근성
+
+### 대체 텍스트 (alt)
+
+```tsx
+// 정보 전달 이미지 - 설명 필요
+<img src="chart.png" alt="2024년 매출 추이: 1월 100만원에서 12월 500만원으로 성장" />
+
+// 장식용 이미지 - 빈 alt
+<img src="decorative.png" alt="" />
+
+// 아이콘 버튼 - 기능 설명
+<button aria-label="닫기">
+  <img src="close.svg" alt="" />
+</button>
+```
+
+## 터치 접근성
+
+### 최소 터치 영역
+
+```tsx
+// 최소 44x44px 터치 영역
+<button className="min-w-[44px] min-h-[44px] p-2">
+  <Icon className="w-6 h-6" />
+</button>
+
+// 작은 체크박스도 터치 영역 확보
+<label className="flex items-center gap-2 p-2 -m-2 cursor-pointer">
+  <input type="checkbox" className="w-4 h-4" />
+  <span>동의합니다</span>
+</label>
+```
+
+### 터치 타겟 간격
+
+```tsx
+// 터치 타겟 사이 최소 8px 간격
+<div className="flex gap-2">
+  <button className="p-3">버튼 1</button>
+  <button className="p-3">버튼 2</button>
+</div>
+```
+
+## 접근성 테스트
+
+### 자동화 도구
+
+| 도구 | 용도 |
+|------|------|
+| **axe DevTools** | 브라우저 확장, 자동 검사 |
+| **Lighthouse** | Chrome 내장, 접근성 점수 |
+| **WAVE** | 시각적 피드백 |
+| **eslint-plugin-jsx-a11y** | 코드 레벨 검사 |
+
+### 수동 테스트
+
+```
+1. 키보드만으로 모든 기능 사용 가능한가?
+2. Tab 순서가 논리적인가?
+3. 포커스 표시가 명확한가?
+4. 스크린 리더로 내용을 이해할 수 있는가?
+5. 200% 확대해도 사용 가능한가?
+```
+
+### ESLint 설정
+
+```bash
+yarn add -D eslint-plugin-jsx-a11y
+```
+
+```js
+// eslint.config.js
+import jsxA11y from 'eslint-plugin-jsx-a11y'
+
+export default [
+  {
+    plugins: { 'jsx-a11y': jsxA11y },
+    rules: {
+      'jsx-a11y/alt-text': 'error',
+      'jsx-a11y/anchor-has-content': 'error',
+      'jsx-a11y/click-events-have-key-events': 'error',
+      'jsx-a11y/no-noninteractive-element-interactions': 'error',
+    },
+  },
+]
+```
+
+## 체크리스트
+
+### 필수 (Level A)
+
+- [ ] 모든 이미지에 alt 텍스트
+- [ ] 모든 폼 요소에 레이블
+- [ ] 키보드로 모든 기능 접근 가능
+- [ ] 포커스 표시 유지
+- [ ] 색상만으로 정보 전달하지 않음
+
+### 권장 (Level AA)
+
+- [ ] 텍스트 대비 4.5:1 이상
+- [ ] 페이지 제목 명확
+- [ ] 제목 계층 논리적
+- [ ] 에러 메시지 명확
+- [ ] 200% 확대 시 가로 스크롤 없음
+
+### 최고 수준 (Level AAA)
+
+- [ ] 텍스트 대비 7:1 이상
+- [ ] 읽기 수준 고려
+- [ ] 약어 설명 제공

package/templates/tanstack-start/docs/design/color.md

@@ -0,0 +1,235 @@
+# 색상 시스템
+
+> **상위 문서**: [UI/UX 디자인 가이드](./index.md)
+
+색상은 UI에서 가장 강력한 시각적 요소입니다. 일관된 색상 사용은 브랜드 인지도를 높이고 사용자 경험을 개선합니다.
+
+## 60-30-10 규칙
+
+디자이너들이 가장 많이 사용하는 색상 배분 규칙입니다.
+
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│              60% 기본색 (Primary)               │
+│              배경, 여백, 기본 영역               │
+│                                                 │
+├───────────────────────────────────┬─────────────┤
+│                                   │             │
+│       30% 보조색 (Secondary)      │    10%      │
+│       카드, 섹션, 구분 영역        │   강조색    │
+│                                   │   (Accent)  │
+│                                   │   버튼,     │
+│                                   │   링크,     │
+│                                   │   CTA       │
+└───────────────────────────────────┴─────────────┘
+```
+
+### 실제 적용 예시
+
+```tsx
+// 60% - 배경
+<div className="bg-white">              {/* 흰색 배경 */}
+
+  // 30% - 보조 영역
+  <section className="bg-gray-50">      {/* 밝은 회색 섹션 */}
+    <div className="bg-white">          {/* 카드 배경 */}
+
+      // 10% - 강조
+      <button className="bg-blue-600">  {/* 주요 버튼 */}
+        시작하기
+      </button>
+    </div>
+  </section>
+</div>
+```
+
+## 색상 팔레트 구성
+
+### 1. 기본 색상 (Neutral Colors)
+
+배경, 텍스트, 테두리에 사용하는 중립적인 색상입니다.
+
+```
+White       #FFFFFF   bg-white        가장 밝은 배경
+Gray 50     #F9FAFB   bg-gray-50      섹션 배경
+Gray 100    #F3F4F6   bg-gray-100     카드 배경, hover
+Gray 200    #E5E7EB   bg-gray-200     테두리, 구분선
+Gray 300    #D1D5DB   bg-gray-300     비활성 테두리
+Gray 400    #9CA3AF   text-gray-400   비활성 텍스트
+Gray 500    #6B7280   text-gray-500   보조 텍스트
+Gray 600    #4B5563   text-gray-600   부제목
+Gray 700    #374151   text-gray-700   본문
+Gray 800    #1F2937   text-gray-800   제목
+Gray 900    #111827   text-gray-900   강조 텍스트
+```
+
+### 2. 브랜드 색상 (Brand Colors)
+
+서비스를 대표하는 주요 색상입니다. **1-2가지**만 선택하세요.
+
+```tsx
+// 예시: 파란색 브랜드
+const brandColors = {
+  primary: {
+    50:  '#EFF6FF',  // 매우 밝은 배경
+    100: '#DBEAFE',  // 밝은 배경
+    200: '#BFDBFE',  // hover 배경
+    300: '#93C5FD',  // 테두리
+    400: '#60A5FA',  // 비활성 버튼
+    500: '#3B82F6',  // 기본 버튼
+    600: '#2563EB',  // hover 버튼
+    700: '#1D4ED8',  // active 버튼
+    800: '#1E40AF',  // 어두운 버튼
+    900: '#1E3A8A',  // 매우 어두운
+  }
+}
+```
+
+### 3. 의미론적 색상 (Semantic Colors)
+
+특정 의미를 가진 색상입니다. **절대 다른 용도로 사용하지 마세요.**
+
+| 색상 | 의미 | 사용처 | Tailwind |
+|------|------|--------|----------|
+| 🟢 Green | 성공, 완료 | 성공 메시지, 체크 | `text-green-600` |
+| 🔴 Red | 오류, 위험 | 에러 메시지, 삭제 | `text-red-600` |
+| 🟡 Yellow | 경고, 주의 | 경고 메시지 | `text-yellow-600` |
+| 🔵 Blue | 정보, 안내 | 안내 메시지, 링크 | `text-blue-600` |
+
+```tsx
+// ✅ 올바른 사용
+<span className="text-green-600">저장되었습니다</span>
+<span className="text-red-600">필수 항목입니다</span>
+
+// ❌ 잘못된 사용 - 빨간색을 장식용으로
+<span className="text-red-600">새로운 기능!</span>
+```
+
+## 색상 대비 (Contrast)
+
+### WCAG 접근성 기준
+
+텍스트가 잘 읽히려면 배경과 충분한 대비가 필요합니다.
+
+| 기준 | 최소 대비 | 적용 대상 |
+|------|----------|----------|
+| AA (일반) | 4.5:1 | 일반 텍스트 (16px 미만) |
+| AA (큰 텍스트) | 3:1 | 큰 텍스트 (18px 이상) |
+| AAA (강화) | 7:1 | 최고 수준 접근성 |
+
+### 안전한 조합
+
+```tsx
+// ✅ 좋은 대비 (흰 배경)
+<p className="text-gray-900">진한 텍스트 - 대비 15.8:1</p>
+<p className="text-gray-700">본문 텍스트 - 대비 8.6:1</p>
+<p className="text-gray-600">보조 텍스트 - 대비 5.7:1</p>
+
+// ⚠️ 주의 필요
+<p className="text-gray-500">밝은 텍스트 - 대비 4.6:1 (경계)</p>
+
+// ❌ 피해야 함
+<p className="text-gray-400">너무 밝음 - 대비 3.0:1</p>
+```
+
+### 버튼 색상 대비
+
+```tsx
+// ✅ 좋은 버튼 대비
+<button className="bg-blue-600 text-white">    {/* 흰색 on 파란색 */}
+<button className="bg-gray-900 text-white">    {/* 흰색 on 검정색 */}
+<button className="bg-white text-gray-900 border"> {/* 검정색 on 흰색 */}
+
+// ❌ 나쁜 버튼 대비
+<button className="bg-yellow-300 text-white">  {/* 대비 부족 */}
+<button className="bg-gray-200 text-gray-400"> {/* 대비 부족 */}
+```
+
+## 다크 모드
+
+다크 모드는 선택이 아닌 필수가 되어가고 있습니다.
+
+### 색상 반전 원칙
+
+```
+라이트 모드              다크 모드
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+bg-white         ←→     bg-gray-900
+bg-gray-50       ←→     bg-gray-800
+bg-gray-100      ←→     bg-gray-700
+text-gray-900    ←→     text-white
+text-gray-700    ←→     text-gray-200
+text-gray-500    ←→     text-gray-400
+```
+
+### Tailwind 다크 모드 적용
+
+```tsx
+// 기본 패턴
+<div className="bg-white dark:bg-gray-900">
+  <h1 className="text-gray-900 dark:text-white">제목</h1>
+  <p className="text-gray-600 dark:text-gray-300">본문</p>
+</div>
+
+// 카드 컴포넌트
+<div className="bg-white dark:bg-gray-800
+               border border-gray-200 dark:border-gray-700
+               shadow-sm">
+  <h3 className="text-gray-900 dark:text-white">카드 제목</h3>
+</div>
+```
+
+## 색상 사용 체크리스트
+
+### 반드시 지켜야 할 것
+
+- [ ] 브랜드 색상은 1-2가지만 사용
+- [ ] 의미론적 색상(빨강, 초록 등)은 해당 의미로만 사용
+- [ ] 텍스트-배경 대비 4.5:1 이상 유지
+- [ ] 색상만으로 정보 전달하지 않기 (아이콘/텍스트 병행)
+
+### 권장 사항
+
+- [ ] 60-30-10 규칙 따르기
+- [ ] 다크 모드 지원
+- [ ] 색상 변수(토큰) 사용
+- [ ] 일관된 색상 네이밍
+
+## Tailwind 설정
+
+```css
+/* src/styles/app.css */
+@import "tailwindcss";
+
+@theme {
+  /* 브랜드 색상 */
+  --color-primary-50: oklch(0.97 0.01 250);
+  --color-primary-100: oklch(0.93 0.03 250);
+  --color-primary-500: oklch(0.55 0.2 250);
+  --color-primary-600: oklch(0.48 0.22 250);
+  --color-primary-700: oklch(0.42 0.2 250);
+
+  /* 의미론적 색상 */
+  --color-success: oklch(0.55 0.15 145);
+  --color-error: oklch(0.55 0.2 25);
+  --color-warning: oklch(0.75 0.15 85);
+  --color-info: oklch(0.55 0.2 250);
+}
+```
+
+```tsx
+// 사용 예시
+<button className="bg-primary-600 hover:bg-primary-700">
+  주요 버튼
+</button>
+
+<span className="text-success">성공!</span>
+<span className="text-error">오류 발생</span>
+```
+
+## 참고 자료
+
+- [Tailwind CSS Colors](https://tailwindcss.com/docs/colors)
+- [WCAG Color Contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)
+- [Coolors - 색상 팔레트 생성](https://coolors.co/)