yunchan/vignette
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
vignette/docs/archive/ops/dark-ui-refresh-implementation-plan-2026-06-28.md
Yun Chan 778e8526d4 세션 평가·라이브코치·교수자 분석 라운드 마감 + 문서 정리 + 코드품질 리팩터 
- 누적 작업트리 커밋: 회기 평가 복구·durable 저장, 라이브 코치 이력/근거, 교수자 학생분석, 음성 비언어 메타, PII 마스킹, 운영 티켓/헬스 등
- 문서: 완료 기록 docs/archive/ 냉동 보관, docs/ 단일 인덱스(docs/README.md)+통합 TODO(docs/TODO.md)로 정리
- 리팩터(행위 보존): Stage enum SSOT(taxonomy 소유·state_machine re-export), store recent/masked_turns 중복 제거, speaker_ko_label 단일 헬퍼, _list_sessions N+1 제거(state/turns 배치 + 턴평가 하이드레이션 배치)
- 검증: 백엔드 pytest 352 passed, _list_sessions E2E chromium-single-run 2 passed
2026-07-02 02:50:36 +09:00

11 KiB
Raw Blame History

다크 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 검증이다.