Files
appkit/.claude/commands/appkit.ui.md
2025-12-15 08:53:23 +09:00

779 lines
21 KiB
Markdown

---
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 생성 완료
```