Avoid duplication of utility classes in primer/marketing

[tobiasahlin]

The problem

primer/marketing uses a spacing scale that goes further (1-12) than primer proper (1-6). Since all sizing classes can be overridden at certain breakpoints (mt-3 mt-md-5 mt-lg-7), these utility classes need to be generated in a specific order:

• Global first (mt-3)
• Followed by the next breakpoint (mt-sm-3)
• Followed by the next breakpoint (mt-md-3), and so on, so forth

This means that we can't generate the primer proper utility classes (1-6) in primer and then just extend these in primer/marketing: mt-9 will unexpectedly override mt-md-3 (wrong), but not mt-md-7 (correct). For this reason, we're currently generating full scales of utility classes (1-12) in primer/marketing, overriding the primer spacing utilities, and making their inclusion in primer effectively redundant while using primer/marketing. This produces a bigger CSS bundle than necessary, but also a fragmented setup where it can be difficult to get a sense of which utility classes that exists, where, and if there are gaps in our utility class coverage or not.

Possible solutions

While exploring this problem with @simurai, we discussed some possible ways of solving this:

1. Move all marketing variables to primer/primitives, but then make primer/marketing include all of primer (generated with the same set of primitives). This would enable us to load the primer/marketing bundle instead of the primer bundle on marketing pages, removing all potential overlap. It would also reduce render-blocking requests by one on marketing pages. (For what it's worth, we could check if the primer/marketing bundle is being loaded in the application controller, and if so always exclude the primer bundle to make sure that both are never loaded). Caching would be worse with this setup (the primer bundles wouldn't be shared at all between product and marketing pages), but it might not be a significant performance hit.
2. Extend primer to include the "marketing" spacing scale, and only use the marketing bundle to include other types of utilities, not extensions of the scales. This would undoubtedly increase the size of the primer bundle somewhat, but would keep our current separation of bundles, that apart from this issue seems to work well (?)
3. Probably not a good idea, but we could keep the current setup but use multiple instances of !important, and explicitly define the scales with higher and higher specificity for each breaking point modifier, i.e. producing .mt-sm-3 { … !important }, .mt-md-3 { … !important !important }, and .mt-lg-3 { … !important !important !important },etc. This would be a complete mess to override, but would go around the problem by not relying on the order of selectors at all.

Are there other ways of solving this that we should outline? Are some of the outlined options worth exploring?

[yaili]

@vdepizzol is this case considered in your latest sizing scale proposal? 🙂

[vdepizzol]

@yaili I think this issue is happening regardless of my spacing proposal 😅.... with that said I think there is an opportunity to make these changes in sync with those new spacing considerations if the marketing team also considers there's a benefit in updating the current 7–12 scale.

👋 @tobiasahlin a few comments:

1. Move all marketing variables to primer/primitives, but then make primer/marketing include all of primer (generated with the same set of primitives).

My only concern is making github.com feel slower for users because of the different bundles they have to request while navigating between marketing and non-marketing pages. I'm curious in hearing more about this, maybe I'm not picturing other potential benefits... How big is the entire primer bundle?

2. Extend primer to include the "marketing" spacing scale, and only use the marketing bundle to include other types of utilities, not extensions of the scales.

I'm interested in seeing how this could play out, because if it ends up being a lightweight solution, it could work quite well in terms of implementation, and wouldn't require two different requests of primer altogether.

I've tried to calculate what that would actually mean in terms of size... and here's my estimate:

• Considering our current Primer scale goes from 0 to 6;
• Considering all current margin and padding CSS rules (including all shorthand conventions and responsive variants) weight around 22kb¹ uncompressed when minified;
• Considering we gzip while transporting our assets, that weight lowers to 2.64 KB¹;
• Then each added number to our scale would cost around 0.37kb (2.64kb / 7). Adding 6 more numbers to the scale (7–12) would mean adding a total of ~2.59kb. 😆

This number would probably be cut by a lot considering marketing margins only have responsive variants for mt-*, mb-*, and my-*³.

Also, we could be prescriptive about not supporting all breakpoints for the larger numbers, since those might not be used in the smaller breakpoints. That would also lower the total size if that's a concern.

3. Probably not a good idea, but we could keep the current setup but use multiple instances of !important

Agh, I agree that's probably not a good idea 😝

Let me know your thoughts! ✨ ✨

Footnotes

1. I'm using https://refresh-sf.com/ to make the uncompressed and gzip estimates.
2. "Note: Only the y-axis (mt, mb and my) and its responsive variants are supported." — Primer / Marketing margin

[tobiasahlin]

Talking about 1:

My only concern is making github.com feel slower for users because of the different bundles they have to request while navigating between marketing and non-marketing pages. I'm curious in hearing more about this, maybe I'm not picturing other potential benefits... How big is the entire primer bundle?

The entire frameworks bundle on .com (which is mostly primer) is 45.2kb gzipped. All shared marketing styles (where primer/marketing is ~half) is 14.2kb gzipped. Going down this route would certainly add a big chunk of CSS that we wouldn't be able to cache and share between logged out and logged in. It also adds some new potential headaches, where we have the same solution living in two different places.

Talking about 2:

I'm interested in seeing how this could play out, because if it ends up being a lightweight solution, it could work quite well in terms of implementation, and wouldn't require two different requests of primer altogether.

I love this thinking, and it's definitely one of the easiest ways to detangle this duplication ✨ the more I think about it, the more I'd love to try this route. We may want to keep the separate marketing bundle for styles that we by design want to keep out from the product (like certain types of shadows, typography, etc.), but not splitting up any spacing scales as an architectural design decision makes a lot of sense to me.

This number would probably be cut by a lot considering marketing margins only have responsive variants for mt-, mb-, and my-*3.

We also need to take into consideration that we're also extending the negative margin utilities in primer/marketing (right now only outside of the bundle), but either way, per your assessment, the extra weight added to primer should be relatively small. Let's open an experimental PR and assess the impact? ✨

[jonrohan]

@tobiasahlin did you fix this issue or is it still relevant?

[tobiasahlin]

@jonrohan this is still relevant 🙏 I'm working on a PR but a bit unsure how to extend the scales in the most elegant way, since we e.g. only want to do it for top and bottom for margins and paddings, and not sideways. I'll open it up for discussion!

[tobiasahlin]

Fixed in #1372 ✨