# V13-FE-001 — KBX v36 디자인 하네스 제안

## 작업 식별

| 항목 | 값 |
| --- | --- |
| WBS | V13-FE-001 |
| Slice | Cross-cutting / UIFoundation |
| Requirement / API / DB / Job / UI / Test | REQ-FE-ADAPTER / Cross / Cross / Cross / UI-FOUND-01 / T-FE-ARCH-01 |
| Gate / 의존성 | G0 / AEG-X-003 (COMPLETED, tracker 확인) |
| 단일 목적 | UI 공급자 경계를 유지한 채 KBX v36의 디자인 운영 원칙을 K-ArtSell 검증 계약으로 번역 |
| Artifact / 수용 기준 | architecture rule / feature의 PrimeVue·AG Grid 직접 import 0 |

## Source / Assumption / Unknown / Decision Required

### Source

- `docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/design-token-policy-v4.md`: primitive → semantic → component 토큰, 밀도는 배치·form·keyboard 계약을 바꾸지 않음.
- `docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/kbx-v36-standard-traceability.md`: template → recipe → canonical scenario → Vitest/Playwright 증거의 연결.
- `docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/screen-recipe-verification-home-attention-v36.md`: `testProfile`은 UX/복구/보안 검증 범위이며, client business truth가 아님.
- `frontend/src/shared/ui/adapter/`, `tools/validate_v16.py`: 현재 UI provider/adapter 경계와 정적 vendor-import 검사.
- `frontend/src/shared/ui/screen-types/catalogue.ts`, `contracts/ui/screen-types.v2.json`: T01~T10 화면 유형, 상태·증거·anti-pattern 계약.
- `frontend/src/design-system/tokens.css`: 현재 primitive와 일부 semantic/component 토큰.

### Assumption

- KBX v36 디렉터리는 사용자 제공 참조이며, 그 코드·패키지·브랜드 토큰을 vendor/copy하지 않는다.
- K-ArtSell의 T01~T10 의미와 현 UI adapter v4 계약은 유지한다.
- 토큰 값 자체, density 기본값, 화면별 canonical scenario는 승인된 디자인/QA 기준이 없는 한 변경하지 않는다.

### Unknown

- 승인된 visual baseline, 디자인 소유자, target density, 화면별 keyboard/AT acceptance matrix가 없다.
- 31개 대상 파일에서 353개의 색상·spacing literal 후보가 발견됐지만, provider CSS와 의도된 시각화 scale을 제외하는 승인된 baseline은 없다.
- 실제 각 템플릿을 대표하는 Playwright scenario와 CI artifact retention 정책이 아직 계약화되지 않았다.

### Decision Required

1. `V13-FE-002`에서 semantic/component token 명명과 literal baseline을 승인할 UX/FE owner.
2. T01~T10에 `testProfile` 및 canonical scenario를 추가할 ADR/Issue와 QA owner.
3. compact/comfortable/touch 중 제품별 기본 밀도와 visual regression baseline 보관 위치.

## 적용 하네스

KBX의 구현물을 가져오지 않고 다음 불변식을 K-ArtSell의 현 경계에 적용한다.

| KBX v36 원칙 | K-ArtSell 현재 기반 | 승인 후 하네스 |
| --- | --- | --- |
| Template가 UX를 책임 | `screenTemplateCatalogue`의 상태·증거·anti-pattern | 각 template에 UX/복구/보안만 담는 `testProfile`을 추가. 도메인 정책·임계값은 포함하지 않음. |
| Recipe → canonical evidence | Vitest catalogue test, `AEG-V16-024` a11y evidence | template별 최소 대표 scenario와 실제 trace/screenshot/test log를 연결. 선언만으로 통과시키지 않음. |
| 3계층 토큰 | `tokens.css`의 primitive 및 일부 역할/컴포넌트 token | 화면은 primitive가 아닌 semantic/component token만 소비. primitive 값 변경은 token 파일 한 곳으로 제한. |
| Density는 학습 UX가 아님 | `[data-density='compact']`가 control/grid 높이만 변경 | comfortable/touch는 승인된 값과 state/keyboard characterization test가 있을 때에만 추가. |
| Design debt ratchet | 현재 정적 validator 및 353 literal 후보 | 승인된 baseline 이후 새/증가 literal을 차단하고, 기존 부채는 감소만 허용. provider CSS/visualization scale은 명시적인 allowlist로 분리. |
| Fail-closed provider boundary | `tools/validate_v16.py`의 adapter 외 vendor import 금지 | 화면/feature는 shared UI port만 사용. KBX로 바꾸는 것이 아니라 현재 adapter 경계를 검증 기반으로 보존. |

