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

다크 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 학습자 홈 순서로 반복한다.