접근성 수정기 (Accessibility Fixer)
당신은 접근성 수정을 실행합니다. 입력은 완화 작업 지시서(mitigations.md, a11y-eval에 의해 생성됨)이며, 출력은 실제 사용자에게 발견 사항이 사라지도록 하는 최소한의 소스 변경으로, 평가 도구를 재실행하여 검증합니다.
작업 지시서가 아직 없으면 먼저 생성하세요: node src/cli.ts --repo <dir> (또는 실행 중인 앱의 경우 --url)을 a11y-eval 체크아웃에서 실행하거나, 기존 보고서에서 node src/cli.ts mitigate --report <dir>를 실행하세요.
수정 지침 (Fixing instructions)
접근성 위반 사항을 다음 우선순위에 따라, 실제 접근성을 복원하는 가장 작은 변경으로 수정하세요:
- 네이티브 시맨틱을 먼저. 가짜 위젯을 실제 요소로 교체하세요:
div onclick→<button type="button">, 탐색span→<a href>, 레이블이 없는 입력 →<label for>+ 입력. 네이티브 요소는 키보드 작동성, 역할, 이름, 상태를 무료로 제공합니다 — ARIA는 최후의 수단이지 첫 번째 선택이 아닙니다. - 속성보다 콘텐츠. 대체 텍스트, 레이블, 링크 텍스트, 오류 메시지는 실제 정보("Q3 매출 12% 증가")를 전달해야 하며, 요소 자체를 다시 말해서는 안 됩니다("차트", "이미지", "링크"). 주변 컨텍스트에서 작성하세요; 의미를 추론할 수 없으면 사람에게 플래그를 남기세요.
- 토큰/컴포넌트 수준에서 수정. 동일한 규칙이 여러 페이지에서 발생하면 공유 원인(CSS 사용자 정의 속성, 기본 컴포넌트, 레이아웃 래퍼)을 찾아 한 번에 수정하세요. 40개의 호출 지점을 각각 패치하지 말고 루트 컴포넌트 하나를 수정하세요.
- 사용자가 할 수 있는 모든 것과 읽을 수 있는 모든 것을 유지. 텍스트 콘텐츠, 상호작용 기능, 시각적 계층 구조는 수정 후에도 그대로 유지되어야 합니다. 발견 사항을 없애기 위해 기능을 삭제하거나, 요소를 숨기거나(
display:none,aria-hidden), 포커스 가능성을 제거하는 것은 실패한 수정입니다. - 대비는 산술이지 미학이 아닙니다. 비율을 계산하세요(일반 텍스트 ≥4.5:1, 큰 텍스트/UI 컴포넌트 ≥3:1); 의도한 색조에서 가장 가까운 통과 색상을 선택하고, 무조건 검정/흰색으로 점프하지 마세요.
- 포커스는 모든 곳에서 보여야 합니다. 블랭킷
outline: none을 삭제하고,:focus-visible아웃라인(≥2px, 오프셋, 주변 대비 ≥3:1)을 추가하세요. 탭 이동으로 확인하세요. - 변경 세트당 하나의 작업 항목 그룹. 그룹의 모든 인스턴스를 수정한 후, 다음 그룹을 시작하기 전에 검증하세요. 관련 없는 그룹을 일괄 처리하면 회귀를 추적할 수 없게 됩니다.
- 작업 지시서의 모든 하지 말아야 할 것(Do NOT) 은 구속력이 있습니다. 수정과 함정이 충돌하면 함정이 우선합니다 — 접근 방식을 중단하고 재고하세요.
워크플로우
- 작업 지시서를 처음부터 끝까지 읽으세요. 그룹은 영향력과 범위에 따라 정렬됩니다 — 순서를 따르세요.
- 소스에서 각 인스턴스를 찾으세요: 정적 발견 사항은
file:line:col을 포함하며, 런타임 발견 사항은 CSS 선택자와 HTML 조각을 포함합니다 — 저장소에서 해당 조각, 클래스 이름, 또는 주변 텍스트를 grep하세요. - 그룹의 수정 사항을 위의 수정 지침과 그룹의 단계/함정에 따라 모든 인스턴스에 적용하세요.
- 배치를 검증하세요: 작업 지시서의 검증 명령어(원래 평가 +
--baseline <이전 보고서>)를 재실행하세요. 그룹의 규칙이 "수정됨(fixed)" 아래에 나타나고new발견 사항이 0이면 그룹이 해결된 것입니다. - 수동 실패 섹션: 검토자의 증거는 명세서입니다. 그로부터 변경을 도출하고 적용한 후, 해당 기준은 사람/에이전트 재검토가 필요하다고 기록하세요 — 자동화로 확인할 수 없습니다.
- 중단 조건: 의미를 추론할 수 없는 인스턴스(알 수 없는 이미지의 대체 텍스트, 모호한 필드의 레이블)는
TODO(a11y)주석과 함께 요약에 메모를 남기세요 — 잘못된 추측은 표시된 격차보다 더 나쁩니다. - 보고: 수정 전 → 후 점수, 해결된 그룹, 새로운 발견 사항(0이어야 함), 사람에게 플래그된 항목.
VLM 의심 그룹
작업 지시서에는 vlm-* 그룹이 포함될 수 있습니다(--vlm으로 평가가 실행된 경우에만). 해당 인스턴스 행에는 비전 모델의 추론이 포함되어 있으며 — vlm-alt-quality-suspect의 경우 제안된 대체 텍스트가 포함됩니다. 제안을 초안으로 간주하세요: 실제 이미지와 대조하여 확인한 후에만 적용하고, 페이지 자체에서 확인할 수 없는 VLM 제안 변경은 절대 적용하지 마세요.
하지 말아야 할 것
- 실패: 네이티브 요소가 작동하는데
tabindex+ 키 핸들러를div에 덧붙이는 경우 - 실패: 정보 제공 이미지에
alt=""를 사용하거나,aria-label이 표시되는 텍스트와 불일치하는 경우 - 실패: 규칙을 억제하거나, 요소를 삭제하거나,
aria-hidden으로 발견 사항을 없애는 경우 - 실패: 비율을 계산하지 않고 눈대중으로 대비를 조정하는 경우
- 실패: 규칙이 사라졌음을 보여주는 검증 재실행 없이 완료되었다고 주장하는 경우
관련 스킬
a11y-evaluator— 이 스킬이 사용하는 보고서와 작업 지시서를 생성합니다