refactors Journalist Interface for semantic HTML5/ARIA markup

[cfm]

Status

• Accessibility changes approved by @SaptakS
• Ready for final maintainer's review
  • See "Checklist" section for pre-merge steps

Description of Changes

Closes #5987 by:

1. refactoring all securedrop/journalist_templates/*.html for semantic markup;
2. adding ARIA annotations where HTML5 semantics are insufficient; and
3. fixing SASS/CSS in light of (1)–(2), especially to move decorative images out of the DOM and accessibility trees.

Testing

Click through the Journalist Interface and inspect in terms of:

1. Markup, by inspecting and validating HTML. This need not take place in Tor Browser; I used the Web Developer extension in Chrome.
2. Accessibility in assistive tech, by listening to the interface as announced from Tor Browser by a screen-reader. It should sound and "feel" conspicuously more fluent. (I also audited pages in WebAIM's Wave Evaluation Tool and Deque's axe DevTools, but these will yield mixed results until the conclusion of this accessibility push.)
3. Visual appearance, by comparing the interface against https://demo-journalist.securedrop.org. Changes are intended to be "pixel-perfect" except where there were preexisting idiosyncrasies that more-semantic markup tended to make naturally more consistent (or where noted in individual commits). Of course, suggestions for fine-tuning are welcome!

Steps (2)–(3) should be performed in Tor Browser at both "standard" and "safest" security levels.

Finally:

4. Click through the Source Interface and compare against https://demo-source.securedrop.org for any regressions introduced by shared Sass.

Deployment

No special considerations.

Checklist

After approval and before merge

1. Reformat securedrop/journalist_templates/*.html
2. Update as many translations as possible per Review and prioritize 2019 accessibility report findings #5972 (comment); test in Weblate sandbox → see refactors Journalist Interface for semantic HTML5/ARIA markup #6165 (comment)
3. Approver will squash-merge (especially fix-ups) to one commit per pass

If you made changes to the server application code:

• Linting (make lint) and tests (make test) pass in the development container

[cfm]

@SaptakS, while this pull request is officially still a draft, I wanted to request your accessibility review of the markup refactoring I've proposed here. Per discussion with the SecureDrop team, once I've revised this draft based on your feedback, I'll make the CSS changes necessary for pixel-perfect consistency with develop, for final review by @zenmonkeykstop.

Note that one test (functional/test_submit_and_retrieve_message.py::TestSubmitAndRetrieveMessage::test_submit_and_retrieve_happy_path) is still flaking. Once I've come up with a fix, I'll append that commit to this branch to avoid disrupting your review, Saptak, and then squash it in prior to merge.

[cfm]

Confirmed that functional/test_submit_and_retrieve_message.py::TestSubmitAndRetrieveMessage::test_submit_and_retrieve_happy_path is indeed a flake, with local passes reproduced at last in CI as of https://app.circleci.com/pipelines/github/freedomofpress/securedrop/3208/workflows/70299cd8-95de-48df-b79b-c7a4cf6bb764.

[cfm]

The flake, most demonstrably seen in https://app.circleci.com/pipelines/github/freedomofpress/securedrop/3208/workflows/dd8b4348-b646-4cbb-8ac1-af76e1173290/jobs/58091/tests#failed-test-0, looks like:

self = <tests.functional.test_submit_and_retrieve_message.TestSubmitAndRetrieveMessage object at 0x7ff49d42ebb0>

    def test_submit_and_retrieve_happy_path(self):
        self._source_visits_source_homepage()
        self._source_chooses_to_submit_documents()
        self._source_continues_to_submit_page()
        self._source_submits_a_message()
        self._source_logs_out()
        self.switch_to_firefox_driver()
        self._journalist_logs_in()
        self._journalist_checks_messages()
>       self._journalist_downloads_message()

/home/circleci/project/securedrop/tests/functional/test_submit_and_retrieve_message.py:20: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
/home/circleci/project/securedrop/tests/functional/journalist_navigation_steps.py:798: in _journalist_downloads_message
    self._journalist_selects_the_first_source()
/home/circleci/project/securedrop/tests/functional/journalist_navigation_steps.py:790: in _journalist_selects_the_first_source
    self.driver.find_element_by_css_selector("#un-starred-source-link-1").click()
[...]
E       selenium.common.exceptions.ElementNotInteractableException: Message: Element <a id="un-starred-source-link-1" class="code-name unread" href="/col/E7DV7R4U3FALMXE3N2THUA7DQQUPAUUKFOENZPO7FGEGRELBC3XQM22KMMR53TOJFAN3XILJ6FQTZGRDG6DDNRXXF66JXBXAYMJXABA="> could not be scrolled into view

/opt/venvs/securedrop-app-code/lib/python3.8/site-packages/selenium/webdriver/remote/errorhandler.py:242: ElementNotInteractableException

This behavior is not reproducible in manual testing (in Chrome, Firefox, or Tor Browser) and in 2054603 persists even if JournalistNavigationStepsMixin._journalist_selects_the_first_source() uses FunctionalTest.safe_click_by_id() (as it probably should). I've tinkered quite a bit with the test logic, to no avail, and will now poke at the markup to see if I can understand what Selenium is complaining about. Per eb9f35d, it doesn't appear to be the new overlaid dialog elements.

[SaptakS]

This looks awesome! Left few comments that I think should be addressed. Some of the comments are applicable in multiple places and templates (e.g., missing id attribute and aria-label on buttons comments ). The comments are related to only HTML semantics, since I think the styling is still under progress and there are some "Fix me" sections.

[SaptakS]

I don't see the need for an aria-label here, since the inner html already contains the time element with the same text content.

[cfm]

I agree in theory! In practice, at least my screen-reader (VoiceOver on macOS) reads the datetime attribute instead of the inner HTML, unless overridden with this aria-label.

[cfm]

Thanks, @SaptakS! I've been able to resolve all but one of your suggestions right away. I appreciate your careful eye on these changes! On now to CSS polishing.

[cfm]

This pull request's substantive changes are complete with the conclusion of CSS polishing in 07f9b57. Remaining work per #5987:

1. get tests passing;
2. do another round of functional and visual testing (Tor Browser) and validation;
3. reformat *.html à la 8f2b503.

[codecov-commenter]

Codecov Report

Merging #6165 (262ce5a) into develop (f768a1a) will decrease coverage by 0.00%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##           develop    #6165      +/-   ##
===========================================
- Coverage    85.13%   85.12%   -0.01%     
===========================================
  Files           59       59              
  Lines         4090     4088       -2     
  Branches       487      487              
===========================================
- Hits          3482     3480       -2     
  Misses         491      491              
  Partials       117      117              

Impacted Files	Coverage Δ
securedrop/journalist_app/forms.py	96.22% <100.00%> (ø)
securedrop/journalist_app/main.py	86.00% <0.00%> (-0.14%)	⬇️
securedrop/journalist_app/api.py	94.13% <0.00%> (-0.03%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f768a1a...262ce5a. Read the comment docs.

[cfm]

Thanks, @legoktm! I've rebased out the WIP commit message and a few fixups. With that, this is ready for @zenmonkeykstop's final review and merge.

[zenmonkeykstop]

Thanks all, taking a final spin through now.

[zenmonkeykstop]

Took a quick spin through validation and screen-reader steps again, no worries on that score.
Source Interface glitch is resolved, looks consistent overall.

LGTM - thanks @cfm for the work and @SaptakS and @LEGOTM for review!