fe-a11y

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FE Accessibility Audit

前端可访问性审计

$ARGUMENTS

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

按照WCAG 2.1 AA标准检查通过

$ARGUMENTS

传递的文件的可访问性。

검사 절차

检查流程

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

读取目标文件：分析组件代码
基于清单检查：针对8个分类进行检查
生成报告：列出违规事项并提供修改代码

검사 체크리스트

检查清单

1. 시맨틱 HTML

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>

避免滥用
```
<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 속성

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>

为交互式自定义小部件添加合适的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. 키보드 네비게이션

3. 键盘导航

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

tsx

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

所有交互式元素可通过Tab键访问
为自定义小部件添加键盘事件处理器（
```
Enter
```
,
```
Space
```
,
```
Escape
```
, 方向键）
焦点陷阱 — 模态框/对话框内的焦点循环
跳过导航链接（直接跳转到主内容）
合理的Tab顺序（禁止使用
```
tabIndex
```
正数值）

tsx

// 模态框焦点陷阱（shadcn/ui Dialog自动支持）
<Dialog>
  <DialogContent>
    {/* Tab键仅在此区域内循环 */}
  </DialogContent>
</Dialog>

4. 색상 & 대비

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>

文本对比度最低为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 ? "错误: " : "成功: "}{status}
</span>

5. 폼 접근성

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>
  )}
/>

使用
```
<label>
```
+
```
htmlFor
```
关联输入字段
通过
```
aria-describedby
```
关联错误提示信息
必填字段添加
```
aria-required="true"
```
或
```
required
```
自动完成：合理设置
```
autoComplete
```
属性
向屏幕阅读器传递验证结果

tsx

// shadcn/ui Form自动处理可访问性
<FormField
  control={form.control}
  name="email"
  render={({ field }) => (
    <FormItem>
      <FormLabel>邮箱</FormLabel>
      <FormControl>
        <Input {...field} autoComplete="email" />
      </FormControl>
      <FormDescription>我们绝不会分享您的邮箱。</FormDescription>
      <FormMessage /> {/* 自动关联aria-describedby */}
    </FormItem>
  )}
/>

6. 이미지 & 미디어

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" />

传递信息的图片：使用有意义的
```
alt
```
文本
装饰性图片：设置
```
alt=""
```
或
```
aria-hidden="true"
```
复杂图片（图表、图形）：提供详细说明
Next.js
```
<Image>
```
组件必须添加
```
alt
```
属性

tsx

// 传递信息的图片
<Image src="/chart.png" alt="2024年营收趋势：第一季度100亿，第二季度150亿" />

// 装饰性图片
<Image src="/bg-pattern.png" alt="" aria-hidden="true" />

7. 동적 콘텐츠

7. 动态内容

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

加载状态：使用
```
aria-busy="true"
```
及加载提示文本
页面切换：将焦点移至新内容
无限滚动：提供替代导航方式（分页）
提示/通知：使用
```
role="alert"
```
或
```
aria-live="polite"
```

8. shadcn/ui 접근성 패턴

8. shadcn/ui可访问性模式

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

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

shadcn/ui基于Radix UI构建，大部分可访问性功能已内置，但仍需检查以下事项：

```
Dialog
```
：必须包含
```
DialogTitle
```
+
```
DialogDescription
```
```
DropdownMenu
```
：触发按钮需设置清晰标签
```
Toast
```
：设置
```
aria-live
```
区域
```
Tooltip
```
：可通过键盘焦点显示
```
Tabs
```
：确认方向键导航功能正常
```
Sheet
```
：焦点陷阱 + 按ESC关闭

리포트 형식

报告格式

markdown

undefined

markdown

undefined

Accessibility Audit: [파일명]

可访问性审计：[文件名]

요약

摘要

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

WCAG 2.1 AA合规率：[N]%
违规：N项（严重：N，主要：N，次要：N）

Critical (WCAG A 위반)

严重（违反WCAG A级标准）

[A1] 이슈 제목

[A1] 问题标题

기준: WCAG [번호] [이름]
위치:
```
파일:라인
```
문제: 설명
수정안: 코드

标准：WCAG [编号] [名称]
位置：
```
文件:行号
```
问题：说明
修改方案：代码

Major (WCAG AA 위반)

主要（违反WCAG AA级标准）

...

Minor (개선 권장)

次要（建议改进）

...

통과 항목

通过项

undefined

undefined

실행 규칙

执行规则

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

若无参数，询问用户检查目标
确认是否使用shadcn/ui组件，并考虑其内置可访问性功能
修改方案中必须包含具体代码
同时说明自动测试无法检测到的手动验证项