Communitygithub.com

WCAG 2.2 접근성 감사

자동화 테스트, 수동 검증 및 수정 지침을 통해 WCAG 2.2 접근성 감사를 수행합니다. 웹사이트 접근성 감사, WCAG 위반 수정, 접근성 디자인 패턴 구현 시 사용하세요.

WCAG 2.2 접근성 감사란 무엇인가요?

이 기술은 WCAG 2.2 지침에 따라 웹 콘텐츠의 접근성을 종합적으로 감사하고 수정하는 데 사용됩니다. Claude Code, Cursor, Codex 등 AI 에이전트 기반 개발 환경에서 활용할 수 있으며, WCAG 적합성 수준(A, AA, AAA)과 POUR 원칙(지각 가능, 운용 가능, 이해 가능, 견고)에 기반한 체계적인 감사 체크리스트를 제공합니다. 감사 자동화, 수동 검증, 수정 패턴 구현을 단계별로 안내하며, 누락된 대체 텍스트, 키보드 접근성 문제, 색상 대비 부족 등 일반적인 위반 사항을 식별하고 구체적인 HTML/CSS/JavaScript 수정 예시를 제공합니다. 또한 VPAT(Voluntary Product Accessibility Template) 준수, ADA/Section 508 요구 사항 충족, 접근성 소송 대비 등 실무적 필요에 맞춰 설계되었습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ulasalyesil/personal-website-v2/tree/HEAD/.agent/skills/wcag-audit-patterns

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

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

미리보기

스킬 README에서

WCAG 2.2 접근성 감사 preview
WCAG 2.2 접근성 감사 preview

문서

WCAG 감사 패턴

WCAG 2.2 지침에 따라 웹 콘텐츠를 감사하고 실행 가능한 수정 전략을 제공하는 종합 가이드입니다.

이 기술을 사용해야 하는 경우

  • 접근성 감사 수행
  • WCAG 위반 사항 수정
  • 접근성 컴포넌트 구현
  • 접근성 소송 대비
  • ADA/Section 508 요구 사항 충족
  • VPAT 준수 달성

핵심 개념

1. WCAG 적합성 수준

수준설명필요 조건
A최소 접근성법적 기준
AA표준 적합성대부분의 규정
AAA향상된 접근성특수 요구 사항

2. POUR 원칙

지각 가능: 사용자가 콘텐츠를 인식할 수 있는가?
운용 가능: 사용자가 인터페이스를 조작할 수 있는가?
이해 가능: 사용자가 콘텐츠를 이해할 수 있는가?
견고: 보조 기술과 호환되는가?

3. 영향별 일반적인 위반 사항

심각 (차단):
├── 기능 이미지에 대한 대체 텍스트 누락
├── 대화형 요소에 키보드 접근 불가
├── 양식 레이블 누락
├── 자동 재생 미디어 (컨트롤 없음)

심각:
├── 색상 대비 부족
├── 스킵 링크 누락
├── 접근 불가능한 사용자 정의 위젯
├── 페이지 제목 누락

중간:
├── 언어 속성 누락
├── 불명확한 링크 텍스트
├── 랜드마크 누락
├── 잘못된 제목 계층 구조

감사 체크리스트

지각 가능 (원칙 1)

## 1.1 텍스트 대체

### 1.1.1 비텍스트 콘텐츠 (레벨 A)

- [ ] 모든 이미지에 대체 텍스트가 있는가
- [ ] 장식용 이미지에 alt=""가 있는가
- [ ] 복잡한 이미지에 긴 설명이 있는가
- [ ] 의미가 있는 아이콘에 접근 가능한 이름이 있는가
- [ ] CAPTCHA에 대체 수단이 있는가

확인:

```html
<!-- 좋은 예 -->
<img src="chart.png" alt="1분기에서 2분기로 매출이 25% 증가했습니다" />
<img src="decorative-line.png" alt="" />

<!-- 나쁜 예 -->
<img src="chart.png" />
<img src="decorative-line.png" alt="장식용 선" />
```

