UI library accessibility initiative

[Mohammer5]

Current situation

We have a decent amount of custom input components. They:

• Require a lot more maintenance than native components, which are free
• Are nowhere near as accessible as their native counterparts
  • limited keyboard accessibility support in comparison with native input elements
  • lack of "meaning for non-standard interactive elements"
  • have internal structure/design that might not be distinguishable enough
  • are not completely navigable

Solution

We introduce styled native inputs. These provide a consistent DHIS2 branding, without the complexity or maintenance burden of our existing components and can be implemented quickly due to their simplicity and built-in features.

1. A namespace to avoid clashes and make adoption optional: Native. We'll have NativeInput, NativeSelect, etc.
2. We forward all props, this simplifies maintenance and usage.
3. Over time we can deprecate our inaccessible components in favor of the native components

By allowing the new native components to be opt-in adoption can be gradual. We'll have time to figure out edge cases that can't be easily addressed by native components. But those that want to upgrade can easily do so.

This is also the easiest possible way to quickly have accessible components that cost very little to maintain. Besides that it paves the way for meeting accessibility requirements for our funding.

Background

There are two reasons for making this proposal now:

Funding
During our last team platform meeting, some peers mentioned that we'd have to improve our accessibility to continue to receive funding from some governments.

Blur events
4. React final form has a feature called "validate on blur", which improves forms' performance by only running validation when leaving a field. Some of our components have dropdowns (most notably the select components), which are rendered outside the DOM of the actual select component as we're using a combination of our Layer component (to manage z-axis layering) and Popper (to ensure the dropdown is always in the viewport). This makes having a sane implementation for focusing and blurring the input component impossible. @ismay looked into the differences between our select components and native select inputs here. Changing the select so it implements the focus and blur specs of the native element requires using quirks and hacks (as clicking an option will trigger the blur event, which we have to suppress, we'd then have to refocus the actual select component without firing a focus event)

[cooper-joe]

Happy to see this! I wholeheartedly support an accessibility initiative for our UI library. I'm open to different ways of achieving this.

Previous work

2.5 years ago I wrote up a "minimum accessibility support" checklist that would've established a baseline of accessibility across our components. Looks like work on that has stalled, which perhaps is a consequence of the "require a lot more maintenance than native components" downside of custom components you mention above.

Native components

I am in favour of using native components where possible, the advantages for accessibility are worth it. Looking at the UI library, I'm not sure how many components we'd classify as "not native" though? Select is the obvious one, but what are the others?

For example, is our checkbox considered non-native because of the amount of customisation we've applied, even though it's still <input type="checkbox"> under the hood?

Regarding Select, the reasons we offer a non-native component are clear: there are use cases that warrant it. So, this stands out to me:

We'll have time to figure out edge cases that can't be easily addressed by native components.

Filterable and Multiselect, to name two, are heavily used across the platform and can't be considered edge cases. We'd need to be comfortable accepting that a custom Select is required to keep offering the UI options that we offer today. I think offering a basic, native NativeSelect can be a good idea, but I don't think that means we can avoid implementing accessibility best practices in our custom components too.
Edit: For example, Elastic's UI library offers four Select-type components.

Moving forward

I definitely want to see this initiative move forward, so I'd suggest a few next steps, if I may:

• Get more opinions about the Native... approach.
• Evaluate each UI component, determine if there's a native version we can offer as NativeComponent.
• Establish a baseline of accessibility we commit to achieving in our custom components

[ismay]

Looking at the UI library, I'm not sure how many components we'd classify as "not native" though?

I would say all components that do more than applying styles, and don't just forward all props (so no manual prop forwarding as that still introduces maintenance overhead). I'm not sure, but that might be all of them, or at least a lot. That's in my opinion a core goal of this proposal: to forward all props via prop spreading, and to just apply styles. Anything else introduces a lot of maintenance and complexity.

Filterable and Multiselect, to name two, are heavily used across the platform and can't be considered edge cases. We'd need to be comfortable accepting that a custom Select is required to keep offering the UI options that we offer today. I think offering a basic, native NativeSelect can be a good idea, but I don't think that means we can avoid implementing accessibility best practices in our custom components too.

I agree. I don't think that this proposal aims to reduce our components to just native elements. Instead, the goal is to allow for custom components where necessary. The use-cases you mention seem like valid reasons to retain those custom components to me, they can exist side-by-side.

The thing that this proposal solves is the usecases that would be adequately solved by native elements. Those just require components that match the DHIS2 design language, and I suspect that those usecases are very common.

[ismay]

One thing I should add is that even the styling should be done conservatively in my opinion. Even styles can introduce accessibility issues.

[Mohammer5]

Select is the obvious one, but what are the others?

Transfer is the other big one I can think of. It looks like it could be a composition of two native multi selects with buttons. That'd be more accessible than what it is now.

@ismay: I don't think that this proposal aims to reduce our components to just native elements.

Yes, this is not a proposal to remove any component but rather to deprecate those that can be deprecated safely. If there are components that we simply cannot re-implement in an accessible way, then we can keep them of course!

Also I think that we can certainly wrap the native elements with additional states that we have already (e.g. loading, warning, error states which will show different border color and icons) as long as we make sure that it won't harm accessibility. E.g. the tab index should be applied to the input, not the root container dom element, unknown probs should probably still be forwarded to the input component, but this is where things get a little complicated and we'd have to discuss what we want and how we solve it as we might want to allow props forwarding to the root container, too.

---

For example, is our checkbox considered non-native because of the amount of customisation we've applied, even though it's still under the hood?

I think that the way we've hidden the checkbox keeps it accessible (with opacity: 0). So it's a technique we could apply. I would like to question hidden + fake checkboxes and radio buttons though, here's the "First Rule of ARIA Use" from w3.org:

If you can use a native HTML element [HTML51] or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so.

There are some things we have to think about, in this case the checkbox'es indeterminate state, which could be solved this way. But even w3.org states that:

There may be support gaps in some browser and assistive technology combinations, especially for mobile/touch devices. Testing code based on this example with assistive technologies is essential before considering use in production systems.

---

We'll have time to figure out edge cases that can't be easily addressed by native components.

Filterable and Multiselect, to name two, are heavily used across the platform and can't be considered edge cases. We'd need to be comfortable accepting that a custom Select is required to keep offering the UI options that we offer today. I think offering a basic, native NativeSelect can be a good idea, but I don't think that means we can avoid implementing accessibility best practices in our custom components too.
Edit: For example, elastic/eui#7049.

The three complex select suffer from the same issues Ismay and I discovered in our own select components: Just clicking an option is already triggering the blur event, which is different from how the native select works.

This can be reproduced by adding onBlur={() => console.log('blur')} to the code sandboxes:

• native select wrapped: https://codesandbox.io/s/2j4xyk?file=/demo.js
  onBlur is not triggered when clicking an option, but when focusing another element (e.g. body) afterwards
• super select with custom menu: https://codesandbox.io/s/wrm4nl?file=/demo.js
  onBlur is triggered immediately when clicking an option

---

Moving forward

I definitely want to see this initiative move forward, so I'd suggest a few next steps, if I may:

• Get more opinions about the Native... approach.
• Evaluate each UI component, determine if there's a native version we can offer as NativeComponent.
• Establish a baseline of accessibility we commit to achieving in our custom components

That sounds good to me! There are ways to re-create our complex components in an accessible way with slightly different approaches.
E.g. a searchable select can be implemented with an input + radio (single select replacement) or input + checkbox (multi select replacement). If we want to hide the options, we can make use of the a11y disclosure pattern. This would mean we'd have an input, a button (to have an accessible control for collapse/expand the options) and a div container with the actual option inputs. Of course we can also programmatically open the options when the user focuses the input, but we'd still have the button for assistive technology

[amcgee]

As mentioned in the call I'm very in favor of accessibility improvements and this is something strategically we want to do.

I don't think we should offer a separate component for native. If the functionality is the same, we should replace it under the hood of the existing component and spread props where possible (or offer namespaced passthrough props like inputProps where not). This will ease the transition and ensure that all users of our components (including existing ones) benefit from the improvements.

I agree with @cooper-joe - I'm not sure there are that many components that could be native that aren't already... so other than prop spreading it's not clear to me which components would benefit from this proposal, would love to see the list! Probably even more important than prop-spreading from an accessibility standpoint is to improve the props we pass to the underlying native components (without requiring the app to pass those props) to ensure they are keyboard and screen-reader accessible by default.

[ismay]

I'm not sure there are that many components that could be native that aren't already

Depends on your definition. These components all do more than just apply styles to their browser-native counterparts:

• https://github.com/dhis2/ui/tree/master/components/text-area
• https://github.com/dhis2/ui/tree/master/components/radio
• https://github.com/dhis2/ui/tree/master/components/select
• https://github.com/dhis2/ui/blob/master/components/legend
• https://github.com/dhis2/ui/tree/master/components/input
• https://github.com/dhis2/ui/blob/master/components/label
• https://github.com/dhis2/ui/tree/master/components/button
• https://github.com/dhis2/ui/tree/master/components/checkbox

That's from a quick check of the repo. But basically all UI components that have a browser-native counterpart have functionality that isn't present in their upstream equivalents, extra elements, or both. So they're not interchangeable.

[amcgee]

Right, for sure. But they all render native components under the hood (rather than a styled <div> with onClick or something) which is what I thought we meant here. In many cases the additional elements or custom behaviors are by design and something we want to provide a good user experience. Ensuring that custom elements and custom interactions are minimized where possible and where necessary are designed to be accessible sounds like the right approach, but I still think that should be done in-situ rather than with a new set of components.

[ismay]

But they all render native components under the hood

That's true (except for the select and the transfer). But yeah that's not what I really meant. The way I see the proposal is as a way to move towards standardized, simpler, more maintainable components.

For example, our input:

• The statusicon functionality here: https://github.com/dhis2/ui/blob/master/components/input/src/input/input.js#L184-L189. This pattern is duplicated throughout our lib. It seems like it would be more maintainable to implement as a HOC or with some other kind of composition.
• The props here: https://github.com/dhis2/ui/blob/master/components/input/src/input/input.js#L133-L151 most of these are just passing through props to the input verbatim. Prop spreading would be a lot easier to maintain. No more manual allowlisting and no more chances of mistakes, weird incongruencies or missing props.
• This handler is not necessary when using prop spreading: https://github.com/dhis2/ui/blob/master/components/input/src/input/input.js#L94-L98. You can just use the autoFocus prop.
• These handlers are also duplicated throughout our lib.: https://github.com/dhis2/ui/blob/master/components/input/src/input/input.js#L100-L129. In my opinion we should never have diverged from the standard callback signature, but that's besides the point. At the very least I think that there's a lot of opportunity for simplification/reduction of duplication here as well.
• This style: https://github.com/dhis2/ui/blob/master/components/input/src/input/input.js#L194 is not how a standard input behaves. This seems counterproductive to me. Adding these styles where necessary is just as easy. If the usecase is common enough then I'd say it maybe warrants a different component, but not overriding the defaults. That just annoys all the people who don't need this.

Stripping out all the above leaves you with just the styles. That is what I'd propose. Create components with a clear scope that don't diverge from the standards but just provide consistent branding. I'm not against doing this all in situ btw. We could build our existing components on top of those simplified components. I think there's already value in that and I think it could help us tackle all of the above.

I did like the additional goal of exposing those barebones components that just provide style. I see value in that, but it does hinge on us dropping some of our non standard behaviour like the callback signatures, otherwise it'll just be confusing. I think that's a good thing, but we might already be at a point of no return, so I'm ok with dropping that part of it in favor of just improving things within the current API.

[Mohammer5]

Besides the select and transfer components, the checkbox is not accessible either due to the indeterminate state

[kabaros]

I have setup the topic for the next DevEx meeting to discuss this proposal in details (January 11th). Few thoughts I have:

• We discussed forwarding props before without filtering and there was consensus that this is something we want to do. I think we should do it (even outside this proposal) since it's very arbitrary what we choose to pass down or not right now. The challenge was that for some composite components, it's not straight-forward to know where to pass the props. But at least for many of the ones mentioned here, we can make good assumptions (and that would solve some of the accessibility issues, or at least not lock consumers in an inaccessible UI).

• I agree with the pain points described here but not necessarily the solution (the NativeX components). I think we should aim to update the existing components whenever possible, otherwise we end up doubling the problems we have. Some of these components will be straight-forward, others might involve breaking changes or a totally different approach to how we build them but I think it's better to have breaking changes than having to maintain two sets of components. The starting point in all cases would be to just have a more detailed analysis of the existing components and try to group them together. Some possible groupings:

  • components that have one underlying native component (easy-ish group)
  • some that have multiple underlying native components but there is one main native component (they are not interchangeable but we can have a consistent approach on deciding which is the main underlying component)
  • some that have fundamental accessibility issues and we need to re-architecture regardless

It would also be good to analyse what other UI libraries do in this space (especially ones focused on accessibility like radix-ui which is also unstyled), since a lot of these challenges are not specific to us. I think a general concern to address would also be whether we can provide components that are accessible by default, rather than ones that rely on the consumer to address accessibility (by using native components, or forwarding props).

Get more opinions about the Native... approach.
Evaluate each UI component, determine if there's a native version we can offer as NativeComponent.
Establish a baseline of accessibility we commit to achieving in our custom components

I think the three points here from Joe are good way to head forward, so let's use them as a starting agenda for the meeting.