Replace Annotations / Page Notes / Orphans selection tabs with a standard view switcher component

[seanh]

The code in this PR is fully working but it's not final code - if we decide to do this I'll tidy up the code. This PR is for UX discussion.

The sidebar has a set of 2-3 of what our code calls "selection tabs" at the top for switching the view between annotations, page notes and orphans:

(The orphans tab only appears when there are orphans, the other two tabs are there all the time whether there are annotations or page notes or not.)

In my opinion there are some problems with this control:

• The buttons are small and hard to click. Since they're actually just links not buttons you actually have to click on the (small) text itself. This isn't good for accessibility (for people with fine pointer control issues) or for touch or mobile.

• Users may not realise that these are clickable: the buttons don't look like buttons (no rounded rect border and background colour like a button, as opposed to a link, usually has) and they don't look like links either (they aren't blue or purple or underlined like most links on the web).

  These buttons also look different than other buttons (and links) in the sidebar itself.

• Because bold text is used to indicate the currently selected tab, when you click on a different tab the other tabs jump around horizontally (as can be seen in the gif above). Admittedly this one is fixable without completely changing the control.

• It doesn't look like common controllers used in many web and native apps for the same purpose - doesn't look familiar to users, won't be immediately recognisable as this kind of control, users may not immediately realise what it is.

• The use of superscript text to show the number of items in each view doesn't look very good (in my subjective opinion). It's also an unusual way to display the number of items contained in a view, again this won't be familiar or recognisable to users who're used to seeing badges with numbers in them used for this same purpose in many web and native apps. Superscript is usually used to indicate a footnote.

• It uses HTML <a> elements with href="#", which I don't believe is correct for these controllers, which are really buttons not links. They should be <button>s. (Again, this one is fixable without completely changing the control.)

• It generally doesn't look very good (in my subjective opinion)

• It looks odd that it's left-aligned rather than centred (again, my subjective opinion). (Also fixable without completely changing the control.)

  Tabs (where the number of tabs can change dynamically, tabs opening and closing in response to events or user actions, like in a desktop web browser) are normally left aligned. View switchers (which are like tabs except that the set of tabs is fixed and generally doesn't change dynamically) are usually centre-aligned. Here we have a fixed number of buttons that don't expand and contract during use and aren't as wide as the sidebar that contains them - centre-aligned definitely feels right to me.

This pull request changes this control to look more like a typical view switcher control as seen in many web and native apps, and also to look like the buttons used elsewhere in the sidebar itself:

Here's how it look when there aren't any orphans:

I think this is an improvement because:

• It looks better
• The look of the control fits in with / is consistent with the rest of the controls in the sidebar
• It is more familiar and recognisable to users
• The buttons are easier to hit, especially on mobile

Prior Art (!)

I think one of the main advantages of this change is that the controller should be familiar and recognisable to users based on similar-looking standard controllers that are used for this same purpose on most web and native app platforms and toolkits.

I think the fact that this is a common, standard type of control also backs up the argument that it looks better and is easier to use (e.g. easier to touch or click on).

Examples:

View switchers in the GNOME HIG:

In iOS this is called a segmented control:

In macOS these seem to be called tab views:

Bootstrap calls it a button group:

Design Notes

• The buttons are designed to look like other buttons on the sidebar. Same background colour, same border thickness and colour, same rounded corners, same drop shadow, same height.
  

• When you hover over a button it looks as it will like after you click on it / as the currently clicked button looks. Helps to hint at that it is clickable and what clicking it does.

  

• The buttons are vertically aligned with (and the same height as) the button next to it in the bucket bar:

  

  This is unlike the existing controls, which are top-aligned with the bucket bar button but aren't the same height as it:

  

• The first annotation card is now vertically aligned with the top of the next button in the bucket bar:

  

  This also means that the vertical gap between the new buttons and the first annotation is the same height as the gap between the two buttons in the bucket bar.

  Again, this is not aligned in the current design:

  

• This vertical alignment does mean that the vertical gap above the new view switcher (between the top bar and the view switcher) is larger than the gap below the view switcher (down to the first annotation). Unfortunately you can't have everything aligned on a grid (without tweaking positions of existing components in the sidebar first).

  

• It is centre-aligned, as these controls usually are (see examples above)

• The buttons are all same width, even though the text labels are not the same length. They remain the same width with or without a count number showing as well. This just looks better.

• The buttons remain the same width when selected and when not selected, so things don't jump around when you click on them:

  

  In the current design they jump around:

  

[sean-roberts]

👍

This is great, imo. Something to be aware of is, the way our tabs work now (floating) works well with a grey background. But since our background is now brandable, it does not play well with other colors. Specifically, eLife explicitly called out that the tabs are awkward with their white background. The team on our side agreed. This addresses that problem as the centered button group makes less assumptions about the background and would play better with branding. +1 on this for me

[seanh]

It's a separate issue but a further improvement that these buttons might enable is that you can show notifications inside the buttons.

Currently when new real-time annotations (or page notes or orphans) are received through the websocket, we show a somewhat mysterious icon in the top bar:

The icon has a tooltip that reads "Show 23 new/updated annotation(s)".

Some problems with this might be:

1. Not immediately obvious what the icon means or does, without the tooltip (which doesn't work on mobile). When you click on the icon it just disappears so it may still not be clear what it did.

2. When you click on the icon you don't know whether the new things went into the annotations, page notes or orphans tab. (I believe the count numbers on the tabs change, but this is easy to miss.)

3. Even if you guess correctly which tab the new annotations went into, if there are a lot of annotations you can't find them.

With the buttons in this PR we can show the number of new annotations, page notes or orphans in the relevant button instead:

If there were new annotations and new page notes you'd see a number badge on both tabs. We could also use the same refresh icon that we use currently, instead of a number badge.

I'd argue this fixes problem 1, I think a number (2) badge inside an Annotations button is more likely to be understood as "2 new annotations" because the number is right next to the label Annotations and is where the count of annotations normally appears. We can still keep the tooltip as well of course. Badges like this are also typically used to indicate a number of new items (e.g. in email apps, feed readers, etc) so I think familiar and recognisable.

It solves 2 as well.

It doesn't immediately solve 3 although we may be able to address that - when you switch to a tab that has new annotations, or click on the button to show new annotations in the current tab, then it could also change the ordering of annotations in the sidebar to show the most recent ones at the top (and it could even highlight which ones are new for a sec).

If you have to click on the badge in order to actually show the new items, then a possible problem might be that, if the new items are in the currently focused tab, people don't realise they can click on it. (If the new items are in one of the other tabs, they should be shown as soon as the user clicks over to that tab, i.e. they don't have to actually click on the badge.) I think this issue is fixable though. (For example if the new items are in the current tab, then we add an additional "Show 2 new annotations" button underneath the view switcher control.)

PS clicking anywhere on the tab's button would move to that tab, if you're not on it already, and show any new items in that tab, you wouldn't have to click on a small icon anymore.

[segdeha]

I love a) the initiative you're taking by addressing this, b) your thoughtful approach, and c) your thorough documentation of both your solution and rationale. Nice work!

[robertknight]

Thanks for taking the initiative and the detailed write-up 🙂. I've left a bunch of annotations on specific details. Some quick general thoughts:

• I agree with some of the issues you've identified with the existing design: Small hit target for the buttons, it possibly being non-obvious that controls are tabs, labels jumping around when changing selected tab.
• The proposal looks like a pretty good stab at addressing those. It does seem influenced quite strongly by GNOME / macOS / iOS notions of what a tab control should look like. That's reasonable on its own but I'm not certain that it fully fits in with the most recent design direction for the sidebar, starting from the work Conor began last year which @sheetaluk implemented. That design has tended to be flatter and cleaner.

One way forward would be to put this behind a feature flag so we can let other people try it out. The dumbest way to do that is probably just to copy and paste the <selection-tabs> component's code into a set of files with a new name. In the container of the component you can then just conditionally display the existing or revised version. As we're not going to keep both versions in the tree for very long, you don't need to worry that much about de-duplicating the code.

[seanh]

I'm not certain that it fully fits in with the most recent design direction for the sidebar, starting from the work Conor began last year which @sheetaluk implemented. That design has tended to be flatter and cleaner.

Hmm. I could do a version of this component that's based on the style of newer buttons like the Post button on annotations or the buttons on the new website forms, see how that looks. My guess is it might look odd as it won't match with and may not vertically align with the old-style top bar, Hide Highlights and New Page Note buttons that are next to it. This component isn't near to or usually shown at the same time as the Post button or the website forms.

[ajpeddakotla]

@seanh while I love the proactive design upgrade you've thought of here, I think we should wait on implementing this feature, until our new designer comes onboard. I think Dawa will have a lot to say about how she might want to change the look/feel of the sidebar and its various elements. So let's hold off and give her a chance to get her feet under her and decide on design choices like this.

[seanh]

As suggested by @robertknight here's a version based on the flatter and cleaner look of more recent buttons designed by Conor:

I remembered that we do actually have a couple of new-style buttons that sometimes appear in this area of the sidebar, so I based this on those:

(Different colours, bold font, no drop-shadow, no different-coloured border on the selected button, smaller border radius at the corners.)

I also added a 100ms fade transition when a tab is selected / unselected (noticed iOS has this).

This is also more similar to recent versions of iOS (see the iOS gif above): background of unselected tabs is transparent / same colour as background behind them; text colour of unselected tabs is same colour as background colour of selected tab; text colour reverses when tab is selected; unselected tabs have a 1px border the same colour as the background of the selected tab,

Here's an alternative, more minimal version as well:

(Although this version might not solve the branding problem @sean-roberts mentioned, whereas I think the other version do.)

While doing this I noticed that, although I said I didn't think new-style buttons would line up vertically with the old-style buttons next to it in the bucket bar, they actually do for this view switcher control - the new-style buttons (at least some of them) are the same height as the old ones. There do seem to be alignment issues with the other buttons though...

And here's some screens of the vertical height / alignment issues with the new-style buttons and the old ones in the top bar. I haven't looked too closely, it may be the presence of a drop-shadow and border on the leftmost button that's throwing the alignment off. Or the buttons may be slightly different heights or just vertically positioned differently. These look like possible implementation mistakes rather than deliberate design choices, could be easy fixes:

[seanh]

I'm going to close this, think it's served for the purpose of discussion for now

[sean-roberts]

Perhaps you should consolidate all of your work into a ticket that could have the discussion continued - if it isn't already consolidated?

[seanh]

I've created three tickets for the issues identified here:

hypothesis/product-backlog#325
hypothesis/product-backlog#326
hypothesis/product-backlog#327

Possible design improvement low-hanging fruit, I think.

[dawachan]

Great level of detail particularly the design rationale behind updating the UX. Definitely onboard with this update. Have a few questions about orphans, how this model scales, if we have sub levels of annotations etc. This improved tab switcher will definitely make it easier to display subfolders of annotations if it exists.. Looking forward to discussing shortly!

[dawachan]

Identified minor areas of to improve in today's discussion:

- Adjust spacing between count and tab name.
Reduce to 1-2 chars, makes it feel more connected/natural spacing (try 1 character between tab name and count)

- Tab width dynamic.
Tab width varies and is dependent on tab word size, padding is consistent between text + tab border across all tabs.

- Possible future features + scalability.
Dawa to investigate how it might scale if we have more tabs (e.g. if tabs are dynamic/user created or nested tabs under the static parent.) Looking at the current UX improvements proposed, it does appear more scalable than the current UI.

[seanh]

Closing in favour of #465