피그마 파일 구성

이 문서는 figma-workflow.md 가 아닙니다. 그 이름은 cc-blueprint 의 작업규칙 정본 cc-blueprint/rules/figma-workflow.md 가 쓰고, 이 문서는 그 규칙 위에서 CoUI 제품 파일을 어떻게 구성하는지만 정합니다.

이 문서는 CoUI 로 그리는 서비스 피그마 파일의 페이지 순서 · 섹션과 프레임 이름 · 캡션과 배치 · 공통 화면 처리 · 새 화면을 만드는 순서 · 다크 확인 · 디자인 판단 방법 · Overview 페이지 점검표를 정합니다. 이름 계약(섹션 이름 == @UseCase(name:), 프레임 플랫폼-상태, 페이지 번호)과 검사 등급은 cc-blueprint 의 것을 그대로 따르고, 저작과 검사는 /cc-blueprint:design · cc-blueprint:design-self-check 가 합니다. 여기 적힌 것은 그 계약 위에 하우스 파일이 더 지키는 순서와 습관입니다. 색 값은 하나도 정하지 않습니다. 어느 CoUI 토큰을 어디에 쓰는지는 token-usage.md 를 봅니다.

페이지 이름은 작업규칙의 형식 {3자리 번호} {domain}-{한글 라벨} 을 지킵니다. 순서는 아래대로 손으로 둡니다. 번호는 피그마 페이지와 Widgetbook 트리를 같은 순서로 맞추는 정렬 수단입니다(cc-flutter:figma-widgetbook-alignment). 000 overview-개요 와 900 components 는 화면을 등재하지 않아 맞출 Widgetbook 트리가 없으므로, 900 components 를 세 번째에 두어도 등재 페이지(010 · 100 · 200 …)의 번호 순서는 그대로입니다. 그 스킬의 L2 위생 검사(페이지 번호 정렬)가 이 배치를 표시하면 서비스 DDR 에 「페이지 순서 = Cover → Overview → Components → Common → 역할(coui-product-style)」을 적어 사유로 씁니다.

• 역할 페이지 예: 교육 100 teacher-강사 · 200 student-수강생 · 300 owner-원장, 병원 100 reception-접수 · 200 doctor-원장, 커머스 100 seller-판매자 · 200 ops-운영, 사내 도구 100 member-멤버 · 200 admin-관리자. 하이픈 뒤 한글은 바꿔도 되고(R4), 영문 슬러그와 번호는 레지스트리 figma_page 와 맞춰 둡니다.
• 검사 대상에서 빠지는 이름은 Cover · _flow · _explore · _archive 넷뿐입니다. _overview · _draft 같은 이름은 예외 목록에 없어 1번 검사(구조 · 네이밍)에 걸립니다. 쓰지 않습니다.
• 900 components 에 두는 것은 「이 제품이 아닌 다른 제품에서도 필요한가?」 판정을 거친 것만입니다. 그렇다면 promote/ 로 두고 CoUI 승격 백로그에 올립니다(cc-blueprint/rules/coui-library-consumption.md). 한 화면에서만 쓰는 요소는 컴포넌트로 만들지 않고 그 프레임 안에 둡니다.
• 브랜드/제품 로컬 변수와 스타일을 만들 수 있습니다. Overview도 같은 제품 테마를 참조하고 원본 라이브러리와의 연결을 기록합니다.

섹션 하나가 화면 하나입니다. 이름은 「<역할 접두> · <코드> <제목>」 이고, 개발이 이 문자열을 @UseCase(name:) 에 공백까지 그대로 복사합니다.

