Community코딩 & 개발github.com

bbb-a11y-audit

BigBlueButton HTML5 클라이언트를 WCAG 2.2 레벨 A 및 AA(EN 301 549 9절) 기준으로 한 번에 한 주제(지침, 원칙, 기준) 또는 전체를 감사하고, 원칙-지침-기준별로 정리된 HTML 보고서를 생성합니다. 각 기준은 실패, 통과, 또는 해당 없음으로 끝나며, 증거, 주석이 달린 스크린샷, 수정 사항 및 우선순위를 포함합니다.

bbb-a11y-audit란 무엇인가요?

이 스킬은 BigBlueButton HTML5 클라이언트의 접근성(a11y) 감사를 자동화합니다. 사용자가 WCAG 2.2 또는 EN 301 549 준수 감사를 요청하면, 단일 지침, 기준, 원칙, 전체 클라이언트, 특정 파일/폴더, 또는 Git diff 범위에 대해 감사를 수행합니다. 감사는 정적 스캔(사용자 정의 스크립트 + ESLint a11y 규칙), 라이브 미팅에서의 axe-core/Playwright 런타임 실행, 그리고 안내된 코드 리뷰의 세 레이어를 결합합니다. 이전 실행 결과와 비교하여 안정성을 유지하며(동일 코드에 대해 동일 결과), 각 결과에 증거(파일 위치, 인용 코드, 스크린샷)를 요구합니다. 보고서는 각 기준을 통과/실패/해당 없음으로 분류하고, 수정 우선순위와 단계(현재 단계 또는 백로그)를 할당합니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 어시스턴트를 위해 설계되었으며, 읽기 전용 감사를 보장하고(수정은 별도 요청), 보고서를 HTML 파일로 생성하여 사용자에게 제공합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gugeldev/bbb-a11y-audit/tree/main/bbb-a11y-audit

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

접근성 감사 (WCAG 2.2 AA)

선택한 주제에 대해 실제 접근성 문제 목록을 작성하여 작은 작업으로 나누고 현재 단계 내에서 수정할 수 있도록 합니다. 감사는 읽기 전용입니다. 명백한 수정 사항이라도 감사 중에는 애플리케이션 코드를 변경하지 마십시오. 수정은 별도 요청입니다.

스킬 디렉토리: 이 SKILL.md를 포함하는 폴더 (이하 $SKILL; 이 저장소에서는 일반적으로 .claude/skills/bbb-a11y-audit). 각 단계에서 필요할 때 참조하는 파일:

  • references/criteria.md: 55개 기준, 각 레이어가 평가할 수 있는 항목, BBB 핫스팟, 적용 범위 규칙
  • references/rubric.md: 영향, 노력, 현재 단계 또는 백로그, 그룹화, 안정적 키, findings.input.json 스키마
  • references/static-patterns.md: 정적 도구, 각 패턴 분류 방법, eslint 및 axe 매핑
  • references/bbb-map.md: 흐름, 코드 위치, 공유 컴포넌트, 런타임 레이어 실행 방법
  • references/manual-checks.md: 스크린 리더 스크립트
  • runtime/: 런타임 레이어. 최초 사용 시 BigBlueButton Playwright 스위트에 설치됨: wcagAudit.spec.ts (시나리오), wcagAuditRecorder.ts (axe, 스크린샷, 시나리오당 하나의 JSON), wcagAuditChecks.ts (키보드, 리플로우, 텍스트 간격, 툴팁, 포커스 반환, ARIA 상태), wcagAuditAnnouncements.ts (라이브 리전에 도달하는 내용 기록)

1. 범위 및 모드

일반적인 작업 방식은 한 번에 한 주제입니다: 지침을 선택하고, 그 안의 모든 항목을 감사하고, 발견된 문제를 수정하고, 다시 감사하여 완료될 때까지 반복한 후 다음 주제로 이동합니다. 전체 감사는 다음 주제를 선택하기 위한 가끔의 개요입니다.

