accessible-web-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

University of Sheffield Web Accessibility Skill

谢菲尔德大学Web无障碍开发实践规范

Build web applications that meet WCAG 2.1 Level AA standards and University of Sheffield accessibility requirements.

构建符合WCAG 2.1 AA级标准及谢菲尔德大学无障碍要求的Web应用。

When to Use This Skill

适用场景

Trigger this skill when working on:

Building new web applications, sites, or digital platforms
Creating forms, interactive components, or custom widgets
Reviewing content for accessibility compliance
Auditing existing websites for WCAG violations
User mentions: accessibility, WCAG, screen reader, keyboard navigation, alt text, ARIA, captions, color contrast, inclusive design

在以下工作场景中遵循本规范：

构建新的Web应用、网站或数字平台
创建表单、交互组件或自定义小部件
审查内容的无障碍合规性
审计现有网站的WCAG违规问题
用户提及以下关键词时：accessibility（无障碍）、WCAG、屏幕阅读器、键盘导航、替代文本、ARIA、字幕、色彩对比度、包容性设计

Core Requirements

核心要求

Compliance Standard: WCAG 2.1 Level AA minimum across all University of Sheffield digital platforms

Everyone's Responsibility: Accessibility is not just for developers—product owners, designers, content creators, and communications specialists all play critical roles.

合规标准： 谢菲尔德大学所有数字平台均需至少符合WCAG 2.1 AA级标准

全员责任： 无障碍设计并非仅开发者的职责——产品负责人、设计师、内容创作者和传播专员都肩负重要角色。

Quick Start Workflow

快速实施流程

1. Planning Phase

1. 规划阶段

Define accessibility requirements in acceptance criteria
Identify content types (text, images, video, interactive elements)
Establish responsibility matrix across team roles
Budget for testing and remediation

在验收标准中明确无障碍要求
识别内容类型（文本、图片、视频、交互元素）
建立跨团队角色的责任矩阵
为测试和修复工作分配预算

2. Design Phase

2. 设计阶段

Color Contrast: 4.5:1 minimum for normal text, 3:1 for large text
Focus Indicators: Clear, visible focus states for all interactive elements
Touch Targets: Minimum 44×44 CSS pixels
Color Alone: Never use color as sole indicator (add patterns, labels, icons)

Test designs with contrast checker:

python scripts/contrast_checker.py "#foreground" "#background"

色彩对比度： 普通文本最低4.5:1，大文本最低3:1
焦点指示器： 所有交互元素需有清晰可见的焦点状态
触摸目标： 最小44×44 CSS像素
仅用色彩： 绝不能仅以色彩作为唯一标识（需添加图案、标签、图标）

使用对比度检查工具测试设计：

python scripts/contrast_checker.py "#foreground" "#background"

3. Development Phase

3. 开发阶段

Semantic HTML First:

html

<!-- Good: Native HTML -->
<button type="button">Click me</button>
<nav aria-label="Main navigation">
  <ul><li><a href="/research">Research</a></li></ul>
</nav>

<!-- Bad: Div soup -->
<div onclick="...">Click me</div>
<div class="nav">...</div>

Heading Hierarchy:

One
```
<h1>
```
per page
Never skip levels (h1 → h2 → h3, not h1 → h3)
Headings describe content structure, not styling

Form Accessibility:

Associate labels with inputs using
```
for
```
/
```
id
```
Mark required fields with
```
required
```
and
```
aria-required="true"
```
Provide error messages via
```
aria-describedby
```
and
```
role="alert"
```
Use
```
autocomplete
```
attributes for common fields
See:
```
assets/templates/form-template.html
```

Keyboard Navigation:

All functionality available via keyboard (Tab, Enter, Space, Arrows)
Logical focus order
No keyboard traps
Visible focus indicators
Skip links for main content

ARIA Usage:

Rule 1: Use native HTML when possible (don't use
```
<div role="button">
```
, use
```
<button>
```
)
Rule 2: Only add ARIA when native HTML insufficient
For complex widgets (tabs, modals, accordions), see:
```
references/aria_patterns.md
```

