# KBX FE QA Hardening v43
## Semantic Theme · Home Navigation · Visual Hierarchy · FE Reference Parity

### 1. 이번 버전의 결론

v43의 핵심은 색상 변경이 아니다. KBX의 기존 `surface / text / border / primary / success / warning / danger / focus / AI` 의미 토큰을 기반으로 **KBX Business Light / KBX Business Dark** 두 표현 모드를 만들고, 같은 의미 계약을 Application Shell, Home, PrimeVue, AG Grid, 공통 Component, FE Reference Lab까지 공유하도록 정리한 것이다.

첨부 `KBX Business UX/AX Standard v1.0`, `KBX Design System v1.0`, `KBX Reference Screens v1.0`, `KBX Implementation Contract v1.0`은 Light/Dark 모드 자체를 명시적으로 요구하지 않는다. 따라서 Dark Theme는 표준 문서의 직접 요구사항이라고 과장하지 않는다. 이번 Theme는 사용자의 요청에 따라 **기존 Semantic Token, Density, Accessibility, Predictable Layout 계약을 확장한 구현 선택**이다.

Reference Screen의 디자인 리뷰 순서가 업무 단계·입력량·Focus·예외·Grid·상태·복구·감사·AI를 먼저 보고 미관을 마지막에 보도록 정의한 만큼, Theme 역시 업무 판단을 흐리면 실패로 판단했다.

---

## 2. 30년 현장 QA 관점의 냉정한 v42 평가

v42에는 Token이 있고 UI가 정돈되어 있었지만, 이를 완성된 Theme System이라고 부르기에는 부족했다.

### P1 — 세 개의 서로 다른 시각 경계

실제 구현은 사실상 다음 세 영역으로 나뉘어 있었다.

1. KBX CSS semantic tokens
2. PrimeVue Aura 기본 Theme
3. AG Grid Quartz 개별 파라미터
4. 별도의 FE Reference Lab CSS

같은 `primary`, `surface`, `warning`, `focus` 의미가 제품 영역에 따라 미묘하게 달라질 수 있었다. 이 상태에서 Dark Mode를 추가하면 화면마다 다른 Dark가 만들어질 가능성이 높다.

### P1 — Home의 의미 우선순위가 색상으로 충분히 보강되지 않음

Home의 정보 구조 자체는 `확인 필요 → 바로 시작 → 모듈별 업무`로 올바른 방향이었지만, 긴급 예외·미저장·고정 업무·일반 메뉴가 시각적으로 비슷해 스캔 속도가 떨어질 수 있었다.

### P1 — 하드코딩 색상 잔존

Network Indicator, Dialog/Toast Shadow, FE Reference surface 등에 일부 직접 색상이 남아 Theme 전환 시 의미 토큰과 어긋날 여지가 있었다.

### P1 — Dark Mode의 대표적인 함정 재현

첫 Dark 시각 QA에서 실제로 결함이 발견됐다. `.kbx-app[data-theme="dark"]`의 배경 변수는 Dark로 바뀌었지만 상위 `body`에서 이미 계산된 Light text color가 일부 자식에게 상속되어 **배경은 어둡고 글자는 검은 가짜 Dark Mode**가 만들어졌다.

이 문제는 정적 코드 리뷰만으로는 지나치기 쉽다. 실제 렌더링을 통해 발견했고 Theme Root에서 `color/background`를 재계산하도록 수정했다.

---

## 3. v43 구현

### 3.1 KBX Business Theme 계약

Token source version을 `1.9.0`으로 올리고 다음 Theme mode를 명시했다.

- `KBX Business Light`
- `KBX Business Dark`

Theme는 primitive color를 화면마다 다시 정의하지 않는다. Semantic Token override만 가진다.

주요 Dark semantic 예:

- surface / muted / subtle / hover
- text / text-muted
- border / border-strong
- primary
- success / warning / danger
- focus
- info/success/warning/danger surface + border
- changed / AI suggested
- overlay / overlay shadow

Density는 Theme와 독립적으로 유지한다. `compact / comfortable / touch`의 업무 밀도 계약을 Theme가 바꾸지 않는다.

### 3.2 Theme Runtime API

`applyKbxTheme()`, `normalizeKbxThemeMode()`, `nextKbxThemeMode()`를 공통 Theme 경계로 추가했다.

Theme preference는 `light | dark` allow-list만 허용한다. 알 수 없는 값은 `light`로 fail-safe 한다.

중요한 보안 원칙:

> Theme는 presentation preference일 뿐 Permission, Domain State, Business Rule, AI Capability를 결정하지 않는다.

### 3.3 Application Shell

Global Header에 Icon-only가 아닌 명시적 Theme Action을 추가했다.

- `☀ Light`
- `☾ Dark`
- 스크린리더용 `밝은 테마로 변경 / 어두운 테마로 변경`
- 40rem 이하에서 기존 Header action과 함께 4-column으로 재배치

Preference는 기존 사용자 UI preference 저장 경계를 재사용한다.

### 3.4 PrimeVue / AG Grid Theme Bridge

PrimeVue Dark selector를 KBX root의 `[data-kbx-theme="dark"]`와 연결했다.

AG Grid Quartz는 다음 KBX semantic variable을 참조한다.

- foreground → text
- background → surface
- accent → primary
- border → border
- header → surface-subtle
- row hover → surface-hover
- selected row → info-surface

따라서 업무 Page가 PrimeVue/AG Grid Theme API를 각각 직접 조정하지 않아도 된다.

### 3.5 Home Navigation Visual Hierarchy

Home에 새로운 Dashboard Card를 더 넣지 않았다.

대신 현재 구조에서 업무 우선순위만 강화했다.

