@kood/claude-code 0.1.6 → 0.1.9

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

@@ -1,107 +1,151 @@
 # UI/UX 디자인 가이드
 
-> **상위 문서**: [홈](../index.md)
+> TanStack Start + Tailwind CSS v4
 
-TanStack Start + Tailwind CSS 프로젝트를 위한 UI/UX 디자인 가이드입니다.
+@components.md
+@safe-area.md
+@tailwind-setup.md
 
-## 왜 디자인 시스템이 필요한가?
+---
 
-디자인 시스템은 **일관된 사용자 경험**을 만들기 위한 규칙과 컴포넌트의 모음입니다.
-
-### 디자인 시스템의 장점
+## 핵심 원칙
 
-| 장점 | 설명 |
+| 원칙 | 설명 |
 |------|------|
-| **일관성** | 모든 페이지에서 동일한 룩앤필 제공 |
-| **효율성** | 재사용 가능한 컴포넌트로 개발 속도 향상 |
-| **유지보수** | 한 곳에서 수정하면 전체에 반영 |
-| **협업** | 디자이너-개발자 간 명확한 기준 공유 |
+| **일관성** | 같은 요소는 같은 스타일과 동작 |
+| **계층 구조** | 중요한 것이 먼저 눈에 들어옴 |
+| **단순함** | 색상 3-5개, 폰트 2-3개, 충분한 여백 |
+| **접근성** | 충분한 대비, 읽기 쉬운 크기, 키보드 조작 |
+
+---
 
-## 가이드 구성
+## 색상 (60-30-10 규칙)
 
 ```
-docs/design/
-├── index.md              # 이 문서 (개요)
-├── color.md              # 색상 시스템
-├── typography.md         # 타이포그래피 (폰트)
-├── spacing.md            # 간격과 레이아웃
-├── components.md         # 컴포넌트 가이드라인
-├── accessibility.md      # 접근성
-├── safe-area.md          # iOS Safe Area
-└── tailwind-setup.md     # Tailwind CSS 설정
+60% - 배경색 (중립색)
+30% - 보조색 (카드, 섹션)
+10% - 강조색 (버튼, CTA)
 ```
 
-## 핵심 원칙
+### 의미론적 색상
 
-### 1. 일관성 (Consistency)
+| 색상 | 의미 | Tailwind |
+|------|------|----------|
+| 🟢 Green | 성공 | `text-green-600` |
+| 🔴 Red | 오류 | `text-red-600` |
+| 🟡 Yellow | 경고 | `text-yellow-600` |
+| 🔵 Blue | 정보 | `text-blue-600` |
 
-> 같은 요소는 항상 같은 모습과 동작을 가져야 합니다.
+### 다크 모드 매핑
 
-- 버튼은 항상 같은 스타일
-- 같은 종류의 텍스트는 같은 크기와 색상
-- 동일한 간격 규칙 적용
+```
+라이트 ←→ 다크
+bg-white     ←→ bg-gray-900
+bg-gray-50   ←→ bg-gray-800
+text-gray-900 ←→ text-white
+text-gray-600 ←→ text-gray-300
+```
 
-### 2. 계층 구조 (Hierarchy)
+---
 
-> 중요한 것이 먼저 눈에 들어와야 합니다.
+## 폰트
 
-- 제목 > 부제목 > 본문 순서로 크기 차이
-- 주요 버튼은 눈에 띄는 색상
-- 여백으로 콘텐츠 그룹 구분
+| 폰트 | 용도 |
+|------|------|
+| Pretendard | 한글 (권장) |
+| Inter | 영문 |
+| JetBrains Mono | 코드 |
 
-### 3. 단순함 (Simplicity)
+### 크기
 
-> 불필요한 요소는 제거합니다.
+```
+text-4xl  36px  h1
+text-2xl  24px  h2, h3
+text-base 16px  본문
+text-sm   14px  보조 텍스트
+```
 
-- 색상은 3-5가지만 사용
-- 폰트는 2-3개만 사용
-- 여백을 충분히 활용
+### Tailwind 설정
 
