accessibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ensuring Accessibility and Quality Code in Web Projects

确保网页项目中的可访问性与高质量代码

Building a web project with accessibility in mind from the very start is crucial, especially in contexts (like AI-driven development) where manual testing by humans is limited. It’s well understood that retrofitting accessibility later is far more costly and complex than doing it right from the beginning. Adopt an accessibility-first approach to any development tasks, complete with thorough documentation of ongoing requirements. Ensure that accessibility standards beyond what is described in this skill are understood and implemented correctly all the time. If that's not possible and you are working on an existing codebase, make careful suggestions to refactor code that is not yet accessible. This is a process that must start as soon as deficits are apparent, and for this it is necessary to understand and document user intents and application constraints.

从项目一开始就将可访问性纳入考量至关重要，尤其是在AI驱动开发这类人工手动测试受限的场景中。众所周知，后期再为项目适配可访问性的成本和复杂度，远高于从一开始就做好这件事。在所有开发任务中采用可访问性优先的方法，并持续记录相关需求。确保始终理解并正确落实本技能描述之外的其他可访问性标准。如果无法做到这一点，或是在现有代码库上工作，请谨慎提出重构非可访问代码的建议。这个过程必须在发现问题后立即启动，为此需要理解并记录用户意图和应用约束。

Code Comments and WCAG References

代码注释与WCAG参考

Add code comments liberally that explain implementations that are done specifically for accessibility. In those, explain this based on the WCAG 2.2 requirements of any level. Explain the expected user flow if relevant.

大量添加代码注释，专门解释为可访问性实现的功能。注释中要基于任意级别的WCAG 2.2要求进行说明。如果相关的话，解释预期用户流程。

Use Semantic HTML and Proper Structure

使用语义化HTML与合理结构

Start by using semantic HTML for all content and controls. Use real

<button>

elements for buttons,

<header>

<nav>

<main>

for layout,

<form>

and

<label>

for forms, and a locial hierarchy of heading levels for titles. For example, a

<button>

element comes with default keyboard support (focusable and activatable via keyboard), whereas a non-semantic element like a

<div>

would lack those features. It is required to use existing native elements like

<select>

<details>

<dialog>

. If there is no way of avoiding custom components (there usually isn't), follow established ARIA design patterns and keyboard interaction models. Use ARIA only if there is NO alternative, and in most cases, there is. If you do, document this choice and the reasoning behind it.

Ensure the page is organized with clear structure and landmarks. Use HTML5 sectioning elements to delineate navigation, main content, forms, etc, to give users and yourself a clear understanding of how the content is structured. Always provide text equivalents for non-text media: include descriptive alt text for images, transcripts or captions for audio/video. If you can't reliably make those yourself, note a required and blocking task for another maintainer. Similarly, use table headings (with

<th>

and

scope

attributes) for data tables to make relationships in tabular data clear to screen readers. Avoid link texts like "here", "click" or "Continue Reading". If they are required visually, add a redundant way to receive their content (e.g. an interactive card) and remove those from the accessibility tree.

首先，为所有内容和控件使用语义化HTML。为按钮使用原生

<button>

元素，为布局使用

<header>

<nav>

<main>

，为表单使用

<form>

和

<label>

，为标题使用逻辑层级的标题标签。例如，

<button>

元素默认支持键盘操作（可聚焦且可通过键盘激活），而非语义化元素如

<div>

则缺少这些特性。必须使用

<select>

、

<details>

或

<dialog>

等现有原生元素。如果无法避免自定义组件（通常可以避免），请遵循既定的ARIA设计模式和键盘交互模型。只有在没有替代方案的情况下才使用ARIA，而大多数情况下都有替代方案。如果确实使用了ARIA，请记录这个选择及其背后的原因。

确保页面通过清晰的结构和地标组织内容。使用HTML5分段元素划分导航、主内容、表单等区域，让用户和你自己都能清晰了解内容的结构。始终为非文本媒体提供文本等效内容：为图片添加描述性的替代文本（alt text），为音频/视频提供文字转录或字幕。如果你无法可靠地自行完成这些工作，请标注为需要其他维护人员处理的必要阻塞任务。同样，为数据表格使用表头（带

<th>

和

scope

属性），以便屏幕阅读器能清晰识别表格数据中的关联关系。避免使用“这里”“点击”或“继续阅读”这类链接文本。如果视觉上需要这些文本，请添加冗余的内容获取方式（例如交互式卡片），并将这些文本从可访问性树中移除。

Design Accessible Components

设计可访问的组件

Each component’s HTML structure must reflect its semantics: use lists for menus or multi-option controls, use headings for titles, use fieldsets and legends for groups of form fields, etc. Maintain a consistent style for focus indicators (the outline or highlight when an element is focused) so that keyboard users can always see where focus is. Keyboard accessibility isn’t optional – ensure users can reach and operate every interactive element via keyboard alone (e.g., using Tab, Enter, space, arrow keys as appropriate). This may require adding

