# 다크 UI v2 실행 준비 계획 — 2026-06-28

목표: `docs/design-concepts/generated/*-v2-dark-unified.png` 시안을 실제 코드 기반 UI 개선 작업으로 전환한다. 생성 이미지는 방향성 기준일 뿐이며, 제품 UI는 React/CSS 컴포넌트로 구현한다.

## 0. 기준 자산

| 화면 | 기준 이미지 | 구현 기준 |
|---|---|---|
| 학습자 홈 | `docs/design-concepts/generated/02-learner-home-responsive-v2-dark-unified.png` | `apps/web/src/pages/LearnerHome.tsx`, `apps/web/src/pages/learner-home.css` |
| 라이브 상담 세션 | `docs/design-concepts/generated/03-session-responsive-v2-dark-unified.png` | `apps/web/src/pages/Session.tsx`, `apps/web/src/pages/session/session.css` |
| 회기 리뷰 | `docs/design-concepts/generated/04-session-review-responsive-v2-dark-unified.png` | `apps/web/src/pages/SessionReview.tsx`, `apps/web/src/pages/session-review/session-review.css` |
| 토큰 | `apps/web/src/styles/tokens.css` | dark 기본, sage-teal/clay/warn 배급 유지 |
| 프롬프트 근거 | `docs/design-concepts/prompts/vignette-dark-ui-refresh-2026-06-28.md` | UX 원칙과 금지 패턴 |

## 1. 적용 원칙

- 기존 기능을 새 이미지처럼 보이게 숨기지 않는다. 실제 API·세션 상태·저장된 리뷰·코칭 이력만 표시한다.
- generated PNG를 앱에 직접 박지 않는다. 이미지는 레이아웃/밀도/톤 기준으로만 쓴다.
- active 작업 화면은 단일 dark surface로 유지한다. 큰 white/beige 카드, 라이트 패널, 장식용 hero는 금지한다.
- 실시간 상담 중 피드백은 주변 신호다. 중앙 과업은 내담자 얼굴, 자막, 입력이다.
- 회기 리뷰는 점수 폭격이 아니라 근거 기반 회고다. 축어록·근거·워크시트 연결을 우선한다.
- 학습자 홈은 create/continue-first flow다. 첫 화면의 핵심 결정은 새 회기 시작 또는 이어가기다.

## 2. 구현 순서

### P1. 라이브 상담 세션

우선순위가 가장 높다. 사용자가 지적한 light/dark 혼합 문제가 여기서 시작됐고, 현재 학습 몰입도에 직접 영향을 준다.

변경 후보:

- `sx-page--active`, `sx-panel`, `sx-transcript`, `sx-controlbar`의 dark surface 명도 차이를 v2 기준으로 정리한다.
- 좌측 `내담자 컨텍스트`와 `회기 진행`은 더 조밀하게 만들되, 단계/주호소/난도/접근 정보는 유지한다.
- 중앙 stage는 avatar/orb/현재 상태 문구 위계를 분명히 하고, transcript와 시각적으로 같은 dark 작업면으로 맞춘다.
- 우측 rail은 `라이브 신호`, `관찰 신호`, `안전 점검`의 순서를 유지하되 색을 낮추고 amber/red 남용을 막는다.
- mobile/tablet에서는 context strip, stage, transcript, input, controlbar가 한 흐름으로 내려오게 한다.

검증:

- `cd apps/web; npm run typecheck`
- `cd apps/web; npm run build`
- `cd apps/web; npx playwright test e2e/session-layout.spec.ts --project=chromium-desktop --project=chromium-mobile --workers=1`
- `cd apps/web; npx playwright test e2e/layout-visual-gate.spec.ts --project=chromium-single-run --workers=1`

완료 증거:

- `docs/design-verification/full-pages/03-session-active-desktop.png`
- `docs/design-verification/full-pages/03-session-active-tablet.png`
- `docs/design-verification/full-pages/03-session-active-mobile.png`
- 가로 overflow 0, 컨트롤/텍스트 클립 0, 큰 white CSS surface 0.

### P2. 회기 리뷰

세션 다음의 학습 전환 화면이다. v2처럼 dark review workbench로 톤을 맞추되, 빈 상태와 실제 저장본 상태를 분리해야 한다.

