fe-a11y

Original：🇺🇸 English

Translated

React/Next.js 컴포넌트의 WCAG 2.1 AA 기준 웹 접근성을 검사하고 수정 가이드를 제공하는 스킬. "접근성", "a11y", "accessibility", "WCAG", "스크린리더", "키보드 접근" 등의 요청 시 사용.

7installs

Sourceingpdw/pdw-fe-dev-tool

Added on2026-02-08

NPX Install

npx skill4agent add ingpdw/pdw-fe-dev-tool fe-a11y

SKILL.md Content

View Translation Comparison →

FE Accessibility Audit

$ARGUMENTS

로 전달된 파일의 접근성을 WCAG 2.1 AA 기준으로 검사한다.

검사 절차

대상 파일 읽기: 컴포넌트 코드를 분석한다
체크리스트 기반 검사: 8개 카테고리에 대해 검사한다
리포트 생성: 위반 사항과 수정 코드를 제시한다

검사 체크리스트

1. 시맨틱 HTML

```
<div>
```
/
```
<span>
```
남용 대신 적절한 시맨틱 태그 사용
- ```
<nav>
```
  ,
```
<main>
```
  ,
```
<aside>
```
  ,
```
<header>
```
  ,
```
<footer>
```
  ,
```
<section>
```
  ,
```
<article>
```
- ```
<button>
```
  (클릭 가능 요소),
```
<a>
```
  (네비게이션)
- ```
<ul>
```
  /
```
<ol>
```
  (목록),
```
<table>
```
  (표형 데이터)
헤딩 계층 순서 (
```
h1
```
→
```
h2
```
→
```
h3
```
, 건너뛰기 금지)
```
<img>
```
,
```
<svg>
```
에 대체 텍스트

tsx

// Bad
<div onClick={handleClick}>Submit</div>

// Good
<button onClick={handleClick}>Submit</button>

2. ARIA 속성

인터랙티브 커스텀 위젯에 적절한 role + ARIA 속성
```
aria-label
```
,
```
aria-labelledby
```
— 시각적 레이블이 없는 요소
```
aria-describedby
```
— 추가 설명이 필요한 요소
```
aria-expanded
```
,
```
aria-haspopup
```
— 드롭다운/모달
```
aria-live
```
— 동적 콘텐츠 업데이트 알림
```
aria-hidden="true"
```
— 장식용 요소

tsx

// 토스트 알림
<div role="alert" aria-live="polite">
  {message}
</div>

// 아이콘 버튼
<button aria-label="Close dialog">
  <XIcon aria-hidden="true" />
</button>

3. 키보드 네비게이션

모든 인터랙티브 요소가 Tab으로 접근 가능
커스텀 위젯에 키보드 핸들러 (
```
Enter
```
,
```
Space
```
,
```
Escape
```
, 화살표키)
포커스 트랩 — 모달/다이얼로그 내 포커스 순환
Skip navigation 링크 (메인 콘텐츠로 바로 이동)
논리적인 탭 순서 (
```
tabIndex
```
양수값 사용 금지)

tsx

// 모달 포커스 트랩 (shadcn/ui Dialog는 자동 지원)
<Dialog>
  <DialogContent>
    {/* Tab 키가 이 안에서만 순환 */}
  </DialogContent>
</Dialog>

4. 색상 & 대비

텍스트 대비율 최소 4.5:1 (일반), 3:1 (큰 텍스트 18px+)
색상만으로 정보를 전달하지 않음 (아이콘, 텍스트 병행)
다크 모드에서도 대비율 충족
포커스 표시 (outline) 제거 금지 —
```
focus-visible
```
사용

tsx

// Bad — 색상만으로 상태 표현
<span className={isError ? "text-red-500" : "text-green-500"}>
  {status}
</span>

// Good — 아이콘 + 텍스트 병행
<span className={isError ? "text-red-500" : "text-green-500"}>
  {isError ? <AlertIcon aria-hidden="true" /> : <CheckIcon aria-hidden="true" />}
  {isError ? "Error: " : "Success: "}{status}
</span>

5. 폼 접근성

```
<label>
```
+
```
htmlFor
```
로 입력 필드와 연결
에러 메시지를
```
aria-describedby
```
로 연결
필수 필드에
```
aria-required="true"
```
또는
```
required
```
자동완성:
```
autoComplete
```
속성 적절히 설정
유효성 검사 결과를 스크린리더에 전달

tsx

// shadcn/ui Form은 자동으로 접근성 처리
<FormField
  control={form.control}
  name="email"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Email</FormLabel>
      <FormControl>
        <Input {...field} autoComplete="email" />
      </FormControl>
      <FormDescription>We'll never share your email.</FormDescription>
      <FormMessage /> {/* aria-describedby 자동 연결 */}
    </FormItem>
  )}
/>

6. 이미지 & 미디어

정보를 전달하는 이미지: 의미 있는
```
alt
```
텍스트
장식용 이미지:
```
alt=""
```
또는
```
aria-hidden="true"
```
복잡한 이미지 (차트, 그래프): 상세 설명 제공
Next.js
```
<Image>
```
컴포넌트에
```
alt
```
필수

tsx

// 정보 전달 이미지
<Image src="/chart.png" alt="2024년 매출 추이: 1분기 100억, 2분기 150억" />

// 장식용 이미지
<Image src="/bg-pattern.png" alt="" aria-hidden="true" />

7. 동적 콘텐츠

로딩 상태:
```
aria-busy="true"
```
, 로딩 안내 텍스트
페이지 전환: 포커스를 새 콘텐츠로 이동
무한 스크롤: 대안 네비게이션 제공 (페이지네이션)
토스트/알림:
```
role="alert"
```
또는
```
aria-live="polite"
```

8. shadcn/ui 접근성 패턴

shadcn/ui는 Radix UI 기반으로 대부분의 접근성이 내장되어 있지만, 확인해야 할 사항:

```
Dialog
```
:
```
DialogTitle
```
+
```
DialogDescription
```
필수
```
DropdownMenu
```
: 트리거 버튼에 명확한 레이블
```
Toast
```
:
```
aria-live
```
영역 설정
```
Tooltip
```
: 키보드 포커스로 표시 가능
```
Tabs
```
: 화살표 키 네비게이션 동작 확인
```
Sheet
```
: 포커스 트랩 + ESC로 닫기

리포트 형식

markdown

# Accessibility Audit: [파일명]

## 요약
- WCAG 2.1 AA 준수율: [N]%
- 위반: N개 (Critical: N, Major: N, Minor: N)

## Critical (WCAG A 위반)
### [A1] 이슈 제목
- **기준**: WCAG [번호] [이름]
- **위치**: `파일:라인`
- **문제**: 설명
- **수정안**: 코드

## Major (WCAG AA 위반)
...

## Minor (개선 권장)
...

## 통과 항목
- ...

실행 규칙

인자가 없으면 사용자에게 검사 대상을 질문한다
shadcn/ui 컴포넌트 사용 여부를 확인하고, 내장 접근성 기능을 고려한다
수정안에는 항상 구체적인 코드를 포함한다
자동 테스트로 잡을 수 없는 수동 검증 항목도 안내한다