web-design-guidelines

name	web-design-guidelines
description	UI/UX best practices and accessibility audit. Use when reviewing UI code, checking accessibility, running accessibility audits, auditing forms, or ensuring web interface best practices. Triggers on "audit accessibility", "check WCAG", "review UI", "check accessibility", "audit design", "review UX", or "check best practices".
license	MIT
metadata	{"author":"agent-skills","version":"2.1.0"}

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

• WCAG 2.2 Quick Reference
• WAI-ARIA Authoring Practices
• web.dev Accessibility
• MDN Accessibility
• The A11Y Project

Full Compiled Document

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