Files
joke-app/docs/07-ui-ux.md
EJClaw 4e0eb4d52c 모든 게임: 결과·팝업은 애니메이션이 끝난 뒤에, 증강 윷놀이: 이의있음!이 다음 판에도 뜨게, 증강 고르는 목록·나오게 할 증강을 팝업 목록으로
- lib/motion: motionBusy / useMotionHold / useMotionSettled / useAfterMotionValue / AfterMotion
- 방 화면: 결과 창과 상태 줄은 판이 멈춘 뒤에(실시간 게임은 상태 줄 그대로), 새 판마다 판 화면을 새로 그림
  (결과 창에 둔 채 다음 판이 시작되면 이전 판의 효과 번호가 남아 이의있음!·알림이 안 뜨던 문제)
- 41개 게임: 결과 패널·배너·점수·팝업이 마지막 움직임 뒤에 나오도록 게임별로 정리
- 증강 윷놀이: 명탐정·배달·손버릇·따라쟁이·착각 대상은 아이콘과 설명이 다 보이는 목록에서,
  방 설정의 나오게 할 증강은 팝업 목록에서 스위치로 켜고 끔
- e2e: 늦게 바뀌는 상태 줄·결과 창과 새 증강 화면에 맞춤

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 22:26:22 +09:00

24 KiB
Raw Blame History

07. UI/UX 설계

1. 디자인 원칙

  1. 한 화면에 할 일 하나. 지금 눌러야 하는 버튼이 가장 크고 진하다.
  2. 글자 + 아이콘. 아이콘만 있는 버튼 금지(닫기 ✕ 제외).
  3. 지금 상황을 문장으로. 화면 맨 위에 "내 차례예요. 돌을 놓을 곳을 눌러 주세요."
  4. 할 수 있는 것만 누를 수 있게. 둘 수 있는 곳·낼 수 있는 카드만 밝게, 나머지는 흐리게. 잘못 누르면 짧게 흔들리고 이유를 한 줄로("같은 색 카드만 낼 수 있어요").
  5. 실수 방지. 큰 결정(기권, 나가기, 올인, 다이)은 확인. 단, 매 턴 확인창은 금지(느려짐) — 대신 "두 번 눌러 확정" 옵션(바둑·오목 오착 방지, 기본 켜짐: 첫 탭은 미리보기 돌, 같은 곳을 다시 탭하면 착수).
  6. 기다림을 보여 준다. 남은 시간 링, "OO님이 생각 중…", 연결 상태.
  7. 가볍게. 장식 이미지 최소, 애니메이션은 짧게(150~250ms), prefers-reduced-motion 존중.
    • 게임 속도(2026-10-14): 코드에 적힌 길이는 그대로 두고, 게임 화면 안의 모든 움직임을 lib/motion.ts가 1.5 ÷ 관리자 게임 속도 배율배로 늘인다(1배여도 적힌 길이보다 1.5배 천천히). CSS 애니메이션·트랜지션은 .game-layout 안에서 useMotionScope가 재생 속도(playbackRate)를 맞추고, Web Animations는 fxAnim(...), 연출 타이머(배너 유지, 다음 단계, 날아가는 복사본 정리, 숫자 세기)는 fxMs(ms)로 감싼다. 채팅 칸과 role="timer"(남은 시간 막대)는 실제 시간이라 빼고, 주사위 숫자 깜빡임 간격·그림 스트림·두 번 눌러 확인하는 창도 그대로.
    • 결과는 움직임 다음(2026-11-08): 결과 창, 위쪽 상태 줄, 게임 안의 결과 팝업·배너·점수는 판이 다 움직인 뒤에 나온다. lib/motion.ts의 motionBusy(끝이 있는 CSS·Web Animation이 돌고 있거나 useMotionHold가 잡고 있으면 움직이는 중), useMotionSettled/<AfterMotion>(0.22초 동안 멈춰 있으면 보여 줌, 최대 12초), useAfterMotionValue(멈춘 뒤에 값을 바꿈)를 쓴다. 타이머로 한 단계씩 보여 주는 연출은 useMotionHold로 잡아 둔다. 실시간 게임(할리갈리·도블·사과 게임·그림 맞히기)은 상태 줄을 바로 바꾼다(liveStatus).
  8. 한눈에 들어오게 (2026-10-09, "한 화면에 정보가 너무 많다" 피드백). 참고: NN/g 점진적 공개(자주 쓰는 것만 첫 단계, 나머지는 이름이 분명한 두 번째 단계, 최대 2단계), 토스 "한 화면 한 가지", Board Game Arena 화면 지침(판이 가운데, 정보는 묶어서, 드문 정보는 버튼·접기 뒤로), Hick의 법칙(고를 것이 많으면 묶음 탭으로 나눈다).
    • 같은 정보를 두 곳에 두지 않는다(방 안에서는 사이트 메뉴를 숨기고 방 막대 한 줄만, 대기실의 규칙 전문은 [📖 규칙]으로).
    • 목록 카드는 이름 + 한 줄 정보만. 설명·난이도는 들어간 다음 화면에서.
    • 지금 필요 없는 것은 숨긴다(자리가 다 차면 초대 카드, 처음부터 펼친 해시값 같은 세부 정보).
    • 버튼은 화면마다 진한 것 하나. 나머지는 한 줄에 묶어 덜 진하게.
    • 경고·안내 문구는 한 줄로 줄인다(전문은 처음 한 번, 로그인·이름 정하기·/me에서).

