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

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 토큰.

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

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 금지

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

검증	실제 결과
`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이 없으므로 실행 전 승인 상태를 확인한다.