accessible-web-dev

# University of Sheffield Web Accessibility Skill

Build web applications that meet WCAG 2.1 Level AA standards and University of Sheffield accessibility requirements.

## When to Use This Skill

Trigger this skill when working on:
- Building new web applications, sites, or digital platforms
- Creating forms, interactive components, or custom widgets
- Reviewing content for accessibility compliance
- Auditing existing websites for WCAG violations
- User mentions: accessibility, WCAG, screen reader, keyboard navigation, alt text, ARIA, captions, color contrast, inclusive design

## Core Requirements

**Compliance Standard:** WCAG 2.1 Level AA minimum across all University of Sheffield digital platforms

**Everyone's Responsibility:** Accessibility is not just for developers—product owners, designers, content creators, and communications specialists all play critical roles.

---

## Quick Start Workflow

### 1. Planning Phase
- Define accessibility requirements in acceptance criteria
- Identify content types (text, images, video, interactive elements)
- Establish responsibility matrix across team roles
- Budget for testing and remediation

### 2. Design Phase
- **Color Contrast:** 4.5:1 minimum for normal text, 3:1 for large text
- **Focus Indicators:** Clear, visible focus states for all interactive elements
- **Touch Targets:** Minimum 44×44 CSS pixels
- **Color Alone:** Never use color as sole indicator (add patterns, labels, icons)
- Test designs with contrast checker: `python scripts/contrast_checker.py "#foreground" "#background"`

### 3. Development Phase

**Semantic HTML First:**
```html
<!-- Good: Native HTML -->
<button type="button">Click me</button>
<nav aria-label="Main navigation">
  <ul><li><a href="/research">Research</a></li></ul>
</nav>

<!-- Bad: Div soup -->
<div onclick="...">Click me</div>
<div class="nav">...</div>
```

**Heading Hierarchy:**
- One `<h1>` per page
- Never skip levels (h1 → h2 → h3, not h1 → h3)
- Headings describe content structure, not styling

**Form Accessibility:**
- Associate labels with inputs using `for`/`id`
- Mark required fields with `required` and `aria-required="true"`
- Provide error messages via `aria-describedby` and `role="alert"`
- Use `autocomplete` attributes for common fields
- See: `assets/templates/form-template.html`

**Keyboard Navigation:**
- All functionality available via keyboard (Tab, Enter, Space, Arrows)
- Logical focus order
- No keyboard traps
- Visible focus indicators
- Skip links for main content

