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
Owner

무엇을, 왜

round9 확인 리뷰 그룹 A의 묶음 A5(접근성 남은 것)를 고친다. 네 발견이다.

  • 1112/05-01 (Medium·P2): FE-GATE-028(review:a11y-manual)이 기록끼리 Release ID가 같은지만 봐서, 앞 release에 서명한 기록이 다음 release 후보에서도 통과한다.
  • 1112/05-05의 남은 것 (Low·P3): 제품은 WCAG 2.2 AA를 약속하는데 수동 기록 양식에 2.4.11(포커스 가림)·2.5.8(목표 크기) 칸이 없다. axe 태그(wcag22aa)는 F5(978170cb)가 이미 더했다.
  • 1112/05-16 (확인되면 Low·P3): 공개 라우트 axe가 h1만 기다려 Suspense 뒤의 표가 아직 받는 중일 때 스캔할 수 있다. 실험으로 확인했다(아래 검증).
  • 1112/04-04 (Low·P3): 매뉴얼과 fe-ux 스킬이 라우트 loadingSurface가 로딩 모양을 고르는 것처럼 적는다. 실제로는 data-surface 이름표일 뿐이다.

고른 방법과 버린 대안

  • 05-01: scripts/verify-a11y-manual.ts가 env RELEASE_TAG를 읽고 각 기록의 Release ID가 그 태그와 같지 않으면 실패한다. 태그가 비면 모두 실패한다(fail-closed). 규칙은 releaseTagFailures(scripts/lib/manual-a11y-evidence.ts). release job이 RELEASE_TAG를 넘기고 FE-GATE-028이 요구하는 쪽은 이미 main에 있다(000b5a35, w2-fe-2). 버린 대안: workflow RELEASE_ID와 대조(run마다 달라 미리 적을 수 없다), 새 --release-root 입력(release gate 때는 후보가 아직 없다).
  • 05-05: 기록 필드에 M8 Focus not obscured, M9 Target size를 더한다(검사기, checklist, 템플릿 기록 셋, create:feature가 만드는 기록, 매뉴얼 03, fe-a11y 스킬).
  • 05-16: 공개 분기도 h1 뒤에 [aria-busy='true'] 0개를 기다린 뒤 axe를 돌린다. 버린 대안: EXAMPLES_PLATFORM에만 전용 대기(다음 공개 라우트에서 같은 구멍).
  • 04-04: 매뉴얼 1단계와 fe-ux 확인 항목을 실제 동작(이름표, 모양은 고르지 않음)으로 고친다. 버린 대안: loadingSurface를 닫힌 union으로 바꿔 모양을 고르게 하기(라우트 계약·생성 출력·기준선 변경).

정한 기본값

  • 결정 R9-D7 세부(2026-11-13, r9-fe·w2-fe-2: 후보 ID는 릴리스 태그), R9-D9(2026-11-12, 총괄: 수동 칸 2.4.11·2.5.8), R9-D5(2026-11-12, 총괄: 계약은 그대로, 문장을 동작에 맞춘다)를 그대로 따랐다.
  • 태그 비교는 대소문자를 구분하고 앞뒤 공백만 지운다(태그가 그렇다).
  • 새 칸 이름은 기존 M1~M7을 이어 M8·M9로 했다.

위험과 영향

  • 다운스트림이 따라 할 일(CHANGELOG 후보):
    • 기존 route 기록에 M8 Focus not obscured: pending, M9 Target size: pending 두 줄을 더한다. 없으면 FE-GATE-009 형식 검사가 그 필드 이름을 대며 실패한다.
    • 서명한 기록의 Release ID는 다음 release부터 릴리스 태그(예 v1.4.0)로 적는다. 앞 태그로 서명한 기록은 FE-GATE-028에서 실패한다.
  • 공개 라우트 axe가 busy 0을 기다리므로, 영원히 busy인 표면이 생기면 그 시험이 시간 초과로 실패한다(그게 맞는 동작이다). 지금 공개 라우트에는 없다(새 눈 리뷰가 출처를 확인).

검증

