KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/design-code-parity-v12.md

KBX v12 — Design ↔ Code Parity

목적

KBX의 Design System과 Vue 구현이 시간이 지나면서 서로 다른 이름·상태·Token을 갖는 것을 방지한다.

Source of Truth

Design Token JSON
  ↓
CSS Variables
  ↓
Token Manifest
  ↓
Figma Variable Contract

Component는:

Component Manifest
 + Component Catalog
        ↓
Figma Component Contract

으로 연결한다.

Token 경계

• Primitive: 원시 spacing/color/typography/radius
• Semantic: surface/text/border/action/status/focus
• Component: control/grid/header/label 등 실제 UI 계약

Component CSS는 가능하면 Semantic/Component Token을 소비한다. 새 raw hex/px literal은 기본적으로 기술부채 증가로 간주한다.

Design Debt Ratchet

기존 코드에는 historical hardcoded value가 남아 있다. 이를 v12에서 일괄 변경하면 Visual Regression 위험이 크므로 기존 수치를 baseline으로 고정한다.

현재 부채 <= baseline : PASS
현재 부채 > baseline  : FAIL
새 파일의 hardcode     : baseline 0에서 시작

즉 기존 부채는 리팩토링할 때 감소시키고, 새로운 부채는 늘리지 않는다.

Core Component parity

Design System v1.0의 34개 1차 필수 Component는 모두:

• Public component manifest
• Component Catalog
• Figma component contract

에 존재해야 한다.

금지

• Figma에서만 존재하는 임의 업무 Component
• 코드에서만 존재하는 Core Component 상태
• 화면별 임의 Token 이름
• Semantic 의미 없이 raw color를 상태값으로 사용
• Component 이름 변경 후 SemVer/Migration 미검토