Style Code Reference ToC links to better indicate interaction

[kevinwhoffman]

The devhub ToC links have black text with no hover effect beyond the default browser cursor change. I'm suggesting that the links are styled similarly to the Codex ToC links which provide :link, :hover, and :visited styles. Screenshots attached.

[kevinwhoffman]

Devhub ToC styles

[kevinwhoffman]

Codex ToC styles

[DrewAPicture]

Before 1814.diff​

[DrewAPicture]

w/ 1814.diff​

[DrewAPicture]

1814.diff​ adds hover styles to the ToC in the Code Reference and slightly tightens up the un-ordered lists.

We don't really use :visited styles anywhere else on DevHub so for now I'd rather not add them in lieu of a design review. Hover styles now with possible :visited styles later would be the best short term fix, imo. See 1814._after.png​.

[drewapicture]

In 3649:

developer.wordpress.org: Add hover styles to table of contents links in Code Reference pages.

Also slightly tightens up unordered lists within the ToC.

h/t kevinwhoffman.

See #1814.

[drewapicture]

In 3650:

developer.wordpress.org: Bump stylesheet following [3649].

See #1814.

[kevinwhoffman]

@drewapicture Hover styles look good. What about using blue for the default :link state? There's still no visual indication that those are clickable links until hovering, which you can't do on touch devices.

[DrewAPicture]

@kevinwhoffman I think the purpose of a table of contents on DevHub just as with handbooks is fairly self-explanatory - it's a list of jump links.

Whether the links are initially blue or black is not really the problem, in my opinion. For that matter, we're using slightly modified -- but basically the same -- styles as the handbooks and to my knowledge there have never been complaints about not realizing they were links.

Also for what it's worth, when I clicked them on an android device, the hover styles were triggered.

[kevinwhoffman]

@drewapicture Forgive me for getting a little nitpicky with my designer hat on.

Affordance is a web design principle in which characteristics imply an action. In other words, elements that are clickable should look clickable, regardless of whether you can deduce their purpose based on their surroundings (such as within a ToC). For hyperlinks, that usually means styling them differently through font-color, font-style, or underlining them and adding a hover style to further imply interaction.

Most mobile devices will flash the hover style when tapped, but that's not the point. The user has already initiated the action. Affordance is about suggesting action before the action itself takes place. And right now, there is still nothing outside of their presence within a ToC that indicates these are links because they look exactly like the content text.

I get what you're saying that a reasonable person can figure out they are links. I'm less concerned about this specific ToC scenario than I am about how this is being handled throughout the rest of Devhub, especially when it seems like a step backwards compared to the UI of the Codex.

I was asking in Slack if a style guide is available to guide these decisions. If you know of one or are interested in starting one, let me know.

[DrewAPicture]

@kevinwhoffman Would you like to pick up this ticket and perhaps work further with @hugobaeta to come to some consensus on how TOCs should generally fit into the design make-up of .org? Many of the DevHub TOC styles are inherited from the standard handbook styles.

See also #1825 where handbooks are being styled inline with O2.

[keesiemeijer]

In the context of the handbooks it's more obvious (to me) that the TOC items are linked chapters in a book. The items are also made up of sentences instead of just words like 'Parameters' or 'Source'. By displaying the ToC items from the code reference as links you get an instant clue what the highlighted section might do (when looking at it at a glance).

The ToC items are the same for all parsed post types and only link to sections within the page itself. This makes the title "Table of Contents" seem a bit off. We could rename it to "Contents" like in the screenshots of @kevinwhoffman or leave it off completely.

[keesiemeijer]

Display code reference ToC items as links

[keesiemeijer]

Before and after patch 1814.1

[coffee2code]

In 4902:

developer.wordpress.org: Display code reference table of contents items as links.

Also minor ToC box style tweaks and renaming to "Contents".

Props keesiemeijer, kevinwhoffman.
Fixes #1814.

[coffee2code]

In 4903:

developer.wordpress.org: Extend code reference "Contents" link styling to handbook "Topics".

See #1814.