문제 tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열 `[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope: "ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를 그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는 그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서 다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다. 고른 방법 (결정 D4 (b)) - tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈 목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와 같은 successEnvelope, 아니면 맨 배열). - 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고 단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다. - 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도 spec을 고치지 않는다(16-03 앞 절반). - 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은 501로 답하고 그 목록이 비어 있다고 단언한다. - 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검 문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다. - 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다 접근성 spec 생성(파일·실행 시간 증가). 위험·한계 - 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다. 그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다. - write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도 "passed"로 적힌다. 검증 - 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과. - 템플릿 상태 chromium test:a11y 대상 spec 14건 통과. - create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과. 변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패. 변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두 axe button-name으로 실패. 생성 파일은 지웠다. - check:types:test, eslint, verify:documentation, check:ci 통과. Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01 Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
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:
passnot-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
h1is on screen, so the scan never lands on the app shell's loading surface (tests/e2e/accessibility.spec.ts). A public route'sh1must 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 ana11y-data-stateannotation. - 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).