@JScherer-WMF
would you be able to take a look at this page to review the design? https://patchdemo.wmflabs.org/wikis/a03fb6d93c/wiki/Main_Page

Change #1025463 had a related patch set uploaded (by Bernard Wang; author: Bernard Wang):

[mediawiki/skins/MinervaNeue@master] Update <p> spacing to only use margins

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

In T362939#9755464, @gerritbot wrote:

Change #1025463 had a related patch set uploaded (by Bernard Wang; author: Bernard Wang):

[mediawiki/skins/MinervaNeue@master] Update <p> spacing to only use margins

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

Just so this isn't lost:

In T360917#9731248, @Jack_who_built_the_house wrote:

In T360917#9730055, @bwang wrote:

An issue @Jdrewniak pointed out with this approach (and technically any approach that relies on sibling selectors) is that we wont have the correct spacing when elements are floated.

Right, unfortunately p + p will immediately distort the appearance of a huge share of articles, and in a noticeable way. Just to be clear: if you apply a fix only to images, something like p + figure + p, you will soon notice that there are also floating tables, floating divs, floating divs preceded by a <link> element from TemplateStyles, groups of floating images, non-floating images, hidden elements, div-nested paragraphs, etc. etc. This is volunteers' turf, not developers'; I don't think it's feasible to find any meaningful compromise here and not find yourself (and volunteers) hunting for the endless exceptions for eternity to come.

While I was developing Convenient Discussions, floating elements were a hell of a troublemaker when I was trying to figure out the visual boundaries of users' comments (so, floating elements had to be ignored). The solution I adopted eventually was to just use an algorithm that parses each and every stylesheet existing on the page and look for float set to left or right in them. But you can't do that in pure CSS.

and technically any approach that relies on sibling selectors

Yet there are cases that are clearly anomalies (e.g. p + figure + ul when the paragraph describes the content of the list that follows) and cases that are a rule rather than an exception.

So unless you have a viable solution to this, I believe p + p { margin-top: 1em; } to be a solution of the same level of harmfulness as padding-bottom: 0.5em.

Maybe negative margins would be a better solution after all?

instead of using padding-bottom: 0.5em for p , you could use margin-bottom: 1em and a negative margin for the next sibling in exceptional cases, e.g. p + ul, p + ol { margin-top: -0.5em }, together with :first-child / :last-child pseudo-classes as required

This one I saw utilized by experienced web designers (e.g. Aegea blog engine, see an example list), but it may come with its drawbacks as well: :last-child can be a floating or hidden element just as well, which would result in p:last-child { margin-bottom: 0.5em } not being applied and 1em bottom margin for the last paragraph. But currently it seems way less invasive to me.

You have to research and think about this very carefully. Whichever solution you settle on, its consequences are gonna haunt developers and volunteers for years. Please don't rush with releasing it as you did with padding-bottom: 0.5em.

And one more consideration: Styles should be applied not as smart ways to achieve this or that visual appearance, but based on a general idea of what you're trying to do.

• Do you want paragraphs to have 0.5em margins, except for the special case where it immediately follows another paragraph?
  • And follows visually and not in terms of the DOM – which seems unattainable with the current state of CSS.
  • But is this case really that special? You will find out that paragraphs are not the only elements that can contain text not delimited by borders (how about p + dl with dt inside, p + div > p:first-child and p + table where the table has a caption instead of a head?). Or, even more importantly, that by increasing spacing between paragraphs, you have affected the general feel of Vector's design, which would necessiate changes in margins of other elements (and other margins of paragraphs) as well. This consideration seems underestimated to me. E.g. p + h3, p + h4 will have the top indentation smaller than that of paragraphs which is inconsistent.