优先使用语义化HTML：

html

<!-- Good: Native HTML -->
<button type="button">Click me</button>
<nav aria-label="Main navigation">
  <ul><li><a href="/research">Research</a></li></ul>
</nav>

<!-- Bad: Div soup -->
<div onclick="...">Click me</div>
<div class="nav">...</div>

标题层级：

每页仅一个
```
<h1>
```
标签
切勿跳过层级（h1 → h2 → h3，而非h1 → h3）
标题应描述内容结构，而非样式

表单无障碍设计：

使用
```
for
```
/
```
id
```
将标签与输入框关联
用
```
required
```
和
```
aria-required="true"
```
标记必填字段
通过
```
aria-describedby
```
和
```
role="alert"
```
提供错误提示
为常见字段使用
```
autocomplete
```
属性
参考：
```
assets/templates/form-template.html
```

键盘导航：

所有功能均可通过键盘（Tab、Enter、Space、方向键）访问
符合逻辑的焦点顺序
无键盘陷阱
可见的焦点指示器
主内容跳转链接

ARIA使用规则：

规则1： 尽可能使用原生HTML（不要用
```
<div role="button">
```
，应使用
```
<button>
```
）
规则2： 仅当原生HTML无法满足需求时才添加ARIA
如需实现复杂小部件（标签页、模态框、折叠面板），请参考：
```
references/aria_patterns.md
```

4. Content Phase

4. 内容阶段

Alternative Text Decision Tree:

Is image meaningful?
├─ YES: Conveys information? → Write descriptive alt text
│   └─ Redundant with surrounding text? → alt=""
└─ NO: Purely decorative? → alt=""

Functional images (buttons, links): Describe function, not appearance
Complex images (charts): Brief alt + detailed description

Examples:

html

<!-- Decorative -->
<img src="border.png" alt="">

<!-- Informative -->
<img src="campus.jpg" alt="Students working in Diamond building collaborative space">

<!-- Functional -->
<a href="/search"><img src="search.svg" alt="Search"></a>

<!-- Complex -->
<img src="chart.png"
     alt="Enrollment trends 2020-2024"
     aria-describedby="chart-details">
<div id="chart-details">
  Enrollment increased from 28,000 to 32,000,
  with largest growth in Engineering (15%)...
</div>

Video/Audio Requirements:

Captions: All video content (prerecorded and live)
Transcripts: All audio/video content
Audio Description: Instructional and informational videos
Upload captions as SRT files (Kaltura for UoS content)

替代文本决策树：

图片是否有意义？
├─ 是：是否传递信息？→ 编写描述性替代文本
│   └─ 是否与周围文本重复？→ alt=""
└─ 否：纯装饰性？→ alt=""

功能性图片（按钮、链接）：描述功能，而非外观
复杂图片（图表）：简短替代文本 + 详细描述

示例：

html

<!-- Decorative -->
<img src="border.png" alt="">

<!-- Informative -->
<img src="campus.jpg" alt="Students working in Diamond building collaborative space">

<!-- Functional -->
<a href="/search"><img src="search.svg" alt="Search"></a>

<!-- Complex -->
<img src="chart.png"
     alt="Enrollment trends 2020-2024"
     aria-describedby="chart-details">
<div id="chart-details">
  Enrollment increased from 28,000 to 32,000,
  with largest growth in Engineering (15%)...
</div>

视频/音频要求：

字幕： 所有视频内容（预录制和直播）均需添加字幕
文字转录： 所有音频/视频内容均需提供文字转录
音频描述： 教学类和信息类视频需添加音频描述
字幕需以SRT格式上传（谢菲尔德大学内容使用Kaltura平台）

5. Testing Phase

5. 测试阶段

Automated Testing:

bash

undefined

自动化测试：

bash

undefined

HTML audit

python scripts/accessibility_audit.py path/to/file.html

Color contrast check