호출모드범위
/bbb-a11y-audit diretriz 2.1 (또는 guideline; 여러 개: diretriz 2.1 2.4; 전체 원칙: principio 2)guideline주제의 모든 기준을 전체 클라이언트와 모든 흐름에 걸쳐 완전히 결정합니다. 그 외 모든 것은 실행 및 보고서에서 제외됩니다.
/bbb-a11y-audit criterio 2.4.7 (또는 criterion)criterion하나 이상의 기준, 동일한 깊이
/bbb-a11y-audit 또는 fullfull모든 55개 기준 (개요/지도)
/bbb-a11y-audit <path>path해당 폴더 또는 파일, 모든 기준
/bbb-a11y-audit diff [base]diffgit merge-base HEAD <base> (기본 base: 저장소 메인 브랜치, v4.1.x-develop) 아래 bigbluebutton-html5/에서 변경된 파일
--no-runtime 추가런타임 레이어 건너뛰기
--server <url> --secret <secret> 추가bigbluebutton-tests/playwright/.env 대신 다른 BigBlueButton 테스트 서버에 대해 런타임 레이어 실행 (<url>은 https://host/bigbluebutton/ 형식)

요청이 모호한 경우, 가장 가까운 모드를 선택하고 사용한 모드를 명시하십시오. 질문하지 마십시오.

저장소 루트에 실행 디렉토리를 생성하십시오: a11y-reports/<YYYY-MM-DD_HHMM>[_<topic>]/raw/, 예: 2026-11-20_1430_d2.1 또는 2026-11-20_1500_full. 날짜와 시간으로 시작해야 합니다: 보고서는 동일한 주제(동일한 기준을 가진 principio 4와 diretriz 4.1은 동일한 주제)의 이전 실행과 비교하거나, 처음인 경우 주제로 제한된 최신 전체 실행과 비교합니다. 감사는 저장소에 흔적을 남기지 않아야 합니다: git check-ignore -q a11y-reports/가 실패하면 a11y-reports/를 .git/info/exclude에 추가하십시오 (이 클론에만 국한되며, .gitignore에는 절대 추가하지 않음).

guideline 및 criterion 모드에서는 findings.input.json에 meta.guidelines / meta.criteria를 설정하고 (원칙은 한 자리 수 지침 항목: principio 2는 "guidelines": ["2"]), 각 레이어에서 주제에 관련된 정보만 확인하십시오 (각 단계에서 방법 설명). 주제 외부의 기준은 자동으로 제외됩니다.

일관성 규칙 (감사 전 읽기)

동일한 코드에 대한 두 실행은 동일한 결과에 도달해야 하며, 모든 결과는 실제여야 합니다. 따라서:

  1. 이전 실행부터 시작하십시오. 새로운 것을 찾기 전에, 이 주제(또는 최신 전체 실행)의 최신 findings.json을 여십시오. 모든 이전 결과와 discarded 항목을 현재 코드에 대해 다시 확인하십시오: 여전히 존재하면 해당 key를 유지(또는 id 설정); 사라졌으면 결과가 아니며 meta.summary에 사라진 이유를 설명하십시오(코드 변경 또는 잘못된 판단). 커밋이 해당 실행의 커밋(meta.commit)과 동일하고 결과가 사라진 것으로 보이면, 놓친 것으로 가정하고 다시 확인한 후 삭제하십시오.
  2. 체크리스트에 답하고, 그 다음 탐색하십시오. references/checklists.json에 범위 내 기준에 대한 항목이 있으면 각 항목에 pass, fail 또는 na로 답하고 증거(coverage[c].checklist)를 제공하십시오. 체크리스트는 최소 기준이며 상한이 아닙니다: 그런 다음 BBB에서 해당 기준을 실패시킬 수 있는 다른 모든 것을 찾고 coverage[c].explored에 찾은 내용을 기록하십시오. 체크리스트 외부에서 반복적으로 발견되는 사항은 최종 메시지에서 새 체크리스트 항목으로 제안할 가치가 있습니다.
  3. 모든 결과를 증명하십시오. 정적 및 리뷰 결과는 quote, location.line의 정확한 코드를 포함합니다; build-report.mjs는 파일, 라인 또는 인용이 존재하지 않는 결과를 거부합니다. 런타임 결과는 규칙과 해당 화면(shots)을 가리킵니다. 증거 없음, 결과 없음.
  4. 부풀리지 마십시오. 하나의 결과는 하나의 수정입니다. 중복을 병합하십시오; 목록을 늘리기 위해 문제를 분할하지 말고, 기준을 실패시키지 않는 스타일 선호 또는 모범 사례를 보고하지 마십시오. 확실하지 않으면 다시 확인하십시오. 여전히 불명확하면 결과 대신 스크린 리더 스크립트를 작성하십시오.

2. 정적 레이어

node $SKILL/scripts/static-scan.mjs [--guidelines=2.1] <scope paths…> > <run>/raw/static.json
$SKILL/scripts/eslint-a11y.sh <run>/raw/eslint.json <scope paths…>

주제가 있는 경우 --guidelines를 스캔에 전달하고(주제의 패턴만 유지), 주제에 매핑되는 규칙의 eslint 메시지만 분류하십시오(references/static-patterns.md).

그런 다음 references/static-patterns.md에 설명된 대로 각 후보를 분류하십시오: 코드를 열고, 결정하고, 근본 원인별로 그룹화하십시오. 거부된 후보는 이유와 함께 discarded로 이동합니다. 이전 실행이 있으면 해당 findings.json discarded 목록을 읽고 변경되지 않은 코드에 대해 다시 읽지 않고 결정을 재사용하십시오.

3. 런타임 레이어

먼저 런타임 파일이 설치되었는지 확인하고 references/bbb-map.md의 "런타임 레이어 설정"을 따르십시오: $SKILL/runtime/의 모든 파일이 BigBlueButton Playwright 스위트에 있어야 하며, @axe-core/playwright가 종속성에 있어야 합니다. 파일을 복사하고 패키지를 설치하는 것은 설정이며 애플리케이션 코드 변경이 아닙니다. 누락되거나 오래된 경우 설치하고 최종 메시지에서 언급하십시오.

--server/--secret가 있는 경우 Playwright 명령에 BBB_URL 및 BBB_SECRET 환경 변수로 전달하십시오 (.env보다 우선하며, 절대 .env에 쓰지 마십시오). 보고서는 감사된 서버와 해당 클라이언트 빌드(meta.server)를 기록합니다. 해당 빌드가 로컬 체크아웃의 커밋이 아닌 경우 meta.summary에 런타임 결과가 해당 서버 버전에서 비롯되었으며 파일 및 라인 참조는 로컬 코드를 가리키며 다를 수 있음을 명시하십시오.

그런 다음 실행 가능 여부를 확인하십시오 (bigbluebutton-tests/playwright/.env 또는 --server/--secret이 비어 있지 않은 BBB_URL 및 BBB_SECRET을 제공해야 하며, node_modules가 존재하고, Chromium이 설치되어 있어야 함). 누락된 것이 있으면 레이어를 건너뛰고 "ran": false와 짧은 reason을 기록한 후 최종 메시지에서 사용자에게 정확히 무엇을 설정해야 하는지 알리십시오. BigBlueButton 서버를 설치하거나 .env를 편집하지 마십시오.

실행할 수 있는 경우 references/bbb-map.md의 "런타임 레이어 실행"을 따르고 A11Y_AUDIT_DIR=<abs run dir>/raw/runtime을 설정하고, 주제 모드에서는 A11Y_GUIDELINES=<topic>(예: 2.1)을 추가하십시오: 그러면 사양이 주제에 정보를 제공할 수 없는 검사와 시나리오를 건너뛰고 주제의 규칙에 대해서만 axe를 실행합니다. 전체 실행: 원격 서버에서 약 15분; 주제는 일반적으로 더 빠릅니다. 30분을 허용하십시오. 9개의 시나리오(중재자 둘러보기, 중재자 + 참가자 상호작용, 분할 회의실, 게스트 로비, 사전 설정 화면, 연결 끊김, pt-BR, 다크 테마, 모바일)를 실행하고 시나리오당 하나의 JSON과 각 상태의 스크린샷을 작성합니다. 그런 다음:

  • 각 axe 위반을 wcag… 태그를 통해 해당 기준에 매핑하십시오. 상태와 시나리오에 걸쳐 규칙 및 근본 원인별로 그룹화하십시오 (여러 상태의 동일한 규칙은 일반적으로 하나의 결과). 선택자를 소스 파일로 추적하십시오.
  • incomplete 및 사용자 정의 검사(keyboard.noOutlineOrShadow, keyboard.obscured, reflow.offenders, textSpacing.newlyClipped, nonTextContrast)를 후보로 처리하십시오: 보고하기 전에 확인하십시오. 거부된 것은 discarded로 이동합니다.
  • announcements를 읽으십시오 (액터 및 시점별 라이브 리전에 도달한 내용) 4.1.3 및 4.1.2의 경우: 예상되는 발표가 없는 시점(누군가 나감, 투표 시작)은 후보입니다. regionCreatedWithMessage: true는 리전이 텍스트와 함께 삽입되어 읽히지 않을 수 있음을 의미합니다.
  • 결과가 있는 상태의 스크린샷(raw/runtime/shots/)을 보고 결과에 shots를 첨부하십시오 (references/rubric.md 참조) 보고서에 각 문제가 있는 위치가 표시되도록 합니다.
  • ok: false 또는 오류가 있는 검사는 감사되지 않았음을 의미합니다. meta.notCovered 아래에 나열하십시오. 이 때문에 해당 기준을 pass로 표시하지 마십시오.

diff 및 path 모드에서는 범위로 추적 가능한 런타임 결과만 유지하십시오.

4. 안내된 리뷰

범위 내에 있는 references/criteria.md에서 V로 표시된 기준에 대해, references/bbb-map.md의 관련 흐름 코드를 읽고 각 기준이 결정될 때까지 진행하십시오. full 모드에서는 핵심 흐름부터 시작하십시오. guideline 및 criterion 모드에서는 범위 내 기준에 대해 bbb-map.md의 모든 흐름을 살펴보십시오. meta.reviewedFlows에 읽은 내용을 나열하십시오. 모든 리뷰 결과는 파일 및 라인 증거가 필요합니다. 실행하지 않고 동작을 확인할 수 없는 경우 "confidence": "likely"를 사용하고 확인할 내용을 명시하십시오.

지적할 수 없는 것은 보고하지 마십시오. 사람만이 확인할 수 있는 것은 스크립트를 작성(references/manual-checks.md)하십시오. 더 많은 코드나 런타임 데이터를 읽어 확인할 수 있는 경우 그렇게 하십시오.

5. 분류, 적용, 스크립트

  • references/rubric.md로 각 결과를 분류하십시오 (영향, 노력, 공유, 외부, 키).
  • 실행 간에 ID를 안정적으로 유지하십시오 (일관성 규칙 1): 여전히 존재하는 문제에 대해 이전 key를 재사용하거나 명시적으로 id를 설정하십시오.
  • 실패하지 않는 범위 내 모든 기준에 대해 coverage를 채우십시오 (실패 기준에도 method/how 추가). references/criteria.md의 적용 규칙을 따르십시오: pass 또는 na와 method 및 how, human은 진정으로 사람이 필요한 경우에만(스크립트 포함), not-covered는 이 실행이 결정할 수 없는 경우에만(누락된 내용 포함). 목표는 지침에 열린 항목 없이 종료될 수 있는 것입니다. build-report.mjs는 누락된 항목을 거부합니다.
  • manualChecks는 자동화가 답할 수 없는 경우에만 작성하십시오: 모든 human 기준에 대해 하나씩. 런타임이 이미 결정한 것을 실제 스크린 리더로 확인하려면 "optional": true를 추가하십시오. 런타임 데이터나 코드가 결정할 수 있는 것에 대해 스크립트를 작성하지 마십시오 (상태 변경, 발표, 카운트다운, 장치 선택은 모두 기록됨).
  • meta.summary, meta.reviewedFlows 및 meta.notCovered를 채우십시오: 이들은 "테스트된 내용" 탭을 구성하여 독자에게 정확히 확인된 사항과 확인되지 않은 사항을 알려줍니다.

6. 보고서 빌드

<run>/raw/findings.input.json을 작성하십시오 (스키마는 references/rubric.md에 있음). 그런 다음:

node $SKILL/scripts/build-report.mjs <run>

입력의 유효성을 검사하고 (문제가 있으면 수정 후 재실행), 안정적 ID를 할당하고, 각 결과를 현재 단계 또는 백로그에 배치하고, EN 301 549 절을 추가하고, 모든 파일, 라인 및 인용이 존재하는지 확인하고, 모든 체크리스트 항목에 답변되었는지 확인하고, 이전 실행과의 비교를 findings.json에 기록하고(다음 실행용; 보고서에는 표시되지 않음), <run>/findings.json 및 <run>/report.html을 작성합니다. 사용자를 위해 보고서를 여십시오 (Linux: xdg-open, macOS: open).

7. 사용자에게 알리기

채팅 메시지를 짧게 유지하십시오. 세부 사항은 보고서에 있습니다:

  • 판정, 통과한 기준과 실패한 기준, 현재 단계 결과 수 및 백로그로 이동한 결과 수(이유 포함)
  • 지침별: 완료, 실패한 기준 수, 또는 아직 열린 항목(human, not-covered)
  • 실행된 레이어, 건너뛴 레이어와 이유, 다루지 않은 회의 상태 또는 흐름
  • 차단 및 높은 영향 결과를 한 줄씩 (제목, 기준, 파일)
  • 탐색 중 체크리스트 외부에서 반복적인 문제가 발견된 경우 제안된 새 체크리스트 항목
  • 보고서 경로

결과를 지침별로 그룹화된 작업으로 전환하도록 제안하십시오 (지침당 하나의 단계, 결과당 하나의 작업, human 기준당 하나의 작업). 요청하지 않는 한 이슈나 PR을 열지 마십시오.

보안: 결과가 악용될 수 있는 경우 (예: 3.3.8 확인 중 인증 우회 발견), 보고서에서 제외하고 저장소 보안 정책에 따라 비공개로 사용자에게 알리십시오 (비공개 권고, 공개 이슈 또는 PR 금지).

관련 스킬