브랜드 테마 → 컴포넌트 스타일 → 대표 화면 → 전체 확장

모든 시각·인터랙션 속성을 제품에 맞게 설계할 수 있다. 현재 라이브러리 preset이나 API에 없다는 이유로 기본값으로 되돌리거나 디자인을 기록만 하는 상태로 제한하지 않는다. 실제 시안에 표현하고, 코드가 직접 지원/adapter 필요/API 확장 필요 중 어디에 해당하는지 기록한다. 기존 API 이름을 추측하거나 “모든 속성 자동 동기화”를 약속하지 않는다.

브랜드 기록에는 theme revision, 원본 라이브러리 revision, 지원 모드, 컬렉션 key와 mode mapping, 변경 속성의 값·타입·단위·의미·적용 범위, Figma 바인딩과 코드 대응을 담는다.

• 전체: 색·타이포·간격·크기·곡률·테두리·효과·재질·모션·아이콘·상태 표현.
• 컴포넌트: 공통 스타일, variant/size/state, 부모의 슬롯, 인스턴스 예외.
• 우선순위: 기본값 < 전체 테마 < 컴포넌트 공통 < variant/size/state < 부모 슬롯 < 인스턴스.
• 미지정은 상속이다. 명시적 0, false, 투명색, 효과 제거와 미지정을 구분한다.
• variant/size/state 조합에서 충돌하면 속성별 결정 규칙을 명시한다. 현재 resolver 순서와 다르면 adapter에서 맞추거나 gap으로 남긴다.
• 부모 슬롯 override는 해당 사용처에 한정한다. Dialog.cancel 변경으로 전역 Button.secondary가 변하면 실패다.

수치 이름의 primitive(space/16)를 다른 값으로 바꿔 의미를 흐리기보다 새 스케일 또는 용도 이름(layout/page-inset, component/dialog/panel-radius)을 둔다. 예시 경로는 새 설계의 표현법이며 현재 CoUI에 존재하는 API 이름이라는 뜻은 아니다.

기본 구조는 CoUI Base → 제품 Brand Theme → 제품 화면이다. 별도 브랜드 파일을 권장하지만 초기 실험은 대상 파일의 분리된 브랜드 컬렉션에서 시작할 수 있다. 로컬 변수/스타일도 유효한 정본이다.

• Extended Collections가 사용 가능한 플랜/API라면 부모를 상속하고 변경분을 override한다. 지원 여부를 실제 연결과 최신 문서에서 확인한다. 확장 컬렉션에 새 변수/모드를 추가할 수 없는 경우 제품 고유 컬렉션을 따로 둔다.
• 확장이 불가능하면 독립 브랜드 컬렉션을 만들고 명시적으로 재바인딩한다. 이를 상속이라고 부르지 않는다.
• 색뿐 아니라 typography/dimension/surface/motion/component도 같은 원칙을 따른다.
• source key → target key, alias 의존성, 적용 모드를 기록한다. 중첩 인스턴스·text/effect style·swap 후 해석값과 신규 인스턴스 삽입을 확인한다. 컬렉션 이름이 같다는 이유로 성공 처리하지 않는다.
• 공통 라이브러리 업데이트 후 변경분 보존과 신규 토큰 반영을 확인한다. 게시 권한과 시안 편집 권한은 구분한다.

브랜드 hue 선택은 시작이다. 색 이외의 타이포 위계, 업무 밀도, 컨트롤 크기, 곡률, 표면 대비, 경계선, 그림자, 주요 행동과 업무 상태의 강조를 함께 설계한다. 특정 미감·색상·그림자 양을 모든 제품에 강제하지 않는다. 원본과 대표 화면의 스크린샷을 비교하고 실제 치수를 읽는다. sm이라는 이름만으로 크기가 같다고 판단하지 않는다. 원본 데이터와 핵심 행동을 보존하며, 같은 카드 반복 대신 업무에 맞는 보드·행·시간축·양식을 선택한다. 대표 화면이 통과하면 전체 목록에 확장한다. 사용자가 전체를 요청했다면 일부만 만든 뒤 완료라고 하지 않는다.

Figma snapshot에서 외부 library alias와 부모 컬렉션·override·mode를 해석한 manifest를 만든다. 원본 관계와 최종값을 함께 보관하며 JSON/Dart/CSS 등 산출물의 revision이 같은지 확인한다. 로컬 변수만 읽는 exporter는 외부 의존성을 누락할 수 있다. composed color, font weight, px/em/%와 shadow/motion 같은 복합값의 지원 범위를 확인한다. 배포에 필요한 토큰의 누락은 export 실패로 처리한다.

