| name | wcag-validator |
| description | Automatically validate Moodle templates, JavaScript, and CSS for WCAG 2.1 Level AA accessibility compliance. Checks semantic HTML, ARIA patterns, keyboard navigation, color contrast, and screen reader compatibility. Activates when working with Mustache templates, AMD modules, or discussing accessibility, a11y, WCAG, screen readers, or keyboard navigation. |
| allowed-tools | Read, Grep, Bash |
WCAG 2.1 AA Validator Skill
Automatic Activation
This skill activates when:
- Working with Mustache templates (*.mustache files)
- Editing AMD JavaScript modules (amd/src/*.js)
- Modifying CSS/SCSS files
- User mentions: "accessibility", "a11y", "WCAG", "screen reader", "keyboard", "contrast", "ARIA"
- Implementing forms, modals, dynamic content
- Creating interactive UI components
Validation Checklist
1. HTML Semantics & Structure
✓ Proper Document Structure
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Descriptive Page Title</title>
</head>
<body>
</body>
</html>
✓ Heading Hierarchy
- Single h1 per page
- No skipped levels (h2 → h4 ❌)
- Logical document outline
✓ Semantic Elements
<nav>, <main>, <aside>, <footer>, <article>, <section>- Not
<div> for everything
✓ Landmarks
<header role="banner">
<nav role="navigation" aria-label="Main">
<main role="main">
<aside role="complementary">
<footer role="contentinfo">
2. Images & Media
✓ Alt Text
<img src="chart.png" alt="Bar chart showing 60% increase in completion rates">
<img src="divider.png" alt="" role="presentation">
<a href="/course/view.php?id=1">
<img src="icon.png" alt="Go to Introduction to Programming course">
</a>
✓ Complex Images
<img src="diagram.png"
alt="Process flowchart"
aria-describedby="diagram-desc">
<div id="diagram-desc" class="sr-only">
Detailed description: The process starts with...
</div>
3. Forms & Inputs
✓ Label Association
<label for="username">Username</label>
<input type="text" id="username" name="username">
<label>
Email
<input type="email" name="email">
</label>
✓ Required Fields
<label for="folder">
Folder name
<span class="text-danger" aria-label="required">*</span>
</label>
<input type="text"
id="folder"
required
aria-required="true">
✓ Error Handling
<div class="form-group {{#error}}has-error{{/error}}">
<label for="email">Email</label>
<input type="email"
id="email"
aria-invalid="{{#error}}true{{/error}}"
aria-describedby="{{#error}}email-error{{/error}}">
{{#error}}
<div id="email-error" class="text-danger" role="alert">
{{error}}
</div>
{{/error}}
</div>
✓ Field Instructions
<label for="password">Password</label>
<input type="password"
id="password"
aria-describedby="password-requirements">
<small id="password-requirements">
Must be at least 8 characters with one number
</small>
4. Interactive Elements
✓ Buttons
<button type="button">Save Changes</button>
<button type="button" aria-label="Delete file">
<i class="fa fa-trash" aria-hidden="true"></i>
</button>
<button type="submit" aria-busy="true">
<span class="spinner" aria-hidden="true"></span>
Loading...
</button>
✓ Links
<a href="file.pdf">Download assignment guidelines (PDF, 2MB)</a>
<a href="/edit" aria-label="Edit folder settings">
<i class="fa fa-edit" aria-hidden="true"></i>
</a>
<a href="https://example.com"
target="_blank"
rel="noopener noreferrer">
External resource
<span class="sr-only">(opens in new window)</span>
</a>
✓ Skip Links
<a href="#main-content" class="sr-only sr-only-focusable">
Skip to main content
</a>
5. ARIA Patterns
✓ Live Regions
<div aria-live="polite" aria-atomic="true" class="sr-only"></div>
<div aria-live="assertive" aria-atomic="true" class="sr-only"></div>
<div role="status" aria-live="polite">
File uploaded successfully
</div>
<div role="alert">
Error: Connection failed
</div>
✓ Dialogs/Modals
<div role="dialog"
aria-labelledby="dialog-title"
aria-describedby="dialog-desc"
aria-modal="true">
<h2 id="dialog-title">Confirm Deletion</h2>
<p id="dialog-desc">Are you sure you want to delete this file?</p>
<button type="button" class="btn-danger">Delete</button>
<button type="button" class="btn-secondary">Cancel</button>
</div>
✓ Tabs
<div role="tablist" aria-label="Content views">
<button role="tab"
aria-selected="true"
aria-controls="tree-panel"
id="tree-tab">
Tree View
</button>
<button role="tab"
aria-selected="false"
aria-controls="table-panel"
id="table-tab"
tabindex="-1">
Table View
</button>
</div>
<div role="tabpanel"
id="tree-panel"
aria-labelledby="tree-tab">
</div>
<div role="tabpanel"
id="table-panel"
aria-labelledby="table-tab"
hidden>
</div>
6. Keyboard Navigation
✓ Focus Management
const trapFocus = (element) => {
const focusableElements = element.querySelectorAll(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
const firstElement = focusableElements[0];
const lastElement = focusableElements[focusableElements.length - 1];
element.addEventListener('keydown', (e) => {
if (e.key === 'Tab') {
if (e.shiftKey && document.activeElement === firstElement) {
e.preventDefault();
lastElement.focus();
} else if (!e.shiftKey && document.activeElement === lastElement) {
e.preventDefault();
firstElement.focus();
}
}
});
};
let previousFocus = null;
const openModal = (modal) => {
previousFocus = document.activeElement;
modal.showModal();
modal.querySelector('button').focus();
};
= () => {
modal.();
(previousFocus) {
previousFocus.();
}
};
✓ Keyboard Event Handlers
element.addEventListener('click', handleAction);
element.addEventListener('keydown', (e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
handleAction();
}
});
dialog.addEventListener('keydown', (e) => {
if (e.key === 'Escape') {
closeDialog();
}
});
7. Color & Contrast
✓ Contrast Ratios (WCAG AA)
- Normal text (< 18pt): 4.5:1 minimum
- Large text (≥ 18pt or 14pt bold): 3.0:1 minimum
- UI components & graphics: 3.0:1 minimum
.text {
color: #999;
background: #fff;
}
.text {
color: #666;
background: #fff;
}
.text {
color: #333;
background: #fff;
}
✓ Don't Rely on Color Alone
<span style="color: red;">Error</span>
<span class="text-danger">
<i class="fa fa-exclamation-circle" aria-hidden="true"></i>
Error: Invalid input
</span>
8. Dynamic Content
✓ Screen Reader Announcements
const announceLoading = () => {
const liveRegion = document.querySelector('[aria-live="polite"]');
liveRegion.textContent = 'Loading files...';
};
const announceComplete = (count) => {
const liveRegion = document.querySelector('[aria-live="polite"]');
liveRegion.textContent = `${count} files loaded successfully`;
setTimeout(() => {
liveRegion.textContent = '';
}, 1000);
};
const announceError = (message) => {
const liveRegion = document.querySelector('[aria-live="assertive"]');
liveRegion.textContent = `Error: ${message}`;
};
Validation Workflow
Step 1: Automated Scan
grep -r "onclick=" templates/
grep -r "<img" templates/ | grep -v "alt="
grep -r "<input" templates/ | grep -v "label"
Step 2: Template Analysis
For each .mustache file:
- Check heading hierarchy
- Verify form label associations
- Ensure buttons have accessible text
- Validate ARIA usage
- Check color contrast in CSS
Step 3: JavaScript Analysis
For each AMD module:
- Check keyboard event handlers
- Verify focus management
- Validate live region updates
- Check for focus traps
- Ensure escape key handling
Step 4: Generate Report
♿ Accessibility Validation Report
File: templates/folder_view.mustache
Status: ❌ FAILED (3 issues)
Issues:
❌ Line 45: Image missing alt attribute
<img src="{{icon}}">
Fix: <img src="{{icon}}" alt="{{iconDescription}}">
❌ Line 78: Button not keyboard accessible
<div onclick="deleteFile()">Delete</div>
Fix: <button type="button" onclick="deleteFile()">Delete</button>
❌ Line 102: Form input missing label
<input type="text" name="foldername">
Fix: <label for="folder-{{id}}">Folder name</label>
<input type="text" id="folder-{{id}}" name="foldername">
Recommendations:
- Add aria-live region for file loading status
- Implement keyboard navigation for file list
- Add skip link to file content
WCAG 2.1 AA Compliance: 68% → Target: 100%
Common Patterns
Accessible Card Component
<div class="card" role="region" aria-labelledby="card-title-{{id}}">
<div class="card-header">
<h3 id="card-title-{{id}}">{{title}}</h3>
</div>
<div class="card-body">
<p>{{description}}</p>
</div>
<div class="card-footer">
<a href="{{url}}"
class="btn btn-primary"
aria-label="View details for {{title}}">
View Details
</a>
</div>
</div>
Accessible Data Table
<table class="table">
<caption>List of course files</caption>
<thead>
<tr>
<th scope="col">Filename</th>
<th scope="col">Size</th>
<th scope="col">Modified</th>
<th scope="col">Actions</th>
</tr>
</thead>
<tbody>
{{#files}}
<tr>
<th scope="row">{{name}}</th>
<td>{{size}}</td>
<td>{{modified}}</td>
<td>
<button =
=
=>
Download
{{/files}}
Integration
- Auto-validates on template writes/edits
- Triggered by
/m:a11y command
- Pre-commit hook validation
- Part of CI/CD pipeline
References
- WCAG 2.1 Quick Reference
- ARIA Authoring Practices Guide
- Moodle Accessibility Guidelines
