Files
clean-architecture-frontend…/docs/accessibility/manual-checklist.md
T
DongHyeonka 978170cb03
frontend-quality-gates / merge / static checks (pull_request) Successful in 3m52s
frontend-quality-gates / merge / tests (pull_request) Failing after 15m28s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 10m56s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
test(a11y): 접근성 자동 검사가 지키는 규칙에 실제로 닿게 한다
접근성 자동 검사 셋이 지키는 것에 닿지 않는다.

- reduced-motion e2e가 body의 animationDuration으로 브라우저 기본값
  0s도 받아들인다. responsive.css의 reduced-motion 규칙을 지워도
  통과한다(1112/05-08).
- 예제 화면을 Storybook 갤러리로 옮기면서 화면 전체 axe 검사가 빠졌다.
  기능이 없는 템플릿에서 빈·오류·로그인·권한 표면이 axe를 받지
  않는다(05-04).
- 제품이 WCAG 2.2 AA를 약속하는데 스캔 태그는 2.1까지다. 같은 태그 목록이
  네 곳에 손으로 적혀 있다(05-05 일부).
- 셸 compact drawer는 modal이고 모든 셸 route에 있는데, 라우트 수동 기록
  셋과 checklist 예시가 M4를 "modal 없음"으로 채운다(05-07).

고른 방법: reduced-motion 시험은 규칙이 없을 때의 값(0s)과 규칙의 값
(0.01ms)을 함께 본다. 갤러리 두 story를 light·dark에서 화면 전체 axe로
본다. 태그는 tests/support/browser/axe-tags.ts 하나에 두고 wcag22aa를
더한다. 라우트 기록의 M4를 pending으로 바꾸고 checklist에 셸 drawer를
적는다. 수동 기록 양식에 2.4.11·2.5.8 칸을 더하는 일(05-05의 나머지)은 양식과 생성
출력이 바뀌는 일이라 이 커밋에 넣지 않았다. R9-D9(권하는 안으로 정함
(2026-11-12, 총괄))에 따라 따로 한다.

위험·한계: wcag22aa는 axe의 target-size 규칙만 더한다. 포커스 가림(2.4.11)
같은 기준은 여전히 수동이다.

검증: reduced-motion 시험이 규칙을 지운 변이에서 실패하고 원래 코드에서
통과한다. 갤러리 axe 넷과 FE-GATE-009는 desktop에서 돈다(PR 본문).

Refs: 1112/05-04, 1112/05-05, 1112/05-07, 1112/05-08
2026-11-13 00:13:36 +09:00

4.7 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 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만 바꿔서 시작한다.

항목에 쓸 수 있는 판정:

  • pass
  • not-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: pass
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로 표시하면 안 된다. 셸(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-state annotation을 기록한다. 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 검사를 받는다.