I've worked on this new breakpoints proposal adding the following:

• New breakpoints sizes: based on the most used screen sizes today
  • 1920px (max)
  • 1366px
  • 768px
  • 320px (min)

• Legacy breakpoints: our current breakpoints
  • 2000px (max)
  • 1200px
  • 1000px
  • 720px
  • 320px (min)

About new breakpoints, I've created them based on the most used screens (here where you can find the most used screens today). So, I proposed breakpoints from 320px (the smallest screen) to 1920px, and we will apply a 1514px max-width content for our grids in this other task T298198.

👁 Here you can view the Figma file with the new breakpoints proposal.

In T303522#7969997, @bmartinezcalvo wrote:

NOTE: @alexhollender_WMF we need to know if 1200px and 1000px would have impact in DIP since in this proposal I've documented them as legacy.

• we are currently using the 1200px breakpoint in order to reduce the size and spacing around the table of contents, so that the article can take up more space at that smaller size
• we are currently using the 1000px breakpoint in order to hide the table of contents

Vector, MediaUploader, UploadWizard and one community skin, StarCitizenTools / mediawiki-skins-Citizen are the only ones using 1200px widely.

I'm a big proponent of the agreed on proposal, I think that it's very solid and while hold for major parts.

One note on the naming, while the t-shirt scale makes sense in a number of other token categories, I'd pledge to use mobile, tablet, desktop, desktop-wide and desktop-extrawide or similar.
It's really hard to apply those and keep the abstraction in head on this specifically unchanging category. Thoughts @bmartinezcalvo and @Sarai-WMDE…?

In T303522#7996273, @Volker_E wrote:

I'm a big proponent of the agreed on proposal, I think that it's very solid and while hold for major parts.

One note on the naming, while the t-shirt scale makes sense in a number of other token categories, I'd pledge to use mobile, tablet, desktop, desktop-wide and desktop-extrawide or similar.
It's really hard to apply those and keep the abstraction in head on this specifically unchanging category. Thoughts @bmartinezcalvo and @Sarai-WMDE…?

I don't thing using the name of the devices in the token name is the best solution since some of them works for more than one device, e.g. breakpoint-desktop would work for both small desktop screens and landscape tablets.

Instead of using t-shirt names (I used them to have a more short names and @Sarai-WMDE used them too for text size) we could use instead these other names we use in other tokens like shadows:

• Extra Large
• Large
• Medium
• Small
• Extra Small

