Accessibility (A11y) Skill

技能描述

专注于 Web 无障碍标准 (WCAG) 的检查与修复。帮助开发者发现潜在的访问性问题并提供修复代码。

📝 代码示例

1. 图片无障碍

// ✅ 正确的图片无障碍实现
function AccessibleImage({ src, alt, caption }: ImageProps) {
  return (
    <figure>
      <img
        src={src}
        alt={alt} // 描述性文字，装饰性图片使用 alt=""
        loading="lazy"
      />
      {caption && <figcaption>{caption}</figcaption>}
    </figure>
  );
}

// ❌ 避免
<img src="photo.jpg" /> // 缺少 alt
<img src="photo.jpg" alt="image" /> // 无意义的 alt

2. 表单无障碍

// ✅ 正确的表单关联
function AccessibleForm() {
  return (
    <form>
      <div>
        <label htmlFor="email">邮箱地址</label>
        <input
          id="email"
          type="email"
          aria-describedby="email-hint"
          aria-required="true"
        />
        <span id="email-hint">我们会向此邮箱发送验证码</span>
      </div>

      <div>
        <label htmlFor="password">密码</label>
        <input
          id="password"
          type="password"
          aria-describedby="password-error"
          aria-invalid={hasError ? 'true' : 'false'}
        />
        {hasError && (
          <span id="password-error" role="alert">
            密码至少需要8个字符
          </span>
        )}
      </div>

      <button type="submit">登录</button>
    </form>
  );
}

3. 键盘导航

// ✅ 可键盘操作的按钮
function AccessibleButton({ onClick, children }: ButtonProps) {
  return (
    <button
      onClick={onClick}
      onKeyDown={(e) => {
        if (e.key === 'Enter' || e.key === ' ') {
          e.preventDefault();
          onClick();
        }
      }}
    >
      {children}
    </button>
  );
}

// ✅ 焦点管理样式
const focusStyles = css`
  &:focus-visible {
    outline: 3px solid #005fcc;
    outline-offset: 2px;
  }
`;

4. 模态框焦点陷阱

// ✅ 模态框无障碍实现
function AccessibleModal({ isOpen, onClose, title, children }: ModalProps) {
  const modalRef = useRef<HTMLDivElement>(null);
  const previousActiveElement = useRef<Element | null>(null);

  useEffect(() => {
    if (isOpen) {
      previousActiveElement.current = document.activeElement;
      modalRef.current?.focus();
      document.body.style.overflow = 'hidden';
    } else {
      previousActiveElement.current?.focus();
      document.body.style.overflow = '';
    }
  }, [isOpen]);

  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === 'Escape') onClose();
  };

  if (!isOpen) return null;

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      ref={modalRef}
      tabIndex={-1}
      onKeyDown={handleKeyDown}
    >
      <div className="modal-backdrop" onClick={onClose} aria-hidden="true" />
      <div className="modal-content">
        <h2 id="modal-title">{title}</h2>
        {children}
        <button onClick={onClose} aria-label="关闭对话框">
          <CloseIcon />
        </button>
      </div>
    </div>
  );
}

5. 颜色对比度

/* ✅ 符合 WCAG AA 标准的对比度 */
.text-primary {
  color: #1a1a1a; /* 与白色背景对比度 > 12:1 */
}

.text-secondary {
  color: #4a4a4a; /* 与白色背景对比度 > 7:1 */
}

/* ✅ 不只依赖颜色传达信息 */
.status-success {
  color: #0a8754;
}
.status-success::before {
  content: '✓ '; /* 同时使用图标 */
}

/* ✅ 聚焦状态清晰可见 */
:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}

6. ARIA 地标与语义化

// ✅ 语义化页面结构
function AccessibleLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <header role="banner">
        <nav aria-label="主导航">
          <ul>
            <li><a href="/">首页</a></li>
            <li><a href="/about">关于</a></li>
          </ul>
        </nav>
      </header>

      <main role="main" id="main-content">
        <h1>页面标题</h1>
        {children}
      </main>

      <aside aria-label="侧边栏">
        {/* 侧边栏内容 */}
      </aside>

      <footer role="contentinfo">
        {/* 页脚内容 */}
      </footer>
    </>
  );
}

♿ 常用指令

1. 快速审查 (Audit)

/ui-design 审查这段代码的无障碍问题
# 关注点:
# - 语义化标签 (nav, main, aside)
# - ARIA 属性使用
# - 键盘可访问性 (tabindex, focus)
# - 图片 Alt 文本

2. 对比度检查 (Contrast)

/ui-design 检查这个配色的对比度是否符合 WCAG AA 标准

3. 修复建议 (Fix)

/ui-design 修复这个表单的 Label 关联和 ARIA 描述问题
/ui-design 为这个模态框添加 Focus Trap (焦点陷阱) 功能

✅ Self-Checklist (自查清单)

在提交代码前，请检查：

• 所有的 <img> 都有 alt 属性吗？
• 所有的表单输入框都有对应的 <label> 吗？
• 按钮是否有清晰的文字描述（避免仅图标）？
• 页面是否可以仅用键盘顺畅操作？
• 颜色对比度是否足够清晰？