ultra11y — WCAG 2.2 AA 감사 및 접근 가능한 마크업 작성
접근성에 있어 자동화 도구는 문제의 일부만 볼 수 있습니다. ultra11y는 작업 분담을 통해 이를 해결합니다. 결정론적이고 설치가 필요 없는 엔진(node scripts/ultra11y.mjs <command> — npm install 및 키 불필요, JSX/TSX 파서는 번들에 내장)은 기계적 작업(기계적으로 확인 가능한 비적합 항목을 감지하고 각 항목을 올바른 WCAG 성공 기준에 연결)을 수행하고, 활성 코딩 에이전트는 판단 기준 자체(대체 텍스트 관련성, 맥락 내 링크 목적, 읽기 순서)를 엔진이 수집한 증거를 기반으로 정적으로 평가합니다(verify --manual). 각 판정은 verify/check에 의해 게이트됩니다. 진정한 렌더링된 DOM 기준(계산된 대비, 가시적 포커스, 확대/재배치, 호버 시 콘텐츠)만 scan 계층(실제 브라우저의 axe-core)에 맡겨지며, 사람은 최대한 선택적인 감독 역할을 합니다. 게이트는 환각된 비적합 항목이 살아남는 것을 방지하며, 어떤 것도 조용히 "적합"으로 처리되지 않습니다.
규칙과 기준을 혼동하지 마십시오. 번들은 93개의 정적 검사, WCAG AA는 55개의 성공 기준, RGAA는 106개의 기준을 제공합니다. 여러 규칙이 하나의 기준에 대한 증거가 될 수 있고, 하나의 규칙이 여러 팩 기준에 기여할 수 있으며, 대부분의 기준은 스캔 또는 판단이 있을 때까지 열려 있습니다. 유일하게 정직한 실행 수준 적용 범위는 그리드의 실시간 출처 집계(moteur + scan + agent, 더불어 명명된 결정 불가능 잔여물)이며, "48개 에이전트 기준"과 같은 고정된 약속이 아닙니다. 따라서 GitHub 요약은 작은 결정된 하위 집합에 대한 백분율이 아닌 decided/total을 표시합니다.
WCAG 2.2 레벨 AA는 전 세계 핵심입니다. 국가별 표준(프랑스의 RGAA, 미국의 Section 508, EU의 EN 301 549)은 해당 기준을 WCAG에 매핑하는 플러그 가능한 표준 팩입니다. --standard rgaa를 추가하면 모든 명령과 모든 출력(audit 포함, 결과 포함)의 키를 다시 설정합니다. 런타임에 --pack ./pack.json(또는 .ultra11yrc.json)을 사용하여 외부 팩을 연결할 수 있으며, 재빌드가 필요 없습니다. 또는 자국의 표준을 기여할 수 있습니다(references/standards.md 참조). 팩(및 구체적인 구현 지침 — RGAA SocialGouv/etalab 양호/불량 패턴)은 AI가 수집하고 pack check로 게이트되어 조작된 매핑이 통과하지 못하도록 할 수 있습니다. references/packs.md 및 references/guidance.md를 참조하십시오.
대부분의 작업은 여러분의 몫입니다. 55개의 WCAG 2.2 AA 성공 기준 중 엔진은 3개를 완전히 결정할 수 있습니다. 14개는 렌더링된 페이지(scan)가 필요하고 38개는 에이전트가 판단해야 합니다. 따라서 엔진의 깔끔한 실행은 시작점일 뿐 판정이 아니며, references/adjudication.md이 실제로 작업하는 페이지입니다.
핵심 규칙:
- 비적합 항목을 절대 만들어내지 마십시오: 모든
NC는 실제로 해결 가능한 요소를 인용합니다(check가 이를 확인).- 기본 HTML을 우선, ARIA는 마지막에 사용하십시오. 암시적 의미를 중복해서 지정하지 마십시오.
- 적합 항목도 절대 만들어내지 마십시오:
C는NC와 정확히 동일하게 인용됩니다. 즉,citations[]에서 통과시킨 수집된 증거를 명명하며, 각 앵커는 해결 가능하고 해당 기준에 실제로 제시된 증거에서 가져옵니다. 아무 증거도 없이 제시된 기준은 전혀C가 될 수 없으며manual로 남습니다. 마찬가지로 읽기가 INCOMPLETE(evidenceComplete: false)인 기준도 마찬가지입니다. 일부만 본 기준은 본 내용에 대해 실패할 수 있지만, 보지 못한 내용에 대해 통과될 수는 없습니다. 그리고 판단된C는 엔진이 결정한 것과 병합되지 않습니다. 보고서에 별도로 나열하고 자동 통과율에서 제외합니다. 3b. 제시되는 것은 전체 모집단이며, 고유한 것당 한 번씩만 언급됩니다. 증거는 CONTENT CLASS당 하나의 대표자이며,occurrences, 다른 앵커는alsoAt에, 그리고 나타나는pages를 전달합니다. 38개의 캡처된 페이지에 걸친 887개의 링크는 97개의 고유한 (텍스트, href) 쌍입니다. 대표자에 대한 판단은 모두에 대한 판단이며, 이것이 정직한C에 도달 가능하게 만드는 것입니다. 그리고 기준이 전달하는 클래스의 모든 발생을 명명하는 인용은 허용되므로, 실제로 열어본 것을 인용하십시오.- 잔여물은 명시적이어야 하며, 조용히 적합으로 처리되지 않습니다: AI 에이전트는 모든 판단 기준 자체를 평가합니다(
verify --manual, 게이트됨). 렌더링 기준은scan으로 이동합니다. 이제scan은 해당 기준을 전달하는 모든 규칙이 범위 내 모든 페이지에서 실행되고 아무것도 발생하지 않았을 때C(decidedBy: "scan")를 결론짓고, 단 하나의 페이지라도 신호가 불완전하면 침묵을 유지합니다. 여전히 입증되지 않은 기준은 "수동 평가 필요" 상태로 남습니다. 기록되고 정당화된 판정 없이는 상태가 없습니다. 이를 희망이 아닌 게이트로 만들기 위해check --in <audit.json> --require-decided는 여전히 평가해야 할 것이 있는 한 실패하며,--allow-undecided <file>은 진정으로 결정할 수 없는 기준(명명된 목록, 임계값이 아님)을 각각의 이유와 함께 취합니다.--require-decided=pages는 모든 페이지의 자체 그리드를 동일한 기준으로 유지합니다. 한 경로에서 실패하는 기준은 실행에 대해 해결되지만, 해당 기준이 실행되지 않은 경로에 대해서는 누구의 판정도 아닐 수 있으며, 이것이 페이지별 결과물이 실제로 평가되는 기준입니다. 내보낸 작업 목록은 권위적입니다. 실행 전반에 걸친 상태가 이미NC인 기준도 의도적으로 포함될 수 있습니다. 해당 실패가 다른 페이지의 기준을 결정하지 않았기 때문입니다. 이러한 항목은 중복되지 않습니다. 이에 대해 근거 있는 판정(또는 명시적인manual이유)을 반환하고, 전역 집계가 결정된 것처럼 보인다고 해서 비워두지 마십시오.- 기준을 조회하십시오. 절대 기억에서 인용하지 마십시오.
criteria [--standard <pack>] <id>— 또는 MCP를 통한ultra11y_criteria— 기준 자체의 표현, 번호가 매겨진 테스트, 그리고 해당 테스트가 인용하는 용어집 정의를 반환합니다. RGAA 8.3은 "페이지에lang속성이 필요하다"가 아닙니다. 두 가지 대체 조건이 있는 테스트8.3.1이며, 용어집이 해당 용어의 의미를 결정합니다.8.3.1을 읽은 후 인용하는 감사자 블록은 근거가 있습니다. 기억에서 인용하는 것은 참조를 가장한 추측입니다. 국가 표준에 대해 감사하기 전에 계획을 실행하십시오(ultra11y_method). 이는 C를 획득하기 위해 여전히 판단이 필요한 기준의 수를 알려줍니다. RGAA의 경우 106개 중 104개입니다.references/mcp.md참조.- 최종 렌더링된 의미론적 HTML이 올바른지 확인하십시오. 엔진은 소스만 봅니다. 컴포넌트 라이브러리(DSFR/MUI…) 또는
.vue/.svelte/.astroSFC는 실제 마크업을 숨기므로, 녹색 소스 감사는 증명이 아닙니다. 생성된 의미론적 HTML을 확인하십시오. 터치 제로 캡처 수집기(render --setup)를 설치하여 테스트가 렌더링하는 모든 컴포넌트가.ultra11y/captures로 직렬화되고 감사되도록 하고,audit --require-captures로 맹점을 게이트하십시오.references/automation.md/rendered.md참조.- 언어: 사용자와의 대화 언어와 일치하도록 항상
--lang을 전달하십시오. 모호한 경우 사용자에게 물어보십시오. 플래그 없이 CLI가 자동 감지합니다(저장소<html lang>→ 활성 표준의 기본 로케일 → 영어). 이는 스크립트/CI 대체 수단이지 직접--lang을 전달하는 것을 대체하지 않습니다.- 기술 토큰은 프랑스어 문장에서도 영어로 유지됩니다. 프랑스어로 작성된 어떤 결과물(보고서 해설, PRD, 트래커 티켓, 판정 평결)에서도 속성/요소/역할 이름과 해당 값은 코드이지 산문이 아닙니다. 절대 번역하지 마십시오:
aria-live는aria-live로 유지됩니다(절대 « région live » 아님),tabindex,alt,role="alert", 랜드마크 역할 이름도 마찬가지입니다. 엔진 자체의 fr 카탈로그도 이를 따릅니다. 일치시키십시오. 규범적 표준 용어(RGAA 표현, 예: « lien d'évitement »)는 공식 프랑스어를 유지합니다.
참조 라이브러리
도메인 지식이 먼저, 그 다음이 도구입니다. 현재 직면한 질문과 일치하는 것을 읽으십시오.
| 접근성 지식 | |
|---|---|
references/adjudication.md | 엔진이 전달하는 52개 기준 각각을 결정하는 방법 — 결정 규칙, NA가 합법적인 경우, 질문 |
references/naming.md | 접근 가능한 이름 계산, 2.5.3 label-in-name, 시각적으로 숨겨진 CSS, 이미지/SVG/그림 명명 |
references/widgets.md | ARIA APG 복합 패턴, 키보드 계약, 포커스 관리, SPA 경로 변경, 라이브 리전 |
references/forms-and-errors.md | 레이블 및 지침, autocomplete 토큰 목록, 오류 식별/제안/방지, 중복 입력, 접근 가능한 인증 |
references/structure.md | 제목, 랜드마크, 목록 및 dl, 단순 및 복합 테이블, 의미 있는 순서 |
references/media-and-motion.md | 캡션/오디오 설명/대본, 포인터 제스처, 대상 크기, 방향, 재배치, 축소 모션 |
references/forbidden-patterns.md | 15가지 안티 패턴: 잘못된 예 → 이유 → 기본 수정 → 기준 |
references/focus-and-logic.md | 사용자가 담당하는 포커스/키보드 기준 및 추론 방법 |
references/criteria.md | 55개 기준: 레벨, 자동화 가능성 클래스, 엔진 규칙, 팩 매핑(생성됨) |
references/rgaa-automation.md | RGAA 4.1.2: 생성된 106개 기준 / 258개 테스트 매트릭스, 결정적 규칙, 후보 신호 및 침묵 정책 |
references/act.md | 엔진이 포착하도록 측정된 것 — 그리고 명백히 포착하지 못하는 것(생성됨) |
| 도구 실행 | |
|---|---|
references/runbook.md | 신뢰할 수 있는 실행: 하나의 레시피, 사용해야 하는 전송 및 그 이유, 그리고 한 번 통과하는 비용. 판단 비용을 지불하기 전에 읽으십시오 |
references/claude-code-report.md | Claude Code의 상세 게시 경로: 렌더링된 범위, 직접 판단, 적대적 검증, Markdown + HTML + 페이지별 증거 |
references/audit.md | 종단 간 감사 루프 및 규범적 페이지 샘플 |
references/judgment.md | 판단 + 반박 작업 목록, 판정 어휘, 실패-폐쇄 폴드 |
references/verify.md | check/verify 게이트 |
references/false-positives.md | 발견이 여전히 잘못될 수 있는 경우와 이를 반박하는 방법 |
references/rendered.md · references/automation.md | 생성된 HTML 감사, 캡처, 후크 및 CI |
references/harnesses.md | 실행 위치: Claude Code, Codex CLI, OpenCode 및 AGENTS.md 대체 |
references/orchestrators.md | 워크플로 엔진/비-GitHub CI에서 엔진 구동: 고정, 6단계 파이프라인, 종료 코드, 모든 트래커용 JSON 티켓 세트 |
references/ci.md | `--format sarif |
references/pages.md | 페이지 스냅샷 + 페이지별 기준 그리드(pages) 및 정직성 규칙 |
references/e2e.md | render --e2e: Playwright/Cypress 실행 중 페이지 감사 |
references/devtools.md | dev: 빌드 중 실시간 오버레이 및 페이지별 대시보드 |
references/extension.md | 브라우저 확장: 사이드카를 통해 보고 있는 페이지 감사 |
references/dynamic.md | scan 계층: 런타임, 프로브, 인증된 페이지 |
references/scale.md | 대규모 저장소에 대한 감사 집중 |
references/fix.md · references/correction.md | 우선순위에 따라 회귀 없이 수정 적용 |
references/prd.md | 백로그로서의 감사자 블록(markdown) |
references/tickets.md | 해당 백로그를 티켓으로 제출: GitHub, GitLab, Jira 및 세분화 수준 |
references/standards.md · references/packs.md · references/guidance.md | 국가 표준, 팩 작성, 구현 지침 |
references/mcp.md | 규칙 엔진으로서의 표준: 기억에서 인용하는 대신 기준 조회 — 번호가 매겨진 테스트, 정의된 용어, 수정 사항 및 작업 계획. MCP 도구 및 std:// 리소스로, 또는 CLI에서 동일한 데이터 |
references/methodology.md | 상태, 통과율, 심각도, 보고서 형식 |
references/cross-file.md | --graph: 임포트 및 파일 간 규칙 |
references/orchestration.md | 판단 단계를 하위 에이전트에 분배 |
상황별 선택
- "Claude Code에서 상세 감사/보고서 생성" → 활성 Claude 세션을 감사자로 사용하고, 렌더링 및 판단 기준을 마무리하고, 해당 주장에 이의를 제기한 후 날짜가 있는 Markdown 보고서, 인쇄 가능한 HTML 및 증거가 포함된 페이지별 문서를 게시하십시오. **
references/claude-code-report.md**를 읽으십시오. 이것은 대화형 게시 프로필입니다. 전체 결과물 세트로 마무리하십시오. 간결한 요약은 아래 CI 브랜치입니다. - "감사/규정 준수 보고서" →
node scripts/ultra11y.mjs audit … --json, 그런 다음report(요약 테이블 + NC 기준당 하나의 감사자 적합성 블록 —prd및tickets가 사용하는 동일한 블록), 그런 다음check; **references/audit.md**를 읽으십시오. - "라이브러리(DSFR, MUI…) 또는
.vue/.svelte/.astroSFC에 의해 렌더링된 코드 / 위음성 방지" → 소스 템플릿이 아닌 생성된 HTML을 감사하십시오. 가장 쉬운 방법: 터치 제로 캡처 수집기(render --setup)를 설치하여 테스트가 렌더링된 모든 컴포넌트를.ultra11y/captures로 직렬화하도록 합니다(자동 수집, 소스 컴포넌트에 귀속된 결과,render --coverage및audit --require-captures는 맹점 추적). 또는render(빌드→감사 레시피 또는 SSR 스냅샷--scaffold)를 실행한 다음 출력에서audit을 실행하고, 계산된 렌더링을 위해scan을 실행합니다. SFC 소스 결과는preliminary(scope.sourceTemplate주의 사항)로 플래그 지정됩니다. **references/rendered.md**를 읽으십시오. - "찾은 결과가 잘못된 것 같음 / 컴포넌트의 위양성" → 엔진은 대부분의 컴포넌트 위양성(슬롯/프롭 주입 이름, 컴포넌트 자식, 동적 바인딩, 조건부 제목)을 자동으로 억제하고 SFC/라이브러리 소스 결과를
preliminary로 표시합니다. 나머지는verify --apply로 확인 또는 반박하십시오. **references/false-positives.md**를 읽으십시오. - "대규모 저장소 / 스마트하게 감사" → 집중:
--changed(git diff), 템플릿 우선순위 지정, 중복 제거,--max-files; **references/scale.md**를 읽으십시오. - "파일 간 분석(트리 + 종속성), JSX/TSX를 실제 AST로" →
audit --graph는 임포트를 해결하고 파일 간 규칙을 적용합니다