semantic (HTML5/ARIA) page structure in Journalist 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
• Keep in mind per @eloquence in Review and prioritize 2019 accessibility report findings #5972 (comment):

  One thing we may want to look into for the next round of changes is how to minimize the need to re-translate strings - e.g., should we generate our own translations in cases where only HTML elements or attributes change (can we do so in the main repo and then import these into Weblate?).

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) and keep journalist.js in sync
   • decorative img/hr/etc. elements: comment out 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. Accessibility-focused review of draft PR before continuing further
4. Review string changes for translation per Review and prioritize 2019 accessibility report findings #5972 (comment)
5. Third pass: CSS and images broken in first pass (test visually in Tor Browser)
   • FIXMEs
     • Revert 6d4602d
   • tests pass
6. Write and run through test plan in refactors Journalist Interface for semantic HTML5/ARIA markup #6165

Path	First Pass	Second Pass	Third Pass
securedrop/journalist_templates	✓	✓	✓
├──_confirmation_modal.html	✓	✓	✓
├──_source_row.html	✓	✓	✓
├──_sources_confirmation_final_modal.html	✓	✓	✓
├──_sources_confirmation_modal.html	✓	✓	✓
├──account_edit_hotp_secret.html	✓	✓	✓
├──account_new_two_factor.html	✓	✓	✓
├──admin.html	✓	✓	✓
├──admin_add_user.html	✓	✓	✓
├──admin_edit_hotp_secret.html	✓	✓	✓
├──admin_new_user_two_factor.html	✓	✓	✓
├──base.html	✓	✓	✓
├──col.html	✓	✓	✓
├──config.html	✓	✓	✓
├──delete.html	✓	✓	✓
├──edit_account.html	✓	✓	✓
├──error.html	✓	✓	✓
├──flashed.html	✓	✓	✓
├──index.html	✓	✓	✓
├──js-strings.html	✓	✓	✓
├──locales.html	✓	✓	✓
├──login.html	✓	✓	✓
└──preferences_saved_flash.html	✓	✓	✓

Specific cases

• Address review feedback in refactors Source Interface for semantic HTML5/ARIA markup #6041 (comment)
• Refactor *modal.html as dialogs à la Source Interface's .{confirm,hidden}-prompt

add_user.html

• h1 should not be .visually-hidden

col.html

• Listing of a source collection could be a semantic table
• securedrop/journalist_templates/col.html: p.breadcrumbs is a set of unstructured inline elements; could be ul styled with li:{before,after} selectors
• div dialogs are still being read (unlike those in index.html)

index.html

• List of sources could be a semantic table
  • td.filename should wrap more elegantly (or not at all)

[cfm]

@eloquence, per #5972 (comment), here is the translation distance incurred by the draft of #6165:

cfm@ozymandias securedrop % make translate
Updating translations...
[...]
cfm@ozymandias securedrop % git diff --compact-summary securedrop/translations/messages.pot
 securedrop/translations/messages.pot | 119 ++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 85 insertions(+), 34 deletions(-)

A handful of these will be case changes that we can edit in bulk in the individual .po catalogs before starting localization for the v2.2.0 release. The rest we'll just need to give translators adequate time to work with, especially from updated screenshots.

[eloquence]

Thanks, that's helpful! For the string changes we can apply across language immediately, should that be done as part of #6165 already or are there good reasons to hold off on that?

[cfm]

On 13 Dec 2021, at 16:57, Erik Moeller wrote: Thanks, that's helpful! For the string changes we can apply across language immediately, should that be done as part of #6165 already or are there good reasons to hold off on that?

Yep, I’ve noted this in #5987 as part of the final linting to be applied to #6165 before final review and merge. (I’ll test these manual translation updates in the Weblate sandbox, too.)

[cfm]

#6165 now has a test plan, and I've updated this ticket with the things that I've caught (so far) and will fix incrementally while FPF is off between now and New Year's.

[cfm]

As outlined above, #6165 will be ready for review tonight pending CI. Of note, but out of scope of the current accessibility effort: The Journalist Interface’s style sheets tend to be more logical and DRYer than the Source Interface’s, but there’s still room for more consistency. For example:

• Button-related styles could be refactored to be agnostic as to whether they are styling an a or a button element.
• Buttons’ icon adornments could be streamlined by using generic selectors like [classname^="icon-"] and then adding icon-specific background properties: e.g., .icon-foo → background-image: url(foo.png).

More broadly, with the completion of this second accessibility refactoring, I see an opportunity to use a UI framework, if one exists that can be bundled acceptably or rendered server-side, to translate the current UI into reusable components, much as we’re doing in Qt for the SecureDrop Client. Such a further refactoring would make the UI more maintainable going forward, including by taking the current template-level accessibility improvements and baking them in at the component level.