Usage#

/cc-blueprint:design [--spec {path|text}] [--frames  " {섹션}/{상태},... " ]
                     [--file {figma_url} | --new-file  " {name} " ] [--surface {surface}]

Rules SoT (이 커맨드는 규칙을 재정의하지 않는다)#

Step 0: Preflight (fail-fast)#

rules/coui-library-consumption.md §3 절차 그대로:

1. figma MCP 인증 확인 — 미인증이면 즉시 중단:  " 인증 후 재실행 "   안내 (/mcp → figma).
   ⛔ 저작은 쓰기 작업이므로 무인 폴백이 없다 (읽기 전용 추출과 다르다).
2. CoUI 라이브러리 접근 — 라이브러리 컴포넌트 검색 1건 히트 확인.
   실패 시: 팀 라이브러리 publish 상태 확인 안내 후 중단.
3. 세대 대조 — 라이브러리 컴포넌트 명명이 저장소 루트 coui.version.json 의
   coui_skills_basis 세대(bare-widget)와 일치하는지 확인. 가능하면 coui figma 플러그인의
   토큰 드리프트 점검(coui#4537)으로 세대 내 skew 도 함께 본다.
   skew 발견: 진행하되 결과 보고에  " 라이브러리 구세대 — coui figma-token-sync 재발행 필요 "   명시,
   흡수 절차는 `skills/coui-library-update` 로 라우팅 (저작을 막지 않는다).

Step 1: Screen Decomposition (LLM-SEMANTIC)#

• --spec 텍스트를 화면(섹션) 목록으로 분해 — 섹션 1개 = 화면 1개 (rules/figma-workflow.md §2).
• 화면마다 상태 축 확정: 기본 4종(Default/Loading/Empty/Error — Default 는 예외 없이 필수) 중 스펙이 명시한 것 + 필요 추론분. 스펙에 없는 상태 처리 방식은 cc-designer:design-decision 으로 확정하고 DDR 기록.
• 산출: 저작 계획 표 — | 섹션 | 상태 프레임 | 사용할 CoUI 컴포넌트 후보 | DDR |

Step 1.5: Cover 생성 (--new-file 전용)#

새 파일에는 화면 저작 전에 표준 표지를 깐다 — Unibook App v2.0 표지(fileKey xcJWHajRef2txj9zmFDlu3 · node 6:157, 2026-08-28 figma-mcp 실측)와 동일한 스타일이다. 스타일 개정 시 그 노드를 재추출해 아래 표를 갱신한다.

5슬롯 템플릿 — 페이지 Cover · 프레임 Cover 1280×720 · 배경 #FFFFFF:

절차 (Step 2 와 같은 스킬 위임 — figma:figma-use 로드 필수):
1. 폰트 로딩 — Pretendard Medium/SemiBold(로고 폴백 시 Bold), Inter Medium.
   figma-use 의 폰트 로딩 규칙을 따르고, 워크스페이스에 Pretendard 가 없으면
   조기 실패 + 폰트 설치 안내 (다른 폰트로 대체하지 않는다 — 표지 통일성이 목적이다).
2. use_figma 로 Cover 페이지에 위 표 그대로 프레임 저작 — 이 표가 곧 시안이다.
   텍스트 값은 입력에서 채운다: 제품 구분 = --new-file 이름에서 추론, 버전 기본 v1.0,
   기간 기본 현재 연월. 회사·트랙 라벨은 원본값 유지가 기본.
3. 썸네일 지정 — use_figma 스크립트에서 figma.setFileThumbnailNodeAsync(coverFrame) 시도.
   실패는 비차단:  " 표지 프레임 우클릭 → Set as thumbnail "   수동 안내를 결과에 남긴다.

표지는 화면이 아니다 — 레지스트리에 등재하지 않고, self-check 대상도 아니다 (Cover 페이지는 매핑 표 밖 — rules/figma-workflow.md §1 의 등재 원칙 그대로).

Step 2: Authoring (figma 스킬 위임)#

Figma Plugin API 사용법은 여기 없다 — 반드시 아래 스킬을 로드해 그 규칙대로 실행한다:

1. Skill(figma:figma-use)             — use_figma 호출 전 필수 (모든 쓰기)
2. Skill(figma:figma-generate-design) — 페이지/뷰 조립 워크플로우 (컴포넌트 발견→임포트→섹션별 조립)
3. (--new-file 시) Skill(figma:figma-create-new-file)

이 커맨드가 위 스킬에 추가로 강제하는 것만 적는다:

• 컴포넌트 소스는 CoUI 라이브러리 인스턴스만 — 프리미티브 드로잉·detach·로컬 스타일 생성 금지 (rules/figma-workflow.md §4 L0). figma-generate-design 의 "디자인 시스템 재사용" 경로를 CoUI 라이브러리로 고정하는 것이다.
• 색·간격·타이포는 라이브러리 variable 바인딩으로만. 화면 고유 값은 DDR 없이 넣지 않는다.
• 상태·크기·종류는 인스턴스 component property(Variant=/Size=/State=/Enabled=) 전환으로.

Step 3: Naming + Registry#

• 프레임 네이밍: rules/figma-workflow.md §2 표 그대로 ({플랫폼}-{상태}, 예 Web-Empty — 같은 섹션 안 왼쪽 Mobile · 오른쪽 Web).
• 레지스트리 등재: 3단 대응(Project/Page/Section ↔ [Surface]/Feature/UseCase)으로 화면 레지스트리에 행 추가 — 계약·위치는 cc-flutter:figma-widgetbook-alignment 가 SoT. 코드 쪽 use_case 가 아직 없으면 코드 칸을 —(미구현: /cc-blueprint:build 대상) 으로 남긴다.
• 보고: 섹션별 프레임 node URL 목록 (이후 /cc-blueprint:build 의 입력이 된다).

Step 4: Self-check (필수 마지막 단계)#

skills/design-self-check 를 저작 결과 전체에 적용한다:

• L0 발견 → 그 자리에서 재작업 (보고로 미루지 않는다). 재작업 2회 후에도 L0 이 남으면 해당 섹션만 실패로 보고하고 나머지는 산출한다.
• L1/L2 는 판정표와 함께 보고에 싣는다.
• DDR 목록(결정문·근거 사다리 등급·신뢰도)을 보고 마지막에 첨부한다.

Output#

## 🎨 저작 결과 — {파일명}
| 섹션 | 프레임 | node URL | self-check |
|------|--------|----------|------------|
| 도서 목록 | 4 (Default/Loading/Empty/Error) | figma.com/...?node-id=... | L0 0 · L1 1 |
### 디자인 결정 (DDR n건) · 라이브러리 세대: {일치|skew}
### 다음 단계: /cc-blueprint:build --frames {...}

Error Handling#

Related#

• rules/figma-workflow.md · rules/coui-library-consumption.md — 이 커맨드의 규칙 SoT
• figma:figma-use · figma:figma-generate-design · figma:figma-create-new-file — 실행 계층 (위임)
• skills/design-self-check — Step 4 판정기
• skills/coui-library-update — 프리플라이트 skew 발견 시 흡수 절차
• /cc-blueprint:build — 저작 결과를 화면 코드로 (다음 단계)
• cc-designer:design-decision — DDR 프로토콜