Material-ui: Avoid docs layout jump (caused by the ad)

[Janpot]

Every time I open the docs, the page jumps around whenever the ad loads. This is kind of disruptive.

• [x] The issue is present in the latest release.
• [x] I have searched the issues of this repository and believe that this is not a duplicate.

Current Behavior 😯

The page slides down when the ad loads

Expected Behavior 🤔

Ideally, a placeholder is shown, or space is reserved for where the ad will appear. This way the page content doesn't slide down when it loads and it doesn't disrupt the reading experience (I understand that disrupting the reader is the purpose of ads, but I don't think it should be the purpose of the docs).
Maybe the new skeleton component can be used for this?

Steps to Reproduce 🕹

Steps:

1. open the docs
2. observe

Context 🔦

Just trying to find answers in the docs in the most pleasant and effective way.

There is also a secondary issue, when you have dark theme enabled, there's a FOLC (flash of light-themed content 🙂) on page load.

Your Environment 🌎

Screenshots were generated in chrome

[oliviertassinari]

@Janpot Interesting concern, the jump was a concern I took into account when implementing the ad placement. It was simpler to implement this way, and had the potential to perform better. But maybe it's not needed, to A/B test without.

[eps1lon]

But maybe it's not needed, to A/B test without.

What target would you test how? Because popups do increase attention and revenue. They are however annoying and reduce satisfaction.

[Janpot]

Oh wow, I would never have expected this to be intentional. Maybe you could add the behavior, only when the ad-blocker is enabled?

@Janpot Interesting concern, the jump was engineered to increase people's attention. But maybe it's not needed, to A/B test without.

I'm not unsympathetic towards you using advertisement. But not in this way, I will put the ad-blocker back on until this is resolved.

[oliviertassinari]

The other reason why the jump is present is that it was simpler to implement. I don't know how an implementation without it would look like. Please understand that ads are a big part of why this project can sustain ongoing development. And yes, the other motivation was to reproduce Bootstrap approach to the problem, they generate significantly more than we do with ads, I hopped they have this concern a serious look.

Regarding the A/B test, the approach would be to change the behavior at 100% and compare the CTR for a month.

[eps1lon]

Regarding the A/B test, the approach would be to change the behavior at 100% and compare the CTR for a month.

This too shortterm to monitor user satisfaction among long term users. It also disregards any revenue created from opencollective etc. It also assumes that the clicks are intentional. I could imagine that a proportion of the current clicks are unintentional since the layout shifts.

[oliviertassinari]

How long do you think that we should run the experiment?

[Janpot]

You could also incentivize people to disable their adblocker by making it clear the page won't shift when ads are enabled. Who knows, maybe this has a net positive effect?

[oliviertassinari]

On a second order of thinking, there is an option to force a layout shift no matter if the ad blocker is used or not. This would reduce the incentive to use an ad blocker. However, given that the strategy is to move toward a freemium model, with an open core (paid advanced components) Material-UI has a growing incentive to make the free content experience as smooth as possible, hence solve this jump issue.

[eps1lon]

How long do you think that we should run the experiment?

I would not put time into an experiment that tries to gain insights into layout shifts. We know these are very bad¹. I'd rather put time into improving Material-UI so that people want to pay instead getting Ads money from flashing the screen.

¹ Quick google search:

• https://github.com/WICG/layout-instability
• https://developers.google.com/web/fundamentals/performance/user-centric-performance-metrics#user-centric_performance_metrics
• https://css-tricks.com/content-jumping-avoid/

[oliviertassinari]

I'm even wondering if the current jump doesn't violate the nonintrusive whitelisting adblocker policy our ad benefit from (as well as Bootstrap). I have updated my initial comment: the first incentive was to get the implementation working fast, to move to a different problem (I ignored the shift)

Yeah, there is no question that a jump destroys the browsing experience. Now, maybe the solution to this problem is identical to the dark mode flash, it's less noticeable on the Bootstrap side because the page is interactive sooner.

[oliviertassinari]

Actually, I will double down on this:

maybe the solution to this problem is identical to the dark mode flash

The problem is more visible on the initial page load, not between consequence page navigations. So as it seems, the jump wasn't engineered, or I engineered it poorly.

[eps1lon]

maybe the solution to this problem is identical to the dark mode flash

I was not aware that the dark mode flash causes a layout shift. Seems like something we should address since dark mode shouldn't be concerned with layout.

[Janpot]

With the risk of piling more issues on top here, but since we're talking about the dark mode flash. Didn't the "custom doc colours" used to persist between page loads in the past? I feel like I've seen that make a flash from default to custom as well, but I can't reproduce anymore.

[eps1lon]

@Janpot This is an issue with how we serve our docs. If you have a page with different themes you also have to ensure that the server can serve those themes if you want no flashes. For simplicity we only serve the default theme from the server and allow switching on the client. This will always include a little flash since there is a period between html being rendered and javascript being executed.

Since we don't use CSS media queries for the colors but listen to media queries and then change themes accordingly you'll always have some flash when landing on a page even with OS wide dark mode.

Once landed it shouldn't flash when navigating via links though.

[Janpot]

Just for my understanding, in case I ever need to implement this

This is an issue with how we serve our docs.

Which is to store the theme state in localStorage and SSR the docs? For which the solution would be to store the theme state in a cookie?

[eps1lon]

Which is to store the theme state in localStorage and SSR the docs? For which the solution would be to store the theme state in a cookie?

If you have a server that receives requests and renders that page and then serves it, yes.

Our docs are rendered as a static site though which means we wouldn't be able to process cookies from requests.

[oliviertassinari]

@Janpot What do you think of this fix?

diff --git a/docs/src/modules/components/Ad.js b/docs/src/modules/components/Ad.js
index 57ac3c966..07c133574 100644
--- a/docs/src/modules/components/Ad.js
+++ b/docs/src/modules/components/Ad.js
@@ -10,7 +10,7 @@ import AdCarbon from 'docs/src/modules/components/AdCarbon';
 const styles = theme => ({
   root: {
     position: 'relative',
-    minHeight: 116,
+    minHeight: 124,
     maxWidth: 345,
     display: 'block',
     marginTop: theme.spacing(4),

From what I can observe, we have 2 jumps. 1. The first jump comes from the initial page load, the page jumps as soon as React hydration complete. 2. The second jump happens once the ad is loaded.

The above diff should eliminate 2. Now, assuming? that we have, on average 5 client-side navigations for each server-side navigation. We should have fix +80% (5/6) of the problem. Should we stop here and move to the next problem?

To solve 1. a possible approach is to add more margin-bottom to .description class name, and to reduce it as soon as the placeholder is injected, we should be able to solve 100% of the problem with this additional change. Do you want to work on it? :)

---

I was not aware that the dark mode flash causes a layout shift. Seems like something we should address since dark mode shouldn't be concerned with layout.

@eps1lon Agree, me neither. The point I want to develop is that the root cause of the layout jump and the layout flash might be identical: a hydration duration that is long enough to be noticeable, on desktop. Bootstrap has put me on this path as the jump disrupts me less than on our documentation.

[Janpot]

Should we stop here and move to the next problem?

I'd have to see it live first, but if I'm honest, I have a feeling that the jump I'm seeing, the disruptive one, is greater than 8 pixels. Other people's browsing patterns may differ, but I quite often navigate to docs pages directly as often the page I want to access is still fresh in my history. So oftentimes it appears in my omnibox when I start typing "mat".

[oliviertassinari]

@Janpot It makes sense, I have updated my comment to include a mention to a .description patch to solve jump 1.