refactors Source Interface for semantic HTML5/ARIA markup #6041

cfm · 2021-07-13T18:46:15Z

Status

Ready for review

Depends for merge on refactors status-indicator imgs and related elements for ARIA labeling #6021

Stylistic changes suggested for rebasing after review and before merge:

"[Squash] each phase's commits into one"
Rebase from develop
Lint (beyond make lint) for indentation of HTML in all securedrop/source_templates/*.html

Description of Changes

Closes #5986 by:

refactoring all securedrop/source_templates/*.html for semantic markup;
adding ARIA annotations where HTML5 semantics are insufficient to make the Source Interface easily navigable by assistive tech, especially in the absence of JavaScript for changing state, polyfilling for undersupported HTML5 elements, etc.; and
fixing SASS/CSS in light of (1)–(2), especially to move decorative images out of the DOM and accessibility trees.

Known issues

For future work:

make BCP47/RFC5646 RequestLocaleInfo.language_tag property available in locale selectors #6056 (out of scope)
invalid datetime attributes #6057 (out of scope)
Some pages need h1s (address in re: WCAG 2.4.2)

Testing

Click through the Source Interface and inspect in terms of:

Markup, by inspecting and validating HTML. This need not take place in Tor Browser; I used the Web Developer extension in Chrome.
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.)
Visual appearance, by comparing the interface against develop. Changes are intended to be "pixel-perfect" except where there were preexisting idiosyncrasies that more-semantic markup tended to make naturally more consistent. Of course, suggestions for fine-tuning are welcome!

Deployment

No special considerations.

Checklist

If you made changes to the server application code:

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

If you made non-trivial code changes:

~~I have written a test plan and validated it for this PR~~

Let me know if this is necessary.

I have opened a PR in the docs repo for these changes, or will do so later
- suggest tools for auditing accessibility impact of HTML/SASS changes securedrop-docs#245

codecov-commenter · 2021-07-15T07:42:20Z

Codecov Report

Merging #6041 (80547cd) into develop (0589168) will not change coverage.
The diff coverage is 100.00%.

@@           Coverage Diff            @@
##           develop    #6041   +/-   ##
========================================
  Coverage    85.11%   85.11%           
========================================
  Files           55       55           
  Lines         3863     3863           
  Branches       479      479           
========================================
  Hits          3288     3288           
  Misses         463      463           
  Partials       112      112

Impacted Files	Coverage Δ
securedrop/source_app/forms.py	`94.73% <100.00%> (ø)`
securedrop/source_app/main.py	`92.26% <100.00%> (ø)`

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 0589168...80547cd. Read the comment docs.

SaptakS

This is amazing work @cfm !!! Love to see efforts towards making the HTML more semantic and accessible. I have left some small comments/questions that caught my eyes. Few are probably bigger changes which might need their own separate issues.

securedrop/source_templates/flashed.html

securedrop/source_templates/base.html

securedrop/journalist_templates/_source_row.html

securedrop/source_templates/index.html

securedrop/source_templates/locales.html

securedrop/source_templates/generate.html

securedrop/source_templates/lookup.html

securedrop/source_templates/locales.html

securedrop/source_templates/lookup.html

Corrects 876bfa2's removal of these decorative IMGs without replacing their semantic content. thread: #6041 (comment) squash/fixup: 876bfa2

Adds explicit ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment)

Adds explicit title-case ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment)

Refactors MAIN.index-row rather than wrapping the whole DIV.grid in MAIN. thread: #6041 (comment) squash/fixup: 80547cd

Adds explicit title-case ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment)

Refactors MAIN.index-row rather than wrapping the whole DIV.grid in MAIN. thread: #6041 (comment) squash/fixup: 80547cd

Adds explicit title-case ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment)

Refactors MAIN.index-row rather than wrapping the whole DIV.grid in MAIN. thread: #6041 (comment) squash/fixup: 80547cd

thread: #6041 (comment)

LABEL[for="codename"] was marked HIDDEN to prevent redundant narration in screen readers. Refactoring the LABEL to an H2 that ARIA-labels the containing section streamlines the narration and makes for a more-logical outline. thread: #6041 (comment) squash/fixup: ae56f49

::{before,after} pseudo-elements must be used to style the expand/collapse links ("Show"/"Hide", respectively) because under DIR="ltr" the ::marker pseudo-element will be displayed to the left of the SUMMARY. thread: #6041 (comment) squash/fixup: 1f69640

thread: #6041 (comment)

rmol · 2021-08-09T17:35:24Z

The changes of output to mark or p worked, as did the fix for the replies section. Once the merge conflicts are resolved and CI is passing, I think this is good to go. Nice work, @cfm.

reconciles JavaScript-free locale selector with ARIA best practices Accessible checkbox-based menus (e.g., hamburger menus[1]) tend to rely on JavaScript to update the menu's ARIA attributes in response to changes in state. Here we reconcile the script-free and accessibility requirements so that: 1. the current locale and "Choose locale" menu are announced logically; and 2. the menu itself is annotated to be announced by screen-reader and navigable by keyboard. As a bonus, each locale is now announced *in* that locale, via the A LANG and HREFLANG attributes. [1]: http://www.ashleysheridan.co.uk/blog/Making+an+Accessible+Hamburger+Menu first pass through "/generate" restore div#content and div#container first pass through "/lookup" pass 1.5 through /lookup with replies sets focus to #flashed when POST /submit redirects to /lookup As recommended by <https://webaim.org/techniques/formvalidation/#error>. first pass through "/logout" first pass through "/login" first pass through / first pass through ancillary templates

second pass through /: validate/audit second pass through /lookup: validate/audit second pass through /login: validate/audit second pass through ancillary templates: validate/audit

third pass through /: fix "footer.html" styling Introduces a change in vertical spacing which could be corrected. Journalist Interface breakage: Adds a gratuitous BORDER-TOP to the FOOTER. third pass through /: fix H1 logo styling I've been persuaded[1] that: 1. the logo image is content, rather than decoration, after all, and so can remain an explicit IMG, with an ALT attribute that describes the image rather than offers a tooltip-style TITLE; and 2. on the home page the logo *is* the top-level heading, reflected in both the H1 and the page TITLE. [1]: https://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/ third pass through /: fix #js-warning styling third pass through /: fix "locales.html" styling third pass through /generate: "{base,generate}.html" styling third pass through /generate: "Refresh Codename" button styling third pass through /lookup: fix "lookup.html" styling third pass through /lookup: fix "flashed.html" styling third pass through /: fix "{first,next}_submission_flashed_message.html" styling third pass through /logout third pass through /login: fix "login.html" styling third pass: fix "banner_warning_flashed.html" styling third pass through /why-public-key: fix "why-public-key.html" styling

Replaces STRONG elements with B, according to the latter's new HTML5 semantics[1]. Removes STRONG elements in headings, where they are superfluous both semantically and visually. [1]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-b-element

addresses review feedback Corrects 876bfa2's removal of these decorative IMGs without replacing their semantic content. thread: #6041 (comment) squash/fixup: 876bfa2 addresses review feedback Adds explicit title-case ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment) addresses review feedback Refactors MAIN.index-row rather than wrapping the whole DIV.grid in MAIN. thread: #6041 (comment) squash/fixup: 80547cd removes stray ARIA-LABELS (per review feedback) thread: #6041 (comment) addresses review feedback LABEL[for="codename"] was marked HIDDEN to prevent redundant narration in screen readers. Refactoring the LABEL to an H2 that ARIA-labels the containing section streamlines the narration and makes for a more-logical outline. thread: #6041 (comment) squash/fixup: ae56f49 refactors SECTION#codename-hint as DETAILS (per review feedback) ::{before,after} pseudo-elements must be used to style the expand/collapse links ("Show"/"Hide", respectively) because under DIR="ltr" the ::marker pseudo-element will be displayed to the left of the SUMMARY. thread: #6041 (comment) squash/fixup: 1f69640 adds "button" role to non-navigating links (per review feedback) thread: #6041 (comment) undoes autoformatting squash/fixup: 1f69640 fixes tests for refactored DETAILS#codename-hint squash/fixup: c8baf3d fixes unclosed ARIA-LABEL attribute (per review feedback) thread: #6041 (comment) squash/fixup: d6116a2 refactors TIME as H3 of reply ARTICLE (per review feedback) Each reply now consists of an ARTICLE automatically labeled by its H3 TIME. These implicit ARIA semantics are more fluent than those marked explicitly in 1f69640. thread: #6041 (comment) squash/fixup: 1f69640 refactors OUTPUTs as MARKs or Ps (per review feedback) Some "browser / screen reader pairings may not announce or make available the accessible name of the output, even though its a labelable element"[1], apparently including Orca (i.e., on Tails). These elements give the next-best semantics without implying a live region. [1]: https://www.scottohara.me/blog/2019/07/10/the-output-element.html thread: #6041 (review) squash/fixup: 1f69640 squash/fixup: f37fc17 squash/fixup: ae56f49

A refactoring like #5986 seems like a good opportunity for this kind of reformatting.

cfm · 2021-08-09T18:11:06Z

Thanks, @rmol. CI is running now with everything squashed down to one commit per phase of the refactoring. Feel free to pop off the 8f2b503 head if you don't like this formatting.

addresses review feedback Corrects 876bfa2's removal of these decorative IMGs without replacing their semantic content. thread: #6041 (comment) squash/fixup: 876bfa2 addresses review feedback Adds explicit title-case ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment) addresses review feedback Refactors MAIN.index-row rather than wrapping the whole DIV.grid in MAIN. thread: #6041 (comment) squash/fixup: 80547cd removes stray ARIA-LABELS (per review feedback) thread: #6041 (comment) addresses review feedback LABEL[for="codename"] was marked HIDDEN to prevent redundant narration in screen readers. Refactoring the LABEL to an H2 that ARIA-labels the containing section streamlines the narration and makes for a more-logical outline. thread: #6041 (comment) squash/fixup: ae56f49 refactors SECTION#codename-hint as DETAILS (per review feedback) ::{before,after} pseudo-elements must be used to style the expand/collapse links ("Show"/"Hide", respectively) because under DIR="ltr" the ::marker pseudo-element will be displayed to the left of the SUMMARY. thread: #6041 (comment) squash/fixup: 1f69640 adds "button" role to non-navigating links (per review feedback) thread: #6041 (comment) undoes autoformatting squash/fixup: 1f69640 fixes tests for refactored DETAILS#codename-hint squash/fixup: c8baf3d fixes unclosed ARIA-LABEL attribute (per review feedback) thread: #6041 (comment) squash/fixup: d6116a2 refactors TIME as H3 of reply ARTICLE (per review feedback) Each reply now consists of an ARTICLE automatically labeled by its H3 TIME. These implicit ARIA semantics are more fluent than those marked explicitly in 1f69640. thread: #6041 (comment) squash/fixup: 1f69640 refactors OUTPUTs as MARKs or Ps (per review feedback) Some "browser / screen reader pairings may not announce or make available the accessible name of the output, even though its a labelable element"[1], apparently including Orca (i.e., on Tails). These elements give the next-best semantics without implying a live region. [1]: https://www.scottohara.me/blog/2019/07/10/the-output-element.html thread: #6041 (review) squash/fixup: 1f69640 squash/fixup: f37fc17 squash/fixup: ae56f49

zenmonkeykstop

LGTM, thanks to @cfm for the work and for your patience!

Fixes #6081. Spacing is still *different* than pre-#6041, but as intended.

In #6041 we added the "aria-label" attribute in the "render_kw" dictionary passed to each wtforms.fields.Field. Here we add them these attributes directly to the raw INPUT elements.

cfm force-pushed the 5986-semantic-source-interface branch 2 times, most recently from 484cbd7 to 3ad7b2e Compare July 15, 2021 06:34

cfm force-pushed the 5986-semantic-source-interface branch 2 times, most recently from b0ef502 to 80547cd Compare July 19, 2021 04:27

cfm marked this pull request as ready for review July 19, 2021 04:35

cfm requested a review from a team as a code owner July 19, 2021 04:35

cfm requested a review from zenmonkeykstop July 19, 2021 04:35

SaptakS reviewed Jul 21, 2021

View reviewed changes

cfm added a commit that referenced this pull request Jul 27, 2021

addresses review feedback

c6cd5af

Corrects 876bfa2's removal of these decorative IMGs without replacing their semantic content. thread: #6041 (comment) squash/fixup: 876bfa2

cfm force-pushed the 5986-semantic-source-interface branch from e8c4073 to c6cd5af Compare July 27, 2021 18:50

cfm added a commit that referenced this pull request Jul 27, 2021

addresses review feedback

79b5924

Adds explicit ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment)

cfm added a commit that referenced this pull request Jul 27, 2021

addresses review feedback

17eb17a

Adds explicit title-case ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment)

cfm force-pushed the 5986-semantic-source-interface branch from 79b5924 to 17eb17a Compare July 27, 2021 19:17

cfm mentioned this pull request Jul 27, 2021

semantic (HTML5/ARIA) page structure in Journalist Interface #5987

Closed

20 tasks

cfm added a commit that referenced this pull request Jul 27, 2021

addresses review feedback

3ac7810

Refactors MAIN.index-row rather than wrapping the whole DIV.grid in MAIN. thread: #6041 (comment) squash/fixup: 80547cd

cfm added a commit that referenced this pull request Jul 27, 2021

addresses review feedback

2a908db

Adds explicit title-case ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment)

cfm added a commit that referenced this pull request Jul 27, 2021

addresses review feedback

92a22c6

Refactors MAIN.index-row rather than wrapping the whole DIV.grid in MAIN. thread: #6041 (comment) squash/fixup: 80547cd

cfm force-pushed the 5986-semantic-source-interface branch from 3ac7810 to 92a22c6 Compare July 27, 2021 21:33

cfm added a commit that referenced this pull request Jul 27, 2021

addresses review feedback

d6116a2

Adds explicit title-case ARIA-LABEL attributes to elements whose strings are in all caps to support idiomatic translation (cf. #5821, #6003). thread: #6041 (comment)

cfm added a commit that referenced this pull request Jul 27, 2021

addresses review feedback

adf55a1

Refactors MAIN.index-row rather than wrapping the whole DIV.grid in MAIN. thread: #6041 (comment) squash/fixup: 80547cd

cfm added a commit that referenced this pull request Jul 27, 2021

removes stray ARIA-LABELS (per review feedback)

07cd655

thread: #6041 (comment)

cfm force-pushed the 5986-semantic-source-interface branch from 92a22c6 to 07cd655 Compare July 27, 2021 21:48

cfm mentioned this pull request Jul 28, 2021

evaluate HTML5 UI elements as browser support improves #6031

Open

1 task

cfm mentioned this pull request Jul 28, 2021

reimplement locale menu with focus[-within] styles #6048

Open

cfm force-pushed the 5986-semantic-source-interface branch from 66ab8ba to c8baf3d Compare July 28, 2021 00:25

cfm added a commit that referenced this pull request Jul 28, 2021

adds "button" role to non-navigating links (per review feedback)

753da75

thread: #6041 (comment)

cfm added 6 commits August 9, 2021 13:59

corrects semantic markup per validators and accessibility-audit tools

850fad1

second pass through /: validate/audit second pass through /lookup: validate/audit second pass through /login: validate/audit second pass through ancillary templates: validate/audit

formats templates for more-consistent indentation

8f2b503

A refactoring like #5986 seems like a good opportunity for this kind of reformatting.

cfm dismissed rmol’s stale review via 8f2b503 August 9, 2021 18:07

cfm force-pushed the 5986-semantic-source-interface branch from 245689f to 8f2b503 Compare August 9, 2021 18:07

cfm mentioned this pull request Aug 10, 2021

Make <time datetime= into valid HTML by using a custom jinja tag #6058

Closed

1 task

eloquence unassigned rmol Aug 12, 2021

cfm mentioned this pull request Aug 16, 2021

uses valid BCP47/RFC5646 RequestLocaleInfo.language_tags in locale selectors #6067

Merged

6 tasks

zenmonkeykstop approved these changes Aug 25, 2021

View reviewed changes

zenmonkeykstop merged commit d3b0d36 into develop Aug 25, 2021

zenmonkeykstop deleted the 5986-semantic-source-interface branch August 25, 2021 18:33

cfm added a commit that referenced this pull request Sep 8, 2021

eliminates margin-top on sectioning elements within LIs

49bdaf4

Fixes #6081. Spacing is still *different* than pre-#6041, but as intended.

cfm mentioned this pull request Sep 8, 2021

resolves visual discrepancies on Source Interface #6096

Merged

1 task

eloquence added this to the 2.1.0 milestone Sep 28, 2021

cfm mentioned this pull request Oct 8, 2021

Release SecureDrop 2.1.0 #6103

Closed

26 tasks

conorsch mentioned this pull request Oct 19, 2021

[2.1.0] Merge translations #6148

Merged

1 task

cfm added a commit that referenced this pull request Nov 3, 2021

first pass through "/"

c12d802

In #6041 we added the "aria-label" attribute in the "render_kw" dictionary passed to each wtforms.fields.Field. Here we add them these attributes directly to the raw INPUT elements.

cfm added a commit that referenced this pull request Nov 5, 2021

first pass through "/login"

5b40da5

In #6041 we added the "aria-label" attribute in the "render_kw" dictionary passed to each wtforms.fields.Field. Here we add them these attributes directly to the raw INPUT elements.

This was referenced Jan 29, 2022

prevent focus behind/outside dialogs (WCAG 4.1.2) #6241

Open

ARIA support for source/journalist interfaces #3268

Closed

cfm mentioned this pull request Mar 10, 2022

Add basic message filtering in the SI #6306

Merged

19 tasks

eaon mentioned this pull request Mar 10, 2022

SI: focusing on #flashed message after submitting sometimes scrolls the viewport too far, may obscure message #6333

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactors Source Interface for semantic HTML5/ARIA markup #6041

refactors Source Interface for semantic HTML5/ARIA markup #6041

cfm commented Jul 13, 2021 •

edited

Loading

codecov-commenter commented Jul 15, 2021 •

edited

Loading

SaptakS left a comment

rmol commented Aug 9, 2021

cfm commented Aug 9, 2021

zenmonkeykstop left a comment •

edited

Loading

refactors Source Interface for semantic HTML5/ARIA markup #6041

refactors Source Interface for semantic HTML5/ARIA markup #6041

Conversation

cfm commented Jul 13, 2021 • edited Loading

Status

Description of Changes

Known issues

Testing

Deployment

Checklist

If you made changes to the server application code:

If you made non-trivial code changes:

codecov-commenter commented Jul 15, 2021 • edited Loading

Codecov Report

SaptakS left a comment

Choose a reason for hiding this comment

rmol commented Aug 9, 2021

cfm commented Aug 9, 2021

zenmonkeykstop left a comment • edited Loading

Choose a reason for hiding this comment

cfm commented Jul 13, 2021 •

edited

Loading

codecov-commenter commented Jul 15, 2021 •

edited

Loading

zenmonkeykstop left a comment •

edited

Loading