python scripts/contrast_checker.py "#ffffff" "#000000"


**Manual Testing:**
- Keyboard-only navigation (disconnect mouse)
- Screen reader testing (NVDA on Windows, VoiceOver on Mac)
- Zoom to 200% (content must remain functional)
- Mobile screen reader (TalkBack/VoiceOver)

**Testing Checklist:**
- [ ] All images have alt text or alt=""
- [ ] All form inputs have associated labels
- [ ] Headings follow logical hierarchy
- [ ] All functionality keyboard accessible
- [ ] Focus indicators visible
- [ ] Color contrast meets 4.5:1 (normal text)
- [ ] No keyboard traps
- [ ] Dynamic updates announced by screen readers
- [ ] Link text descriptive out of context

---

python scripts/contrast_checker.py "#ffffff" "#000000"


**手动测试：**
- 仅用键盘导航（断开鼠标）
- 屏幕阅读器测试（Windows用NVDA，Mac用VoiceOver）
- 缩放至200%（内容需保持可用）
- 移动设备屏幕阅读器测试（TalkBack/VoiceOver）

**测试检查清单：**
- [ ] 所有图片均有替代文本或alt=""
- [ ] 所有表单输入框均有关联标签
- [ ] 标题遵循逻辑层级
- [ ] 所有功能均可通过键盘访问
- [ ] 焦点指示器可见
- [ ] 色彩对比度符合4.5:1（普通文本）
- [ ] 无键盘陷阱
- [ ] 动态更新内容可被屏幕阅读器读取
- [ ] 链接文本脱离上下文仍具描述性

---

Common Patterns & Templates

通用模式与模板

Accessible Modal Dialog

无障碍模态对话框

See:

assets/templates/modal-template.html

Key Requirements:

```
role="dialog"
```
and
```
aria-modal="true"
```
Focus trap within modal
Escape key closes modal
Focus returns to trigger element on close
Prevent background scroll when open

React Example:

assets/examples/AccessibleTabs.jsx

参考：

assets/templates/modal-template.html

核心要求：

```
role="dialog"
```
和
```
aria-modal="true"
```
模态框内焦点锁定
ESC键可关闭模态框
关闭后焦点返回触发元素
打开时禁止背景滚动

React示例：

assets/examples/AccessibleTabs.jsx

Accessible Forms

无障碍表单

See:

assets/templates/form-template.html

Key Requirements:

Label/input associations
Error messaging with
```
role="alert"
```
Required field indicators
Validation feedback
Autocomplete attributes

React Components:

assets/examples/AccessibleForm.jsx

参考：

assets/templates/form-template.html

核心要求：

标签与输入框关联
带
```
role="alert"
```
的错误提示
必填字段标识
验证反馈
自动完成属性

React组件：

assets/examples/AccessibleForm.jsx

Accessible Tabs

无障碍标签页

Keyboard Navigation:

Arrow Left/Right: Navigate tabs
Home/End: First/last tab
Tab: Exit tab list

Implementation: See

assets/examples/AccessibleTabs.jsx

键盘导航：

左/右箭头键：切换标签页
Home/End键：跳转到第一个/最后一个标签页
Tab键：退出标签页列表

实现参考： 见

assets/examples/AccessibleTabs.jsx

Quick Reference

快速参考

WCAG 2.1 AA Priority Checks

WCAG 2.1 AA优先级检查项

Level A (Critical):

1.1.1: Alt text for images
2.1.1: Keyboard accessible
2.1.2: No keyboard traps
2.4.1: Skip links
2.4.2: Page titles
3.1.1: Page language (lang attribute)
4.1.2: Name, role, value for components

Level AA (UoS Requirement):

1.2.4: Live captions
1.2.5: Audio descriptions
1.4.3: Color contrast 4.5:1
1.4.5: Avoid images of text
2.4.7: Visible focus
3.3.3: Error suggestions
4.1.3: Status messages

Full details: See

references/wcag_detailed.md

A级（关键）：