1.2 시간 기반 미디어

1.2.1 오디오 전용 및 비디오 전용 (레벨 A)

  • 오디오에 텍스트 대본이 있는가
  • 비디오에 오디오 설명 또는 대본이 있는가

1.2.2 자막 (레벨 A)

  • 모든 비디오에 동기화된 자막이 있는가
  • 자막이 정확하고 완전한가
  • 화자 식별이 포함되었는가

1.2.3 오디오 설명 (레벨 A)

  • 비디오에 시각적 콘텐츠에 대한 오디오 설명이 있는가

1.3 적응 가능

1.3.1 정보 및 관계 (레벨 A)

  • 제목에 적절한 태그(h1-h6) 사용
  • 목록에 ul/ol/dl 사용
  • 표에 헤더가 있는가
  • 양식 입력에 레이블이 있는가
  • ARIA 랜드마크가 있는가

확인:

<!-- 제목 계층 구조 -->
<h1>페이지 제목</h1>
<h2>섹션</h2>
<h3>하위 섹션</h3>
<h2>다른 섹션</h2>

<!-- 표 헤더 -->
<table>
  <thead>
    <tr>
      <th scope="col">이름</th>
      <th scope="col">가격</th>
    </tr>
  </thead>
</table>

1.3.2 의미 있는 순서 (레벨 A)

  • 읽기 순서가 논리적인가
  • CSS 위치 지정이 순서를 깨뜨리지 않는가
  • 포커스 순서가 시각적 순서와 일치하는가

1.3.3 감각 특성 (레벨 A)

  • 지침이 모양/색상에만 의존하지 않는가
  • "빨간 버튼을 클릭하세요" → "제출(빨간 버튼)을 클릭하세요"

1.4 구별 가능

1.4.1 색상 사용 (레벨 A)

  • 색상이 정보 전달의 유일한 수단이 아닌가
  • 링크가 색상 없이도 구별 가능한가
  • 오류 상태가 색상에만 의존하지 않는가

1.4.3 대비 (최소) (레벨 AA)

  • 텍스트: 4.5:1 대비 비율
  • 큰 텍스트(18pt+): 3:1 비율
  • UI 컴포넌트: 3:1 비율

도구: WebAIM 대비 검사기, axe DevTools

1.4.4 텍스트 크기 조정 (레벨 AA)

  • 텍스트가 200%로 조정되어도 손실 없음
  • 320px에서 수평 스크롤 없음
  • 콘텐츠가 적절히 재배치됨

1.4.10 재배치 (레벨 AA)

  • 400% 확대에서 콘텐츠 재배치
  • 2차원 스크롤 없음
  • 320px 너비에서 모든 콘텐츠 접근 가능

1.4.11 비텍스트 대비 (레벨 AA)

  • UI 컴포넌트에 3:1 대비
  • 포커스 표시기가 보이는가
  • 그래픽 객체가 구별 가능한가

1.4.12 텍스트 간격 (레벨 AA)

  • 간격 증가 시 콘텐츠 손실 없음
  • 줄 높이: 글꼴 크기의 1.5배
  • 문단 간격: 글꼴 크기의 2배
  • 글자 간격: 글꼴 크기의 0.12배
  • 단어 간격: 글꼴 크기의 0.16배

### 운용 가능 (원칙 2)

```markdown
## 2.1 키보드 접근 가능

### 2.1.1 키보드 (레벨 A)
- [ ] 모든 기능이 키보드로 접근 가능한가
- [ ] 키보드 트랩이 없는가
- [ ] 탭 순서가 논리적인가
- [ ] 사용자 정의 위젯이 키보드로 작동 가능한가

확인:
```javascript
// 사용자 정의 버튼은 키보드로 접근 가능해야 함
<div role="button" tabindex="0"
     onkeydown="if(event.key === 'Enter' || event.key === ' ') activate()">
