Back to Details

accessibility-inclusive-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Accessibility Inclusive Design

无障碍包容性设计

Purpose

目的

Help an agent design and critique interfaces that are accessible, inclusive, keyboard-friendly, screen-reader-aware, and usable by diverse people.
Use this skill to turn accessibility into normal design practice. Treat accessibility as part of product quality, not as a late QA task or legal checkbox.
帮助Agent设计和评审具备无障碍、包容性、键盘友好、支持屏幕阅读器且可供多元人群使用的界面。
使用本技能将无障碍融入常规设计实践，将其视为产品质量的一部分，而非后期的QA任务或法律合规勾选框。

When to use this skill

何时使用本技能

Use this skill when the user asks for help with:
  • UI, UX, frontend implementation, product design, or design-system work.
  • Accessibility critique, audit, remediation, redesign, or conformance planning.
  • Forms, navigation, menus, filters, product lists, media, tables of contents, dynamic loading, or interactive widgets.
  • Keyboard interaction, focus management, screen reader behavior, semantic HTML, ARIA, color contrast, typography, responsive behavior, or inclusive content.
  • Design defaults for users with visual, auditory, motor, cognitive, language, device, bandwidth, or situational constraints.
当用户需要以下方面的帮助时使用本技能：
  • UI、UX、前端实现、产品设计或设计系统相关工作。
  • 无障碍评审、审计、修复、重新设计或合规规划。
  • 表单、导航、菜单、筛选器、产品列表、媒体、目录、动态加载或交互式组件。
  • 键盘交互、焦点管理、屏幕阅读器行为、语义化HTML、ARIA、色彩对比度、排版、响应式行为或包容性内容。
  • 为有视觉、听觉、运动、认知、语言、设备、带宽或情境限制的用户设计默认方案。

When not to use this skill

何时不使用本技能

Do not use this skill as the primary skill for:
  • Broad UX research planning unrelated to inclusion or accessibility.
  • Brand-only visual exploration where no interface behavior, content, or user task is being designed.
  • Backend-only architecture with no user-facing accessibility impact.
  • Legal advice. You may identify accessibility risk and recommend standards-aligned review, but do not make legal determinations.
以下场景请勿作为主要技能使用本技能：
  • 与包容性或无障碍无关的广义UX研究规划。
  • 仅涉及品牌视觉探索，未设计任何界面行为、内容或用户任务的场景。
  • 仅涉及后端架构，对用户端无障碍无影响的场景。
  • 法律咨询。你可以识别无障碍风险并建议符合标准的评审，但不要做出法律判定。

Core principles

核心原则

  1. Design for real diversity, not an average user. People differ in ability, technology, language, attention, literacy, device, bandwidth, and environment. Avoid solutions that only work for the designer’s setup.
  2. Start with purpose and user task. Clear purpose reduces complexity, cognitive load, and implementation waste.
  3. Prefer native semantics and standard web behavior. Use HTML elements that already include roles, states, keyboard behavior, and platform integration before recreating behavior with JavaScript and ARIA.
  4. Make structure machine-readable. Headings, landmarks, lists, labels, form controls, alt text, captions, and document metadata are part of the interface.
  5. Progressively enhance. Begin with meaningful content and working HTML. Add CSS and JavaScript only when they improve the experience without destroying the baseline.
  6. Give users control. Do not block zoom, trap focus, autoplay media, force motion, impose infinite scroll, or decide display preferences when user choice is feasible.
  7. Use convention as an accessibility feature. Familiar navigation, link styling, button affordance, form patterns, and predictable placement reduce cognitive effort.
  8. Make hidden state explicit. If something expands, loads, errors, becomes selected, or changes dynamically, communicate the state visually and programmatically.
  9. Content is part of design. Clear headings, descriptive links, plain language, usable labels, and helpful errors are accessibility features.
  10. Test beyond automation. Automated checks help, but keyboard walkthroughs, screen reader checks, device/browser testing, and disabled participant feedback uncover issues automation misses.
See references/principle-cards.md for each principle as a reusable card.
  1. 为真实的多样性设计，而非为平均用户设计。 人们在能力、使用的技术、语言、注意力、读写能力、设备、带宽和环境上各不相同。避免仅适用于设计师自身设备环境的解决方案。
  2. 从目的和用户任务出发。 清晰的目的能降低复杂度、认知负荷和实现浪费。
  3. 优先使用原生语义和标准Web行为。 在使用JavaScript和ARIA重新实现行为之前，优先使用已包含角色、状态、键盘行为和平台集成的HTML元素。
  4. 让结构可被机器读取。 标题、地标（landmark）、列表、标签、表单控件、替代文本、字幕和文档元数据都是界面的一部分。
  5. 渐进式增强。 从有意义的内容和可正常工作的HTML开始。仅在CSS和JavaScript能提升体验且不破坏基础功能的情况下才添加它们。
  6. 给予用户控制权。 在用户可以自主选择的情况下，不要阻止缩放、设置焦点陷阱、自动播放媒体、强制动效、强加无限滚动，或替用户决定显示偏好。
  7. 将惯例作为无障碍特性。 熟悉的导航、链接样式、按钮可供性、表单模式和可预测的位置能减少认知负担。
  8. 让隐藏状态显性化。 如果元素展开、加载、出错、被选中或发生动态变化，需要同时通过视觉和程序方式传达状态。
  9. 内容是设计的一部分。 清晰的标题、描述性链接、平实语言、可用的标签和有帮助的错误提示都是无障碍特性。
  10. 测试不能仅依赖自动化。 自动化检查有帮助，但键盘遍历、屏幕阅读器测试、设备/浏览器测试，以及残障参与者的反馈能发现自动化遗漏的问题。
