# 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는 반복성이 충분히 확인된 영역에만 사용한다.