-### 4. 접근성 (Accessibility)
+```css
+@theme {
+  --font-sans: "Pretendard", "Inter", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", monospace;
+}
+```
 
-> 모든 사용자가 사용할 수 있어야 합니다.
+---
 
-- 충분한 색상 대비
-- 읽기 쉬운 폰트 크기
-- 키보드로도 조작 가능
+## 간격 (8px 그리드)
 
-## 빠른 참조
+| 용도 | Tailwind | 크기 |
+|------|----------|------|
+| 아이콘-텍스트 | gap-1 | 4px |
+| 인라인 요소 | gap-2 | 8px |
+| 카드 내부 | p-4 | 16px |
+| 카드 간격 | gap-6 | 24px |
+| 섹션 간격 | py-12 | 48px |
 
-### 색상 (60-30-10 규칙)
+### 컨테이너
 
 ```
-60% - 배경색 (흰색, 회색 등 중립적인 색)
-30% - 보조색 (카드, 섹션 배경)
-10% - 강조색 (버튼, 링크, CTA)
+max-w-md   448px   폼
+max-w-lg   512px   모달
+max-w-3xl  768px   블로그
+max-w-7xl  1280px  대시보드
 ```
 
-### 폰트 크기
+---
 
-```
-제목 (h1):     32-48px
-부제목 (h2):   24-32px
-소제목 (h3):   18-24px
-본문:          16-18px
-작은 텍스트:   12-14px
+## 접근성 (WCAG AA)
+
+### 색상 대비
+
+| 기준 | 최소 대비 | 적용 대상 |
+|------|----------|----------|
+| AA | 4.5:1 | 일반 텍스트 |
+| AA (큰 텍스트) | 3:1 | 18px 이상 |
+
+```tsx
+// ❌ 색상만으로 구분
+<span className="text-red-600">오류</span>
+
+// ✅ 아이콘/텍스트 병행
+<span className="text-red-600 flex items-center gap-1">
+  <XCircleIcon className="w-4 h-4" />
+  오류가 발생했습니다
+</span>
 ```
 
-### 간격 (8px 단위)
+### 키보드
 
+```tsx
+// ✅ 명확한 포커스 스타일
+<button className="focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">
+
+// ❌ 포커스 제거 금지
+<button className="outline-none focus:outline-none">
 ```
-xs:  4px   (0.25rem)
-sm:  8px   (0.5rem)
-md:  16px  (1rem)
-lg:  24px  (1.5rem)
-xl:  32px  (2rem)
-2xl: 48px  (3rem)
+
+### 폼
+
+```tsx
+<label htmlFor="email">이메일</label>
+<input
+  id="email"
+  required
+  aria-invalid={hasError}
+  aria-describedby={hasError ? "email-error" : undefined}
+/>
+{hasError && <p id="email-error" role="alert">오류</p>}
 ```
 
-## 다음 단계
+### 체크리스트
 
-1. [색상 시스템](./color.md) - 색상 팔레트와 사용 규칙
-2. [타이포그래피](./typography.md) - 폰트 선택과 텍스트 스타일
-3. [간격과 레이아웃](./spacing.md) - 여백과 그리드 시스템
-4. [컴포넌트 가이드](./components.md) - UI 컴포넌트 규칙
-5. [접근성](./accessibility.md) - WCAG 가이드라인
-6. [iOS Safe Area](./safe-area.md) - 노치, 홈 인디케이터 대응
-7. [Tailwind 설정](./tailwind-setup.md) - 실제 구현 방법
+- [ ] 모든 이미지에 alt
+- [ ] 폼 요소에 레이블
+- [ ] 키보드 접근 가능
+- [ ] 포커스 표시 유지
+- [ ] 대비 4.5:1 이상
+- [ ] 색상만으로 정보 전달 금지
+- [ ] 터치 영역 44px 이상

package/templates/tanstack-start/docs/design/safe-area.md

@@ -1,9 +1,8 @@
 # iOS Safe Area
 
-> **Framework**: TanStack Start + Tailwind CSS v4
 > **Library**: [tailwindcss-safe-area](https://github.com/mvllow/tailwindcss-safe-area)
 
-iOS 기기의 노치, 홈 인디케이터, 다이나믹 아일랜드 등을 고려한 Safe Area 처리 가이드입니다.
+iOS 노치, 홈 인디케이터, 다이나믹 아일랜드 대응.
 
 ## 설치
 
@@ -11,307 +10,109 @@ iOS 기기의 노치, 홈 인디케이터, 다이나믹 아일랜드 등을 고
 yarn add tailwindcss-safe-area
 ```
 
