@kood/claude-code 0.1.0

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

@@ -0,0 +1,317 @@
+# iOS Safe Area
+
+> **Framework**: TanStack Start + Tailwind CSS v4
+> **Library**: [tailwindcss-safe-area](https://github.com/mvllow/tailwindcss-safe-area)
+
+iOS 기기의 노치, 홈 인디케이터, 다이나믹 아일랜드 등을 고려한 Safe Area 처리 가이드입니다.
+
+## 설치
+
+```bash
+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
+```
+
+### 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에서:
+
+```typescript
+// src/routes/__root.tsx
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      {
+        name: 'viewport',
+        content: 'width=device-width, initial-scale=1, viewport-fit=cover',
+      },
+    ],
+  }),
+})
+```
+
+## 유틸리티 클래스
+
+### 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>
+```
+
+### 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>
+```
+
+### Height 유틸리티
+
+```tsx
+// Safe area를 제외한 화면 높이
+<main className="h-screen-safe">
+  전체 화면에서 safe area를 뺀 높이
+</main>
+
+// 최소 높이
+<div className="min-h-screen-safe">
+  최소 높이로 safe area 적용
+</div>
+```
+
+## Fallback 유틸리티
+
+Safe Area가 0일 때 대체 값을 지정할 수 있습니다.
+
+```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>
+```
+
+### 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>
+  )
+}
+```
+
+### 고정 하단 버튼
+
+```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);
+}
+```
+
+## 높이 문제 해결
+
+모바일 브라우저에서 `100vh`가 실제 뷰포트보다 클 수 있습니다.
+
+### 해결 방법 1: h-screen-safe 사용
+
+```tsx
+<div className="h-screen-safe">
+  {/* safe area를 고려한 정확한 높이 */}
+</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 |
+
+## 트러블슈팅
+
+### 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>
+```
+
+### 하단 버튼이 홈 인디케이터와 겹침
+
+```tsx
+// ❌ 잘못된 예
+<button className="fixed bottom-4">...</button>
+
+// ✅ 올바른 예
+<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)

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