• 코드는 지어내지 않습니다. 코드 쪽 문서(요구사항 ID · 화면 목록)에 있는 코드를 쓰고, 없으면 레지스트리에서 먼저 정합니다. 코드 체계 자체는 서비스마다 다릅니다.
• 작업규칙(R1 · §2)과 cc-flutter:figma-widgetbook-alignment §3 · §4 는 섹션 이름을 순수 한글로 두고 역할을 이름에 넣지 않도록 정합니다. 이 스킬은 역할 접두와 코드를 섹션 이름에 두므로 그 규칙과 다르고, 이 점은 이 스킬이 이깁니다. 계약의 핵심인 「섹션 이름 == @UseCase(name:) 문자 동일」은 그대로입니다. 역할 접두 덕에 강사 · T-01 홈 과 수강생 · S-01 홈 이 겹치지 않아 금지 4종의 「이름 중복」도 지켜집니다.
• cc-blueprint:design-self-check 1번은 섹션 이름을 작업규칙 §2 형식(번호 없음 · 순수 한글)으로 읽으므로 이 형식을 차이로 표시할 수 있습니다. 서비스 DDR 에 「섹션 이름 = <역할 접두> · <코드> <제목>(coui-product-style)」을 한 번 적고, 표시가 나오면 그 DDR 을 사유로 남깁니다.
• 금지 4종(버전 접미사 · 상태 주석 · 담당자와 날짜 · 이름 중복)은 그대로입니다. 상태는 레지스트리 status 칸에 적습니다.
• 섹션 이름을 바꾸면 코드도 바꿉니다. 리네임은 개발에 알리고 한 번에 합니다(R1).
• 레지스트리의 roles 칸도 채웁니다. 이름에 역할이 있어도 기계 대조는 레지스트리로 합니다(cc-flutter:figma-widgetbook-alignment).
• 섹션 하나를 만들면 Copy link to selection 으로 figma_node 를 한 번 적습니다(R3). 그 뒤에는 섹션을 옮기거나 이름을 바꿔도 연결이 살아 있습니다.

섹션 안 프레임은 {플랫폼}-{상태} 입니다. 플랫폼과 상태는 계층이 아니라 축이라 섹션 이름에 넣지 않습니다.

• 예: Web-Default · Web-Empty · Web-Error · Mobile-Default · Web-NoPermission.
• 다크와 언어는 상태가 아닙니다. CoUI 변수 모드가 처리합니다(7절). 태블릿은 그리지 않습니다. 사이드바가 접히는 모습은 제품의 Widgetbook 뷰포트로 확인합니다.
• 메뉴에서 숨긴 기능이라도 주소나 공유 링크로 들어올 수 있는 화면에는 Web-NoPermission 을 둡니다. 숨김은 메뉴의 일이고, 권한 없음 화면은 따로 있어야 합니다.

캡션은 화면 위에 두는 글자 두 줄입니다.

• 캡션은 섹션 안, 프레임 위에 두는 TEXT 레이어 하나입니다. 프레임으로 감싸지 않습니다. 감싸면 플랫폼-상태 어휘 검사에 걸립니다. 섹션 안에 두는 이유는 섹션을 옮겨도 함께 가게 하려는 것입니다.
• 공통 원본 인스턴스를 담은 페이지 바로 아래 FRAME(5절)은 섹션이 없으므로, 캡션 TEXT 를 그 FRAME 바로 위 페이지에 두고 둘을 함께 옮깁니다. 한 줄 5장 배치에서는 이 FRAME 도 화면 하나로 셉니다.
• 캡션의 띄어 쓴 「 · 」는 허용됩니다. 슬롭 지문 §S10 은 화면 프레임 안 글자만 세고, 프레임 밖 글자와 레이어 · 섹션 이름은 세지 않습니다. 화면 안 글자에서는 copy.md 의 나열 규칙을 따릅니다.
• 배치는 한 줄에 화면(섹션) 5개입니다. 섹션 폭이 달라도 섹션 사이 가로 간격과 줄 사이 세로 간격은 파일 안에서 한 값으로 정하고, 그 값을 Overview 「읽는 법」에 적습니다. 캔버스 안 위치 · 정렬 · 간격은 검사 대상이 아니라서(R4) 어떤 값이어도 계약은 깨지지 않습니다.
• 줄은 흐름 묶음입니다. 예: 「1 시작 · 계정」 「2 접수 · 예약」 「3 결제 · 정산」 「9 설정」. 묶음 번호는 모든 역할 페이지에서 같게 두고, 그 역할에 없는 묶음은 줄을 뺍니다. 같은 번호 줄끼리 보면 역할별 차이가 보입니다. 줄 머리는 캔버스 위 글자 하나(Title/Medium)로 둡니다.
• 역할 페이지 맨 위에 「이 페이지는」 글자 한 줄을 둡니다. 어느 역할의 화면이고, 공통 화면은 어디 원본의 인스턴스인지 적습니다.

