Skin:Vector/2022/Design documentation

Vector 2022 was initially designed and developed by the Readers Web Team, starting in 2020. This page aims to provide rationales behind the various design decisions of Vector 2022, with the intended purpose of helping future designers (and developers) of the skin make informed decisions in the future.

1) Why is the table of contents next to the article (vs. inline)?
  
 * Rationale: the table of contents is located next to the article so that you can see it immediately when you land on the page. The table of contents is a critical reading element, allowing people to understand the contents of the page, and easily navigate between different sections. Therefore it is important for it to be easily discovered at the top of the page. In Legacy Vector the table of contents is inline, below the lead section, which means that sometimes when you land on the page you can't see the table of contents at all without scrolling (depending on the length of the lead section and the width of your screen).


 * Tradeoffs:
 * Since the table of contents is now displayed in a more narrow space, long section titles wrap (making it more difficult to read them). There is also less room for indentations, which makes it more difficult to differentiate between the various levels of headings (more on this below).
 * Some people who have been using Wikipedia for a long time have observed that it feels weird to no longer have a gap or separation between the lead section and the rest of the article, which the table of contents previously provided.
 * Follow-up questions:
 * Can it be inline, and then once you’ve scrolled past the inline one, a sticky one appears somewhere? Did you try that?
 * This would mean it isn’t available immediately when you land on the page, which means it wouldn't meet the main design goal. Additionally, it's important to have the table of contents available throughout the entire page, so it can be accessed at any time. If it was inline, there would have to be a second version of it that appeared once you had scrolled past the inline would. This would add significant complexity to the website experience, because instead of just being in one place all the time, the position would change depending on where you were on the page.
 * Prototypes: we did try this approach during our initial testing: version 1, version 2, version 3

2) Why are sub-sections collapsed by default?
  
 * Rationale: sometimes, when an article has many sections and sub-sections, the table of contents is very tall, and you are unable to see the entirething without scrolling the page. Sub-sections are collapsed by default for articles with more than 28 sections total. This is done in order to make it so that (in most cases) you can see all top-level sections within the table of contents without scrolling. This allows you to quickly learn the contents of the entire page, at a high-level.

 
 * Tradeoffs: you have to click the arrows next to the parent sections in order to see the sub-sections (note: you can also click the parent section link, which will both navigate you to that section, and open the sub-sections).
 * Prototype: exploring the option of a "Expand all sections" button: https://di-toc-expand-collapse-all.web.app/Mount_Fuji
 * Follow-up questions:
 * When you scroll to a section that has collapsed sub-sections, why don’t the sub-sections automatically expand?
 * Automatically expanding and collapsing sections in the table of contents can be distracting if you are focused on reading (rather than scanning/navigating). The distraction is even greater when sections with many sub-sections automatically expand, causing a scrollbar to appear in the table of contents, and when moving between a section with many sub-sections, and a section with few sub-sections (note: scrollbar visibility varies based on your operating system settings).
 * Some people have experienced the automatic expanding of sub-sections to be very convenient, and prefer it to having to click on the arrows next to the parent sections in order to see the sub-sections. We discussed making this a setting.
 * Prototype: sub-sections automatically expanding: https://di-toc-section-auto-expand.web.app/The_Moon

3) Why does the table of contents remain on the screen as you scroll down the page?

 * Rationale: The table of contents is a critical reading element, allowing people to understand the contents of the page, and easily navigate between different sections. Data shows that people sometimes use the table of contents multiple times when reading an article, and because Wikipedia articles can be very long, it is inconvenient to return to the top of the page each time you want to use it. Additionally, people find it implicitly helpful to know where they are within the article as they are exploring it.
 * Data: the sticky table of contents results in people exploring articles more extensively.

4) Why isn't the scrolling animated when you click on a link in the table of contents?
 
 * Rationale: animating the scroll results in too much motion on the page as you are navigating between sections. This is exaggerated on long pages.
 * Tradeoff: some people prefer the animated scroll as it indicates the direction you are moving (up vs. down), and provides a sort of quick glimpse of the parts of the page you are moving past.
 * Prototype: allows you to choose "instant jump" or "animated scroll": https://di-toc-instant-animated.web.app/China

