plan-5-wireframe

name	plan-5-wireframe
description	HTML 와이어프레임 생성 스킬. "와이어프레임 만들어주세요", "wireframe", "HTML 와이어프레임", "화면 프로토타입" 등의 요청 시 트리거. plan-4(UI Layout)의 화면 정의를 기반으로 B&W HTML 와이어프레임을 단일 파일로 생성한다. AI Driven Development 파이프라인의 5단계. 반드시 Step 4(UI Layout)가 완료된 상태에서 사용한다.
argument-hint	[기획 주제]

HTML 와이어프레임 생성 (AI Driven Development Step 5/6)

plan-4(UI Layout) 이후, plan-6(기획서 작성) 이전에 실행하는 단계이다. 킥오프에서 팀원들과 화면 단위로 눈높이를 맞추기 위한 B&W HTML 와이어프레임을 생성한다. 완료 후 "기획서 작성해주세요" 로 plan-6을 안내한다.

전제 조건

Step 4의 로컬 md 파일(.claude/docs/ui-layout-*.md)이 존재해야 한다. 파일이 없으면 "먼저 'UI 레이아웃 설명해주세요'로 Step 4를 완료해 주세요"라고 안내한다.

출력 전략

채널	용도	내용
터미널	진행 안내	생성 진행 상황, 완료 시 파일 경로
로컬 HTML	와이어프레임	단일 자체 완결 HTML 파일 (CSS 인라인)

• 터미널에 HTML 코드를 출력하지 않는다.
• 생성 완료 후 두 가지 작업을 반드시 모두 수행한다 — (1) 기본 브라우저로 HTML 미리보기, (2) OS별 파일 탐색기에서 파일 위치 노출. macOS는 Finder reveal, Windows는 Explorer로 해당 디렉토리(파일 선택 포함)를 연다. 사용자가 Notion에 드래그-드롭으로 업로드할 수 있게 한다.

프로토콜

1단계: 입력 로드

1. .claude/docs/ui-layout-*.md 파일을 읽어 화면 목록, 화면별 구성 요소, 화면 흐름, 상태 정의를 파악한다.
2. .claude/docs/draft-*.md 파일이 있으면 기능 목록과 사용 흐름도 참조한다.
3. 프로젝트 루트에 기존 앱 코드가 있으면 탐색하여 기존 디자인 패턴을 파악한다.

2단계: 옵션 설계

3가지 B&W 와이어프레임 옵션을 설계한다:

옵션	역할	설명
Option 1: Safe	기존 패턴 확장	프로젝트의 기존 UI 패턴을 따르는 안전한 선택
Option 2	탐색적 대안 A	다른 UX 철학으로 접근 (예: Progressive Disclosure, Wizard, Hub-and-Spoke 등)
Option 3	탐색적 대안 B	또 다른 UX 철학으로 접근

각 옵션은 1~3단어의 짧은 이름과 한 문장 설명을 갖는다.

3단계: 단일 HTML 파일 생성

.claude/docs/wireframe-{기획주제}.html 경로에 단일 자체 완결 HTML 파일을 생성한다.

파일 구조 규칙:

• CSS는 <style> 태그로 HTML 내부에 인라인. 외부 파일 참조 없음.
• JS는 <script> 태그로 HTML 내부에 인라인. 외부 파일 참조 없음.
• 외부 CDN, 폰트, 아이콘 라이브러리 사용 금지. 시스템 폰트만 사용: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif
• 파일 하나를 다운로드해서 더블클릭하면 브라우저에서 바로 열리는 구조.

페이지 레이아웃:

┌─────────────────────────────────────────────────┐
│  [기획 주제] — [프로젝트명]     ★ 추천: Option N │
│  ┌──────────┬──────────┬──────────┬──────────┐  │
│  │ 1: Safe  │ 2: Name  │ 3: Name  │ Summary  │  │
│  └──────────┴──────────┴──────────┴──────────┘  │
│                                                  │
│  Option 1: Safe Option                           │
│  한 문장 설명                                     │
│  ┌──────────────────────────────────────────┐    │
│  │  ● ● ●              yourapp.com  ─ □ ✕  │    │
│  │  ┌────────────────────────────────────┐  │    │
│  │  │                                    │  │    │
│  │  │  [화면별 와이어프레임 콘텐츠]         │  │    │
│  │  │                                    │  │    │
│  │  └────────────────────────────────────┘  │    │
│  └──────────────────────────────────────────┘    │
│  ① 주석1  ② 주석2  ③ 주석3                       │
└─────────────────────────────────────────────────┘

색상 팔레트 (B&W 엄격 제한): #000 (텍스트/테두리), #333 (보조), #666 (라벨), #999 (플레이스홀더/비활성), #ccc (구분선), #eee (배경), #fff (기본 배경). 그 외 색상 사용 금지.

브라우저 프레임:

• 모바일 앱 프로젝트: max-width: 390px, 둥근 모서리 프레임
• 웹 프로젝트: max-width: 900px, 표준 브라우저 프레임
• plan-4의 대상 플랫폼 정보를 기반으로 자동 결정. 불명확하면 사용자에게 질문.

각 옵션에 포함할 내용:

• plan-4에서 정의한 모든 화면(S-ID)의 와이어프레임
• 화면 간 전환은 탭이나 내부 링크로 표현
• Default 상태를 기본으로, 주요 상태(loading, error, empty)는 주석으로 기술
• 인터랙티브 요소: 클릭 가능한 탭/아코디언, 입력 가능한 폼, 호버 상태

주석 시스템:

• 와이어프레임 요소에 번호 마커(①②③) 표시
• 하단에 대응하는 UX 설명 (한 줄씩)

Summary 탭:

• 3개 옵션 비교 테이블 (옵션명, 한 줄 설명, 장단점)
• 추천 옵션과 이유 (1~2문장)

4단계: 브라우저 미리보기 + OS별 파일 탐색기 노출 (Notion 업로드용)

HTML 파일 생성 직후 두 단계를 모두 수행한다. 한 단계라도 누락되면 사용자가 Notion 업로드 동선을 잃는다.

필수 사전 검증 — 명령을 실행하기 전에 파일이 실제 디스크에 기록되었는지 확인한다:

WF_PATH="$(pwd)/.claude/docs/wireframe-{기획주제}.html"
test -f "$WF_PATH" || { echo "wireframe HTML이 생성되지 않았습니다: $WF_PATH"; exit 1; }

검증 통과 후 OS를 판별하여 분기한다. uname -s 결과로 분기:

• Darwin → macOS 분기
• Linux → Linux 분기 (참고: 기본 지원 외, 가능한 명령 사용)
• MINGW*/MSYS*/CYGWIN*/Windows_NT → Windows 분기

모든 분기에서 항상 절대 경로($WF_PATH)로 호출한다. 작업 디렉토리에 의존하는 상대 경로(.claude/docs/...)는 호출 컨텍스트에 따라 실패한다.

4-1. macOS

1. 브라우저 미리보기:

   open "$WF_PATH"
   

2. Finder에서 파일 reveal:

   open -R "$WF_PATH"
   

   • -R 플래그는 Finder를 띄우고 해당 파일을 선택된 상태로 표시한다. 폴더만 열리는 동작과 다르다.
   • 후속 검증(선택): osascript -e 'tell application "Finder" to get POSIX path of (selection as alias)' 2>/dev/null — 결과가 $WF_PATH와 일치하지 않으면 reveal 실패로 간주하고 다시 시도한다.

4-2. Windows

Git Bash, MSYS2, WSL on Windows, PowerShell 등 환경별로 경로 변환이 필요하다. POSIX 경로를 Windows 경로로 변환한 뒤 호출한다.

