Page MenuHomePhabricator

[Spike 4hrs] Discuss and agree on nomenclature and rules for template partial usage and CSS organization from experience with header
Closed, ResolvedPublicSpike

Description

Template partial/Stylesheet files that are not components are confusing to quickly get overview

Questions I'd like to find answers for:

[✔️] Should we keep all the legacy stylesheets and templates in a respective 'legacy' folder?
[✔️] Let's break up common.css into manageable chunks. Please input on how that should be done. https://gerrit.wikimedia.org/r/587855
[✔️] After https://gerrit.wikimedia.org/r/#/c/mediawiki/skins/Vector/+/578660/ is merged the master templates are called index.mustache (new) and legacy.mustache (old). Are these names acceptable and meaningful given the split? Should we rename to e.g. 'skin' / 'page' / 'layout' / 'pagelayout' / 'master' / 'root' / 'modern' / 'vector'?

Descoped

The following tasks were originally part of this spike, but given the fact they are not blocking us now and are lower priority they have been broken out into

Results summary of the "collaboration" on the agreed nomenclature

These tasks have reached their final state in May, activity ceased. The subtasks, including related changes:
Completion - Proposer - Subtask format

  1. Jdlrobson - keep legacy stylesheets and templates in a respective 'legacy' folder
  2. Jdlrobson - break up 'common.css' into manageable chunks (patch 587855): content.less, print.less, typography.less
  3. Volker - extract 'normalize.less' (patch 604939)
  4. Volker - T257145 rename 'variables.less' to 'vector.variables.less' (patch 603660)
  5. Demian - T253669 split 'content.mustache' from 'skin.mustache' and 'legacy/content.mustache' from 'skin-legacy.mustache' (patch 585625)
  6. Demian - add .mw-tabs (or similar) class to #mw-head
  7. Demian - (not important) split #mw-head from 'index.mustache' and 'legacy.mustache' into the reusable 'Tabs.mustache' (patch 585626)
  8. Jdlrobson - add .vector-menu-tabs class to #left-navigation and #right-navigation (T249372, patch 595001)
  9. Jdlrobson - epic menu templating code refactor (T249372)
  10. Volker - rename 'index.mustache' (only the template) to 'skin.mustache' (patch 596512)
  11. Jdlrobson - rename 'watchstar-ie8.less' to 'TabWatchstarLink.less' (patch 587855)
Related tasks running in parallel:

T249372: [Dev] DRY up the menu templating code
T246170: Build new logo for Desktop Improvements Header

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
Jdlrobson renamed this task from [Spike] Discuss and agree on naming/rules for template composition to [Spike] Discuss and agree on nomenclature and rules for template composition.Apr 6 2020, 6:27 PM
Jdlrobson updated the task description. (Show Details)

What are the guidelines for using template partials? I (@Jdlrobson) believe that we should only use template partials for the purpose of loops or inside the master template and try to avoid them if we can. Template partials within template partials are a potential sign that our templates have got overly complex (Yo-Yo problem) and are likely to suffer from the same issues that we see with class inheritance.

When comparing to OOP, template partials are the analog of composition (best practice), not inheritance (discouraged, long-term issues).
It expresses structure between loosely coupled parts of the DOM. The separation of closely-coupled elements - that belong together by positioning and/or function - localizes changes and creates an easier to understand structure. This results in "complex" partials that contain "simple" partials. This is the best practice in componentization / template composition.
A single level of composition results in an overgrown master-template, that causes difficulties in merging and higher cognitive load.