• Or do you want paragraphs to have a consistent greater bottom indentation, except for the special cases where it 1) is immediately followed by a list and 2) is at the end of a container?
• Maybe, in fact, you want paragraphs to have a consistent greater bottom and top indentation, except for special cases (but there can be really many of those, to the point that it defeats the purpose: hN + p, start of an article, and p:first-child { margin-top: 0.5em } won't work often because of floating and hidden elements at the start of pages)?

If you start with the wrong general idea, at first it might look good, but with time everything will start falling apart.

Discussed in sprint planning. We should add code blocks, block quotes, and images. @JScherer-WMF to look over and will provide more detail and write a specification

I had a look at the patchdemo @bwang, and there are a few discrepancies.

All section breaks should be the same value. It looks like section breaks for H4s and 5s have less space than other headings.

Tables should have paragraph breaks around them like lists and other "inline" items.

@Edtadros Are the new requirements I wrote above sufficient for QA on this? I can assist with the QA, if you like. I find that manually measuring with my screenshot tool between elements is more accurate and reliable than testing by inspecting an element and adding together margin and padding values.

@Jack_who_built_the_house Thank you so much for your collaboration on this issue. I can't really speak to the CSS intricacies above, but do you have any other feedback on the proposed approach that hasn't been addressed?

In T362939#9819218, @JScherer-WMF wrote:

I can't really speak to the CSS intricacies above, but do you have any other feedback on the proposed approach that hasn't been addressed?

As far as I can tell from the lines

Paragraph break: 1 em

If an inline element appears at the end of a paragraph, it should have 1 em of space after it if the element below it is anything other than a heading.

you also hold that 1em after paragraphs should be a general case here and not limited to "paragraph + paragraph" adjacencies. That was my point also (but I was mostly concerned about the implementation in CSS).

Headers were equidistant to the paragraphs above and below them. At a glance, it was unclear whether a header belonged to the paragraph above it or below it, which created more issues with information hierarchy. The solution to this is that headers should be physically closer to the text that they are headers for.

Yep, another point I was making; increased paragraph spacing necessitates increased top spacing of headings following them.

Lists, images, tables, block quotes, and other "inline" elements that are indented from the main body of text should have 1em of space above and below them.

But wait, about lists: are we doing lists like in 1 or like in 2 at the end of the day? From T352875#9527667 I thought you're in favor of 1, and this statement sounds like 2.

1. 0.5em top margin	2. 1em top margin

And also the bottom margin of lists is 0.5em in the patch demo, so they don't follow the 1em guideline. But that should be approached very carefully because of nested lists and other possible adjacencies.

I also want to note that the demo is absolutely insufficient if it's intended to test the design thoroughly. It covers only the tip of the iceberg of the kind of layout that can be encountered in the field, when it comes to paragraphs and vertical spacing in general.

I created a page on that patchdemo with the cases I mentioned above in the comments and some more: https://patchdemo.wmflabs.org/wikis/a03fb6d93c/wiki/Test. There are mostly CSS intricacies that need to be tested there, but also some things that may be of interest to you – e.g. gallery, how lists are spaced around different elements, and how paragraphs are spaced in boxes (which commonly occurs in UI messages and warnings, and those quite often go in .mw-body). I assume that "paragraph break" in the task description refers to the spacing between paragraphs, therefore we should make sure that spacing doesn't "leak" to the top and bottom spacing of a group of paragraphs inside a container, be it the whole page or a smaller box like message boxes (historically in Vector it has always been 0.5em).

As for your comment to the screenshot in T362939#9819207:

Tables should have paragraph breaks around them like lists and other "inline" items.

In MediaWiki/Vector, bare tables and bare images (with no additional classes) historically had zero spacing. So in the demo, bare tables are used. If you add class="wikitable" to a table, you will get a 1em-spaced table. I don't know whether it should be changed; I suspect it shouldn't. In English Wikipedia the use of class="wikitable" is widespread, while bare tables are often used in templates with all kinds of tabular content with custom formatting, so there is a big chance that adding 1em to bare tables would add unwanted spacing to a lot of such tables.

In T362939#9770351, @Jack_who_built_the_house wrote:

Maybe negative margins would be a better solution after all?

Wouldnt the negative margins solution still have issues with the floating element case? Anything that relys on sibling selectors will break in the case where two paragraph elements are visually next to each other but not in the DOM.

Do you want paragraphs to have 0.5em margins, except for the special case where it immediately follows another paragraph?

Based off my understanding of the design, yes. We want 1em margins in between paragraph blocks to separate them more visually. But when there are other elements (i.e. lists, tables, images etc) that are in between two paragraphs blocks, we want to show those elements as "inside" or a part of the surrounding paragraphs, which is why they will have 0.5 margins. The current proposed solution is consistent with this understanding. @JScherer-WMF Pls lmk if this is correct.

And follows visually and not in terms of the DOM – which seems unattainable with the current state of CSS.

Yes, thats also my understanding. I don't see an obvious solution to this outside of the original padding-bottom: 0.5em approach, or changing the design (i.e. making all margins 1em)

So unless you have a viable solution to this, I believe p + p { margin-top: 1em; } to be a solution of the same level of harmfulness as padding-bottom: 0.5em.

Do you have any other proposals for viable solutions? As I see it, there is still a benefit to only using margins for spacing, per the feedback in T361767. It simpler to understand and work around

In T362939#9819207, @JScherer-WMF wrote:

All section breaks should be the same value. It looks like section breaks for H4s and 5s have less space than other headings.

The spacing you are pointing out are coming from the existing styles for heading elements, I think we should make a separate task about that.

Tables should have paragraph breaks around them like lists and other "inline" items.

I dont quite understand what you mean by "paragraph breaks" and "line breaks"? The existing styles for tables dont have margins by default. In this image the spacing around tables are coming from the headings and paragraph elements

In T362939#9822873, @bwang wrote:

Wouldnt the negative margins solution still have issues with the floating element case? Anything that relys on sibling selectors will break in the case where two paragraph elements are visually next to each other but not in the DOM.

As I said:

Yet there are cases that are clearly anomalies (e.g. p + figure + ul when the paragraph describes the content of the list that follows) and cases that are a rule rather than an exception.

The case p + figure + p is not an anomaly. It's pretty much a rule. And there are endless similar cases (see T362939#9770279), so the number of exceptions that you would have to encode in CSS would grow exponentially.

At the same time, this case is an anomaly:

The description of a list:
[[File:Image.png|Image description]]
* List item
* List item

And even if p + ul selector fails here, the consequences are negligable. I'm not even sure Justin wants this exception to be (I asked above).

Based off my understanding of the design, yes. We want 1em margins in between paragraph blocks to separate them more visually. But when there are other elements (i.e. lists, tables, images etc) that are in between two paragraphs blocks, we want to show those elements as "inside" or a part of the surrounding paragraphs, which is why they will have 0.5 margins. The current proposed solution is consistent with this understanding.

Justin will comment, but my reading of his concept is that it's not consistent. I believe it's just untenable from the design perspective, even if we put CSS difficulties aside. Any changes to "paragraph follows paragraph" cases that are not supported by the rest of the layout break the information hierarchy. You can see how it happens on the test page I created.

I don't see an obvious solution to this outside of the original padding-bottom: 0.5em approach, or changing the design (i.e. making all margins 1em)

As I see it, there is still a benefit to only using margins for spacing, per the feedback in T361767. It simpler to understand and work around

No question about the use of margins. As for making all margins 1em as opposed to just the bottom margin (unless it's the last paragraph), that would be quite a radical change, starting with how the very first article paragraph looks:

1em top margin	0.5em top margin

And if we want to still keep 0.5em top margin for some cases, the work of encoding exceptions will likely be unfeasible because of floating and hidden elements that break all :first-child and adjacent sibling selectors.

In general, the deal with floating and hidden elements is that they go on top of an article, a section, etc. way more often than at the bottom. Take this random article. You have this at the top:

{{Short description|Creation of exclusive, custom-fitted clothing}}
{{Redirect|Couturier}}
{{Redirect|High fashion|the song|High Fashion (song)}}
{{Use dmy dates|date=November 2021}}
{{Italic title|reason=foreign phrase}}
[[Image:Pierre Balmain and Ruth Ford, photographed by Carl Van Vechten, November 9, 1947.jpg|thumb|upright|[[Pierre Balmain]] adjusting a dress on model [[Ruth Ford (actress)|Ruth Ford]] in 1947 (photographed by [[Carl Van Vechten]])]]

Lots of invisible/floating stuff. So, you can't do p:first-child to target the first paragraph. You may try to circumvent this with p:first-of-type, but that is also prone to errors. And then you have paragraphs following a section heading. You need adjacent sibling selectors to make sure paragraphs have margin-top: 0.5em. And you fall into the same trap as with p + p.

The good news is that floating and hidden elements at the bottom of things are quite rare. So it is way safer to have p:last-child { margin-bottom: 0.5em } to make sure your container has even top and bottom margins. And even if it fails – no big deal, most people won't notice.

So, for the reasons above my proposed solution is to have 0.5em top margin and 1em bottom margin for paragraphs, and then accounting for a limited number of special cases. If you have examples of cases where this approach will irreparably fail, please share.

In T362939#9822910, @bwang wrote:

In T362939#9819207, @JScherer-WMF wrote:

All section breaks should be the same value. It looks like section breaks for H4s and 5s have less space than other headings.

The spacing you are pointing out are coming from the existing styles for heading elements, I think we should make a separate task about that.

Good to know. Noted. Let's leave those for now.

Tables should have paragraph breaks around them like lists and other "inline" items.

I don't quite understand what you mean by "paragraph breaks" and "line breaks"? The existing styles for tables dont have margins by default. In this image the spacing around tables are coming from the headings and paragraph elements

Ok let's leave the tables because those are existing behaviours.

I updated the requirements in the description to describe what each of those break values should be.

There are 3 flavours of content breaks in an article:

• Line break: vertical spacing = line-height value
• Paragraph break: 1 em
• Section break: 1.5em

Paragraph breaks are the breaks between two text paragraphs.

Section breaks are when there's a new section with a header.

@Jack_who_built_the_house

But wait, about lists: are we doing lists like in 1 or like in 2 at the end of the day? From T352875#9527667 I thought you're in favor of 1, and this statement sounds like 2.

You're right. Thanks for clarifying. I updated the requirements. Inline elements should have 0.5 em above and 1 em below.

The test page you created was massively helpful when @bwang and I chatted about this again this morning. Thank you!

As I understand the terminology used in the specification and how it correlates with HTML/CSS entities, correct me if I'm wrong,

• "Inline elements" are elements that are part of narration (?) as it goes from top to bottom, i.e. not headings and not floating elements (which is not the same as inline is used in CSS where it means elements inside horizontal flow of text).
• "Paragraphs" are units of text which may include a literal HTML <p> paragraph together with an inline element; not necessarily only <p> (or even at all?).

In T362939#9827765, @JScherer-WMF wrote:

You're right. Thanks for clarifying. I updated the requirements. Inline elements should have 0.5 em above and 1 em below.

So that it is articulated: this implies a change to the current design where tables, code blocks, and quotes have 1em above.

As long as the list of these inline elements is a closed one, it shouldn't substantially complicate the technical implementation with negative margins. In any case, the list of exceptions for this case would be reasonable to maintain, as opposed to such list with p + p which would just grow without limit.

To be clear, there is no straightforward technical way to distinguish between, say, tables that are part of the narration ("The population of the city dropped in the last century: <Population table by year>") and those that stand alone ("The city has a population of N. <Population table by year>"). To quote myself in T352875#9424919,

neither Parsoid nor the current parser make a difference between 1) an empty line after a list and 2) no empty line after a list:

And that applies to all elements, not only lists. And we will have even big stand alone tables with 0.5em top margin, e.g.:

T240113 Proposes an exception to the following design goal:

Lists, images, tables, block quotes, and other "inline" elements that are indented from the main body of text should have 0.5 em of space above and 1 em of space below them.

@JScherer-WMF In the case of sublists, should the indented lists have vertical spacing? (i.e. vertical margins between sublists?)

0.5em margins	no margins on sublists

In T362939#9835763, @Jdrewniak wrote:

T240113 Proposes an exception to the following design goal:

Lists, images, tables, block quotes, and other "inline" elements that are indented from the main body of text should have 0.5 em of space above and 1 em of space below them.

@JScherer-WMF In the case of sublists, should the indented lists have vertical spacing? (i.e. vertical margins between sublists?)

0.5em margins	no margins on sublists

Yes, they should follow the same rules as other inline elements. I like how it reads with the vertical spacing included. There is theoretically a world where an image could be nested in a block quote nested in a sub-list, which means we would want to keep the behaviour consistent.

In T362939#9833697, @Jack_who_built_the_house wrote:

As I understand the terminology used in the specification and how it correlates with HTML/CSS entities, correct me if I'm wrong,

• "Inline elements" are elements that are part of narration (?) as it goes from top to bottom, i.e. not headings and not floating elements (which is not the same as inline is used in CSS where it means elements inside horizontal flow of text).
• "Paragraphs" are units of text which may include a literal HTML <p> paragraph together with an inline element; not necessarily only <p> (or even at all?).

