Disclosure pattern docs update 🏖️

[laurenmrice]

Update disclosure pattern docs

With the new addition of Menu and Menu buttons documentation on the website, parts of the Disclosure pattern documentation are now outdated and need to be updated with new information to be more accurate.

What is a disclosure pattern, and what isn't?
Let's be more clear with our guidelines around what is considered to be a disclosure pattern.

• For example: A disclosure pattern is something that is always disclosed by the user.
• For example: A disclosure can consist of a trigger + popover OR a trigger + menu. These are considered to be disclosures.
• This pattern should help guide user's to decide which type of disclosure to use for their usecases in product.

We need to determine if this pattern is still needed or if it makes sense to continue to iterate on it.

---

Define rules

Define rules around which components in our system are considered disclosure type patterns and which ones are not.

ARE disclosures: Menus, Dropdowns, Tooltips, and Toggletips

ARE NOT disclosures: Modals, Tearsheets, Megamenus, Accordions, Multi-line Code Snippet, Expandable Tiles, and Notifications.

• We need to explain why these are not considered to be disclosures in our docs. Many reasons for this have to do with displacement and persistence.

Create guidelines

Label treatment

• What is the label treatment of the trigger? Sometimes, the label needs to be explicit above the component that triggers it (like a dropdown), or it could be in a tooltip on hover if it is an icon button. Cover the most common situations for this.

Focus treatment and behavior

• Where does Focus typically go in disclosures, whether on the trigger or within the area that is disclosed to the user?
• Think about if the focus behavior automatically moves into the disclosed area (like menus) or if it needs to manually be moved by the user with a keyboard (like toggletips).

Persistence

• Once information is disclosed, the information persists until the user dismisses it by either clicking on the page or on the trigger again.

Displacement

• Things considered not to be disclosures are usually full-page takeovers like modals or tearsheets, which obscures the disclosure trigger which needs to still be available to dismiss it.
• Things considered not to be disclosures typically push down content when disclosed on the same level of the page instead of overlaying content on a separate layer.

Proximity

• Show the different ways of how the disclosed information, in a popover or menu container, for example, is closely related to the trigger. Sometimes, this could be a no tip, caret tip, or tab tip situation. Explain when to use one over the other.

Tasks

Preview Give feedback

1. Audit and research what types of situations are considered to be disclosures and playback to team
2. Define clear guidelines and rules for disclosures and playback to team
3. Update the disclosure pattern docs on the website
4. Combo button in Disclosure: Audit and update the info accordingly to the Menu buttons docs #3739
   component: combo-button role: design ✏️ type: docs 📖 +3

[laurenmrice]

Related #3739

[laurenmrice]

To unblock this issue:

• Merge Menu docs
• Have an a11y discussion