데스크톱 온보딩 — 빈 화면에서 검정 지면 위 흰 카드로 (2026-09-14)
- 기간: 2026-09-14 (세션 1개, 오너 보고 "지금 데스크톱에서 바탕화면이 이런식으로 되어있는데 왜 그런거야?" → 지시 "배경화면이 검정색이고, 가운데 하얀 카드가 떠있는 구조였으면 좋겠어")
- 랜딩: 앱 PR #1601(Phase 1
dc577c6c+ Phase 2b586ca02) → release/v0.19.0 병합53265b7e(큐 실행) — 마이그레이션·엣지 없음, staging·Production 미배포(v0.19.0 승격 대기) - 설계서: 없음(수리 건) — 분석·Phase 계획·예상 효과는 앱 이슈 #1600
- 정본: 앱
src/react/vite/desktopRoot.tsx(온보딩 =DesktopAppFrame안),src/react/ui/desktop/styles/desktop.css의.dk-onb·.dk-onb-wel - 도구: 임시 로컬 하네스(앱 레포 루트
dev-onb-1600.html·dev-onb-1600.tsx, 커밋하지 않고 삭제) — 계정 없이 가입 5단계를 실제 프레임 안에서 렌더 - 게이트:
npm run check2회(정적 검사·Dead-CSS 게이트·단위 테스트 실패 0),ci:precheck-local(검증: ci:precheck-local precheck · static 통과 · unit-1 통과 2074 passed / 0 failed / 64 conditional skip · unit-2 통과 1790 passed / 0 failed / 85 conditional skip · 1분 56초). 마이그레이션·pgTAP·e2e 미접촉. 브라우저 회귀 테스트는 QA1 저장소 소관이라 이번에 추가하지 않음 - 버그리포트:
bug-report/bug-145-20260914.md - 계약: 없음
Phase 현황
| Phase | 내용 | 상태 |
|---|---|---|
| Phase 1 | 구조 수리 — 진입점이 온보딩을 DesktopAppFrame(.dk-app) 안에서 렌더 | ✅ dc577c6c (PR #1601) |
| Phase 2 | 검정 지면(#000) + 로그인·4단계·웰컴 가운데 흰 카드 구조 | ✅ b586ca02 (PR #1601) |
1. 배경
데스크톱 웹에서 새 계정으로 로그인하면 약관 동의 화면이 하늘색 바탕에 글자만 흩어져 보였다. 체크 동그라미와 "다음" 버튼 배경이 없어 어디를 눌러야 하는지 알 수 없었다. 오너가 staging 스크린샷으로 보고했고, 조사 결과 Production 로그인 화면도 같은 상태였다.
2. 문제 제기
온보딩 여섯 화면이 데스크톱 토큰 상자 밖에서 그려지고 있었다
desktop.css의 색·테두리·그림자 변수는 .dk-app 안에서만 선언된다. 컨트롤러(app.tsx)는 로그인 전·가입 절차에서 온보딩을 그 상자 없이 돌려주고, 진입점(desktopRoot.tsx)도 감싸지 않았다. 값이 없는 변수를 쓴 속성은 통째로 무효가 되어 카드 배경 투명, 테두리 없음, 버튼 글꼴 Arial이 됐다. 2026-07-18 온보딩 연결(#245)부터 이 구조였다(코드 이력 기준). 증상별 대응은 BUG-145 1절.
지면이 오너가 원하는 구조가 아니었다
수리해도 원래 설계는 하늘색 글로우 지면 위 흰 카드였다. 오너는 부팅 스플래시처럼 검정 지면 위에 흰 카드가 가운데 떠 있는 구조를 원했다.
3. 해결 방안
원칙
- D1 (2026-09-14, 오너): "배경화면이 검정색이고, 가운데 하얀 카드가 떠있는 구조였으면 좋겠어" → 로그인·약관·신체·프로필·1RM·웰컴 여섯 화면을 검정 지면(#000) + 가운데 흰 카드로 통일. 전제(오너 go로 확정): 검정 = 스플래시·모바일
ob-dark와 같은#000, 로그인·웰컴도 같은 구조, 목적 릴리스 release/v0.19.0.
접근
| 대안 | 판단 |
|---|---|
.dk-onb에 필요한 변수만 복사 선언 | 기각 — 토큰 두 벌, 다음 화면에서 재발 |
토큰을 전역 :root로 이동 | 기각 — 2026-06-23 모바일/데스크톱 토큰 격리 정책 폐기 |
진입점에서 DesktopAppFrame으로 감싼다(모바일 MobileAppFrame과 대칭) | 채택 — 화면 루트가 셸 밖으로 나가는 구멍을 한 곳에서 막는다 |
4. 적용한 내용
Phase 1 — 구조 수리 (dc577c6c)
src/react/vite/desktopRoot.tsx:renderDesktopOnboarding이UiDesktopOnboarding을DesktopAppFrame으로 감싼다. 주석에 이유와 #1600을 남겼다.
Phase 2 — 검정 지면 + 흰 카드 (b586ca02)
src/react/ui/desktop/styles/desktop.css:.dk-onb { background: #000 }—.dk-app그리드의 유일한 항목이라 뷰포트를 채우고, 자식margin: auto가 카드를 가운데에 둔다..dk-onb-wel을 다른 단계처럼 흰 카드(560px, 반경 22px,--sh-card)로.
주요 결정과 그 근거
- 래핑 위치를 컨트롤러가 아니라 진입점으로 둔 이유: 모바일이 이미 진입점(
mobileRoot)에서 같은 일을 하고 있어 두 플랫폼의 계약이 대칭이 된다. - 웰컴 화면도 카드로 만든 이유: 여섯 화면이 하나의 구조("검정 지면 + 가운데 흰 카드")를 갖게 해 예외를 없앤다.
작업 중 드러난 것
- 가입 5단계는 새 계정이 있어야 보이는 화면이라, 앱 레포 루트에 임시 하네스 HTML/TSX를 두고 vite dev 서버로 실제 프레임(
DesktopHostFrame>DesktopAppFrame) 안에서 렌더해 클릭으로 진행하며 검증했다. 커밋하지 않고 삭제했다. - 앱 저장소의
tests/는 QA1로 이관되어(#1591) 회귀 테스트를 앱 PR에 넣을 수 없다. 후속은 QA1 소관.
5. 적용 결과
| 항목 | 결과 |
|---|---|
로그인 화면 .dk-onb의 .dk-app 조상 | 없음 → 있음 |
--surface 계산값 | "" → oklch(1 0 0) |
| 로그인 카드 배경·그림자 | 투명·없음 → 흰색·--sh-card |
| 소셜 버튼 글꼴·모서리 | Arial·0 → Wanted Sans·11px |
| 온보딩 지면 | 하늘색 글로우 → #000, 뷰포트 1400×900 전체, 문서 스크롤 없음 |
| 카드 정중앙 오차 | 로그인·약관·신체·프로필·1RM·웰컴 모두 0px·0px |
| 모바일 375×812 | 무영향(모바일 루트만 렌더, .dk-onb 없음) |
| staging·Production 화면 | 미검증 — v0.19.0 승격 뒤 확인 |
| 시각 품질 | 사람 눈으로만 판단 가능(검정 위 카드 그림자는 보이지 않으며 그대로 둠) |
6. 이번 개선으로 향상된 것
데스크톱 신규 유저가 가입 절차를 볼 수 있다
체크 동그라미·버튼·카드가 보이지 않던 화면이 검정 지면 위 흰 카드로 나타난다. 로그인 화면도 카드·글꼴이 설계대로 나온다.
구조적으로 남는 것
- 데스크톱 진입점이 컨트롤러 밖 화면도 토큰 상자 안에서 그린다 — 모바일과 대칭인 계약.
남은 것
- v0.19.0 승격 뒤 staging·Production 화면 확인(승격 세션 몫).
- QA1: 데스크톱 로그인·온보딩 DOM에
.dk-app조상이 있고--surface가 해석되는지 단언하는 브라우저 회귀 테스트(범위 밖, 오너 결정 불필요).