Web Design Guidelines

WCAG accessibility, semantic HTML, keyboard navigation, forms, and performance patterns for inclusive web interfaces. Contains 23 rules across 4 categories. Supports both coding reference and audit mode.

Metadata

Version: 2.1.0
Rule Count: 23 rules across 4 categories
License: MIT

How to Audit

When the user asks to "audit accessibility", "check WCAG compliance", or "review accessibility" — run the checklist below against their codebase.

Step 1: Determine Scope

If arguments provided ($ARGUMENTS): audit only those files or components
If no arguments: audit all UI components and pages in the codebase

Step 2: Detect Stack

Check the project for:

.tsx/.jsx files → React
.vue files → Vue
.blade.php files → Laravel Blade
.html files → Static HTML

Step 3: Run Accessibility Checklist

Work through every item below. For each, output:

PASS — brief confirmation of what was verified
FAIL — exact file:line, description of the issue, and fix recommendation
N/A — if the check does not apply to this project

Semantic HTML & Structure

Pages use semantic elements (<header>, <main>, <nav>, <footer>, <article>, <section>) — not <div> soup
Heading hierarchy is sequential (h1 → h2 → h3) — no skipped levels
One <h1> per page
Skip link exists to bypass navigation (<a href="#main-content">Skip to content</a>)
Landmark regions are labelled when duplicated (aria-label on multiple <nav> elements)

Keyboard Navigation

All interactive elements are reachable via Tab key
Focus order follows visual order (no positive tabindex values)
Focus indicator is visible on all focusable elements (not removed with outline: none without replacement)
Modal dialogs trap focus and return focus on close
Custom components (dropdowns, tabs, accordions) support expected keyboard patterns (Arrow keys, Escape, Enter)

Images & Media

All <img> elements have alt attributes — descriptive for content images, empty (alt="") for decorative
Complex images (charts, diagrams) have extended descriptions
Video content has captions or transcripts

Color & Contrast

Text meets WCAG AA contrast ratio (4.5:1 for normal text, 3:1 for large text)
Information is not conveyed by color alone (e.g., error states use icons + text, not just red)
UI components and focus indicators meet 3:1 contrast ratio against background

Forms

Every input has an associated <label> (not just placeholder text)
Required fields indicated with both visual cue and aria-required="true"
Error messages linked to inputs via aria-describedby
Error messages use role="alert" or aria-live="assertive" for screen reader announcement
Correct type attributes on inputs (email, tel, url, number)
autocomplete attributes present on common fields (name, email, address, credit card)

ARIA & Screen Readers

ARIA labels on icon-only buttons (aria-label="Close")
Dynamic content updates use aria-live regions
Loading states announced to screen readers (aria-busy="true", status messages)
Decorative elements hidden from screen readers (aria-hidden="true")

Motion & Animation

prefers-reduced-motion respected — animations disabled or reduced
No auto-playing video or audio without user control
No content that flashes more than 3 times per second

Step 4: Summary

End the audit with:

## Accessibility Audit Summary
- **PASS**: X checks
- **FAIL**: X checks
- **N/A**: X checks
- **WCAG Level**: AA / Partial AA / Below AA
- **Top Priority Fixes**: (list the 3 most impactful FAIL items)

When to Apply

Reference these guidelines when:

Running an accessibility audit on a codebase
Reviewing UI code for accessibility (WCAG compliance)
Implementing forms and interactions
Ensuring keyboard navigation works
Adding ARIA labels and live regions
Optimizing image loading and layout stability

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Accessibility	CRITICAL	`a11y-`
2	Forms	HIGH	`form-`
3	Animation & Motion	CRITICAL	`motion-`
4	Performance & UX	MEDIUM	`perf-`

Quick Reference

1. Accessibility (CRITICAL)

a11y-semantic-html - Use semantic HTML elements
a11y-heading-hierarchy - Maintain proper heading hierarchy
a11y-screen-reader - Optimize for screen reader compatibility
a11y-skip-links - Provide skip links for navigation
a11y-keyboard-nav - Ensure full keyboard navigation
a11y-focus-management - Manage keyboard focus properly
a11y-aria-labels - Add ARIA labels to interactive elements
a11y-color-contrast - Ensure sufficient color contrast (WCAG AA)
a11y-alt-text - Provide meaningful alt text for images
a11y-error-messages - Make error messages accessible
a11y-form-labels - Associate labels with form inputs
a11y-live-regions - Announce dynamic content to screen readers

2. Forms (HIGH)

form-autocomplete - Use autocomplete attributes
form-input-types - Use correct input types
form-error-display - Display form errors clearly
form-validation-ux - Design user-friendly validation
form-inline-validation - Implement smart inline validation
form-multi-step - Design effective multi-step forms
form-placeholder-usage - Use placeholders appropriately
form-submit-feedback - Provide clear submission feedback

3. Animation & Motion (CRITICAL)

motion-reduced - Respect prefers-reduced-motion (WCAG AAA)

4. Performance & UX (MEDIUM)

perf-image-loading - Optimize image loading for UX
perf-layout-stability - Prevent cumulative layout shift

Essential Guidelines

Semantic HTML

// ❌ Div soup
<div className="header"><div className="nav"><div onClick={handleClick}>Home</div></div></div>

// ✅ Semantic HTML
<header><nav aria-label="Main"><a href="/">Home</a></nav></header>
<main><article><h1>Title</h1><p>Content</p></article></main>

Form Accessibility

<label htmlFor="email">Email <span aria-hidden="true">*</span></label>
<input id="email" type="email" required aria-required="true" aria-describedby="email-error" autoComplete="email" />
{error && <p id="email-error" role="alert">{error}</p>}

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

How to Use

Read individual rule files for detailed explanations:

rules/a11y-semantic-html.md
rules/form-autocomplete.md
rules/motion-reduced.md
rules/perf-image-loading.md

References

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

web-design-guidelines