• 판정: 상단 바 · 사이드바까지 포함해 모든 역할에서 픽셀이 같으면 공통, 하나라도 다르면 역할 페이지입니다. 대화상자만 같으면 대화상자만 공통이고 뒤 배경은 각 역할 화면입니다.
• 원본은 010 common-공통 에 섹션으로 둡니다. 상태 프레임(Web-Default · Web-Error …)은 FRAME 그대로 두고, 그 안에 화면 전체를 담은 컴포넌트 하나를 둡니다. 섹션 바로 아래 노드를 COMPONENT 로 바꾸면 연결 레시피가 그 화면을 찾지 못합니다(아래). 이것은 제품 파일 안의 공유 화면 컴포넌트이고 CoUI 재제작이 아닙니다. 안쪽은 전부 CoUI 인스턴스입니다.
• 역할 페이지에는 그 컴포넌트의 인스턴스를 페이지 바로 아래 FRAME 하나에 담아 흐름 자리에 둡니다. 피그마 프로토타입 이동은 같은 페이지 안에서만 되고, 연결 레시피(/cc-blueprint:design Step 3.5 의 prototype-links.figma.js)는 페이지 바로 아래 FRAME 과 섹션 바로 아래 FRAME 만 출발 · 도착으로 찾기 때문입니다. 페이지에 바로 놓은 INSTANCE 는 찾지 못합니다. 감싼 FRAME 이름은 페이지 안에서 유일하게 짓고(예: ↗ C-01 로그인 · Web-Default), 「↗ C-01 · 로그인」 캡션을 답니다. 섹션으로 감싸지 않습니다. 같은 섹션 이름이 두 번 생기면 이름 중복(L0)입니다.
• 레지스트리에는 원본 하나만 올립니다. 역할 페이지의 인스턴스는 등재하지 않고, 등재하지 않은 것은 검사하지 않습니다(R4).
• 같은 흐름인데 셸(사이드바 · 상단 바 역할 칩)만 다른 화면은 공통이 아닙니다. 역할 페이지에 섹션으로 두고 캡션 2줄에 「수강생의 S-04 와 같은 흐름 · 강사 사이드바」처럼 원본을 가리킵니다. 화면 지도에서는 「= 코드」로 표시합니다(9절).
• 셸 템플릿(사이드바 + 상단 바 + 본문 틀)은 900 components 의 템플릿 프레임입니다. 역할마다 메뉴만 줄어든 변형을 두고, 화면은 그 복제로 시작합니다. 복제본의 구조와 바인딩이 같은지는 self-check 10번이 봅니다.

1. 비슷한 화면 복제 — 같은 역할 페이지에서 구성이 가장 가까운 섹션을 복제합니다. 섹션 이름을 새 이름으로 바로 바꾸고(이름 중복 L0 방지), 레지스트리에 행을 더하고 figma_node 를 적습니다.
2. CoUI 인스턴스로 내용 교체 — 글자는 TEXT property 로, 슬롯은 INSTANCE_SWAP 으로 바꿉니다. 새 부품이 필요하면 먼저 CoUI 라이브러리에서 찾습니다. 없으면 1절의 판정 질문을 거쳐 900 components 에 둡니다. detach 하지 않습니다.
3. 상태 확인 — Default 는 필수입니다. Loading · Empty · Error 를 두고, 없는 상태는 사유(스펙 문장)를 레지스트리 note 에 적습니다. patterns.md 6절의 11가지 중 나머지 일곱(진행 · 한도 · 잠김 · 업그레이드 · 권한 없음 · 오프라인 · 확인 대화상자)에서 이 화면에 해당하는 것을 고릅니다.
4. 들어오는 · 나가는 연결 — 이 화면으로 오는 이동 요소와 이 화면에서 나가는 이동 요소를 모두 잇습니다. 다른 페이지로 가는 이동은 불가하니 미연결 목록에 사유를 남깁니다. 공통 화면으로 가는 이동은 같은 페이지의 인스턴스를 담은 FRAME(5절)에 잇습니다.
5. 스크린샷 확인 — 복제한 화면은 꼭 스크린샷으로 봅니다. 노드 값만 보면 아래가 남습니다.

6. 검사 — cc-blueprint:design-self-check 를 돌립니다. 10번(화면 간 일관성)이 복제본의 구조 · 바인딩 · 부품 기본 문구 잔존을 잡고, 11번이 슬롭 지문을 잡습니다. 그 다음 7절 다크 확인을 합니다.

라이트가 기본입니다. 모든 저작과 cc-blueprint 의 검사 · 크리틱은 Light 해석값으로 합니다. 다크 확인은 이 스킬이 더하는 저작자 점검이고, 다크를 상태 프레임으로 만들지 않습니다. 개발 쪽 완료 판정(/cc-pixel-loop:verify)도 상태 프레임마다 라이트 · 다크를 함께 대조합니다 — 다크는 프레임의 복제본을 Dark 모드로 바꿔 찍으므로, 색이 변수에 묶이지 않은 프레임은 다크를 그릴 수 없어 그 대조가 판정 불가로 디자이너에게 돌아옵니다.