현재 CoUI의 CoreColorScheme, CoreTypography, component theme/style 등 실제 통로를 확인해서 매핑한다. 정적 상수, 전역 scaling, preset만으로 모든 세부 속성이 덮어써진다고 가정하지 않는다. 필요한 adapter·제품 스타일·API 확장을 계획하고 앱 구현이 범위에 포함되면 구현한다. 디자인만 요청받은 경우 코드 대응표와 gap을 남기되 앱을 임의 배포하지 않는다.

1. 전역 테마 변경이 override 없는 컴포넌트에 전파된다.
2. 특정 컴포넌트 스타일 변경이 다른 컴포넌트에 번지지 않는다.
3. variant/state와 부모 슬롯·인스턴스 override 우선순위가 의도대로이며, 제거하면 상속값으로 돌아간다.
4. 지원 모드별 disabled/hover/pressed/focus, 실제 패널 크기와 텍스트 줄바꿈이 유지된다.
5. Figma 신규/중첩 인스턴스와 코드 렌더가 같은 revision의 값을 사용한다.

검증하지 않은 항목은 미검증으로 남긴다. 읽기 전용 Figma 연결이면 수정 성공이라고 보고하지 않고, 접근 문제와 준비된 산출물을 구분한다. 접근 허용 후 실행할 변경은 원본을 보존하고 재실행 시 중복되지 않게 준비한다.

변환 전에 원본의 구성/상태 계약을 적는다: 요소 개수와 순서, 실제 폭·높이·간격·곡률, 입력값, 선택·focus 위치, 텍스트 계층, fill/outline 역할, 구분자, 클릭 영역. 같은 컴포넌트 이름을 찾았다는 이유로 원본의 시각·상호작용 계약을 버리지 않는다. 기존 size/variant/props → component style → 부모 슬롯 override → 필요한 API 확장 순으로 해결한다. 원본에 없는 장식을 추가하거나 중요한 상태를 초기값으로 바꾸지 않는다.

실제 사례: Bottari 인증번호 원본(260:2712)은 본문 362px 안에 6칸, 4·8·2 입력과 네 번째 focus를 표현한다. 교체본(260:2741)은 외곽 362px 안의 stack이 401px로 넘치고, 구분자가 추가되며 입력/포커스와 채움 스타일이 달라졌다. 이런 결과는 취향 차이가 아니라 구성·상태·레이아웃 회귀다. 6칸의 합 + gap + border + 구분자 폭을 확인하고 마지막 칸까지 보이는 렌더 증거를 남긴다. 이 수치를 다른 제품의 기본값으로 강제하지 않는다.

시안 원본과 결과를 같은 viewport에서 나란히 확인한다. 의도적으로 바꾼 것은 변경 이유를, 나머지 차이는 수정 결과를 기록한다. overflow·누락·focus/selection 소실은 완료를 막는다. API 제한이면 그 제한과 필요한 확장을 보고하고 미완료로 남긴다. 기계적인 토큰 검사 통과가 실제 화면 비교를 대체하지 않는다.

대표 화면만 확인하고 나머지를 통과 처리하지 않는다. 전체 화면별 원본/결과 node ID, 동일 viewport 스크린샷, 차이, 의도적 변경 여부, 수정 경로와 재검증 결과를 남긴다.

• 안내: Alert의 icon slot·제목/본문 위계·disabled CTA.
• 홈: 작은 버튼/배지의 실제 크기, 선택 Navigation 색상.
• Dialog/Sheet: 바깥 프레임이 아닌 실제 패널 폭, padding, 본문 줄바꿈, 취소 액션의 역할.
• 입력/신고: label gap, 필드 경계, radio와 카드의 선택 상태, 컨트롤 크기.
• Toast: 화면 위 표면 대비와 글자 대비, 위치·수명. 정지 시안에서 수명/동작을 검증했다고 하지 않는다.
• 알림: 긴 본문 전체 표시, unread 배경/점 크기, badge 정렬, 시간의 보조 위계.
• 채팅: 말풍선 형태/채움, avatar, 보조 액션, 타임스탬프와 긴 메시지.
• 인증번호: 전체 칸 표시, 값/포커스 보존, 구분자와 반응형 폭.
• 프로필: 카드 구성의 장점 보존, avatar/배지의 상대 크기, CTA.
• 내역/설정: 보조 행동 강도, selected/disabled/off 차이, 칩·토글 치수.
• 관리자: 행 높이, 열 폭/정렬, 텍스트 위계, badge 가독성, 긴 데이터.

Bottari 실제 알림 변환에서 295×40의 두 줄 본문이 287px 슬롯 안의 498×20 단일 행으로 바뀌어 뒤가 잘렸고, unread 점은 6px에서 20px가 되었다. 본문 손실은 완료 차단 결함이고 점 크기·배경은 원본 의도와 비교할 스타일 계약이다. 기본 컴포넌트가 다르게 보인다는 사실만으로 라이브러리 버그라고 단정하지 말고 사용 설정/스타일 지원/구조 결함을 구분한다.