⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

Web可访问性开发指南：从语义化HTML到WCAG标准，构建无障碍网站

accessibility by kreerc/accessibility.md

63 周安装量

20 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/kreerc/accessibility.md --skill accessibility

开发代码质量用户体验

🇨🇳中文介绍

确保 Web 项目中的可访问性与代码质量

从一开始就考虑可访问性来构建 Web 项目至关重要，尤其是在人工手动测试受限（例如在 AI 驱动的开发中）的情况下。众所周知，事后补救可访问性的成本远高于从一开始就正确处理。对任何开发任务都采用可访问性优先的方法，并附上持续需求的详细文档。确保始终正确理解和实施超出本技能描述范围的可访问性标准。如果无法做到这一点，并且您正在处理现有的代码库，请谨慎地建议重构尚不具备可访问性的代码。这是一个必须在缺陷显现时就立即开始的过程，为此，需要理解和记录用户意图及应用程序约束。

代码注释与 WCAG 参考

大量添加代码注释，解释专门为实现可访问性而做的实现。在这些注释中，根据 WCAG 2.2 任何级别的需求来解释。如果相关，解释预期的用户流程。

使用语义化 HTML 和正确的结构

首先，对所有内容和控件使用语义化 HTML。对按钮使用真正的 <button> 元素，对布局使用 <header>/<nav>/<main>，对表单使用 <form> 和 <label>，对标题使用逻辑清晰的标题级别层次结构。例如，<button> 元素自带默认的键盘支持（可通过键盘聚焦和激活），而像这样的非语义元素则缺乏这些功能。要求使用现有的原生元素，如、或。如果无法避免使用自定义组件（通常无法避免），请遵循已建立的 ARIA 设计模式和。只有在没有替代方案时才使用 ARIA，而在大多数情况下，替代方案是存在的。如果确实使用了，请记录这个选择及其背后的理由。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

设计可访问的组件

每个组件的 HTML 结构必须反映其语义：对菜单或多选项控件使用列表，对标题使用标题元素，对表单字段组使用字段集和图例等。为焦点指示器（元素获得焦点时的轮廓或高亮）保持一致的样式，以便键盘用户始终能看到焦点位置。键盘可访问性不是可选的——确保用户仅通过键盘就能到达并操作每个交互元素（例如，酌情使用 Tab、Enter、空格、方向键）。这可能需要对自定义可聚焦元素添加 tabindex，并且仅使用负值，并为自定义小部件在脚本中处理按键事件。

记住 WCAG 关于触摸目标尺寸的规则。所有内容都应易于触及。鼠标或手势控制（如拖拽）需要提供替代方案。

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

持续维护与避免反模式

实现可访问性不是一次性任务——它需要随着项目的发展进行持续评估。为了长期保持最大的可访问性，每当添加内容或功能时，都将可访问性检查视为一项持续的要求。为未来的变更记录并强制执行的一些关键实践包括：

为新媒体提供替代文本： 每次添加图像或其他媒体时，强制要求提供替代文本（或等效的文本替代）。这可以是拉取请求或内容发布工作流程中的一个检查项。要求开发人员或内容作者包含 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 等。

进一步的待办事项

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

本技能并不构成对以可访问方式开发所需了解的所有重要事项的全面认识。如果不确定，请始终记录下来，并仅查阅官方的 W3C/WCAG 资源以寻求帮助。

🇺🇸English

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.

Code Comments and WCAG References

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.

Use Semantic HTML and Proper Structure

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> or <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.

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.

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 or added to the navigation landmarks ( etc.).

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.

Weekly Installs

Repository

kreerc/accessibility.md

GitHub Stars

First Seen

Feb 9, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

github-copilot60

gemini-cli59

opencode59

codex59

kimi-cli58

cursor58

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

123,700 周安装

<nav>, <main>, <aside>

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.)