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/visible when you click on a link in the table of contents? Why does it just instantly jump to the section?
 
 * 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.