tabindex

ONLY for custom focusable elements and ONLY with negative values, and handling key events in scripts for custom widgets.

Remember the WCAG rule for touch target sizes. Everything should be easily reachable. Mouse or gesture controls (like dragging) require an alternative.

Make use of accessibility linters and libraries. There are frameworks and component libraries that emphasize accessible design. If using React/Vue/Angular, leverage their accessibility tooling (like React’s eslint-plugin-JSX-a11y) and prefer community-vetted accessible components. Ultimately, an accessible component is achieved by a combination of correct HTML structure, proper ARIA roles/states where needed, and scripting that follows usability conventions for assistive tech users. Documentation should record how each custom component addresses accessibility (e.g. how to provide alt text for an image component, or how a carousel handles focus and screen reader announcements), so that anyone extending the component knows what requirements to uphold.

每个组件的HTML结构必须反映其语义：为菜单或多选项控件使用列表，为标题使用标签，为表单字段组使用

<fieldset>

和

<legend>

等。保持焦点指示器（元素获得焦点时的轮廓或高亮）的样式一致，以便键盘用户始终能看到焦点位置。键盘可访问性是必须的——确保用户仅通过键盘就能到达并操作所有交互元素（例如，根据需要使用Tab、Enter、空格、箭头键）。这可能需要仅为自定义可聚焦元素添加

tabindex

，且只能使用负值，并为自定义组件在脚本中处理键盘事件。

记住WCAG关于触摸目标大小的规则。所有交互元素都应易于点击。鼠标或手势控制（如拖拽）需要提供替代操作方式。

利用可访问性检查工具与库。有许多强调可访问性设计的框架和组件库。如果使用React/Vue/Angular，请利用它们的可访问性工具（如React的eslint-plugin-JSX-a11y），并优先选择社区验证过的可访问组件。最终，一个可访问的组件需要结合正确的HTML结构、必要时的适当ARIA角色/状态，以及符合辅助技术用户使用习惯的脚本。文档应记录每个自定义组件如何解决可访问性问题（例如，如何为图片组件提供替代文本，或轮播组件如何处理焦点和屏幕阅读器播报），以便任何扩展该组件的人都知道需要遵守哪些要求。

Continuous Maintenance and Avoiding Anti-Patterns

持续维护与避免反模式

Achieving accessibility is not a one-time task – it requires continuous evaluation as the project evolves. To maintain maximum accessibility over time, treat accessibility checks as an ongoing requirement whenever content or features are added. A few key practices to document and enforce for future changes include:

Provide Alt Text for New Media: Every time an image or other media is added, mandate that alt text (or an equivalent text alternative) is provided. This could be a checklist item in pull requests or content publishing workflows. Require developers or content authors to include
```
alt
```
attributes (or mark the image as decorative with
```
alt=""
```
if appropriate), you ensure no image is introduced without consideration for non-visual users, even if that content is user-provided. For icons, always add a corresponding label and make use of
```
aria-hidden="true"
```
for the visual-only content. Keep alt text short and concise, but there is no character limit.
Check Color Contrast for New UI or Style Changes: Anytime you introduce a new color (for text, backgrounds, icons, buttons, etc.) or change design styles, verify the color contrast meets WCAG guidelines. According to WCAG 2.x, contrast ratio is calculated as (L1 + 0.05) / (L2 + 0.05) (where L1 is the luminance of the lighter color and L2 of the darker). This formula yields a ratio from 1:1 (no contrast, e.g. white on white) up to 21:1 (highest contrast, e.g. black on white). Standard text should have at least a 4.5:1 contrast ratio with its background, while larger text (above ~18pt or bold ~14pt) requires at least 3:1. Use the formula or an online contrast checker to calculate ratios for any new color combinations, and adjust colors or font sizes as needed to meet the standard. This also applies to hover/focus/disabled/... states.
Maintain Heading Structure and Landmarks: When adding new content or pages, ensure the heading hierarchy (
```
<h1>…<h6>
```
) remains logical (no skipping levels arbitrarily) and sectioning elements are used where appropriate. For instance, if a new section is added to a page, it might need a heading of the correct level and perhaps be wrapped in a
```
<section>
```
or added to the navigation landmarks (
```
<nav>, <main>, <aside>
```
etc.).
Re-evaluate with each Change: It’s important to continuously re-test your application’s accessibility as it grows. Incorporate automated tests (like Pa11y) into regression test suites so every build or release runs them.
Avoid Anti-Patterns:
```
<div>
```
-buttons,
```
onclick
```
without keyboard handling,
```
outline: none
```
, aria-label as replacement for visual labels, role=button on external links etc.)

