From aa4bddac36b17dd7ab23b4681c7964139c1fbece Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:41:15 +0900 Subject: [PATCH 1/3] =?UTF-8?q?fix(a11y):=20=EC=88=98=EB=8F=99=20=EC=A0=91?= =?UTF-8?q?=EA=B7=BC=EC=84=B1=20=EA=B8=B0=EB=A1=9D=EC=9D=B4=20=EB=A6=B4?= =?UTF-8?q?=EB=A6=AC=EC=8A=A4=20=ED=83=9C=EA=B7=B8=EB=A1=9C=20=EC=84=9C?= =?UTF-8?q?=EB=AA=85=EB=90=98=EA=B3=A0=20WCAG=202.2=20=EC=B9=B8=EC=9D=84?= =?UTF-8?q?=20=EA=B0=96=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 수동 접근성 기록 검사에 구멍이 둘 있다. - 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 --- .claude/skills/fe-a11y/SKILL.md | 4 +- docs/accessibility/manual-checklist.md | 17 +++- docs/accessibility/route-reviews/APP_HOME.md | 2 + .../route-reviews/EXAMPLES_PLATFORM.md | 2 + docs/accessibility/route-reviews/NOT_FOUND.md | 2 + docs/manual/03-outside-feature-folder.md | 8 +- docs/manual/reference/errors.md | 2 + scripts/create-feature.ts | 2 + scripts/lib/manual-a11y-evidence.ts | 22 +++++ scripts/verify-a11y-manual.ts | 16 ++-- tests/unit/manual-a11y-evidence.test.ts | 84 ++++++++++++++++++- 11 files changed, 144 insertions(+), 17 deletions(-) diff --git a/.claude/skills/fe-a11y/SKILL.md b/.claude/skills/fe-a11y/SKILL.md index 5d764f24..c27a3ce1 100644 --- a/.claude/skills/fe-a11y/SKILL.md +++ b/.claude/skills/fe-a11y/SKILL.md @@ -23,7 +23,7 @@ paths: ## 함정 -1. axe 통과를 접근성 완료로 적는다. 스캔 태그는 `tests/support/browser/axe-tags.ts` 하나다. WCAG 2.2 AA 태그(`wcag22aa`, 목표 크기 2.5.8)도 돌지만, 2.2에서 더해진 기준 대부분(포커스가 가려지지 않음, 드래그 대안 등)은 axe에 규칙이 없어 자동으로 보지 않는다. 그리고 critical·serious 위반만 막는다. — `tests/e2e/accessibility.spec.ts`, `docs/accessibility/manual-checklist.md`, `docs/design/2026-07-26-design-system-platform-design.md` 13절 +1. axe 통과를 접근성 완료로 적는다. 스캔 태그는 `tests/support/browser/axe-tags.ts` 하나다. WCAG 2.2 AA 태그(`wcag22aa`, 목표 크기 2.5.8)도 돌지만, 2.2에서 더해진 기준 대부분(포커스가 가려지지 않음, 드래그 대안 등)은 axe에 규칙이 없어 자동으로 보지 않는다. 포커스 가림과 목표 크기는 수동 기록의 M8·M9가 본다. 그리고 critical·serious 위반만 막는다. — `tests/e2e/accessibility.spec.ts`, `docs/accessibility/manual-checklist.md`, `docs/design/2026-07-26-design-system-platform-design.md` 13절 2. 자동 스캔이 본 상태를 넘겨 짐작한다. 보호 라우트는 데모 로그인 뒤, 목록은 빈 상태, 단건 읽기 상세는 실패 상태에서 스캔하고 `notChecked`로 남긴다. 데이터가 찬 목록·상세는 기능 시험과 수동 검토 몫이다. — `docs/accessibility/manual-checklist.md` 「자동 실행이 검사하는 것」 3. 린트가 의미를 잡아 줄 거라 믿는다. `eslint.config.ts`에 접근성 규칙 플러그인이 없다. `div` + 키 핸들러로 만든 버튼, 이름 없는 아이콘 버튼은 component 시험·axe·리뷰가 잡는다. — `eslint.config.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 13절 4. 저장 중 버튼을 `disabled`로 바꿔 키보드 포커스를 잃게 한다. `pending`을 쓴다. — `docs/manual/02-decision-tables.md` 6절 @@ -73,7 +73,7 @@ pnpm·브라우저는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). ## 이 repo에서 정한 것 - `PRODUCT.md` 「Accessibility & Inclusion」 — WCAG 2.2 AA 기준, 라이트·다크 대비, 수동 검토 절차. -- `docs/accessibility/manual-checklist.md` — M1~M7과 스크린 리더, 기록 형식, 자동 스캔이 보는 범위. +- `docs/accessibility/manual-checklist.md` — M1~M9와 스크린 리더, 기록 형식(`Release ID`는 release 태그), 자동 스캔이 보는 범위. - `docs/accessibility/route-reviews/` — 등록 라우트마다 기록 하나(`.md`). - `docs/design/2026-07-26-design-system-platform-design.md` 8절 — 공통·overlay·form 기준. - `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.3절 — 라우트 포커스와 스크롤. diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index cb83f5b9..d7207472 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -6,7 +6,14 @@ registry(`src/features/installed-feature-contracts.ts`의 `ROUTE_REGISTRY`)다. route 하나에 기록 하나를 두고, 이름은 `.md`로 한다. template 필드를 그대로 복사한다. gate는 다음을 거부한다: 비어 있는 신원·시각·서명 필드, 아직 -정하지 않은(pending) 판정, 맞지 않는 release ID, 빠진 route. +정하지 않은(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는 @@ -30,7 +37,7 @@ merge마다가 아니라 release 후보마다 한 번 필요하다. merge gate F ```text Status: reviewed Route ID: APP_HOME -Release ID: +Release ID: Reviewer: Reviewed at: Signature: @@ -42,6 +49,8 @@ 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: ``` @@ -55,6 +64,10 @@ Notes: - 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 필드 오류 리뷰를 실제로 해야 diff --git a/docs/accessibility/route-reviews/APP_HOME.md b/docs/accessibility/route-reviews/APP_HOME.md index 033989c1..b52d3e97 100644 --- a/docs/accessibility/route-reviews/APP_HOME.md +++ b/docs/accessibility/route-reviews/APP_HOME.md @@ -14,5 +14,7 @@ M4 Modal focus: pending M5 Error association: not-applicable (no form error on this route) M6 Color signal: pending M7 Reduced motion: pending +M8 Focus not obscured: pending +M9 Target size: pending Screen reader: pending Notes: Automated axe, keyboard-focus, and reduced-motion evidence is available; human review pending. diff --git a/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md b/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md index 28d9d6d0..d82869af 100644 --- a/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md +++ b/docs/accessibility/route-reviews/EXAMPLES_PLATFORM.md @@ -14,5 +14,7 @@ M4 Modal focus: pending M5 Error association: not-applicable (no form error on this route) M6 Color signal: pending M7 Reduced motion: pending +M8 Focus not obscured: pending +M9 Target size: pending Screen reader: pending Notes: Review the horizontally scrollable registry tables for keyboard reachability of the scroll container, table caption and header association announced per row, capability status badges carrying their meaning in text rather than colour alone, and the release identity region announcing its update through aria-live without interrupting a reader mid row. diff --git a/docs/accessibility/route-reviews/NOT_FOUND.md b/docs/accessibility/route-reviews/NOT_FOUND.md index 729ae595..9971f67f 100644 --- a/docs/accessibility/route-reviews/NOT_FOUND.md +++ b/docs/accessibility/route-reviews/NOT_FOUND.md @@ -14,5 +14,7 @@ M4 Modal focus: pending M5 Error association: not-applicable (no form error on this route) M6 Color signal: pending M7 Reduced motion: pending +M8 Focus not obscured: pending +M9 Target size: pending Screen reader: pending Notes: Human review pending. diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index 16e92bd7..9b9cd26c 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -60,12 +60,12 @@ create:feature가 pending 기록을 만든다 할 일: -1. 릴리스 후보 하나를 띄운다. -2. `docs/accessibility/manual-checklist.md`의 M1~M7과 스크린 리더 항목을 그 라우트에서 확인한다. +1. 릴리스 후보 하나를 띄운다. 그 릴리스의 태그(예 `v1.4.0`)를 정한다. +2. `docs/accessibility/manual-checklist.md`의 M1~M9와 스크린 리더 항목을 그 라우트에서 확인한다. 3. `docs/accessibility/route-reviews/.md`를 채운다. - - `Status: reviewed`, `Release ID`, `Reviewer`, `Reviewed at`, `Signature`, `Attestation: accepted` + - `Status: reviewed`, `Release ID`(그 릴리스 태그), `Reviewer`, `Reviewed at`, `Signature`, `Attestation: accepted` - 항목마다 `pass` 또는 `not-applicable (<구체적 이유>)` -4. 모든 라우트 기록의 `Release ID`가 같아야 한다. +4. 모든 라우트 기록의 `Release ID`가 이번 릴리스 태그와 같아야 한다. release job이 그 태그를 `RELEASE_TAG`로 FE-GATE-028에 넘기고, 앞 릴리스 태그로 서명한 기록은 실패한다. 그래서 릴리스마다 다시 검토하고 그 태그로 서명한다. 안 하면: FE-GATE-028이 `Manual accessibility evidence is incomplete:`로 릴리스를 막는다. diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 6bd93f7f..78a4dee7 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -180,6 +180,8 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `a11y.json not written:` 다음 `a11y: reads one resource () but has no failure-state record in artifacts/tests/a11y-data-state` (`test:a11y`, FE-GATE-009) | 라우트의 `paramsSchema`가 한 자원을 읽는 GET의 입력인데, 접근성 spec이 그 라우트를 실패 화면으로만 봤다는 기록이 없다(1106/11-01). spec이 기록 호출을 놓쳤거나, 그 라우트의 페이지가 그 GET을 부르지 않아 spec이 실패 화면을 보지 않았다. 앞의 경우 그대로면 `a11y.json`이 그 라우트를 통과로 센다 | 페이지가 그 GET을 부르면 `tests/e2e/accessibility.spec.ts`의 기록 호출(`recordA11yDataState`)을 본다. 이때 기능 파일은 고치지 않는다. 페이지가 그 GET을 부르지 않으면(예: `/things/:thingId/parts/new` 같은 하위 항목 작성 폼이 상세 GET과 같은 `ThingParams`를 쓴다) 그 라우트에 자기 `paramsSchema`를 따로 둔다. 기능의 라우트 계약과 `contracts/-schema-metadata.ts`를 고친다 | | `Manual accessibility evidence is incomplete:` 다음 `: ` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) | | `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 | +| `: Release ID "" is not the release tag ""` (FE-GATE-028) | 그 기록이 이번 릴리스 태그가 아닌 릴리스(보통 앞 릴리스)로 서명됐다 | 이번 릴리스에서 다시 검토하고 `Release ID`를 그 태그로 적어 서명한다([03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명)) | +| `no release tag to compare the Release ID with (RELEASE_TAG is empty)` (FE-GATE-028) | 태그 run이 아닌 곳에서 서명 검사를 돌렸다. release job은 태그 run에서만 `RELEASE_TAG`를 채운다 | 릴리스 태그(`v*`)를 push한 run에서 돌린다. 손으로 돌리면 `RELEASE_TAG=`를 준다 | | ` names paths that do not exist: ` (`verify:documentation`) | 문서가 없는 경로를 적었다 | 그 문서 | --- diff --git a/scripts/create-feature.ts b/scripts/create-feature.ts index a68fe5a2..5a547dc1 100644 --- a/scripts/create-feature.ts +++ b/scripts/create-feature.ts @@ -1620,6 +1620,8 @@ M4 Modal focus: pending M5 Error association: pending M6 Color signal: pending M7 Reduced motion: pending +M8 Focus not obscured: pending +M9 Target size: pending Screen reader: pending Notes: Human review pending. ${GENERATED} `; diff --git a/scripts/lib/manual-a11y-evidence.ts b/scripts/lib/manual-a11y-evidence.ts index a254dd0e..b518e781 100644 --- a/scripts/lib/manual-a11y-evidence.ts +++ b/scripts/lib/manual-a11y-evidence.ts @@ -12,6 +12,10 @@ const REVIEW_FIELDS = Object.freeze([ "M5 Error association", "M6 Color signal", "M7 Reduced motion", + // 1112/05-05. WCAG 2.2 AA criteria axe has no rule for (focus not obscured + // 2.4.11) or covers only in part (target size 2.5.8). + "M8 Focus not obscured", + "M9 Target size", "Screen reader", ]); @@ -98,3 +102,21 @@ export function validateManualA11yEvidence(content: string) { passed: failures.length === 0, }); } + +/** + * 1112/05-01. A signed record is evidence for one release only: the release + * tag the release job is building (`RELEASE_TAG`, e.g. `v1.4.0`). A record + * signed for an earlier tag does not pass a later one. With no tag there is + * nothing to compare with, so every record fails (fail-closed). + */ +export function releaseTagFailures( + releaseTag: string | undefined, + releaseId: string | null | undefined, +): string[] { + const tag = releaseTag?.trim() ?? ""; + if (tag === "") return ["no release tag to compare the Release ID with (RELEASE_TAG is empty)"]; + if (releaseId !== tag) { + return [`Release ID ${releaseId ? `"${releaseId}"` : "(empty)"} is not the release tag "${tag}"`]; + } + return []; +} diff --git a/scripts/verify-a11y-manual.ts b/scripts/verify-a11y-manual.ts index ef205fd8..a8af9e0c 100644 --- a/scripts/verify-a11y-manual.ts +++ b/scripts/verify-a11y-manual.ts @@ -3,6 +3,7 @@ import { mkdir, readFile } from "node:fs/promises"; import { manualA11yReportArtifactSchema } from "./contracts/release-artifacts.ts"; import { MANUAL_A11Y_ROUTE_IDS, + releaseTagFailures, validateManualA11yEvidence, validateManualA11yRecordFormat, } from "./lib/manual-a11y-evidence.ts"; @@ -39,15 +40,20 @@ if (process.argv.includes("--format-only")) { process.exit(0); } +// 1112/05-01. The release job passes the tag it is releasing (FE-GATE-028 +// declares RELEASE_TAG as required, so run-ci-gate refuses a run without it); +// every record must be signed for that tag. +const releaseTag = process.env.RELEASE_TAG; const results: ManualA11yResult[] = []; for (const routeId of MANUAL_A11Y_ROUTE_IDS) { const path = `docs/accessibility/route-reviews/${routeId}.md`; const evidence = await readFile(path, "utf8"); const validation = validateManualA11yEvidence(evidence); - const failures = - validation.fields["Route ID"] === routeId - ? validation.failures - : Object.freeze([...validation.failures, "Route ID mismatch"]); + const failures = Object.freeze([ + ...validation.failures, + ...(validation.fields["Route ID"] === routeId ? [] : ["Route ID mismatch"]), + ...releaseTagFailures(releaseTag, validation.fields["Release ID"]), + ]); results.push({ routeId, path, @@ -55,7 +61,7 @@ for (const routeId of MANUAL_A11Y_ROUTE_IDS) { reviewedAt: validation.fields["Reviewed at"] ?? null, releaseId: validation.fields["Release ID"] ?? null, failures, - passed: validation.passed && failures.length === 0, + passed: failures.length === 0, }); } const releaseIds = new Set( diff --git a/tests/unit/manual-a11y-evidence.test.ts b/tests/unit/manual-a11y-evidence.test.ts index 1bb99468..4b1555b1 100644 --- a/tests/unit/manual-a11y-evidence.test.ts +++ b/tests/unit/manual-a11y-evidence.test.ts @@ -1,17 +1,22 @@ -import { describe, expect, it } from "vitest"; +import { afterAll, describe, expect, it } from "vitest"; -import { readFileSync } from "node:fs"; +import { spawnSync } from "node:child_process"; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; import { MANUAL_A11Y_ROUTE_IDS, + releaseTagFailures, validateManualA11yEvidence, validateManualA11yRecordFormat, } from "../../scripts/lib/manual-a11y-evidence.ts"; import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts"; +import { childProcessTimeout } from "../helpers/child-process-timeout.ts"; const reviewed = `Status: reviewed Route ID: APP_HOME -Release ID: release-1 +Release ID: v1.4.0 Reviewer: reviewer@example.test Reviewed at: 2026-07-25T12:00:00Z Signature: review-record-1 @@ -23,6 +28,8 @@ M4 Modal focus: not-applicable (no modal) M5 Error association: not-applicable (no form error) M6 Color signal: pass M7 Reduced motion: pass +M8 Focus not obscured: pass +M9 Target size: pass Screen reader: pass Notes: no defects`; @@ -73,7 +80,7 @@ describe("manual accessibility evidence", () => { describe("record format", () => { const pending = reviewed .replace("Status: reviewed", "Status: pending-manual-review") - .replace("Release ID: release-1", "Release ID:") + .replace("Release ID: v1.4.0", "Release ID:") .replace("Reviewer: reviewer@example.test", "Reviewer:") .replace("Reviewed at: 2026-07-25T12:00:00Z", "Reviewed at:") .replace("Signature: review-record-1", "Signature:") @@ -98,8 +105,77 @@ describe("manual accessibility evidence", () => { ["an unknown verdict", pending.replace("M1 Keyboard: pending", "M1 Keyboard: ok"), "APP_HOME", "M1 Keyboard"], ["another route's record", pending, "NOT_FOUND", "Route ID"], ["a reviewed record that is not complete", reviewed.replace("Signature: review-record-1", "Signature:"), "APP_HOME", "Signature"], + // 1112/05-05. The WCAG 2.2 AA criteria axe does not cover. + ["a record without the focus-not-obscured review", pending.replace("M8 Focus not obscured: pass\n", ""), "APP_HOME", "M8 Focus not obscured"], + ["a record without the target-size review", pending.replace("M9 Target size: pass\n", ""), "APP_HOME", "M9 Target size"], ])("rejects %s", (_name, record, routeId, field) => { expect(validateManualA11yRecordFormat(record, routeId)).toContain(field); }); }); + + // 1112/05-01. A record signed for one release tag is not evidence for the + // next one, and with no tag there is nothing to sign against. + describe("release tag", () => { + it("accepts the Release ID that is the release tag", () => { + expect(releaseTagFailures("v1.4.0", "v1.4.0")).toEqual([]); + }); + + it("rejects a record signed for an earlier release", () => { + expect(releaseTagFailures("v1.5.0", "v1.4.0")).toEqual([ + 'Release ID "v1.4.0" is not the release tag "v1.5.0"', + ]); + }); + + it.each([undefined, "", " "])("fails closed when the tag is %j", (tag) => { + expect(releaseTagFailures(tag, "v1.4.0")).toEqual([ + "no release tag to compare the Release ID with (RELEASE_TAG is empty)", + ]); + }); + }); +}); + +// 1112/05-01. FE-GATE-028 runs `review:a11y-manual`; it reads RELEASE_TAG. +describe("review:a11y-manual against the release tag", () => { + const roots: string[] = []; + afterAll(() => { + for (const root of roots) rmSync(root, { recursive: true, force: true }); + }); + + function signedRecords(releaseId: string): string { + const root = mkdtempSync(path.join(tmpdir(), "a11y-manual-")); + roots.push(root); + mkdirSync(path.join(root, "docs/accessibility/route-reviews"), { recursive: true }); + for (const routeId of MANUAL_A11Y_ROUTE_IDS) { + writeFileSync( + path.join(root, `docs/accessibility/route-reviews/${routeId}.md`), + reviewed + .replace("Route ID: APP_HOME", `Route ID: ${routeId}`) + .replace("Release ID: v1.4.0", `Release ID: ${releaseId}`), + ); + } + return root; + } + + function review(root: string, releaseTag: string | undefined) { + const environment = { ...process.env }; + delete environment["RELEASE_TAG"]; + if (releaseTag !== undefined) environment["RELEASE_TAG"] = releaseTag; + return spawnSync(process.execPath, [path.resolve("scripts/verify-a11y-manual.ts")], { + cwd: root, + encoding: "utf8", + env: environment, + }); + } + + it("passes records signed for the tag and refuses them for the next tag or no tag", () => { + const root = signedRecords("v1.4.0"); + + expect(review(root, "v1.4.0")).toMatchObject({ status: 0 }); + const next = review(root, "v1.5.0"); + expect(next.status).toBe(1); + expect(next.stderr).toContain('is not the release tag "v1.5.0"'); + const untagged = review(root, undefined); + expect(untagged.status).toBe(1); + expect(untagged.stderr).toContain("RELEASE_TAG is empty"); + }, childProcessTimeout(771)); }); From 48b2e50d46e0ef43758e5626bf737b2ddbb88a88 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:41:15 +0900 Subject: [PATCH 2/3] =?UTF-8?q?docs(manual):=20loadingSurface=EA=B0=80=20?= =?UTF-8?q?=EB=A1=9C=EB=94=A9=20=EB=AA=A8=EC=96=91=EC=9D=B4=20=EC=95=84?= =?UTF-8?q?=EB=8B=88=EB=9D=BC=20=EC=9D=B4=EB=A6=84=ED=91=9C=EB=9D=BC?= =?UTF-8?q?=EA=B3=A0=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 라우트 계약의 `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 --- .claude/skills/fe-ux/SKILL.md | 4 ++-- docs/manual/01-add-a-feature.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/skills/fe-ux/SKILL.md b/.claude/skills/fe-ux/SKILL.md index afa7fc08..b94a0fdb 100644 --- a/.claude/skills/fe-ux/SKILL.md +++ b/.claude/skills/fe-ux/SKILL.md @@ -48,8 +48,8 @@ paths: 상태 - [ ] 로딩·빈·오류·배경 갱신은 `AsyncSurface`, 로그인 필요·권한 없음·없음·점검은 `StatusPage`와 상태 화면이다. — `src/presentation/components/async-surface.tsx`, `src/presentation/components/state-surfaces.tsx` -- [ ] loading surface가 실제 내용 모양(collection·detail·form)을 따른다. reduced-motion에서 skeleton 움직임을 줄인다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.1절 -- [ ] 예상 못 한 오류는 안전한 일반 문구 + 지원 참조(build id와 incident id)다. — 같은 문서 6.2절 +- [ ] 라우트 로딩은 모든 라우트가 같은 `LoadingSurface`다. 라우트 계약의 `loadingSurface`는 그 표면의 이름표(`data-surface`)일 뿐 모양을 고르지 않는다(소유자 결정 2026-11-12). 데이터를 받는 동안 내용 모양을 따르는 skeleton이 필요하면 그 페이지가 그린다. reduced-motion에서 skeleton 움직임을 줄인다. — `src/presentation/routes/app-router.tsx` `RouteLoadingSurface`, `docs/manual/01-add-a-feature.md` +- [ ] 예상 못 한 오류는 안전한 일반 문구 + 지원 참조(build id와 incident id)다. — `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.2절 문구 diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 07093512..4ed75fe3 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -436,7 +436,7 @@ projectRequest: (input) => Object.freeze({ ① **정할 것** - `access`: `public`(로그인 없이) 또는 `session-required`(로그인 필요). -- `loadingSurface`: 로딩 화면 이름. 케밥 표기. +- `loadingSurface`: 라우트 청크를 받는 동안 보이는 로딩 표면의 이름. 케밥 표기. 화면에는 `data-surface` 속성으로만 붙는다. 진단과 시험이 어느 라우트의 로딩인지 찾는 이름표이고, 로딩 모양은 고르지 않는다. 모든 라우트가 같은 `LoadingSurface`를 그린다(`src/presentation/routes/app-router.tsx`). - `errorSurface`: `route-boundary`, `feature-boundary`, `not-found` 중 하나. 생성된 판은 `feature-boundary`다. - `chunkId`: 지연 로드 청크 이름. 전역에서 유일해야 한다. - `navigationOrder`: 메뉴 순서. `null`이면 메뉴에 나오지 않는다. From 638c074c73a635616558a79e89f09c272ed46f87 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:41:15 +0900 Subject: [PATCH 3/3] =?UTF-8?q?test(a11y):=20=EA=B3=B5=EA=B0=9C=20?= =?UTF-8?q?=EB=9D=BC=EC=9A=B0=ED=8A=B8=EB=8F=84=20aria-busy=20=ED=91=9C?= =?UTF-8?q?=EB=A9=B4=EC=9D=B4=20=ED=92=80=EB=A6=B0=20=EB=92=A4=20axe?= =?UTF-8?q?=EB=A5=BC=20=EB=8F=8C=EB=A6=B0=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `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 --- docs/accessibility/manual-checklist.md | 5 +++-- tests/e2e/accessibility.spec.ts | 3 +++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/accessibility/manual-checklist.md b/docs/accessibility/manual-checklist.md index d7207472..0648285d 100644 --- a/docs/accessibility/manual-checklist.md +++ b/docs/accessibility/manual-checklist.md @@ -79,8 +79,9 @@ not-applicable이 아니다. 자동 증거가 자동 실행이 검사하는 것: -- 등록된 모든 route. route 자신의 `h1`이 화면에 나온 뒤 검사한다. 그래서 앱 셸의 - 로딩 화면을 검사하는 일이 없다(`tests/e2e/accessibility.spec.ts`). 공개 +- 등록된 모든 route. route 자신의 `h1`이 화면에 나오고 `aria-busy` 표면이 모두 + 풀린 뒤 검사한다. 그래서 앱 셸의 로딩 화면이나 아직 받는 중인 표를 검사하는 일이 + 없다(`tests/e2e/accessibility.spec.ts`). 공개 route의 `h1`은 catalog 제목과 같아야 한다. - 보호된 route는 데모 로그인 뒤에 검사하고, 로그인 안내 화면은 검사하지 않는다. 목록 읽기에는 빈 목록이 응답으로 온다. 그 응답은 descriptor가 선언한 frame에 diff --git a/tests/e2e/accessibility.spec.ts b/tests/e2e/accessibility.spec.ts index 81fcbd97..8ab6b5f1 100644 --- a/tests/e2e/accessibility.spec.ts +++ b/tests/e2e/accessibility.spec.ts @@ -91,6 +91,9 @@ for (const definition of ROUTES) { await page.goto(route); const title = CATALOG[`route.${definition.routeId}.title`]; await expect(heading).toHaveText(title ?? definition.title); + // 1112/05-16. A public page can still be loading behind Suspense (the + // platform page's operation table) when its h1 is up; scan it settled. + await expect(page.locator("[aria-busy='true']")).toHaveCount(0); await recordA11yDataState(definition.routeId, null); } expect(await blockingViolations(page)).toEqual([]);