Web Design Guidelines

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 (`, , , , , ) — not ` soup
• [ ] Heading hierarchy is sequential (h1 → h2 → h3) — no skipped levels
• [ ] One `` per page
• [ ] Skip link exists to bypass navigation (Skip to content)
• [ ] Landmark regions are labelled when duplicated (aria-label on multiple `` 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 ` 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 `` (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
Home

// ✅ Semantic HTML
Home
TitleContent

Form Accessibility

Email *

{error && {error}}

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AsyrafHussin
• Source: AsyrafHussin/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.