Page MenuHomePhabricator

[SPIKE 10hrs] Build new header within the Vector skin
Open, HighPublic

Description

Background

We decided that a good way to explore the vector codebase is to begin with building a throwaway feature that we can later remove or iterate on. This is our first attempt at doing this

Acceptance criteria

Build the new header within the vector skin

  • must be feature flagged

Design


as in: https://wikipedia-vue-protoype.netlify.com/en/wiki/moon (without the collapsible sidebar)

Questions we'd like to answer

  • What did you wish you'd known before you started working on this ?
  • What were the main difficulties did you run into while trying to maintain the existing Vector?
  • What small improvements could be made beforehand that would have made hacking on this easier?
  • What code smells did you encounter while hacking on this that should be discussed as a group?
  • What issues with caching (if any) did you run into?
  • Do you have any recommendations on how to split up the code to support working on the new mode and the existing mode?

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptNov 7 2019, 12:39 PM
ovasileva triaged this task as High priority.Nov 7 2019, 12:40 PM

@alexhollender - do you have a mock of the header with the puzzle globe but without the collapsible sidebar?

alexhollender updated the task description. (Show Details)Nov 7 2019, 5:11 PM
Jdlrobson updated the task description. (Show Details)Wed, Nov 13, 6:16 PM
Jdlrobson updated the task description. (Show Details)
ovasileva renamed this task from [SPIKE] Build new header within the vector skin to [SPIKE 10hrs] Build new header within the vector skin.Wed, Nov 13, 6:20 PM

Currently in the Vector skin, the header HTML, (along with the sidebar & other navigation) are placed below the content. (The header is made to look like it is above the content with CSS).
My understanding is that this was done for performance purposes - so that page content loads first, as well as for accessibility reasons - so that page content is the first thing presented to screen-readers.

I'm interesting in input from the performance team (ping: @Krinkle) as to whether or not we should continue this practice of placing the navigation below the content, or if best-practices have changed since then.

(I can imagine that a metric like first-paint might be delayed by having the header be the last thing rendered in the viewport).

We also had a conversation about DOM order during our offsite in regards to accessibility. My intuition says that rendering the content first, as Vector currently does, makes life easier for screen-readers & assistive tech, since they don't have to skip through the navigation to get to the content.

However, @nray mentioned this WebAIM article https://webaim.org/techniques/skipnav/#altorders which suggests that the "skip to navigation" links Vector employs are unusual, and could therefore be confusing. Given that, I'm open to placing the header above the content. On a related note, @Volker_E mentioned on slack that we should use the semantic <header> <nav> and <main> elements going forward distinguish these "landmarks" for assistive tech (I was personally surprised we don't do this already).

To be precise, I've referred to ARIA landmark roles, which could also be put on div elements equivalent to current master, for example on <div id="content" class="mw-body" role="main">.

It's highly recommended to put the most important elements first, in our case

  1. site logo/branding for identification
  2. content
  3. navigation

and accompanied by skip link(s).
The reason for this order is, we are not a normal business website, with our navigation featuring the information architecture sectional entrance points to our contents. So we don't rely on our navigation to understand or browse our content.

Volker_E renamed this task from [SPIKE 10hrs] Build new header within the vector skin to [SPIKE 10hrs] Build new header within the Vector skin.Wed, Nov 27, 5:05 PM

The re-ordering of the sidebar HTML is imho uncontroversial and something I planned to do as part of T231168 "very soon". It's mainly blocked on someone (maybe me) doing some speed-tests to confirm the hypothesis and then "Just do it".

The current order is inherited from Monobook and was originally motivated by a vague SEO rationale if I recall correctly. Given our existing skip links, I had not considered this to be an accessibility concern. However, that indeed does make the change a little less trivial because our skip links are currently positioned in the content area. Which is unusual but makes sense because unlike most sites our skip links aren't for getting to the content but for getting to the navigation. We'd have to place these higher up as well and decide how/where to style them, and then inverse their relation and/or add a third one (Jump to content, navigation, or search) instead of (Jump to navigation, or search).

@Volker_E Would that be acceptable? If not, do you have other suggestions or requirements for how to accomodate that HTML order?

Jdrewniak claimed this task.Tue, Dec 3, 1:48 PM

Although this task sets out to actually try and build a new "throwaway" header, I've identified some ground-work that has to happen before we can even begin building a new header:

  • T237635 What mechanism do we use to swap out the old header for the new one?
  • T239248 In order to be "swappable", the header has to be componentized instead of just echo'ed out as it currently is.
  • The best DOM order (convo started above) should be established to accommodate performance and a11y.
  • The ResourceLoader & configuration for the logo has to be considered. As of 546733, the skin.styles ResourceLoader module has been split out into "features". We will have to treat the logo differently than the $wgLogo config option.
  • A conversation with Performance needs to happen to determine what's the best way of placing the logo (css vs. img tag).
  • A strategy for generating new logos or updating existing ones has to be considered as well as it's implications across projects. Wikipedia is ~300 logos, but that times 12 projects? Also the third-party implications.

From the list above, I'd say just changing the logo seems like an epic to me 🙈 but more might be uncovered while building a "throwaway" header.

Everything should be assumed an epic... at least while we get up and running :) This sounds like a good list. would it be to premature to carve out tasks for all of the ones we're missing?

The ResourceLoader & configuration for the logo has to be considered. As of 546733, the skin.styles ResourceLoader module has been split out into "features". We will have to treat the logo differently than the $wgLogo config option.
A strategy for generating new logos or updating existing ones has to be considered as well as it's implications across projects. Wikipedia is ~300 logos, but that times 12 projects? Also the third-party implications.

I started poking at these 2 issues in https://gerrit.wikimedia.org/r/551668 but haven't setup a task yet but I agree this is a task in itself.

Adding on to discussions above, (re-)defining DOM structure is carved out into T240489.