Files
clean-architecture-frontend…/docs/accessibility/manual-checklist.md
T
DongHyeonka 1dda18da30 fix(docs): 참조 기능 경로를 다시 백틱으로 적어 문서 검사가 본다
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.

고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
  README, starter-experience, static-delivery, compatibility,
  backend-api-and-server-state-contract, manual-checklist,
  adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
  참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
  적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
  1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
  지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
  measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
  안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
  위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
  and scripts only where verify:documentation checks them"을 더했다. 검사기가
  읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
  기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
  같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
  커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
  검사기와 같은 규칙을 두 곳에 두게 된다.

위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
  백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
  아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/template-feature-removal-documents.test.ts
  tests/unit/documentation-readiness.test.ts, corepack pnpm
  verify:documentation, corepack pnpm test:sample-removal

Refs: 1105/14-03
2026-11-06 02:59:02 +09:00

3.6 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. A list read answers an empty list in the frame its descriptor declares (inside the Envelope for responseEnvelope: "ENVELOPE_V1"), and the scan runs only once no alert box is on screen, so a list page is scanned in its empty state. A read of one resource (a detail page) has no generic answer: that route is scanned in its failure state and the run records an a11y-data-state annotation.
  • 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).