UI Shell: Consistent naming structure for elements

[lesnider]

Acceptance criteria

• Writers need to know how to refer to UI elements when they write documentation.
• Content guidelines are needed for naming UI elements (main menu, in-page menus, hamburger menu...)

Tasks

• Align on terminology that we want to use to label the anatomy parts of our Shell. (I am sure a11y has recommendations for this as well.)
• Look into what best practice naming is for these things in the industry.
• Playback

---

Relevant information

For example, should we call the menu on the left shown here the "main menu" because it leads users throughout the product and the in-page menu that leads users within that page the "page menu"?

IBM Style calls the "main menu" the navigation tree. However, "tree" might have a different functional meaning.

Note: IBM Terminology says not to use navigation as a noun

https://carbondesignsystem.com/guidelines/icons/library/ shows the menu icon, but writers don’t know what to call this.

• Do Carbon-compliant products use the hamburger-styled menu or the > expand/< collapse menu approach on their home pages? Shouldn’t we be consistent?

• What should we call this menu? Is it the main menu?

See a detailed discussion in https://ibm-cloud.slack.com/archives/C0M053VPT/p1706712766009609.

Related issue: #3235

[thyhmdo]

Note for Issue sizing: We need to clean up other related issues and link up with this issue for clearer action items.

[mbgower]

I've flagged some of these considerations before, which have ramifications for accessibility, based on the role they are assigned. I'll try to reference some of the issues I've opened.

[thyhmdo]

CAG call with Mike Gower and the team 11/18

Naming doc

• Accessibility: Left and right could be mistaken for universal RTL
• Guidance: Provide a general visual for areas + break down individual components within each area
• Cloud Pal: It could be level 1,2,3 instead of specified names that are only targeted to their users
• Look into the Switch panel (Carbon) vs the Side panel (triggered from the page)

[thyhmdo]

Call with designers 11/20

Two directions:

• Keep the current UI shell components and suggest better names for the left and right panels. Including a Pattern for Navigation, in general, could also help.
• Include other navigation components from other libraries and consider naming based on levels of navigation

---

Research summary

• Top: Across the board, the name Header sounds right. Could be global header
• Left: Side navigation coming from the left side, usually triggered by the hamburger menu
• Right: Carbon is unique with the Switcher panel that extends top to bottom, others (internal) have Side panels. External systems call it Drawer, or Tray sometimes.

---

Moved it to Backlog because this work will be transitioned to another work group.