LogoSkills

CoUI Figma 라이브러리 소비 규약

cc-blueprint 가 Figma 에서 제품 화면을 저작할 때 쓰는 부품의 출처와 사용 방식을 고정한다.

cc-blueprint 가 Figma 에서 제품 화면을 저작할 때 쓰는 부품의 출처와 사용 방식을 고정한다. 라이브러리를 만드는 쪽이 아니라 쓰는 쪽의 규약이다 — 생성 파이프라인의 SoT 는 coco-de/coui 저장소의 tools/figma-token-sync 플러그인이다.

§1. 출처 — 무엇이 정본인가#

항목값
라이브러리 생성기 coco-de/coui tools/figma-token-sync — coui_core 컨트랙트의 투영
데이터 SSOTcomponents.json schema v3 (coui repo 산출물)
페이지 규약 컴포넌트당 1페이지 {Section} / {Component} — 섹션은 docs 사이트 큐레이션 그룹과 1:1 (0.130 기준 10그룹, coui#4277 · 페이지 순서도 큐레이션 순서 coui#4333) + 섹션 헤더 페이지(coui#4547), 마지막 +1 페이지는 Palette. (0.129 이전의 4종 fold Display→Control→Form→Layout 은 폐지)
페이지 구성 프레임 ① 축 완전 조합 variant set · ② Properties 표(전 프로퍼티) · ③ Code Examples(기본 생성자/withStyle/토큰 체인)
축·프로퍼티 4축 Variant= ( Core{Component}Variant ) · Size= · State= ( Core{Component}State 정확 일치만) · Enabled= + 기타 상호배타 enum 축 전수 투영 (schema v3 axes 판독기 coui#4051 — 예: Chip·Banner Emphasis= ) + TEXT·BOOLEAN component property (문구·플래그 — coui#4108, 예: Toast 문구·FormField counterText)
브랜드 축 색·시맨틱 variable 은 브랜드별 Semantic/Color 컬렉션 으로 분리 — 제품 파일의 브랜드 전환은 figma-token-sync 의 리바인딩 커맨드 소관(coui#4290). 소비 측은 컬렉션을 직접 바꾸지 않는다
버전 기준 이 저장소 루트 coui.version.json 의 coui_skills_basis (현재 0.127.15 — bare-widget 세대: 위젯 Co 접두 제거, Core* enum 체계 유지). 명명 세대는 0.127+ 전체에서 유효하나 라이브러리 구조·축은 마이너 단위로도 변한다 — 세대 내 변경의 감지·흡수는 skills/coui-library-update

§2. 사용 규칙#

  1. 라이브러리 인스턴스만 — 제품 파일에는 CoUI 라이브러리 컴포넌트의 instance 를 놓는다. detach·복제 후 수정·프리미티브로 흉내 전부 금지 (figma-workflow §4 L0).
  2. variant 는 property 로 전환 — 상태·크기·종류는 인스턴스의 component property (Variant=/Size=/State=/Enabled=/기타 축)로 바꾸고, 문구·플래그는 TEXT·BOOLEAN property 로 넣는다. 다른 variant 를 새로 그리거나 문구용 텍스트 노드를 덧대지 않는다.
  3. 색·간격·타이포는 라이브러리 variable 바인딩 — 제품 파일 로컬 스타일을 만들지 않는다. 화면 고유 값이 필요하면 먼저 cc-designer:design-decision 으로 확정(DDR)하고, coui 토큰 후보로 coui repo 에 제안한다.
  4. 코드 대응 확인 — 인스턴스로 놓은 컴포넌트가 코드에서 무엇인지는 그 페이지의 Properties 표·Code Examples 프레임이 1차 소스다. Flutter 구현 시 cc-coui:* 스킬 (컴포넌트 1:1)이 API 정본이다.

§3. 프리플라이트 (design 커맨드 Step 0)#

/cc-blueprint:design 은 저작 전에 다음을 확인하고, 실패 시 조기 중단 + 해소 안내한다:

1. figma MCP 인증 — 미인증이면 인증 안내 후 중단 (폴백 없음: 저작은 쓰기 작업이다)
2. 대상 파일에서 CoUI 라이브러리 접근 가능 여부 — 라이브러리 검색으로 컴포넌트 1건 히트 확인
3. 라이브러리 세대 확인 — 컴포넌트 명명이 coui.version.json 의 coui_skills_basis 세대와
   일치하는가 (bare-widget 세대 기준). 가능하면 coui figma 플러그인의 토큰 드리프트 점검
   (코드↔라이브 파일 발산 가시화, coui#4537)으로 세대 내 skew 도 함께 확인한다.
   skew 발견 시: 저작은 계속하되 결과 보고에  " 라이브러리 구세대(재발행 필요: coui
   figma-token-sync 재실행) "   를 명시하고, 흡수 절차는
   [`skills/coui-library-update`](../skills/coui-library-update/SKILL.md) 로 라우팅한다

§4. 라이브러리에 없는 부품이 필요할 때#

디자이너 원본 규칙(figma-workflow §5 R5)의 판정 질문을 따른다 — 차단이 아니라 분류다:

  1. 기존 컴포넌트 조합으로 대체 가능한지 먼저 판정 (cc-coui:coui-composition-and-extension 참조)
  2. 불가하면 판정 질문: 「교재 전자책이 아닌 제품에서도 이게 필요한가?」
    • 그렇다(범용) → promote/{Component} 로 만들어 쓴다 — 부채 표시이며 CoUI 승격 백로그로 보낸다(coui repo 에 승격 제안 이슈 + DDR 첨부). 저작은 계속한다.
    • 아니다(도메인 전용) → {domain}/{Component} (예: unibook/ViewerToolbar) 도메인 컴포넌트로 만들어 900 components 페이지에 둔다. 여러 화면 재사용일 때만 컴포넌트화 — 한 화면 전용 요소는 해당 프레임 안에 그대로 둔다.
  3. 두 경로 모두 CoUI 인스턴스의 detach·재제작으로 흉내 내지 않는다(§2-1). /cc-blueprint:sync 가 promote/ 부채 목록을 추적한다.