(It's the same than t-shirt names but with a more large name)

Hi @bmartinezcalvo, thanks for the ping for feedback. I mostly agree with this proposal and it fits in with the 3 layouts we use on the Growth Desktop version of the homepage (see this task T258005 for reference to the responsive breakpoints we have set, and demo the page live at testwiki at Special:Homepage).

The one part that seems odd is the breakpoint-M (1200px) and breakpoint-L(1366px) sizes being quite close together to not make a material difference, and I would suggest either removing one, or reconsider the sizes with trending breakpoints in mind, so that perhaps we have Large at closer to 1536px. By trending, I mean if zooming out on the last 5 years of the statcounter site, the 1536x864 is moving higher, whilst the 1366x768 is moving down:

Having a set of reference sizes is really useful for designers, especially when based on common used sizes. What is not clear to me is that the breakpoints should match exactly those reference sizes.

Defining breakpoints creates a set of ranges of sizes in which the design layout will be optimized for those sizes. An aspect that may be problematic is to define the breakpoints in a way that leaves the reference sizes at the very extreme of the ranges. This means that sizes that are very close to a reference size can get a design that is less optimized for them. For example, 1920px wide screens seem to be the most common desktop size based on the data above and is the reference size for the XL size, however a user that has a browser window that is not full-width (e.g., 1910px) will get the L version of the design which was optimized for a smaller L size (1366px).

These variations in sizes can exist for different reasons such as window size being different (smaller) than screen size or device diversity.

I think it may be more useful to have the reference sizes more centered in the ranges the breakpoints define. In that way when designing for a reference size, devices in the same category (slightly larger or smaller than the reference) will get the experience designed for their category. There is an article covering this idea in more length.

Based on last comments from @Pginer-WMF and @RHo I've been working on a new proposal aligning the breakpoints not with the right value of the most used screens but using these most used screen sizes as midpoint of each breakpoint (as explained in in this article sent by @Pginer-WMF ).

The breakpoints based on the midpoints of these most used screen sizes would be:

• breakpoint-L 1680px and more
• breakpoint-M 1120px - 1799px
• breakpoint -S 640px - 1119px
• breakpoint-XS 320px - 639px

{F35258903}

With this new proposal where the most used screens are at the midpoint of each breakpoint (view here):

• We cover more screen sizes with fewer breakpoints. In this proposal we use 4 breakpoints while in the previous proposal we used 5 breakpoints (the 5 one was used for the 1200px one).
• We cover a larger number of screen sizes as each breakpoint covers several important screen sizes. Also, the most used screens have been tested here and we can view that all them are well covered with these breakpoints.
• We don't have very approximate breakpoints (as we had in the previous proposal @RHo where breakpoint-L and breakpoint-M were so close)
• We cover important use cases as the ToC one @alexhollender_WMF (in 1280px screens we would use the breakpoint-M and the ToC would be a bit narrow but I think it could work)

{F35258981}

Thanks @bmartinezcalvo, this latest proposal with four breakpoints looks good to me!
Though I think there is a typo on breakpoint-M - I assume the range should be 1120px to 1679px (not 1799px as it is currently in the mock and figma)... is that right?

In T303522#8019834, @RHo wrote:

Thanks @bmartinezcalvo, this latest proposal with four breakpoints looks good to me!
Though I think there is a typo on breakpoint-M - I assume the range should be 1120px to 1679px (not 1799px as it is currently in the mock and figma)... is that right?

@RHo oh yes, it was a mistake. Updated with 1679px. Thank you Rita!

{F35265198}

The last proposal makes perfect sense to me. Thanks for iterating on this, @bmartinezcalvo.

On specific projects I think the current responsive adjustments for Content and Section Translation can be well adapted to the new break points.

As next steps, it would be great to include the final proposal in the task description above (maybe simplifying/structuring the existing contents since it seems a long description already).

In T303522#8005415, @Pginer-WMF wrote:

Having a set of reference sizes is really useful for designers, especially when based on common used sizes. What is not clear to me is that the breakpoints should match exactly those reference sizes.

Defining breakpoints creates a set of ranges of sizes in which the design layout will be optimized for those sizes. An aspect that may be problematic is to define the breakpoints in a way that leaves the reference sizes at the very extreme of the ranges. This means that sizes that are very close to a reference size can get a design that is less optimized for them. For example, 1920px wide screens seem to be the most common desktop size based on the data above and is the reference size for the XL size, however a user that has a browser window that is not full-width (e.g., 1910px) will get the L version of the design which was optimized for a smaller L size (1366px).

These variations in sizes can exist for different reasons such as window size being different (smaller) than screen size or device diversity.

I think it may be more useful to have the reference sizes more centered in the ranges the breakpoints define. In that way when designing for a reference size, devices in the same category (slightly larger or smaller than the reference) will get the experience designed for their category. There is an article covering this idea in more length.

I understand that notion and think for “tablet” plus sizes onwards this makes sense. Material uses a similar approach in their responsive layout grid, after having featured both, a device agnostic and a strongly device centered approach for years. Personally I'm not fully convinced about the fluid sizes in a mobile/tablet environment as the vast majority of cases is featuring a full-screen window there (split screens the exception) and 640px is very small for any two content streams (main content & sidebar) and will probably be triggered in too many cases counter-productive to the users.

Another point is, that our legacy breakpoint tokens are strongly device boundary centered, so there's a risk of having two different breakpoints triggered in different products, given our mitigation strategy and usual maintenance. This is, again, an issue specifically in smaller viewports.
Therefore I'd propose to increase the 640px to 720px to have lesser implementation risk here.

@Volker_E keep in mind that if we increase the breakpoint-XS to 719px, then 640-670px screens will use the breakpoint-XS and in some cases the content would be so expanded in the screen, e.g. in the info box of the article content where it would be full width.

Here you can compare both proposals:

• Option 1: breakpoint-XS from 320-639px
• Option 2: breakpoint-XS 320-719px

I think Option 1 (320-639px) is the best option to avoid this kind of expanded content.

In understand that concern of extra long infoboxes and that's not optimal. Would like to try a counter argument for consideration:
Mobile frontend/Minerva Neue currently features a single article content column with the infobox taking full width at 640px:

Barack Obama English	German Wikipedia

But you also end up, on infobox-heavy articles with

With this I'd definitely involve Web team to the hardening the decision about tablet breakpoint moving forward. cc: @alexhollender_WMF.
Next I'll provide a WIP patch for the currently outlined breakpoints.

In T303522#8084812, @Volker_E wrote:

In understand that concern of extra long infoboxes and that's not optimal. Would like to try a counter argument for consideration:
Mobile frontend/Minerva Neue currently features a single article content column with the infobox taking full width at 640px:
This results in a line-length of around 78 characters in English, which is about aligned to our own guideline of max 75 chars.

@Volker_E if we apply the breakpoint-S (tablet) on 667px screens the article content would have 96 characters in each line, so we would be exceeding the maximum 75 characters defined in our DSG.

Here you can compare both breakpoint-XS and breakpoint-S applied on 667px and 640px screens.

But you also end up, on infobox-heavy articles with

, which I'm not convinced is a better solution than one full-width column.

With this I'd definitely involve Web team to the hardening the decision about tablet breakpoint moving forward. cc: @alexhollender_WMF.
Next I'll provide a WIP patch for the currently outlined breakpoints.

@Volker_E in that extreme case we could simply hide the long info as we have in desktop where the user can show/hide the info box list:

On the implementation side of the Figma designs:

1. We should have minimum and maximum breakpoints. We'll need both in implementation at times, for example in Desktop Improvements, not a range as one token
   1. This would also help us with the legacy tokens side-by-side moving forward with bringing Codex tokens to be used in WikimediaUI Base
2. I feel strongly about not using t-shirt sizes for media queries. It's such a lookup pain in the a** for devs:

Look at that code example from Vector 2022:

	#left-navigation {
		// Layout correction - as it was before introduce of flex box.
		@media ( min-width: @min-width-desktop-wide ) {
			margin-left: @border-base-ems * 3;
		}
	}

	.mw-portlet-views {
		display: none;

		@media ( min-width: @min-width-tablet ) {
			&:not( .emptyPortlet ) {
				display: block;
			}
		}
	}

	.vector-more-collapsible-item {
		display: block;

		@media ( min-width: @min-width-tablet ) {
			display: none;
		}
	}

	// Make sure pcactions is displayed (even if .emptyPortlet present)
	.vector-has-collapsible-items {
		@media ( max-width: @max-width-mobile ) {
			display: block;
		}
	}

