디자인 소스#

CoUI 코드가 디자인 결정을 대조하는 문서는 이 레포 안에 없다 — coco-de/docs 라는 별도 레포의 design/ 아래에 산다. 이 페이지는 그 문서들 중 무엇이 정본인지, 버전/커밋이 무엇에 고정돼 있는지, 문서끼리 갈릴 때 어느 쪽이 이기는지를 기록한다. 값 자체의 단일 출처는 여전히 coui_core 다 — 이 페이지는 coui_core 와 문서가 갈릴 때 어느 문서를 근거로 삼을지 정할 뿐, coui_core 를 대체하지 않는다.

SSOT 정의#

coui_core 는 값의 SSOT 다. coco-de/docs 의 문서들은 결정 기록 (decision record) 이며 값의 출처가 아니다. 둘이 갈릴 때:

• 코드에 근거 주석/테스트가 있으면 → 문서를 갱신한다.
• 코드에 근거가 없으면 → 코드를 문서에 맞춘다.
• 문서끼리 갈리면 → 어느 쪽도 채택하지 않고 결정을 다시 받는다(아래 우선순위 규칙으로 먼저 판정을 시도하고, 그래도 안 갈리면 별도 결정 이슈로 보낸다).

왜 이 정의가 필요한가: "코드가 문서를 어긴다" 를 결함이라 부르려면 그 문서가 정본이어야 한다. 그런데 대조에 쓰인 문서는 레포 안에 존재하지 않고 (find . -name '*Specification*.md' → 0), 버전 고정도 승인 상태도 커밋 연결도 없었으며, 심지어 자기들끼리 갈리는 곳이 있었다. 충돌하는 것은 SSOT 가 될 수 없다 — 이 페이지가 그 공백을 채운다.

문서 73종의 두 종류#

coco-de/docs/design 아래 마크다운 73개는 파일명 자체가 이미 두 갈래로 나뉜다:

33+1+36+3 = 73. 다수(36/73, 49%)가 결정 기록이라는 사실 자체가, 73종 전부를 "정본화" 하면 안 되는 이유다 — 결정 기록은 명세가 아니고, 못박으면 앞으로 결정을 바꿀 때마다 문서 개정 절차가 걸린다. 명세 34개만 "코드가 참조해야 할 것" 의 후보이고, 그중에서도 아래 우선순위 규칙을 통과한 것만 실제로 근거로 쓰인다.

버전/날짜 헤더 유무가 그 자체로 신호다. 결정 기록 36개 중 31개는 헤더가 아예 없다 — 애초에 버전 추적 대상으로 설계되지 않았다는 뜻이다. 2개는 날짜만 있고 버전은 없다(CoUI_Menu_Item_Shared_Component_Rationale.md, CoUI_Space_Token_Decision_Rationale.md). 나머지 3개만 버전·날짜를 둘 다 갖는다(CoUI_Badge_Tag_Chip_Taxonomy_Decision_Rationale.md v1.0, CoUI_Tag_Chip_Taxonomy_Decision_Rationale.md v2.1, CoUI_Badge_Dot_Size_Token_Decision_Rationale.md v1.0) — 버전을 붙일 이유가 있었던 문서라는 뜻이고, 실제로 앞의 둘이 아래 "충돌 1" 의 당사자다.

우선순위 규칙#

명세와 명세가, 또는 명세와 코드가 갈릴 때 다음 순서로 판정한다. 규칙은 이미 승인된 결정(D1, A-4′)을 일반화한 것이지 새로 발명한 것이 아니다.

