[a11y]: Toggletip documentation changes necessary

[mbgower]

This is an omnibus ticket summarizing key problems with the content of the Usage and Style pages for the Toggletip component. (Specific problems with toggletip implementation are captured in https://github.com/carbon-design-system/carbon/issues/12922.) Detailed considerations, edits and suggestions are captured as comments (by Jess Lin and myself) in pdf exports of the pages: usage.pdf and style.pdf. These documents should be reviewed in detail.

The key considerations are:

Usage

• tooltip and toggletip may potentially work better as a single component (tooltip) and variant (toggletip). It may make it easier to focus on the distictions, and ensure they are used consistently in Carbon

• the focus on popover is distracting to the overall content, and should be played down; I suggest using "tip" as the generic phrase to describe the disclosed panel.

• it may help to use trigger and toggletip (or just tip) when talking about the main parts of the component.

• I have made significant editorial change suggestions to the Usage page. Since it becomes hard to absorb the overall effect in all the edits, I have typically provided a complete rewording on the paragraphs in a single comment at the end of each section.

• in regard to what components a togletip can contain, consider what benefits there may be in ONLY allowing links (and encouraging 1 or at most a few). It could make a much cleaner division between tip interactions and more interactive things like modals, menus, etc.

• I list the following description of the toggletip in a comment in the behaviour section, and I think what's identified here is pretty important to focus on as core messages of the component:

  I think 'open' and 'closed' are better state names for the toggletip than 'active' and 'inactive'. I also don't think the difference between the trigger and the tip are sufficiently discussed. To elaborate, the trigger can get focus. The trigger can be activated. When it is activated, it toggles the tip's visibility on and off. Focus is maintained on the trigger during this toggling. However, users have the option of moving focus into the tip itself (it's not clear to me if the tip itself takes focus, or if only objects in it do; probably the latter, but there are ramifications). The toggletip stays open until focus is no longer on the trigger or the tip's contents. When users tab away from the trigger or out of the tip content, the tip closes.

• focus handling is not really covered well

Style

• there are states shown which are incorrect.
• The description of the component in the Placement section is more successful than other existing content. It departs from much of the terminology used in the existing style and usage material.

[sstrubberg]

• Before starting this, see what comes out of Aubrey's variant work.
• Do Tooltip first, then do Toggletip.