5) Why doesn’t the table of contents hide/collapse in place?
   
 * Rationale: hiding/collapsing in place takes up horizontal space next to the article. Assuming that people on smaller screens are sometimes hiding the table of contents in order to gain additional space for the article, collapsing it into the article title gives them the most additional space back.
 * Tradeoffs: some people might have difficulty figuring out where the table of contents has gone (note: this change should help with that). Also, this pattern is inconsistent with other, similar collapsible elements, which means it might be unexpected for more experienced users.
 * Comments: further exploration of collapsing the table of contents in place as an icon would be worthwhile. Especially considering that when you are logged-out, and collapse the table of contents, then scroll down the page, it persists as a floating icon.

6) Why is the table of contents hidden sometimes?

 * Comments: this should no longer be the case. Originally we were following the pattern from Legacy Vector, where the table of contents is hidden automatically on articles with less than 4 sections. However to provide a more consistent experience Vector 2022 shows the table of contents on all pages (link).

7) Why isn’t there more indentation between h2s, h3s, etc.?

 * Rationale: to avoid excessive line-wrapping for the section titles (which makes them more difficult to read).
 * Tradeoffs: more difficult to differentiate levels of headings. This is less of an issue between h2s and h3s, because h2s have a toggle icon next to them. More of an issue between h3s and h4s, etc.
 * Comments: increasing the padding from 8px to 12px would help with this. A different approach: some kind of guiding lines that appear when you hover over the table of contents:
 * Follow-up questions:
 * 1) In Legacy Vector the sections in the table of contents are numbered, why have the numbers been removed?
 * The numbers add unnecessary visual noise while taking up valuable space (which in Vector 2022 is limited for the table of contents). Additionally, a strong case for the numbering of table of contents sections has yet to be articulated.
 * 2) When you uncollapse an h2 in the table of contents, all subsequent headings (h3s, h4s, etc.) are shown. Why is this? Why don't the h4s remain hidden under a collapsable h3 heading, etc.?
 * The reason for making h2s into toggle-able elements that can hide their children headings is so that for long articles with many sections, you can see all top-level sections within the table of contents without scrolling. This allows you to quickly learn the contents of the entire page, at a high-level. Adding this capability for h3s, h4s, etc. would increase the complexity of the interface without adding value. Additionally, given the distribution of heading levels there would be diminishing returns for each additional level of nesting.

8) Why does the main menu appear above the table of contents when it’s pinned?

 * Rationale: global navigation and personal tools are located in the site header, and page navigation and page tools are located in the article header, article toolbar, and article sidebars. The main menu contains global navigation and is therefore located in the site header by default. For some people, and some Wiki projects, there is a need to pin the main menu so it remains visible at all times. To keep it as close as possible to the site header (where it "lives"), it gets pinned above the table of contents (otherwise it would have to sort of jump over the table of contents, and be pinned below it). Additionally, because the table of contents is sticky and can be taller than the screen, it would be more complicated to have the main menu pinned below it.
 * Tradeoffs: for people/projects where the main menu is pinned, it pushes the table of contents further down the page.

9) Why isn't the "top" link sticky?

 * Rationale: the table of contents will rarely be very long, therefore it's easy enough to scroll it to the top in order to access the "top" link.
 * Comments: outside of some additional code complexity there isn't a downside to enabling this. Worth looking into further.
 * Prototype:

10) Why doesn’t the table of contents use a thinner, custom scrollbar?

 * Comment: we have not had time to explore this. Worth looking into further (note: scrollbar styling varies between operating systems, browsers, and settings).