In this example separation of the ArticleTools component (which I used to call PageButtons) has multiple benefits:

  1. The root template is more concise, easier to get an overview of the DOM structure, in what order the page elements are served.
  2. If we would move the ArticleTools (#mw-head) element somewhere else in the DOM structure, we only need to move the template inclusion (1 line) instead of the whole element (24 lines).
  3. The same component can be split from legacy.mustache into ArticleTools-legacy.mustache. After SearchBox will be moved to the Header from ArticleTools.mustache, the two files will be easy to compare to see that the SearchBox is the only difference compared to legacy. This would be difficult to do if #mw-head is in index.mustache and legacy.mustache: the structure of those files will differ significantly, thus line-by-line diff won't be able to line up #mw-head in the two versions.

Thanks for the nomenclature, @Jdlrobson, ArticleTools expresses very well the purpose of the #mw-head element. The reason for 4 alternatives previously was that I didn't find any of those really fitting.

Note that the ticket title is now very academic, but unclear, particularly what "rules" do you mean "for template composition". Our purpose here is not so much composing templates, but separating those 😄 .

Jdlrobson renamed this task from [Spike] Discuss and agree on nomenclature and rules for template composition to [Spike] Discuss and agree on nomenclature and rules for template partial usage.Apr 6 2020, 9:49 PM
Jdlrobson updated the task description. (Show Details)

After https://gerrit.wikimedia.org/r/#/c/mediawiki/skins/Vector/+/578660/ is merged the master templates are called index.mustache (new) and legacy.mustache (old). Are these names acceptable and meaningful given the split? Should we rename to e.g.

I think the names for these master templates is going to be very subjective and risks not reaching any kind of consensus, but I believe @Demian is correct in recognizing that these would commonly be called "Layout" components in tools that have embraced a component architecture [1][2]. Therefore, my preference would be Layout and LayoutLegacy or Layout and LegacyLayout. I'm not really fond of kebab case in the component name as I haven't seen that pattern used in the component frameworks I've used (React, Flutter). Vue seems to be receptive to kebab-case, but they also seem to encourage PascalCase [3]

Do we need to refactor any of the existing template to create new components that have been suggested? If so what are the scopes of these components?

I think moving HTML/CSS that serve a logical function into its own component gives us the following advantages:

  • Encourages us to make styles that are isolated to the component assuming that there will be a corresponding .less file with the .mustache file (e.g. Content.mustache & Content.less) which increases the modularity of the skin's presentation layer. Discourages us from putting styles into the generic and non-descriptive common.less which risks becoming bloated if we maintain the status quo and decreases the modularity of the skin's presentation layer.
  • Makes it easier to to know at first-glance the function of HTML/CSS just by looking at the filename vs having to look through disparate HTML elements/CSS located in ambiguous files (e.g. common.less).
  • DRY's up the code In cases where Vector/LegacyVector have identical HTML/CSS. Perhaps the most obvious benefit is that components promote reusability, but let's not underestimate the aforementioned pros.

Given this, the proposed Content and Logo components make sense to me. I have more doubts about the ArticleTools component as that might be more just a collection of Header children components rather than one functional component, but I might need to look at that one a bit more.

[1] https://www.gatsbyjs.org/docs/layout-components/#what-are-layout-components
[2] https://nextjs.org/learn/basics/using-shared-components/the-layout-component
[3[ https://vuejs.org/v2/style-guide/#Single-file-component-filename-casing-strongly-recommended

  • Encourages us to make styles that are isolated to the component assuming that there will be a corresponding .less file with the .mustache file (e.g. Content.mustache & Content.less) which increases the modularity of the skin's presentation layer. Discourages us from putting styles into the generic and non-descriptive common.less which risks becoming bloated if we maintain the status quo and decreases the modularity of the skin's presentation layer.

This is already implemented and awaiting review: patch 585367. Help in reviewing it is greatly needed and appreciated.

  • Makes it easier to to know at first-glance the function of HTML/CSS just by looking at the filename vs having to look through disparate HTML elements/CSS located in ambiguous files (e.g. common.less).

Or even more an antipattern: in index.less. This should be avoided.

Given this, the proposed Content and Logo components make sense to me. I have more doubts about the ArticleTools component as that might be more just a collection of Header children components rather than one functional component, but I might need to look at that one a bit more.

ArticleTools is not part of the Header in new Vector. It's more like a second header. It's detached in the layout from the Header (unlike in old Vector): the open/closed state of the Sidebar affects the positioning of ArticleTools, but not the Header.

Besides that the contents of ArticleTools form a functional group: all the links (buttons) that does changes how the article is viewed (discussions, history, edit, etc.). SearchBox and PersonalMenu are the exceptions, but not for long: both will be moved into the Header: PersonalMenu, SearchBox, result DEMO (login: "Patch Demo" pass: "patchdemo1").

The next nearest components are: Sidebar, then Footer, both very distinct functional groups, that do not belong in the same component.

In a recent patch @Jdlrobson introduced a new idea for the ke-bab vs PasCal question that I'd like to endorse as the best of all the options so far. I've asked him to write about it, but that did not happen, so here's what I know:
Robson hinted there was some decision made regarding legacy in some team meeting (no more details). The result is one legacy template moved to includes/templates/legacy/Sidebar.mustache.
This looks very good:

  • The files can keep their original name.
  • Comparison (matching by same name) will be easy.
  • The component file names continue the pattern of using Pascal case (except the root template).
  • Clear separation.

Regarding the root template:

  • I'm used to "Layout", so that's what I prefer.
  • Initially I was against kebab case, but then I saw it's easier to recognize them in a folder listing by the small initials, so JdlRobson has a compelling argument there.
  • 'layout.mustache' looks good to me.
  • 'index.mustache' has one argument: it's the same name as 'index.less'.

And the root stylesheet:

  • 'index.less' makes sense for stylesheet as it is a listing of all the included files.
  • 'all.less' is also used with similar meaning.
  • 'layout.less' would be confusing: I would expect actual CSS rules in that, not imports.

@nray New, cleaner patches to demonstrate the components, in sequence:

  1. Header
  2. Logo
  3. Content
  4. ArticleTools

Result DEMO

ovasileva renamed this task from [Spike] Discuss and agree on nomenclature and rules for template partial usage to [Spike 4hrs] Discuss and agree on nomenclature and rules for template partial usage.Apr 8 2020, 4:33 PM

Some conclusions I've drawn

Should we keep all the legacy stylesheets and templates in a respective 'legacy' folder?

  1. Yes. I think we should be limiting changes to the legacy mode as much as possible. If we are rebuilding a component for new Vector the process should be to move that component to a legacy folder and remove that component from new Vector. New CSS should be written from scratch to avoid inheriting tech debt.

After https://gerrit.wikimedia.org/r/#/c/mediawiki/skins/Vector/+/578660/ is merged the master templates are called index.mustache (new) and legacy.mustache (old). Are these names acceptable and meaningful given the split? Should we rename to e.g.

  1. To me these names make sense, however what doesn't make seen is how we mix base and layout (and some component) CSS (See categories section on https://spaceninja.com/2018/09/18/what-is-modular-css/ if you are not familiar with what I mean by those terms)

Suggested actionable: Introduce a base.less file and a layout.less file (note the lowercase). Refactor common.less print.less, hd.less so that the CSS is put in the appropriate files (for example .emptyPortlet should move to a Portal.less module file and ) . I think camelcase should be reserved for components (modules).

POC of what this looks like is here > https://gerrit.wikimedia.org/r/#/c/mediawiki/skins/Vector/+/587855

What are the guidelines for using template partials? I

I think our template partials should only be used for things that are reusable, but I can see the inclination to use them more to identify components/modules even if those components are only ever used once. I think I can live with this provided we limit the use of template partials inside template partials.
My suggested rule of thumb: If a template X contains a partial P then partial P should not contain any other partials unless those partials avoid duplication of code elsewhere.
To give some concrete examples of what this might mean:

  • The index.mustache template can contain a Header.mustache, but that Header template partial shouldn't use a one-time use template partial called Logo
  • The index.mustache template can include a Sidebar.mustache component and that Sidebar component may contain the Portal partial as that reduces code duplication.

That said...

Do we need to refactor any of the existing templates to create new components that have been suggested? If so what are the scopes of these components?

I don't think Content and Header are actually components. They are layout. However if we do decide to think of them as components then we must separate the placement of these components from the styling. For example Header.less should not be responsible for positioning itself - only determining what it looks like inside. Same goes for Content.less - it would style headings inside itself, but it wouldn't position itself in the skin.

What common language can we (engineers, designers) agree on? See also: design nomenclature.

I don't think this is a pressing concern with the above. We should use names where they help conversation with designers and ourselves. Let's not over do it.

New CSS should be written from scratch to avoid inheriting tech debt.

I agree. Does it mean that renaming CSS classes to more appropriate (expressive, etc.) names is now unrestricted, or there are still class names that we must retain?

  1. however what doesn't make seen is how we mix base and layout

Suggested actionable: Introduce a base.less file and a layout.less file (note the lowercase). Refactor common.less print.less, hd.less so that the CSS is put in the appropriate files (for example .emptyPortlet should move to a Portal.less module file and ) . I think camelcase should be reserved for components (modules).

100% agree. This is how my first POC was done (different file names): finished layout CSS, relevant patch, patch in legacy.

POC of what this looks like is here > https://gerrit.wikimedia.org/r/#/c/mediawiki/skins/Vector/+/587855

Looks good.

My suggested rule of thumb: If a template X contains a partial P then partial P should not contain any other partials unless those partials avoid duplication of code elsewhere.
To give some concrete examples of what this might mean:

  • The index.mustache template can contain a Header.mustache, but that Header template partial shouldn't use a one-time use template partial called Logo
  • The index.mustache template can include a Sidebar.mustache component and that Sidebar component may contain the Portal partial as that reduces code duplication.

My thinking was that Logo might be reused in another skin / project by simply copying its .mustache and .less files. Following that thought Logo is definitely a component.

Header on the other hand is as much about the layout (in layout.mustache) as being a clearly distinguishable component of the page (in Header.mustache).
For ex. if I were to create an updated version of Timeless with collapsible sidebars, I would copy the Header component (an its attachments) from Vector as a starter. This is why multi-level component composition makes sense from a reusability perspective.

However, this potential for reuse is unlikely to be actually used and it can be achieved with copying 3 template inclusions: Logo, SearchBox, PersonalMenu (or Menu).
Inlining the Header element in layout would have the benefit of showing the important components of the page in one place, in relation to each other.
Practically that means when SearchBox is moved from #mw-head to the Header, that all happens within one file.

The similar 50%-50% logic applies to ArticleTools (#mw-head): both inlining in layout and separating to a component has its benefits.
There seems to be no plan to significantly change the position and style of these, therefore I'm inclining a little (say 60%) to handling it as a farely stable, "sealed" entity wrapped in a component.

I don't think Content and Header are actually components. They are layout.

Content is not a "functional" component, but it's very complex, making index.mustache hard to read and noisy as of now. It's also cleanly reusable in both new and legacy as demonstrated in this patch. That's a clear benefit, that would avoid duplicated edits like it was done with {{{html-indicators}}}.

For me separating Content is like getting freed of a huge burden: layout is much easier to reason about without that 1 page long static element in the middle, that we don't plan on changing. That being said, if it does not feel like a component then it would make sense to use the lowercase content.mustache name.

However if we do decide to think of them as components then we must separate the placement of these components from the styling. For example Header.less should not be responsible for positioning itself - only determining what it looks like inside. Same goes for Content.less - it would style headings inside itself, but it wouldn't position itself in the skin.

Absolutely.

I'll throw my thoughts out in case they might be useful, but note that I'm not trying to block any progress here. These are just my opinions for the sake of discussion:

Yes. I think we should be limiting changes to the legacy mode as much as possible. If we are rebuilding a component for new Vector the process should be to move that component to a legacy folder and remove that component from new Vector. New CSS should be written from scratch to avoid inheriting tech debt.

Sgtm for components that we completely rebuild. It might still be nice from a file search perspective to prepend or append the term "Legacy" to make the distinction even clearer between the two e.g. (legacy/SidebarLegacy.mustache or legacy/LegacySidebar.mustache), but I don't have strong opinions on that right now.

Suggested actionable: Introduce a base.less file and a layout.less file (note the lowercase). Refactor common.less print.less, hd.less so that the CSS is put in the appropriate files (for example .emptyPortlet should move to a Portal.less module file and )

I like the move to separate common.less out more which I consider a garbage pile for CSS. I also like calling the default HTML element rules base.less instead of common.less.

I think our template partials should only be used for things that are reusable, but I can see the inclination to use them more to identify components/modules even if those components are only ever used once. I think I can live with this provided we limit the use of template partials inside template partials.
My suggested rule of thumb: If a template X contains a partial P then partial P should not contain any other partials unless those partials avoid duplication of code elsewhere.

I can live with this, but I just want to point out that I think one of the reasons deeply nested (>= 3 levels) partials have been annoying in Vector is because we were making our lives more difficult in VectorTemplate by modeling the data array to match the partial nesting structure. Mustache's magical context switching coupled with the use of sections ({{#section}}{/sections}} can make deeply nested data particularly confusing to reason about. I think in many cases, following the data flow in mustache templates is made easier by flattening the data more because then you don't have to keep track of your calling context in Mustache. For example, when we still had the Navigation component, we were basically setting any sidebar data as:

$commonSkinData['data-navigation']['data-sidebar'] = [...sidebar data]

instead of just doing:

$commonSkinData['data-sidebar'] = [...sidebar data]

The index.mustache template can contain a Header.mustache, but that Header template partial shouldn't use a one-time use template partial called Logo

I can live with not having a Logo component. I still think a Header component is useful though.

I don't think Content and Header are actually components. They are layout.

I can still see benefits to splitting these out. FWIW the modular CSS article seems to suggest page headers are modules when describing modules:

Module: (aka object, block, or component) a reusable and self-contained pattern. Examples include media object, navigation, and page header.

For example Header.less should not be responsible for positioning itself - only determining what it looks like inside. Same goes for Content.less - it would style headings inside itself, but it wouldn't position itself in the skin.

I agree. Ideally, Content and Header shouldn't know how to position themselves. Both of those could be positioned instead by their parent (e.g. index or Layout component), and I think there are different ways of going about that. =

Updated patch with legacy/layout.less split and legacy.less from scratch: 585367

It might still be nice from a file search perspective to prepend or append the term "Legacy" to make the distinction even clearer between the two e.g. (legacy/SidebarLegacy.mustache or legacy/LegacySidebar.mustache), but I don't have strong opinions on that right now.

What workflow / tool do you use where this is beneficial?

I would advocate for the same file names: I use TotalCommander (2 pane) which has a shortcut for comparing files with the same name. Additionally, the folder-compare also matches by name. With this I can quickly compare the two versions, confirm if the rebase worked out as I intended, find the changes we made so far, etc. This convenience works only with consistent file names.

I can live with this, but I just want to point out that I think one of the reasons deeply nested (>= 3 levels) partials have been annoying in Vector is because we were making our lives more difficult in VectorTemplate by modeling the data array to match the partial nesting structure. Mustache's magical context switching coupled with the use of sections ({{#section}}{/sections}} can make deeply nested data particularly confusing to reason about. I think in many cases, following the data flow in mustache templates is made easier by flattening the data more because then you don't have to keep track of your calling context in Mustache.

This I wanted to say for a few weeks now, but the template data has been step-by-step flattened since then, so it's far less of an issue now: afaict all data- keys are on the top level, none nested.

I can live with not having a Logo component. I still think a Header component is useful though.

I gave up on the Header component to have a Logo component 😉
The DOM and the styling of the Logo is quite complex (sample), tightly coupled and self-contained, making it a good candidate for a component.
Maybe both are useful enough.
To demonstrate it's more readable as a component:

Change 587855 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/skins/Vector@master] Organize CSS by base, layout and components

https://gerrit.wikimedia.org/r/587855

My thinking was that Logo might be reused in another skin / project by simply copying its .mustache and .less files. Following that thought Logo is definitely a component.

There's no chance of reuse here outside Vector.I think we should either have a Logo or a Header component not both. That said, my opinion here is weakly held. I've reached out to a few other folk at Wikimedia Foundation to get some clarity about the things we're discussing here on the internal Slack channel (Sorry that's not public). I'll be sure to summarize in public the discourse there.

I think we should either have a Logo or a Header component not both.

I've given up on the Header component for this reason. (I wrote this above.)

things we're discussing here on the internal Slack channel (Sorry that's not public).

Slack is the appropriate tool for such discussions. Just don't expect me to know.

I'll be sure to summarize in public the discourse there.

That's great, thanks.

There's one thing in your latest patch 587855 that we haven't discussed before: the resources/skins.vector.styles/base/ folder.
Please elaborate on how you would specify that folder.

  1. Is it for stylesheets that are common to both legacy and new?
  2. Is it for non-component stylesheets?
  3. Will there be a resources/skins.vector.styles/legacy/base/ folder at some time?

There's significant overlap, thus it's hard to tell.

I am fine with the non-component stylesheets in the skins.vector.styles folder - camelCase is already a distinction -, but moving those in a folder is also fine for me.
If those are moved in a folder I'd rather call it common. I don't feel those files serve as a "base" for anything, they just don't belong to the components.
Note: the common.less file we seem to almost agree that it will be renamed to content.less, thus the name won't cause confusion with that.

Change 588762 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/skins/Vector@master] Layout is separated from common css