변경 후보:

- filled review는 transcript 중심 + insight rail + worksheet workbench 구조를 강화한다.
- empty review는 가짜 데이터 없이 `대기` 상태만 dark panel로 표현한다.
- audio replay, PDF export, supervisor/teacher review, worksheet manual review 상태를 한눈에 보이게 정리한다.
- mobile은 `요약 / 트랜스크립트 / 인사이트` 식의 progressive disclosure를 유지한다.

검증:

- `cd apps/web; npm run typecheck`
- `cd apps/web; npm run build`
- `cd apps/web; npx playwright test e2e/session-review.spec.ts --project=chromium-desktop --workers=1`
- `cd apps/web; npx playwright test e2e/layout-visual-gate.spec.ts --project=chromium-single-run --workers=1`

완료 증거:

- filled/empty review 모두 dark surface 유지.
- worksheet, transcript, feedback cards가 서로 겹치지 않는다.
- 교사용 read-only 상태와 학습자 편집 상태가 깨지지 않는다.

### P3. 학습자 홈

세션 시작 전 의사결정 화면이다. 현재 구현을 유지하면서 persona 선택과 이어하기 CTA를 더 명확하게 만든다.

변경 후보:

- persona list는 코드, 이름, 나이/상황, 난도, 접근을 한 행에서 비교 가능하게 유지한다.
- selected-client workspace는 주호소, 현재 회기, 마지막 반응, `이어하기`/`새 회기 시작` CTA를 분명히 둔다.
- 기존 회기, 리뷰 대기, 다음 연습 추천은 실제 데이터 기반으로만 표시한다.
- mobile bottom nav와 compact card의 텍스트 클립을 다시 확인한다.

검증:

- `cd apps/web; npm run typecheck`
- `cd apps/web; npm run build`
- `cd apps/web; npx playwright test e2e/learner.spec.ts --project=chromium-desktop --workers=1`
- `cd apps/web; npx playwright test e2e/layout-visual-gate.spec.ts --project=chromium-single-run --workers=1`

완료 증거:

- create/continue primary action이 첫 화면에서 명확하다.
- 390/720/900/1440 폭에서 persona row, CTA, recent session row 텍스트가 잘리지 않는다.

## 3. 구현 전 체크

- 현재 작업트리가 dirty 상태이므로 UI 구현 전에는 변경 파일 범위를 좁힌다.
- `docs/dev_dashboard.html`에는 PLAN 상태로만 두고, 실제 구현/검증 전까지 DONE으로 바꾸지 않는다.
- API response shape를 바꾸지 않는 UI/CSS 라운드로 제한한다. 만약 DTO 변경이 생기면 `npm run check:api-types`를 추가한다.
- visual gate가 기존 9개 화면을 모두 보므로 한 화면 수정 후에도 전체 gate를 돌린다.
- 새 이미지와 실제 코드가 다를 때는 코드의 실제 기능을 우선한다. 이미지는 방향성이고 기능은 SSOT다.

## 4. 다음 실행 단위

1. `P1 라이브 상담 세션`만 먼저 구현한다.
2. 현재 `03-session-active-*` 캡처와 v2 이미지를 나란히 비교해 CSS delta를 최소화한다.
3. 1차 CSS 보정만으로 v2 근접도가 부족하면 `Session.tsx` 구조도 실제 기능 데이터 범위 안에서 조정한다.
4. 검증 통과 후 새 full-page 캡처를 남기고 SSOT를 DONE/VERIFY 상태로 갱신한다.
5. 그 다음 `P2 회기 리뷰`, `P3 학습자 홈` 순서로 반복한다.

## 5. P1 실행 기록

2026-06-29 1차 적용:

- `Session.tsx` stage에 내담자 이름/현재 발화 영역을 추가하고, 좌측에는 실제 경과·권장 시간·저장 발화 수 기반 `세션 진행` 패널을 추가했다.
- 우측 rail은 `라이브 신호`를 파형/상태 행/최근 흐름으로 재구성하고, `안전 점검`은 정상 상태에서도 보이는 체크 패널로 바꿨다.
- `session.css` active 화면 전용 dark token을 추가해 beige/off-white surface 혼입을 막고, stage/transcript/input/controlbar의 표면 명도와 focus-visible 상태를 v2 방향으로 정리했다.
- 갱신 캡처: `docs/design-verification/full-pages/03-session-active-desktop.png`, `03-session-active-tablet.png`, `03-session-active-mobile.png`.
- 검증: `npm run typecheck`, `npm run build`, `npx playwright test e2e/session-layout.spec.ts --project=chromium-desktop --project=chromium-mobile --workers=1` 8 passed, `npx playwright test e2e/layout-visual-gate.spec.ts --project=chromium-single-run --workers=1` 9 passed.