절차: 확인할 화면 프레임(Web-Default 등)을 직접 고릅니다 → 그 프레임의 변수 모드에서 이 파일이 고른 색 컬렉션(Semantic/ Color · <브랜드>, 기본 CoUI)을 Dark 로 바꿉니다 → 스크린샷을 찍어 아래 표를 봅니다 → 같은 프레임을 Light 로 되돌립니다. 브랜드 바인딩(cc-blueprint/rules/figma-brand-selection.md §6)이 화면 프레임마다 Light 를 명시로 고정하므로, 섹션이나 페이지의 모드를 바꿔서는 화면이 바뀌지 않습니다. 공유 컴포넌트(표 행 · 표)에는 모드를 고정하지 않으므로 인스턴스가 프레임의 모드를 그대로 따릅니다. 되돌리지 않으면 그 Light 고정이 깨져 cc-blueprint:design-self-check 3번(색 컬렉션 · 모드)에서 걸립니다.

• 이 면 층은 CoUI 부품 기본값 그대로입니다(token-usage.md 2절). 화면 프레임의 채움은 Scaffold 의 color/surface 에 묶고, 제품이 다른 바탕을 고른 경우에만 그 변수에 묶습니다 — 그때 코드는 앱 테마에서 같은 값을 씁니다.
• 다크에서 채도나 밝기를 손으로 고치지 않습니다. 토큰 모드가 처리하고, 어긋나면 토큰 자리를 고칩니다.

규칙에 없는 판단이 필요하면 세 관점을 차례로 적고 결정합니다.

• 확정과 기록은 cc-designer:design-decision 으로 합니다. 세 관점 중 (3) CoUI 일관성(있는 부품 · variant · 토큰 · 누적 DDR)은 그 근거 사다리의 R2 이고, (1) 다른 디자인 시스템 · (2) 실제 쓰임은 R3 · R4 에서 씁니다. R2 를 건너뛰지 않습니다. 신뢰도는 끝난 단계가 정하고(R1 · R2 종결 high, R3 · R4 medium, R5 low), design-decision 은 에스컬레이션 4종 밖에서는 묻지 않습니다. 이 스킬이 먼저 묻는 것은 아래 도메인 컴포넌트 구조 변경 하나뿐입니다.
• 도메인 컴포넌트의 구조(속성 · 축 · 변형 이름)를 바꾸는 판단은 근거를 적고 먼저 묻습니다. 무인 실행이면 바꾸지 않고 DDR 에 제안만 남깁니다.
• 레퍼런스는 참고일 뿐 근거가 아닙니다. 「다른 시스템이 그렇게 한다」 하나로는 결정하지 않습니다.

000 overview-개요 에는 아래 7종을 세로로 쌓습니다. 문서 7종은 섹션이 아니라 프레임으로 둡니다. 섹션으로 두면 cc-flutter:figma-widgetbook-alignment 의 L0(디자인에 있으나 레지스트리에 없는 섹션)에 걸립니다. 문서마다 「제목 + 한 줄 설명」 머리를 둡니다. 결정이 먼저, 화면은 뒤입니다.

• 권한표에서 ○ 보기만 을 범례에만 두고 표에서 한 번도 쓰지 않았다면, 그 역할에 정말 보기만 하는 기능이 없는지 확인합니다.
• 화면 지도 표는 머리 행과 합계 행까지 잘리지 않게 그립니다. 표가 넓으면 역할별로 나눕니다.
• Overview 도 CoUI 텍스트 스타일과 color/* 변수로 그립니다. 화면의 반복값은 브랜드 변수·스타일에 연결합니다. 로컬 변수도 허용합니다.

• 이름 계약 · 검사 등급 · CoUI 3금지의 정본: cc-blueprint/rules/figma-workflow.md, 검사기 cc-blueprint:design-self-check, 저작 절차 /cc-blueprint:design.
• 화면 레지스트리 칼럼(figma_page · figma_node · roles · label_ko · status): cc-flutter:figma-widgetbook-alignment.
• 부품이 없을 때의 판정과 승격 제안: cc-blueprint/rules/coui-library-consumption.md.
• 어느 토큰을 어디에: token-usage.md. 화면 구성과 여백: layout.md. 상태 점검 목록: patterns.md. 화면 안 문구: copy.md.