2. 디자인 토큰

2.1 색 (밝은 테마 / 어두운 테마)

토큰 밝게 어둡게 용도
--bg #F7F5F0 #16181D 배경(따뜻한 미색)
--surface #FFFFFF #20232A 카드, 패널
--text #1C1E21 #F2F3F5 본문(명암비 15:1 이상)
--text-sub #4A4F57 #B8BCC4 보조 글(4.5:1 이상)
--primary #2563EB #5B8DEF 주요 버튼(파랑)
--primary-text #FFFFFF #0B1020 주요 버튼 글자
--success #15803D #4ADE80 준비, 성공
--warning #B45309 #FBBF24 시간 부족, 연결 불안정
--danger #B91C1C #F87171 기권, 나가기
--felt #1F6B4A #17513A 카드 게임 테이블
--wood #E3B76B #B98C45 바둑판·오목판·장기판
--focus #F59E0B #F59E0B 키보드 포커스 테두리 3px
  • 색만으로 정보를 전달하지 않는다(내 차례 = 색 + 글자 + 테두리). 색약 모드: 카드 무늬에 모양 추가(♦에 빗금 등), 팀 색을 파랑/주황 조합으로.

2.2 글자

  • 글꼴: Pretendard Variable(자체 호스팅, KS X 1001 서브셋 + 필요한 문자).
  • 크기 단계(기본 "보통"): 본문 17px, 작은 글 15px(최소), 버튼 18px, 제목 22/28px. 줄 간격 1.5.
  • 글자 크기 설정: 보통(100%) / 크게(120%) / 아주 크게(140%). 루트 font-size만 바꾸고 모든 크기는 rem으로.
  • 굵기: 본문 500, 버튼·제목 700. 300 이하 금지.

2.3 크기·간격

  • 터치 영역 최소 48×48px, 주요 버튼 높이 56px, 버튼 사이 간격 최소 8px.
  • 간격 단위 4px(4/8/12/16/24/32).
  • 모서리 둥글기 12px(버튼), 16px(카드).
  • 바둑판처럼 칸이 작은 보드: 칸 크기가 32px 미만이면 "확대 보기" 버튼 + 두 손가락 확대 지원, "두 번 눌러 확정" 기본 켜짐.

3. 화면 틀 — PC 중심 (2026-10-04 결정)

사용자 요청으로 PC 화면을 기준으로 설계한다. 휴대폰·태블릿은 같은 화면을 세로로 접어서 지원한다.

3.1 화면 폭 구간

구간 폭 배치
PC (기준) 1100px 이상 (설계 기준 1280~1920) 상단 메뉴 + 여러 칸 배치, 채팅·기보 항상 보임
태블릿 720~1099px 두 칸 → 한 칸으로 접힘, 오른쪽 패널은 판 아래로
휴대폰 720px 미만 한 칸, 채팅은 버튼으로 여는 시트, 주요 버튼은 아래 고정

