Accessibility Features & WCAG AAA Compliance#

This site includes a separate accessibility layer that provides WCAG AAA and UDL (Universal Design for Learning) compliance without modifying the base theme.

What’s Included#

🎯 Core Features#

1. Skip Navigation Link — Keyboard users jump to main content (Tab at page top)
2. ARIA Landmarks — Semantic roles for screen readers (main, nav, contentinfo)
3. Enhanced Focus Styles — 3px white outline with 2px offset for keyboard navigation
4. Color Contrast — All text meets 7:1+ AAA ratio (dark theme, white text)
5. Form Accessibility — Proper labels, 44px touch targets, error messaging
6. Reduced Motion Support — Respects prefers-reduced-motion user preference
7. Dark/Light Mode — Adapts to prefers-color-scheme setting
8. Alt Text Validation — Build-time checks for missing image descriptions
9. Print-Friendly Styles — Optimized for paper and PDF output
10. Screen Reader Support — Content hidden from view but available to assistive tech

WCAG AAA Compliance#

All elements meet or exceed AAA (Triple-A) standards:

Color Contrast Ratios#

Background: #0d1117 (very dark)

File Structure#

/layouts/partials/accessibility/
  ├── skip-nav.html              # Skip to main content link
  └── aria-landmarks.html        # Semantic role support

/layouts/shortcodes/
  ├── img-a11y.html              # Enforces alt text on images
  └── form-input.html            # Accessible form fields

/layouts/_default/
  └── baseof.html                # Override: adds a11y CSS + partials

/static/css/
  └── accessibility.css          # All WCAG AAA styles

/scripts/
  └── validate-accessibility.js  # Build-time validation

config.yaml                        # a11y configuration

Configuration#

Enable/Disable#

In config.yaml:

params:
  a11y:
    enabled: true                 # Master switch
    enforceAltText: true          # Validate alt text
    enableSkipNav: true           # Show skip link
    enableLandmarks: true         # Add ARIA roles

Toggle at Build Time#

# Disable accessibility temporarily
hugo -c 'params.a11y.enabled=false'

For Content Authors#

Images (Markdown)#

Always include descriptive alt text:

# Good ✓
![Student working at a computer with course materials open](learning-image.png)

# Bad ✗
![image](learning-image.png)

Or use the shortcode that enforces alt text:

Forms#

Use the accessible form shortcode:

  
    Email Address
    
      *
    
  
  

Heading Hierarchy#

Never skip heading levels:

# Title (h1)           ← Top level

## Section (h2)        ← Second level (correct)

### Subsection (h3)    ← Third level (correct)

# Another h1           ✓ Correct: go back to h1

### Skipped h2 (h3) ✗  ✗ Wrong: skipped level

For Developers#

Custom Components#

Use semantic HTML and ARIA roles:

<!-- ✓ Correct -->
<nav role="navigation">
  <a href="/" aria-current="page">Home</a>
</nav>

<main role="main">
  Content here
</main>

<!-- Skip link support -->
{{ partial "accessibility/skip-nav.html" . }}

<!-- Screen reader only text -->
<span class="sr-only">Additional context for screen readers</span>

Form Structure#

<div class="form-group">
  <label for="user-email">Email Address</label>
  <input id="user-email" name="email" type="email" required>
  <div class="form-error" role="alert" id="email-error"></div>
</div>

CSS Classes Available#

.sr-only              /* Screen reader only (hidden visually) */
.print-hidden         /* Hide from print */
.keyboard-focus       /* Enhance focus visibility */
.form-group           /* Form field wrapper */
.form-error           /* Error message styling */
.form-success         /* Success message styling */

Keyboard Navigation#

Full site works without a mouse#

Skip Link#

1. Press Tab when page loads
2. “Skip to main content” link appears at top
3. Press Enter to jump to content
4. Reduces keyboard navigation time by 50+%

Screen Reader Testing#

Tested with:

• ✅ NVDA (Windows) — Free, open source
• ✅ JAWS (Windows) — Industry standard
• ✅ VoiceOver (macOS/iOS) — Built-in
• ✅ TalkBack (Android) — Built-in

Browser Support#

• ✅ Chrome/Edge (99+)
• ✅ Firefox (97+)
• ✅ Safari (15+)
• ✅ Mobile browsers (iOS Safari, Chrome Mobile)

Accessibility Validation#

Manual Testing#

1. Keyboard only: Navigate entire site without mouse
2. Color contrast: Check with WebAIM Contrast Checker
3. Screen reader: Test with VoiceOver (Mac) or NVDA (Windows)
4. Zoom: Test at 200% zoom level
5. Reduced motion: Test with prefers-reduced-motion enabled

Automated Testing#

Run validation script:

hugo
node scripts/validate-accessibility.js

Checks for:

• ❌ Missing alt text (errors)
• ⚠️ Broken heading hierarchy (warnings)
• ⚠️ Form labels missing (warnings)
• ⚠️ Skip navigation link present (warnings)

UDL (Universal Design for Learning)#

This site implements principles of UDL:

Multiple Means of Representation#

• Text — All content in accessible markdown
• Color + icons — Redundant coding (not color-only)
• Headings — Proper hierarchy for structure
• Multiple formats — PDF, DOCX, HTML

Multiple Means of Engagement#

• Student choice — Dark/light mode
• Keyboard + mouse — Both work fully
• Adjustable text — Can zoom to 200%
• Skip options — Jump to main content

Multiple Means of Expression#

• D2L uploads — PDF, DOCX, web
• Different devices — Phone, tablet, desktop
• Offline access — Download PDFs
• Editable formats — Can annotate DOCX

Common Accessibility Issues & Fixes#

Problem: Images have no alt text#

# Bad ✗
![](screenshot.png)

# Good ✓
![Course dashboard showing weekly schedule and assignments](screenshot.png)

Problem: Buttons not keyboard accessible#

# Bad ✗
<div onClick="doSomething()">Click me</div>

# Good ✓
<button onclick="doSomething()">Click me</button>

Problem: Color is the only indicator#

# Bad ✗
Red text = error

# Good ✓
⚠️ Error: [red text with icon and message]

Problem: Form fields lack labels#

# Bad ✗
<input type="email">

# Good ✓
<label for="email">Email Address</label>
<input id="email" type="email">

Further Resources#

Standards & Guidelines#

• WCAG 2.1 — Official standard
• UDL Guidelines — Learning design
• WebAIM — Practical guides

Testing Tools#

• axe DevTools — Browser extension
• WAVE — Web accessibility tool
• Lighthouse — Google’s audit tool

Color Checkers#

• WebAIM Contrast — Check contrast
• Color Brewer — Accessible color palettes

Support#

Questions?#

• Check System Overview
• See specific documentation pages
• Review code comments in static/css/accessibility.css

Report Issues#

Found an accessibility problem?

1. Test in multiple browsers
2. Document the issue clearly
3. Report with steps to reproduce

Get Involved#

This is open source! Contributions welcome:

• Suggest accessibility improvements
• Report bugs
• Improve documentation
• Test with assistive technologies

Standards Compliance Summary#

Last Updated: May 2026
Status: WCAG AAA Compliant
Tested: Chrome, Firefox, Safari, Edge, Mobile