实现可访问性并非一劳永逸的任务——随着项目发展，需要持续评估。为了长期保持最高水平的可访问性，每次添加内容或功能时，都要将可访问性检查作为一项持续要求。以下是一些需要记录并强制执行的关键实践，以应对未来的变更：

为新增媒体添加替代文本： 每次添加图片或其他媒体时，强制要求提供替代文本（或等效的文本替代内容）。这可以作为拉取请求或内容发布流程中的检查项。要求开发人员或内容作者添加
```
alt
```
属性（如果是装饰性图片，则使用
```
alt=""
```
），确保即使是用户提供的内容，也不会有图片在未考虑非视觉用户需求的情况下被引入。对于图标，始终添加对应的标签，并对仅用于视觉展示的内容使用
```
aria-hidden="true"
```
。替代文本应简洁明了，但没有字符限制。
检查新增UI或样式变更的颜色对比度： 每当引入新颜色（用于文本、背景、图标、按钮等）或更改设计样式时，验证颜色对比度是否符合WCAG指南。根据WCAG 2.x，对比度比值的计算公式为**(L1 + 0.05) / (L2 + 0.05)**（其中L1是浅色的亮度，L2是深色的亮度）。该公式得出的比值范围从1:1（无对比度，如白字白底）到21:1（最高对比度，如黑字白底）。标准文本与背景的对比度比值至少应为4.5:1，而较大文本（约18pt以上或加粗14pt以上）的对比度比值至少应为3:1。使用公式或在线对比度检查工具计算任何新颜色组合的比值，并根据需要调整颜色或字体大小以符合标准。这也适用于悬停/聚焦/禁用等状态。
维护标题结构与地标： 添加新内容或页面时，确保标题层级（
```
<h1>…<h6>
```
）保持逻辑连贯（不要随意跳过层级），并在适当的地方使用分段元素。例如，如果在页面中添加新章节，可能需要使用正确层级的标题，并可能需要用
```
<section>
```
包裹，或添加到导航地标（
```
<nav>, <main>, <aside>
```
等）中。
随每次变更重新评估： 随着应用的发展，持续重新测试其可访问性非常重要。将自动化测试（如Pa11y）纳入回归测试套件，以便每次构建或发布时都能运行这些测试。
避免反模式： 例如用
```
<div>
```
模拟按钮、仅使用
```
onclick
```
而不处理键盘事件、
```
outline: none
```
、用aria-label替代视觉标签、在外部链接上设置role=button等。

Further TODOs

进一步待办事项

```
<html>
```
requires a
```
lang
```
attribute (as well as any text blocks -- not single words -- in a foreign language. If the project is multilingual, change this dynamically as required).
```
<title>
```
elements are a requirement. Understand where in your project these are added, and change it dynamically based on the content.
Implement skip links before each non-content block (e.g. just before the navigation) that are only visible once focused. Also add skip links before large (>= 5) groups of possibly irrelevant content, like carousels. Call them "Skip 'thing'", e.g. "Skip navigation" or "Skip sponsor links". Make sure they stay correct when structure changes.
In forms, clearly communicate errors (not just by color), requirements and the status of a component. Avoid using the disabled-state entirely. Controls should rather be invisible.
```
prefers-reduced-motion
```
is handled and respected.
Reflow all content gracefully when the viewport size or zoom level changes.
Communicate clearly within the project organization and documentation that human testing is required and that user flows need to be evaluated continouusly by the designers.
In the UI itself, never mention accessibility.

This skill does not constitute full awareness of everything that is important to develop in a way that it is accessible. If unsure, always document that and consult only official W3C/WCAG resources for help.

```
<html>
```
标签需要添加
```
lang
```
属性（以及任何使用外语的文本块——而非单个单词。如果项目是多语言的，需要根据需求动态更改该属性）。
```
<title>
```
标签是必填项。了解项目中这些标签的添加位置，并根据内容动态更改。
在每个非内容块之前（例如导航栏之前）实现仅在获得焦点时可见的跳转链接。在大型（≥5个）可能无关的内容组（如轮播）之前也添加跳转链接。命名为“跳过‘内容名称’”，例如“跳过导航”或“跳过赞助商链接”。确保结构变更时这些链接仍保持正确。
在表单中，清晰传达错误信息（不能仅通过颜色）、要求和组件状态。完全避免使用禁用状态，控件应改为隐藏。
处理并尊重
```
prefers-reduced-motion
```
特性。
当视口大小或缩放级别变化时，所有内容应能优雅地重排。
在项目组织和文档中明确说明，需要进行人工测试，且设计师需要持续评估用户流程。
在UI本身中，绝对不要提及“可访问性”一词。

本技能并未涵盖开发可访问应用所需的全部要点。如有疑问，请务必记录下来，并仅参考W3C/WCAG的官方资源寻求帮助。",