https://gerrit.wikimedia.org/r/588762

Change 588762 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Layout is separated from "common" CSS

https://gerrit.wikimedia.org/r/588762

@Jdlrobson Importing 'layout.less' at the bottom of 'index.less' in the last patch 588762 causes issues:

  • @import 'mediawiki.mixins.less' in 'layout.less' does nothing, as the file is imported previously. However, the mixins are imported to a separate block, thus unavailable in 'layout.less'. (This looks like a less.php bug, btw.) This wouldn't be an issue if 'layout.less' is in the @media screen block in 'index.less' (result: Storybook build error).
  • A margin: auto; rule in 'layout.less' will override a margin-left: 0; rule in any component. Usually, the opposite is the intention.

Is there any need to

  1. Move 'layout.less' down? These rules were part of 'common.less', the first import. It would make sense to import 'layout.less' before 'common.less'
  2. Move 'layout.less' out of the @media screen block in 'index.less'? I assume this is to merge the print rules in the future. That has some pros and cons. I'm not sure of the benefits of that, but if that happens it should happen consistently to all '.less' files to avoid these issues and to keep indentation consistent in the files. The latter makes editing much easier.
Jdlrobson renamed this task from [Spike 4hrs] Discuss and agree on nomenclature and rules for template partial usage to [Spike 4hrs] Discuss and agree on nomenclature and rules for template partial usage and CSS organization from experience with header.Apr 29 2020, 11:25 PM
Jdlrobson updated the task description. (Show Details)

