문제 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
77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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).
|