accessibility-auditor

Files (1)

• SKILL.md

SKILL.md (first lines)

# The Accessibility Auditor

## Overview

The Accessibility Auditor treats accessible HTML as a requirement, not a nice-to-have. It checks generated code against WCAG priorities — semantic structure, keyboard operability, contrast ratios, screen reader compatibility — and verifies with automated tools plus manual tests. A page that only works with a mouse is a page that does not work.

## When to Use

- Generating or reviewing HTML for accessibility compliance
- Auditing an interface against WCAG standards
- Designing forms, navigation, or dynamic content with accessibility in mind
- Verifying that a UI passes automated and manual accessibility checks

## Process

### 1. Semantic HTML First
- Use proper semantic elements: `<nav>`, `<main>`, `<section>`, `<article>`, `<header>`, `<footer>`
- Structure headings sequentially (h1 → h2 → h3, never skip levels)
- Use one `<h1>` per page with descriptive heading text

### 2. Apply Essential ARIA Requirements
- Add `alt` text to all images
- Label form inputs with `<label>` or `aria-label`
- Ensure interactive elements have accessible names
- Use `aria-expanded` for collapsible content
- Add `role`, `aria-labelledby`, and `aria-describedby` when semantic HTML is not sufficient

### 3. Verify Keyboard Navigation
- All interactive elements must be keyboard accessible
- Provide visible focus indicators (minimum 2px outline)
- Include skip links: `<a href="#main">Skip to main content</a>`
- Use logical tab order that matches visual layout

### 4. Check Color and Contrast
- 4.5:1 contrast ratio for normal text (under 18pt); 3:1 for large text (18pt+ or 14pt+ bold)
- 3:1 for UI components and graphics
- Never rely on color alone to convey information — use color + icon + text
- Add patterns or textures to distinguish chart elements; label graphs and data visualizations

### 5. Ensure Screen Reader Compatibility
- Describe non-text content by function, not appearance: `alt="Submit form"`, not `alt="Blue button"`
- Associate every input with a `<label>` element
- Use descriptive link text — "Download the accessibility report (PDF, 2MB)", never "Click here"
- Announce dynamic content updates: `aria-live="polite"` for status, `aria-live="assertive"` for urgent notifications

### 6. Apply Form Design Standards
- Place labels above or to the left of form fields
- Group related fields with `<fieldset>` and `<legend>`
- Display validation errors immediately after the field with `aria-describedby`
- Use `aria-required="true"` for required fields
- Provide clear instructions before users start filling out forms

### 7. Test, Automated Then Manual
**Automated:** run axe-core scanner in CI/CD, test with lighthouse accessibility audit, validate HTML markup for semantic correctness
**Manual:** navigate the entire interface using only Tab/Shift+Tab/arrow keys; test with a screen reader (NVDA on Windows, VoiceOver on Mac); verify 200% zoom does not break layout or hide content; check contrast with a tool like the WebAIM Color Contrast Checker

**Code Generation Rule:** include accessibility comments explaining ARIA attributes and semantic choices; test code with keyboard navigation before suggesting it is complete.

## Red Flags

- Semantic HTML replaced by a mountain of `div`s and `role` attributes
- Focus indicators removed "for aesthetics"
- Color as the only status signal
- Labels omitted, placeholder text used instead
- No keyboard test before calling a UI done
- Skip levels in heading structure

## Rationalizations

| What you think | What The Accessibility Auditor knows |
|----------------|---------------------------------------|
| "Screen readers are rare, it's fine" | Accessibility is not a niche. It is a legal, ethical, and quality requirement. |
| "aria-label on everything fixes it" | ARIA is a patch for semantic HTML, not a replacement for it. Structure first. |
| "The contrast looks fine to me" | "Looks fine" is not 4.5:1. Measure it. |
| "We'll add alt text later" | Later is never. Accessibility is a generation-time requirement. |

## Verification

The audit is complete when:

- [ ] Semantic elements and sequential heading structure are used
- [ ] Every image has functional alt text; every input has a label
- [ ] Full interface is operable by keyboard alone with visible focus
- [ ] Contrast ratios meet 4.5:1 (text) and 3:1 (large text/UI)
- [ ] Dynamic content is announced via aria-live
- [ ] Automated scans (axe/lighthouse) and manual tests (keyboard, screen reader, 200% zoom) pass

From fworks-tech/agenthood, MIT.

More from fworks-tech/agenthood