appkit/.claude/commands/appkit.ui.md

description

description
화면설계서 - 라우터, 화면 목록, UI 컴포넌트 정의

User Input

$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

/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. UI 설계 대화

Step 1: 전체 구조 제시

## UI 설계 초안

### 라우터 구조

/ # 기본 탭 ├── /[tab1] # 탭1 │ └── /:id # 상세 ├── /[tab2] # 탭2 │ └── /:id # 상세 └── /settings # 설정

### 탭 구조

| # | 탭 | 아이콘 | 경로 | 뱃지 |
|---|-----|------|-----|------|
| 1 | [탭1] | [아이콘] | `/[경로]` | [조건] |
| 2 | [탭2] | [아이콘] | `/[경로]` | [조건] |

---

이 구조가 맞나요? 수정할 부분이 있나요?

Step 2: 사용자 피드백

• "좋아", "Yes" → 상세 문서 생성
• 수정 요청 → 업데이트 후 재제시

3. 생성할 문서들

3-1. router.md (라우터 & UI 목록)

File: docs/router.md

템플릿: .specify/templates/ui-router.md 참조

# [서비스명] - Router & UI 목록

## 라우터 구조

/ # 기본 = [메인탭] ├── /[tab1] # 탭1 (목록) │ └── /:id # 상세 ├── /[tab2] # 탭2 (목록) │ └── /:id # 상세 ├── /[tab3] # 탭3 (메인 액션) ├── /[tab4] # 탭4 └── /settings # 설정

---

## 탭 구조

### 하단 탭바 (Bottom Tab)

| # | 탭 | 아이콘 | 경로 | 뱃지 |
|---|-----|------|-----|------|
| 1 | [탭명] | [아이콘] | `/[경로]` | [조건] |
| 2 | [탭명] | [아이콘] | `/[경로]` | [조건] |

### 탭바 레이아웃

┌─────────────────────────────────────────────────┐ │ │ │ [아이콘] [아이콘] [아이콘] [아이콘] [아이콘] │ │ 탭1 탭2 탭3 탭4 탭5 │ └─────────────────────────────────────────────────┘

---

## 화면 목록

### 1. [탭명] 탭

| 항목 | 내용 |
|-----|------|
| 경로 | `/[경로]` |
| 탭바 | [탭] (활성) |
| 역할 | [역할 설명] |

#### 컴포넌트

| ID | 유형 | 이름 | 설명 |
|----|-----|-----|------|
| `[id]-header` | Header | 상단 헤더 | [설명] |
| `[id]-list` | List | 목록 | [설명] |
| `[id]-item` | Card | 아이템 | [설명] |

#### 팝업/모달

| ID | 유형 | 트리거 | 설명 |
|----|-----|-------|------|
| `popup-[name]` | Modal | [트리거] | [설명] |

---

### 2. [화면명] 상세

| 항목 | 내용 |
|-----|------|
| 경로 | `/[경로]/:id` |
| 진입 | [어디서] (Push) |

#### 컴포넌트

| ID | 유형 | 이름 | 설명 |
|----|-----|-----|------|
| `detail-header` | Header | 헤더 | [설명] |
| `detail-content` | Display | 컨텐츠 | [설명] |

---

## 전역 컴포넌트

### 상단 헤더 (Global Header)

┌─────────────────────────────────────────────────┐ │ [로고] [상태 표시] ⚙️ │ └─────────────────────────────────────────────────┘

### 전역 팝업

| ID | 유형 | 트리거 | 설명 |
|----|-----|-------|------|
| `global-network-error` | Modal | 네트워크 오류 | 재시도/취소 |
| `global-session-expired` | Modal | 세션 만료 | 재로그인 |

---

## 네비게이션 플로우

### 기본 플로우

[앱 실행] │ └─→ [메인 탭] (기본) │ ├─→ [액션] → [상세 화면] │ └─→ [다른 탭으로 이동]

---

## URL 스킴

### 딥링크

| 경로 | 설명 |
|-----|------|
| `[scheme]://` | 앱 실행 |
| `[scheme]://[path]` | 특정 화면 |

---

## 요약 통계

| 카테고리 | 개수 |
|---------|-----|
| 탭 화면 | N개 |
| 상세 화면 | N개 |
| 바텀시트 | N개 |
| 팝업/모달 | N개 |
| **총 UI 요소** | **N개** |

