시나리오: 프론트엔드 팀
UI 팀에서 하네스가 어떻게 브라우저 QA, 접근성, 디자인 규칙을 엔지니어링 시스템으로 만드는지 설명합니다.
핵심 요약
- 프론트엔드 하네스에서 중요한 건 코드 정확성보다 보이는 상태와 상호작용을 일관되게 검증하는 일입니다.
- browser QA, visual/interaction 체크리스트, design rules 문서, accessibility gate가 load-bearing 요소입니다.
- task contract에 must_render(desktop/mobile/empty/error)와 must_verify(키보드, focus trap, 스크린리더 라벨)를 명시합니다.
- checkout·pricing·auth 화면 변경은 human_gate로 두고, 문구 수정·storybook 예제는 auto로 분리합니다.
- 30일 도입은 자주 깨지는 화면 2개의 browser QA 템플릿부터 시작해 design-rules와 a11y-checklist를 분리합니다.
프론트엔드 팀의 하네스는 대개 "코드를 바르게 쓰는가"보다 보이는 상태와 상호작용을 얼마나 일관되게 검증하느냐에서 갈립니다.
문제 구조
- 코드는 맞아 보여도 실제 브라우저에서 깨질 수 있음
- 모바일/데스크톱/다크모드/빈 상태/에러 상태가 자주 누락됨
- 디자인 시스템 규칙이 코드 리뷰에서만 늦게 드러남
- a11y 회귀가 구현 단계에서는 잘 안 보임
load-bearing 하네스 요소
| 요소 | 왜 중요한가 |
|---|---|
| browser QA | 텍스트 기반 self-check가 놓치는 상태를 잡음 |
| visual / interaction checklist | "렌더링 됨"과 "사용 가능함"을 구분 |
| design rules 문서 | spacing, typography, component invariant를 고정 |
| accessibility gate | 키보드, 포커스, 명도, 라벨 회귀 방지 |
권장 루프
코드 diff만 봐서는 실제 품질을 판정할 수 없습니다. 프론트엔드에서 이 루프가 중요한 이유입니다.
아티팩트 구조 예시
design-rules.md
interaction-states.md
a11y-checklist.md
ui-task-contract.yaml
browser-qa-report.md
visual-regression-notes.md
task contract 예시
ui_change:
goal: "검색 패널 상호작용 개선"
must_render:
- "desktop"
- "mobile"
- "empty state"
- "error state"
must_verify:
- "keyboard navigation"
- "focus trap"
- "screen reader label"
non_goals:
- "검색 API 변경"
escalation:
- "design token 추가 필요"왜 이게 엔지니어링인가
프론트엔드 하네스는 사실상 UI state-space management입니다.
- 어떤 상태를 보여야 하는지 정의합니다.
- 어떤 상태를 반드시 검증해야 하는지 고정합니다.
- 브라우저 검증을 완료 정의에 넣습니다.
- 디자인 시스템 규칙을 사람이 기억하지 않도록 외부화합니다.
감각 좋은 프론트엔드 개발자의 머릿속에만 있던 체크리스트를 시스템으로 내려놓는 작업입니다.
approval / handoff 예시
frontend_approval:
auto:
- "문구 수정"
- "storybook 예제 추가"
review_required:
- "사용자 노출 UI 변경"
- "design token 변경"
human_gate:
- "checkout / pricing / auth 화면 변경"자주 망하는 패턴
| 실패 패턴 | 하네스로 막는 방식 |
|---|---|
| 데스크톱만 보고 완료 처리 | must_render에 모바일/빈 상태 강제 |
| 클릭은 되지만 키보드 접근 불가 | a11y checklist와 keyboard QA 분리 |
| 디자인 시스템 규칙 위반 | design-rules.md + review rubric |
| 브라우저 확인 없이 ship | browser QA를 release gate로 승격 |
30일 도입 순서
- 자주 깨지는 화면 2개를 골라 browser QA report 템플릿을 만든다.
design-rules.md와a11y-checklist.md를 분리한다.- UI 변경은 최소한
browser + keyboard + empty/error state를 통과하도록 고정한다.