每条原则的可复用卡片请参见 references/principle-cards.md。

Default recommendations

默认建议

Use these defaults unless the user provides stronger product context or constraints.
AreaDefaultWhy it is usually bestOverride only when
Accessibility targetDesign to WCAG AA-level expectations and current product/platform standard; treat legal conformance as a floor, not the goal.Uploaded sources repeatedly frame accessibility as built-in quality and identify AA as a common conformance target.The user has a regulated context, internal standard, or specific conformance target.
Product goalClarify the primary user task before layout or styling.Clear purpose simplifies decisions and reduces barriers.The user is only asking for a narrow component fix.
SemanticsUse native HTML first: 
button
, 
a
, 
label
, 
input
, 
fieldset
, 
legend
, 
nav
, 
main
, headings, lists.		Native elements include expected keyboard and assistive-technology behavior.The needed interaction has no suitable native pattern.
ARIAUse ARIA only to add missing names, relationships, live updates, and states to otherwise sound markup.ARIA changes semantics but does not automatically add behavior.A custom component truly needs ARIA roles/states and matching keyboard behavior.
LayoutUse flexible, content-driven, responsive layouts; avoid fixed widths/heights.Content, device sizes, zoom, and text settings vary.A fixed dimension is intrinsic to media or a constrained platform surface.
BreakpointsAdd breakpoints where content breaks, not for named devices.Device-specific breakpoints cannot cover all setups.A native app or embedded surface has fixed known constraints.
TypographyUse readable type, relative units, generous line height, comfortable measure, and real content.Readability supports low vision, dyslexia, cognitive load, language learners, and everyone else.Brand type is constrained; then test and tune size, spacing, weight, and contrast.
ContrastEnsure sufficient contrast and never use color alone; avoid unnecessary low contrast and avoid extreme glare as the only option.Low contrast excludes many users; excessive glare can harm some readers.A brand palette is fixed; then adapt tokens to meet contrast and comfort.
LinksKeep inline links visually identifiable, usually underlined, and make link text meaningful out of context.Screen readers list links independently; color-only links fail many users.Button-like CTAs may use button affordance, but still need clear text.
NavigationUse landmarked, list-based navigation with familiar placement and clear current-location cues.It works visually, without CSS, and in assistive technologies.A very small flow genuinely needs no navigation.
MenusDo not hide a short menu. For disclosure menus, use a real button, visible label, 
aria-expanded
, adjacent menu, and robust hidden state.		Hidden navigation adds an action cost and state complexity.Screen space is severely constrained or the menu is large.
FormsUse persistent labels, grouped controls when useful, clear required indicators, forgiving validation, and error recovery.Forms are high-risk for cognitive, motor, and screen reader barriers.Extremely short forms may not need grouping; labels still remain required.
ValidationValidate on submit first; after errors exist, give supportive inline feedback while the user corrects.Premature live validation can be noisy and stressful.The field is high-cost or security-sensitive and immediate feedback is clearly helpful.
PasswordsPrefer a show-password control over forcing duplicate password entry.It reduces cognitive and motor burden while preserving user control.Security policy prohibits reveal controls.
Dynamic loadingPrefer explicit “Load more” or user-triggered updates over infinite scroll. Announce loading and move focus after new content appears.Infinite scroll undermines keyboard navigation, control, and orientation.Research proves auto-loading is expected and an accessible fallback is provided.
MediaProvide captions, transcripts, and meaningful image alternatives.Different users need different sensory channels and contexts.Decorative images should use empty alt text rather than a description.
MotionKeep motion optional, purposeful, and controllable.Motion can distract, disorient, or trigger symptoms.Motion conveys essential state; still provide reduced-motion handling.
TestingRun at least keyboard-only, focus, semantic/DOM, contrast, responsive/zoom, and screen reader smoke checks.Automation cannot validate real interaction quality.The task is conceptual only; still mention testing needed before launch.
除非用户提供了更明确的产品上下文或约束，否则使用以下默认方案：
领域默认方案通常最优的原因仅在以下情况可覆盖
无障碍目标按照WCAG AA级要求和当前产品/平台标准进行设计；将法律合规视为底线，而非目标。上传的资料反复强调无障碍是内置质量，并将AA级作为常见合规目标。用户有受监管的场景、内部标准或特定的合规目标。
产品目标在布局或样式设计前明确主要用户任务。清晰的目的能简化决策并减少障碍。用户仅要求修复某个窄范围的组件。
语义优先使用原生HTML：
button
、
a
、
label
、
input
、
fieldset
、
legend
、
nav
、
main
、标题、列表。		原生元素包含预期的键盘和辅助技术行为。所需交互没有合适的原生模式。
ARIA仅在完善的标记基础上，使用ARIA补充缺失的名称、关系、实时更新和状态。ARIA会改变语义，但不会自动添加行为。自定义组件确实需要ARIA角色/状态及匹配的键盘行为。
布局使用灵活的、内容驱动的响应式布局；避免固定宽度/高度。内容、设备尺寸、缩放和文本设置各不相同。固定尺寸是媒体或受限平台界面的固有属性。
断点在内容换行处添加断点，而非针对特定设备命名。针对特定设备的断点无法覆盖所有配置。原生应用或嵌入式界面有固定的已知约束。
排版使用易读的字体、相对单位、充足的行高、舒适的行宽和真实内容。可读性支持低视力、阅读障碍、认知负荷、语言学习者和所有其他用户。品牌字体受限；此时需测试并调整字号、间距、字重和对比度。
对比度确保足够的对比度，且绝不仅使用颜色传达信息；避免不必要的低对比度，也避免将极端强光作为唯一选项。低对比度会将许多用户排除在外；过强的眩光可能会伤害部分读者。品牌调色板是固定的；此时需调整设计token以满足对比度和舒适度要求。
链接保持行内链接的视觉可识别性，通常带下划线，并让链接文本在脱离上下文时仍有意义。屏幕阅读器会独立列出链接；仅靠颜色区分的链接对许多用户无效。按钮式CTA可以使用按钮可供性，但仍需要清晰的文本。
导航使用带地标的、基于列表的导航，位置熟悉，当前位置提示清晰。它在视觉上、无CSS情况下以及辅助技术中都能正常工作。非常小的流程确实不需要导航。
菜单不要隐藏短菜单。对于展开式菜单，使用真实的
button
、可见标签、
aria-expanded
、相邻菜单和可靠的隐藏状态。		隐藏的导航会增加操作成本和状态复杂度。屏幕空间严重受限或菜单很大。
表单使用持久化标签、必要时的分组控件、清晰的必填标识、容错验证和错误恢复机制。表单在认知、运动和屏幕阅读器障碍方面风险很高。极短的表单可能不需要分组；但标签仍然是必需的。
验证优先在提交时验证；出现错误后，在用户更正时提供支持性的内联反馈。过早的实时验证可能会很嘈杂且有压力。字段是高成本或安全敏感的，且即时反馈明显有帮助。
密码优先使用显示密码控件，而非强制重复输入密码。它在保留用户控制权的同时减少了认知和运动负担。安全策略禁止显示控件。
动态加载优先使用明确的“加载更多”或用户触发的更新，而非无限滚动。加载时进行播报，并在新内容出现后移动焦点。无限滚动会破坏键盘导航、控制权和方向感。研究证明自动加载是预期的，且提供了无障碍的降级方案。
媒体提供字幕、文字记录和有意义的图像替代文本。不同的用户需要不同的感官通道和上下文。装饰性图像应使用空的alt文本，而非描述。
动效保持动效可选、有目的且可控。动效可能会分散注意力、导致定向障碍或引发症状。动效传达必要状态；但仍需提供减少动效的处理方式。
测试至少运行纯键盘、焦点、语义/DOM、对比度、响应式/缩放和屏幕阅读器冒烟测试。自动化无法验证真实的交互质量。任务仅为概念性的；但仍需提及上线前需要进行测试。

