跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
法律与合规

a11y-page-audit

Run an accessibility and keyboard navigation audit on a web page or project, then fix what it finds — audit, fix, and verify, not just a report. Use whenever the user asks about accessibility, a11y, keyboard navigation, focus styles or focus management, screen readers, ARIA, WCAG compliance, skip links, tab order, or making a site keyboard-navigable before shipping.

glrodasz · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add glrodasz/dotfiles --skill a11y-page-audit

技能说明


name: a11y-page-audit description: > Run an accessibility and keyboard navigation audit on a web page or project, then fix what it finds — audit, fix, and verify, not just a report. Use whenever the user asks about accessibility, a11y, keyboard navigation, focus styles or focus management, screen readers, ARIA, WCAG compliance, skip links, tab order, or making a site keyboard-navigable before shipping.

Accessibility & Keyboard Navigation Audit

Audit-then-fix workflow. The goal is to leave the codebase with working keyboard nav, visible focus indicators, correct semantics, and proper ARIA — not just a report.

Phase 0 — Understand the target

  1. Input type: directory → scan components, layouts, global CSS. URL → fetch HTML and flag that source fixes need the actual codebase.
  2. Framework: determines where layouts, head tags, and route changes live.
  3. Design system: tokens / CSS custom properties / Tailwind / component library — determines how to implement the focus ring.

If ambiguous, ask one focused question before proceeding.

Phase 1 — Audit & fix

Work through each category: record file path, current state, verdict (✅ PASS / ⚠️ WARN / ❌ FAIL), then apply the fix pattern for every ❌ and ⚠️.

1.1 Global CSS resets

Check: * { outline: none }, *:focus { outline: none }, or any blanket outline: 0 without a paired visible alternative — the most common a11y regression.

Fix: remove global outline resets. If a component legitimately needs a custom indicator (e.g. box-shadow ring on inputs), keep outline: none only when paired with a visible alternative using the focus token.

1.2 Focus ring system

Check: is there a shared, theme-aware focus ring?

  • A design token / custom property for focus color that adapts between light and dark mode
  • Passes WCAG AA contrast for UI components (3:1) against each mode's background
  • A global :focus-visible rule applying the ring
  • Components aliasing the token rather than hardcoding hex values

Fix — if missing, build it:

  1. Add a system-level focus color token per theme. Pick from the existing palette when possible; each mode's value must pass 3:1 against that mode's background. If the brand palette has no passing color, use the closest passing color and document the override — don't sacrifice visibility for brand consistency.
  2. Add component-level tokens aliasing it: --focus-ring-color, --focus-ring-width: 2px, --focus-ring-offset: 2px.
  3. Add the global rule:
    :focus-visible {
      outline: var(--focus-ring-width) solid var(--focus-ring-color);
      outline-offset: var(--focus-ring-offset);
    }
    
    Do NOT set border-radius here — outline follows the element's existing radius automatically; setting it changes the element's shape on focus.
  4. Re-point existing per-component focus tokens to alias the system color.

1.3 Interactive elements

Check focus visibility and keyboard operability for: buttons (real <button> vs <div onClick>), links (incl. anchor-wrapped cards), form inputs and custom checkboxes, custom widgets (dropdowns, accordions, toggles, hamburger menus — keyboard operable? aria-expanded?), and persistent landmarks (header/footer/nav tab order).

Watch for: :focus used instead of :focus-visible (rings on mouse click); outline: none with no visible alternative; non-interactive elements with onClick but no role, tabIndex, or keyboard handler.

Fix: replace :focus selectors with :focus-visible unless there's a documented reason (rare — e.g. a text input that should always show its ring). Make custom widgets keyboard-operable.

1.4 Skip link (WCAG 2.4.1)

Check: exists; is the first focusable element; target <main> has tabIndex={-1} so focus actually moves; hidden with transform (not display: none — removes it from tab order); revealed on :focus-visible (not :focus — shows on mouse click).

Fix — if missing:

<a href="#main-content" className="skip-to-content">Skip to main content</a>
<main id="main-content" tabIndex={-1}>...</main>

Hidden by default via transform: translateY(-200%), revealed on :focus-visible, styled through design tokens, high z-index.

1.5 Semantic HTML

Check:

  • Exactly one <main> per page (SPAs commonly nest multiples)
  • One <h1>, no skipped heading levels
  • Landmarks (<header>, <nav>, <main>, <footer>, <aside>) instead of <div> + role
  • Footer/sidebar section titles are headings, not <p>/<span>
  • No double-announcing: alt="" on decorative images whose accessible name comes from a sibling
  • <html lang="..."> set

Fix: collapse nested <main>s (keep one, demote others to <div>); promote section titles to headings with font-family: inherit; margin-top: 0; to preserve rendering; fix heading gaps; set decorative alt=""; add lang.

1.6 ARIA

Check & fix:

  • Icon-only buttons (hamburger, theme toggle, close, search) → aria-label
  • Disclosure triggers (menus, accordions, collapsibles) → aria-expanded (with JS toggle if needed)
  • Form errors → aria-invalid + aria-describedby linking to the message
  • Decorative SVGs/emojis next to text → aria-hidden="true"
  • Remove redundant ARIA (<button role="button">, <nav role="navigation">)

1.7 SPA route-change focus (if applicable)

Check: after client-side navigation, does focus reset so the next Tab starts from the top? Does scroll reset?

Fix: in the route-change/scroll-restoration hook, scroll to top and blur document.activeElement (when it's an HTMLElement other than body) on pathname change.

1.8 Overflow-hidden focus clipping

Check: parents with overflow: hidden (cards, pills, button groups) containing focusable children — the parent clips an outline that extends beyond its bounds.

Fix:

  • Pill / small element: negative offset so the ring draws inside — outline-offset: -2px
  • **Card /
阅读完整来源 ↗