Sorry for the confusion. You're correct here ^^

To be clear, there is no straightforward technical way to distinguish between, say, tables that are part of the narration ("The population of the city dropped in the last century: <Population table by year>") and those that stand alone ("The city has a population of N. <Population table by year>"). To quote myself in T352875#9424919,

neither Parsoid nor the current parser make a difference between 1) an empty line after a list and 2) no empty line after a list:

And that applies to all elements, not only lists. And we will have even big stand alone tables with 0.5em top margin, e.g.:

Is that intended? Not saying that is bad – it's a fairly minor detail – but maybe such a distinction between standalone elements and elements that attach to the paragraph above should be acknowledged so that wikis could fine-tune the appearance of their content, like this climate table.

I agree that a technical way to distinguish between these things would be a nice affordance to have for future typography and layout efforts.

In T362939#9835763, @Jdrewniak wrote:

T240113 Proposes an exception to the following design goal:

Lists, images, tables, block quotes, and other "inline" elements that are indented from the main body of text should have 0.5 em of space above and 1 em of space below them.

@JScherer-WMF In the case of sublists, should the indented lists have vertical spacing? (i.e. vertical margins between sublists?)

0.5em margins	no margins on sublists

This is based off my convo with @JScherer-WMF ,but my understanding is that justin isnt saying that 0.5em spacing above and 1em below are applied to "Lists, images, tables, block quotes, and other "inline" elements", but rather in the context of those "inline elements" being surrounded by paragraph elements, they should have that spacing.