-## 설정
-
-### 1. Tailwind CSS 플러그인 등록
-
 ```typescript
 // tailwind.config.ts
-import type { Config } from 'tailwindcss'
 import safeArea from 'tailwindcss-safe-area'
-
-export default {
-  content: ['./src/**/*.{ts,tsx}'],
-  plugins: [safeArea],
-} satisfies Config
+export default { plugins: [safeArea] }
 ```
 
-### 2. Viewport 메타 태그 설정 (필수)
-
-Safe Area 유틸리티가 작동하려면 `viewport-fit=cover`가 **반드시** 필요합니다.
-
-```html
-<!-- app.html 또는 root layout -->
-<meta
-  name="viewport"
-  content="width=device-width, initial-scale=1, viewport-fit=cover"
-/>
-```
-
-TanStack Start에서:
+## Viewport 설정 (필수)
 
 ```typescript
 // src/routes/__root.tsx
 export const Route = createRootRoute({
   head: () => ({
-    meta: [
-      {
-        name: 'viewport',
-        content: 'width=device-width, initial-scale=1, viewport-fit=cover',
-      },
-    ],
+    meta: [{
+      name: 'viewport',
+      content: 'width=device-width, initial-scale=1, viewport-fit=cover',
+    }],
   }),
 })
 ```
 
 ## 유틸리티 클래스
 
-### Padding 유틸리티
-
+### Padding
 ```tsx
-// 전체 방향 safe area padding
-<div className="p-safe">...</div>
-
-// 개별 방향
-<header className="pt-safe">상단 노치/다이나믹 아일랜드 영역</header>
-<footer className="pb-safe">하단 홈 인디케이터 영역</footer>
-<div className="pl-safe pr-safe">좌우 safe area</div>
-
-// X축, Y축
-<div className="px-safe">좌우 safe area</div>
-<div className="py-safe">상하 safe area</div>
+<div className="p-safe">          {/* 전체 */}
+<header className="pt-safe">      {/* 상단 (노치) */}
+<footer className="pb-safe">      {/* 하단 (홈 인디케이터) */}
+<div className="px-safe py-safe"> {/* X축, Y축 */}
 ```
 
-### Margin 유틸리티
-
+### Margin
 ```tsx
-// 전체 방향 safe area margin
-<div className="m-safe">...</div>
-
-// 개별 방향
-<div className="mt-safe mb-safe">상하 margin</div>
-<div className="ml-safe mr-safe">좌우 margin</div>
-
-// X축, Y축
-<div className="mx-safe">좌우 safe area margin</div>
-<div className="my-safe">상하 safe area margin</div>
+<div className="m-safe mt-safe mb-safe mx-safe my-safe">
 ```
 
-### Height 유틸리티
-
+### Height
 ```tsx
-// Safe area를 제외한 화면 높이
-<main className="h-screen-safe">
-  전체 화면에서 safe area를 뺀 높이
-</main>
-
-// 최소 높이
-<div className="min-h-screen-safe">
-  최소 높이로 safe area 적용
-</div>
+<main className="h-screen-safe">     {/* safe area 제외 높이 */}
+<div className="min-h-screen-safe">  {/* 최소 높이 */}
 ```
 