- `확인 필요`: warning border
- 긴급/치명 예외: danger left marker
- Dirty work: warning semantic surface
- Pinned/Favorite: info semantic surface
- Module header: subtle surface + primary code
- active module filter: info surface

이 설계의 목적은 “예쁘게 보이기”가 아니라 사용자가 Home에 들어온 뒤 **어디부터 처리해야 하는지를 1~2초 안에 스캔**하도록 하는 것이다.

### 3.6 Side Navigation

현재 업무 Screen에는 primary inset marker를 추가했다. Background 전체를 강하게 칠하지 않고 현재 위치를 안정적으로 인식하도록 했다.

### 3.7 Shared Component hard-code 감소

- Network Indicator text/danger → semantic token
- Unsaved Changes Dialog shadow → semantic shadow token
- Toast shadow → semantic shadow token
- Reference HTML fixed white surfaces 제거

Design Debt는 `122 → 116`으로 감소했다.

### 3.8 FE Reference Lab Theme parity

BE 없이 실행되는 실제 HTML/CSS/JavaScript Reference Lab에도 같은 Light/Dark 의미 체계를 적용했다.

Theme toggle은:

- local preference allow-list
- aria-label 갱신
- `documentElement.colorScheme` 갱신
- Light/Dark 즉시 전환
- `?theme=light|dark` 결정적 preview 지원

T01~T09의 업무 상호작용은 Theme에 의해 바뀌지 않는다.

---

## 4. 보안 판단

Theme 기능에서 가장 중요한 보안 원칙은 **표현 상태가 권한 상태로 승격되지 않는 것**이다.

v43에서는 다음을 금지한다.

- Dark/Light preference에 따라 Permission 변경
- Theme 값으로 API route 또는 Domain Action 결정
- 저장된 임의 Theme 문자열을 class/style로 그대로 주입
- 업무 오류/상태를 색만으로 표현

Theme 값은 `light | dark` allow-list 후 dataset과 color-scheme에만 적용한다.

Frontend의 Disabled/Hidden/Theme 표시는 UX일 뿐 보안 경계가 아니다. Permission Enforcement와 상태전이/정합성은 Server가 최종 책임져야 한다.

---

## 5. 브라우저 QA

실제 FE Reference HTML/CSS/JavaScript asset을 Chromium에 inline하여 검증했다. 실행환경 정책상 localhost/file navigation이 차단되므로 production CSP가 제거된 inline harness를 사용했으며, CSP 자체는 별도 정적 Gate에서 검증한다.

Theme Browser QA: **16 / 16 PASS**

검증 항목:

- Light 기본값
- Dark Toggle
- Dark text 실제 computed-color 재계산
- Theme button aria-label
- T01~T08 Dark render
- T09 WMS mobile 전용 render + mode
- 1280px document horizontal overflow 없음
- Light 복귀
- JavaScript runtime/page error 0

시각 증적:

- Home Light 1440×900
- Home Dark 1440×900
- T01 Dark 1440×900

---

## 6. 전체 Governance 결과

최종 `validate:kbx` PASS.

- Design Tokens: 153
- Screen Recipes: 9
- Recipe Verification: 9/9
- Screen Definitions: 20
- Components: 84
- Catalog Entries: 66
- Navigation Entries: 16
- Canonical Scenarios: 30
- Canonical Fields: 51
- API Operations: 66
- TS/Vue Script Units: 305
- Design Debt: 116 <= ratchet 131
- Release Impact: required major / declared major

Theme 전용 자동 Gate도 전체 validator에 포함했다.

---

## 7. 아직 완료라고 부르지 않는 부분

### P1 — 실제 Vite/PrimeVue/AG Grid Live Theme E2E

v42에서 만든 실제 Vite Runtime은 소스 계약상 준비되어 있으나, 현재 실행환경은 package registry 접근이 차단되어 `pnpm install`과 실제 Vite runtime 기동을 수행할 수 없다.

따라서 이번 16/16 브라우저 증적은 **FE Reference Lab의 실제 HTML/CSS/JS 증적**이며, Vue/PrimeVue/AG Grid live-runtime Theme E2E로 대체해서 주장하지 않는다.

### P1 — Full-query XLSX

v42에서 남긴 Server-side 전체 검색조건 XLSX / Hangfire export는 Theme와 별개이며 여전히 후속 과제다.

### P2 — Forced Colors / OS High Contrast

Light/Dark와 별개로 Windows Forced Colors 및 실제 Screen Reader 환경 검증은 추가 현장 QA가 필요하다.

### P2 — 실제 PDA 장비 Dark Theme

T09은 390×844 브라우저 Reference 검증을 통과했지만 Scanner/PDA의 저휘도·창고 조명·장갑 조건에서 Dark Theme가 실제로 우월하다고 단정할 근거는 아직 없다. 현장 사용성 검증 후 WMS 기본 Theme를 결정해야 한다.

---

## 8. 다음 우선순위

1. Network-enabled 환경에서 실제 Vite install/typecheck/build
2. Vue App Light/Dark Playwright Visual Regression
3. OMS-ORD-001 / 002 / ERP-MST-ITEM-001 Theme parity
4. 1280×720 / 1440×900 / 200% Zoom × Light/Dark matrix
5. WMS 390×844 실장비 contrast/scan feedback
6. Forced Colors / keyboard-only / screen-reader QA
7. Server-side full-query XLSX

새로운 T10/T11이나 더 큰 Metadata Theme Engine은 필요하지 않다. 현재는 **하나의 의미 토큰 계약이 기존 T01~T09 전체에서 실제로 유지되는지**를 더 깊게 검증하는 것이 우선이다.
