Files
clean-architecture-frontend…/docs/accessibility/manual-checklist.md
T
DongHyeonka c4d587052e fix(removal): 참조 기능을 지워도 문서 게이트가 통과하고 드릴이 그것을 본다
문제
README는 참조 기능을 지울 수 있다고 적는다. 그러나 매뉴얼·입구 문서
10개가 참조 기능과 그 드릴 전용 파일의 경로를 백틱으로 적고,
verify:documentation(FE-GATE-017)은 백틱 경로의 존재를 검사한다. 그래서
참조 기능을 지운 복사본에서 문서 게이트가 경로 24개로 실패한다. 제거
드릴(test:sample-removal)은 문서를 복사하지 않고 그 게이트와 lint·
check:i18n·check:design-system을 돌리지 않아 이 충돌을 보지 못했다.

고른 방법
- 리뷰 5.2절 (b): 참조 기능이 가진 경로는 백틱 없이 "예제(참조 기능)"으로
  적는다. 기능 공통 모양은 생성 경로 꼴(`src/features/<id>/domain`)로
  적는다. 규칙은 docs/manual/reference/patterns.md 첫머리에 적었다.
- 드릴은 REMOVAL_FIXTURE_DOCUMENT_TARGETS(README·CHANGELOG·docs)까지
  복사하고, 지운 뒤와 생성 기능을 더한 뒤 두 번 모두 lint,
  verify:documentation, check:i18n, check:design-system을 돈다
  (FOLLOW-UP 09-07). 문서 테스트 두 개도 fixture에서 다시 돈다.
- 버린 대안: 검사기가 참조 기능 경로를 "없어도 되는 경로"로 보기(5.2
  (c)). 매뉴얼이 없는 파일을 가리키는 상태를 허용한다. 참조 기능을 지울
  수 없게 하기(5.2 (d)). README 약속과 드릴의 존재 이유가 바뀐다.

위험·한계
- 템플릿 자신에서도 참조 기능 경로의 존재를 문서 검사가 더는 보지
  않는다. 참조 기능 파일 이름을 바꾸면 그 문장은 사람이 고쳐야 한다.
- 드릴 시간이 lint·문서 검사 두 번만큼 는다.
- 드릴 실제 실행 결과는 이 커밋 메시지에 적지 않았다(공유 잠금 대기).

검증
- 참조 기능·참조 context·SAMPLE_EXTRAS를 지운 복사본(scratchpad
  sim-sample-docs.sh)에서 수정 전 FAIL_UNVERIFIED(문서 10개), 수정 뒤
  PASS_SCOPED.
- 저장소에서 verify:documentation PASS_SCOPED,
  documentation-readiness 14건 통과, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
2026-11-04 21:02:14 +09:00

3.2 KiB

Manual accessibility review checklist

Automated axe checks do not establish WCAG conformance. A human reviewer must review every route record in artifacts/tests/a11y-manual/ against one release candidate and sign them. The required scope is the route registry (ROUTE_REGISTRY in src/features/installed-feature-contracts.ts): one record per route, named <ROUTE_ID>.md. Copy the template fields exactly; the gate rejects blank identity/timestamp/signature fields, pending verdicts, mismatched release IDs, or missing routes.

The signed review is the release gate FE-GATE-028 (review:a11y-manual), so it is required once per release candidate, not on every merge. The merge gate FE-GATE-009 runs review:a11y-manual -- --format-only: each record must keep the fields below with pending, pass or not-applicable (<reason>) verdicts, and a record marked reviewed must be complete.

This document keeps no route list. A list here once said six routes while ten were registered, and keeping it current made every new feature edit this file. Instead verify:documentation fails, naming the route ID, when a registered route has no record file. A new route starts from a copy of a pending record with its title and Route ID changed.

Allowed item verdicts:

  • pass
  • not-applicable (<specific reason>)

Required record:

Status: reviewed
Route ID: APP_HOME
Release ID: <immutable release ID>
Reviewer: <human reviewer identity>
Reviewed at: <RFC 3339 timestamp>
Signature: <reviewer identity or approved signature reference>
Attestation: accepted
M1 Keyboard: pass
M2 Visible focus: pass
M3 Route focus: pass
M4 Modal focus: not-applicable (no modal on this route)
M5 Error association: not-applicable (no form error on this route)
M6 Color signal: pass
M7 Reduced motion: pass
Screen reader: pass
Notes: <observations and linked defect IDs>

The reviewer must verify:

  • M1: every action works without a pointing device
  • M2: every focused element has a visible indicator
  • M3: route transitions move focus to a deterministic target
  • M4: modal focus is trapped and restored, when a modal exists
  • M5: errors are programmatically associated with their controls, when present
  • M6: state never relies on color alone
  • M7: non-essential motion is suppressed with reduced-motion preference
  • Screen reader: headings, live regions, errors, and actions are announced once

EXAMPLES_UI requires real M4 modal and M5 field-error review; those items must not be marked not-applicable on that route. Passing automated evidence means only that tested pages had no critical or serious axe findings under the recorded Chromium, Firefox, and WebKit runs.

What the automated run scans:

  • Every registered route, after the route's own h1 is on screen, so the scan never lands on the app shell's loading surface (tests/e2e/accessibility.spec.ts). A public route's h1 must equal its catalog title.
  • Protected routes after the demo sign-in, never the sign-in prompt. Their API calls answer an empty list there.
  • The reference sample's list in its success, empty and error states, its detail, its form with submit errors and its status page, each after that state is on screen (tests/e2e/reference-form.spec.ts, removed with the sample).