With the header work almost wrapped I'd love to shift the focus here. I've increased the scope of this task to cover all the friction I/we faced during the implementation of this first task. My hope is when the dust settled we can come to some agreements to reduce friction in future work from the lessons learned. The list is in priority order.

Should we keep all the legacy stylesheets and templates in a respective 'legacy' folder?

We have started doing this so I wonder if it would be okay for us to add a README to these folders to explain that these templates should be considered in maintenance mode and only updated to reflect essential upstream changes.

Let's break up common.css into manageable chunks. Please input on how that should be done. https://gerrit.wikimedia.org/r/587855

I'm requesting code review on https://gerrit.wikimedia.org/r/587855 - so if you have any thoughts on how our CSS should be rearranged please jump in.

Should we keep all the legacy stylesheets and templates in a respective 'legacy' folder?

Works very well for me.

Let's break up common.css into manageable chunks. Please input on how that should be done. https://gerrit.wikimedia.org/r/587855

Patch looks good, no objections.

While @Jdlrobson is working on patch 587855 (which is looking good imo, awaiting rebase), we could summarize where the consensus stands on changes discussed in this ticket. I'll list the points I recall to be nearing consensus. Please share your standing on each.

  1. keep legacy stylesheets and templates in a respective 'legacy' folder (done)
  2. break up 'common.css' into manageable chunks (patch 587855): content.less, externalLinks.less, print.less, theme.less, typography.less, Indicators.less, SiteNotice.less
  3. split 'content.mustache' from 'index.mustache' and 'legacy/content.mustache' from 'legacy.mustache' (patch 585625)
  4. add .mw-tabs class to #mw-head
  5. split #mw-head from 'index.mustache' and 'legacy.mustache' into the reusable 'Tabs.mustache' (patch 585626)
  6. rename 'index.mustache' (only the template) to 'skin' / 'page' / 'layout' / 'pagelayout' / 'master' / 'root' / 'modern' / 'vector'?
  7. rename 'watchstar-ie8.less' to 'grade-c.less', 'watchstar.less' to 'WatchstarTab.less'