3.2 공통 상단 메뉴 (PC)

┌──────────────────────────────────────────────────────────────────────────┐
│ ● 같이 놀자 보드게임    홈   게임 목록                         [🌙]   👤 닉네임 ▾ │ 64px
└──────────────────────────────────────────────────────────────────────────┘
  • 오른쪽에 테마 버튼(🌙/☀️)을 둔다. 누를 때마다 밝은 화면 ↔ 어두운 화면으로 바뀌고, /me의 '화면 색' 설정과 같은 값을 쓴다('자동'이면 지금 보이는 색의 반대로). 코드로 참여는 홈의 [🔢 코드로 참여](→ /j)로 한다.
  • 오른쪽 끝: 로그인 전에는 [로그인](→ /login: 큰 [디스코드로 로그인], 아래 [게스트로 시작하기] → /login/guest에서 계정 이름 정하기). 로그인 뒤에는 닉네임(디스코드로 가입했으면 디스코드 이름)을 보이고, 누르면 [⚙️ 설정]·[🚪 로그아웃] 메뉴가 열린다. [⚙️ 설정]은 페이지를 옮기지 않는 팝업(화면 설정 + [내 계정 · 기록 보기] → /me)이고, 방 막대의 [⚙️ 설정]도 같은 팝업(계정 링크 없음)이라 방에서 나가지 않는다. /me에도 같은 화면 설정이 있다.
  • 내용 폭은 최대 1280px, 가운데 정렬. 게임 화면만 화면 전체 폭을 쓴다.
  • 한 줄로 읽고 입력하는 화면(게임 소개 /g/:id, 코드로 참여 /j, 규칙 /rules/:id)은 PC에서 가운데 768px 칸만 쓴다. 휴대폰용 한 줄 배치를 1,200px로 늘리면 버튼·입력칸·글 줄이 너무 길어져 오히려 흩어져 보인다(2026-10-09). 페이지 위 [← 뒤로] 줄도 같은 폭(TopBar width).
  • 설정(/me)은 PC에서 1080px 두 칸: 왼쪽 프로필·로그아웃(따라 내려옴), 오른쪽 화면 설정·기록. 휴대폰은 한 줄이고 로그아웃은 맨 아래.

3.3 홈 (PC)

┌ 상단 메뉴 ───────────────────────────────────────────────────────────────┐
│ [▶ 하던 게임으로 돌아가기] (있을 때만)                                        │
│ [+ 방 만들기 (파란 큰 버튼)]   [🔢 코드로 참여 → /j]   [🤖 컴퓨터와 연습]        │
├──────────────────────────────────────────────────────────────────────────┤
│ 🎮 게임 고르기  [전체] [판·주사위] [카드·패] [여럿이 파티]  ← 제목과 종류 탭 한 줄          │
│ 게임 타일 격자 (PC 자동 열, 휴대폰 3열. 타일 = 아이콘·이름·"2명 · 5~15분")            │
└──────────────────────────────────────────────────────────────────────────┘
  • 첫 화면에 다 넣지 않는다. 설명 글은 버튼 아래 한 줄만, 나머지는 탭이나 버튼을 눌러 들어간다.
  • 게임 한 줄 소개와 난이도는 게임 소개(/g/:id)에만 둔다. 휴대폰에서 26개가 세 화면 남짓에 들어온다.
  • 휴대폰: [+ 방 만들기]는 한 줄 전체, [코드로 참여]·[컴퓨터와 연습]은 그 아래 나란히.
  • PC·태블릿: 큰 버튼 3개는 아이콘을 왼쪽에 둔 낮은 가로 카드. 1440×900에서 게임 26개가 스크롤 없이 한 화면에 들어온다. [방 만들기]·[컴퓨터와 연습]의 게임 고르기 창은 두 줄로 나란히.

3.4 대기실 (PC)