Versus the current proposal. It's so confusing what's meant here:

	#left-navigation {
		display: flex;

		// Layout correction - as it was before introduce of flex box.
		@media ( min-width: @min-width-breakpoint-l ) {
			margin-left: @border-base-ems * 3;
		}
	}

	.mw-portlet-views {
		display: none;

		@media ( min-width: @min-width-breakpoint-s ) {
			&:not( .emptyPortlet ) {
				display: block;
			}
		}
	}

	.vector-more-collapsible-item {
		display: block;

		@media ( min-width: @min-width-breakpoint-s ) {
			display: none;
		}
	}

	// Make sure pcactions is displayed (even if .emptyPortlet present)
	.vector-has-collapsible-items {
		@media ( max-width: @max-width-breakpoint-xs ) {
			display: block;
		}
	}

I highly recommend to remain with named device type media queries to make quick orientation possible and improve developer experience.

Change 815343 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] tokens: Add design-first breakpoints tokens

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

In T303522#8088576, @Volker_E wrote:

On the implementation side of the Figma designs:

1. We should have minimum and maximum breakpoints. We'll need both in implementation at times, for example in Desktop Improvements, not a range as one token
   1. This would also help us with the legacy tokens side-by-side moving forward with bringing Codex tokens to be used in WikimediaUI Base