(desktop, scripts/verify.sh, 공유 잠금)

  • RED·GREEN r9a-pr3-rg(트리 e252ff89, 기준 ee95573f): unit 70/70 통과. 고치기 전 코드에서 새 시험 8개 실패(M8·M9 칸 둘, 태그 다섯, review:a11y-manual을 띄운 시험 하나).
  • 05-16 실험(V4-X2, accessibility.spec.ts --grep examples/platform --repeat-each 5, 세 엔진): 고치기 전 15회 중 1회 스캔 직전 busy-at-scan 1(발견 확인), 고친 뒤 busy 대기 다음 14회 모두 0. 고친 쪽의 남은 1회는 Firefox에서 h1이 5초 안에 안 나온 알려진 첫 렌더 흔들림이다(새 줄보다 앞에서 실패. 같은 증상을 w2-fe-2가 Firefox 프로필 설정으로 고치는 중).
  • check:types·lint·review:a11y-manual -- --format-only rc=0(같은 실행). 문서 단계 FE-GATE-017(r9a-pr3-docs, 트리 deb3dc43) rc=0.
  • 노트북 scripts/verify.sh docs·hooks OK.
  • scripts/verify.sh merge(r9a-pr3-merge, 트리 deb3dc43 = 이 PR head 트리, CI env): FE-GATE-001~013·020 14개 모두 rc=0. FE-GATE-013(시스템 컨테이너) 포함. 005 181 s, 008 242 s, 013 235 s, 020 400 s.
  • 새 눈 리뷰(렌즈 fe-a11y·fe-testing) 1회: Medium 1(매뉴얼 03의 「Release ID가 같아야 한다」 문장), Low 1(오류표에 새 실패 문구 없음) → 둘 다 고쳤다. spawn 시험 timeout은 desktop 실측 771 ms로 childProcessTimeout(771).

발견 ID 표

ID 판정 커밋
1112/05-01 고침 aa4bddac
1112/05-05 (남은 것: 수동 칸) 고침 aa4bddac
1112/05-16 고침(실험으로 확인한 뒤) 638c074c
1112/04-04 고침(문서, R9-D5) 48b2e50d

리뷰어가 볼 곳

  • scripts/lib/manual-a11y-evidence.ts releaseTagFailures, scripts/verify-a11y-manual.ts
  • tests/unit/manual-a11y-evidence.test.ts의 review:a11y-manual spawn 시험
  • docs/accessibility/manual-checklist.md, docs/manual/03-outside-feature-folder.md 「수동 접근성 검토 서명」

관련

  • 리뷰: docs/reviews/2026-11-round9-05-accessibility.md(A11Y-01·05·16), -04-ux-design-system.md(UX-04), 검증 -15-verify-ux-ds-a11y.md
  • 결정 색인: docs/work/reference/decisions.md R9-D5·D7·D9
  • 그룹 A의 다른 PR: 화면(처리 중 버튼·문구·적재), 토큰·story·검사