Required user questions

需要向用户询问的问题

Do not ask users to approve routine best practices. Apply the default and explain it.
Ask one focused question only when the answer affects a material recommendation. Use a 
question
tool or equivalent when available.
Ask when:
  1. Regulatory or organizational target is unknown and compliance is central.
    • Default: WCAG AA-level design and current product standard.
  2. Audience, assistive technologies, language, geography, or platform materially changes the design.
    • Default: broad web audience, keyboard and screen reader support, responsive browser behavior.
  3. A component may need a custom interaction pattern rather than native HTML.
    • Default: native HTML or simpler pattern.
  4. Brand voice conflicts with clear labels, plain language, or recognizable affordances.
    • Default: clear task language with brand personality secondary.
  5. A dynamic behavior could change user control, focus, or orientation.
    • Default: explicit user-triggered action with visible and programmatic feedback.
  6. The user requests a legal/conformance claim.
    • Default: provide design/implementation recommendations and recommend expert/legal validation.
Use the question-tool-ready prompts in references/decision-prompts.md.
不要要求用户批准常规最佳实践。直接应用默认方案并进行解释。
仅当答案会影响实质性建议时，才提出一个聚焦的问题。如有可用的
question
工具或等效工具时使用它们。
在以下情况下询问：
  1. 监管或组织目标未知且合规是核心要求时。
    • 默认：WCAG AA级设计和当前产品标准。
  2. 受众、辅助技术、语言、地域或平台会显著改变设计时。
    • 默认：广泛的Web受众、键盘和屏幕阅读器支持、响应式浏览器行为。
  3. 组件可能需要自定义交互模式而非原生HTML时。
    • 默认：原生HTML或更简单的模式。
  4. 品牌调性与清晰的标签、平实语言或可识别的可供性冲突时。
    • 默认：清晰的任务语言，品牌个性次之。
  5. 动态行为可能改变用户控制权、焦点或方向感时。
    • 默认：明确的用户触发操作，附带视觉和程序层面的反馈。
  6. 用户要求法律/合规声明时。
    • 默认：提供设计/实现建议，并建议进行专家/法律验证。
