KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/foundation-v4.md

KBX Foundation v4

목적

세 Golden Screen을 개별 예제가 아니라 재사용 가능한 제품 기반으로 승격한다. v4는 화면 구현보다 변하지 않아야 할 UX 계약과 자동 품질 게이트에 초점을 둔다.

새 경계

• @kbx/contracts: Screen/Component/Permission/Help/Preference/Status 계약
• @kbx/ui: PrimeVue/AG Grid adapter, template, tokens, registry
• apps/web/src/registry: 제품 Screen 등록
• generated/: CI에서 비교 가능한 Screen/Component Manifest
• .gitea/workflows: Architecture 품질 게이트

Design Token 원칙

KBX의 시각 규칙은 페이지 scoped CSS의 임의 숫자가 아니라 token을 우선한다.

• Desktop 기본 입력 34px
• Grid row 34px
• Grid header 36px
• Command bar 44px
• Page header 48px
• WMS touch target 52px
• 기본 font 14px / Grid 13px

compact, comfortable, touch density를 token으로 전환하고, 화면 구조는 동일하게 유지한다.

AG Grid

v4 Reference는 AG Grid Theming API를 packages/kbx-ui/src/theme/kbxGridTheme.ts에 격리한다. 업무 모듈은 Theme object나 Grid 옵션을 직접 소유하지 않는다.

Registry

Screen Registry의 실질적인 목적은 메뉴 생성이 아니다. 다음 기능의 공통 식별자를 확보하는 것이다.

• Help
• Permission
• Telemetry
• 사용자 제안
• 개인 Grid/Layout 설정
• AI Screen Context
• 테스트 및 운영 재현

중요한 제한

Screen Definition을 DB 기반 Low-code Builder로 확장하지 않는다. 코드 우선 정의를 유지하고, Metadata는 반복성이 충분히 확인된 영역에만 사용한다.