mvp-preview

요구사항 문서나 화면설계서를 받아서 순수 HTML/CSS/JS 파일로 화면 프리뷰를 만든다. 프레임워크 없이 브라우저에서 바로 열 수 있고, 링크 하나로 공유 가능하다. 완성도보다 빠른 확인이 목적이다.

지원 입력 형식

입력	처리 방식
`.pdf`	내장 Node.js 스크립트로 텍스트 추출 후 분석
`.txt` / `.md`	직접 읽어서 분석
`screen-design/` 폴더	화면설계서 파일 자동 참조
없음	무엇을 만들지 간단히 물어보고 진행

실행 절차

Step 0 — 모드 감지

워크스페이스 루트에 preview/ 폴더가 이미 존재하는지 확인한다.

preview/ 없음 → 신규 생성 모드: Step 1부터 진행
preview/ 있음 → 업데이트 모드: 아래 업데이트 모드 상세 절차로 건너뜀
- preview/ 하위에 사이트 폴더(예: preview/admin/, preview/user/)가 있으면 멀티 사이트 업데이트 모드

Step 1 — 입력 확인

다음 순서로 입력 소스를 결정한다:

사용자가 파일 경로를 제공했으면 → 해당 파일 사용 (.pdf/.txt/.md만 허용)
워크스페이스 루트에 screen-design/ 폴더가 있으면 → 자동으로 화면설계서 참조
아무것도 없으면 → 한 가지만 묻는다:

"어떤 화면들을 만들어드릴까요? 간단히 설명해주세요." 답변을 받으면 brief.md에 기록하고 진행한다 (템플릿: templates/brief.md)

Step 2 — 텍스트 추출

PDF 입력일 때:

# 의존성 설치 (최초 1회)
cd ~/.claude/skills/mvp-preview/scripts && npm install --silent

# 텍스트 추출 — 반드시 이 경로로 저장
node ~/.claude/skills/html-prototype/scripts/extract_pdf_text.js \
  <입력.pdf> -o <워크스페이스_루트>/preview/extracted/source.txt

TXT/MD 파일, screen-design/ 폴더: Read 도구로 직접 읽는다.

Step 3 — 화면 목록 분석

입력에서 아래 항목을 파악한다:

필요한 화면 목록
화면 간 이동 흐름 (어디서 어디로 가는가)
각 화면의 주요 UI 요소

screen-design/ 참조 시 사이트 판단:

screen-design/ 하위에 사이트 폴더가 있으면 멀티 사이트
각 사이트의 ia-sitemap.md 상단 메타 테이블에서 플랫폼/레이아웃 정보를 읽는다
단일 사이트면 screen-design/ia-sitemap.md의 메타 테이블을 읽는다

문서 직접 입력 시 사이트 판단:

역할이 다르고 화면 구성이 전혀 다름 / 대상 디바이스가 다름 / 독립 배포 필요 → 멀티 사이트
사이트별 플랫폼과 레이아웃을 결정한다

분석 결과를 간략히 정리한 뒤 생성에 진입한다:

단일 사이트:

01. 로그인 화면 → 대시보드로 이동
02. 대시보드 → 목록, 설정으로 이동
03. 목록 화면 → 상세로 이동, 뒤로 가기
04. 상세 화면 → 뒤로 가기

멀티 사이트:

[admin — 웹 데스크톱 / 사이드바]
01. 로그인 → 대시보드
02. 대시보드 → 회원 관리
03. 회원 관리 → 회원 상세

[user — 모바일 웹 / 하단탭]
01. 온보딩 → 홈
02. 홈 → 마이페이지
03. 마이페이지

Step 3.5 — 공통 컴포넌트 생성 (해당 시)

화면 분석 결과, 네비게이션 바 · 사이드바 · 하단 탭 바 등이 3개 이상 화면에 반복되면 HTML 파일 생성 전에 공통 컴포넌트를 먼저 작성한다. 각 공통 요소를 Web Component로 정의하고, 해당 앱의 실제 메뉴 구조를 반영한다.

단일 사이트: preview/components.js
멀티 사이트: 사이트별 preview/[사이트]/components.js (플랫폼/레이아웃이 다르므로 분리)