请使用 references/decision-prompts.md 中适配问题工具的提示词。

Workflow

工作流程

A. Critique existing UI, screenshots, code, or flows

A. 评审现有UI、截图、代码或流程

Inspect in this order:
  1. Task and purpose
    • What is the user trying to do?
    • Is the primary path obvious and unnecessary complexity removed?
  2. Structure and semantics
    • Are document title, language, headings, landmarks, lists, controls, labels, and relationships meaningful?
    • Does source order match reading and focus order?
  3. Keyboard and focus
    • Can every interactive element be reached, seen, operated, and exited by keyboard?
    • Are focus states visible and not removed?
    • Is focus managed after disclosures, in-page links, validation, and dynamic loading?
  4. Interaction behavior
    • Are controls recognizable?
    • Are states and changes communicated visually and programmatically?
    • Does the interface preserve user control?
  5. Content and labels
    • Are headings, links, form labels, button names, instructions, and errors clear out of context?
    • Is brand language secondary to task clarity?
  6. Visual presentation
    • Are contrast, text size, line height, measure, spacing, and grouping readable?
    • Is information conveyed by more than color, position, or sound alone?
  7. Forms and errors
    • Are labels persistent and associated?
    • Are required fields clear?
    • Are errors announced, located near the user’s work, and actionable?
  8. Media and alternatives
    • Are images, icons, video, audio, and non-text cues available through appropriate alternatives?
  9. Responsive and environmental resilience
    • Does it work with zoom, text resizing, narrow/wide viewports, slow networks, disabled CSS/JS, and user font/color preferences?
  10. Testing and maintainability
  • Are accessibility checks embedded in the component/design-system workflow?
Output critique as:
  • Severity: blocker, major, moderate, minor.
  • Who is affected: keyboard users, screen reader users, low-vision users, cognitive load, motor access, language/literacy, low bandwidth, etc.
  • Why it matters.
  • Recommended fix.
  • Implementation note.
  • Test to verify.
按以下顺序检查：
  1. 任务与目的
    • 用户想要做什么？
    • 主要路径是否清晰，且已移除不必要的复杂度？
  2. 结构与语义
    • 文档标题、语言、标题、地标、列表、控件、标签和关系是否有意义？
    • 源码顺序是否与阅读和焦点顺序一致？
  3. 键盘与焦点
    • 每个交互元素是否都可以通过键盘访问、看到、操作和退出？
    • 焦点状态是否可见且未被移除？
    • 在展开/收起、页内链接、验证和动态加载后是否管理了焦点？
  4. 交互行为
    • 控件是否可识别？
    • 状态和变化是否通过视觉和程序方式传达？
    • 界面是否保留了用户控制权？
  5. 内容与标签
    • 标题、链接、表单标签、按钮名称、说明和错误提示在脱离上下文时是否清晰？
    • 品牌语言是否次于任务清晰度？
  6. 视觉呈现
    • 对比度、文本大小、行高、行宽、间距和分组是否易读？
    • 信息是否不仅仅通过颜色、位置或声音传达？
  7. 表单与错误
    • 标签是否持久且关联正确？
    • 必填字段是否清晰？
    • 错误是否被播报、位于用户操作区域附近且可操作？
  8. 媒体与替代方案
    • 图像、图标、视频、音频和非文本提示是否有合适的替代方案？
  9. 响应式与环境适应性
    • 在缩放、文本调整、窄/宽视口、慢速网络、禁用CSS/JS以及用户字体/颜色偏好下是否正常工作？
  10. 测试与可维护性
    • 无障碍检查是否已嵌入组件/设计系统工作流？
评审结果按以下格式输出：
  • 严重程度：阻断级（blocker）、严重（major）、中等（moderate）、轻微（minor）。
  • 受影响人群：键盘用户、屏幕阅读器用户、低视力用户、认知负荷、运动访问、语言/读写能力、低带宽等。
  • 重要性原因。
  • 建议修复方案。
  • 实现说明。
  • 验证测试。

B. Create or improve a design

B. 创建或改进设计

Proceed in this order:
  1. Clarify the feature and user task.
    • If missing, ask one focused question and propose the default.
  2. Choose the simplest useful pattern.
    • Prefer native controls and familiar conventions.
  3. Establish structure.
    • Define headings, regions, reading order, navigation, form groups, and content relationships before styling.
  4. Write labels and content.
    • Use direct, descriptive, context-independent copy.
  5. Define interaction and state.
    • Specify keyboard behavior, focus order, visible focus, state announcements, loading, errors, and recovery.
  6. Apply visual design.
    • Tune typography, contrast, spacing, grouping, affordance, and responsive behavior.
  7. Add progressive enhancement.
    • Add JavaScript only after the HTML baseline works.
  8. Validate edge cases.
    • Test zoom, long content, localization, RTL if relevant, slow network, disabled CSS/JS, and alternative input.
  9. Explain decisions.
    • Tie recommendations to user impact, not just standards.