My answers:

  1. 'legacy': yes. Works very well.
  2. break up 'common.css': definitely. My focus is 'content.less', rest: no strong opinion, but +1.
  3. 'content.mustache': yes. It's reusable for both modern and legacy and it will make 'index.mustache' much more comprehensible and easier to work on.
  4. add .mw-tabs class to #mw-head: yes, name more descriptive, using classes preferable
  5. 'Tabs.mustache': yes. It's reusable for both modern and legacy.
  6. rename 'index.mustache': possibly. No strong opinion on the names, 'layout', 'pagelayout' is common (familiar).
  7. 'grade-c.less': yes, 'WatchstarTab.less': sounds good, no strong opinion.
  1. Why abstract here, when it's just about one brower at current time? Name the things after what they are, abstract if necessary in future. –We should also be clear that the aim of this file is to be removed any time soon with T248061 on the horizon.

EmphasizedSidebarAction
-> SidebarActionEmphasized?
-> LinkSidebarEmphasized?

.mw-jump-link component, not part of content.less(!)

Change 595001 had a related patch set uploaded (by Jdlrobson; owner: Jdlrobson):
[mediawiki/skins/Vector@master] Class names with hyphens preferred over camel case

https://gerrit.wikimedia.org/r/595001

@Volker_E thank you for the feedback to T249073#6099186. What about @Jdlrobson and others?