2. I feel strongly about not using t-shirt sizes for media queries. It's such a lookup pain in the a** for devs:

@Volker_E I understand the reasons for not to use the t-shirt sizes nomenclature and reading the code example you added in your last comment it's true the t-shirt sizes are lost among the rest of code since they are single letters. But I don't agree with using the decides names for breakpoints since, as I explained some time ago
these breakpoints are not necessarily for a single device type (e.g. the current breakpoint-S could be used for both portrait tablets and some landscape mobiles) so I wouldn't relate the names directly with a single device.

I propose to use this new nomenclature, that moreover is the one we use for other tokens to represent scales (like in Shadows:

New breakpoints:

• @min-width-breakpoint-large
• @min-width-breakpoint-medium
• @min-width-breakpoint-small
• @min-width-breakpoint-extra-small

Legacy breakpoints:

• @min-width-breakpoint-legacy-extra-large
• @min-width-breakpoint-legacy-large
• @min-width-breakpoint-legacy-medium
• @min-width-breakpoint-legacy-small
• @min-width-breakpoint-legacy-extra-small

Regarding the minimum and maximum breakpoints, I've added the min in each breakpoint name but not sure if breakpoint-large should be the maximum one (although is the bigger) since 1680px is the value this breakpoint starts from, but it can be scaled to any screen size above this value so there would be no exact maximum size for the largest breakpoint. If what we want is to determine the minimum and maximum value according to the existing screen sizes, the minimum value would be the smallest screen (320px) and the maximum the largest screen (2560px for now). For this reason, the breakpoints were created taking into account the smallest 320px screens and the biggest 2560px screens.

In T303522#8090543, @bmartinezcalvo wrote:

In T303522#8088576, @Volker_E wrote:

On the implementation side of the Figma designs:

1. We should have minimum and maximum breakpoints. We'll need both in implementation at times, for example in Desktop Improvements, not a range as one token
   1. This would also help us with the legacy tokens side-by-side moving forward with bringing Codex tokens to be used in WikimediaUI Base
2. I feel strongly about not using t-shirt sizes for media queries. It's such a lookup pain in the a** for devs:

@Volker_E I understand the reasons for not to use the t-shirt sizes nomenclature and reading the code example you added in your last comment it's true the t-shirt sizes are lost among the rest of code since they are single letters. But I don't agree with using the decides names for breakpoints since, as I explained some time ago
these breakpoints are not necessarily for a single device type (e.g. the current breakpoint-S could be used for both portrait tablets and some landscape mobiles) so I wouldn't relate the names directly with a single device.

IMHO it doesn't matter if they are not grouping perfectly, the improvement over t-shirt sizes is, that devs, even without knowing the t-shirts pointers, immediately understand the tokens applied. It's fine to have certain big landscape mobile canvases in tablet as it's the size where we're offering a different layout.

I propose to use this new nomenclature, that moreover is the one we use for other tokens to represent scales (like in Shadows:

New breakpoints:

• @min-width-breakpoint-large
• @min-width-breakpoint-medium
• @min-width-breakpoint-small
• @min-width-breakpoint-extra-small

Legacy breakpoints:

• @min-width-breakpoint-legacy-extra-large
• @min-width-breakpoint-legacy-large
• @min-width-breakpoint-legacy-medium
• @min-width-breakpoint-legacy-small
• @min-width-breakpoint-legacy-extra-small

That's not different than before, it's just the terminology expanded. Nobody knows what's hiding between medium, small or extra-small and media queries are especially hard to work with already.
I'd like to get more eyes on this problem, without IDE value lookup support, this is a blocker for me. cc: @Catrope @AnneT @egardner

Regarding the minimum and maximum breakpoints, I've added the min in each breakpoint name but not sure if breakpoint-large should be the maximum one (although is the bigger) since 1680px is the value this breakpoint starts from, but it can be scaled to any screen size above this value so there would be no exact maximum size for the largest breakpoint. If what we want is to determine the minimum and maximum value according to the existing screen sizes, the minimum value would be the smallest screen (320px) and the maximum the largest screen (2560px for now). For this reason, the breakpoints were created taking into account the smallest 320px screens and the biggest 2560px screens.

We don't need a @max-width-breakpoint-desktop-wide one.

I second Volker's argument that the t-shirt/size based token names make it really difficult to work with the tokens when writing code—I would have to look up what the tokens meant every time. I definitely see Bárbara's point that the breakpoints don't exactly map to specific devices, but I still think the t-shirt or size names aren't sufficient.

How do other design systems solve this problem? Is there a way we can name the tokens more meaningfully without relying on outdated assumptions of what devices sizes are?

In T303522#8094785, @AnneT wrote:

How do other design systems solve this problem? Is there a way we can name the tokens more meaningfully without relying on outdated assumptions of what devices sizes are?

@AnneT I send you other design systems where they use the sizes too for breakpoint names:

• Carbono IBM
• Fluent Microsoft
• Material Android
• Polaris Shopify (here they even use t-shirt sizes)

I can't find any other design system where they use devices, if you have any reference please send it.

In T303522#8094785, @AnneT wrote:

How do other design systems solve this problem? Is there a way we can name the tokens more meaningfully without relying on outdated assumptions of what devices sizes are?

t-shirt sizes seem to be used in common UI frameworks such as bootstrap. An alternative approach that hints at the devices but uses names of more general categories was used by csswizardry and consists of "palm", "lap" and "desk" (also defining "portable" as "palm" = "lap", and a "regular" size to cover all sizes):

• palm -- palm-based devices, like phones and small tablets
• lap -- lap-based devices, like iPads or laptops
• portable -- all of the above
• desk -- stationary devices, like desktop computers
• regular -- any/all types of device

Not sure if something like this could help solve both kinds of concerns, but sharing in case it helps spark new ideas.

Sounds like this task is blocked until we make a decision on naming conventions - should we split the decision into its own subtask @Volker_E ? And would a synchronous discussion help?

@ldelench_wmf We've had talked about this task in the last design meeting, with @AnneT and @NHillard-WMF there as well. We've come to an agreement and the next step is updating the patch with an ADR about our agreement alongside the code change.

In T303522#8097973, @ldelench_wmf wrote:

Sounds like this task is blocked until we make a decision on naming conventions - should we split the decision into its own subtask @Volker_E ? And would a synchronous discussion help?

@ldelench_wmf as Volker comments, we decided to move forward with devices names during the last DS design sync so I updated the Figma spec sheet with the new devices nomenclature for breakpoints.

Change 815343 merged by jenkins-bot:

[design/codex@main] tokens: Add design-first breakpoints tokens

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

On breakpoint token demo: A table like mentioned in task description currently doesn't make sense without Grids. We already feature tabular presentation in place.
One way I could see a low-leve breakpoint visualization would be a flat scale from 0-2000px, with the min and max values connecting as lines above.
But that would mean an extra wide page and not much gain.

Another possibility could be to have a simple table

Anyways we should carve possible further needs out of this extra long task here and move them to the Codex documentation task or a subtask.

Change 826407 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] styles, demo: Use Codex breakpoint token

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

Change 826407 merged by jenkins-bot:

[design/codex@main] styles, demo: Use Codex breakpoint token

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

All looks good to me. Moving task to QTE sign-off.

Moving this to Product sign-off, as QTE sign-off is not really required here.

Change 828083 had a related patch set uploaded (by Catrope; author: Catrope):

[mediawiki/core@master] Update Codex from v0.1.0-alpha.10 to v0.1.0

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

Change 828083 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.1.0-alpha.10 to v0.1.1

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

Product sign-off complete