1) Why is the article width limited to 960px?

 * Rationale: the article width is limited in order to improve the reading experience. Long lines of text are more difficult for most people to read (link to research). The Web Content Accessibility Guidelines suggest a maximum of 80 characters per line (link). However Vector 2022 allows for slightly more, in an attempt to accommodate scanning, in addition to focused reading.
 * Tradeoffs:
 * Longer page, more scrolling
 * Worse for wide tables and other wide content
 * For people who have been using Wikipedia with large screens, the formatting/layouts of some articles is now different, sometimes in ways that they don't like. However, it's important to keep in mind that the formatting/layouts that they are now seeing were already occurring in Legacy Vector for people with smaller screens. Editors should be mindful of the fact that people read Wikipedia on a variety of different screen sizes, and therefore should not be optimizing for any one particular size.
 * Comments: this was the most debated change by far. Most of the opposition seemed to be resistance to change, plain and simple (rather than concerns about usability). This is the biggest change Vector 2022 introduced, so it’s inherently uncomfortable for people who have been using Wikipedia for a long time. Secondly, some people prefer reading longer longes. Thirdly, a side-effect of limiting the article width is that there is white/empty space on either side of it. While not necessarily opposed to shorter line-lengths, some people were indirectly opposed to the change because of this side-effect (which was undesirable to them).
 * Follow-up questions:
 * 1) Why don’t you just leave it up to people to adjust their browser size?
 * It is important that the majority of people have the best possible reading experience by default (i.e. when they first land on the page). Many people may not be aware of the negative effects that long line-lengths have on their reading experience, and therefore may not think to adjust their browser width. For people who want more control over the article width, they can use the full-width toggle/setting, and then adjust their browser width accordingly.
 * 2) How do you know for certain that this is a better reading experience?
 * Short answer: we don't know this for certain, however we have a lot of confidence. The existing research studies line lengths within the 35–125 characters per line (cpl) range, therefore we don't have direct evidence that 200 cpl (or more) is problematic. We would like to commission a study comparing line lengths of 100 cpl, 200 cpl, and 300 cpl. Despite not having that direct evidence and certainty, our confidence is high for a number of reasons:
 * Similarly limited line-lengths are ubiquitous across all websites (including non-profit and government websites)
 * Similarly limited line-lengths are ubiquitous across all printed text (magazines, newspapers, books, etc.)
 * We assume that there is a good reason why the fact that all of the research is focused within a narrow range — because that range is the ideal range for readability
 * The WCAG criteria (linked above)
 * Fandom introduced a toggle that allows people to increase the article width, and it is used by ~0.1% of people (link)
 * 3) What about wide tables, images, and other wide content?
 * For people with large screens we have undoubtedly made the situation worse. However, as noted above, wide content was already problematic for people with smaller screens. We need to provide solutions for wide content that work for people regardless of their screen size (e.g. better overflow handling for tables, and/or being able to them in a full-screen mode).

2) Why is there so much empty space? Is that an indication of a bad design? Was the website designed for mobile?

 * Comments: a certain amount of whitespace surrounding text is helpful for reading. It allows your eyes to easily find the edge of the paragraph, and to rest in between lines. Beyond that, because the recommended line-length is a fixed value (rather than a percentage of the screen width) as the screen gets bigger there will be more empty space on both sides of the article. Empty space is not inherently an issue, nor is it an indication that the website was designed for mobile. A good design is not one that fills all available space. Rather a good design is one where each element is appropriately sized. If this results in empty space on larger screens, that's an inconsequential side effect. At the same time, the empty space presents an opportunity. What might we fill this empty space with? For people who prefer longer line lengths they can fill the empty space with article content (i.e. the full-width setting/toggle). Maybe logged-in people would like a list of languages to be displayed in a column next to page tools? We are open to ideas for using the empty space in a way that will provide a lot of value to people, while at the same time being cautious of the fact that each additional element on the page takes focus away from the content, the table of contents, the talk page link, the history link, the edit link, and other critical elements. So it’s a balancing act : )

3) Why are all of the main menu links collapsed for logged-out people (like “About Wikipedia” and “Recent changes”)? Without these links how will people discover pages that show how Wikipedia works?

 * Rationale: firstly this is about increasing the focus on the content, and improving the reading experience by removing clutter. Secondly, less is more. Instead of having many entry points to get "behind the scenes" of Wikipedia, we are focusing on fewer, more guided entry points. This is more approachable for people using the website, and also makes things easier for us, in terms of providing welcoming experiences. It will also allow us to experiment in the future with adding emphasis to different entry points/flows.
 * Tradeoffs: specific links are less discoverable, and require an extra click (to open the menu)
 * Data:

4) Why isn’t Vector 2022 using a grid?
  <p style="border:1px solid #ececec;height:fit-content;box-shadow:2px 4px 8px 0px rgb(0 0 0 / 10%);">
 * Comments: we plan to implement a 24 column grid, but it was out of scope for the initial development.
 * Prototype: https://vector-2022.web.app/Moss