按以下顺序进行：
  1. 明确功能和用户任务。
    • 如果缺失，提出一个聚焦的问题并给出默认方案。
  2. 选择最简单的可用模式。
    • 优先使用原生控件和熟悉的惯例。
  3. 建立结构。
    • 在样式设计之前定义标题、区域、阅读顺序、导航、表单分组和内容关系。
  4. 编写标签和内容。
    • 使用直接、描述性、不依赖上下文的文案。
  5. 定义交互和状态。
    • 明确键盘行为、焦点顺序、可见焦点、状态播报、加载、错误和恢复机制。
  6. 应用视觉设计。
    • 调整排版、对比度、间距、分组、可供性和响应式行为。
  7. 添加渐进式增强。
    • 仅在HTML基础功能正常工作后添加JavaScript。
  8. 验证边缘情况。
    • 测试缩放、长内容、本地化、RTL（如相关）、慢速网络、禁用CSS/JS和替代输入方式。
  9. 解释决策。
    • 将建议与用户影响关联起来，而不仅仅是标准。

Decision framework

决策框架

When choosing a pattern, prefer the first option that satisfies the user task:
  1. No interaction needed: Use semantic static content.
  2. Native interaction exists: Use the native element.
  3. Native interaction can be styled: Keep native behavior and style labels/containers rather than replacing controls.
  4. Progressive enhancement is enough: Keep the baseline form/link behavior and enhance with JS.
  5. Custom interaction is unavoidable: Implement the full pattern: role, name, state, keyboard behavior, focus management, visible affordance, instructions, and tests.
  6. The pattern hides content or takes control: Reconsider. Ask whether the product context truly requires it.
  7. The pattern depends on user preferences: Provide choice or respect browser/OS settings.
选择模式时，优先选择满足用户任务的第一个选项：
  1. 无需交互： 使用语义化静态内容。
  2. 存在原生交互： 使用原生元素。
  3. 原生交互可样式化： 保留原生行为，仅对标签/容器进行样式设置，而非替换控件。
  4. 渐进式增强足够： 保留基础的表单/链接行为，用JS进行增强。
  5. 自定义交互不可避免： 实现完整模式：角色、名称、状态、键盘行为、焦点管理、可见可供性、说明和测试。
  6. 模式会隐藏内容或夺取控制权： 重新考虑。询问产品场景是否确实需要这样做。
  7. 模式依赖用户偏好： 提供选择或尊重浏览器/操作系统设置。

Practical rules

实用规则

Document and page structure

文档和页面结构

  • Include a valid doctype.
  • Declare the page language with 
    lang
    ; declare 
    dir
    for right-to-left languages.
  • Use one meaningful document 
    <title>
    that names the current page or result state.
  • Use one primary 
    <main>
    region for the unique page content.
  • Provide a skip link to main content for sighted keyboard users.
  • Use headings for structure, not visual size. Do not skip heading levels just to achieve a style.
  • Use lists for grouped navigation and grouped content.
  • Ensure source order makes sense when read top-to-bottom.
  • 包含有效的doctype。
  • 使用
    lang
    声明页面语言；对于从右到左的语言，声明
    dir
    。
  • 使用一个有意义的文档
    <title>
    ，标明当前页面或结果状态。
  • 为页面唯一内容使用一个主要
    <main>
    区域。
  • 为有视力的键盘用户提供跳转到主内容的链接。
  • 使用标题来构建结构，而非用于调整视觉大小。不要仅为了实现样式而跳过标题层级。
  • 对分组的导航和内容使用列表。
  • 确保源码顺序从上到下阅读时合理。

Navigation and wayfinding

导航与寻路

  • Put primary navigation in a 
    nav
    landmark.
  • Label multiple navigation landmarks uniquely, such as “site” and “contents”.
  • Keep familiar placement and recognizable shapes.
  • Indicate the current page/section with more than color.
  • For current-page links, avoid redundant reload behavior; use a same-page link to main content when appropriate, or a clear described current state.
  • Use tables of contents for long pages instead of complex dropdown submenus when the goal is section navigation.
  • 将主导航放在
    nav
    地标中。
  • 为多个导航地标添加唯一标签，例如“站点”和“目录”。
  • 保持熟悉的位置和可识别的形状。
  • 不仅仅使用颜色来指示当前页面/章节。
  • 对于当前页面的链接，避免冗余的重新加载行为；适当时使用指向主内容的同页链接，或清晰描述的当前状态。
  • 当目标是章节导航时，长页面使用目录而非复杂的下拉子菜单。

Buttons, links, and controls