┌──────────────────────────────────────────────┬──────────────────────┐
│ 초대 카드 한 줄(빈자리 있을 때만): 코드 | [링크 복사][초대글 복사] │ 게임 설정               │
│ 자리 카드(2명 방은 2칸, 5명 넘으면 3칸씩)               │ (펼쳐서 바로 수정 — 방장) │
│ [🤖 컴퓨터 넣기] [관전으로 바꾸기]                     │                      │
│        [▶ 게임 시작] / [준비하기] (가운데 420px)       │                      │
│ 채팅                                         │                      │
└──────────────────────────────────────────────┴──────────────────────┘
  • 사람에 관한 것(초대 → 자리 → 시작 → 채팅)은 넓은 왼쪽 칸에 위에서 아래로, 가끔 보는 게임 설정은 오른쪽 400px 칸. 오른쪽 칸에 자리 카드를 두 칸씩 넣으면 이름이 한 글자씩 꺾여서(2026-10-09) 자리를 넓은 칸으로 옮겼다.
  • 태블릿·휴대폰은 한 줄: 초대 → 자리 → 게임 설정, 시작 버튼은 아래(휴대폰은 화면 아래 고정).

3.5 게임 화면 (PC)

┌ 상단 메뉴(얇게 48px: 게임명·코드·메뉴) ─────────────────────────────────────┐
│                                              │ 상태: 내 차례예요 ◔ 23초       │
│                                              │ 상대 정보 · 시계               │
│             게임 판 (화면 높이에 맞춤)            │ 내 정보 · 시계                 │
│                                              │ [무르기][무승부][기권]          │
│                                              │ 기보(수 목록)                  │
│                                              │ 채팅 + 반응 버튼               │
└──────────────────────────────────────────────┴──────────────────────────────┘
  • 오른쪽 패널 폭 360px, 판은 남은 공간에서 가장 큰 정사각형.
  • 카드 게임: 판 자리에 원형 테이블, 나는 항상 아래, 내 패는 판 아래쪽 넓게.
  • 다른 사람 자리 줄(구십구·원카드·도블): PC·태블릿(720px 이상)에서는 사람이 많아도 옆으로 스크롤하지 않고 판 위 빈 공간에 여러 줄로 쌓는다. 한 줄에 들어가면 한 줄, 넘치면 줄마다 고르게 나눈다(9명 → 5 + 4, 8 + 1이 아님). 한 줄에 몇 칸 들어가는지는 화면 폭이 아니라 게임 칸의 실제 폭으로 정한다(lib/seat-rows.ts). 휴대폰은 세로 공간이 모자라서 한 줄 그대로 옆으로 밀어 본다(2026-10-11).
  • PC 조작: 마우스를 올리면 미리 보기 돌(반투명), 클릭 한 번에 착수(기본값). "두 번 눌러 확정"은 터치 기기의 기본값이고 설정에서 바꿀 수 있다.
  • 단축키: Enter 채팅 입력, Esc 창 닫기, 방향키+Enter 판 조작.
  • 방 막대 버튼은 마우스 환경에서 40px(막대 52px 안에 여유), 터치 기기에서는 48px.
  • 방 안(대기실·게임·결과)에서는 사이트 상단 메뉴를 숨기고 방 막대(← 홈 · 게임 이름 · 🔗 방 코드 · 📖 규칙 · ⚙️ 설정 · 🚪 나가기) 한 줄만 둔다. 판이 그만큼 커진다. 높이 계산은 CSS 변수 --site-h(방 안에서는 0)를 쓴다.
  • 채팅의 빠른 반응(이모지·짧은 말)은 한 줄. 넘치면 옆으로 밀어 본다.
  • 채팅 한 줄은 이름(작은 글씨, 사람마다 다른 색)과 말풍선(내용)을 위아래로 나눠 보여 준다. 내 말은 오른쪽, 같은 사람이 이어서 말하면 이름은 한 번만. 목록은 늘 맨 아래(새 말)에 붙어 있고, 위로 올려 읽는 중에는 움직이지 않다가 내가 보내거나 아래로 내려오면 다시 붙는다(2026-10-13). 사람별 채팅 가리기는 없앴다(사용자 요청, 2026-10-13. 필요하면 방장이 내보내기).
  • 채팅을 보낸 뒤에도 입력 칸 포커스를 그대로 둔다. 휴대폰에서 "보내기" 버튼을 눌러도 키보드가 내려가지 않는다(버튼을 누를 때 포커스를 가져가지 않음, keepFocus). 방 채팅·그림 맞히기·마피아·라이어 게임 채팅 모두 같다(사용자 요청, 2026-10-15).
  • 결과 창: 진한 버튼은 [🔁 한 판 더] 하나(누르면 그 방 대기실로 돌아간다, docs/06 §결과). [판 보기]·[▶ 다시 보기]는 한 줄에 나란히, [방 나가기]는 글자 버튼, 공정성 확인은 접어 둔다.

