Figma 라이브러리#

정본 파일 — CoUI — Cocode Design System v1.0 을 엽니다. 값은 coui_core 가 정본이고, 이 파일은 그 투영입니다.

tools/figma-token-sync 플러그인(Generate Components)은 실행하는 순간 열려 있는 Figma 문서를 대상으로 컴포넌트를 만들거나 갱신합니다 (figma.root) — manifest.json 에는 특정 파일에 대한 바인딩이 없습니다. 즉 누가 다른 문서에서 플러그인을 실행하면 거기에 병렬 컴포넌트 세트가 생깁니다 — 정체성 보존은 "항상 같은 문서에서 재실행한다"는 전제 위에 있고, 그 전제가 사실인지 확인하는 곳이 바로 여기입니다.

정본#

값의 단일 출처는 docs_core/content/_data/figma_library.json 한 파일입니다. 정본 문서가 바뀌면 이 파일의 값만 갱신합니다 — 플러그인이나 exporter 코드는 건드리지 않습니다. 이 파일은 packages/coui_core/bin/export_figma_tokens.dart 가 빌드 시점에 읽어 build/tokens.figma.json 의 meta.canonicalLibrary 에 실어 보내고, esbuild --bundle 이 그 JSON을 code.js 에 인라인합니다 (components.json 과 같은 경로 — 플러그인은 런타임에 아무것도 조회하지 않습니다. manifest.json 의 networkAccess: { "allowedDomains": ["none"] } 는 그대로 유지됩니다).

Foundation ↔ 문서#

캔버스의 Foundation 페이지와 소비자 가이드를 같은 축으로 맞춥니다. 노드 id 는 구조 스냅샷 기준이며, 페이지를 새로 만들면 바뀔 수 있습니다 — 그럴 때는 파일에서 페이지 이름으로 찾으세요. 값이 갈리면 coui_core 가 이깁니다.

테마 주입·서페이스 프리셋은 코드 축입니다 — 테마, 서페이스 스타일. 결정 문서의 우선순위는 디자인 소스.

타이포는 스타일로 적용한다#

화면의 텍스트에는 텍스트 스타일(Headline, Title, Body, Label …)을 붙인다. 같은 값을 만드는 변수(font-size/*, letter-spacing/*)를 텍스트 노드에 직접 걸지 않는다 — 변수 직접 바인딩은 색과 간격에만.

이유는 두 가지다.

• 변수는 크기와 자간만 나르고 굵기와 행간은 노드에 남는다. 그래서 같은 역할의 제목이 화면마다 다른 굵기로 그려져도 아무것도 경고하지 않는다. 실제로 화면 제목 150여 개가 시스템 Headline(SemiBold · 140%)과 다른 Bold · 160% 로 그려진 채 발견됐다.
• 스타일 위에 변수를 겹치면 변수가 이긴다. 시스템에서 스타일을 고쳐도 그 노드만 안 따라온다.

점검법 — 텍스트 노드를 골라 오른쪽 패널을 본다.

컴포넌트 페이지(❖ …)는 이 규약의 대상이 아니다 — 플러그인이 생성하며, 스타일을 붙이는 쪽으로 옮기는 일은 별도 과제로 진행 중이다.

스타일 자체는 코드에서 온다 — 손으로 고치지 않는다#

텍스트 스타일 17개(Display/Large … Label/Small, Label/XL·Label/XL2 포함)는 Import Tokens 가 변수와 함께 이름으로 upsert 한다. 크기·자간·굵기·글꼴은 시맨틱 변수(font-size/*·letter-spacing/*·font-weight/<그룹>)에 묶이고, 행간은 export 가 준 % 리터럴로 쓰인다(Figma 는 행간에 묶인 숫자 변수를 단위와 무관하게 px 로 읽어 비율을 변수로 나를 수 없다).

그래서 스타일의 굵기·행간이 틀려 보이면 스타일을 편집하지 말고 코드의 역할(CoreTypography)을 고친 뒤 export → Import 를 다시 돌린다. 스타일에 직접 쓴 값은 다음 Import 가 덮어쓴다. 플러그인의 드리프트 점검이 스타일 절을 따로 보고한다 — 없는 스타일, 풀린 바인딩, export 와 다른 굵기·행간.

구조 스냅샷 — 캔버스가 무엇을 바꿨는지 코드가 알게 하는 법#

플러그인의 구조 → .json 을 누르면 파일 전체(모든 페이지)의 노드 구조와 기하(id · 이름 · 타입 · x/y/w/h)가 파일 하나로 내려온다. 그 파일을 레포의 tools/figma-token-sync/reverse/incoming/ 에 커밋하면, 구조 드리프트 대조가 지난 베이스라인과 비교해 "디자이너가 무엇을 추가·삭제·이동·이름 변경했는지" 를 이슈로 남긴다.

이 버튼이 있는 이유: 자동화가 MCP 로 이 파일을 걷으면 페이지 목록 버그와 호출 예산 때문에 Cover 한 장밖에 못 본다. 플러그인은 파일 안에서 돌아 그 한계가 없다. 색 · 토큰 바인딩 · 타이포는 이 스냅샷에 없다 — 그건 충실도 → .json 이 답한다.

대조는 경고이지 차단이 아니다#

플러그인은 실행 시 현재 문서의 root pluginData에 스탬프가 있는지 봅니다. 없거나 다르면 "이 문서는 기록된 CoUI 라이브러리가 아닙니다 — 계속하면 별도 세트가 생깁니다" 확인을 요구하되, 계속 진행은 항상 허용합니다. 승인자가 명시한 대로 정본은 언제든 바뀔 수 있어야 하고, 차단형 게이트는 정본 교체 시점에 플러그인을 못 쓰게 만들어 오히려 사람이 우회하게 만듭니다.

A-5 (미결) — private org plugin 배포#

figma.fileKey 로 정확한 문서 대조(같은 파일인지 실제로 확인)를 하려면 이 플러그인이 private organization plugin 으로 배포돼야 합니다 (plugin-api.d.ts: fileKey 는 enablePrivatePluginApi 가 있는 private 플러그인에서만 접근 가능 — 현행 개발모드 로드에서는 undefined). 배포 전까지는 root pluginData 스탬프만으로 "처음 보는 문서인가"는 구분되지만 "이게 바로 그 정본 문서인가"까지는 확인할 수 없습니다 — 그 판단은 사람이 이 페이지의 URL 을 보고 합니다.

Organization 이상 플랜 확인이 필요해 별도로 결정되지 않았고, 나머지 작업과는 병렬로 진행 가능해 착수를 막지 않습니다.