Step 4 — HTML/CSS/JS 생성

references/build.md의 패턴을 참고해 화면별 HTML 파일을 만든다.

파일명 규칙: index.html (허브) + 01-[영문화면명].html, 02-[영문화면명].html, ...

핵심 원칙:

CSS/JS는 각 HTML 파일에 인라인으로 포함 (외부 파일 분리 안 함)
Form 유효성 검사 없음 — 버튼 클릭 시 바로 다음 화면으로 이동
목업 데이터 하드코딩 — API 연결 없음
해피 패스만 — 에러 처리, 예외 케이스 없음
외부 CDN/라이브러리 없음 — 순수 HTML/CSS/JS만
공통 UI가 3개 이상 화면에 반복되면 Step 3.5에서 미리 만든 components.js의 Web Component 태그를 사용

멀티 사이트 시:

사이트별 폴더로 분리: preview/admin/, preview/user/
각 사이트 폴더에 index.html (사이트 내 화면 허브) + 화면 파일 + components.js
플랫폼에 따라 레이아웃 프리셋 적용 (references/build.md 참고):
- 웹 데스크톱 → max-width: 1200px, 사이드바 레이아웃
- 모바일 웹 → max-width: 480px, 하단탭 레이아웃
- 반응형 → 미디어쿼리 브레이크포인트
최상위 preview/index.html은 사이트 선택 허브 (각 사이트의 index.html로 링크)

Step 5 — 공유 안내

생성 완료 후 아래를 사용자에게 안내한다:

바로 보기:

preview/index.html 파일을 브라우저로 드래그하거나 더블클릭하세요.

멀티 사이트: 사이트별로 개별 공유 가능 — 각 사이트 폴더(preview/admin/, preview/user/)를 독립적으로 배포할 수 있다.

링크로 공유: references/share.md의 상황별 방법 안내. 정적 HTML이므로 Surge.sh 또는 GitHub Pages가 가장 간편하다.

업데이트 모드 상세 절차

워크스페이스에 이미 preview/ 폴더가 있을 때 사용하는 플로우다. 참고 문서가 바뀌었거나 화면을 수정해야 할 때 해당한다.

U-Step 1 — 현황 파악

기존 파일을 읽어 현재 상태를 파악한다:

preview/index.html — 전체 화면 목록 허브 (또는 사이트 선택 허브)
단일 사이트: preview/0N-[화면명].html — 각 화면 파일
멀티 사이트: preview/[사이트]/index.html + preview/[사이트]/0N-[화면명].html

현재 화면 수, 파일명 목록, 화면 간 링크 구조를 파악해둔다.

U-Step 2 — 변경 내용 파악

새 문서가 있는 경우: Step 1~3을 수행한 뒤 기존 현황과 비교
구두 지시만 있는 경우: 사용자 설명에서 직접 변경사항 도출

변경 유형 분류:

[추가] 새 화면
[수정] 기존 화면 UI/흐름 변경
[삭제] 화면 제거

U-Step 3 — 선택적 수정

변경이 있는 파일만 수정한다.

특정 화면 변경 → 해당 .html + index.html (목록/링크 변경 시)
새 화면 추가 → 새 .html 생성 + index.html 업데이트
화면 삭제 → 해당 .html 삭제 + index.html 링크 제거 + 관련 화면의 링크 정리

파일 넘버링은 기존 번호 유지, 새 파일은 마지막 번호 이어서 붙인다.

U-Step 4 — 변경 요약 보고

✅ 업데이트 완료

[수정된 파일]
- 02-list.html: 필터 UI 추가
- index.html: 링크 업데이트

[추가된 파일]
- 05-settings.html: 설정 화면 신규 추가

[변경 없는 파일]
- 01-login.html, 03-detail.html (변경 없음)

참고 파일

references/build.md — HTML/CSS/JS 패턴, 화면 간 이동, form 처리
references/share.md — 정적 파일 공유 방법 (Surge, GitHub Pages 등)
templates/brief.md — 문서 없이 시작할 때 사용하는 맥락 기록 템플릿