라이브 /quiz 검증 런북 작성 (UI 221·a11y 222/223·UX 224)
요약Sprint 221~224로 코드측 완성된 CS 퀴즈(/quiz)의 UI 개편(221)·접근성(222/223)·UX 심화(224)는 merge≠라이브(빌드 자동/롤아웃 수동 ops)라 라이브 육안·스크린리더 검증이 매 스프린트 이월돼 왔다. 라이브 /quiz는 미들웨어상 로그인 필수(PUBLIC_PATHS 제외)이고 롤아웃도 수동이라 에이전트 자율 라이브 구동이 불가하므로, 검증을 1회성 수동 작업이 아니라 repo 영속 절차서로 산출했다. 신규 런북 docs/runbook/quiz-ui-verification.md를 작성 — §0 전제조건(로그인 필수·merge≠라이브·검증 매트릭스) / §1 UI(분야 5색+아이콘·난이도 semantic·3화면 애니메이션·피드백 톤·Trophy) / §2 a11y(단계 전환 포커스·progressbar 시맨틱·sr-only 라이브 공지) / §3 UX(PillRadioGroup 키보드 네비·통계 막대·전환 모션·reduced-motion) / §4 i18n(ko↔en) / §5 결과 기록 템플릿. 모든 항목에 파일:라인 출처를 붙여 검증자가 라이브에서 무엇을 확인할지 도출 가능. 코드 변경 0(순수 docs). Critic 교차 리뷰로 출처 정확성 확인.
목표
- Sprint 221~224로 코드측 완성·검증된 CS 퀴즈(
/quiz)의 UI 개편(221)·접근성(222/223)·UX 심화(224)를 라이브에서 사람이 검증할 수 있는 사실 기반 절차서를 산출한다. - 매 스프린트 이월돼 온 "재배포 후 라이브 /quiz 검증"을 1회성 수동 작업이 아니라 repo 영속 런북으로 고정해 향후 quiz UI 변경마다 재사용 가능하게 한다.
- 순수 docs — 서비스/프론트 코드 무변경.
배경
Sprint 221~224는 quiz /quiz를 다음과 같이 개선·머지했다:
- 221: 분야별 accent 색 토큰(
--quiz-cat-*) + lucide 아이콘 도입, 3화면 재설계 - 222/223: 단계 전환 포커스 관리, progressbar 접근 이름/
aria-valuenow(223에서 공통 래퍼 전역 정석화), 결과 신기록 sr-only 라이브 공지 - 224: PillRadioGroup radiogroup 키보드 네비, "내 기록" 분야별 통계 막대, 전환 모션
그러나 이 프로젝트의 배포 모델은 merge ≠ 라이브다(이미지 빌드는 머지 시 자동, 롤아웃은 수동 ops). 그 결과 "재배포 후 라이브 육안·스크린리더 검증"이 221→222→223→224 내내 이월 항목으로만 누적됐다.
검증을 막는 두 제약:
- 라이브
/quiz는 로그인 필수 —frontend/src/middleware.ts의PUBLIC_PATHS(26~34행)에/quiz가 없어 미인증 시/login으로 307 리다이렉트. 에이전트는 비밀번호 입력이 금지(안전 규칙)라 자율 로그인 불가. - 롤아웃은 수동 ops — 에이전트가 재배포 불가.
따라서 에이전트가 라이브를 직접 구동해 검증하는 것은 불가능하고, 사람(사용자/운영)이 라이브에서 실행할 정확한 절차서가 가장 현실적이고 repo에 영속하는 산출물이다. 기존 docs/runbook/sp217-quiz-records-cutover.md는 기록 컷오버 + 기능 E2E 6항목만 다루고 221~224의 시각·접근성·UX 검증은 미커버 — 이 갭을 메운다.
결정
D1. 라이브 검증을 repo 영속 런북으로 산출
docs/runbook/quiz-ui-verification.md를 신규 작성한다. 구조:
- §0 전제조건:
/quiz로그인 필수(미들웨어 근거 + curl 307 예시), merge≠라이브, 검증 매트릭스(테마 라이트/다크 · 로케일 ko/en · 입력 마우스/키보드/스크린리더) - §1 UI(221): 분야 5색 표(라이트/다크 hex) + lucide 아이콘 매핑, 난이도 semantic 재사용, 3화면 애니메이션 표, 피드백 정답/오답 톤 + 신기록 Trophy
- §2 a11y(222/223): 단계 전환 포커스 이동(피드백→다음, 결과→다시하기), progressbar 시맨틱(Radix 자동 ARIA + QuizPlay aria-label/valuetext), 결과 신기록 sr-only
role=status aria-live=polite공지 - §3 UX(224): PillRadioGroup 3그룹 radiogroup 키보드(화살표/Home/End/roving tabindex), QuizStats 통계 막대(progressbar 시맨틱·내림차순), 전환 모션 + reduced-motion 존중
- §4 i18n: ko↔en 핵심 라벨/공지 대조표
- §5 결과 기록 템플릿: PASS/FAIL/N/A 표 + 발견 이슈 → 후속 시드 양식
D2. 모든 검증 항목에 파일:라인 출처 명시
추측 0 원칙. 각 기대값은 실제 코드 출처(frontend/src/components/quiz/*, globals.css, category-meta.ts, messages/*/quiz.json, middleware.ts)와 라인 번호로 뒷받침한다. Critic 교차 리뷰가 출처 정확성을 검사한다.
D3. 코드 변경 0
순수 docs 스프린트. frontend/services 무변경 → 코드 게이트(jest/tsc/lint/coverage) 영향 없음.
구현
총 atomic commit (start 544ac8d):
| 커밋 | 에이전트 | 내용 |
|---|---|---|
| (runbook) | Librarian | docs/runbook/quiz-ui-verification.md 신규 (§0~§5, 파일:라인 출처 포함) |
| (ADR) | Librarian | ADR sprint-226 KR+EN + docs/adr/README.md 인덱스 163→164 |
검증
- 출처 정확성: 런북 작성 전 핵심 출처 11종(globals.css quiz-cat 변수·keyframe, category-meta 아이콘, QuizStart DIFFICULTY_TONE, QuizPlay Progress aria, QuizFeedback/QuizResult 포커스·role·announce, PillRadioGroup 키보드/role, QuizStats progressbar, QuizQuestion 모션, middleware PUBLIC_PATHS, i18n 키)을 현재 코드와 직접 대조해 라인 번호 검증.
- ADR 게이트: index count(sprint 164, --strict) / adr-en coverage(KR/EN 1:1) / adr-links 0 broken / doc-refs no broken.
- CI: PR 게이트 통과 후 Squash 머지. 문서 전용이라 코드 게이트 무영향.
- Critic: R1 CLEAN — codex(gpt-5.5)가 참조 소스 파일을 직접 읽고 ADR/런북 내용이 일치함을 확인, actionable issue 0.
Critic 교차 리뷰
- 도구: Codex codex-cli 0.130.0,
codex review --base 544ac8d -c model=gpt-5.5 - 라운드: 1
R1 — CLEAN (P-finding 0): "The changes are documentation-only and the added ADR/runbook content is consistent with the referenced source files and existing ADR checks. I did not find any actionable issue that would break existing code, tests, or documented workflows." (codex가 frontend/src/components/quiz/* 등 참조 소스를 직접 읽고 런북 출처와 대조)
종합 판정: ✅ 머지 가능 — 문서 전용, 런북/ADR 내용이 참조 소스 파일 및 기존 ADR 게이트와 일치, 회귀 0. 단일 라운드 CLEAN.