## 6. P2 실행 기록

2026-06-29 2차 적용:

- `session-review.css`의 learner filled review를 2열에서 3열 workbench로 바꿔, 왼쪽 요약/차트/흐름, 중앙 축어록, 오른쪽 평가/인사이트, 하단 워크시트 구조로 재배치했다.
- `layout-visual-gate.spec.ts`의 기존 2열 가정을 3열 workbench 검증으로 갱신하고, empty review는 계속 sparse third column 없이 2열 이하로 접히게 유지했다.
- 4차 QA에서 dark surface 계층을 overview/worksheet/rubric/prepost별로 다시 분리하고, chip/evidence/timestamp 버튼의 `focus-visible` 상태를 보강했다.
- 갱신 캡처: `docs/design-verification/full-pages/04-session-review-desktop.png`, `04-session-review-tablet.png`, `04-session-review-mobile.png`.
- empty 상태 증거 캡처: `04-session-review-empty-desktop.png`, `04-session-review-empty-tablet.png`, `04-session-review-empty-mobile.png`.
- 검증: `npm run typecheck`, `npm run build`, `npx playwright test e2e/session-review.spec.ts --project=chromium-desktop --workers=1` 3 passed, `npx playwright test e2e/layout-visual-gate.spec.ts --project=chromium-single-run --workers=1` 9 passed.

## 7. P3 실행 기록

2026-06-29 3차 적용:

- `LearnerHome.tsx` dashboard view를 재구성해 대시보드의 연습 대상 레일을 제거했다. 내담자 선택은 `/learn/practice`의 역할로 분리하고, `/learn`은 학습 상태와 오늘 이어갈 회기 판단에 집중한다.
- 진행 회기/리뷰 대기/최근 평가/라포 흐름은 상단 CTA 바 `lh-dashboard-status`로 올렸다. 핵심 지표는 오늘 회기 카드의 부속 정보가 아니라 대시보드 진입 직후 확인하는 상태 요약이다.
- 오늘 이어갈 회기, AI 코치, 다음 연습 추천, 최근 피드백은 `lh-work-cluster` 안에서 같은 작업 묶음으로 보이게 했다. 데스크톱에서는 회기와 코치가 같은 row에 놓이고, 추천/피드백은 그 아래 row로 묶인다.
- 오른쪽 레일은 최근 기록, 리뷰 대기, 반복 대상만 남겨 학습 이력과 후속 행동을 담당하게 했다.
- visual gate의 learner-home 준비 조건은 상단 지표 CTA, 작업 클러스터, 실제 최근 기록 row가 보이는 상태로 강화했다.
- 4차 QA에서 `학습 현황` ARIA label strict 충돌을 제거하고, persona name/summary clamp와 주요 버튼의 `focus-visible` 상태를 보강했다.
- 갱신 캡처: `docs/design-verification/full-pages/02-learner-home-desktop.png`, `02-learner-home-tablet.png`, `02-learner-home-mobile.png`.
- 검증: `npm run typecheck`, `npm run build`, `npx playwright test e2e/layout-visual-gate.spec.ts --project=chromium-single-run --workers=1` 9 passed.

## 8. 완료 상태

- P1/P2/P3 모두 실제 React/CSS 화면에 적용했고, 생성 PNG는 레이아웃·밀도·톤 기준으로만 사용했다.
- 이번 라운드는 API response shape를 바꾸지 않았으므로 `npm run check:api-types`는 추가하지 않았다.
- `layout-visual-gate.spec.ts`는 4차 QA부터 각 캡처가 dark UI surface인지 `html[data-theme="dark"]`로 단언한다.
- 전체 DONE 근거는 최신 full-page 캡처와 `typecheck/build/layout-gate` 검증이다.