Audit accessibility

Audit 06 — Accessibility

Static Websites on cPanel

Accessibility is not a finishing touch and not optional. An inaccessible site excludes real people — users who navigate by keyboard, use screen readers, have low vision, or rely on assistive technology. Beyond inclusion, accessibility directly affects SEO, legal compliance, and overall code quality.

This audit reviews every layer of accessibility compliance without requiring external tools. All checks can be performed by reading the code directly.

---

Core Framework — WCAG 2.1 POUR Principles

Every accessibility requirement traces back to one of four principles:

• Perceivable — Information must be presentable in ways users can perceive. If it's only communicated through color, sound, or an image with no alternative — some users cannot access it.
• Operable — All functionality must be operable through multiple input methods. If something only works with a mouse, keyboard and switch device users are excluded.
• Understandable — Content and interface behavior must be understandable. Error messages that don't explain what went wrong, forms that fail silently, and inconsistent navigation all fail this principle.
• Robust — Content must be interpreted reliably by assistive technologies. Semantic HTML and correct ARIA usage make this possible.

---

Severity Levels

Level	Description	Action
Critical	Completely blocks access for a group of users	Fix before any other work
High	Significantly impairs access or WCAG AA failure	Fix before launch
Medium	Reduces usability for assistive technology users	Fix within current sprint
Low	Minor improvement opportunity	Fix when convenient

---

Section 1 — Perceivable

1.1 Images and Alt Text

Every image must communicate its purpose to users who cannot see it. The rule is not "add alt text to everything" — it is "add the RIGHT alt text based on the image's role."

Rules:

• Informative images — describe the content, not the appearance
• Decorative images — alt="" (empty, not missing)
• Functional images inside links or buttons — describe the action, not the image
• Complex images — provide detailed description in <figcaption> linked via aria-describedby
• Never use filename as alt text
• Never start alt text with "Image of" or "Photo of"

1.2 Color Contrast

Color contrast must meet WCAG AA minimums — the most commonly failed accessibility requirement.

Text Type	Minimum AA	Enhanced AAA
Normal text (< 18px regular, < 14px bold)	4.5:1	7:1
Large text (≥ 18px regular, ≥ 14px bold)	3:1	4.5:1
UI components and graphics	3:1	—

What to check — review every text color against its background in variables.css:

• Primary text on canvas background
• Secondary text on canvas background — most common failure point
• Muted/tertiary text on canvas background
• Text on accent/colored backgrounds (CTAs, badges, alerts)
• Placeholder text in inputs
• Disabled state text

Do not rely on color alone:

• Links must be distinguishable from surrounding text by more than color — use underline, weight, or icon
• Error states must not be communicated only through red — include an icon or text label
• Required form fields must not use only a colored asterisk — include text indication

  
  Please enter a valid email address

1.3 SVG Icons

Flag every SVG that carries meaning but has no aria-label and role="img". Flag every decorative SVG that lacks aria-hidden="true".

---

Section 2 — Operable

2.1 Keyboard Navigation

Every interaction available with a mouse must be available with a keyboard. Tab navigates forward, Shift+Tab backward, Enter activates links and buttons, Space activates buttons, Escape closes modals and dropdowns.

What to check:

Submit
Open


Submit

Flag every: <div> or <span> with onclick but no role="button" and tabindex="0", <a href="javascript:void(0)">, <a> wrapping <button>, custom components without keyboard handlers, visually interactive elements without focusability.

2.2 Focus Indicators

Every interactive element must have a visible focus indicator. Removing the default outline without an alternative is a critical failure.

/* ❌ Critical failure — removes focus visibility */
* { outline: none; }
button:focus { outline: none; }

/* ✅ :focus-visible — shows indicator for keyboard, not mouse */
:focus-visible {
  outline: 2px solid var(--border-focus);
  outline-offset: 2px;
  border-radius: var(--radius-sm);
}

2.3 Tab Order

Tab order must follow the visual reading flow — left to right, top to bottom.

What to check:

• No tabindex values greater than 0 — only tabindex="0" and tabindex="-1" should be used
• Visual layout matches DOM order — CSS Flexbox/Grid can reorder visually without changing DOM, tab order follows DOM

2.4 Skip Links

Skip links allow keyboard users to bypass repetitive navigation and jump to main content.

Skip to main content

...

...

