Usage of cutting-edge `:where` selector broken in old browsers

[guyskk]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Button style css :where selector is experimental feature and broken in many browsers. Can reproduce by visit https://docusaurus.io/ in some old version browser, the "Get Started" and "Try a Demo" button style is broken.

And I checked the css file, seems no needs to use :where selector, change them to simple css selector can fix the issue.

:where(.button--primary) {
    --ifm-button-background-color: var(--ifm-color-primary);
    --ifm-button-border-color: var(--ifm-color-primary);
}

:where(.button--primary):not(.button--outline):hover {
    --ifm-button-background-color: var(--ifm-color-primary-dark);
    --ifm-button-border-color: var(--ifm-color-primary-dark)
}

:where(.button--secondary) {
    --ifm-button-background-color: var(--ifm-color-secondary);
    --ifm-button-border-color: var(--ifm-color-secondary)
}

:where(.button--secondary):not(.button--outline):hover {
    --ifm-button-background-color: var(--ifm-color-secondary-dark);
    --ifm-button-border-color: var(--ifm-color-secondary-dark)
}

See also: https://caniuse.com/?search=where

Reproducible demo

https://docusaurus.io/

Steps to reproduce

1. Visit https://docusaurus.io/ in chrome older than version 87, or other old version browsers
2. Check the button style

Expected behavior

Expect the Button style is same as the style show in latest browser.

Actual behavior

The Button style not work, no background color.

Your environment

• Public source code: N/A
• Public site URL: https://docusaurus.io/
• Docusaurus version used: 2.0.0-beta.21
• Environment name and version: the browser in Wechat, it seems based on an old version chrome.
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Android

Self-service

• I'd be willing to fix this bug myself.

[Josh-Cena]

cf facebookincubator/infima#243 for our decision-making and #7455 for further discussions on this.

Why would anyone even use a Chrome that's not the latest version (and in fact 15 versions behind the latest)? Is there anything preventing you from upgrading? Web dev these days kind of assumes that you are on a reasonably new version as long as you are using Chrome/Firefox/Safari (hence the name evergreen).

[guyskk]

@Josh-Cena The first version support css where selector was released in Jan 2021, less than 2 years. And Caniuse shows only 56% users in China use newer version browsers, it needs more time to complete upgrade.

[Josh-Cena]

Yes—but out of the rest 44%, probably <3% read websites set up with Docusaurus (most of them are state-affiliated organizations). I'm pretty optimistic about supporting only recent versions, and I'm simply curious about you as a particular user who's using an outdated browser, not the general picture of how many people may be affected. This will help us make decisions in #7455.

Also—I'm really curious about that 56% figure. For my own education, can I get a link please?

[guyskk]

The usage figure from https://caniuse.com/?search=where , maybe need change settings to view China region data.

I can not tell how many users affected, the bug was first reported by one of my customer. I think many people simply use Wechat to open links sent by friends, most of them are affected.

It's fine to keep the issue open, if other people run into the same issue, they will 👍 here.

[Josh-Cena]

Ah—I see. I still had to manually add a "China" filter, not sure why.

No problem, we can leave it open for now, since the discussion of browser support is still underway.

[slorber]

😬 this is annoying, cc @lex111

We also introduced flex gap property, which is not very well supported in China

https://caniuse.com/?search=gap

In the future, we should probably whitelist new CSS features one by one to mark them as safe to use after some study 🤷‍♂️

In the meantime, I'm not sure it would be nice to revert all our modern CSS changes.

But maybe we can revert the critical issues that prevent a decent usage of the Docusaurus site?

Now it's also worth considering what is a "critical issue"? Maybe inaccessible labels are critical, but bad spacing due to missing flex gaps is not a big deal?

Do you see many other things in a Docusaurus site that appears broken on older browsers, apart those buttons?

---

Yes—but out of the rest 44%, probably <3% read websites set up with Docusaurus (most of them are state-affiliated organizations).

I don't know how it works in China. Are large organizations freezing their desktop employees to a fixed version?

[Josh-Cena]

I think it happens in other countries as well—state-affiliated organizations are especially slow to migrate to modern IT infrastructure because of worries of security, legal issues, financing, politics, software compatibility, etc. (e.g. there are many British hospitals still using Windows XP + IE.) But these people have a particularly big share in the Chinese market.

Now, whether individuals fail to upgrade their browsers I don't know, because the privilege I enjoy is probably disproportionate compared to most Chinese people. But from my observation, the actual Docusaurus users in China mostly work at Internet giants like Alibaba & ByteDance, and both site creators and users of these sites usually have access to modern browsers.

[romainmenke]

But from my observation, the actual Docusaurus users in China mostly work at Internet giants like Alibaba & ByteDance, and both site creators and users of these sites usually have access to modern browsers.

Have you adjusted for survivors bias?

[Josh-Cena]

If I understand you correctly—you are saying those that don't have access to modern browsers and/or those that need to target ancient browsers are excluded from Docusaurus' audience in the first place. Yes, that's a fair point. But, what do we actually aim for?

1. Do we want to maximize user accessibility (in terms of browser compatibility)?
2. Do we want to maximize site creators' DX (by making the CSS as easy to reason about as possible)?
3. Do we want to make the best optimizations (by stripping all "unnecessary" CSS like @supports queries)?

Docusaurus primarily goes towards (2) and (3). It doesn't mean (1) is unimportant—but you have to look into the comparative. Most JavaScript bundle can still be downleveled, so this problem is very limited in scope and impact. Also, we have to do actual user portraits—how many users visiting Docusaurus websites are actually using outdated browsers? Are they our intended audience? Do we want to make these people happy at the cost of making CSS overriding harder and/or penalizing everyone with bigger bundles?

When I say "the actual Docusaurus users in China", it's not purely an a posteriori assertion. Docusaurus is not a general-purpose site builder—its design goals have naturally created a niche user base. Our main focus is on technical, or tech-oriented, documentation, intended for open-source projects and personal tech blogs. Keeping this goal in mind, we drew the conclusion that readers of the site are also those that are interested in technology. If you are using Docusaurus for a government landing page or service panel where your users can be on all kinds of devices, Docusaurus is probably not the best choice.