Improve disabled states documentation

[tay1orjones]

In https://github.com/carbon-design-system/carbon/issues/8509 users asked for tooltips on disabled buttons. In https://github.com/carbon-design-system/carbon/pull/14646 I took a jab at putting something together for it. This issue outlines the result of that exploration and the steps we'll take moving forward to address this problem space.

Why tooltips on disabled elements are not ideal

After lots of review with our team, the IBM Accessibility team, and external accessibility experts, we feel this pattern has inherent problems and isn't something we want to pursue adding to the system. This isn't an exhaustive list:

• Disabled buttons are intentionally removed from the focus order, according to the spec. Therefore, any information revealed on hover cannot be surfaced on focus, resulting in an accessibility failure.
• Adding "disabled" buttons to the focus order would increase time on task (significantly on some interactions) for screenreader/keyboard users, and also increase cognitive load, with a heavier impact on users with cognitive disabilities
• Disabled controls don't have to meet contrast requirements, but operable ones do. This would mean the need to add another visual state to button, and it would be difficult to distinguish from the existing states of enabled and disabled.

How to solve this issue

Without being able to put tooltips on disabled buttons, we're left with an important question:

What is the intended way to indicate to the user why a button is disabled?

This issue aims to answer this question by adding new documentation to the disabled states pattern on our website. We believe the use cases that appear to call for tooltips on disabled buttons can actually be solved via other methods that are more accessible and scalable. One small example of this in the wild was recently fixed by GitHub in a similar manner, https://github.com/carbon-design-system/carbon/issues/8509#issuecomment-1737745487.

The focus so far has been exclusively on buttons (mostly IconButton), but this documentation should cover other interactive elements with disabled states such as RadioButtons, OverflowMenuItems, MenuItems, DataTable selection checkboxes, etc.

Additional resources

• Internal slack thread
• https://uxpsychology.substack.com/p/hidden-vs-disabled-states
• https://uxdesign.cc/why-you-shouldnt-include-disabled-interaction-elements-in-your-design-system-76a2d4307faf
• https://www.smashingmagazine.com/2021/08/frustrating-design-patterns-disabled-buttons/

Request for feedback

To make this documentation as robust as possible, we'd like to compile a set of concrete examples showing UI where a tooltip on a disabled button would've been needed. Armed with these examples, our team will use them to ideate on scalable solutions and inform the documentation.

[!IMPORTANT]
If you have examples of areas you would've preferred to have tooltips on disabled buttons, please share screenshots in comments on this issue.

---

- [ ] Gather use case examples
- [ ] Evaluate use case examples and craft scalable UX solutions for these situations
- [ ] Document findings on the website in the form of new sections, do/don't examples, etc.
- [ ] Review with the Carbon team, IBMa, and internal teams/stakeholders

[jan-christensen1]

added some screenshots to a mural to show how we currently make use of tooltips on disabled buttons. Invite link to the mural is in this Slack post

[dakahn]

(Butting in where I don't officially belong so feel free to ignore, but I remembered some nuance from when we'd discuss this back in the day)

I can think of two distinct use cases for disabled form elements that also have distinct "justification" worth picking apart a little bit here:

1. A disabled form element that communicates a user error of some kind. Justification: we don't want the user to waste a click/trip to the server and return an error they have to fix (??? this seems to be the most oft-cited reasoning at least; there could be others).

I would say this constitutes an anti-pattern worth phasing out. For sighted users it's too subtle and inefficient necessitating easy to miss inline error messaging anyway trading one frustration for another (not totally down to design. Users can't know website to website when their form will be validated) and for screen reader users it requires a highly illogical solution to be accessible--allowing a disabled element to receive focus 😅--which potentially degrades sighted keyboard user's experience. When folks write about disabled form elements being problematic this case is usually what they're referring to.

2. A disabled form element that communicates that some previous choice a user's made has resulted in the disabled choice being invalid. Justification: this allows the user to explore options, configurations--sometimes It's potentially a marketing tactic with lower stakes as part of a 'funnel'

So in this case we're not necessarily thinking of a user whose spent some amount of time carefully (or not so carefully) filling out a form being unable to continue until they correct some error. This I think is the case worth building out and documenting. I'd say that either way having tooltips on disabled elements falls pretty neatly into that aforementioned "highly illogical" solution category so I support the conclusion 😄.

It would seem like messaging in plain text in close proximity to the disabled element is the way to go: "Server size options are unavailable when configuring a serverless framework" or something. 🏄🏽