widgetbook-wiring — 화면을 전시장과 회귀 테스트에 연결#
한마디로#
구현된 화면을 위젯북 전시장에 등재하고, 상태 스위치가 실제로 동작하게 만들고, 상태별 스냅샷 (골든)을 기준 사진으로 남기는 배선 작업입니다. 이 배선이 끝나야 화면은 "코드가 있다"에서 "기획·디자이너가 눌러보고 회귀가 감시되는 화면"이 됩니다.
무엇을·언제#
- 무엇을: use_case 생성 → 상태 Knob 배선 → Figma 결합(designLink) → 골든 스냅샷 생성 → 경계 확인.
- 언제:
/cc-blueprint:buildStep 4 (자동), 또는 기존 화면 소급 등재 시 단독 호출. - 좋은 점: 이 단계를 건너뛴 화면은 실측에서 100개 중 82개가 "Knob 이 장식"이었습니다 — 배선 순서를 고정해 그 사고를 구조적으로 막습니다.
규약 SoT (재정의 금지)#
| 판단 | SoT |
|---|---|
use_case 소유 위치·1 Page = 1 use_case·Knob 규약·this.bloc 주입 |
cc-flutter:widgetbook-conventions |
@UseCase(name:)·designLink·레지스트리 결합 |
cc-flutter:figma-widgetbook-alignment |
| 골든 테스트 작성·승인 절차 | cc-flutter:golden-test-guide |
이 스킬이 고정하는 것은 순서·완료 조건·경계뿐이다.
배선 절차#
1. use_case 생성 — feature 패키지 소유(조립 앱은 sink), 섹션당 1건.
@UseCase(name:) = Figma 섹션 이름과 문자 동일 · path 는 `[Surface]/Feature` 표기.
2. 상태 Knob — Default/Loading/Empty/Error 를 dropdown 단일 Knob 으로. mock 시나리오
(build 의 mock/ 데이터)를 Knob 값에 1:1 바인딩한다.
⛔ 함정 검사: Page 가 BlocSignalProvider(create:) 로 BLoC 을 자체 생성하면 주입 mock 이
가려져 Knob 이 무력화된다 — Page 의 this.bloc 선택 주입 여부를 먼저 확인하고,
아니면 build 산출물 결함으로 되돌린다 (여기서 우회 배선하지 않는다).
3. designLink — use_case 에 Figma 프레임 node URL 을 단다 (섹션 프레임, 파일 루트 아님).
레지스트리 행의 코드 칸을 `—(미구현)` → use_case 참조로 갱신한다.
4. 골든 스냅샷 — 상태 4종 × 대표 뷰포트(Mobile 필수 · Web 은 시안에 Web 프레임이 있는 화면. Tablet 프레임은 시안에 없다(figma-workflow §5 R2) — Widgetbook Viewport 애드온으로만 확인)
골든 테스트 생성 → 1회 승인(update-goldens) → `flutter test` green 확인.
5. 경계 확인 — 아래 표의 이웃 검증 계층으로 넘어갈 일을 여기서 하지 않는다.검증 경계 — 어디까지가 이 배선인가#
| 검증 | 담당 | 이 스킬과의 관계 |
|---|---|---|
| 정적 스냅샷 회귀 (골든) | 이 스킬 (4단계) | 여기까지가 배선 완료 조건 |
| Figma↔Widgetbook 집합 대조 (L0/L1/L2) | /cc-blueprint:sync | 배선 결과를 소비 |
| 런타임 픽셀 수렴 (Figma↔렌더) | cc-pixel-loop | 디바이스 렌더 검증 — 골든과 별개 축 |
| 위젯 트리 단위 자동화 회귀 | cc-marionette | 실행 중 앱 검증 |
| 앱 내부 상태 검증 | cc-mcp-toolkit | BLoC/DB 관측 |
완료 조건#
□ 섹션마다 use_case 1건 · @UseCase(name:) == 섹션명 · designLink == 프레임 node URL
□ 상태 Knob 4종이 화면을 실제로 바꾼다 (Page 자체 BLoC 생성 없음 확인)
□ 골든: 상태 4종 × 대표 뷰포트 스냅샷 존재 + flutter test green
□ 레지스트리 코드 칸 갱신 (—(미구현) 해소)