```

### 2.1.2 키보드 트랩 없음 (레벨 A)

- [ ] 모든 컴포넌트에서 포커스를 이동할 수 있는가
- [ ] 모달 대화상자가 포커스를 올바르게 트랩하는가
- [ ] 모달 닫힌 후 포커스가 돌아오는가

## 2.2 충분한 시간

### 2.2.1 시간 조정 가능 (레벨 A)

- [ ] 세션 시간 초과를 연장할 수 있는가
- [ ] 시간 초과 전 사용자에게 경고하는가
- [ ] 자동 새로 고침을 비활성화할 수 있는가

### 2.2.2 일시 정지, 중지, 숨기기 (레벨 A)

- [ ] 움직이는 콘텐츠를 일시 정지할 수 있는가
- [ ] 자동 업데이트 콘텐츠를 일시 정지할 수 있는가
- [ ] 애니메이션이 prefers-reduced-motion을 준수하는가

```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}
```

## 2.3 발작 및 신체 반응

### 2.3.1 세 번 깜박임 (레벨 A)

- [ ] 콘텐츠가 초당 3회 이상 깜박이지 않는가
- [ ] 깜박이는 영역이 작은가(뷰포트 25% 미만)

## 2.4 탐색 가능

### 2.4.1 블록 건너뛰기 (레벨 A)

- [ ] 메인 콘텐츠로 건너뛰기 링크가 있는가
- [ ] 랜드마크 영역이 정의되었는가
- [ ] 적절한 제목 구조

```html
<a href="#main" class="skip-link">메인 콘텐츠로 건너뛰기</a>
<main id="main">...</main>
```

### 2.4.2 페이지 제목 (레벨 A)

- [ ] 고유하고 설명적인 페이지 제목
- [ ] 제목이 페이지 콘텐츠를 반영하는가

### 2.4.3 포커스 순서 (레벨 A)

- [ ] 포커스 순서가 시각적 순서와 일치하는가
- [ ] tabindex가 올바르게 사용되었는가

### 2.4.4 링크 목적 (문맥 내) (레벨 A)

- [ ] 링크가 문맥에서 의미를 갖는가
- [ ] "여기를 클릭하세요" 또는 "더 읽기"만 있지 않은가

```html
<!-- 나쁜 예 -->
<a href="report.pdf">여기를 클릭하세요</a>

<!-- 좋은 예 -->
<a href="report.pdf">Q4 판매 보고서 다운로드 (PDF)</a>
```

### 2.4.6 제목 및 레이블 (레벨 AA)

- [ ] 제목이 콘텐츠를 설명하는가
- [ ] 레이블이 목적을 설명하는가

### 2.4.7 포커스 표시 (레벨 AA)

- [ ] 모든 요소에 포커스 표시기가 보이는가
- [ ] 사용자 정의 포커스 스타일이 대비를 충족하는가

```css
:focus {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}
```

### 2.4.11 포커스 가려짐 없음 (레벨 AA) - WCAG 2.2

- [ ] 포커스된 요소가 완전히 숨겨지지 않는가
- [ ] 고정 헤더가 포커스를 가리지 않는가

이해 가능 (원칙 3)

## 3.1 읽기 가능

### 3.1.1 페이지 언어 (레벨 A)
- [ ] HTML lang 속성이 설정되었는가
- [ ] 언어가 콘텐츠에 맞는가

```html
<html lang="en">

3.1.2 부분 언어 (레벨 AA)

  • 언어 변경이 표시되었는가
<p>프랑스어 단어 <span lang="fr">bonjour</span>는 안녕하세요를 의미합니다.</p>

3.2 예측 가능

3.2.1 포커스 시 (레벨 A)

  • 포커스만으로 문맥 변화가 없는가
  • 포커스 시 예기치 않은 팝업이 없는가

3.2.2 입력 시 (레벨 A)

  • 자동 양식 제출이 없는가
  • 문맥 변화 전 사용자에게 경고하는가