3.6 관리자 (PC)

왼쪽 사이드바(220px)에 메뉴, 오른쪽에 내용. 표는 PC에서 표 형태, 좁은 화면에서는 카드 목록.

4. 공통 컴포넌트

컴포넌트 동작
BigButton 56px, 종류 primary/secondary/danger, 로딩 표시, 두 번 눌림 방지
CodeDisplay 123 456 큰 글씨 + 복사
CopyButton 복사 후 1.5초 "복사했어요 ✓", 실패하면 텍스트 선택 상태로 보여 줌
ShareButton navigator.share 있으면 공유 시트, 없으면 링크 복사
QrModal QR 크게 + 코드
CodeInput 6칸, 숫자 키패드, 붙여넣기 감지, 다 채우면 자동 제출
Seat 프로필, 이름, 방장/준비/연결 상태
TurnTimer 원형 링, 10초 남으면 주황 + 똑딱 소리(설정), 5초 남으면 빨강 + 진동
Toast 위에서 내려오는 짧은 알림(3초), 스크린리더 aria-live
ConfirmSheet 아래에서 올라오는 확인창(큰 버튼 두 개)
Card 트럼프/화투/게임 카드 공용 SVG, 크기 3단계
RulesSheet 게임 중 규칙 요약(그림), 현재 상황 도움말
ConnectionBanner "다시 연결하는 중…" 띠, 인터넷이 끊기면 방 밖에서도 "인터넷 연결이 없어요" 띠

5. 초보자 도움

  • 처음 하는 게임이면(기기 기준) 시작할 때 "30초 규칙 요약" 카드 3장(그림 위주), [건너뛰기].
    • 구현: 게임이 진행 중인 화면을 이 기기에서 처음 볼 때(시작하거나 진행 중인 방에 들어올 때, 관전 포함) 카드 3장을 띄운다. [다음]·[건너뛰기], 마지막 장은 [시작하기]. 본 게임은 localStorage bg:qs:<게임id>에 기억한다. 규칙 페이지의 [30초 요약 보기], 게임 중 [?]의 [30초 요약 다시 보기]로 언제든 다시 본다.
    • 그림은 이미지 파일 없이 기존 카드 컴포넌트(트럼프·화투·마작패 등)나 작은 인라인 SVG·이모지로 그리고, 그림마다 대체 글(alt)을 단다.
  • 게임 중 [?] → 지금 상황에서 할 수 있는 것 설명("지금은 낼 카드를 고르는 차례예요. 밝게 보이는 카드만 낼 수 있어요").
    • 구현: 차례 안내 줄 오른쪽의 [? 도움] → "지금 할 수 있는 것" 시트. 게임마다 지금 화면(view)만 보고 문장을 만든다(숨은 정보는 쓰지 않음). 시트에서 [전체 규칙 보기](그 게임의 규칙 설명을 펼침)와 [30초 요약 다시 보기]로 이어진다. 관전자에게는 "구경하고 있어요"를 먼저 알려 준다.
    • 내용은 게임별 apps/web/src/games/<id>/quick.tsx(카드 3장)·help.ts(helpNow)에 있고 게임 화면 묶음과 함께 필요할 때만 내려받는다.
  • 족보·점수가 복잡한 게임(섯다, 포커, 고스톱, 마작)은 내 패 옆에 현재 족보 이름 표시("지금: 7끗", "투페어"), 족보표 버튼.
    • 구현 확인: 섯다·포커는 "지금: <족보>"(방 설정 힌트가 켜졌을 때)와 족보표, 고스톱은 내 점수 내역(광·열끗·띠·피 진행, 점수 항목, 고 횟수)과 족보표, 마작은 대기패·버리면 텐파이 표시(초보 모드)와 역 목록. [?] 설명에도 지금 족보·점수·대기패를 함께 보여 준다.
  • 힌트 옵션(방 설정): 끄면 하이라이트만, 켜면 추천 수 표시(초보 방).