3-2. main.md (메인 구조)

File: /Users/taesupyoon/sideProjects/rovel.ai/docs/appkit/ui/works/main.md

템플릿: .specify/templates/ui-main.md 참조

# [서비스명] - 메인 구조

## 화면 개요

| 항목 | 내용 |
|-----|------|
| 서비스명 | [서비스명] |
| UI 컨셉 | [UI 컨셉] |
| 탭 수 | N개 |
| 메인 액션 | [메인 액션 설명] |

---

## 탭 구조

### 탭 비교 (레퍼런스)

| 위치 | [레퍼런스 앱] | [우리 앱] | 역할 |
|-----|--------------|---------|------|
| 1 | [탭] | [탭] | [역할] |
| 2 | [탭] | [탭] | [역할] |

### 탭바 레이아웃

┌─────────────────────────────────────────────────┐ │ [각 탭 아이콘과 라벨] │ └─────────────────────────────────────────────────┘

---

## 상단 헤더

### 기본 구조

┌─────────────────────────────────────────────────┐ │ [로고] [상태 표시] ⚙️ │ └─────────────────────────────────────────────────┘

### 헤더 요소

| 요소 | 위치 | 설명 | 액션 |
|-----|-----|------|-----|
| 로고 | 좌측 | [설명] | [액션] |
| [상태] | 우측 | [설명] | [액션] |
| 설정 | 우측 끝 | 설정 아이콘 | 설정 화면 |

---

## 탭별 개요

### 1탭: [탭명]

┌─────────────────────────────────────┐ │ [화면 레이아웃 ASCII Art] │ │ │ │ │ ├─────────────────────────────────────┤ │ [탭바] │ └─────────────────────────────────────┘

**상세 문서:** [해당 문서 링크]

---

## 네비게이션 구조

### 탭 내비게이션 (Bottom Tab)

[앱 실행] │ ├─ 탭1 │ └─ 상세 (push) │ ├─ 탭2 │ └─ 상세 (push) │ └─ 탭3 ← 기본 시작 탭

---

## 테마 및 스타일

### 컬러 테마

| 모드 | 배경 | 텍스트 | 포인트 |
|-----|-----|-------|-------|
| 기본 | #[색상] | #[색상] | #[색상] |
| 다크 | #[색상] | #[색상] | #[색상] |

### 탭바 스타일

```css
.tab-bar {
  background: #[색상];
  height: 56px;
}

---

데이터 요구사항

API 명세

GET /api/[endpoint]

interface [Response] {
  [field]: [type];
}

---

MVP 구현 범위

Phase 1 (필수)

• [항목 1]
• [항목 2]

Phase 2

• [항목 1]
• [항목 2]

---

### 4. 완료 리포트

✅ 화면설계서 작성 완료!

📁 생성된 파일:

• ui/works/router.md
• ui/works/main.md

📊 요약:

• 탭 화면: N개
• 상세 화면: N개
• 컴포넌트: N개

📝 다음 단계:

Step 4 - 정책설계서 (/appkit.policy) /appkit.policy

Step 5 - HTML 목업 (/appkit.visualize) /appkit.visualize home /appkit.visualize all

📍 현재 위치: Step 3/5 완료

---

## 화면설계 원칙

### Do's
- ✅ **라우터 명확화**: 모든 화면의 경로와 계층 구조 정의
- ✅ **컴포넌트 ID**: 재사용 가능한 ID 체계 사용
- ✅ **상태 고려**: 각 화면의 Empty, Loading, Error 상태
- ✅ **네비게이션 흐름**: 화면 간 이동 경로 명시
- ✅ **ASCII Art**: 레이아웃을 시각적으로 표현

### Don'ts
- ❌ **경로 누락**: 라우터에 없는 화면 금지
- ❌ **ID 중복**: 컴포넌트 ID 중복 금지
- ❌ **모호한 설명**: "적절히", "필요시" 지양

---

## Example

$ /appkit.ui

📱 UI 설계서 작성

라우터 구조: / ├── /friends │ └── /:id ├── /chat │ └── /:id ├── /home (기본) ├── /shop └── /more

탭 구조:

1. 👩 친구
2. 💬 채팅
3. 🏠 홈 (센터)
4. 🛒 쇼핑
5. ••• 더보기

✅ router.md 생성 완료 ✅ main.md 생성 완료