.skip-link {
  position: absolute;
  top: -100%;
  left: var(--space-4);
  background-color: var(--bg-elevated);
  color: var(--text-primary);
  padding: var(--space-3) var(--space-6);
  border-radius: var(--radius-md);
  text-decoration: none;
  z-index: 9999;
  transition: top var(--transition-fast);
}

.skip-link:focus {
  top: var(--space-4);
}

Flag if: no skip link exists, skip link is not first focusable element, target does not exist, skip link never becomes visible on focus.

2.5 No Keyboard Traps

Users must always be able to navigate away from any component. The only acceptable trap is a modal while open — and Escape must close it.

Full modal focus management code example: see references/interactive-patterns.md

What to check:

• Custom dropdowns release focus on Escape
• Modals trap focus correctly — cycling within while open
• Modals release focus and return it to trigger element on close

2.6 Reduced Motion

When prefers-reduced-motion is active, animations must be disabled or significantly reduced.

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

Flag if: no prefers-reduced-motion query exists, animations lack the override, scroll behavior not disabled under reduced motion.

---

Section 3 — Understandable

3.1 Language Declaration

The system uses Retrieval Augmented Generation technology.

3.2 Semantic HTML Structure

  
    
      Home
      Solutions
    
  



  Page title
  
    Features
  



  ...

Heading hierarchy — non-negotiable rules:

• One and only one <h1> per page
• Never skip heading levels — <h1> → <h2> → <h3>, never <h1> → <h3>
• Headings describe content — not used for visual sizing
• Every major section must have a heading

3.3 Form Accessibility

Full name




  Email address
  *
  (required)




Email address

Please enter a valid email address

3.4 Error Identification

What to check:

• Error messages specific — not just "Error"
• Errors associated with inputs via aria-describedby
• Errors use role="alert" for automatic announcement
• Errors communicated through text, not only color
• Focus moves to first invalid field on submit

Full error handling and form validation code examples: see references/interactive-patterns.md

---

Section 4 — Robust

4.1 ARIA Usage

The first rule of ARIA: if a native HTML element can do it, use the native element.

Submit
...





Submit



  ...

Common ARIA patterns:

Home


Menu
...





Sending...

4.2 Dynamic Content Announcements

When content updates dynamically, assistive technologies must be notified.

// ✅ Clear aria-live region before updating
function announceToScreenReader(message, urgency = 'polite') {
  const announcer = document.getElementById(`${urgency}-announcer`);
  announcer.textContent = '';
  requestAnimationFrame(() => {
    announcer.textContent = message;
  });
}

Flag if: dynamic content appended without aria-live region, form results not announced, loading states change without AT notification.

4.3 Valid HTML

Assistive technologies parse HTML directly. Invalid HTML produces unpredictable screen reader behavior.

What to check:

• No duplicate id attributes on any page
• No invalid nesting — <a> not wrapping <button>, <li> only inside <ul>/<ol>
• Required attributes present — <img> needs alt, <input> needs type
• <!DOCTYPE html> on every page

4.4 Interactive Component States

Every interactive element needs all states defined — visually and for assistive technology.

.btn { }               /* Default */
.btn:hover { }         /* Hover */
.btn:focus-visible { } /* Focus */
.btn:active { }        /* Active */
.btn:disabled,
.btn[disabled] {       /* Disabled */
  opacity: 0.4;
  cursor: not-allowed;
  pointer-events: none;
}

---

Section 5 — Screen Reader Utilities

/* Must exist in base.css */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

Flag if .sr-only is not defined. Flag every place where screen-reader-only context is needed but the class is absent.

---

Audit Output Format

Accessibility Audit — [Project Name] Date: [Date] Standard: WCAG 2.1 Level AA Summary

Critical issues: X High priority: X Medium priority: X Low priority: X WCAG principle most affected: [Perceivable / Operable / Understandable / Robust] Overall compliance: [Compliant / Partially compliant / Non-compliant]

Critical Issues [Issue title]

WCAG Principle: [Perceivable / Operable / Understandable / Robust] WCAG Criterion: [e.g., 1.1.1 Non-text Content] File: [filename and line] Issue: [What is wrong and who it affects] Fix: [Specific correction with code example]

High Priority [Same format] Medium Priority [Same format] Low Priority [Same format] Recommended Fix Order

[First because it affects the most users...] [Then...] [Finally...]

Full quick-reference checklist: see references/checklist.md