semantic (HTML5/ARIA) page structure in Source Interface

[cfm]

Description

Accessibility Lab recommendations include:

• h1...hn hierarchy
• HTML5 section elements
• ARIA roles ("landmarks"), labels, and descriptions

Our findings include:

• moving decorative img elements to CSS styles on semantic elements

User Research Evidence

WCAG 1.3.1 per #5972.

Progress

To invert the way things are usually done :-):

1. First pass: Refactor for semantic markup (test in developer tools and screen-readers)
   • decorative img/hr/etc. elements: mark as FIXMEs to move to CSS styles on semantic elements
   • linters pass
   • tests pass
2. Second pass: Audit in validators and accessibility tools (axe, WAVE), e.g.:
   • h1...hn hierarchy
   • HTML5 section elements
   • ARIA roles ("landmarks"), labels, and descriptions
3. Third pass: CSS and images broken in first pass (test visually in browser)
   • FIXMEs
   • visual review

Path	First Pass	Second Pass	Third Pass
securedrop/source_templates	✓	✓	✓
├── banner_warning_flashed.html	✓	✓	✓
├── base.html	✓	✓	✓
├── error.html	✓	✓	✓
├── first_submission_flashed_message.html	✓	✓	✓
├── flashed.html	✓	✓	✓
├── footer.html	✓	✓	✓
├── generate.html	✓	✓	✓
├── index.html	✓	✓	✓
├── locales.html	✓	✓	✓
├── login.html	✓	✓	✓
├── logout.html	✓	✓	✓
├── lookup.html	✓	✓	✓
├── next_submission_flashed_message.html	✓	✓	✓
├── notfound.html	✓	✓	✓
├── session_timeout.html	✓	✓	✓
├── tor2web-warning.html	✓	✓	✓
├── use-tor-browser.html	✓	✓	✓
└── why-public-key.html	✓	✓	✓

Specific cases (could be filed as separate issues)

• securedrop/source_templates/generate.html: p.explanation should be associated with p#codename

[cfm]

@zenmonkeykstop, I'm starting work on this with the assumption that this and #5987 will each take the form of an omnibus PR consisting of:

1. refactored templates; and
2. stylesheets updated accordingly, with the goal of making it as close as possible to a pixel-perfect markup-only refactoring, with no (visually apparent) UI/UX consequences.

Given this scope, is there a particular sequence or structure you'd like to see the PR follow for ease of review?

[zenmonkeykstop]

A single big PR is fine for this IMO, the scope isn't that massive and there isn't an obvious clean way to separate it given styles being used across multiple templates. If you are still thinking of a 3-phase approach, rebasing each phase's commits into one would be helpful but is not required.

Note that you may (will) encounter SASS modules shared between the SI and JI. If you do want separate PRs for both then you may need to either duplicate some modules or deal with breakage in the JI while you're working in the SI. If it's particularly egregious having dedicated SI or JI SASS is preferable IMO.

Also note there will probably be an impact on functional tests. You might need to clean those up as well after you're done with UI changes, especially if id/class names get changed as part of the process.

Otherwise, plan looks solid, have at it!