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
- Input type: directory → scan components, layouts, global CSS. URL → fetch HTML and flag that source fixes need the actual codebase.
- Framework: determines where layouts, head tags, and route changes live.
- 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-visiblerule applying the ring - Components aliasing the token rather than hardcoding hex values
Fix — if missing, build it:
- 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.
- Add component-level tokens aliasing it:
--focus-ring-color,--focus-ring-width: 2px,--focus-ring-offset: 2px. - Add the global rule:
Do NOT set:focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring-color); outline-offset: var(--focus-ring-offset); }border-radiushere —outlinefollows the element's existing radius automatically; setting it changes the element's shape on focus. - 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-describedbylinking 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 /