생성 컴포넌트 업데이트 — 실제 크기 추종까지 확인한다

CoUI 컴포넌트의 슬롯·레이아웃·기본값·빌더를 갱신할 때, 그리고 기존 라이브러리를

CoUI 컴포넌트의 슬롯·레이아웃·기본값·빌더를 갱신할 때, 그리고 기존 라이브러리를 전면 감사할 때 적용하는 검증 절차다. 엔지니어링 규범은 coco-de/coui의 .claude/rules/가 정본이다. 제품 파일을 갱신하는 쪽은 이 절차의 증거를 받아 cc-blueprint:coui-library-update로 이어간다.

1. 무엇이 업데이트됐는지 먼저 구분한다#

다음 상태를 한 개의 '완료'로 합치지 않는다:

단계	확인할 증거
코드 반영	머지 SHA · 빌더/위젯 diff · 로컬/CI 결과
플러그인 빌드	번들 소스 해시 · 소유 워크트리 · 빌드 기준 ref
Generate	대상 파일 · 컴포넌트 키/멤버 · 실행 범위 · 성공/실패/skip 로그
라이브 메인 검증	아래 리사이즈·슬롯·본문 측정표
라이브러리 발행	발행된 버전 또는 발행 확인 기록
제품 적용	업데이트 수락 · 영향 화면 재검증

코드와 라이브가 다르다는 사실만으로 '해시 스킵이 원인'이라고 쓰지 않는다. 오래된 번들, Generate 미실행/부분 실행/중단, 인스턴스 override, 캐시를 위 증거로 구분한다. 버전 문자열이나 컴포넌트 이름이 같아도 레이아웃 결함은 남을 수 있다. 도구·권한·대상 노드가 없으면 그 단계는 미확인이다.

2. 모집단과 검사 깊이를 기록한다#

현행 REGISTRY의 컴포넌트 목록을 원본으로 삼고 라이브 메인 목록과 대조한다. 페이지가 비면 다른 페이지/Section으로 이동한 메인도 조회한다.
이름/키를 기준으로 생성됨·누락·폐기·이동을 구분한다. 조회 실패와 빈 결과는 다르다. 분모를 라이브에서 찾은 항목 수로 줄여 '전수 통과'라고 하지 않는다.
생성 트리는 모든 variant와 숨김 슬롯을 포함한다. 같은 경로의 노드라도 variant별 sizing/constraints/크기가 다르면 첫 표본으로 합치지 않는다.
메인 내부의 INSTANCE는 그 메인의 소비 관계로 기록하고, 내부 결함의 소유자는 해당 INSTANCE의 main component로 귀속한다. 같은 결함을 모든 부모의 새 결함으로 중복 집계하지 않는다. 수정 후에는 영향받는 부모 합성도 재검증한다.
tools/figma-token-sync의 npm run audit:layout(명령이 있는 버전)으로 인벤토리를 얻는다. 없으면 같은 필드의 읽기 전용 순회를 사용한다.

산출: 대상 수 / 생성 트리 검사 수 / 라이브 확인 수 / 실제 리사이즈 수 / 미확인 목록. 대표 variant 검사와 전체 variant 검사는 별도로 적는다. 구조가 다른 variant는 각각 검사하고, 값만 다른 멤버를 대표로 묶었다면 그 기준과 생략한 멤버를 남긴다.

3. Figma에서 변화를 주고 잰다#

Figma 실행 지침(figma-use)을 로드한다. 아래 작업은 임시 노드를 만드는 검사다. 라이브 메인과 제품 화면을 직접 바꾸지 않는다.

숨김 탐색 시 figma.skipInvisibleInstanceChildren의 원래 값을 저장하고 false로 설정한다. 끝나면 원래 값으로 복원한다.
대상 텍스트의 getStyledTextSegments(['fontName'])로 실제 폰트를 모아 loadFontAsync로 로드한 뒤 복제/append한다. 특정 폰트·굵기를 추측하지 않는다.
임시 프레임뿐 아니라 만들어진 인스턴스도 생성 즉시 cleanup 목록에 넣는다. append가 실패하면 인스턴스가 프레임 밖에 남으므로 프레임만 지우면 누출된다. finally에서 자기 임시 노드만 지우고 정리 결과를 확인한다.
인스턴스를 baseline과 비교용으로 만들고 동일 조건에서 다음 변화를 준다.

검사 축	입력 변화	유지돼야 할 것
가로	작은/기준/큰 폭, 부모 Auto Layout의 Fill container	표면·콘텐츠·트랙의 가용 폭 추종
세로	폭 유지 후 높이 변경	전체 viewport/overlay 추종, 본문은 chrome을 뺀 영역
내용	짧은/긴 본문, 여러 줄	콘텐츠 주도 높이·배경·외곽선이 함께 증가
옵션	Show 슬롯 off→on→off, 슬롯 교체	숨긴 슬롯의 실제 sizing, 여백 붕괴, 바뀐 내용의 크기 추종
구조	비기본 variant, 가로/세로·wrap/scroll 등	그 구조의 위젯 레이아웃과 일치
비율/위치	root 폭·높이를 각각 변경	split/값 비율, thumb 자체 크기, 끝단 fade, 중앙/하단 anchor