6. 소리·진동

  • 짧은 효과음만(돌 놓기, 카드 넘기기, 내 차례 알림, 시간 경고, 승리). 합쳐서 100KB 이하, 처음 사용자 조작 후에만 재생(브라우저 정책).
  • 내 차례가 되었는데 탭이 백그라운드면: 탭 제목 깜빡임("● 내 차례예요") + 소리(설정).
  • 진동(navigator.vibrate): 내 차례, 시간 5초 남음.

7. 접근성

  • 키보드만으로 모든 조작 가능(보드는 방향키로 칸 이동 + Enter). 포커스 테두리 항상 보이게.
  • 스크린리더: 보드 칸에 aria-label("가로 8, 세로 8, 빈칸"), 상대의 수를 aria-live로 읽어 줌("상대가 H8에 두었어요").
  • 명암비 기준 WCAG 2.2 AA 이상, 큰 글자 모드에서 화면이 깨지지 않는지 테스트.
  • 시스템 글자 크기·확대 존중(user-scalable 막지 않음).

8. 성능 예산

항목 예산
첫 화면 JS 150KB gzip 이하 (React + 라우터 + 홈)
게임 화면 하나 추가 80KB gzip 이하(lazy)
글꼴 서브셋 woff2 2개(500/700) 합 400KB 이하, font-display: swap
이미지 게임 카드 썸네일은 SVG 또는 WebP 10KB 이하
외부 요청 0개(디스코드 아바타 제외)

9. 문구 규칙

  • 존댓말 해요체, 짧게. "~하시겠습니까?" 대신 "~할까요?".
  • 어려운 말 금지: "테이블" → "방", "세션" → 쓰지 않음, "로비" → "홈".
  • 오류 문구는 원인 + 할 일: "방을 찾을 수 없어요. 코드를 다시 확인해 주세요."

10. 화면 목록과 상태 (구현 체크용)

  • 홈(로그인 전/후, 진행 중 게임 있음)
  • 닉네임 입력(게스트 시작 / 링크 입장)
  • 코드 입력
  • 게임 상세
  • 대기실(방장/참가자/관전자, 인원 부족/가득 참)
  • 게임 화면(내 차례/남의 차례/연결 끊김/자리 비움/일시 정지)
  • 결과 화면(승/패/무승부, 한 판 더 → 대기실, ▶ 다시 보기)
  • 계정(게스트/디스코드, 내 게임 기록 목록 + [다시 보기])
  • 다시 보기(/replay/:gamePk: 판은 읽기 전용, 처음/이전/재생·멈춤/다음/끝 + 슬라이더. PC는 오른쪽 칸, 폰은 아래 고정 막대. 못 보는 게임은 안내 문구, docs/09 §8)
  • 오류(방 없음, 방 가득 참, 서버 업데이트, 오프라인)

11. PWA (홈 화면 추가·오프라인 안내)

  • 매니페스트 /manifest.webmanifest: 이름 "같이 놀자 보드게임", 짧은 이름 "같이 놀자", lang: ko, 시작 /, display: standalone, 테마·배경 #F7F5F0(--bg). 아이콘은 "게임천국" 느낌의 게임패드 + 천사 고리 + 반짝이(보라→분홍→주황 배경). public/icons/: 192·512(favicon 그대로, 둥근 모서리), 512 maskable(가득 채움, 그림은 가운데 안전 영역 안), apple-touch-icon 180. favicon.svg와 PNG 모두 bun scripts/pwa-icons.ts가 한 디자인에서 만든다(Chrome으로 그림).
  • 서비스 워커: 손으로 쓴 apps/web/sw.js를 빌드 때 Vite 플러그인이 빌드 ID(파일 이름 해시 기준)를 넣어 dist/sw.js로 낸다. 배포 빌드에서만 등록한다(개발 서버에서는 등록 안 함).