**ARIA Usage:**
- **Rule 1:** Use native HTML when possible (don't use `<div role="button">`, use `<button>`)
- **Rule 2:** Only add ARIA when native HTML insufficient
- For complex widgets (tabs, modals, accordions), see: `references/aria_patterns.md`

### 4. Content Phase

**Alternative Text Decision Tree:**
```
Is image meaningful?
├─ YES: Conveys information? → Write descriptive alt text
│   └─ Redundant with surrounding text? → alt=""
└─ NO: Purely decorative? → alt=""

Functional images (buttons, links): Describe function, not appearance
Complex images (charts): Brief alt + detailed description
```

**Examples:**
```html
<!-- Decorative -->
<img src="border.png" alt="">

<!-- Informative -->
<img src="campus.jpg" alt="Students working in Diamond building collaborative space">

<!-- Functional -->
<a href="/search"><img src="search.svg" alt="Search"></a>

<!-- Complex -->
<img src="chart.png"
     alt="Enrollment trends 2020-2024"
     aria-describedby="chart-details">
<div id="chart-details">
  Enrollment increased from 28,000 to 32,000,
  with largest growth in Engineering (15%)...
</div>
```

**Video/Audio Requirements:**
- **Captions:** All video content (prerecorded and live)
- **Transcripts:** All audio/video content
- **Audio Description:** Instructional and informational videos
- Upload captions as SRT files (Kaltura for UoS content)

### 5. Testing Phase

**Automated Testing:**
```bash
# HTML audit
python scripts/accessibility_audit.py path/to/file.html

# Color contrast check
python scripts/contrast_checker.py "#ffffff" "#000000"
```

**Manual Testing:**
- Keyboard-only navigation (disconnect mouse)
- Screen reader testing (NVDA on Windows, VoiceOver on Mac)
- Zoom to 200% (content must remain functional)
- Mobile screen reader (TalkBack/VoiceOver)

**Testing Checklist:**
- [ ] All images have alt text or alt=""
- [ ] All form inputs have associated labels
- [ ] Headings follow logical hierarchy
- [ ] All functionality keyboard accessible
- [ ] Focus indicators visible
- [ ] Color contrast meets 4.5:1 (normal text)
- [ ] No keyboard traps
- [ ] Dynamic updates announced by screen readers
- [ ] Link text descriptive out of context

---

## Common Patterns & Templates

### Accessible Modal Dialog
See: `assets/templates/modal-template.html`

**Key Requirements:**
- `role="dialog"` and `aria-modal="true"`
- Focus trap within modal
- Escape key closes modal
- Focus returns to trigger element on close
- Prevent background scroll when open

**React Example:** `assets/examples/AccessibleTabs.jsx`

### Accessible Forms
See: `assets/templates/form-template.html`

**Key Requirements:**
- Label/input associations
- Error messaging with `role="alert"`
- Required field indicators
- Validation feedback
- Autocomplete attributes

**React Components:** `assets/examples/AccessibleForm.jsx`

### Accessible Tabs
**Keyboard Navigation:**
- Arrow Left/Right: Navigate tabs
- Home/End: First/last tab
- Tab: Exit tab list

**Implementation:** See `assets/examples/AccessibleTabs.jsx`

---

## Quick Reference

### WCAG 2.1 AA Priority Checks

**Level A (Critical):**
- 1.1.1: Alt text for images
- 2.1.1: Keyboard accessible
- 2.1.2: No keyboard traps
- 2.4.1: Skip links
- 2.4.2: Page titles
- 3.1.1: Page language (lang attribute)
- 4.1.2: Name, role, value for components

**Level AA (UoS Requirement):**
- 1.2.4: Live captions
- 1.2.5: Audio descriptions
- 1.4.3: Color contrast 4.5:1
- 1.4.5: Avoid images of text
- 2.4.7: Visible focus
- 3.3.3: Error suggestions
- 4.1.3: Status messages

**Full details:** See `references/wcag_detailed.md`

### ARIA Patterns Reference

For implementing complex widgets:
- Accordion, Alert Dialog, Breadcrumb
- Button (Toggle), Combobox, Dialog (Modal)
- Disclosure, Menu, Tabs, Tooltip
- Tree View, Live Regions

**Full patterns with code:** See `references/aria_patterns.md`

### Color Contrast Quick Check

**Minimum Ratios:**
- Normal text: 4.5:1
- Large text (18pt+ or 14pt+ bold): 3:1
- UI components/graphics: 3:1

**Common UoS Colors:**
- White on UoS blue (#009ADE): 3.2:1 ✗ Fails for normal text
- Black on UoS yellow (#FECB00): 10:1 ✓ Passes

**Tool:** `python scripts/contrast_checker.py "#color1" "#color2" --level AA`

---

## Common Pitfalls & Solutions

### Pitfall 1: Generic Link Text
❌ **Bad:** "Click here" or "Read more"
✅ **Good:** "Annual Research Report 2024 (PDF, 2.3MB)"

### Pitfall 2: Missing Form Labels
❌ **Bad:** `<input type="text" placeholder="Email">`
✅ **Good:** `<label for="email">Email</label><input id="email" type="email">`

### Pitfall 3: Div/Span Buttons
❌ **Bad:** `<div onclick="submit()">Submit</div>`
✅ **Good:** `<button type="button" onclick="submit()">Submit</button>`

### Pitfall 4: Low Color Contrast
❌ **Bad:** Light gray (#CCC) on white (1.7:1)
✅ **Good:** Dark gray (#767676) on white (4.5:1)

### Pitfall 5: Auto-Playing Media
❌ **Bad:** `<video autoplay>`
✅ **Good:** `<video controls><track kind="captions" src="captions.vtt"></video>`

### Pitfall 6: Missing Page Titles
❌ **Bad:** `<title>University of Sheffield</title>` (on every page)
✅ **Good:** `<title>Computer Science MSc - Courses - University of Sheffield</title>`

---

## Tools & Scripts

### Included Scripts

**Accessibility Auditor:**
```bash
# Audit single file
python scripts/accessibility_audit.py file.html

# Audit directory
python scripts/accessibility_audit.py src/

# JSON output
python scripts/accessibility_audit.py file.html --format json
```

Checks: Images, headings, links, forms, page structure, semantic HTML, tables, buttons, ARIA usage

**Contrast Checker:**
```bash
# Basic check
python scripts/contrast_checker.py "#ffffff" "#000000"

# Check for AAA
python scripts/contrast_checker.py "#ffffff" "#000000" --level AAA

# Large text
python scripts/contrast_checker.py "#999999" "#ffffff" --large-text

# Show suggestions
python scripts/contrast_checker.py "#cccccc" "#ffffff" --suggest
```

### External Tools

**Browser Extensions:**
- WAVE (WebAIM): Visual accessibility feedback
- axe DevTools: Comprehensive automated testing
- Lighthouse: Built into Chrome DevTools

**Screen Readers:**
- NVDA (Windows): Free, nvaccess.org
- JAWS (Windows): Commercial, enterprise standard
- VoiceOver (Mac/iOS): Built-in (Cmd+F5)
- TalkBack (Android): Built-in

**Online Tools:**
- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
- WAVE Web Accessibility Evaluation: https://wave.webaim.org/

---

## University of Sheffield Specific

**Content Tone:**
- Active voice over passive
- Plain English (avoid jargon)
- Short paragraphs for scannability
- Sentence case (not title case/capitals)

**Platform Requirements:**
- Kaltura for video hosting and captioning
- Standard SRT format for captions
- Accessibility statement required on all sites
- Diverse representation in all visual content

**Documentation:**
- Must document any exceptions with justification
- Standards apply unless clear reason why not possible
- Regular audits required

---

## Implementation Example

**Scenario: Building a student portal**

```javascript
// 1. Use this skill to generate accessible component
"I need to build a course enrollment form for University of Sheffield
student portal. Include name, email, course selection dropdown, and
accessibility preferences checkboxes."

// 2. Skill will:
// - Use semantic HTML form structure
// - Add proper label associations
// - Include error handling with aria-live
// - Implement keyboard navigation
// - Ensure color contrast compliance
// - Add autocomplete attributes
// - Reference form template from assets/

// 3. Test with provided tools
python scripts/accessibility_audit.py enrollment-form.html
python scripts/contrast_checker.py "#005eb8" "#ffffff"

// 4. Manual verification
// - Tab through form with keyboard only
// - Test with NVDA screen reader
// - Verify error messages announced
// - Check focus indicators visible
```

---

## Resources

**Detailed References:**
- Full WCAG 2.1 criteria: `references/wcag_detailed.md`
- Complete ARIA patterns: `references/aria_patterns.md`

**Templates & Examples:**
- HTML form template: `assets/templates/form-template.html`
- HTML modal template: `assets/templates/modal-template.html`
- React tabs component: `assets/examples/AccessibleTabs.jsx`
- React form components: `assets/examples/AccessibleForm.jsx`

**Official Guidelines:**
- WCAG 2.1: https://www.w3.org/TR/WCAG21/
- WAI-ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
- UK Public Sector Requirements: https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps

**Learning Resources:**
- WebAIM: https://webaim.org/
- A11y Project: https://www.a11yproject.com/
- Inclusive Components: https://inclusive-components.design/

---

## Success Criteria

**Technical:**
- 100% WCAG 2.1 AA compliance
- Zero critical errors in automated testing
- All pages pass keyboard-only navigation
- All content announced correctly by screen readers

**User Experience:**
- Users with disabilities can complete all tasks
- Equivalent experience regardless of ability
- Positive feedback from assistive technology users
- No accessibility-related support issues

**Process:**
- Accessibility in all acceptance criteria
- Testing integrated into CI/CD pipeline
- Team trained on accessibility standards
- Regular audits completed and documented