숨긴 자식은 저장된 FILL이 있어도 intrinsic FIXED처럼 읽히거나 트리에서 빠질 수 있다. 복제본에서 Show property를 켠 후 다시 잰다. property에 바인딩된 visible을 직접 덮지 않는다. 가로·세로를 동시에 늘린 한 번의 결과는 축별 검사를 대신하지 못한다.

4. 프레임의 역할과 전체 연결로 판정한다#

layoutMode !== NONE, FILL, STRETCH라는 문자열만으로 통과시키지 않는다. host → 표면 holder → content → slot → 실제 instance/text의 연결을 끝까지 본다.

관측	확인할 원인
root만 커짐	중간 frame의 FIXED/Hug, 부모가 크기를 줄 수 있는지
holder는 커지고 내부만 고정	instance FILL 누락, 별도 고정 크기 override
STRETCH가 있지만 내용 폭 유지	auto-layout의 Hug 재측정, 내부 row/slot의 고정 폭
긴 본문만 외곽 밖으로 나옴	초기 높이를 resize한 NONE root, 숨김 상태로 잰 표면 높이
막대 비율·손잡이 위치가 달라짐	preview 폭으로 한 번만 계산한 좌표·크기
끝단 장식이 안쪽에 남음	좌표만 있고 MAX/CENTER/STRETCH 등 역할에 맞는 anchor 없음

정상 고정값도 컴포넌트 이름이 아니라 역할·축으로 구분한다. 아이콘·간격·thumb 직경·행 높이는 고정일 수 있지만, 같은 노드의 행 폭이나 thumb 위치는 가변이다. 스크롤 내용은 scroll 축으로 넘쳐야 할 수 있고, 반대 축은 viewport를 따라야 할 수 있다. maxWidth는 상한이지 모든 작은 화면에도 강제할 고정 폭이 아니다. Center는 위치 정렬이지 자식 확장의 증거가 아니다. 위젯의 Expanded/Position.fill/constraints 및 Style의 실제 의미로 판정한다.

NONE 스택을 전부 Auto Layout으로 바꾸지 않는다. 겹침을 유지하면서 constraints를 보강할 자리와 실제 flow로 바꿀 자리를 구분한다. 이름이 같은 instance가 있다는 이유만으로 일반 프레임을 pin holder로 취급해 자동 변환하지 않는다.

5. 원인이 있는 곳을 고치고 같은 검사를 반복한다#

생성 결함은 coco-de/coui/tools/figma-token-sync 빌더에서 고친다. 제품 파일에서 detach·외곽선 재제작·고정 픽셀 보정으로 감추지 않는다. 메인이 정상이고 소비 인스턴스의 Fill/override만 잘못됐다면 그 소비 설정을 수정한다.
새 생성과 기존 메인 identity 재사용 경로를 모두 검증한다. 정체성/슬롯 property 보존과 레이아웃 갱신은 서로 다른 검사다.
회귀 검사는 본 결함을 실제로 주입했을 때 실패하고 수정 후 통과해야 한다. 스윕이 빨개졌다는 이유로 검사 조건을 줄여 0건을 만들지 않는다. 오탐이라면 위젯 근거와 정상 fixture를 함께 남긴다.
selftest의 test double은 Figma 레이아웃 엔진이 아니다. 소스 인벤토리와 0 stale holders는 라이브 리사이즈/긴 본문 통과를 대신하지 못한다.
Generate 뒤 같은 파일/키의 메인으로 다시 측정한다. 코드만 머지했거나 감사 문서만 저장했으면 코드 반영 / 검토 완료 / 라이브 미확인을 구별해 보고한다.

6. 완료 기록#

Command / Expected / Evidence / Pass 형식에 다음 표를 첨부한다:

컴포넌트·variant·노드 경로/키	변화	전→후 host	전→후 내부	기대 규칙	판정
대상 및 실제 키	폭/높이/본문/slot	실측	실측	FILL/Hug/비율/anchor	통과/결함/미확인

수정 대상·의도된 고정·판정 보류·라이브 미확인을 별도로 기록한다. 미확인 항목은 이름과 재개 방법을 남긴다. 라이브러리 발행과 제품 업데이트 수락 후의 해소 판정은 cc-blueprint:coui-library-update가 담당한다.

근거 사례: CoUI 레이아웃 감사. 그 문서의 컴포넌트 목록·치수는 당시 관측값이며 영구 allowlist나 목표값이 아니다.