I categorised icons according to the below by inserting a comment above each icon - which I then removed before finalising the PR, so those comments can be found in the commit history to track the 'why' of each change.

Icon Categories

We use both decorative and semantic icons in the Front of House. In every case, icons are inserted using the syntax: <i aria-hidden="true" class="fa fa-icon-name"></i>. Where these are decorative, that is all that is required. Where the icon is being used to indicate a date, then the date which follows should be able to be programatically determined by using the <time> tag. The final category are semantic icons, where a non-visual alternative is required, and this is coded using the <span class="sr-only">text alternative </span> syntax.

Icons should not be included in any other way unless no fa version exists.
known exceptions:

• ORCID logo (inserted as image).
• X logo (a hidden span with unicode).
• unicode × (×) used for close buttons

Decorative

these icons are purely decorative, and should include aria-hidden="true"

<i aria-hidden="true" class="fa fa-search"></i>

Semantic

these icons should be aria-hidden=true as with decorative, but have adjacent <span class="sr-only"> text alternative</span>. Note, the sr-only span may be a few lines before or after the icon, depending only on where it make the most sense if read aloud in the context of other content.

<span class="sr-only">{% trans 'Externally hosted article:' %} </span>
{{ article.title|safe }}&nbsp;
<i aria-hidden="true" class="fa fa-external-link small-icon-text"></i>

or

<i aria-hidden="true" class="fa fa-play" ></i>
<span class="sr-only">{% trans 'Play' %}</span>

Special Cases

Date

These icons are used to indicate a date, and should be marked as decorative with the date itself marked up with the <time> html tag. Note that the <time> tag is not yet supported by WAI-ARIA but is recommended for future proofing. Screen reader support is variable, and from manual testing, the internal <span role="time"> was found to be needed to prevent some screen-readers from reading out the date twice. This is therefore the format to be used:

<i aria-hidden="true" class="fa fa-calendar"></i>
<time datetime="{{ article.date_published|date:"Y-m-d" }}">
    <span role="time">{{ article.date_published|date:"Y-m-d" }}</span>
</time>

Email (within a loop)

These icons are semantic, however as many of our email icons are as part of 'email author' links where a loop is used because there could be more than one author. In order to meet WCAG 2.4.4 these sr-only spans need to include the author name so as not to create multiple indistinguishable 'email author' links. A similar approach should be taken for any other semantic icons used with logic loops which could output multiple copies.

<a itemprop="email" href="mailto:{{ author.email }}" >
    <i aria-hidden="true" class="fa fa-envelope email-link" ></i>
    <span class="sr-only">{% trans 'Email' %} {{ author.full_name }}.</span>
</a>

ORCID logo as a link to an author's ORCID profile

Handle as Semantic Icons. These are not strictly icons, as it is included as a local .png. However, as with author emails, it is important to make the text alternative for these links unique, by including the author's name. Note, when testing with VoiceOver, using an aria-label on the <a> tag did not work well, as it ended up with the ORCID numbers being included in the link description that was read aloud.

<a href="https://orcid.org/{{ author.orcid }}" class="">
    <img src="{% static 'common/img/icons/orcid.png' %}" alt="">
    <span class="sr-only">{{author.full_name}} {% trans 'ORCID profile.' %}</span>
</a>

X

Our icon set doesn't include the X logo. But the unicode 𝕏 (𝕏) looks identical, so we have used that. Note the span that includes the X needs to be aria-hidden=true .

<span aria-hidden="true"> &#120143;</span>
<span class="sr-only">{% trans 'Share on X' %}</span>

× for close

We have used the unicode × on close buttons in many places. This is already accessibly marked up, so has been not been changed during this update.

<button class="close-button" data-close aria-label="Close modal" type="button">
    <span aria-hidden="true">&times;</span>
</button>

Testing

Results

Notes

• "passed on sight" are items where code was reviewed by @ajrbyers
• ✅ passed a manual review of the page
• "not used" / "deprecated" are templates no longer in use
• "no styling on page" refers to two templates were icons shouldn't be used anyway, these were then removed.

I've re-assigned this issue to @StephDriver as there is an outstanding conflict.

I've re-assigned this issue to @StephDriver as there is an outstanding conflict.

resolved.

conflicts resolved. I have also reviewed the new share templates that replace several icons used here, and they match the new syntax.

@joemull I think adding in Search labels is feature creep over this PR which was very specifically for icons and tables (the two were originally separate, but the table one hadn't gone through and they handle the same lines, so they were bundled for practicality, the search changes haven't even been started yet, so not the same).

the accessible search is needed, but that's out of scope here - and needs to be done across all templates just like these changes were done across all to get them standardised. The search is no less accessible than it was before.