3.2.3 일관된 탐색 (레벨 AA)

  • 탐색이 페이지 간 일관적인가
  • 반복되는 컴포넌트가 같은 순서인가

3.2.4 일관된 식별 (레벨 AA)

  • 같은 기능 = 같은 레이블
  • 아이콘이 일관적으로 사용되었는가

3.3 입력 도움

3.3.1 오류 식별 (레벨 A)

  • 오류가 명확히 식별되었는가
  • 오류 메시지가 문제를 설명하는가
  • 오류가 필드에 연결되었는가
<input aria-describedby="email-error" aria-invalid="true" />
<span id="email-error" role="alert">유효한 이메일을 입력하세요</span>

3.3.2 레이블 또는 지침 (레벨 A)

  • 모든 입력에 보이는 레이블이 있는가
  • 필수 필드가 표시되었는가
  • 형식 힌트가 제공되었는가

3.3.3 오류 제안 (레벨 AA)

  • 오류에 수정 제안이 포함되었는가
  • 제안이 구체적인가

3.3.4 오류 방지 (레벨 AA)

  • 법적/금융 양식이 되돌릴 수 있는가
  • 제출 전 데이터 확인
  • 제출 전 검토 가능

### 견고 (원칙 4)

```markdown
## 4.1 호환 가능

### 4.1.1 구문 분석 (레벨 A) - WCAG 2.2에서 폐기됨
- [ ] 유효한 HTML (좋은 관행)
- [ ] 중복 ID 없음
- [ ] 완전한 시작/종료 태그

### 4.1.2 이름, 역할, 값 (레벨 A)
- [ ] 사용자 정의 위젯에 접근 가능한 이름이 있는가
- [ ] ARIA 역할이 올바른가
- [ ] 상태 변경이 알려지는가

```html
<!-- 접근 가능한 사용자 정의 체크박스 -->
<div role="checkbox"
     aria-checked="false"
     tabindex="0"
     aria-labelledby="label">
</div>
<span id="label">약관 동의</span>
```

### 4.1.3 상태 메시지 (레벨 AA)

- [ ] 상태 업데이트가 알려지는가
- [ ] 라이브 영역이 올바르게 사용되었는가

```html
<div role="status" aria-live="polite">장바구니에 3개 항목 추가됨</div>

