수동 접근성 기록 검사에 구멍이 둘 있다. - FE-GATE-028(`review:a11y-manual`)은 기록끼리 Release ID가 같은지만 본다 (05-01). 후보를 받는 입력이 없어, 첫 release에 세 기록을 서명한 뒤 화면을 바꾸고 기록을 그대로 둔 채 다음 release를 돌아도 통과한다. checklist의 "release 후보마다 한 번"이 지켜지지 않는다(결함 패턴 G7). - 제품은 WCAG 2.2 AA를 약속하는데 기록 양식은 M1~M7과 스크린 리더뿐이다 (05-05의 남은 것). axe에 규칙이 없는 2.4.11 포커스 가림과 일부만 보는 2.5.8 목표 크기를 볼 칸이 없다. 고른 방법: - 결정(2026-11-13, r9-fe·w2-fe-2: 후보 ID는 릴리스 태그)대로 `scripts/verify-a11y-manual.ts`가 env `RELEASE_TAG`를 읽고, 각 기록의 `Release ID`가 그 태그와 같지 않으면 실패한다. 태그가 비면 비교할 것이 없으니 모두 실패한다(fail-closed). release job은 이미 `RELEASE_TAG`를 넘기고 FE-GATE-028이 그것을 요구한다(main `000b5a35`). 규칙은 `releaseTagFailures`(`scripts/lib/manual-a11y-evidence.ts`)에 둔다. - 결정 R9-D9(2026-11-12, 총괄)대로 기록 양식에 `M8 Focus not obscured` (2.4.11)와 `M9 Target size`(2.5.8)를 더한다: 검사기의 필드 목록, checklist, 템플릿 기록 셋, `create:feature`가 만드는 기록. checklist의 `Release ID` 예는 "release tag"로 바꿨다. - 버린 대안: workflow의 `RELEASE_ID`와 대조(run마다 달라 사람이 미리 적을 수 없다), 칸 없이 태그만 더하기(2.2 AA 일부를 아무도 보지 않는다). 위험·한계: 다운스트림의 기존 route 기록에는 M8·M9가 없어 다음 동기화 뒤 FE-GATE-009 형식 검사가 그 필드 이름을 대며 실패한다. 기록마다 `M8 Focus not obscured: pending`, `M9 Target size: pending` 두 줄을 더하면 된다. 서명한 기록의 `Release ID`는 다음 release부터 태그(예 `v1.4.0`)로 적는다. 검증: `tests/unit/manual-a11y-evidence.test.ts`(M8·M9가 빠진 기록 거절, 태그 같음·다름·빔, `review:a11y-manual`을 실제로 띄워 태그로 통과·다음 태그와 빈 태그로 실패)가 고치기 전 코드에서 실패하고 고친 뒤 통과한다(desktop, PR 본문). Refs: 1112/05-01, 1112/05-05
5.6 KiB
수동 접근성 리뷰 체크리스트
자동 axe 검사만으로는 WCAG 준수를 증명하지 못한다. 사람 리뷰어가
docs/accessibility/route-reviews/의 route 기록을 모두 한 release 후보에 대해
리뷰하고 서명해야 한다. 필요한 범위는 route
registry(src/features/installed-feature-contracts.ts의 ROUTE_REGISTRY)다.
route 하나에 기록 하나를 두고, 이름은 <ROUTE_ID>.md로 한다. template 필드를
그대로 복사한다. gate는 다음을 거부한다: 비어 있는 신원·시각·서명 필드, 아직
정하지 않은(pending) 판정, 이번 release 태그와 다른 Release ID, 빠진 route.
Release ID는 리뷰한 release의 태그다(예: v1.4.0). release job은 만드는
태그를 RELEASE_TAG로 FE-GATE-028에 넘기고(config/ci/gates.json의
requiresEnvironment), review:a11y-manual은 모든 기록의 Release ID가 그 값과
같은지 본다. 앞 release 태그로 서명한 기록은 다음 release에서 실패한다. 그래서
release마다 기록을 다시 검토하고 그 태그로 서명한다. RELEASE_TAG가 비어 있으면
비교할 태그가 없으므로 실패한다.
서명된 리뷰는 release gate FE-GATE-028(review:a11y-manual)이다. 그래서
merge마다가 아니라 release 후보마다 한 번 필요하다. merge gate FE-GATE-009는
review:a11y-manual -- --format-only를 돌린다. 각 기록은 아래 필드를 유지하고
판정 값은 pending, pass, not-applicable (<reason>) 중 하나여야 한다.
reviewed로 표시한 기록은 빠짐없이 채워져 있어야 한다.
이 문서에는 route 목록을 두지 않는다. 예전에 여기 목록이 route 6개라고 적었을 때
실제로는 10개가 등록돼 있었다. 그리고 목록을 최신으로 유지하느라 새 feature마다
이 파일을 고쳐야 했다. 대신 등록된 route에 기록 파일이 없으면
verify:documentation이 그 route ID를 밝히며 실패한다. 새 route는 pending 기록
하나를 복사하고 제목과 Route ID만 바꿔서 시작한다.
항목에 쓸 수 있는 판정:
passnot-applicable (<specific reason>)
필수 기록:
Status: reviewed
Route ID: APP_HOME
Release ID: <release tag, e.g. v1.4.0>
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: pass
M5 Error association: not-applicable (no form error on this route)
M6 Color signal: pass
M7 Reduced motion: pass
M8 Focus not obscured: pass
M9 Target size: pass
Screen reader: pass
Notes: <observations and linked defect IDs>
리뷰어가 확인해야 할 것:
- M1: 모든 동작이 포인팅 장치 없이 된다
- M2: focus를 받은 모든 요소에 눈에 보이는 표시가 있다
- M3: route가 바뀌면 focus가 정해진 대상으로 옮겨 간다
- M4: modal이 있으면 focus가 modal 안에 갇히고, 닫으면 원래 자리로 돌아간다
- M5: 오류가 있으면 해당 입력 요소와 프로그램으로 연결돼 있다
- M6: 상태를 색으로만 나타내지 않는다
- M7: 동작 줄이기(reduced-motion) 설정이 켜지면 꼭 필요하지 않은 움직임을 멈춘다
- M8: focus를 받은 요소가 sticky header, sticky 폼 버튼, toast 같은 고정 요소에 완전히 가려지지 않는다(WCAG 2.2 2.4.11). axe에는 이 규칙이 없다
- M9: 누르는 대상이 24×24 CSS px 이상이거나 그만큼 떨어져 있다(WCAG 2.2 2.5.8).
axe
target-size는 일부만 본다. 템플릿 목표는 44×44 CSS px다 - Screen reader: 제목, live region, 오류, 동작이 한 번씩 읽힌다
form이나 dialog가 있는 route는 M4 modal 리뷰와 M5 필드 오류 리뷰를 실제로 해야
한다. 그런 route에서는 그 항목을 not-applicable로 표시하면 안 된다. 셸(AppShell)의
compact 탐색 drawer는 modal이고 셸 아래 모든 route에 있으므로, 셸 route의 M4는
not-applicable이 아니다. 자동 증거가
통과했다는 것은 이것만 뜻한다: 기록된 Chromium, Firefox, WebKit 실행에서
테스트한 페이지에 critical이나 serious 등급의 axe 발견이 없었다.
자동 실행이 검사하는 것:
- 등록된 모든 route. route 자신의
h1이 화면에 나온 뒤 검사한다. 그래서 앱 셸의 로딩 화면을 검사하는 일이 없다(tests/e2e/accessibility.spec.ts). 공개 route의h1은 catalog 제목과 같아야 한다. - 보호된 route는 데모 로그인 뒤에 검사하고, 로그인 안내 화면은 검사하지 않는다.
목록 읽기에는 빈 목록이 응답으로 온다. 그 응답은 descriptor가 선언한 frame에
담긴다(
responseEnvelope: "ENVELOPE_V1"이면 Envelope 안). 검사는 화면에 alert 상자가 없을 때만 돈다. 그래서 목록 페이지는 빈 상태로 검사된다. 자원 하나를 읽는 경우(상세 페이지)에는 범용 응답이 없다. 그런 route는 실패 상태로 검사하고, 실행이a11y-data-stateannotation을 기록한다.a11y.json은 그 route를notChecked아래에 적는다. 보호된 route의paramsSchema가 그런 읽기의 입력이면, 보고서는 descriptor만 보고 그 기록이 있어야 한다고 판단하고, 없으면 실패한다(scripts/write-a11y-report.ts). create:feature가 만드는 feature의 목록(성공·빈·오류 상태), 상세, 제출 오류가 난 form. 각 상태가 화면에 나온 뒤 검사한다(tests/e2e/generated-feature.spec.ts, 그 feature가 들어간 빌드에서). 제품이 직접 만든 feature는 위의 route 검사를 받는다.