We will not be merging this ticket this sprint - next steps are to make a patchdemo, review designs, and then implement in sprint 5.

Change #1036715 had a related patch set uploaded (by Bernard Wang; author: Bernard Wang):

[mediawiki/skins/Vector@master] POC: Make paragraph spacing 0.5em top and 1em bottom by default, handle adjacent inline elements manually

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

Test wiki created on Patch demo by BWang (WMF) using patch(es) linked to this task:
https://patchdemo.wmflabs.org/wikis/228f3d1cc6/w

I created a new patch demo based off @Jack_who_built_the_house 's feedback, where the paragraph element has 0.5em top margin and 1em bottom margin by default, and adjacent "inline" elements (i.e. lists, tables, dl, blockquote) use a negative top margin in order to create an effective 0.5em spacing next to paragraphs. Again, this doesnt work well for elements that are floated, but I believe this is acceptable given that at least paragraph elements should have the right spacing.

Another thing to note, in this patch demo "inline" elements do not have a bottom spacing of 1em, they have 0.5em. Let me know if you see any issues or if I misunderstood anything @JScherer-WMF, and if you are able to review as well @Jack_who_built_the_house, that would be greatly appreciated.

https://patchdemo.wmflabs.org/wikis/228f3d1cc6/wiki/Main_Page