<div role="alert" aria-live="assertive">오류: 양식 제출 실패</div>
```

자동화된 테스트

// axe-core 통합
const axe = require('axe-core');

async function runAccessibilityAudit(page) {
  await page.addScriptTag({ path: require.resolve('axe-core') });

  const results = await page.evaluate(async () => {
    return await axe.run(document, {
      runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa']
      }
    });
  });

  return {
    violations: results.violations,
    passes: results.passes,
    incomplete: results.incomplete
  };
}

// Playwright 테스트 예시
test('접근성 위반이 없어야 함', async ({ page }) => {
  await page.goto('/');
  const results = await runAccessibilityAudit(page);

  expect(results.violations).toHaveLength(0);
});
# CLI 도구
npx @axe-core/cli https://example.com
npx pa11y https://example.com
lighthouse https://example.com --only-categories=accessibility

수정 패턴

수정: 누락된 양식 레이블

<!-- 수정 전 -->
<input type="email" placeholder="이메일" />

<!-- 수정 후: 옵션 1 - 보이는 레이블 -->
<label for="email">이메일 주소</label>
<input id="email" type="email" />

<!-- 수정 후: 옵션 2 - aria-label -->
<input type="email" aria-label="이메일 주소" />

<!-- 수정 후: 옵션 3 - aria-labelledby -->
<span id="email-label">이메일</span>
<input type="email" aria-labelledby="email-label" />

수정: 부족한 색상 대비

/* 수정 전: 2.5:1 대비 */
.text {
  color: #767676;
}

/* 수정 후: 4.5:1 대비 */
.text {
  color: #595959;
}

/* 또는 배경 추가 */
.text {
  color: #767676;
  background: #000;
}

수정: 키보드 탐색

// 사용자 정의 요소를 키보드 접근 가능하게 만들기
class AccessibleDropdown extends HTMLElement {
  connectedCallback() {
    this.setAttribute("tabindex", "0");
    this.setAttribute("role", "combobox");
    this.setAttribute("aria-expanded", "false");

    this.addEventListener("keydown", (e) => {
      switch (e.key) {
        case "Enter":
        case " ":
          this.toggle();
          e.preventDefault();
          break;
        case "Escape":
          this.close();
          break;
        case "ArrowDown":
          this.focusNext();
          e.preventDefault();
          break;
        case "ArrowUp":
          this.focusPrevious();
          e.preventDefault();
          break;
      }
    });
  }
}

모범 사례

해야 할 일

  • 조기에 시작 - 설계 단계에서 접근성 고려
  • 실제 사용자로 테스트 - 장애인 사용자가 최고의 피드백 제공
  • 자동화 가능한 것은 자동화 - 30-50% 문제 감지 가능
  • 시맨틱 HTML 사용 - ARIA 필요성 감소
  • 패턴 문서화 - 접근 가능한 컴포넌트 라이브러리 구축

하지 말아야 할 일

  • 자동화 테스트에만 의존하지 말 것 - 수동 테스트 필요
  • ARIA를 첫 번째 해결책으로 사용하지 말 것 - 기본 HTML 우선
  • 포커스 아웃라인을 숨기지 말 것 - 키보드 사용자에게 필요
  • 확대/축소를 비활성화하지 말 것 - 사용자가 크기 조정 필요
  • 색상만으로 사용하지 말 것 - 여러 지표 필요

리소스

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ulasalyesil/personal-website-v2

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

ulasalyesil/personal-website-v2

Conduct design interviews, generate five distinct UI variations in a temporary design lab, collect feedback, and produce implementation plans. Use when the user wants to explore UI design options, redesign existing components, or create new UI with multiple approaches to compare.

ulasalyesil/personal-website-v2

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

ulasalyesil/personal-website-v2

Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.

ulasalyesil/personal-website-v2

This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).

ulasalyesil/personal-website-v2

Best practices and example-driven guidance for building SwiftUI views and components. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens, or needing component-specific patterns and examples.

ulasalyesil/personal-website-v2

UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples.

ulasalyesil/personal-website-v2

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

ulasalyesil/personal-website-v2

Enforces an opinionated UI baseline to prevent AI-generated interface slop.

ulasalyesil/personal-website-v2

Build modern, composable, and accessible React UI components following the components.build specification. Use when creating, reviewing, or refactoring component libraries, design systems, or any reusable UI components. Triggers on tasks involving component APIs, composition patterns, accessibility, styling systems, or TypeScript props.

ulasalyesil/personal-website-v2

Ship correct, complete metadata.

ulasalyesil/personal-website-v2

Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement.

ulasalyesil/personal-website-v2

Defines the product's objects, relationships, states, and vocabulary independently of any interface — the most load-bearing layer

ulasalyesil/personal-website-v2

Maps domain concepts, terminology conflicts, and bounded contexts — produces a noun harvest for the conceptual model layer

ulasalyesil/personal-website-v2

Maps interaction structure and flow — produces breadboard notation with edge cases, failure paths, and open decisions

ulasalyesil/personal-website-v2

Framework orientation for Layers of Product Design — load this first; provides the context all other skills depend on

ulasalyesil/personal-website-v2

User research planning and synthesis at the observed behaviour layer — produces candidate job stories with confidence ratings

ulasalyesil/personal-website-v2

Diagnostic audit across all seven layers — identifies the bottleneck layer and recommends where to focus

ulasalyesil/personal-website-v2

Connects user opportunities to business outcomes and solution bets — produces a strategy tree and prioritised experiments

ulasalyesil/personal-website-v2

Audits existing surface against lower-layer decisions and produces a surface decision inventory — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility

관련 스킬