figma-widgetbook-alignment Reference

SKILL.md 의 참조 자료입니다. 레지스트리 컬럼 스키마와 검증 항목 전체를 담습니다.

화면 하나 = 한 행. 파일은 리포에 두고(CSV 또는 그에 준하는 텍스트 포맷), 디자인 파일에는 목차 페이지로 미러링합니다.

dart_class · usecase_name · platforms · states 를 사람이 적기 시작하면 표가 죽습니다. 클래스 이름 하나만 바뀌어도 표가 거짓말을 시작하고, 거짓말하는 표는 아무도 안 봅니다.

시드 단계에서는 자동 컬럼이 비어 있는 게 정상입니다. 코드 스캔이 채웁니다.

figma_node 는 섹션을 지웠다 다시 만들면 바뀝니다. dart_class 는 리네임되면 바뀝니다. figma_page 는 도메인 재편으로 옮겨집니다. 모든 컬럼이 변할 수 있으므로, 행을 추적할 불변 축이 하나 필요합니다. 그게 key 입니다. 도메인이 바뀌어도 key 는 두고 domain 만 고칩니다.

검증 항목#

결합이 끊긴 것만 여기 둡니다. 이 계층이 붉으면 표를 신뢰할 수 없다는 뜻입니다.

프레임 여러 장과 use_case 하나는 1:1 이 아니므로 집합 포함 관계를 봅니다. 두 집합의 원소는 같은 어휘(SKILL §2-1)라, 어느 상태가 빠졌는지까지 이름으로 짚어 낼 수 있습니다.

차단으로 올리지 마세요. 도입 초기에 이 검사는 거의 모든 화면에서 걸립니다. 차단하면 팀이 검사를 끕니다. 경고로 두면 같은 정보가 부채 리포트로 남습니다.

L1 이 성립하려면 프레임 이름이 기계로 읽혀야 합니다.

{플랫폼}-{상태}

• 구분자는 하이픈. 첫 하이픈에서만 자른다 — 상태 이름에 하이픈이 들어가도 안전하다(cc-blueprint rules/figma-workflow.md §5 R2 와 같은 규칙)
• ·(공백 + 가운뎃점 + 공백)으로 적은 옛 프레임은 같은 이름으로 읽되 경고로 리포트한다 — 고칠 대상이다
• 플랫폼 어휘: Mobile · Web — 태블릿 프레임은 그리지 않는다(cc-blueprint rules/figma-workflow.md §5 R2). 옛 파일의 Tablet-… 프레임은 어휘 밖으로 리포트한다
• 상태 어휘: SKILL §2-1 의 표 — 공통 어휘(Default · Loading · Empty · Error · Long · Typing · Collapsed · NoPermission)와 그 제품이 DDR 에 남긴 제품 전용 어휘
• 어휘 밖의 값은 경고로 리포트하고 집합에서 제외 — 조용히 버리면 오탐이 된다

Section: 도서 목록
  Frame: Web-Default        → platforms{Web},    states{Default}
  Frame: Web-Empty          → platforms{Web},    states{Empty}
  Frame: Mobile-Default     → platforms{Mobile}, states{Default}

파싱 결과: platforms = {Web, Mobile}, states = {Default, Empty}. 코드 쪽 states = {Default, Loading, Empty, Error} 이므로 Loading·Error 가 "디자인 미지정" 으로 리포트됩니다.

좌측(자동) 컬럼 생성기는 @UseCase 어노테이션에서 다음을 뽑습니다.

states 는 Knob 이 고르는 시나리오 enum 에서 읽습니다. 상태 Knob 은 context.knobs.object.dropdown<{화면}Scenario>(options: {화면}Scenario.values, …) 한 줄이고, 스캐너는 그 타입의 enum 선언에서 값마다 첫 인자 문자열을 읽습니다 — 그 문자열이 프레임의 상태 이름입니다. 본문의 문자열 목록이 아니라 선언된 enum 을 읽으므로 파싱이 흔들리지 않습니다.

enum BookListScenario {
  data('Default', '데이터'),   // → states 에 Default
  loading('Loading', '로딩'),
  empty('Empty', '빈'),
  error('Error', '에러');
  // …
}

한국어 문자열 목록으로 Knob 을 만든 옛 use_case(['로딩', '데이터', '빈', '에러'])는 SKILL §2-1 표의 라벨로 상태 이름을 읽되 경고로 리포트합니다 — 라벨은 대조의 키가 아니므로 고칠 대상입니다.

화면 하나를 끝까지 따라갑니다. 기계가 쓰는 키는 셋뿐입니다 — 섹션 node ID = figma_node, 섹션 이름 = name:, 상태 이름 = enum 의 frameState.

① 레지스트리 행 — 사람 칸은 화면당 1회, 자동 칸은 스캔이 채웁니다(나머지 칸 생략).

② 섹션의 프레임 — node 1234:5678, 섹션 이름 도서 목록.

Section: 도서 목록
  Frame: Web-Default
  Frame: Web-Empty
  Frame: Web-Error
  Frame: Tablet-Default     ← 옛 파일에 남은 태블릿 프레임

③ use_case — 섹션 이름 · 클래스 · 상태가 행의 자동 칸이 됩니다.

@UseCase(
  name: '도서 목록',              // → usecase_name. figma_section 과 공백까지 같다 (L0)
  type: BookListPage,            // → dart_class
  path: '[Console]/Book',
  designLink: 'https://www.figma.com/design/<key>/...?node-id=1234-5679',   // Web-Default 프레임
)
Widget buildWidgetbookBookListPageUseCase(BuildContext context) {
  final scenario = context.knobs.object.dropdown<BookListScenario>(
    label: '상태',
    options: BookListScenario.values,   // → states = Default;Loading;Empty;Error
    initialOption: BookListScenario.data,
    labelBuilder: (s) => s.label,
  );
  return BookListPage(bloc: scenario.bloc());
}

④ Figma 대조 캡처 — 같은 enum 의 같은 bloc() 으로 그립니다(cc-pixel-loop:visual-verify §3).

for (final s in BookListScenario.values) {
  figmaFrames.scenario(s.captureScenario, build: (_) => BookListPage(bloc: s.bloc()));
}

⑤ 짝 — 프레임의 상태 이름이 enum 값과 캡처 폴더를 정합니다.

파싱 결과는 platforms = {Web} · states = {Default, Empty, Error} 이고 코드 쪽 platforms 와 states 가 둘 다 포함합니다. 경고는 둘입니다 — Loading 의 "디자인 미지정", 그리고 어휘 밖 프레임 Tablet-Default.

짝이 맞지 않으면 어디서 드러나는지:

• 섹션 이름 ≠ name: → L0 (결합이 끊겼다)
• 시안에만 있는 상태(예: Web-Long 인데 enum 에 Long 이 없음) → L1 "구현 누락". 대조에서도 long/ 캡처가 없어 figma_compare.py ingest 가 그 비교를 판정 불가로 남긴다
• enum 에만 있는 상태 → L1 "디자인 미지정" — 그 상태는 대조할 프레임이 없다

도입 시 흔한 실패#