--- description: 화면설계서 - 라우터, 화면 목록, UI 컴포넌트 정의 --- ## User Input ```text $ARGUMENTS ``` User input can be empty (전체) or specific feature/screen name. ## Overview **논리적 사고 5단계 워크플로우**: ``` 1. /appkit.new → 아이디어 스케치 (어떤 서비스인지?) 2. /appkit.mvp → MVP 범위 정하기 + 랜딩페이지 3. /appkit.ui → 화면설계서 (라우터, 화면, 컴포넌트) ← YOU ARE HERE 4. /appkit.policy → 정책설계서 (비즈니스 규칙) 5. /appkit.visualize → 목업 생성 (HTML 프로토타입) ``` **출력 디렉토리**: `docs/` ## Purpose 라우터 구조, 탭 네비게이션, 화면 목록, UI 컴포넌트를 체계적으로 정의합니다. 개발자가 바로 구현할 수 있는 수준의 상세 화면 명세를 작성합니다. --- ## Pre-requisite - `/appkit.new`로 서비스 컨셉이 정의되어 있어야 함 - `concept.md` 파일이 존재해야 함 --- ## Usage ```bash /appkit.ui # 전체 UI 설계 (router.md + main.md) /appkit.ui router # 라우터 구조만 /appkit.ui main # 메인 구조만 /appkit.ui "채팅" # 특정 화면 상세 ``` --- ## Execution Flow ### 1. 기존 기획 읽기 Read files from `docs/`: - `concept.md` - 서비스 컨셉 - `mvp-scope.md` - MVP 범위 ### 2. 플랫폼 확인 **먼저 사용자에게 플랫폼을 질문:** "어떤 플랫폼으로 개발하시나요?" 옵션: - 웹 (Web Application) - 모바일 앱 (iOS/Android) - 반응형 웹앱 (Progressive Web App) - 크로스 플랫폼 (Web + Mobile) ### 3. UI 설계 대화 **Step 1: 플랫폼별 전체 구조 제시** #### 웹 (Web Application) ```markdown ## UI 설계 초안 ### 플랫폼 - **유형**: 웹 애플리케이션 - **네비게이션**: 상단 헤더 + 사이드바 (또는 상단 탭) ### 라우터 구조 ``` / # 홈/대시보드 ├── /[section1] # 섹션1 │ └── /:id # 상세 ├── /[section2] # 섹션2 │ └── /:id # 상세 └── /settings # 설정 ``` ### 레이아웃 구조 **데스크톱 (1024px+)** ``` ┌─────────────────────────────────────────────────┐ │ [Header: 로고, 네비게이션, 사용자 메뉴] │ ├──────┬──────────────────────────────────────────┤ │ │ │ │ 사이드│ 메인 컨텐츠 영역 │ │ 바 │ │ │ │ │ └──────┴──────────────────────────────────────────┘ ``` **태블릿/모바일 (< 1024px)** ``` ┌─────────────────────────────────────┐ │ [Header: 햄버거, 로고, 메뉴] │ ├─────────────────────────────────────┤ │ │ │ 메인 컨텐츠 영역 │ │ (전체 너비) │ │ │ └─────────────────────────────────────┘ ``` ### 네비게이션 메뉴 | # | 메뉴 | 아이콘 | 경로 | 뱃지 | |---|-----|------|-----|------| | 1 | [메뉴1] | [아이콘] | `/[경로]` | [조건] | | 2 | [메뉴2] | [아이콘] | `/[경로]` | [조건] | --- 이 구조가 맞나요? 수정할 부분이 있나요? ``` #### 모바일 앱 (iOS/Android) ```markdown ## UI 설계 초안 ### 플랫폼 - **유형**: 네이티브/하이브리드 모바일 앱 - **네비게이션**: 하단 탭바 (Bottom Tab Navigation) ### 라우터 구조 ``` / # 기본 탭 ├── /[tab1] # 탭1 │ └── /:id # 상세 ├── /[tab2] # 탭2 │ └── /:id # 상세 └── /settings # 설정 ``` ### 탭바 구조 | # | 탭 | 아이콘 | 경로 | 뱃지 | |---|-----|------|-----|------| | 1 | [탭1] | [아이콘] | `/[경로]` | [조건] | | 2 | [탭2] | [아이콘] | `/[경로]` | [조건] | ### 화면 레이아웃 ``` ┌─────────────────────────────────────┐ │ [상단 헤더] │ ├─────────────────────────────────────┤ │ │ │ 메인 컨텐츠 영역 │ │ │ ├─────────────────────────────────────┤ │ [하단 탭바] │ └─────────────────────────────────────┘ ``` --- 이 구조가 맞나요? 수정할 부분이 있나요? ``` **Step 2: 사용자 피드백** - "좋아", "Yes" → 상세 문서 생성 - 수정 요청 → 업데이트 후 재제시 ### 4. 생성할 문서들 **출력 디렉토리**: `docs/ui/` **파일 구조**: ``` docs/ui/ ├── router.md # 라우터 구조 정의 ├── main.md # 메인 구조 개요 ├── [screen1].md # 화면1 상세 문서 ├── [screen2].md # 화면2 상세 문서 └── ... # 각 화면별 상세 문서 ``` #### 4-1. router.md (라우터 구조) **File**: `docs/ui/router.md` **템플릿**: `.specify/templates/ui-router.md` 참조 라우터 구조와 화면 목록만 간결하게 정의: - **웹**: 헤더 네비게이션, 사이드바, 반응형 레이아웃 - **모바일**: 탭바, 스택 네비게이션, 모달 ```markdown # [서비스명] - Router & UI 목록 ## 플랫폼 정보 | 항목 | 내용 | |-----|------| | 플랫폼 타입 | [Web / Mobile App / PWA / Cross-platform] | | 네비게이션 패턴 | [Header+Sidebar / Bottom Tab / Top Tab] | | 반응형 지원 | [Yes / No] | --- ## 라우터 구조 ``` / # 기본 경로 ├── /[section1] # 섹션1 │ └── /:id # 상세 ├── /[section2] # 섹션2 │ └── /:id # 상세 └── /settings # 설정 ``` --- ## 네비게이션 구조 ### 웹 (Header + Sidebar) **데스크톱 레이아웃** ``` ┌─────────────────────────────────────────────────┐ │ Logo [메뉴1] [메뉴2] [메뉴3] 👤 Profile │ ├──────┬──────────────────────────────────────────┤ │ │ │ │ 사이드│ 메인 컨텐츠 │ │ 메뉴 │ │ │ │ │ └──────┴──────────────────────────────────────────┘ ``` | # | 메뉴 | 아이콘 | 경로 | 설명 | |---|-----|------|-----|------| | 1 | [메뉴1] | [아이콘] | `/[경로]` | [설명] | | 2 | [메뉴2] | [아이콘] | `/[경로]` | [설명] | ### 모바일 앱 (Bottom Tab) **모바일 레이아웃** ``` ┌─────────────────────────────────────────────────┐ │ [상단 헤더] │ ├─────────────────────────────────────────────────┤ │ │ │ 메인 컨텐츠 │ │ │ ├─────────────────────────────────────────────────┤ │ [아이콘] [아이콘] [아이콘] [아이콘] [아이콘] │ │ 탭1 탭2 탭3 탭4 탭5 │ └─────────────────────────────────────────────────┘ ``` | # | 탭 | 아이콘 | 경로 | 뱃지 | |---|-----|------|-----|------| | 1 | [탭명] | [아이콘] | `/[경로]` | [조건] | | 2 | [탭명] | [아이콘] | `/[경로]` | [조건] | --- ## 화면 목록 ### 탭/메인 화면 | # | 화면명 | 경로 | 파일 | 설명 | |---|-------|-----|------|------| | 1 | [화면1] | `/[경로]` | `[screen1].md` | [설명] | | 2 | [화면2] | `/[경로]` | `[screen2].md` | [설명] | ### 상세 화면 | # | 화면명 | 경로 | 파일 | 진입점 | |---|-------|-----|------|-------| | 1 | [화면1 상세] | `/[경로]/:id` | `[screen1-detail].md` | [진입점] | | 2 | [화면2 상세] | `/[경로]/:id` | `[screen2-detail].md` | [진입점] | --- ## 전역 컴포넌트 ### 상단 헤더 (Global Header) ``` ┌─────────────────────────────────────────────────┐ │ [로고] [상태 표시] ⚙️ │ └─────────────────────────────────────────────────┘ ``` ### 전역 팝업 | ID | 유형 | 트리거 | 설명 | |----|-----|-------|------| | `global-network-error` | Modal | 네트워크 오류 | 재시도/취소 | | `global-session-expired` | Modal | 세션 만료 | 재로그인 | --- ## 네비게이션 플로우 ### 기본 플로우 ``` [앱 실행] │ └─→ [메인 탭] (기본) │ ├─→ [액션] → [상세 화면] │ └─→ [다른 탭으로 이동] ``` --- ## URL 스킴 ### 딥링크 | 경로 | 설명 | |-----|------| | `[scheme]://` | 앱 실행 | | `[scheme]://[path]` | 특정 화면 | --- ## 요약 통계 | 카테고리 | 개수 | |---------|-----| | 탭 화면 | N개 | | 상세 화면 | N개 | | 바텀시트 | N개 | | 팝업/모달 | N개 | | **총 UI 요소** | **N개** | ``` #### 4-2. main.md (메인 구조) **File**: `docs/ui/main.md` **템플릿**: `.specify/templates/ui-main.md` 참조 ```markdown # [서비스명] - 메인 구조 ## 화면 개요 | 항목 | 내용 | |-----|------| | 서비스명 | [서비스명] | | 플랫폼 | [Web / Mobile App / PWA] | | UI 컨셉 | [UI 컨셉 - 예: Notion 스타일 워크스페이스] | | 레퍼런스 | [유사 서비스] | | 메인 액션 | [메인 액션 설명] | --- ## 레이아웃 구조 ### 웹 (Desktop + Mobile) **데스크톱 (1024px+)** ``` ┌─────────────────────────────────────────────────┐ │ Logo [메뉴1] [메뉴2] [메뉴3] 👤 Profile │ ├──────┬──────────────────────────────────────────┤ │ │ │ │ 사이드│ 메인 컨텐츠 영역 │ │ 메뉴 │ │ │ │ │ └──────┴──────────────────────────────────────────┘ ``` **모바일 (< 768px)** ``` ┌─────────────────────────────────────┐ │ ☰ Logo 👤 │ ├─────────────────────────────────────┤ │ 메인 컨텐츠 (전체 너비) │ └─────────────────────────────────────┘ ``` ### 모바일 앱 **기본 레이아웃** ``` ┌─────────────────────────────────────┐ │ [상단 헤더] │ ├─────────────────────────────────────┤ │ 메인 컨텐츠 │ ├─────────────────────────────────────┤ │ [하단 탭바] │ └─────────────────────────────────────┘ ``` ### 레퍼런스 비교 (모바일 앱만 해당) | 위치 | [레퍼런스 앱] | [우리 앱] | 역할 | |-----|--------------|---------|------| | 1 | [탭] | [탭] | [역할] | | 2 | [탭] | [탭] | [역할] | --- ## 상단 헤더 ### 기본 구조 ``` ┌─────────────────────────────────────────────────┐ │ [로고] [상태 표시] ⚙️ │ └─────────────────────────────────────────────────┘ ``` ### 헤더 요소 | 요소 | 위치 | 설명 | 액션 | |-----|-----|------|-----| | 로고 | 좌측 | [설명] | [액션] | | [상태] | 우측 | [설명] | [액션] | | 설정 | 우측 끝 | 설정 아이콘 | 설정 화면 | --- ## 탭별 개요 ### 1탭: [탭명] ``` ┌─────────────────────────────────────┐ │ [화면 레이아웃 ASCII Art] │ │ │ │ │ ├─────────────────────────────────────┤ │ [탭바] │ └─────────────────────────────────────┘ ``` **상세 문서:** [해당 문서 링크] --- ## 네비게이션 구조 ### 탭 내비게이션 (Bottom Tab) ``` [앱 실행] │ ├─ 탭1 │ └─ 상세 (push) │ ├─ 탭2 │ └─ 상세 (push) │ └─ 탭3 ← 기본 시작 탭 ``` --- ## 테마 및 스타일 ### 컬러 테마 | 모드 | 배경 | 텍스트 | 포인트 | |-----|-----|-------|-------| | 기본 | #[색상] | #[색상] | #[색상] | | 다크 | #[색상] | #[색상] | #[색상] | ### 탭바 스타일 ```css .tab-bar { background: #[색상]; height: 56px; } ``` --- ## 데이터 요구사항 ### API 명세 ``` GET /api/[endpoint] ``` ```typescript interface [Response] { [field]: [type]; } ``` --- ## MVP 구현 범위 ### Phase 1 (필수) - [ ] [항목 1] - [ ] [항목 2] ### Phase 2 - [ ] [항목 1] - [ ] [항목 2] ``` #### 4-3. [화면별 상세 문서] (예: friends.md, chat.md 등) **File**: `docs/ui/[screen].md` 각 화면별로 독립적인 상세 문서를 생성합니다. **템플릿**: ```markdown # [서비스명] - [화면명] ## 화면 개요 | 항목 | 내용 | |-----|------| | 경로 | `/[경로]` | | 탭/섹션 | [탭/섹션명] | | 목적 | [화면의 목적] | | 핵심 액션 | [주요 사용자 액션] | | UI 컨셉 | [UI 스타일 및 레퍼런스] | --- ## 레이아웃 구조 ``` ┌─────────────────────────────────────┐ │ [상단 영역] │ ├─────────────────────────────────────┤ │ │ │ [메인 컨텐츠 영역] │ │ │ ├─────────────────────────────────────┤ │ [하단 영역] │ └─────────────────────────────────────┘ ``` --- ## 컴포넌트 구성 ### 헤더 영역 | ID | 유형 | 이름 | 설명 | 액션 | |----|-----|-----|------|-----| | `[screen]-header` | Header | 헤더 | [설명] | [액션] | ### 메인 컨텐츠 | ID | 유형 | 이름 | 설명 | 상태 | |----|-----|-----|------|------| | `[screen]-list` | List | 목록 | [설명] | Empty/Loading/Error | | `[screen]-item` | Card | 아이템 | [설명] | - | ### 인터랙션 요소 | ID | 유형 | 트리거 | 액션 | 결과 | |----|-----|-------|-----|------| | `btn-[action]` | Button | 클릭 | [액션] | [결과] | ### 팝업/모달 | ID | 유형 | 트리거 | 설명 | |----|-----|-------|------| | `popup-[name]` | Modal | [트리거] | [설명] | --- ## 상태별 UI ### Empty State [아이템이 없을 때] ### Loading State [로딩 중일 때] ### Error State [에러 발생 시] --- ## 데이터 요구사항 ### API 엔드포인트 ``` GET /api/[endpoint] POST /api/[endpoint] ``` ### 데이터 모델 ```typescript interface [Model] { [field]: [type]; } ``` --- ## 네비게이션 ### 진입 경로 - [어디서] → [이 화면] ### 이동 경로 - [액션] → [다른 화면] --- ## 정책 연결 | 정책 ID | 정책명 | 적용 위치 | |--------|-------|---------| | [POL-001] | [정책명] | [컴포넌트 ID] | --- ## 구현 노트 ### Phase 1 (필수) - [ ] [기본 기능] ### Phase 2 (선택) - [ ] [추가 기능] ``` --- ### 5. 화면별 상세 문서 생성 프로세스 **사용자 입력에 따라**: 1. **입력 없음 또는 "all"**: - `router.md` 생성 - `main.md` 생성 - 모든 주요 화면별 상세 문서 생성 (예: `friends.md`, `chat.md`, `progress.md` 등) 2. **특정 화면명 입력 (예: "친구", "채팅")**: - 해당 화면의 상세 문서만 생성/업데이트 - 기존 `router.md`의 해당 화면 정보와 일관성 유지 **생성할 화면 문서 예시**: - `friends.md` - 친구 탭 - `chat-list.md` - 채팅 목록 - `chat.md` - 채팅방 상세 - `progress.md` - 진행 탭 - `shop.md` - 쇼핑 탭 - `more.md` - 더보기 탭 - `settings.md` - 설정 화면 --- ### 6. 완료 리포트 ``` ✅ 화면설계서 작성 완료! 📁 생성된 파일: - docs/ui/router.md (라우터 구조) - docs/ui/main.md (메인 구조) - docs/ui/[screen1].md (화면1 상세) - docs/ui/[screen2].md (화면2 상세) - ... (총 N개 화면 문서) 📊 요약: - 플랫폼: [Web / Mobile App] - 화면 문서: N개 - 전체 컴포넌트: N개 📝 다음 단계: **Step 4 - 정책설계서 (/appkit.policy)** /appkit.policy **Step 5 - HTML 목업 + 통합 뷰어 (/appkit.visualize)** /appkit.visualize # 통합 뷰어(index.html) + 모든 화면 목업 자동 생성 📍 현재 위치: Step 3/5 완료 ``` --- ## 화면설계 원칙 ### Do's - ✅ **라우터 명확화**: 모든 화면의 경로와 계층 구조 정의 - ✅ **컴포넌트 ID**: 재사용 가능한 ID 체계 사용 - ✅ **상태 고려**: 각 화면의 Empty, Loading, Error 상태 - ✅ **네비게이션 흐름**: 화면 간 이동 경로 명시 - ✅ **ASCII Art**: 레이아웃을 시각적으로 표현 ### Don'ts - ❌ **경로 누락**: 라우터에 없는 화면 금지 - ❌ **ID 중복**: 컴포넌트 ID 중복 금지 - ❌ **모호한 설명**: "적절히", "필요시" 지양 --- ## Example ### 웹 애플리케이션 ``` $ /appkit.ui 어떤 플랫폼으로 개발하시나요? → 웹 (Web Application) 💻 UI 설계서 작성 (웹) 라우터 구조: / ├── /dashboard ├── /projects │ └── /:id ├── /analytics └── /settings 네비게이션: - Header: 로고, 메뉴, 프로필 - Sidebar: 대시보드, 프로젝트, 분석, 설정 ✅ docs/ui/router.md 생성 완료 ✅ docs/ui/main.md 생성 완료 ``` ### 모바일 앱 ``` $ /appkit.ui 어떤 플랫폼으로 개발하시나요? → 모바일 앱 (iOS/Android) 📱 UI 설계서 작성 (모바일) 라우터 구조: / ├── /friends │ └── /:id ├── /chat │ └── /:id ├── /home (기본) ├── /shop └── /more 탭 구조: 1. 👩 친구 2. 💬 채팅 3. 🏠 홈 (센터) 4. 🛒 쇼핑 5. ••• 더보기 ✅ docs/ui/router.md 생성 완료 ✅ docs/ui/main.md 생성 완료 ```