1.1.1：图片的替代文本
2.1.1：键盘可访问
2.1.2：无键盘陷阱
2.4.1：主内容跳转链接
2.4.2：页面标题
3.1.1：页面语言（lang属性）
4.1.2：组件的名称、角色、值

AA级（谢菲尔德大学要求）：

1.2.4：直播字幕
1.2.5：音频描述
1.4.3：色彩对比度4.5:1
1.4.5：避免使用图片文本
2.4.7：可见焦点
3.3.3：错误建议
4.1.3：状态提示

详细内容： 见

references/wcag_detailed.md

ARIA Patterns Reference

ARIA模式参考

For implementing complex widgets:

Accordion, Alert Dialog, Breadcrumb
Button (Toggle), Combobox, Dialog (Modal)
Disclosure, Menu, Tabs, Tooltip
Tree View, Live Regions

Full patterns with code: See

references/aria_patterns.md

如需实现复杂小部件：

折叠面板、警告对话框、面包屑
按钮（切换）、组合框、对话框（模态）
披露组件、菜单、标签页、工具提示
树形视图、实时区域

带代码的完整模式： 见

references/aria_patterns.md

Color Contrast Quick Check

色彩对比度快速检查

Minimum Ratios:

Normal text: 4.5:1
Large text (18pt+ or 14pt+ bold): 3:1
UI components/graphics: 3:1

Common UoS Colors:

White on UoS blue (#009ADE): 3.2:1 ✗ Fails for normal text
Black on UoS yellow (#FECB00): 10:1 ✓ Passes

Tool:

python scripts/contrast_checker.py "#color1" "#color2" --level AA

最低对比度：

普通文本：4.5:1
大文本（18pt+ 或 14pt+ 粗体）：3:1
UI组件/图形：3:1

谢菲尔德大学常用色彩：

谢菲尔德大学蓝色（#009ADE）配白色：3.2:1 ✗ 不符合普通文本要求
谢菲尔德大学黄色（#FECB00）配黑色：10:1 ✓ 符合要求

工具：

python scripts/contrast_checker.py "#color1" "#color2" --level AA

Common Pitfalls & Solutions

常见问题与解决方案

Pitfall 1: Generic Link Text

问题1：通用链接文本

❌ Bad: "Click here" or "Read more" ✅ Good: "Annual Research Report 2024 (PDF, 2.3MB)"

❌ 错误示例： "Click here"（点击此处）或"Read more"（阅读更多） ✅ 正确示例： "2024年度研究报告（PDF，2.3MB）"

Pitfall 2: Missing Form Labels

问题2：缺失表单标签

❌ Bad:

<input type="text" placeholder="Email">

✅ Good:

<label for="email">Email</label><input id="email" type="email">

❌ 错误示例：

<input type="text" placeholder="Email">

✅ 正确示例：

<label for="email">Email</label><input id="email" type="email">

Pitfall 3: Div/Span Buttons

问题3：Div/Span模拟按钮

❌ Bad:

<div onclick="submit()">Submit</div>

✅ Good:

<button type="button" onclick="submit()">Submit</button>

❌ 错误示例：

<div onclick="submit()">Submit</div>

✅ 正确示例：

<button type="button" onclick="submit()">Submit</button>

Pitfall 4: Low Color Contrast

问题4：低色彩对比度

❌ Bad: Light gray (#CCC) on white (1.7:1) ✅ Good: Dark gray (#767676) on white (4.5:1)

❌ 错误示例： 浅灰色（#CCC）配白色（对比度1.7:1） ✅ 正确示例： 深灰色（#767676）配白色（对比度4.5:1）

Pitfall 5: Auto-Playing Media

问题5：自动播放媒体

❌ Bad:

<video autoplay>

✅ Good:

<video controls><track kind="captions" src="captions.vtt"></video>

❌ 错误示例：

<video autoplay>

✅ 正确示例：

<video controls><track kind="captions" src="captions.vtt"></video>

Pitfall 6: Missing Page Titles

问题6：缺失页面标题

❌ Bad:

<title>University of Sheffield</title>

(on every page) ✅ Good:

<title>Computer Science MSc - Courses - University of Sheffield</title>

❌ 错误示例：

<title>University of Sheffield</title>

（所有页面均使用此标题） ✅ 正确示例：

<title>Computer Science MSc - Courses - University of Sheffield</title>

Tools & Scripts

工具与脚本

Included Scripts

内置脚本

Accessibility Auditor:

bash

undefined

无障碍审计工具：

bash

undefined

Audit single file

审计单个文件

python scripts/accessibility_audit.py file.html

Audit directory

审计目录

python scripts/accessibility_audit.py src/

JSON output

JSON格式输出

python scripts/accessibility_audit.py file.html --format json


Checks: Images, headings, links, forms, page structure, semantic HTML, tables, buttons, ARIA usage

**Contrast Checker:**
```bash

python scripts/accessibility_audit.py file.html --format json


检查内容：图片、标题、链接、表单、页面结构、语义化HTML、表格、按钮、ARIA使用情况

**对比度检查工具：**
```bash

Basic check

基础检查

python scripts/contrast_checker.py "#ffffff" "#000000"

Check for AAA

检查AAA级标准

python scripts/contrast_checker.py "#ffffff" "#000000" --level AAA

Large text

大文本检查

python scripts/contrast_checker.py "#999999" "#ffffff" --large-text

Show suggestions

显示优化建议

python scripts/contrast_checker.py "#cccccc" "#ffffff" --suggest

undefined

python scripts/contrast_checker.py "#cccccc" "#ffffff" --suggest

undefined

External Tools

外部工具

Browser Extensions:

WAVE (WebAIM): Visual accessibility feedback
axe DevTools: Comprehensive automated testing
Lighthouse: Built into Chrome DevTools

Screen Readers:

NVDA (Windows): Free, nvaccess.org
JAWS (Windows): Commercial, enterprise standard
VoiceOver (Mac/iOS): Built-in (Cmd+F5)
TalkBack (Android): Built-in

Online Tools:

WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
WAVE Web Accessibility Evaluation: https://wave.webaim.org/

浏览器扩展：

WAVE (WebAIM): 可视化无障碍反馈
axe DevTools: 全面的自动化测试工具
Lighthouse: 内置在Chrome开发者工具中

屏幕阅读器：

NVDA (Windows): 免费工具，官网nvaccess.org
JAWS (Windows): 商业工具，企业标准
VoiceOver (Mac/iOS): 内置工具（Cmd+F5启动）
TalkBack (Android): 内置工具

在线工具：

WebAIM对比度检查器：https://webaim.org/resources/contrastchecker/
WAVE Web无障碍评估工具：https://wave.webaim.org/

University of Sheffield Specific

谢菲尔德大学特定要求

Content Tone:

Active voice over passive
Plain English (avoid jargon)
Short paragraphs for scannability
Sentence case (not title case/capitals)

Platform Requirements:

Kaltura for video hosting and captioning
Standard SRT format for captions
Accessibility statement required on all sites
Diverse representation in all visual content

Documentation:

Must document any exceptions with justification
Standards apply unless clear reason why not possible
Regular audits required

内容语气：

优先使用主动语态而非被动语态
使用简明英语（避免行话）
短段落便于快速阅读
句子大小写（而非标题大小写/全大写）

平台要求：

使用Kaltura进行视频托管和字幕添加
字幕采用标准SRT格式
所有网站均需包含无障碍声明
所有视觉内容需体现多元化

文档要求：

任何例外情况均需记录并说明理由
除非有明确的不可行原因，否则需遵循标准
定期进行审计并记录结果

Implementation Example

实现示例

Scenario: Building a student portal

javascript

// 1. Use this skill to generate accessible component
"I need to build a course enrollment form for University of Sheffield
student portal. Include name, email, course selection dropdown, and
accessibility preferences checkboxes."

// 2. Skill will:
// - Use semantic HTML form structure
// - Add proper label associations
// - Include error handling with aria-live
// - Implement keyboard navigation
// - Ensure color contrast compliance
// - Add autocomplete attributes
// - Reference form template from assets/

// 3. Test with provided tools
python scripts/accessibility_audit.py enrollment-form.html
python scripts/contrast_checker.py "#005eb8" "#ffffff"

// 4. Manual verification
// - Tab through form with keyboard only
// - Test with NVDA screen reader
// - Verify error messages announced
// - Check focus indicators visible

场景：构建学生门户

javascript

// 1. 使用本规范生成无障碍组件
"我需要为谢菲尔德大学学生门户构建一个课程注册表单，包含姓名、邮箱、课程选择下拉菜单和无障碍偏好复选框。"

// 2. 本规范将：
// - 使用语义化HTML表单结构
// - 添加正确的标签关联
// - 包含带aria-live的错误处理
// - 实现键盘导航
// - 确保色彩对比度合规
// - 添加autocomplete属性
// - 参考assets/中的表单模板

// 3. 使用提供的工具测试
python scripts/accessibility_audit.py enrollment-form.html
python scripts/contrast_checker.py "#005eb8" "#ffffff"

// 4. 手动验证
// - 仅用键盘Tab键遍历表单
// - 使用NVDA屏幕阅读器测试
// - 验证错误提示是否可被读取
// - 检查焦点指示器是否可见

Resources

资源

Detailed References:

Full WCAG 2.1 criteria:
```
references/wcag_detailed.md
```
Complete ARIA patterns:
```
references/aria_patterns.md
```

Templates & Examples:

HTML form template:
```
assets/templates/form-template.html
```
HTML modal template:
```
assets/templates/modal-template.html
```
React tabs component:
```
assets/examples/AccessibleTabs.jsx
```
React form components:
```
assets/examples/AccessibleForm.jsx
```

Official Guidelines:

WCAG 2.1: https://www.w3.org/TR/WCAG21/
WAI-ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
UK Public Sector Requirements: https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps

Learning Resources:

WebAIM: https://webaim.org/
A11y Project: https://www.a11yproject.com/
Inclusive Components: https://inclusive-components.design/

详细参考文档：

WCAG 2.1完整标准：
```
references/wcag_detailed.md
```
ARIA完整模式：
```
references/aria_patterns.md
```

模板与示例：

HTML表单模板：
```
assets/templates/form-template.html
```
HTML模态框模板：
```
assets/templates/modal-template.html
```
React标签页组件：
```
assets/examples/AccessibleTabs.jsx
```
React表单组件：
```
assets/examples/AccessibleForm.jsx
```

官方指南：

WCAG 2.1：https://www.w3.org/TR/WCAG21/
WAI-ARIA创作实践：https://www.w3.org/WAI/ARIA/apg/
英国公共部门要求：https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps

学习资源：

WebAIM：https://webaim.org/
A11y Project：https://www.a11yproject.com/
Inclusive Components：https://inclusive-components.design/

Success Criteria

成功标准

Technical:

100% WCAG 2.1 AA compliance
Zero critical errors in automated testing
All pages pass keyboard-only navigation
All content announced correctly by screen readers

User Experience:

Users with disabilities can complete all tasks
Equivalent experience regardless of ability
Positive feedback from assistive technology users
No accessibility-related support issues

Process:

Accessibility in all acceptance criteria
Testing integrated into CI/CD pipeline
Team trained on accessibility standards
Regular audits completed and documented

技术标准：

100%符合WCAG 2.1 AA标准
自动化测试无严重错误
所有页面支持仅键盘导航
所有内容可被屏幕阅读器正确读取

用户体验标准：

残障用户可完成所有任务
无论能力如何，用户体验一致
辅助技术用户给出正面反馈
无无障碍相关的支持问题

流程标准：

所有验收标准均包含无障碍要求
测试集成到CI/CD流水线中
团队接受过无障碍标准培训
定期完成审计并记录结果