Building a Salesforce UI for Accessibility — Part 1 — Introduction

Disclaimer: I’m not a Subject Matter Expert on assistive technologies, and these articles are about my learning journey. I’ve been able to build fairly complex Salesforce LWC components for a while now and wanted to understand how these have fallen short of being truly accessible and determine approaches to address them.

Salesforce does an admirable job in making its user interface particularly accessible. They have built their user interfaces and components with accessibility built in along WCAG guidelines and provide clear guidance for anyone building on top of the platform.

1. Accessibility checking tools can help validate your user interface for accessibility, but
2. A truly accessible user interface requires a lot more thought and design.

My first discovery is that if you restrict yourself to building custom components with the Salesforce LWC toolkit and minimum attributes, then your resulting custom components will actually be mostly WCAT compliant. If you choose to ‘go off the beaten track’ and implement your own components with HTML, then you will definitely need to put in a good deal of effort to get that compliance.

Remember that ‘compliance’ is a starting benchmark, but that in itself is not enough to make a useful accessible component. In fact your component can pass all automated tests and be completely unusable to screen readers.

My first example is a simple LWC calculator control that just does multiplication. It runs only in the browser, and I didn’t build it with wider User Interface or UX concerns — just plain and simple:

Simple calculator LWC control

I used the Microsoft Edge Accessibility Insights tool to look for issues, and quickly discovered that even bare minimum individual LWC controls will pass automated WCAT validation with little effort. Nevertheless, my whole component had two clear problems — 1) a decorative image with no purpose, and with no indication that it can be ignored, and 2) an image button that doesn’t indicate its purpose textually:

So, what is the practical effect of these issues? Well, you can run a screen reader over the controls and see what happens when you select the ‘=’ button. Because it is an image, the screen reader doesn’t know how to describe it and speaks out the text below instead. This tells me that I have selected a button, but with no indication at all about what it does. As far as I know it could clear the input values:

Screen reader trying and failing to describe an image button on the user interface.

These can be easily fixed with Alternative text labels and titles, and WCAT validation now fully passes.

Better description for the image button.

However, we can take it further by adding descriptions specific for users of assistive readers with the ‘aria-label’ attribute:

<lightning-input label="Second input:" aria-label="Second integer value for calculation" type="number" name="inputSecond" value={valueSecond} onchange={handleSecondInputChange}></lightning-input>

<lightning-button-icon title="Multiply Values" aria-label="Multiply both input values" aria-live="assertive" icon-name="standard:assignment" class="slds-var-m-left_xx-small" onclick={handleCalculateClick}><label>Multiply</label></lightning-button-icon>

Even more detailed description targeted at screen readers.

So, the user can now multiply the two input values, but then what? The screen displays the result but there is no other indication that anything changed!

We can add an ‘aria-live’ attribute to the result in order to automatically announce it when changed:

<div role="alert" aria-live="polite">
     Result is <b>{calculationResultLabel}</b>
</div>

The screen reader reacts to the result being displayed.

Is this a good accessible component? Definitely not — a new user will still face challenges in understanding the user interface. However, you can see already how additional attention to accessibility markup can make the difference to a component that is almost unusable to a screen reader, to one that can provide some useful context, information, and feedback.

Notes:

1. Source code for both ‘bad’ and ‘better’ components are here: andrewwhitten/lwc-accessibility-learning: Salesforce LWC component samples with accessibility designs (github.com)
2. You can run the components in a Salesforce instance or even easier on a local LWC server: Set Up LWC Local Development | Salesforce for VSCode
3. I used the built in screen reader on MacOS Somona.
4. I used the Microsoft Edge browser. Accessibility tools / plugins are available on Chrome and Safari as well.
5. I’m not an SME in this space at all. Please feel free to provide feedback to this article and I’ll update it.