An additional question came up in gerrit:

  1. the root stylesheets: 'index.less' / 'all.less' / 'vector.less' ?
  2. the location of the legacy root: 'legacy.less' / '?-legacy.less' / 'legacy/?.less' (consider the resulting file: almost all paths are prepended with '../')

Imo 8. 'all.less', 9. 'all-legacy.less'

To root/entry point stylesheet naming:
We don't have a clear naming convention in MediaWiki skins for entry point stylesheets, Example skin uses something along the lines of media queries ('screen-common.less'/'print.less'), which is making me personally not too excited, as we sometimes have stylesheets that are shared across media queries (hence probably ''screen-common.less'?!).
It's not a widely known pattern outside of MediaWiki world.

index.less is currently mirroring Apache naming conventions, which is a widely known naming pattern for web devs, nonetheless also not too clear, but somewhat acceptable IMO.

We do have a strictly enforced naming convention in regards to skins & extensions though:
skin.json/extension.json

Something like skin.less and skin-legacy.less seem the best fit to me.

Alternatively, @Jdlrobson brought up vector.less, which sounds fine from a inner-Vector perspective, but if I imagine Example featuring an example.less file, I'd think above naming scheme wins.

Change 595001 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Class names with hyphens preferred over camel case

https://gerrit.wikimedia.org/r/595001

