Making WordPress.org

Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#1814 closed enhancement (fixed)

Style Code Reference ToC links to better indicate interaction

Reported by: kevinwhoffman Owned by: kevinwhoffman
Milestone: Priority: normal
Component: Developer Hub Keywords: has-screenshots ui-feedback has-patch


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.

Attachments (7)

devhub-toc-styles.png (136.8 KB) - added by kevinwhoffman 5 years ago.
Devhub ToC styles
codex-toc-styles.png (205.8 KB) - added by kevinwhoffman 5 years ago.
Codex ToC styles
1814.diff (1.9 KB) - added by DrewAPicture 5 years ago.
1814_before.png (35.1 KB) - added by DrewAPicture 5 years ago.
Before 1814.diff
1814._after.png (35.7 KB) - added by DrewAPicture 5 years ago.
w/ 1814.diff
1814.1.patch (3.6 KB) - added by keesiemeijer 5 years ago.
Display code reference ToC items as links
1814.1-before-and-after.png (117.0 KB) - added by keesiemeijer 5 years ago.
Before and after patch 1814.1

Download all attachments as: .zip

Change History (19)

5 years ago

Devhub ToC styles

5 years ago

Codex ToC styles

#1 @DrewAPicture
5 years ago

  • Owner set to DrewAPicture
  • Status changed from new to accepted

5 years ago

#2 @DrewAPicture
5 years ago

  • Keywords has-patch added

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.

#3 @drewapicture
5 years ago

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.

#4 @drewapicture
5 years ago

In 3650:

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

See #1814.

#5 @kevinwhoffman
5 years ago

@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.

#6 @DrewAPicture
5 years ago

@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.

#7 @kevinwhoffman
5 years ago

@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 ToC.

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.

Last edited 5 years ago by kevinwhoffman (previous) (diff)

This ticket was mentioned in Slack in #meta-devhub by drew. View the logs.

5 years ago

#9 @DrewAPicture
5 years ago

  • Owner changed from DrewAPicture to kevinwhoffman
  • Status changed from accepted to assigned

@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.

#10 @keesiemeijer
5 years ago

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.

5 years ago

Display code reference ToC items as links

5 years ago

Before and after patch 1814.1

#11 @coffee2code
5 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

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.

#12 @coffee2code
5 years ago

In 4903:

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

See #1814.

Note: See TracTickets for help on using tickets.