按钮、链接和控件

  • Use 
    button
    for actions and 
    a href
    for navigation.
  • Do not use a clickable 
    div
    or 
    span
    when a native element fits.
  • Do not remove button or link affordance without replacing it with an equally clear affordance.
  • Icon-only controls need an accessible name. Prefer visible text when space allows.
  • Keep touch targets generous and separated; use full-row vertical navigation on narrow touch viewports.
  • Invisible elements must not be focusable.
  • 操作用
    button
    ，导航用
    a href
    。
  • 当原生元素适用时，不要使用可点击的
    div
    或
    span
    。
  • 不要移除按钮或链接的可供性，除非用同样清晰的可供性替代。
  • 仅含图标的控件需要无障碍名称。空间允许时优先使用可见文本。
  • 保持触摸目标充足且相互分隔；在窄触摸视口上使用全宽垂直导航。
  • 不可见元素不可获得焦点。

Keyboard and focus

键盘与焦点

  • Every actionable control must be reachable by keyboard.
  • Every focused control must have a visible focus indicator.
  • Do not set 
    outline: none
    unless you provide a stronger replacement.
  • Do not use positive 
    tabindex
    to rearrange navigation. Fix the source order instead.
  • Use 
    tabindex="-1"
    only for programmatic focus targets such as in-page headings after smooth scroll or newly loaded content.
  • When JavaScript hijacks native behavior, restore focus movement, URL updates, and expected keyboard behavior.
  • 每个可操作控件都必须可以通过键盘访问。
  • 每个获得焦点的控件都必须有可见的焦点指示器。
  • 不要设置
    outline: none
    ，除非你提供了更明显的替代方案。
  • 不要使用正的
    tabindex
    来重新排列导航顺序。改为修复源码顺序。
  • 仅将
    tabindex="-1"
    用于程序化焦点目标，例如平滑滚动后的页内标题或新加载的内容。
  • 当JavaScript劫持原生行为时，恢复焦点移动、URL更新和预期的键盘行为。

Forms

表单

  • Every input has a persistent, associated label.
  • Placeholder text is only a hint; never use it as the only label.
  • Use 
    fieldset
    and 
    legend
    when they clarify multiple related controls; avoid them when they add noise without benefit.
  • Ask only for information needed to complete the task.
  • Mark required fields visibly and programmatically.
  • Put errors near the user’s current work, not only at the top of the page.
  • Separate “there are errors” from “how to fix this field.”
  • Use 
    aria-invalid
    and 
    aria-describedby
    for invalid fields and remediation text when appropriate.
  • Use live regions for asynchronous form or loading feedback, but do not over-announce every keystroke.
  • Debounce live validation and avoid noisy, aggressive validation.
  • Prefer “show password” to duplicate password fields unless policy prevents it.
  • 每个输入框都有持久的、关联的标签。
  • 占位符文本仅为提示；绝不要将其作为唯一标签。
  • 当
    fieldset
    和
    legend
    能阐明多个相关控件时使用它们；当它们只会增加噪音而无益处时避免使用。
  • 仅询问完成任务所需的信息。
  • 以视觉和程序方式标记必填字段。
  • 将错误放在用户当前操作区域附近，而非仅放在页面顶部。
  • 将“存在错误”与“如何修复该字段”分开。
  • 适当时，对无效字段和修复文本使用
    aria-invalid
    和
    aria-describedby
    。
  • 对异步表单或加载反馈使用实时区域（live region），但不要过度播报每次按键。
  • 对实时验证进行防抖处理，避免嘈杂、激进的验证。
  • 优先使用“显示密码”而非重复密码字段，除非策略禁止。

Dynamic content

动态内容

  • Prefer explicit actions such as “Apply filters” and “Load more” when changes are consequential.
  • Announce loading and completion to screen readers.
  • Prevent duplicate loading actions while requests are pending.
  • After new content loads, move focus to the first meaningful new item when the trigger is displaced.
  • Avoid infinite scroll by default.
  • If using live regions, choose polite/assertive behavior based on urgency and avoid interrupting routine reading unless necessary.
  • 当变化会产生影响时，优先使用明确的操作，例如“应用筛选”和“加载更多”。
  • 向屏幕阅读器播报加载和完成状态。
  • 请求待处理时防止重复加载操作。
  • 新内容加载后，当触发器被移位时，将焦点移到第一个有意义的新项目上。
  • 默认避免无限滚动。
  • 如果使用实时区域，根据紧急程度选择polite/assertive模式，除非必要，否则避免打断常规阅读。

Visual design and readability

视觉设计与可读性

  • Use real content early. Do not design only with idealized placeholder text.
  • Choose typefaces for legibility, character distinction, language support, and required weights/styles.
  • Use relative units for text, spacing, and layout.
  • Keep line length comfortable; avoid overly wide or narrow text blocks.
  • Use unitless line-height, typically around 1.5 for body text unless typography testing supports another value.
  • Avoid justified text for web body copy unless hyphenation and language support are reliable and tested.
  • Use enough contrast for text and UI states, but avoid unnecessary harshness as the only reading mode.
  • Convey state with shape, text, icon, placement, or pattern, not color alone.
  • Use whitespace and proximity to clarify grouping.
  • 尽早使用真实内容。不要仅用理想化的占位符文本进行设计。
  • 选择字体时考虑易读性、字符区分度、语言支持和所需的字重/样式。
  • 文本、间距和布局使用相对单位。
  • 保持行宽舒适；避免过宽或过窄的文本块。
  • 使用无单位的line-height，正文通常约为1.5，除非排版测试支持其他值。
  • 网页正文避免使用两端对齐文本，除非断字和语言支持可靠且经过测试。
  • 文本和UI状态使用足够的对比度，但避免将不必要的高对比度作为唯一阅读模式。
  • 使用形状、文本、图标、位置或图案传达状态，而非仅靠颜色。
  • 使用留白和邻近性来明确分组。

