Add note on visually hidden labels

[TylerJDev]

Adds a note on visually hidden labels, that there must be a visual label defined if the label is visually hidden.

Context: https://github.com/github/primer/issues/3441

[TylerJDev]

@primer/accessibility-design - Would love a review on this PR, as I believe we can add this note to other form elements that describe usage of "visually hidden" labels.

[ericwbailey]

What is an example of a rare case? I worry that without defining that everyone will think their use case is the exception to the rule.

[IanPouncey]

I agree with @ericwbailey, more examples would be beneficial.

The most common example is a single field search form, with a magnifying glass icon as the content of the submit button. In this situation, the icon is acting as both the content of the button and the label for the input field.

If an icon is used, it must be unambiguous as to its purpose. From a users point of view, they should be able to say the name of the icon and have voice control software associate the name with the control. To continue the above example, the magnifying glass indicates "search". There are very few other icons that have this same association as they relate to input fields, a few more that could apply to button elements (such as "+" for "add", "plus", or "increase"), so it should be exceedingly rare for an icon to be the only label, whether it is part of the <label> element or not.

If another piece of text is used, the accessible name for the <input> must include, as an unbroken sub-string or as the entire accessible name, the visible text.

[TylerJDev]

Here are a few examples I could think of right now:

• On an issues/PR page, you can edit the title which brings up an input of the existing title as a value. I'm not entirely sure how accessible this is, the context is there when you activate the "edit" button, but once activated, that context is lost.
• GitHub's search query utilizes an input without a visual text label, but contains an icon (magnifying glass). This is mostly the same as @IanPouncey's example.
  • I'd say this is the most common usage of the prop. Inputs for searching files/branches consist of the same pattern, usually accompanied by a placeholder and icon.
• We recommend this pattern in our docs for nested form controls specifically. I'm not too sure how often this pattern is utilized but I'm curious if this approach is accessible, the context seems to be there initially.

We use this prop a lot, so if we want to stop suggesting it entirely we could definitely do so. Thanks too for the input 🙇