문제: docs/runbooks, docs/security, docs/styling/design-tokens.md, docs/accessibility, docs/contracts, docs/testing/taxonomy.md와 src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다. PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code, 기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로 둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장 끝만 바꾼다. 위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임 문체를 더하면 verify:documentation이 실패한다. 검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다. 문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
4.6 KiB
수동 접근성 리뷰 체크리스트
자동 axe 검사만으로는 WCAG 준수를 증명하지 못한다. 사람 리뷰어가
artifacts/tests/a11y-manual/의 route 기록을 모두 한 release 후보에 대해
리뷰하고 서명해야 한다. 필요한 범위는 route
registry(src/features/installed-feature-contracts.ts의 ROUTE_REGISTRY)다.
route 하나에 기록 하나를 두고, 이름은 <ROUTE_ID>.md로 한다. template 필드를
그대로 복사한다. gate는 다음을 거부한다: 비어 있는 신원·시각·서명 필드, 아직
정하지 않은(pending) 판정, 맞지 않는 release ID, 빠진 route.
서명된 리뷰는 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: <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>
리뷰어가 확인해야 할 것:
- M1: 모든 동작이 포인팅 장치 없이 된다
- M2: focus를 받은 모든 요소에 눈에 보이는 표시가 있다
- M3: route가 바뀌면 focus가 정해진 대상으로 옮겨 간다
- M4: modal이 있으면 focus가 modal 안에 갇히고, 닫으면 원래 자리로 돌아간다
- M5: 오류가 있으면 해당 입력 요소와 프로그램으로 연결돼 있다
- M6: 상태를 색으로만 나타내지 않는다
- M7: 동작 줄이기(reduced-motion) 설정이 켜지면 꼭 필요하지 않은 움직임을 멈춘다
- Screen reader: 제목, live region, 오류, 동작이 한 번씩 읽힌다
form이나 dialog가 있는 route는 M4 modal 리뷰와 M5 필드 오류 리뷰를 실제로 해야 한다. 그런 route에서는 그 항목을 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 검사를 받는다.