## 무엇을, 왜 round9 확인 리뷰 그룹 A의 묶음 A5(접근성 남은 것)를 고친다. 네 발견이다. - 1112/05-01 (Medium·P2): FE-GATE-028(`review:a11y-manual`)이 기록끼리 Release ID가 같은지만 봐서, 앞 release에 서명한 기록이 다음 release 후보에서도 통과한다. - 1112/05-05의 남은 것 (Low·P3): 제품은 WCAG 2.2 AA를 약속하는데 수동 기록 양식에 2.4.11(포커스 가림)·2.5.8(목표 크기) 칸이 없다. axe 태그(`wcag22aa`)는 F5(`978170cb`)가 이미 더했다. - 1112/05-16 (확인되면 Low·P3): 공개 라우트 axe가 h1만 기다려 Suspense 뒤의 표가 아직 받는 중일 때 스캔할 수 있다. 실험으로 확인했다(아래 검증). - 1112/04-04 (Low·P3): 매뉴얼과 fe-ux 스킬이 라우트 `loadingSurface`가 로딩 모양을 고르는 것처럼 적는다. 실제로는 `data-surface` 이름표일 뿐이다. ## 고른 방법과 버린 대안 - 05-01: `scripts/verify-a11y-manual.ts`가 env `RELEASE_TAG`를 읽고 각 기록의 `Release ID`가 그 태그와 같지 않으면 실패한다. 태그가 비면 모두 실패한다(fail-closed). 규칙은 `releaseTagFailures`(`scripts/lib/manual-a11y-evidence.ts`). release job이 `RELEASE_TAG`를 넘기고 FE-GATE-028이 요구하는 쪽은 이미 main에 있다(`000b5a35`, w2-fe-2). 버린 대안: workflow `RELEASE_ID`와 대조(run마다 달라 미리 적을 수 없다), 새 `--release-root` 입력(release gate 때는 후보가 아직 없다). - 05-05: 기록 필드에 `M8 Focus not obscured`, `M9 Target size`를 더한다(검사기, checklist, 템플릿 기록 셋, `create:feature`가 만드는 기록, 매뉴얼 03, fe-a11y 스킬). - 05-16: 공개 분기도 h1 뒤에 `[aria-busy='true']` 0개를 기다린 뒤 axe를 돌린다. 버린 대안: EXAMPLES_PLATFORM에만 전용 대기(다음 공개 라우트에서 같은 구멍). - 04-04: 매뉴얼 1단계와 fe-ux 확인 항목을 실제 동작(이름표, 모양은 고르지 않음)으로 고친다. 버린 대안: `loadingSurface`를 닫힌 union으로 바꿔 모양을 고르게 하기(라우트 계약·생성 출력·기준선 변경). ## 정한 기본값 - 결정 R9-D7 세부(2026-11-13, r9-fe·w2-fe-2: 후보 ID는 릴리스 태그), R9-D9(2026-11-12, 총괄: 수동 칸 2.4.11·2.5.8), R9-D5(2026-11-12, 총괄: 계약은 그대로, 문장을 동작에 맞춘다)를 그대로 따랐다. - 태그 비교는 대소문자를 구분하고 앞뒤 공백만 지운다(태그가 그렇다). - 새 칸 이름은 기존 M1~M7을 이어 M8·M9로 했다. ## 위험과 영향 - 다운스트림이 따라 할 일(CHANGELOG 후보): - 기존 route 기록에 `M8 Focus not obscured: pending`, `M9 Target size: pending` 두 줄을 더한다. 없으면 FE-GATE-009 형식 검사가 그 필드 이름을 대며 실패한다. - 서명한 기록의 `Release ID`는 다음 release부터 릴리스 태그(예 `v1.4.0`)로 적는다. 앞 태그로 서명한 기록은 FE-GATE-028에서 실패한다. - 공개 라우트 axe가 busy 0을 기다리므로, 영원히 busy인 표면이 생기면 그 시험이 시간 초과로 실패한다(그게 맞는 동작이다). 지금 공개 라우트에는 없다(새 눈 리뷰가 출처를 확인). ## 검증 (desktop, `scripts/verify.sh`, 공유 잠금) - RED·GREEN `r9a-pr3-rg`(트리 `e252ff89`, 기준 `ee95573f`): unit 70/70 통과. 고치기 전 코드에서 새 시험 8개 실패(M8·M9 칸 둘, 태그 다섯, `review:a11y-manual`을 띄운 시험 하나). - 05-16 실험(V4-X2, `accessibility.spec.ts --grep examples/platform --repeat-each 5`, 세 엔진): 고치기 전 15회 중 1회 스캔 직전 `busy-at-scan 1`(발견 확인), 고친 뒤 busy 대기 다음 14회 모두 0. 고친 쪽의 남은 1회는 Firefox에서 h1이 5초 안에 안 나온 알려진 첫 렌더 흔들림이다(새 줄보다 앞에서 실패. 같은 증상을 w2-fe-2가 Firefox 프로필 설정으로 고치는 중). - `check:types`·`lint`·`review:a11y-manual -- --format-only` rc=0(같은 실행). 문서 단계 FE-GATE-017(`r9a-pr3-docs`, 트리 `deb3dc43`) rc=0. - 노트북 `scripts/verify.sh docs`·`hooks` OK. - `scripts/verify.sh merge`(`r9a-pr3-merge`, 트리 `deb3dc43` = 이 PR head 트리, CI env): FE-GATE-001~013·020 14개 모두 rc=0. FE-GATE-013(시스템 컨테이너) 포함. 005 181 s, 008 242 s, 013 235 s, 020 400 s. - 새 눈 리뷰(렌즈 fe-a11y·fe-testing) 1회: Medium 1(매뉴얼 03의 「Release ID가 같아야 한다」 문장), Low 1(오류표에 새 실패 문구 없음) → 둘 다 고쳤다. spawn 시험 timeout은 desktop 실측 771 ms로 `childProcessTimeout(771)`. ## 발견 ID 표 | ID | 판정 | 커밋 | |---|---|---| | 1112/05-01 | 고침 | `aa4bddac` | | 1112/05-05 (남은 것: 수동 칸) | 고침 | `aa4bddac` | | 1112/05-16 | 고침(실험으로 확인한 뒤) | `638c074c` | | 1112/04-04 | 고침(문서, R9-D5) | `48b2e50d` | ## 리뷰어가 볼 곳 - `scripts/lib/manual-a11y-evidence.ts` `releaseTagFailures`, `scripts/verify-a11y-manual.ts` - `tests/unit/manual-a11y-evidence.test.ts`의 `review:a11y-manual` spawn 시험 - `docs/accessibility/manual-checklist.md`, `docs/manual/03-outside-feature-folder.md` 「수동 접근성 검토 서명」 ## 관련 - 리뷰: `docs/reviews/2026-11-round9-05-accessibility.md`(A11Y-01·05·16), `-04-ux-design-system.md`(UX-04), 검증 `-15-verify-ux-ds-a11y.md` - 결정 색인: `docs/work/reference/decisions.md` R9-D5·D7·D9 - 그룹 A의 다른 PR: 화면(처리 중 버튼·문구·적재), 토큰·story·검사
donghyeon.kang added 3 commits 2026-11-13 10:52:46 +00:00
수동 접근성 기록 검사에 구멍이 둘 있다.
- 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
라우트 계약의 `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
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
638c074c73
`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
donghyeon.kang merged commit 7e5a0bb8fe into main 2026-11-13 12:55:52 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-frontend-template#48