I propose that we add a new feature to widgets for them to have a screen reader label which is always hidden, and we set that using an aria attribute or hidden text nodes which are set manually using a specific property, or automatically if a manual setting is not specified using the title or label text if either exists.

The unanswered question in this approach is whether we need DOM text, or can use an attribute.

According to http://www.paciellogroup.com/blog/2008/04/aria-toggle-button-and-tri-state-checkbox-examples/ the "alt" attribute can be used to indicate the screen reader label for checkboxes or toggles. There might be subtle differences case-by-case depending on the widget.

I like the idea of a "ScreenReader" mixin with a standard property name for setting the screen reader information. In the constructor you'd set a default value depending on some other property (like a label), and you might override the implementation to alter the attribute name or position.

Maybe we should have actual text labels ... for buttons which only have icons/indicators.

Yes we should. Also T88979 is sort of similar to this.

.. rest, need to double check that.

Hmm, i'm a bit confused, what kind of controls are we talking about specifically ?

Can we get some examples listed ?

@TheDJ: We are coming especially from widgets like "ButtonWidget (icon only, framed)‎" which would get an accessibility push through correct DOM Text implementation IMHO and a work around would be possible for that nasty bug MatmaRex mentioned above: T94750: In MediaWiki theme, button height should be controlled only by 'padding' and label 'line-height'

dom content is ideal, for various reasons, but for screenreaders and also for keyboard accessibility, there is little different between aria-label and offscreen dom content.

However as a standard user, I also like to have tooltips on icon buttons (title=), and then it goes that repitition is annoying for screenreaders, so if we have a title, we might NOT want dom text content.

I was hoping to have DOM content because we need to change the way icons are rendered inside the buttonwidget. most of the height issues will be solved in if iconelement is absolute position, but if we do that then there is no height to the button. if there is DOM text inside the button which is not visible but maintains the height of the button, that would be ideal. then icons and indicators can be absolute and won't contribute to the height of the buttonwidget. also positioning them is much easier.

Second Nirzar's comment!
Another option would be to go for a IMHO dirty hack by putting CSS generated content like a non-breaking space to solve that particular button height issue. If possible, I want to avoid that approach.

But in general I'd definitely opt for DOM Content, also in respect to http://www.paciellogroup.com/blog/2010/11/using-the-html-title-attribute/
Citing from the article:

User groups not well served by use of the title attribute:

Mobile phone users.
Keyboard only users.
Screen magnifier users.
Screen reader users.
Users with fine motor skill impairments.
Users with cognitive impairments

And from HTML 5.1 draft:

Relying on the title attribute is currently discouraged as many user agents do not expose the attribute in an accessible manner as required by this specification (e.g. requiring a pointing device such as a mouse to cause a tooltip to appear, which excludes keyboard-only users and touch-only users, such as anyone with a modern phone or tablet).

Still thinking about how to best Accessibility include DOM Content while preserving Tooltip functionality for users like @TheDJ

@matmarex @Prtksxna How can we move this forward? This is still one of the biggest missing points for screenreaders of all our widgets.
Integrating some text node into iconElement-icon/indicatorElement-indicator per default when no label is set?
We'd need to double-check if we have both, an IconElement & IndicatorElement set, although there's T150071 to get rid of Indicator only buttons, which would help here again.

From the description

Per a chat with @Nirzar today, maybe we should have actual text labels, hidden except for screen reader software, for buttons which only have icons/indicators? Or, in other words, maybe we should force always having a label and sometimes just not display it.

Reading the comments I understand that this was suggested for two reasons:

Height issues

In T94749#1346194, @Volker_E wrote:

… and a work around would be possible for that nasty bug MatmaRex mentioned above: T94750

In T94749#1346901, @Nirzar wrote:

… if there is DOM text inside the button which is not visible but maintains the height of the button, that would be ideal…

Given that T94750 and T93290 are nearly resolved, am I correct in assuming that this is no longer a deciding factor?

Accessibility

This reason still stands, the approach needs a decision:

In T94749#1342510, @TrevorParscal wrote:

…the unanswered question in this approach is whether we need DOM text, or can use an attribute.

WAI-ARIA: 5.2.7.3. Text Alternative Computation explains in detail how an assistive technology might find a text alternative for a given element. Using the aria-labelledby and aria-label are the first two options (in order), but neither is suggested as being better. So, for the sake of simplicity of markup, I'd pick the aria-label attribute.

But, the HTML5 spec has very specific guidelines for a link or button containing nothing but an image. It suggests that one should, 'include text in the alt attribute(s) that together convey the purpose of the link or button'. While different, it isn't at odds with the WAI-AIRA suggestions, since in step 2C the text is collected from the subtree, and the 'alt' attribute can be picked up from there.

After reading this I realized that are images aren't imgs, and instead come from CSS (*facepalm*). So, again, I'd pick aria-label.