@@ -0,0 +1,341 @@
+# 간격과 레이아웃
+
+> **상위 문서**: [UI/UX 디자인 가이드](./index.md)
+
+간격(Spacing)은 요소들 사이의 여백을 말합니다. 적절한 간격은 콘텐츠를 읽기 쉽게 만들고 시각적 계층을 형성합니다.
+
+## 왜 간격이 중요한가?
+
+### 간격 없는 디자인 vs 적절한 간격
+
+```
+❌ 간격 없음                    ✅ 적절한 간격
+┌──────────────────┐           ┌──────────────────┐
+│제목본문텍스트버튼│           │                  │
+│모든것이붙어있음  │           │    제목          │
+│읽기가어려움      │           │                  │
+└──────────────────┘           │    본문 텍스트   │
+                               │                  │
+                               │    [ 버튼 ]      │
+                               │                  │
+                               └──────────────────┘
+```
+
+## 8px 그리드 시스템
+
+### 왜 8px인가?
+
+- 대부분의 화면 해상도에서 깔끔하게 나눠짐
+- 계산이 쉬움 (8, 16, 24, 32...)
+- 반응형 디자인에 유리
+
+### Tailwind 간격 스케일
+
+```css
+/* 기본 단위: 1 = 0.25rem = 4px */
+
+/* 주로 사용하는 간격 */
+1    → 4px   (0.25rem)   아주 작은 간격
+2    → 8px   (0.5rem)    작은 간격
+3    → 12px  (0.75rem)
+4    → 16px  (1rem)      기본 간격
+5    → 20px  (1.25rem)
+6    → 24px  (1.5rem)    중간 간격
+8    → 32px  (2rem)      큰 간격
+10   → 40px  (2.5rem)
+12   → 48px  (3rem)      섹션 간격
+16   → 64px  (4rem)      페이지 섹션
+20   → 80px  (5rem)
+24   → 96px  (6rem)      대형 섹션
+```
+
+### 간격 사용 가이드
+
+| 용도 | 간격 | Tailwind | 실제 크기 |
+|------|------|----------|----------|
+| 아이콘-텍스트 | xs | `gap-1` | 4px |
+| 인라인 요소 | sm | `gap-2` | 8px |
+| 폼 필드 내부 | md | `p-3` | 12px |
+| 카드 내부 | lg | `p-4` | 16px |
+| 카드 간격 | xl | `gap-6` | 24px |
+| 섹션 내부 | 2xl | `py-8` | 32px |
+| 섹션 간격 | 3xl | `py-12` | 48px |
+| 페이지 섹션 | 4xl | `py-16` | 64px |
+
+## 간격 유형
+
+### 1. Padding (내부 여백)
+
+요소 안쪽의 여백입니다.
+
+```tsx
+// 전체 방향
+<div className="p-4">16px 전체</div>
+
+// 개별 방향
+<div className="pt-4">위 16px</div>
+<div className="pr-4">오른쪽 16px</div>
+<div className="pb-4">아래 16px</div>
+<div className="pl-4">왼쪽 16px</div>
+
+// 축 방향
+<div className="px-4">좌우 16px</div>
+<div className="py-4">상하 16px</div>
+```
+
+### 2. Margin (외부 여백)
+
+요소 바깥쪽의 여백입니다.
+
+```tsx
+// 전체 방향
+<div className="m-4">16px 전체</div>
+
+// 개별 방향
+<div className="mt-4">위 16px</div>
+<div className="mr-4">오른쪽 16px</div>
+<div className="mb-4">아래 16px</div>
+<div className="ml-4">왼쪽 16px</div>
+
+// 자동 마진 (중앙 정렬)
+<div className="mx-auto">좌우 중앙</div>
+```
+
+### 3. Gap (그리드/플렉스 간격)
+
+Flexbox나 Grid 아이템 간의 간격입니다.
+
+```tsx
+// Flexbox에서
+<div className="flex gap-4">
+  <div>아이템 1</div>
+  <div>아이템 2</div>  {/* 16px 간격 */}
+  <div>아이템 3</div>
+</div>
+
+// Grid에서
+<div className="grid grid-cols-3 gap-6">
+  <div>카드 1</div>
+  <div>카드 2</div>  {/* 24px 간격 */}
+  <div>카드 3</div>
+</div>
+
+// 축별 gap
+<div className="flex gap-x-4 gap-y-2">
+  {/* 가로 16px, 세로 8px */}
+</div>
+```
+
+## 실전 레이아웃 패턴
+
+### 1. 카드 컴포넌트
+
+```tsx
+<div className="p-6 rounded-lg border border-gray-200">
+  {/* 제목 - 아래 간격 */}
+  <h3 className="text-lg font-semibold mb-2">카드 제목</h3>
+
+  {/* 본문 - 아래 간격 */}
+  <p className="text-gray-600 mb-4">
+    카드 설명 텍스트입니다.
+  </p>
+
+  {/* 버튼 그룹 */}
+  <div className="flex gap-2">
+    <button className="px-4 py-2">취소</button>
+    <button className="px-4 py-2">확인</button>
+  </div>
+</div>
+```
+
+### 2. 폼 레이아웃
+
+```tsx
+<form className="space-y-6">
+  {/* 필드 그룹 */}
+  <div className="space-y-4">
+    <div>
+      <label className="block text-sm font-medium mb-1">이름</label>
+      <input className="w-full px-3 py-2 border rounded" />
+    </div>
+
+    <div>
+      <label className="block text-sm font-medium mb-1">이메일</label>
+      <input className="w-full px-3 py-2 border rounded" />
+    </div>
+  </div>
+
+  {/* 버튼 영역 */}
+  <div className="flex justify-end gap-3">
+    <button className="px-4 py-2">취소</button>
+    <button className="px-4 py-2 bg-blue-600 text-white">저장</button>
+  </div>
+</form>
+```
+
+### 3. 페이지 섹션
+
+```tsx
+<main className="py-12">
+  {/* 히어로 섹션 */}
+  <section className="py-16 px-4">
+    <div className="max-w-4xl mx-auto text-center">
+      <h1 className="text-4xl font-bold mb-4">히어로 제목</h1>
+      <p className="text-xl text-gray-600 mb-8">서브 타이틀</p>
+      <button>시작하기</button>
+    </div>
+  </section>
+
+  {/* 기능 섹션 */}
+  <section className="py-16 px-4 bg-gray-50">
+    <div className="max-w-6xl mx-auto">
+      <h2 className="text-3xl font-bold text-center mb-12">주요 기능</h2>
+      <div className="grid grid-cols-3 gap-8">
+        {/* 카드들 */}
+      </div>
+    </div>
+  </section>
+</main>
+```
+
+### 4. 네비게이션 바
+
+```tsx
+<nav className="px-4 py-3 border-b">
+  <div className="max-w-6xl mx-auto flex items-center justify-between">
+    {/* 로고 */}
+    <div className="font-bold text-xl">Logo</div>
+
+    {/* 메뉴 */}
+    <div className="flex items-center gap-6">
+      <a href="#">메뉴 1</a>
+      <a href="#">메뉴 2</a>
+      <a href="#">메뉴 3</a>
+    </div>
+
+    {/* 액션 */}
+    <div className="flex items-center gap-3">
+      <button className="px-3 py-1.5">로그인</button>
+      <button className="px-3 py-1.5 bg-blue-600 text-white rounded">
+        시작하기
+      </button>
+    </div>
+  </div>
+</nav>
+```
+
+## 반응형 간격
+
+### 화면 크기별 간격 조정
+
+```tsx
+// 모바일에서 작게, 데스크탑에서 크게
+<section className="py-8 md:py-12 lg:py-16">
+  <div className="px-4 md:px-6 lg:px-8">
+    {/* 콘텐츠 */}
+  </div>
+</section>
+
+// 그리드 간격 조정
+<div className="grid gap-4 md:gap-6 lg:gap-8">
+  {/* 아이템들 */}
+</div>
+```
+
+### 브레이크포인트별 권장 간격
+
+| 요소 | Mobile | Tablet (md) | Desktop (lg) |
+|------|--------|-------------|--------------|
+| 컨테이너 패딩 | 16px | 24px | 32px |
+| 섹션 간격 | 32px | 48px | 64px |
+| 카드 간격 | 16px | 24px | 32px |
+| 그리드 gap | 16px | 24px | 32px |
+
+## 시각적 그룹핑
+
+### 근접성의 법칙
+
+> 가까이 있는 요소는 관련있어 보입니다.
+
+```tsx
+// ✅ 좋은 예 - 관련 요소 그룹핑
+<div>
+  <div className="mb-6">
+    <h3 className="mb-2">제목</h3>        {/* 밀접: 8px */}
+    <p>설명 텍스트</p>                    {/* 같은 그룹 */}
+  </div>
+                                          {/* 분리: 24px */}
+  <div className="mb-6">
+    <h3 className="mb-2">다른 제목</h3>   {/* 새 그룹 */}
+    <p>다른 설명</p>
+  </div>
+</div>
+
+// ❌ 나쁜 예 - 같은 간격으로 그룹 불명확
+<div>
+  <h3 className="mb-4">제목</h3>          {/* 16px */}
+  <p className="mb-4">설명 텍스트</p>      {/* 16px - 구분 안됨 */}
+  <h3 className="mb-4">다른 제목</h3>      {/* 16px - 구분 안됨 */}
+  <p className="mb-4">다른 설명</p>
+</div>
+```
+
+### 간격 비율 권장
+
+```
+같은 그룹 내 요소: 8-12px (gap-2, gap-3)
+그룹과 그룹 사이: 24-32px (gap-6, gap-8)
+섹션과 섹션 사이: 48-64px (py-12, py-16)
+```
+
+## 컨테이너와 최대 너비
+
+### 표준 컨테이너
+
+```tsx
+// 기본 컨테이너
+<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+  {/* 콘텐츠 */}
+</div>
+
+// 좁은 콘텐츠 (블로그, 문서)
+<div className="max-w-3xl mx-auto px-4">
+  {/* 텍스트 콘텐츠 */}
+</div>
+
+// 넓은 콘텐츠 (대시보드)
+<div className="max-w-full px-4 lg:px-8">
+  {/* 전체 너비 콘텐츠 */}
+</div>
+```
+
+### 최대 너비 옵션
+
+```css
+max-w-sm     384px    좁은 카드
+max-w-md     448px    폼
+max-w-lg     512px    모달
+max-w-xl     576px    넓은 모달
+max-w-2xl    672px    중간 콘텐츠
+max-w-3xl    768px    블로그 글
+max-w-4xl    896px    문서
+max-w-5xl    1024px   표준 콘텐츠
+max-w-6xl    1152px   넓은 콘텐츠
+max-w-7xl    1280px   대시보드
+```
+
+## 체크리스트
+
+### 반드시 지켜야 할 것
+
+- [ ] 일관된 간격 단위 사용 (8px 배수)
+- [ ] 관련 요소는 가깝게, 다른 그룹은 멀리
+- [ ] 반응형 간격 적용
+- [ ] 충분한 터치 영역 (최소 44px)
+
+### 권장 사항
+
+- [ ] `space-y-*`, `gap-*` 유틸리티 활용
+- [ ] 섹션마다 일관된 패딩 적용
+- [ ] 최대 너비로 가독성 확보
+- [ ] 여백으로 시각적 계층 표현