Gotchas
-
코드 품질 평가 금지 — 아키텍처, 성능, 코드 스타일을 평가하지 마라. 디자인 원칙 준수 여부만 판정한다.
-
토큰 미사용 FAIL 남발 금지 — 디자인 토큰이 없는 프로젝트에서 "토큰 미사용"으로 FAIL을 남발하지 마라. 토큰 체계가 없으면 design-system 스킬 사용을 권장하는 NOTE로 남겨라.
-
접근성 카테고리 필수 — 시각적으로 문제없어 보여도 반드시 검사한다: contrast ratio(WCAG 2.2 AA 4.5:1), 터치 타겟, 포커스 인디케이터, 폼 라벨 연결, WCAG 2.2 신규 SC(Focus Not Obscured 2.4.11 AA, Dragging Movements 2.5.7 AA, Accessible Authentication Min 3.3.8 AA). 생략하면 REJECT.
터치 타겟 기준 정리 (2026-04-11 갱신):
- WCAG 2.2 SC 2.5.8 Target Size (Minimum) — AA = 24×24 CSS px (예외: sufficient spacing / inline text / user-agent / essential)
- WCAG 2.2 SC 2.5.5 Target Size (Enhanced) — AAA = 44×44 CSS px
- Apple HIG 44pt = 터치 디바이스 실용 권장치 (플랫폼 가이드라인)
기존 리포트에서 "44×44pt"만 명시하면 독자가 "WCAG AA 요구"로 오독할 수 있으니, AA/AAA/플랫폼 권장을 구분하여 기재한다. 출처: W3C WCAG 2.2 SC 2.5.8, W3C What's New in WCAG 2.2.
-
AI 안티패턴 검사 포함 — Authenticity 카테고리를 반드시 포함하라. 균일 border-radius, 제네릭 보라-파랑 팔레트, 동일 구조 반복, 목적 없는 장식 효과는 FAIL 사유다.
-
심각도 분류 필수 — FAIL 항목마다 심각도를 표기한다:
Critical(접근성·윤리),Major(위계·일관성),Minor(세부 조정). 심각도 없는 FAIL 리포트는 불완전하다. -
주관적 판정 금지 — "보기 좋다", "이 정도면 괜찮다"는 근거가 될 수 없다. 모든 PASS/FAIL은 audit-criteria.md에 정의된 원칙과 수치 기준에 근거해야 한다.
-
상태/예외 화면 포함 — 기본 화면만 검사하지 마라. 빈 상태, 에러 상태, 로딩 상태, 데이터 과다/과소 상태가 코드에 존재하면 함께 검사한다.
-
코드 미확인 항목 구분 — 런타임 렌더링, 실제 인터랙션처럼 정적 분석으로 판정 불가한 항목은 PASS/FAIL이 아닌
[미검증]으로 표기하고 수동 확인 방법을 안내한다. -
휴리스틱-카테고리 혼동 금지 — Nielsen 10 휴리스틱은 평가 관점 프레임이다. 실제 판정은 반드시 audit-criteria.md의 10개 카테고리 기준(Typography, Color, Spacing, Accessibility, Interaction, Motion, Visual Hierarchy, Layout & Grid, Ethical Design, Authenticity)으로 매핑하여 수행한다.
-
Rule-by-Rule Audit — 완료 선언 전 10 카테고리 전수 대조 — APPROVE/REJECT 판정 전에 audit-criteria.md 의 10 카테고리 × 핵심 체크포인트를 모두 순회하며 각 항목에
PASS / FAIL / [미검증]을 명시한 표가 리포트에 포함되어야 한다. 일부 카테고리를 "해당 없음" 으로 뭉뚱그리지 말고 이유를 기재하라. 카테고리를 건너뛴 감사는 감사가 아니다 (skill-design-guide §3.6 Rule-by-Rule Audit 대응). -
Binary Decidability Pre-Check — 감사 시작 전 이진 판정 가능성 확인 — 감사 범위를 정한 뒤 각 예상 FAIL 항목이 "코드/스타일/토큰만으로 PASS/FAIL 이 이진 판정 가능한가" 를 먼저 체크한다. 런타임 렌더링 · 실제 인터랙션 · MCP Figma 대조가 필요한 항목은 즉시
[미검증]으로 분류하고 PASS 로 통과시키지 마라. 미검증은 두 카운터로 센다 —invalid_evidence([미검증:INVALID]· 접미 없는[미검증])는 0 건 통상 판정, 1 건 PASS 허용 + 경고 명시, 2 건 이상은 개별 FAIL 이 없어도 REJECT 다. 4 요건을 다 채운[미검증:ENV]는env_gaps로 따로 세어 REJECT 셈에 넣지 않고,verified_coverage가 0.60 미만이면 BLOCKED 다. 이 규칙은harness/docs/guides/qa-evaluation-guide.md§Canonical Unverified-Evidence Protocol 의 「임계값 2 는」 조항이 정본이며 여기서 다시 정의하지 않는다. design-reviewer 규칙 8 사본과 같은 값이어야 한다 (agent-design-guide §3.5 Binary Decidability 대응 · skill 측 반영). -
Evidence Validity Gate — "증거가 있다" 와 "증거가 입증한다" 는 다르다 — Gotcha 11 이 증거를 얻을 수 있는가를 다룬다면 이 항목은 증거는 얻었는데 그것이 아무것도 입증하지 못하는 경우를 다룬다. PASS 를 확정하기 전 4 검사를 통과시켜라. 하나라도 실패하면 PASS 가 아니라
[미검증]이다.# 검사 실패 예 (감사 맥락) 1 비공백 0 바이트 스냅샷, 에러만 담긴 로그를 근거로 인용 2 활성화 대비 검사 대상 텍스트 노드 0 개인데 "대비 위반 없음 PASS" 3 반증 가능성 어떤 코드에도 같은 결과를 내는 grep 을 oracle 로 사용 4 출처 구현자 주석·커밋 메시지의 "접근성 확인함" 을 근거로 채택 0 매치 판정 —
grep0 건은 두 가지다. 의도된 0(대상 파일 수를 먼저 세고, 패턴이 다른 위치에서 매치됨을 확인한 뒤의 0)만 PASS 근거가 된다. 공허한 0(경로 오류·빈 파일·절대 매치 안 되는 패턴)은 측정 실패이며[미검증]이다. 근거 문장에대상 N 파일 · 패턴 유효성 확인 · 매치 0형태로 셋을 함께 적어라.렌더 산출물 특칙 — 빈 화면·빈 목록·플레이스홀더만 있는 캡처는 PASS 증거가 아니라 검증 실패 신호다. 캡처를 근거로 쓸 때는 조건이 요구하는 구체 요소를 지목하라. 지목할 수 없으면 무효 증거다. 캡처마다
../../references/visual-change-protocol.md§3 캡처 점검 목록(넘침 · 깨진 글리프 · 칩·뱃지와 줄 모양 · 디버그 겹침)을 보고, 하나라도 걸린 캡처는 PASS 근거로 쓰지 않는다. 출처:harness/docs/guides/qa-evaluation-guide.md§Evidence Validity Gate. -
Before/After 대조 감사 — 의도 외 영역 변화는 FAIL — 변경분(
git diff기준)을 감사할 때는 정적 상태만 보지 말고 요청 범위와 실제 변경 범위를 대조하라. 요청이 특정 시각 속성 하나를 지목했는데(보더만·색만·간격만) 같은 요소의 background / fill / radius / shadow / spacing / typography 가 함께 변했다면MajorFAIL 이다. 승인된 시안·기존 앱 색상이 있는데 프로젝트 토큰이나 기본 팔레트로 치환됐다면MajorFAIL 이다 (우선순위 위반). 감사 리포트는EVIDENCE블록(before / after / proof / 의도 외 영역)으로 닫는다. 상세:../../references/visual-change-protocol.md. -
Decision Propagation Coverage — 확정 결정이 일부 표면에만 적용된 것은 Major FAIL —
.design/decisions.yaml이 있으면 10 카테고리 감사에 앞서 커버리지를 판정한다 (카테고리를 늘리지 않는다 — 전제 조건 검사다).status: approved인decision_id마다required_surfaces[]를 순회해 (a) golden 도 user-visible assertion 도 없으면 FAIL (b) golden 만 있고 visible/count/height assertion 이 없으면 FAIL (c)excluded_surfaces에 이유 없이 빠진 표면은 커버리지 공백이므로 FAIL 이다. 심각도는Major, 접근성·윤리 결정이면Critical이다.status: superseded(대체됨) 결정은 화면 자리를 판정하지 않고,superseded_by가 같은 목록의 다른approved결정을 가리키는지만 본다. manifest 자체가 없으면 FAIL 이 아니라NO_MANIFEST로 보고하고 감사 범위에서 제외한다 — 대상 0 건과 통과는 다르다. 스키마·규칙 4 조·실행 가능한 체커:../../references/visual-change-protocol.md§6 Decision Propagation Manifest. -
증거 채널을 명시하라 —
artifact_snapshot으로 앱 화면을 판정하지 마라 — 근거로 인용하는 모든 증거에 채널 이름(artifact_snapshot/dom_snapshot/browser_user_visible/device_user_visible)을 붙인다. PASS 문장에는 viewport · route/state · visible locator · count/height · screenshot/golden id 5 요소가 있어야 하며, 하나라도 없으면 PASS 가 아니라[미검증]이다. 채널 정의:../../references/visual-change-protocol.md§7 Evidence Channels. 사용자 실패 보고와 자기 증거가 충돌할 때의 규약은harness/docs/guides/skill-design-guide.md§3.8 ·harness/docs/guides/agent-design-guide.md§10 이 정본이며 여기서 재정의하지 않는다 — 감사 리포트로 사용자 관측을 반박하지 마라.
Process
Step 1: 대상 범위 및 모드 결정
사용자가 지정한 경로와 모드를 기준으로 감사 범위를 결정한다:
- 파일 경로 → 해당 파일만
- 디렉토리 경로 → 하위 UI 관련 파일 전체
- 미지정 → 최근 변경된 UI 파일 (git diff 기준)
모드:
quick(기본) — 전체 10개 카테고리를 빠르게 검사. Critical/Major FAIL에 집중.deep— 상태/예외 화면, 반응형 breakpoint, 다크 모드, 접근성 세부 항목까지 전수 검사.
Step 2: 감사 카테고리 확인
10개 카테고리를 순서대로 검사한다. 각 카테고리의 핵심 체크포인트:
| 카테고리 | 핵심 체크포인트 | 심각도 기준 |
|---|---|---|
| Typography | 타이포 스케일 일관성, 행간(문자 체계별 범위 — references/audit-criteria.md 행간 비율 행), 본문 최소 14px(모바일)/16px(웹) | Major |
| Color | 텍스트 대비 WCAG 2.2 AA 4.5:1, 시맨틱 토큰 사용, 다크모드 대비 유지, OKLCH/P3 wide gamut 사용 시 sRGB fallback 확인. APCA Lc 참조(informational): 본문 Lc 75~90, 비본문 Lc 60 이상, Lc 15 미만은 비가시. APCA는 폰트 크기+굵기별 차등 대비를 요구하므로 가는 폰트에 더 높은 대비 필요. 판정 기준은 WCAG 2.2 AA이며 APCA는 WCAG 3.0 WD 참고용 | Critical(대비) / Major(토큰) |
| Spacing | 스페이싱 스케일 일관성, 터치 타겟 WCAG 2.2 SC 2.5.8 AA ≥24×24 CSS px (AAA SC 2.5.5 = 44×44), 그룹 간/내 여백 위계 | Critical(터치) / Major(스케일) |
| Accessibility | 색상만으로 상태 전달 금지, 포커스 인디케이터, 폼 라벨, 대체 텍스트, WCAG 2.2 SC 2.4.11 Focus Not Obscured (AA), SC 2.5.7 Dragging Movements (AA), SC 3.3.8 Accessible Authentication Min (AA) | Critical |
| Interaction | 액션 피드백, 로딩 인디케이터, 에러 표시, 취소/되돌리기 경로, 드래그 전용 UX 시 single-pointer 대체(WCAG 2.2 SC 2.5.7) | Major |
| Motion | 애니메이션 목적성, 듀레이션 200~500ms, prefers-reduced-motion 대응 | Major |
| Visual Hierarchy | 제목/본문/캡션 비율 차이, 핵심 콘텐츠 대비 강조, 그룹 여백 분리 | Major |
| Layout & Grid | 그리드 정렬, 거터 일관성, 주요 breakpoint 반응형 전략, 컴포넌트 수준 반응형은 container-type: inline-size + @container 권장 (크기 쿼리 지원: Chrome 105 · Firefox 110 · Safari 16). Container Queries 체크: 페이지 레벨 분기는 media queries, 컴포넌트 레벨 분기는 container queries 사용 여부 확인. cqw/cqi 유닛 활용, 콘텐츠가 깨지는 지점 기반 breakpoint 설정 권장 (디바이스 타겟 X) | Major |
| Ethical Design | 다크 패턴 12유형 부재, 동의 명시성, 가입·탈퇴 경로 대칭성 | Critical |
| Authenticity | 동일 구조 3회 이상 반복, 제네릭 팔레트, 목적 없는 장식, 범용 카피, 같은 역할 기존 화면과 관례 불일치 | Minor~Major |
Step 3: design-reviewer 에이전트 호출
Agent 도구를 사용하여 design-reviewer 서브에이전트를 생성한다:
Agent 도구 호출:
- subagent_type: design-reviewer
- prompt: "다음 파일을 디자인 원칙 기준으로 [quick|deep] 모드로 평가하라: [대상 파일 목록]"
에이전트가 읽기 전용으로 분석 후 카테고리별 PASS/FAIL/미검증 결과를 반환한다.
Step 4: 리포트 포맷팅
에이전트 결과를 templates/audit-report.md 포맷으로 정리한다.
각 FAIL 항목에 반드시 포함:
- 파일:라인 위치
- 심각도 (
Critical/Major/Minor) - 위반한 원칙 (출처 포함)
- 구체적 개선 방향 (스택 무관 수준)
미검증이 1 건 이상이면 리포트에 유효성 집계를 함께 싣는다 (Gotcha 12):
## Evidence Validity
- 검사 대상 증거: {{n}} 건
- 무효 판정: {{k}} 건 [항목 ID — 실패한 검사 번호 — 사유]
- 미검증 누계: `invalid_evidence` {{a}} 건 / `env_gaps` {{b}} 건 / `verified_coverage` {{c}}
Step 5: 최종 판정
- FAIL 0 +
invalid_evidence0 +verified_coverage0.60 이상 + L3 10/10 → APPROVE (env_gaps수를 적는다) - Decision Propagation Coverage FAIL 1 개 이상 → REJECT (10 카테고리 판정과 별개의 전제 조건 —
Gotcha 14. manifest 부재는 FAIL 이 아니라
NO_MANIFEST보고다) - 결정 전파 검사 종료 코드 2(
SCHEMA_ERROR)는 입력 모양이 틀려 판정하지 못한 것이라 REJECT 다 —FAIL줄 없이violations=0이 찍혀도 통과로 읽지 않는다. 종료 코드 3(NO_SURFACE·NO_DECISION)은NO_MANIFEST와 같이 대상 0 건으로 보고한다 - Critical FAIL 1개 이상 → REJECT (즉시)
- Major/Minor FAIL만 있음 → REJECT + 우선순위별 개선 목록
- FAIL 0 이지만
invalid_evidence2 건 이상 → REJECT (Gotcha 11 임계값) - FAIL 0,
invalid_evidence2 건 미만,verified_coverage = (판정한 체크 항목 수 − env_gaps) / 판정한 체크 항목 수< 0.60 → BLOCKED (insufficient_verified_coverage— 재검증 명령을 돌린 뒤 재감사) - FAIL 0 이어도 L3 커버리지 < 10/10(10 카테고리 중 건너뛴 카테고리가 있음) → REJECT + 남은 카테고리 명시 (건너뛴 카테고리는 FAIL 이다 — 리뷰어 규칙 11)
- FAIL 0,
invalid_evidence1 건,verified_coverage0.60 이상, L3 10/10 → APPROVE + 미검증 항목과 수동 확인 방법 명시
REJECT 리포트 구조:
- Critical FAIL 목록 (즉시 수정 필요)
- Major FAIL 목록 (다음 스프린트 전 수정)
- Minor FAIL 목록 (개선 권장)
- [미검증] 항목 (수동 확인 필요 —
[미검증:ENV]/[미검증:INVALID]구분)
변경분 감사(git diff 기준)인 경우 리포트를 EVIDENCE 블록으로 닫는다 (Gotcha 13):
## EVIDENCE
- before: [변경 전 상태 근거 — 파일:라인 또는 캡처]
- after: [변경 후 상태 근거]
- proof: [판정을 뒷받침하는 명령과 출력]
- 의도 외 영역: [변화 없음 확인 근거 / 또는 FAIL 처리한 항목]
References
references/audit-criteria.md— 카테고리별 감사 기준 상세templates/audit-report.md— 리포트 출력 포맷../../references/visual-change-protocol.md— 시각 변경 우선순위 · 부분 변경 격리 · 증거 블록 · §6 Decision Propagation Manifest · §7 Evidence Channels (SSOT)harness/docs/guides/skill-design-guide.md§3.8 ·harness/docs/guides/agent-design-guide.md§10 — 사용자 실패 보고 우선순위 규약의 정본harness/docs/guides/qa-evaluation-guide.md§Canonical Unverified-Evidence Protocol · §Evidence Validity Gate — 미검증 임계값·유효성 4 검사 정본