화면 흐름 (Screen Flow)
실행 중인 앱의 실제 스크린샷으로 독립 실행형 HTML 화면 흐름을 만듭니다. 다음 세 부분으로 구성됩니다:
- 매핑: 대부분 코드에서 화면과 화면 간 링크를 추출하여
flow.json에 작성합니다. - 캡처: 보유한 에이전트 도구를 사용하여 실행 중인 앱의 각 화면을 캡처합니다. 모든 링크에 대해 해당 링크를 트리거하는 버튼, 탭 또는 행이 스크린샷 상에 위치한 **핫스팟(hotspot)**도 함께 기록합니다. 그러면 뷰어가 각 화살표를 해당 지점에서 시작합니다.
- 빌드:
scripts/build_flow.py스크립트로 페이지를 빌드합니다. 이 스크립트가 레이아웃, 화살표, 이동 및 확대/축소를 처리하고 이미지를 포함합니다. 뷰어 HTML을 직접 작성하지 마십시오. 올바른 맵과 좋은 스크린샷에 노력을 집중하십시오.
아래 경로는 이 스킬의 폴더(이 파일이 있는 폴더)를 기준으로 합니다.
0. 범위 및 출력물
- 범위:
feature(하나의 기능 또는 흐름, 예: "체크아웃" 또는 "자녀 보호") 또는app(모든 화면). 요청에 명시되지 않은 경우 사용자가 언급한 기능을 사용합니다. 기능 이름이 없으면 전체 앱을 사용합니다. - 기능 범위: 기능으로 이어지는 진입 화면(예: 해당 기능을 여는 버튼이 있는 탭 또는 홈 화면)을 포함합니다. 독자가 기능이 시작되는 위치를 알 수 있도록 작은
nav그룹에 배치합니다. 나머지 앱은 캡처하지 마십시오. - 출력 폴더: 사용자가 요청한 폴더를 사용합니다. 그렇지 않으면 프로젝트의
screen-flows/<slug>/를 사용합니다:flow.json,screens/<screen-id>.png,screen-flow.html. 저장소에 쓰기 전에screen-flows/를.gitignore에 추가해야 하는지 확인하십시오. PNG 파일은 클 수 있습니다.
1. 네비게이션 매핑 (스크린샷 전)
코드를 읽어 인벤토리를 구축합니다. 무작정 클릭하지 마십시오. 확인할 위치:
| 스택 | 네비게이션 위치 |
|---|---|
| React Router / TanStack Router | 라우트 설정, createBrowserRouter, <Route>, routes/ 폴더 |
| Next.js / Remix / Nuxt / SvelteKit | 파일 기반 라우트: app/, pages/, routes/, src/routes/ |
| Angular / Vue | *-routing.module.ts, router/index.ts |
| SwiftUI / UIKit | NavigationStack, TabView, .sheet, .fullScreenCover, 코디네이터, 스토리보드/시퀀스 |
| Android | NavHost / composable(...) 라우트, nav_graph.xml, 매니페스트의 Activities, 하단 네비게이션 메뉴 |
| Flutter | GoRouter / routes: / Navigator.push, BottomNavigationBar |
| React Native | createNativeStackNavigator, createBottomTabNavigator, Expo Router app/ 폴더 |
| TV / 10피트 앱 | 포커스 기반 메뉴, 레일, 리모컨의 뒤로 가기 버튼, 딥링크 핸들러 |
그런 다음 화면을 연결하는 트리거를 찾습니다: 버튼, 링크, 탭 바, 메뉴, navigate(...), router.push, .sheet(isPresented:), 로그인 후 리다이렉트, 가드. 각 트리거는 엣지(edge)가 됩니다.
이미지 없이 첫 번째 flow.json을 작성합니다. 전체 형식은 references/flow-schema.md에 있습니다. 간단히 요약하면:
- 그룹
- 기본 네비게이션 셸(탭 바 또는 사이드바 목적지, 홈 화면, 전역 메뉴)에 대해 정확히 하나의
kind: "nav"그룹을 만듭니다. 이 화면들은 캔버스 상단에 한 행으로 함께 배치됩니다. - 기능별로 하나의
kind: "feature"그룹을 만들고 해당 화면을 작업 순서대로 배치합니다(예: 목록 → 상세 → 편집 → 확인). - 온보딩, 로그인 및 회원가입은 자체 기능 그룹에 배치합니다.
- 기본 네비게이션 셸(탭 바 또는 사이드바 목적지, 홈 화면, 전역 메뉴)에 대해 정확히 하나의
- 화면: 구별되는 뷰당 하나입니다. 모달, 시트, 다이얼로그 및 중요한 상태(비어 있음, 오류, 페이월)는 흐름에 중요할 때 화면으로 간주합니다.
state로 표시합니다. 그룹이 시작되는 화면에entry: true를 설정합니다. - 엣지: 사용자 동작을 레이블로 작성합니다(예:
"'체크아웃' 탭"또는"왼쪽으로 스와이프").kind를back(반환 경로),modal,redirect(자동 네비게이션)에 사용합니다. 명백한 뒤로 가기 링크는 중요하지 않으면 생략합니다. 모든 탭을 다른 모든 탭에 연결하지 마십시오. 기본 탭을 다른 탭들에만 연결합니다(5탭 앱의 경우 20개가 아닌 4개의 엣지).
python3 scripts/build_flow.py flow.json --check로 맵을 확인합니다. 약 25개 이상의 화면이 있는 전체 앱의 경우 사용자에게 그룹 및 화면 목록을 보여주고 캡처하기 전에 확인을 요청하십시오.
2. 실제 스크린샷 캡처
각 플랫폼에서 사용할 도구 및 명령어는 references/capture.md를 참조하십시오. 모든 플랫폼에 대한 규칙:
- 먼저 사용 가능한 도구를 사용하십시오. 여기에는 브라우저 또는 미리보기 도구, 기기 또는 시뮬레이터 도구, Playwright/Chrome DevTools MCP 서버가 포함됩니다. 이러한 도구가 없으면
capture.md의 대체 방법을 사용하십시오:scripts/capture_web.mjs(Playwright),xcrun simctl io, 또는adb exec-out screencap. - 직접 앱을 실행하십시오. 프로젝트 자체 실행 지침(README, AGENTS.md/CLAUDE.md,
package.json스크립트, 실행 설정)을 사용하십시오. 테스트 데이터가 포함된 로컬 또는 개발 빌드를 사용하십시오. - 테스트 계정으로 로그인하십시오. 자격 증명이 필요한 경우 사용자에게 물어보십시오. 절대 추측하지 말고, 실제 고객 계정을 사용하지 말며, 비밀을
flow.json에 붙여넣지 마십시오. - 전체 흐름에 대해 하나의 기기와 뷰포트를 사용하십시오. 모바일 웹의 경우 390×844, 2배율을 사용합니다. 데스크톱 웹의 경우 1440×900을 사용합니다. 네이티브 앱의 경우 하나의 시뮬레이터 또는 에뮬레이터 모델을 사용합니다. 모든 곳에서 동일한 테마와 언어를 사용하십시오.
- 가능한 경우 사용자 방식으로 각 화면에 도달하십시오. 이렇게 하면 엣지도 확인할 수 있습니다. 단계가 느리거나 불안정한 경우 딥 링크 또는 URL을 사용하여 화면을 직접 엽니다. 실제 경로가 맵과 다른 경우 맵을 수정하십시오.
- 화면이 안정될 때까지 기다리십시오. 스피너, 스켈레톤 없음, 이미지 로드 완료, 토스트는 요점이 아닌 한 없음. 개발 오버레이 및 디버그 배너를 닫으십시오.
- 파괴적이거나 되돌릴 수 없는 작업(결제, 삭제, 이메일 또는 메시지 발송 등)은 샌드박스 외부에서 절대 수행하지 마십시오. 확인 화면을 캡처하고 거기서 멈추십시오.
- 각 스크린샷을
screens/<screen-id>.png로 저장하고flow.json에image를 설정하십시오. - 소스 화면에 있는 동안 각 링크의 핫스팟을 기록하십시오: 사용자가 탭하는 요소의 경계 상자입니다. 스크린샷과 동일한 좌표계(이미지의 픽셀, 또는 0에서 1 사이의 분수)로 작성합니다. 웹의 경우
scripts/capture_web.mjs가 선택기로부터 이를 자동으로 수행하고hotspots.json에 기록합니다. 네이티브 플랫폼의 경우 UI 트리에서 요소 경계를 가져옵니다(capture.md참조). 스와이프, 자동 리다이렉트 또는 시스템 뒤로 가기 버튼과 같이 보이는 요소가 아닌 링크는 건너뜁니다. - 저장한 후 모든 스크린샷을 확인하십시오(이미지 뷰어 또는 Read 도구 사용). 빈 이미지, 잘린 이미지, 잘못된 화면, 로그인 벽 또는 오류 페이지가 있으면 다시 캡처하십시오.
- 화면에 도달할 수 없는 경우
image없이 맵에 유지하고notes에 이유를 작성하십시오. 뷰어는 해당 화면에 대해 "스크린샷이 캡처되지 않음" 카드를 표시합니다.
3. 빌드 및 확인
python3 scripts/build_flow.py <out>/flow.json # <out>/screen-flow.html 작성
python3 scripts/build_flow.py <out>/flow.json -o docs/flow.html --max-width 900
스크립트는 Python 표준 라이브러리만 필요로 합니다. flow.json 옆에 hotspots.json 파일이 있으면 읽거나, --hotspots로 파일을 전달합니다. 파일 크기를 작게 유지하기 위해 Pillow 또는 macOS sips를 사용할 수 있는 경우 --max-width(기본값 1000px)보다 넓은 스크린샷을 다운스케일합니다.
HTML을 열고 살펴보십시오. 브라우저 도구를 사용하여 스크린샷을 찍거나 사용자에게 엽니다. 그런 다음 flow.json을 통해 레이아웃을 수정하고 다시 빌드하십시오:
| 문제 | 해결책 |
|---|---|
| 그룹 내 화면 순서가 잘못됨 | screens 순서 변경, entry: true 설정, 또는 "column": n으로 화면 고정 |
| 그룹이 순차적이지 않고 느슨한 화면 집합임 | 그룹에 "layout": "grid" 설정 |
| 긴 시퀀스를 한 행에 표시해야 함 | "layout": "row" |
| 기능이 시작 위치에서 멀리 떨어져 있음 | 해당 기능으로 들어가는 엣지를 추가하거나 "parent": "<group-id>" 설정 |
| 화살표가 너무 많음 | 필요하지 않은 뒤로 가기 링크를 제거하거나 기본 탭에서만 탭을 연결 |
| 화살표가 스크린샷의 잘못된 위치에서 시작함 | 해당 엣지의 hotspot 수정 (세부 정보 패널에서 확인) |
PNG 및 PDF 내보내기
사용자가 이미지, PDF를 요청하거나 흐름을 풀 리퀘스트, 티켓, Confluence 또는 슬라이드에 포함해야 하는 경우 헤드리스로 내보냅니다. 페이지의 내보내기 버튼과 동일한 렌더러를 사용합니다:
node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.png # 전체 흐름
node scripts/export.mjs <out>/screen-flow.html <out>/checkout.png --scope checkout # 하나의 그룹
node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.pdf # 개요 + 그룹별 페이지
옵션: --theme light|dark (기본값 light), --no-hotspots, --no-group-pages (PDF). 스크립트는 Playwright가 필요하며 capture_web.mjs와 동일한 방식으로 설정합니다. 전달하기 전에 PNG를 확인하십시오.
4. 보고
사용자에게 screen-flow.html의 경로와 화면 수 및 그룹 수를 알려줍니다. 스크린샷이 없는 화면과 그 이유를 나열합니다. 다음 뷰어 컨트롤을 언급합니다:
- 드래그로 이동, 스크롤 또는 핀치로 확대/축소
- 화면을 클릭하면 크게 보고, 들어오고 나가는 링크 확인
- 화면 또는 그룹(제목으로)을 드래그하여 재배열; 이 변경사항은 해당 브라우저에 저장됨
- 핫스팟 (도구 모음 버튼 또는
H) 각 화살표를 트리거하는 버튼에서 시작합니다. 세부 정보 패널에서 핫스팟을 클릭할 수 있으므로 독자는 프로토타입처럼 흐름을 클릭하여 탐색할 수 있습니다. /검색,F모든 것을 화면에 맞춤- 내보내기 (도구 모음) 모든 항목, 현재 보기 또는 하나의 그룹을 라이트 또는 다크 테마로 PNG 또는 PDF로 다운로드합니다. PDF에는 개요 페이지와 그룹별 페이지가 포함됩니다. 내보내기는 현재 토글(레이블, 그룹 간 링크, 뒤로 가기 링크, 핫스팟)을 따릅니다.
- URL 끝에
#<screen-id>를 추가하면 해당 화면이 열립니다.