-## Fallback 유틸리티
-
-Safe Area가 0일 때 대체 값을 지정할 수 있습니다.
-
+### Fallback (safe area 없을 때 대체값)
 ```tsx
-// safe area가 0이면 1rem(4) 적용
-<div className="p-safe-or-4">...</div>
-
-// 상단: safe area 또는 0.5rem(2)
-<header className="pt-safe-or-2">...</header>
-
-// 하단: safe area 또는 1rem(4)
-<footer className="pb-safe-or-4">...</footer>
-
-// 좌우: safe area 또는 1.5rem(6)
-<div className="px-safe-or-6">...</div>
+<div className="p-safe-or-4">    {/* safe area 또는 1rem */}
+<header className="pt-safe-or-2"> {/* 상단 또는 0.5rem */}
+<footer className="pb-safe-or-4"> {/* 하단 또는 1rem */}
 ```
 
-### Fallback 패턴
-
-| 클래스 | Safe Area 있을 때 | Safe Area 없을 때 |
-|--------|-------------------|-------------------|
-| `p-safe-or-4` | `env(safe-area-inset-*)` | `1rem` |
-| `pt-safe-or-2` | `env(safe-area-inset-top)` | `0.5rem` |
-| `pb-safe-or-4` | `env(safe-area-inset-bottom)` | `1rem` |
-| `px-safe-or-6` | `env(safe-area-inset-left/right)` | `1.5rem` |
-
-## 실전 패턴
+## 레이아웃 패턴
 
 ### 기본 앱 레이아웃
-
-```tsx
-// src/components/app-layout.tsx
-export function AppLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="min-h-screen-safe flex flex-col">
-      {/* 상단 헤더 - 노치/다이나믹 아일랜드 대응 */}
-      <header className="pt-safe-or-2 px-safe-or-4 bg-white border-b">
-        <nav className="h-14 flex items-center">
-          <h1>앱 타이틀</h1>
-        </nav>
-      </header>
-
-      {/* 메인 콘텐츠 */}
-      <main className="flex-1 px-safe-or-4">
-        {children}
-      </main>
-
-      {/* 하단 탭바 - 홈 인디케이터 대응 */}
-      <footer className="pb-safe-or-2 px-safe-or-4 bg-white border-t">
-        <nav className="h-14 flex items-center justify-around">
-          {/* 탭 아이템들 */}
-        </nav>
-      </footer>
-    </div>
-  )
-}
-```
-
-### 전체 화면 모달
-
 ```tsx
-// src/components/fullscreen-modal.tsx
-export function FullscreenModal({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="fixed inset-0 bg-white z-50">
-      <div className="h-screen-safe flex flex-col p-safe">
-        {children}
-      </div>
-    </div>
-  )
-}
+<div className="min-h-screen-safe flex flex-col">
+  <header className="pt-safe-or-2 px-safe-or-4 bg-white border-b">
+    <nav className="h-14 flex items-center">헤더</nav>
+  </header>
+  <main className="flex-1 px-safe-or-4">{children}</main>
+  <footer className="pb-safe-or-2 px-safe-or-4 bg-white border-t">
+    <nav className="h-14 flex items-center justify-around">탭바</nav>
+  </footer>
+</div>
 ```
 
 ### 고정 하단 버튼
-
 ```tsx
-// src/components/fixed-bottom-button.tsx
-export function FixedBottomButton({ children }: { children: React.ReactNode }) {
-  return (
-    <div className="fixed bottom-0 left-0 right-0 pb-safe-or-4 px-safe-or-4 bg-white border-t">
-      <button className="w-full h-12 bg-primary-600 text-white rounded-lg">
-        {children}
-      </button>
-    </div>
-  )
-}
-```
-
-### 스크롤 콘텐츠 with 고정 헤더/푸터
-
-```tsx
-export function ScrollableContent() {
-  return (
-    <div className="h-screen-safe flex flex-col">
-      {/* 고정 헤더 */}
-      <header className="pt-safe px-safe-or-4 shrink-0">
-        <div className="h-14">헤더</div>
-      </header>
-
-      {/* 스크롤 영역 */}
-      <main className="flex-1 overflow-y-auto px-safe-or-4">
-        {/* 스크롤 콘텐츠 */}
-      </main>
-
-      {/* 고정 푸터 */}
-      <footer className="pb-safe px-safe-or-4 shrink-0">
-        <div className="h-14">푸터</div>
-      </footer>
-    </div>
-  )
-}
-```
-
-## CSS 직접 사용
-
-Tailwind 유틸리티 외에 CSS에서 직접 사용할 수도 있습니다.
-
-```css
-.custom-container {
-  padding-top: env(safe-area-inset-top);
-  padding-bottom: env(safe-area-inset-bottom);
-  padding-left: env(safe-area-inset-left);
-  padding-right: env(safe-area-inset-right);
-}
-
-/* fallback 포함 */
-.custom-header {
-  padding-top: max(env(safe-area-inset-top), 1rem);
-}
+<div className="fixed bottom-0 left-0 right-0 pb-safe-or-4 px-safe-or-4 bg-white border-t">
+  <button className="w-full h-12 bg-primary-600 text-white rounded-lg">
+    버튼
+  </button>
+</div>
 ```
 