In T94749#1346748, @TheDJ wrote:

However as a standard user, I also like to have tooltips on icon buttons (title=), and then it goes that repitition is annoying for screenreaders, so if we have a title, we might NOT want dom text content.

According to WAI-ARIA, '2D: The last resort is to use text from a tooltip attribute (such as the title attribute in HTML). This is used only if nothing else, including subtree content, has provided results.'' So, if any other text alternative is found, the title attribute isn't used. According to the spec, and some usage examples, title along with DOM content, or aria-labelledby, or aria-label, should be able to happily co-exist.

I found (a four year old) blog post about this too, especially see the video at the end - https://silktide.com/i-thought-title-text-improved-accessibility-i-was-wrong/

@Prtksxna The height should not play into our decision around this any more.

As you've correctly identified, relying on title only is not providing 100% sufficient support.
This is where my idea above comes in. If we gonna provide a DOM text in the iconElement-icon span in an iconElement-only widget combined with a screen reader only CSS visibility, we would be on the safe side:
DOM of ButtonWidget icon only from the demos would change from

<span class="oo-ui-widget oo-ui-widget-enabled oo-ui-buttonElement oo-ui-buttonElement-framed oo-ui-iconElement oo-ui-buttonWidget" aria-disabled="false">
  <a class="oo-ui-buttonElement-button" role="button" title="Icon only, framed" tabindex="0" aria-disabled="false" rel="nofollow">
    <span class="oo-ui-iconElement-icon oo-ui-icon-help"></span>
    <span class="oo-ui-labelElement-label"></span>
    <span class="oo-ui-indicatorElement-indicator"></span>
  </a>
</span>

to

<span class="oo-ui-widget oo-ui-widget-enabled oo-ui-buttonElement oo-ui-buttonElement-framed oo-ui-iconElement oo-ui-buttonWidget" aria-disabled="false">
  <a class="oo-ui-buttonElement-button" role="button" title="Icon only, framed" tabindex="0" aria-disabled="false" rel="nofollow">
    <span class="oo-ui-iconElement-icon oo-ui-icon-help">Icon only, framed</span>
    <span class="oo-ui-labelElement-label"></span>
    <span class="oo-ui-indicatorElement-indicator"></span>
  </a>
</span>

Instead of altering existing behaviour with adding DOM text nodes to the labelElement-label when there's no label and having to care about 1000+ possibly breaking use cases we would provide a safe, forward-thinking ability to devs who upgrade to the latest version of OOUI.

Change 431653 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[oojs/ui@master] FieldLayout: Provide label to help PopupButtonWidget

https://gerrit.wikimedia.org/r/431653

Change 431653 merged by jenkins-bot:
[oojs/ui@master] FieldLayout: Provide label to 'help' PopupButtonWidget in JS

https://gerrit.wikimedia.org/r/431653

Another small idea, with big impact:
Instead of adding a label element to SelectFileWidget and hiding it at high code complexity, let's just transform the button that is already encapsulating the file input into a label itself.
@Mooeypoo helped in a free minute with executing this.

Change 470720 had a related patch set uploaded (by Bartosz Dziewoński; owner: Bartosz Dziewoński):
[oojs/ui@master] LabelElement: Allow hidden accessibility labels

https://gerrit.wikimedia.org/r/470720

In a longer conversation, @matmarex and myself have been going back and forth to resolve the last remaining part on this task, the icon & indicator only ButtonWidgets.
The crucial parts from my perspective:

• backwards-compatible (not breaking existing code)
• provide clarity and ease-of-use to developers of what to expect when using widgets configuration
• provide labels as often as possible, resolving unclarity to users of assistive technology
• clean markup

@matmarex already provided a forward-thinking, generalized patch set above. Citing his initial commit message:

When given label: '...', hideLabel: true, widgets using LabelElement will look as if no label was given, but the label will be present in the generated DOM/HTML, where it is visible to screen reader software.

This is written with ButtonWidget in mind (and that's the only widget I manually tested), but it should work for other widgets as well.

IconWidget and IndicatorWidget now also mix in LabelElement, with hideLabel: true always set (so they can only have hidden labels).

Custom solution for this in FieldLayout/FieldsetLayout is replaced.

I initially wanted to name this option accessibilityLabel, but then developers would have to learn to spell it. ;)

@matmarex For completion, an option that is not possible due to screen reader & browser support limitations is putting content: attr( title ); on a pseudo element and show it only for screen readers.

Change 470720 merged by jenkins-bot:
[oojs/ui@master] LabelElement: Allow invisible accessibility labels

https://gerrit.wikimedia.org/r/470720

Change 470967 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[mediawiki/core@master] Update OOUI to v0.29.3

https://gerrit.wikimedia.org/r/470967

Change 470967 merged by jenkins-bot:
[mediawiki/core@master] Update OOUI to v0.29.3

https://gerrit.wikimedia.org/r/470967