UI Shell left panel: Usage tab

[laurenmrice]

🔴 This work is being blocked until the Prework is clear (evaluating the priority of the enhancements) in the Epic

Ref discussion: Original issue
Ref boxnote: Usage tab PDF a11y comments

Acceptance criteria

• Update the UI Shell left panel documentation on the website with a11y comments and using the new content template.

Usage tab

Overall page tasks

• Update the Usage tab with the content template.
• Update images to follow our image guidelines.

Overview

• Add "Overview" section.
  • Add "When to use" section
  • Add "When not to use" section if applicable (this is optional)

General Guidance?

• "General Guidance" section could be renamed, but to what? Could this information just follow below the Overview section without a heading?
  • The column header name should be "UI Shell components".
  • There should be a "Purpose" column header for the descriptions.
  • Link out to the other components here.
  • Right panel description needs to be updated to suggest it is non-persistent and include some examples of when a right panel is used in UI.

Live demo

• Add "Live Demo" section.
  • Need the 12 column live demo here.

Formatting

• Add "Formatting" section above "Anatomy section.
• Add "Alignment" section.
  • Could probably discuss here the levels of submenus that can exist in the side panel.
  • Add "Placement" section to mention that the UI Shell left panel does not overlay the UI Shell header, it sits below it.

Content

• Add "Content" section.
  • Add a "Main elements" section and be brief about the expected content for menu and sub-menu item names. The names should be concise and accurately relate to the content shown on the page once you navigate to it.
  • Add "Further guidance" section.

Behaviors

• Should we elaborate more here in the Behaviors section to talk about the different kinds of left navs? like grid influencers/overlays/compact rail, etc.
• Add "States" section underneath the "Behaviors" section.
  • The states section should have a table listing the states and descriptions for them. It should also link out to the style tab.

Interactions

• Add "Interactions" section.
  • Include information for Mouse.
  • Include information for Keyboard.

Clickable areas

• Add "Clickable areas" section.
• Show click target of a menu item when selecting the whole item or expanding/collapsing it.

Modifiers

• Add "Modifiers" section.
• Add a section for adding icons in front of the menu items.

Related

• Add "Related" section.
  • Add UI Shell header and UI Shell right panel in a list here.

Feedback

• Add Feedback section.

[laurenmrice]

Question for a11y:

• There was a question surrounding what do we call items in the UI Shell left panel.
• We currently refer to parent menus that have children as "Sub-menus" and their children as "Sub-menu items. We currently call menus that don't have children as "Links"? Any suggestions of what terminology we want to use here instead?

Feedback

• It was suggested that we do not call these things "Sub-menus" or "Menus", because they technically are not truly menus. The word "Link" can be more appropriate.
• It would be worth looking at other design systems to see what terminology they use for something similar.

To do

• Come up with terminology for these things so we can be consistent with how we are talking about the UI Shell left panel in the website docs, figma kit, and code. After this then we can tackle the docs. This could be determined in this issue: UI Shell: Consistent naming structure for elements #3897