-## 높이 문제 해결
-
-모바일 브라우저에서 `100vh`가 실제 뷰포트보다 클 수 있습니다.
-
-### 해결 방법 1: h-screen-safe 사용
-
+### 전체 화면 모달
 ```tsx
-<div className="h-screen-safe">
-  {/* safe area를 고려한 정확한 높이 */}
+<div className="fixed inset-0 bg-white z-50">
+  <div className="h-screen-safe flex flex-col p-safe">{children}</div>
 </div>
 ```
 
-### 해결 방법 2: -webkit-fill-available
-
-```css
-.full-height {
-  height: 100vh;
-  height: -webkit-fill-available;
-}
-```
-
-### 해결 방법 3: dvh 단위 (권장)
-
-```css
-.full-height {
-  height: 100dvh; /* dynamic viewport height */
-}
-```
-
-Tailwind에서:
+## 높이 문제 해결
 
 ```tsx
+// 동적 뷰포트 높이 (권장)
 <div className="h-dvh">
-  {/* 동적 뷰포트 높이 */}
-</div>
-```
-
-## 디바이스별 Safe Area
 
-| 디바이스 | 상단 | 하단 | 좌우 |
-|----------|------|------|------|
-| iPhone 14 Pro/15 Pro | 59px (다이나믹 아일랜드) | 34px | 0px |
-| iPhone 14/15 | 47px (노치) | 34px | 0px |
-| iPhone SE | 20px (상태바) | 0px | 0px |
-| iPad Pro | 24px | 20px | 0px |
-| Android (일반) | 24px (상태바) | 0px | 0px |
+// 또는
+<div className="h-screen-safe">
+```
 
 ## 트러블슈팅
 
-### Safe Area가 적용되지 않음
-
-1. `viewport-fit=cover` 메타 태그 확인
-2. 플러그인이 올바르게 등록되었는지 확인
-3. 실제 iOS 기기 또는 시뮬레이터에서 테스트 (데스크톱 브라우저는 safe area가 0)
-
-### 콘텐츠가 노치에 가려짐
-
 ```tsx
-// ❌ 잘못된 예
-<header className="fixed top-0">...</header>
-
-// ✅ 올바른 예
-<header className="fixed top-0 pt-safe">...</header>
-```
+// ❌ 노치에 가려짐
+<header className="fixed top-0">
 
-### 하단 버튼이 홈 인디케이터와 겹침
+// ✅ safe area 적용
+<header className="fixed top-0 pt-safe">
 
-```tsx
-// ❌ 잘못된 예
-<button className="fixed bottom-4">...</button>
+// ❌ 홈 인디케이터와 겹침
+<button className="fixed bottom-4">
 
-// ✅ 올바른 예
+// ✅ safe area 적용
 <div className="fixed bottom-0 pb-safe-or-4">
   <button>...</button>
 </div>
 ```
-
-## 참고 자료
-
-- [tailwindcss-safe-area GitHub](https://github.com/mvllow/tailwindcss-safe-area)
-- [Apple Human Interface Guidelines - Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
-- [CSS env() function](https://developer.mozilla.org/en-US/docs/Web/CSS/env)