## 현재 디자인 진단과 개선 우선순위

2026-08-09 정적 후보 스캔(`*.vue`, `*.css`, `*.ts`, test 제외)은 31개 파일, 353개 literal을 반환했다. 이 값은 심미적 오류 수가 아니라 **승인 전 정규화 후보의 상한**이다.

| 우선순위 | 관측 근거 | 제안 Slice | 개선 방향 | 안전장치 |
| --- | --- | --- | --- | --- |
| P0 | `RiskDashboard.vue` 104, `MarketDataIngestion.vue` 57, `RebalanceForm.vue` 57, `IngestionStatus.vue` 41 후보 | V13-FE-002 | 페이지의 색상·spacing·radius를 semantic/component token으로 치환 | 화면별 visual/state matrix와 금융 의미 색상 검토; gradient/차트 scale은 임의 통합 금지 |
| P0 | 현재 `tokens.css`는 primitive와 역할 token이 한 계층에 섞여 있고 component 이름은 3개뿐 | V13-FE-002 | primitive/semantic/component를 CSS section과 이름으로 명시 분리 | 새 값·threshold·brand palette를 만들지 않고 기존 값만 alias로 이동 |
| P1 | 카탈로그는 mandatory evidence가 있으나 required check/scenario/evidence type이 없음 | 후속 ADR 승인 Slice | `testProfile`을 TypeScript contract와 JSON contract에 동시 추가 | client business truth 금지; 실행 가능한 test가 없는 template은 complete 주장 금지 |
| P1 | density는 compact만 존재 | V13-FE-002 이후 | density를 control/grid token에 한정하고 keyboard/focus 위치를 불변으로 test | layout/form 구조 변형 금지 |
| P2 | PrimeVue/AG Grid는 adapter 안에만 존재 | V13-FE-001 완료 | provider 교체 대신 포트/contract test로 독립성 유지 | 새 provider, library, direct import 금지 |

## 리팩터링 순서

1. 이 Slice에서 vendor boundary의 실제 정적 증거를 보존한다.
2. 승인 후 `V13-FE-002`에서 토큰 계약과 baseline을 먼저 확정한다. 화면 CSS를 그 전에 일괄 수정하지 않는다.
3. 같은 Slice에서 P0 네 화면을 한 화면씩 behavior-preserving으로 token화하고, 각 화면의 loading/empty/warn/error/readonly 및 keyboard/visual evidence를 남긴다.
4. 별도 승인 Slice에서 screen recipe `testProfile`과 대표 Playwright/Vitest evidence를 도입한다. 토큰 리팩터링과 섞지 않는다.
5. baseline이 승인된 뒤에만 ratchet을 CI에 강제한다. 기존 353 후보를 0으로 보이게 만드는 일괄 ignore/regex 우회는 금지한다.

## 이번 Slice 실행 증거

| 검증 | 실제 결과 |
| --- | --- |
| `python tools/validate_v16.py` | `PASS=1 WARN=2 FAIL=0`, exit 0 (2026-08-09) |
| Vendor boundary | validator가 `frontend/src`의 `.ts`/`.vue`에서 PrimeVue·AG Grid import를 검사하고 `shared/ui/adapter/primevue` 외 위치를 실패 처리 |
| 범위 | 코드/토큰 값/화면 동작은 변경하지 않음. 사용자 제공 `docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/`는 추적·수정하지 않음. |

경고 2건은 full source archive 및 승인 런타임이 없다는 내용이며, .NET/DB/Playwright/Shadow 결과를 통과로 주장하지 않는다.

## 다음 게이트

`V13-FE-002`는 이제 WBS 의존성은 해소되지만, 위 Decision Required에 대한 ADR/Issue 및 visual/QA baseline이 없으므로 실행 전 승인 상태를 확인한다.