Media and non-text content

媒体与非文本内容

  • Decorative images use empty alt text.
  • Informative images get concise alt text that communicates purpose or content.
  • Linked images describe the link destination or action, not merely the image.
  • Complex images, infographics, and charts need surrounding explanation or structured text alternatives.
  • Video with speech needs captions and a transcript.
  • Captions should identify speaker changes and important non-speech audio.
  • Media players must be keyboard operable, visibly focusable, and screen-reader labeled.
  • 装饰性图像使用空的alt文本。
  • 信息性图像使用简洁的alt文本，传达目的或内容。
  • 带链接的图像描述链接目标或操作，而非仅描述图像本身。
  • 复杂图像、信息图表和图表需要周围的解释或结构化的文本替代方案。
  • 带语音的视频需要字幕和文字记录。
  • 字幕应标识说话人变化和重要的非语音音频。
  • 媒体播放器必须可通过键盘操作、可见焦点、且有屏幕阅读器标签。

Internationalization and environmental resilience

国际化与环境适应性

  • Do not assume one language, address format, name format, date format, device, connection speed, pointer type, or viewport.
  • Use flexible data structures and UI labels where international variation is likely.
  • Test long labels, translated strings, names, product titles, and variable content lengths.
  • Support RTL layout when targeting RTL languages; prefer layout systems that respond to 
    dir
    .
  • Do not block browser zoom, text resizing, user font choices, or high-contrast settings.
  • Treat web fonts, icons, and scripts as enhancements, not requirements for reading or basic operation.
  • 不要假设只有一种语言、地址格式、姓名格式、日期格式、设备、连接速度、指针类型或视口。
  • 在可能存在国际差异的地方使用灵活的数据结构和UI标签。
  • 测试长标签、翻译后的字符串、姓名、产品标题和可变内容长度。
  • 针对RTL语言时支持RTL布局；优先使用响应
    dir
    的布局系统。
  • 不要阻止浏览器缩放、文本调整、用户字体选择或高对比度设置。
  • 将Web字体、图标和脚本视为增强功能，而非阅读或基本操作的必需条件。

Accessibility and inclusion requirements

无障碍与包容性要求

Before finalizing, verify:
  • The product can be used without a mouse.
  • Focus order follows visual and logical order.
  • Focus is visible at all times.
  • Interactive elements have accessible names, roles, states, and values.
  • Important content is not hidden in background images, pseudo-elements, color, audio, or layout position alone.
  • Page structure can be navigated by headings and landmarks.
  • Forms can be understood, completed, corrected, and submitted with assistive technology.
  • Error, loading, expanded/collapsed, selected, and invalid states are communicated visually and programmatically.
  • Text remains readable under zoom, text resizing, small screens, user font settings, and slow networks.
  • Media alternatives are provided.
  • Automated checks are complemented by manual keyboard and assistive-technology checks.
最终确定前，验证：
  • 产品无需鼠标即可使用。
  • 焦点顺序遵循视觉和逻辑顺序。
  • 焦点始终可见。
  • 交互元素具有无障碍名称、角色、状态和值。
  • 重要内容不会仅隐藏在背景图像、伪元素、颜色、音频或布局位置中。
  • 页面结构可通过标题和地标导航。
  • 表单可通过辅助技术理解、填写、更正和提交。
  • 错误、加载、展开/收起、选中和无效状态通过视觉和程序方式传达。
  • 在缩放、文本调整、小屏幕、用户字体设置和慢速网络下，文本仍保持可读。
  • 提供媒体替代方案。
  • 自动化检查辅以手动键盘和辅助技术检查。

Frontend implementation guidance

