fix(a11y): 수동 접근성 기록을 릴리스 태그로 대조하고 WCAG 2.2 칸을 더한다 #48

Merged
donghyeon.kang merged 3 commits from donghyeon.kang/fix/r9-a11y-evidence AGit into main 2026-11-13 12:55:52 +00:00
3 Commits
Author SHA1 Message Date
DongHyeonka 638c074c73 test(a11y): 공개 라우트도 aria-busy 표면이 풀린 뒤 axe를 돌린다
frontend-quality-gates / main / self-tests and removal drills (pull_request) Skipped
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m43s
frontend-quality-gates / merge / tests (pull_request) Successful in 15m44s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 5m56s
frontend-quality-gates / FE-GATE-017 / diagram-review (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
`tests/e2e/accessibility.spec.ts`의 공개 라우트 분기는 h1만 기다리고 axe를
돌린다. 보호 분기에는 `[aria-busy='true']` 0개 대기가 있는데 공개 분기에는
없다. EXAMPLES_PLATFORM은 HTTP 오퍼레이션 표를 Suspense 뒤에(LoadingSurface는
`aria-busy`), 릴리스 지표 `dl`도 `aria-busy`로 그린다. 그래서 그 표가
검사됐는지가 실행마다 달라지고, 그래도 `a11y.json`은 검사한 것으로 센다(fe-a11y
함정 2).

고른 방법: 공개 분기도 h1 뒤에 `aria-busy` 표면이 0개가 될 때까지 기다린 뒤
axe를 돌린다. checklist의 「자동 실행이 검사하는 것」에 같은 조건을 적는다.
버린 대안: EXAMPLES_PLATFORM에만 전용 대기를 두기(다음 공개 라우트에서 같은
구멍이 다시 생긴다).

검증: 실험 V4-X2(E-L5-05) — 고치기 전과 뒤에 스캔 직전 busy 개수를 찍는
desktop 실행 결과를 PR 본문에 적는다.

Refs: 1112/05-16
2026-11-13 18:45:16 +09:00
DongHyeonka 48b2e50d46 docs(manual): loadingSurface가 로딩 모양이 아니라 이름표라고 적는다
라우트 계약의 `loadingSurface`는 로딩 표면의 `data-surface` 속성에만 쓰인다
(`src/presentation/routes/app-router.tsx` `RouteLoadingSurface`). 모든
라우트가 같은 `LoadingSurface`(skeleton 블록 하나)를 그린다. 그런데 매뉴얼은
이 값을 "로딩 화면 이름"으로 정하라고만 하고, fe-ux 스킬은 "loading surface가
실제 내용 모양(collection·detail·form)을 따른다"를 확인 항목으로 둔다. 기능
작성자는 효과 없는 값을 정하고, 리뷰어는 없는 약속을 본다.

고른 방법: 결정 R9-D5(2026-11-12, 총괄: 계약은 그대로, 문장을 동작에 맞춘다)대로
매뉴얼 1단계의 `loadingSurface` 설명과 fe-ux 확인 항목을 실제 동작(이름표,
모양은 고르지 않음, 내용 모양 skeleton이 필요하면 페이지가 그린다)으로
고친다. 버린 대안: `loadingSurface`를 닫힌 union(`collection`·`detail`·`form`)
으로 바꾸고 모양을 고르게 하기(라우트 계약·생성 출력·FE-REG-ROUTE 기준선을
바꾸는 계약 변경이다).

검증: RED 없음 — 문서를 동작에 맞춘 것이다. 이름표 동작은
`tests/component/route-status-surfaces.test.tsx` 첫 사례가 이미 고정한다
(`.route-loading[data-surface="fixture-page"]`). 노트북 `scripts/verify.sh
docs`, desktop `verify:documentation`(PR 본문).

Refs: 1112/04-04
2026-11-13 18:45:16 +09:00
DongHyeonka aa4bddac36 fix(a11y): 수동 접근성 기록이 릴리스 태그로 서명되고 WCAG 2.2 칸을 갖는다
수동 접근성 기록 검사에 구멍이 둘 있다.
- 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
2026-11-13 18:45:16 +09:00