요청 처리
페이지 이동(navigate) 네트워크 먼저, 저장하지 않음. 네트워크 오류면 /offline.html
/assets/* (해시 파일) 캐시 먼저(bg-assets-v1, 200개까지, 오래된 것부터 지움). 200 응답이고 HTML이 아닐 때만 저장(없는 파일은 서버가 index.html을 돌려주므로)
/api/*(관리자 API 포함), /ws, /healthz, /internal/*, 다른 출처, GET 아닌 요청 손대지 않음(저장 안 함)
  • 캐시: bg-shell-<빌드ID>(오프라인 안내 페이지 하나)와 bg-assets-v1. 새 워커는 바로 활성화(skipWaiting + clients.claim)하고, 활성화할 때 이 둘이 아닌 bg-* 캐시를 지운다. index.html은 어디에도 저장하지 않으므로 온라인이면 새 배포가 바로 보인다. 해시 파일은 내용이 바뀌지 않아 배포 뒤에도 남겨 둔다. 워커의 저장 방식을 바꾸면 bg-assets-v1의 숫자를 올린다.
  • 오프라인 안내 페이지: 다른 파일 없이 혼자 그려지는 HTML(인라인 스타일, 밝게/어둡게). 스크립트는 없다(CSP가 인라인 스크립트를 막음). [다시 시도]는 같은 주소를 다시 연다. 자동 새로고침(meta refresh)은 접근성 검사(axe) 위반이라 쓰지 않는다.
  • 앱 안: 인터넷이 끊기면 ConnectionBanner가 위쪽 띠로 알린다(방 안에서는 기존 재연결 문구).
  • 홈 화면에 추가: 홈 아래쪽 카드. beforeinstallprompt를 잡아 [추가하기] 버튼을 보이고, iOS(이 이벤트 없음)는 "공유 버튼 → [홈 화면에 추가]" 안내만. 이미 앱으로 열었거나(standalone) [닫기]를 누르면(기기에 기억) 안 보인다.
  • 서버: /sw.js·/manifest.webmanifest·/offline.html은 index.html과 같이 no-cache, manifest는 application/manifest+json(Bun 기본). CSP default-src 'self'가 워커·매니페스트를 허용해 따로 넣은 것은 없다.
  • 확인: apps/web/src/sw.test.ts(캐시 규칙), bun e2e/pwa.e2e.ts(매니페스트·아이콘, 워커 활성화, 오프라인 띠·안내 페이지, 다시 온라인, 설치 카드, 업데이트 팝업).

11.1 업데이트 알림 (2026-10-11)

  • 사이트가 업데이트되면 열려 있는 페이지 위쪽 가운데에 카드가 뜬다: "업데이트 내용이 있습니다." [지금 새로고침하기] [✕]. ✕를 누르면 닫히고, 그다음 업데이트가 나올 때까지 다시 뜨지 않는다(새로고침하면 새 빌드라 안 뜸). 모든 화면에 보인다(UpdateBanner, apps/web/src/lib/update.ts).
  • 빌드 ID: 빌드할 때 Vite 플러그인(buildId, vite.config.ts)이 만든 파일 이름들의 해시 12자리를 index.html의 <meta name="bg-build">에 넣는다. 스크립트·스타일이 하나라도 바뀌면 달라지고, 서버 코드만 바뀐 배포에는 뜨지 않는다.
  • 서버는 시작할 때 dist/index.html에서 그 값을 읽어(webBuildId) GET /api/version(no-store)과 소켓 welcome.build로 알린다. 페이지는 5분마다, 탭이 다시 보일 때, 소켓이 (다시) 연결될 때 비교한다. 배포로 서버가 다시 켜지면 소켓이 다시 연결되면서 바로 뜬다.
  • 프로토콜 번호가 다를 때(예전 방 화면의 "새 버전이 있어요")도 같은 카드를 쓴다. 개발 서버에는 빌드 ID가 없어 뜨지 않는다.