문제: a11y.json의 notChecked는 접근성 spec이 남긴 기록만으로 정해졌다. 기록이 없으면 "검사함"이었고, 어느 라우트에 기록이 있어야 하는지는 spec 말고 아무도 몰랐다. 리뷰 11-R2에서 실패 화면 분기의 기록 호출 reason을 null로 바꾸자 라우트 test 10건, write-a11y-report.ts, 증거 schema가 모두 통과하고 a11y.json이 상세 라우트를 scope(통과)에 넣고 notChecked: []를 적었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. 같은 실행 뒤 지난 실행의 기록 파일도 디렉터리에 남아 있었다. 고른 방법: 리뷰의 (다)와 기록 초기화. - scripts/lib/a11y-data-state.ts의 oneResourceReadRoutes가 설치된 descriptor만으로 "실패 화면으로만 볼 수 있는 라우트"를 찾는다. 로그인이 필요한 라우트의 paramsSchema가, 경로 파라미터가 있고 빈 목록을 거부하는 GET의 입력 스키마일 때다. GET 쪽 규칙은 tests/e2e/support/installed-api-answers.ts가 답하는 규칙과 같다. 참조 기능 상세와 create:feature --with-create 상세는 GET과 같은 <Pascal>Params를 쓰므로 이 규칙에 든다. - write-a11y-report.ts는 그 라우트가 기록(notChecked)에 없으면 `a11y.json not written:`과 라우트·operation을 찍고 rc=1로 끝난다. a11y.json은 쓰지 않는다. test:a11y(FE-GATE-009)가 실패한다. - accessibility.spec.ts의 라우트 test는 시작할 때 자기 기록을 지운다. 기록 호출에 닿지 못한 실행이 지난 실행의 기록을 그대로 쓰지 않는다. 엔진 셋이 같은 파일을 쓰지만 각 엔진은 지운 뒤에만 쓰고, 실행 중에 기록을 읽는 곳이 없어 순서가 섞여도 결과가 같다. - 단위 테스트: 가짜 descriptor로 규칙(목록·경로 아래 목록·DELETE·공개 라우트 제외)과 거절(null 기록은 거절, 기록이 있으면 통과, 기대 밖 기록은 허용). 참조 기능 테스트가 실제 descriptor에서 REFERENCE_RESOURCE_DETAIL 하나가 나오는지 본다. 이 줄이 없으면 규칙이 아무것도 찾지 못해도 모른다. 참조 기능과 함께 지워진다. - 11-R2 diff는 그대로 적용된다(문맥 줄 유지, 4줄 offset). 버린 대안: - (나) 두 상태 모두 기록하고 기록 없는 라우트를 실패: 기록 삭제는 잡지만 reason을 null로 바꾸는 11-R2는 못 잡는다. 실행 경계(TEST_RUN_ID)도 정해야 한다. - 증거 schema(release-artifacts.ts)에서 검사: schema 모듈이 기능 런타임 전체(top-level await)를 불러야 하고, 그 모듈을 쓰는 스크립트가 많다. - spec 안에서 기록을 다시 읽어 대조: 같은 test의 두 줄을 서로 대조할 뿐이고, 시작 시 초기화와 엔진 동시 실행이 겹치면 거짓 실패가 난다. - 기록 호출의 모양을 바꿔 사실(읽은 operation)을 적고 report가 판정: 11-R2 변이 자리가 사라져 리뷰 변이로 확인할 수 없다. 위험·한계: 방향은 하나다. 규칙이 찾은 라우트가 기록에 없으면 실패하고, 규칙이 못 찾는 라우트를 spec이 notChecked로 적는 것은 덜 주장하는 쪽이라 받는다. paramsSchema가 GET 입력과 다른 상세 페이지(손으로 쓴 기능)는 규칙이 찾지 못해 기록만으로 정해진다(이전과 같다). 공개 라우트는 spec이 API에 답하지 않으므로 이 규칙 밖이다. write-a11y-report.ts가 기능 런타임 전체를 불러온다(check:registries와 같은 경로). check:types:node가 그 그래프를 node 설정으로 검사한다. 노트북에서 아무것도 실행하지 않았다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts tests/features/reference-feature/reference-contract.test.ts 11-R2 변이와 기록 줄 삭제 변이에서 playwright(chromium, @a11y /) 뒤 node scripts/write-a11y-report.ts rc=1, 변이 없이 rc=0. corepack pnpm test:a11y Refs: 1106/11-01
3.8 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.a11y.jsonlists it undernotChecked. When a protected route'sparamsSchemais the input of such a read, the report expects that record from the descriptors alone and fails without it (scripts/write-a11y-report.ts). - 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).