Handbooks: Improve menus design

[felipeloureirosantos]

The menus are not really clear, and that is something that really could be improved.

I put some CSS just to make it easier, and it has got really better, but it would be nice if we could have a professional design proposal on it.

.menu-table-of-contents-container ul ul{
      border-left: 6px solid #0073aa;
      margin-left: 6px;
}

.menu-table-of-contents-container ul ul ul{
      border-left: 6px solid #0073aa;
      margin-left: 2px;
}

[felipeloureirosantos]

Before

[felipeloureirosantos]

After

[dufresnesteven]

Yeah, I agree. It's pretty hard to understand the hierarchy. For me the borders seem unnecessary. Here's another option:

[dufresnesteven]

I also think having the 'arrows' on the right is troubling because usually they help to define hierarchy but on the right they don't support that function and just identify whether the section is open and closed.

[felipeloureirosantos]

Thank for the contribution! :)

I agree that the border is not great. We would still need to create a better hierarchy.

About putting the arrows on the left side, I don't think that it would fix the problem because some of the navigation items don't have descendent items (like 'Filesystem' from your image), so these items wouldn't have the arrow and the hierarchy problem would be the same.

[felipeloureirosantos]

Something that could be great is structuring elements to be numbered sequentially like in the ​WBS coding scheme.

[dufresnesteven]

Here is how Microsoft does it for their Fabric UI documentation.

[coffee2code]

In 9412:

Developer: Improve handbook sidebar menu design.

• Eliminate per-item top/bottom borders.
• Use WCAG-compliant color (as used for links) for left border
• Increase thickness of left border for menu sub-items.

Props felipeloureirosantos, dufresnesteven, coffee2code.
See #4901.

[coffee2code]

In 9413:

Developer: Fix alignment of same-depth menu items in handbook sidebar.

See #4901.

[coffee2code]

I've introduced a bit of a compromise to the two proposals above. I removed all but the left borders, so that reduces some of the visual clutter in the menu while providing a visual indicator of hierarchy in addition to indentation.

Bear in mind the changes have currently only been applied to the handbooks on ​https://developer.wordpress.org and not to the team P2 handbooks.

Thoughts on these changes?

Replying to felipeloureirosantos:

Something that could be great is structuring elements to be numbered sequentially...

I would be against numbering menu items for two reasons:

1. The handbooks are constantly in flux. Numbering each menu item would produce a means of referring to a given item, e.g. "click on 4.2.2", which could quite easily change.
2. The current screen width devoted to the menu can be tight in some cases, especially long names nested in the hierarchy, which would be the ones most affected by having numbering prepended to them.

Replying to dufresnesteven:

I also think having the 'arrows' on the right is troubling because usually they help to define hierarchy but on the right they don't support that function and just identify whether the section is open and closed.

To be fair, the intent of the arrows was never to indicate hierarchy at all, simply to indicate the item has subchildren and to toggle the display of the sub-children (with the arrow indicating if they are currently expanded or not). For the same reason given above (#2), I'm not in favor of moving the arrows to the left—they'd require more horizontal space for display and menu name alignment, and we don't have the space to spare in the current design.

[felipeloureirosantos]

That's great, thank you! I believe that it fixes the hierarchy problem, and I personally think that it was the biggest matter here.

I can understand the problem numbering menu items now, I have not considered these factors before.

[felipeloureirosantos]

@coffee2code do you think that we could also have it on p2 (including local sites) handbooks?

[coffee2code]

@felipeloureirosantos: Indeed. I'm in the midst of making a few more menu-related tweaks and then I'll sync the changes to the P2 handbooks.

[felipeloureirosantos]

Thank you for that awesome work!!! :)

[coffee2code]

In 9428:

Developer theme: More handbook sidebar menu design improvements.

• Decrease padding-right for menu items which do not have children
• Embolden the name of the current page in the menu

Props rilwis, coffee2code.
See #4901, #4467.

[coffee2code]

In 9430:

Breathe theme: Improve handbook sidebar menu design.

• Eliminate per-item top/bottom borders
• Use WCAG-compliant color (as used for links) for left border
• Increase thickness of left border for menu sub-items
• Reduce padding-left to align widget title with leftmost text within widget
• Decrease padding-right for menu items which do not have subchildren
• Embolden the name of the current page in the menu

Props rilwis, felipeloureirosantos, dufresnesteven, coffee2code.
Fixes #4901, #4467.