1. 문서 종류 — 결정 기록의 서술 중 숫자가 우연히 언급돼도 그건 값 출처가 아니다. 명세만 값을 규정한다.
2. 프리미티브가 컴포넌트를 지배한다 — 컴포넌트 명세가 프리미티브 토큰(색상/spacing/radius/stroke-width/duration 등)을 참조하면서 그 프리미티브의 정의된 스케일 밖 값을 쓰면, 프리미티브 명세가 이긴다. 컴포넌트 문서는 프리미티브의 스케일을 확장할 권한이 없다.
3. 버전 동률 타이브레이커 — 같은 축의 두 명세(또는 결정 기록)가 갈리는데 날짜가 같으면, 버전이 높은 쪽이 이긴다. 날짜도 버전도 같으면 타이브레이커가 없다 — 별도 결정 이슈로 보낸다.
4. 코드 우선(D-9) — 위 1~3 을 통과해 문서 쪽 승자가 정해졌는데도 코드가 그 승자와 다르면, 코드에 근거(CI 가드·핀 테스트·근거 주석)가 있는 한 문서를 갱신한다. 근거가 없으면 코드를 문서에 맞춘다.

확인된 충돌 3건과 판정#

1. Taxonomy — v1.0 ↔ v2.1 (Badge/Tag/Chip 분류)#

이건 새 결정이 아니라 D1(#3768)과 동일한 판정을 기록하는 것이다 — D1 은 이미 이 규칙으로 v2.1 을 채택하고, 실제 컴포넌트 리네임(Chip → Tag 계열 재편)은 범위가 커서 별도 Epic(#3768)으로 보냈다. 이 페이지는 그 판정의 근거를 문서 신원으로 기록할 뿐, 리네임 자체를 수행하지 않는다.

2. Size↔Icon — "Space Primitive 참조" ↔ "Font-size 참조"#

두 문서 모두 superseded 로 기록했었다. 2026-08-05 갱신 — coco-de/coui#3817 로 실제 갱신 완료: Icon Spec §1.2/§2.1/§3.4 와 Size Rationale §2 가 census 근거(16=42곳, 20=19곳, 12=9곳, 14=8곳)와 정확한 참조축(CoreSize, CoreSpace 아님)을 반영해 coco-de/docs 쪽에서 갱신됐다(고정 커밋은 아래 "커밋 고정" 참조). 이제 두 문서와 코드가 일치한다 — 더 이상 "갱신 대상" 상태가 아니다.

3. 프리미티브 ↔ 컴포넌트 — stroke-width 1.5px#

이 판정이 Epic K(#3767)의 stroke-width 축(checkbox·radio·spinner border)을 직접 푼다 — 코드를 프리미티브에 맞추는 별도 작업이 필요 없다는 뜻이다.

커밋 고정#

갱신 이력#

coco-de/docs 가 실질적으로 갱신되면(특히 위 3건 관련 문서) 이 표에 새 행을 추가하고 고정 커밋을 옮긴다. 코드 변경 없이 이 파일 한 곳만 고치면 된다 — 정본 문서가 바뀌어도 대조 로직 자체는 그대로다.

전체 카탈로그 (73종)#

명세(명세)만 "코드가 참조해야 할 것" 후보다. 결정 기록은 참고용으로 함께 싣되, 값 출처로 쓰지 않는다. 경로는 coco-de/docs 기준 상대경로다.

색상

타이포그래피

컴포넌트 분류 (Taxonomy)

디자인 토큰 — 프리미티브

디자인 토큰 — 컴포넌트 치수

이 페이지가 하는 것과 안 하는 것#

한다: 어느 문서가 정본인지 판정하고, 그 판정의 근거(우선순위 규칙)를 기록하고, 판정 시점의 문서 스냅샷을 커밋으로 고정한다.

안 한다: 충돌 3건의 내용(컴포넌트를 실제로 어떻게 리네임할지, 아이콘 사다리를 실제로 어떻게 이식할지)을 결정하지 않는다 — Taxonomy 재편은 별도 Epic, Icon/Size 문서 갱신은 coco-de/docs 쪽 작업이다. 또한 이 페이지가 확립한 규칙 밖에 있는 새로운 문서-대-문서 충돌(예: duration/easing alias tier, CoreContentPadding 존폐, stroke-6 정의 여부처럼 우선순위 규칙을 적용해도 안 갈리는 진짜 판단이 필요한 사례)은 여전히 별도 결정 이슈로 간다 — 그런 사례는 산문(rationale) 두 개가 같은 무게로 반대 방향을 가리킬 때 생기며, 이 페이지의 규칙 1~4로는 기계적으로 안 풀린다.