前端实现指导

  • Start with semantic HTML; then add CSS; then add JavaScript.
  • Keep controls native where possible. Style labels or wrappers instead of replacing inputs.
  • Use CSS attribute selectors tied to semantic state, such as 
    [aria-invalid="true"]
    , 
    [aria-expanded="true"]
    , or 
    [aria-pressed="true"]
    , to reduce drift between state and styling.
  • Do not create controls that require JavaScript for basic access when a working form/link fallback is possible.
  • If a component hides content, ensure hidden content is removed from the focus order.
  • If a component reveals content, place the revealed content near the trigger in source order unless there is a strong reason not to.
  • If a component changes page content asynchronously, provide live-region feedback and deliberate focus management.
  • Use design tokens for focus, contrast, spacing, disabled state, error state, and touch target sizing so accessibility is built into the system.
  • Test components with long content, different languages, missing assets, disabled CSS, failed scripts, high contrast mode, zoom, and keyboard-only operation.
  • For design systems, document expected markup, keyboard behavior, ARIA states, focus behavior, content rules, and anti-patterns for each component.
  • 从语义化HTML开始；然后添加CSS；然后添加JavaScript。
  • 尽可能保持控件原生。对标签或容器进行样式设置，而非替换输入框。
  • 使用与语义状态绑定的CSS属性选择器，例如
    [aria-invalid="true"]
    、
    [aria-expanded="true"]
    或
    [aria-pressed="true"]
    ，以减少状态与样式之间的偏差。
  • 只要有可行的表单/链接降级方案，就不要创建基础访问就需要JavaScript的控件。
  • 如果组件隐藏内容，确保隐藏内容已从焦点顺序中移除。
  • 如果组件显示内容，除非有充分理由，否则将显示的内容放在源码顺序中触发器附近。
  • 如果组件异步更改页面内容，提供实时区域反馈和审慎的焦点管理。
  • 为焦点、对比度、间距、禁用状态、错误状态和触摸目标大小使用设计token，以便无障碍内建于系统中。
  • 使用长内容、不同语言、缺失资源、禁用CSS、脚本失败、高对比度模式、缩放和纯键盘操作测试组件。
  • 对于设计系统，为每个组件记录预期的标记、键盘行为、ARIA状态、焦点行为、内容规则和反模式。

Quality checklist

质量检查清单

Use the full checklists in references/checklists.md. At minimum, before answering:
  • The recommendation starts from the user task.
  • Native semantics are preferred over custom controls.
  • Keyboard and focus behavior are specified.
  • Screen reader names, states, and relationships are specified where relevant.
  • Color is never the only cue.
  • Text and labels are clear out of context.
  • Errors, loading, and empty states are included.
  • Responsive, zoom, and variable-content behavior are addressed.
  • The response explains user impact and gives test steps.
使用 references/checklists.md 中的完整检查清单。在回答之前，至少检查：
  • 建议从用户任务出发。
  • 优先使用原生语义而非自定义控件。
  • 明确了键盘和焦点行为。
  • 相关处明确了屏幕阅读器名称、状态和关系。
  • 绝不将颜色作为唯一提示。
  • 文本和标签在脱离上下文时清晰。
  • 包含错误、加载和空状态。
  • 涵盖了响应式、缩放和可变内容行为。
  • 回复解释了用户影响并给出了测试步骤。

Common mistakes to avoid

需要避免的常见错误

See the full anti-pattern list in references/anti-patterns.md. The highest-risk mistakes are:
  • Clickable 
    div
    controls.
  • Placeholder-only labels.
  • Removing focus styles.
  • Disabling zoom.
  • Hiding navigation unnecessarily.
  • Icon-only controls without accessible names.
  • Color-only states.
  • Infinite scroll without an explicit alternative.
  • JavaScript-dependent static content.
  • Visual order that differs from source/focus order.
  • ARIA used to patch a broken native pattern.
  • Relying on automated tests alone.
完整的反模式列表请参见 references/anti-patterns.md。最高风险的错误包括：
  • 可点击的
    div
    控件。
  • 仅用占位符作为标签。
  • 移除焦点样式。
  • 禁用缩放。
  • 不必要地隐藏导航。
  • 没有无障碍名称的纯图标控件。
  • 仅靠颜色区分的状态。
  • 没有明确替代方案的无限滚动。
  • 依赖JavaScript的静态内容。
  • 视觉顺序与源码/焦点顺序不一致。
  • 用ARIA修补有缺陷的原生模式。
  • 仅依赖自动化测试。

How to explain recommendations to the user

如何向用户解释建议

Use practical, user-impact language:
  • “This is not just compliance; it prevents keyboard and screen reader users from getting stuck.”
  • “The native element is simpler and more reliable because the browser already provides role, keyboard behavior, and platform integration.”
  • “This label needs to make sense out of context because screen readers can list controls and links independently.”
  • “The visual state also needs a programmatic state so assistive technology receives the same information.”
  • “This pattern preserves user control; the alternative would make the interface act unexpectedly.”
  • “The default is inclusive for more users, and it does not prevent brand expression.”
When recommending a tradeoff, state:
  1. the default,
  2. the user groups protected,
  3. the cost or constraint,
  4. the condition that would justify an override,
  5. how to test the override.
使用实用的、以用户影响为导向的语言：
  • “这不仅仅是合规；它能避免键盘和屏幕阅读器用户陷入困境。”
  • “原生元素更简单、更可靠，因为浏览器已经提供了角色、键盘行为和平台集成。”
  • “这个标签需要在脱离上下文时也有意义，因为屏幕阅读器可以独立列出控件和链接。”
  • “视觉状态也需要对应的程序状态，以便辅助技术接收相同的信息。”
  • “这种模式保留了用户控制权；替代方案会让界面表现得不符合预期。”
  • “默认方案对更多用户更具包容性，且不会妨碍品牌表达。”
当建议权衡方案时，说明：
  1. 默认方案，
  2. 受保护的用户群体，
  3. 成本或约束，
  4. 证明覆盖默认方案的条件，
  5. 如何测试覆盖方案。