Accessibility - HTML codestyle - icons along text alternatives


In order to fulfill WCAG success criterion 1.1.1: Non text content (level A), we need to provide text alternatives for images. Icons are (most of the time) images that are only here for visuals. By making sure every icon is only here for visuals, we can use the role=‘presentation’ on those icons and avoid failing SC 1.1.1.

I would like to propose a new code style to respect in our HTML templates:
Only use icons along text alternatives. The text alternative can be visually hidden.

So far, in xwiki-platform it’s already the case for most icons. However, this is inconsistent and some icons are used ‘as is’ in a few places. If this proposal is accepted, I’ll take care of adding text alternatives to those outliers.

I think this is better than those two other solutions I could think of to fix our violations to SC 1.1.1. :

  1. Update the icon renderer to give a default text alternatives to the icon based on their name:
    • need to create/update a lot of new translations
    • some icons should have different text alternatives for different contexts, one value is not good enough (e.g. vertical dots is never a good alternative for the icon with this name …).
  2. Update the icon rendering API to get a ‘label’ argument as input (label being short for text alternative) and deprecate the API without a label argument.
    • need to update all uses of the API where the text alternative is already added (most of them) to make use of this new syntax
    • heavier to implement
    • About as difficult to use in new templates as the proposal: $services.icon.renderHTML($iconName) <span class='sr-only'>$iconLabel</span> is not much more difficult than $services.icon.renderHTML($iconName, $iconLabel)

What do you think of this potential addition to our HTML and CSS Codestyle? Would you rather see the solutions 1. or 2. implemented instead?

Thanks for reading this proposal :slight_smile:
Have a good day,
Lucas C.

PS: Accepting this proposal would make the unvalidated WCAG rule on HTML and CSS Codestyle irrelevant and I’d remove it from the page.


Yes, but the API reminds you that you need a text alternative. If we have automated (WCAG) tests to catch this then I agree the new API is not that important. Otherwise, I find it useful.


We do have automated WCAG validation to catch this (as long as there are integration tests made for the feature). :slight_smile:

Updated the HTML Codestyle.