AgentSkillsCN

a11y

适用于所有技术领域的通用无障碍设计最佳实践与标准（HTML、CSS、React、MUI、Astro、React Native）。确保符合 WCAG 2.1 AA 级标准，采用语义化 HTML、ARIA 标准、键盘导航功能，以及良好的色彩对比度。触发时机：在实现 UI 组件、添加交互元素，或确保无障碍合规性时。

SKILL.md
--- frontmatter
name: a11y
description: Universal accessibility best practices and standards across all technologies (HTML, CSS, React, MUI, Astro, React Native). WCAG 2.1 Level AA compliance, semantic HTML, ARIA, keyboard navigation, color contrast. Trigger: When implementing UI components, adding interactive elements, or ensuring accessibility compliance.
allowed-tools:
  - documentation-reader
  - web-search
  - file-reader

Accessibility (a11y) Skill

Overview

This skill centralizes accessibility guidelines and best practices for all technologies and frameworks used in the project, including HTML, CSS, React, MUI, Astro, React Native, and more. It covers semantic structure, ARIA usage, color contrast, keyboard navigation, and compliance with WCAG and WAI-ARIA standards.

Objective

Ensure all user interfaces meet accessibility standards (WCAG 2.1 Level AA minimum) across all technologies. This skill provides universal accessibility guidance that technology-specific skills can reference.

When to Use

Use this skill when:

  • •Building UI components with interactive elements
  • •Implementing forms, modals, or custom widgets
  • •Adding dynamic content or live regions
  • •Ensuring keyboard navigation
  • •Reviewing accessibility compliance
  • •Testing with screen readers

Don't use this skill for:

  • •Technology-specific implementation (delegate to react, html, etc.)
  • •General coding patterns (use conventions skill)
  • •Pure backend logic (no UI)

Critical Patterns

✅ REQUIRED: Semantic HTML Elements

html
<!-- ✅ CORRECT: Semantic elements -->
<nav>
  <a href="/home">Home</a>
</nav>
<main>
  <article>Content</article>
</main>
<button onClick="{action}">Submit</button>

<!-- ❌ WRONG: Non-semantic divs -->
<div class="nav">
  <div onClick="{navigate}">Home</div>
</div>
<div class="main">
  <div>Content</div>
</div>
<div onClick="{action}">Submit</div>

✅ REQUIRED: Keyboard Accessibility

typescript
// ✅ CORRECT: Keyboard events
<button
  onClick={handleClick}
  onKeyDown={(e) => e.key === 'Enter' && handleClick()}
>

// ❌ WRONG: Mouse-only events
<div onClick={handleClick}> // Not keyboard accessible

✅ REQUIRED: Form Labels

html
<!-- ✅ CORRECT: Associated label -->
<label htmlFor="email">Email Address</label>
<input id="email" type="email" />

<!-- ❌ WRONG: No label association -->
<div>Email Address</div>
<input type="email" />

✅ REQUIRED: Alt Text for Images

html
<!-- ✅ CORRECT: Descriptive alt for informative images -->
<img src="chart.png" alt="Sales increased 25% in Q4" />

<!-- ✅ CORRECT: Empty alt for decorative images -->
<img src="decorative-border.png" alt="" />

<!-- ❌ WRONG: Missing alt -->
<img src="chart.png" />

Conventions

Semantic HTML

  • •Use semantic elements (<nav>, <main>, <article>, <aside>, <footer>)
  • •Proper heading hierarchy (h1 → h2 → h3, no skipping levels)
  • •Use <button> for actions, <a> for navigation
  • •Form labels must be associated with inputs

ARIA

  • •Use ARIA only when semantic HTML is insufficient
  • •Prefer native elements over ARIA roles
  • •Common patterns: aria-label, aria-labelledby, aria-describedby
  • •Required for dynamic content: aria-live, aria-atomic

Keyboard Navigation

  • •All interactive elements must be keyboard accessible
  • •Logical tab order (use tabindex only when necessary)
  • •Visible focus indicators
  • •Escape key closes modals/dropdowns

Color and Contrast

  • •Text contrast ratio 4.5:1 minimum (7:1 for Level AAA)
  • •Large text (18pt+) minimum 3:1
  • •Don't rely solely on color to convey information
  • •Test with color blindness simulators

Screen Readers

  • •Provide alternative text for images (alt attribute)
  • •Use aria-hidden="true" for decorative elements
  • •Announce dynamic content changes with aria-live
  • •Test with screen readers (NVDA, JAWS, VoiceOver)

Decision Tree

Interactive element (button, link)? → Ensure keyboard accessible (Tab, Enter/Space), visible focus indicator, proper role and semantic element.

Form field? → Associate <label> with input (htmlFor/id), provide error messages with aria-describedby, announce errors with aria-live.

Dynamic content change? → Use aria-live="polite" for non-urgent updates, aria-live="assertive" for critical alerts, aria-atomic="true" if entire region should be read.

Custom widget (dropdown, modal, tabs)? → Follow WAI-ARIA Authoring Practices patterns, implement keyboard navigation (Arrow keys, Escape, Enter), manage focus properly.

Image or icon? → Decorative: alt="" or aria-hidden="true". Informative: descriptive alt text. Icon-only button: aria-label.

Color conveys meaning? → Add text label, icon, or pattern. Verify 4.5:1 contrast ratio for text, 3:1 for UI components.

Modal or overlay? → Trap focus inside modal, restore focus on close, allow Escape to dismiss, use aria-modal="true" and role="dialog".

Loading or status change? → Use aria-busy="true" during loading, role="status" for status messages, ensure screen reader announces completion.

Edge Cases

Skip links: Provide "Skip to main content" link as first focusable element for keyboard users to bypass navigation.

Focus trap issues: Libraries like React may interfere with focus management. Test focus trap explicitly in modals.

ARIA live regions throttling: Rapid updates may be throttled by screen readers. Debounce updates or use atomic regions.

Touch target size: Minimum 44x44 pixels for touch targets (WCAG 2.1). Use padding to increase clickable area.

Hidden content: Use aria-hidden="true" for visual-only elements. Use sr-only class for screen-reader-only text.

Custom controls: For complex widgets (datepickers, sliders), follow WAI-ARIA Authoring Practices patterns exactly.

References