Change 587855 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Organize CSS by common, layout, typography and components

https://gerrit.wikimedia.org/r/587855

Change 595081 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[mediawiki/skins/Vector@master] [legacy] Merge 'background-gradient.less' into 'layout.less'

https://gerrit.wikimedia.org/r/595081

Change 595081 merged by jenkins-bot:
[mediawiki/skins/Vector@master] [legacy] Merge 'background-gradient.less' into 'layout.less'

https://gerrit.wikimedia.org/r/595081

Talking with the team today I think it might be useful to pull out these remaining questions into separate tickets as they don't seem to be blocking us on any work right now.

Change 596512 had a related patch set uploaded (by VolkerE; owner: VolkerE):
[mediawiki/skins/Vector@master] Naming convention using 'skin' as entrance point

https://gerrit.wikimedia.org/r/596512

Per standup I've descoped this spike and split out 2 new spikes. We will focus on deciding on the template entry point name and then closing out this task.

Change 596512 merged by jenkins-bot:
[mediawiki/skins/Vector@master] Naming convention using 'skin' as entrance point

https://gerrit.wikimedia.org/r/596512

Jdlrobson updated the task description. (Show Details)

Thanks all for your input into these important conversations!

@Jdlrobson was this intentionally not tagged Desktop Improvements, by any chance?

@Demian Please don't reassign tasks and don't add to resolved tasks. That's an anti-pattern! And with “please” I mean don't do this. It makes them really hard to set into specifc timely context and leads to unnecessary confusion. If there's additional work needed we can always open another similar one and link to the original.

I'm sorry @Volker_E. I believe what you are working on belongs to this task, a new task for that one patch would be unaccessible (not explorable) and useless from a documentation standpoint. I hope adding a late patch is not as confusing as having that patch hidden somewhere in the task graph, therefore I believe the task should be reopened. However, I wanted to ask you to do that, to avoid a similarly angry response if I would have done so.

Note: This task is resolved. Resolved tasks should never have open patches associated with them. Create a new task referencing this one if more discussion is needed.

Change 585625 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[mediawiki/skins/Vector@master] [refactor] Split content into its own template to allow reuse in legacy and new Vector

https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/ /585625

I'm sorry for the unexpected comment, dusty old work should have been attached to the new ticket T253669.