In T362939#9839153, @bwang wrote:

I created a new patch demo based off @Jack_who_built_the_house 's feedback, where the paragraph element has 0.5em top margin and 1em bottom margin by default, and adjacent "inline" elements (i.e. lists, tables, dl, blockquote) use a negative top margin in order to create an effective 0.5em spacing next to paragraphs. Again, this doesnt work well for elements that are floated, but I believe this is acceptable given that at least paragraph elements should have the right spacing.

Good first step!

A question to @JScherer-WMF right away: how should we handle definition lists (those that go "term in bold – definition in roman")?

Those are often used for glossary-like entities, see https://en.wikipedia.org/wiki/Project:Manual_of_Style/Glossaries. I'm not sure whether they should attach to the preceding paragraph when it's present; they are often large enough structures that kind of stand alone. What do you think?

Then, we suddenly crossed paths with the implementation of T330527 which wrapped all tables in <div class="noresize">, hehe. Looks like its implementation is unfinished (it currently breaks floating tables at least), but if .noresize will be applied to all .wikitables, we will need at least p + .noresize > table:first-child. So, well, yeah, we should brace ourselves for maintaining a sizeable list of exceptions, knowing that alternatives are worse.

Then, boxes should be evenly spaced from top and bottom (p:last-child { margin-bottom: 0.5em }):

In T362939#9840767, @Jack_who_built_the_house wrote:

A question to @JScherer-WMF right away: how should we handle definition lists (those that go "term in bold – definition in roman")?

Thanks for your collaboration on this, as always!

Definition lists look like a flavour of H4 or H5 element with modified paragraph styling rather than a list. They should follow the header convention of the bolded item being closer to the thing it is heading than the content above it.

Then, boxes should be evenly spaced from top and bottom (p:last-child { margin-bottom: 0.5em }):

Yes, boxes should have equal top and bottom margins like the message component in codex.

Change #1021533 abandoned by Bernard Wang:

[mediawiki/skins/Vector@master] Update <p> spacing to only use margins, update list elements to have consistent top and bottom margins

Reason:

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

In T362939#9920727, @Esanders wrote:

In T362939#9844095, @JScherer-WMF wrote:

In T362939#9840767, @Jack_who_built_the_house wrote:

Then, boxes should be evenly spaced from top and bottom (p:last-child { margin-bottom: 0.5em }):

Yes, boxes should have equal top and bottom margins like the message component in codex.

I can't see this rule in the code, or a follow-up ticket to fix this issue.

I checked with Justin and Bernard and the example here is not a supported component. It is a user generated box with inline styles that looks like a message component. This does not need a ticket as the inline component should be updated.

In T362939#9926763, @Jdlrobson wrote:

I checked with Justin and Bernard and the example here is not a supported component. It is a user generated box with inline styles that looks like a message component. This does not need a ticket as the inline component should be updated.

This is indeed a user-generated box – which serves the purpose of demonstrating how the margins will look in countless real-world cases as they are common on Wikimedia sites. One of the reasons for the backlash after introduction of padding-bottom was that top and bottom margins became uneven in random places of the sites. I don't think every such box should have a template with TemplateStyles accompanying it. Well, probably there is something to discuss here (e.g. possible false positives), so I guess I'll create a task when I have good examples.