1. Windows 경로 변환:

   if command -v cygpath >/dev/null 2>&1; then
     WF_PATH_WIN="$(cygpath -w "$WF_PATH")"
   else
     WF_PATH_WIN="$WF_PATH"
   fi
   

2. 브라우저 미리보기:

   start "" "$WF_PATH_WIN"
   

   • Git Bash/cmd에서 동작. start 첫 인자(빈 문자열)는 윈도우 타이틀로 소비된다.
   • 대안: explorer "$WF_PATH_WIN" (HTML이 기본 브라우저와 연결돼 있을 때).

3. Explorer에서 해당 디렉토리 열기 (파일 선택):

   explorer /select,"$WF_PATH_WIN"
   

   • /select, 뒤에 공백 없이 경로를 붙인다 (Windows Explorer 인자 규칙). 공백을 넣으면 디렉토리 전체만 열리고 파일이 선택되지 않는다.
   • /select,가 실패할 환경(일부 셸이 쉼표를 잘못 파싱)에서는 파일이 위치한 디렉토리 자체를 열기로 폴백한다: explorer "$(dirname "$WF_PATH_WIN")".
   • PowerShell에서 직접 실행할 때는 Start-Process explorer "/select,"$WF_PATH_WIN"" 형태로 인용 처리한다.

4-3. Linux (참고)

기본 지원 범위는 아니지만 동작 가능한 명령:

xdg-open "$WF_PATH"                       # 브라우저 미리보기
xdg-open "$(dirname "$WF_PATH")"          # 파일 매니저로 폴더 열기 (파일 선택은 매니저별로 다름)

4-4. 공통 오류 처리

• 모든 명령의 종료 코드를 점검한다. 0이 아니면 사용자에게 절대 경로($WF_PATH, Windows의 경우 $WF_PATH_WIN 포함)를 그대로 안내하고 수동으로 탐색기를 열도록 요청한다.
• OS 판별 결과가 위 3종에 모두 해당하지 않으면 절대 경로만 안내하고 자동 열기를 생략한다.

사용자는 노출된 탐색기에서 HTML 파일을 Notion 페이지로 드래그-드롭하여 업로드한다.

5단계: 사용자 리뷰 및 다음 단계

사용자에게 안내:

✅ 와이어프레임 생성 완료 (Step 5/6)

파일: .claude/docs/wireframe-{기획주제}.html 브라우저에서 미리보기를 띄웠고, 파일 탐색기(macOS Finder / Windows Explorer)에 해당 파일을 노출했습니다. 탐색기에서 파일을 Notion 페이지로 드래그-드롭하여 업로드해 주세요. 탐색기가 자동으로 열리지 않았다면 아래 절대 경로로 직접 이동해 주세요:

• macOS/Linux: {$WF_PATH}
• Windows: {$WF_PATH_WIN}

기획서 작성으로 넘어가려면: 👉 "기획서 작성해주세요"

수정 요청이 있으면 HTML 파일을 직접 수정한 뒤 4단계의 OS별 명령(브라우저 미리보기 + 탐색기 reveal/디렉토리 열기)을 다시 실행한다. 브라우저 새로고침과 탐색기 노출을 둘 다 수행해야 사용자가 최신 파일을 다시 Notion에 업로드할 수 있다.

핵심 원칙

• B&W만: 색상은 디자이너 영역. 구조와 레이아웃에 집중.
• 단일 파일: 외부 의존성 없이 HTML 하나로 완결. 다운로드 후 더블클릭으로 확인 가능.
• 실제적 콘텐츠: Lorem ipsum 금지. 실제 서비스에 맞는 한국어 플레이스홀더 사용.
• plan-4 기반: 화면 목록, 구성 요소, 상태를 그대로 반영. 임의로 화면을 추가/제거하지 않음.
• 킥오프용: 디자이너에게 의도를 전달하는 수준. 완성된 디자인이 아님.