다크 UI 시안과 운영 문서 갱신

docs/ops/dark-ui-refresh-implementation-plan-2026-06-28.md

@@ -0,0 +1,113 @@
+# 다크 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. `Session.tsx` 구조 변경은 피하고, 가능한 한 `session.css`에서 surface/density/responsive만 조정한다.
+4. 검증 통과 후 새 full-page 캡처를 남기고 SSOT를 DONE/VERIFY 상태로 갱신한다.
+5. 그 다음 `P2 회기 리뷰`, `P3 학습자 홈` 순서로 반복한다.