Dark mode: requirements and proposals

[SiAdcock]

Currently we support dark mode in apps and it's inevitable that web will follow. Source components will need to support dark mode. It would be useful to define patterns allowing all our web products to provide dark mode support in a consistent way.

Possible requirements

List what possible requirements we need to consider for a dark mode solution.

Defining colour schemes

• Use of built-in platform features (i.e. the prefers-color-scheme media feature)
• Avoid re-renders
• Avoid sending unused CSS
• Allow users to opt in and out of dark mode using a toggle, regardless of platform-level preferences
• Tech agnostic (e.g. doesn't rely on Emotion)

Source components

• During a transition phase when some but not all consuming applications offer dark mode support, Source should allow consumers to opt in to dark mode variants.

Possible solutions

• darkModeCss currently used in apps-rendering
• User preference media features client hints headers
• supportsDarkMode prop for all Source components. When set to true by the platform, component may ship dark mode CSS

Discussion

• Try to keep posts focussed on a single topic
• If someone has already raised a topic you'd like to discuss, consider replying directly to that post
• I will update this post with any new requirements or solutions
• The ultimate outcome of this discussion will be a list of possible solutions, and criteria by which we can assess them

Prior discussion

• create slim version of toggle switch #1029 (review)
• darkModeCss Helper #800
• Dark mode support #614

[oliverlloyd]

Avoid sending unused css

I think this should be a line in the sand for this requirement. Maybe splitting the cache is an acceptable way to achieve this? I think we could have a larger discussion about cache splitting (around logged in state specifically, but maybe other things) but, in short, maybe it's worth it?

Here's a good reference for an approach to enabling server side rendering of a page in the reader's desired colour scheme: https://web.dev/user-preference-media-features-headers/

[JamieB-gu]

I think there are two ways this issue could be interpreted?

1. Avoid sending unused CSS to platforms that don't support dark mode. This is the apps/dotcom problem, i.e. apps support dark mode and dotcom doesn't, but they want to use the same components. I think this can be solved on the server-side at least by having all shared components that provide dark mode variants take a supportsDarkMode prop. They only include the dark mode CSS if this prop is true.
2. Avoid sending unused CSS to a platform that does support dark mode. My understanding is that here you want to figure out what colour scheme a client is using at request-time and only serve the CSS for that scheme? So if it's in dark mode you don't serve the light mode CSS and vice versa? Presumably you still need to serve the CSS for the other colour scheme soon after initial load, because the client can swap between light and dark mode at any time?

[SiAdcock]

Here's a good reference for an approach to enabling server side rendering of a page in the reader's desired colour scheme: https://web.dev/user-preference-media-features-headers/

This is great, thanks @oliverlloyd for sharing. Source would need some way of flagging to consumers that some of its styles are dark mode, in order to allow consumers to decide between shipping this or the light mode styles.

Avoid sending unused CSS to platforms that don't support dark mode

This is interesting, we'd like to avoid Source components, for instance, being styled with a dark colour scheme while the rest of the application's UI uses the default light scheme.

Avoid sending unused CSS to a platform that does support dark mode

I think this is the most interesting and difficult point.

Presumably you still need to serve the CSS for the other colour scheme soon after initial load, because the client can swap between light and dark mode at any time?

Personally, I think this is an edge case that won't need covering. For instance, Google doesn't handle this currently, at least on OSX (EDIT: unless some smart person came up with a simple, low cost way of solving this problem by leveraging web platform features designed specifically for this purpose: see below 😅)

[oliverlloyd]

Presumably you still need to serve the CSS for the other colour scheme soon after initial load, because the client can swap between light and dark mode at any time?

We'd want to work through the flows for this, but perhaps we can avoid loading dark css when not needed using: <link rel="stylesheet" href="dark.css" media="(prefers-color-scheme: dark)" />?

[oliverlloyd]

Interestingly, using a media query on link doesn't prevent the non matching css from being downloaded, it only means that it will get downloaded with the lowest priority. So with

<head>
  <link rel="stylesheet" href="dark.css" media="(prefers-color-scheme: dark)" />
  <link rel="stylesheet" href="light.css" media="(prefers-color-scheme: light)" />
</head>

if the user prefers dark, then the browser will download dark.css with the highest priority but it will also download light.css but with the lowest priority.

Refs:
https://web.dev/prefers-color-scheme/
https://blog.tomayac.com/2018/11/08/why-browsers-download-stylesheets-with-non-matching-media-queries-180513/

[oliverlloyd]

I just did a very quick poc to see if we could:

1. Use link tags with media queries to avoid unused css on the critical path
2. Respect system preferences
3. Use css variables
4. Offer a toggle
5. Remember any toggle preference

It works. I simply have a dark.css and a light.css which both set the same css variables.

:root {
	--color: rgb(250, 250, 250);
	--background-color: rgb(5, 5, 5);
}

These css files are loaded in the head with

				<link
					rel="stylesheet"
					href="${CDN}static/frontend/css/dark.css"
					media="(prefers-color-scheme: dark)"
				/>

				<link
					rel="stylesheet"
					href="${CDN}static/frontend/css/light.css"
					media="(prefers-color-scheme: light)"
				/>

and then in decidePalette we can simply replace

const WHITE = neutral[100];
const BLACK = neutral[7];

with

const WHITE = 'var(--background-color)';
const BLACK = 'var(--color)';

and it carries through

Screen.Recording.2021-10-16.at.15.08.47.mov

Screen.Recording.2021-10-16.at.15.23.13.mov

I used a web component for the toggle

Problems with this implementation

Page refreshes cause a flash of unwanted styles. Either we think about cache splitting or implement a style dependency in the page load?

[SiAdcock]

This is very cool thanks for sharing @oliverlloyd .

In light of this, do you think it would be possible / make sense to avoid using colour names tied to hue and lightness within decidePalette?

Replacing:

const WHITE = neutral[100];
const BLACK = neutral[7];

const textStandfirst = (format: ArticleFormat): string => {
	if (format.design === ArticleDesign.LiveBlog) return WHITE;
	return BLACK;
};

With:

const TEXT = 'var(--color-text)';
const TEXT_INVERSE = 'var(--color-text-inverse)';

const textStandfirst = (format: ArticleFormat): string => {
	if (format.design === ArticleDesign.LiveBlog) return TEXT_INVERSE;
	return TEXT;
};

[oliverlloyd]

Yes, I very much agree with this. I think the shift to using css variables would be the perfect time to move over to a more tokenised approach to naming. So instead of yellow, use highlight.

That said, I think black might be an exception because there's an argument that we want to have a slightly off black black instead of pure neutral[0] and it's going to be useful to tokenise that. I guess this kind of thing starts building up layers of tokens that build upon the layer underneath, which is great.

I also think we could think about moving these decisions up. I think we want as many of these tokens to be exported from Source as possible. Not everything, there will be some colour decisions that are only needed for a specific platform and these can be kept local. I'm imagining each platform would have it's own decidePalette that imports a palette from source and then extends it?

[mxdvl]

Does the FOUC also happens when navigating between pages?

[oliverlloyd]

How to choose dark colours?

I think it's worth thinking about what steps would be needed to make the task of deciding the dark palette easier.

Centralise all colour decisions

Right now, in DCR, we make the vast majority of colour choices using decidePalette. But not all. Some simple greys that do not change based on format are still hard coded. That made sense where this value never changed but if we want to enable dark mode in the future then we would need all decisions to happen via palette.

This task would be simple. It's a chore but you could spread the work with a mob session.

Use Storybook as a design tool?

Maybe when the designers are building out dark.css they could be running storybook so that all the variations that an article can have are visualised dynamically as the colours change?

Controversial and possibly stupid question: Do we even need Figma designs?

Extend the layout storybook stories

We should exactly double the number of stories that we capture for each article layout.

So instead of having Design * Theme * Display number of stories, we would have Design * Theme * Display * Mode. This extra visual testing coverage would be essential to preventing regression in future

[mxdvl]

We’d want dark.css and light.css to be generated by JS, right?

Something like vanilla-extract might help with handling all the variables in all the themes.

[oliverlloyd]

Spike implementation

This branch has a spike with dark mode implemented on DCR.

https://github.com/guardian/dotcom-rendering/tree/oliver/dark-mode-poc

This spike is aiming to respect each of the points listed in the description above

• Use of built-in platform features (i.e. the prefers-color-scheme media feature)
• Avoid re-renders
• Avoid sending unused CSS
• Allow users to opt in and out of dark mode using a toggle, regardless of platform-level preferences
• Tech agnostic (e.g. doesn't rely on Emotion)

CSS Variables

I'm using css variables to provide the browser with a way to change styles without the need for a re-render.

Styles are split between two files, light.css and dark.css. Each file is scope to a class on the body tag, eg.: <body class="light">. This means we can use javascript to edit this class value and dynamically switch between light and dark modes.

This also means we don't depend on either React or Emotion so there's no Context and no re-render. Looking at twitter.com, it looks like they are not doing this and there's a re-render which isn't horrible, but isn't smooth like, say, https://overreacted.io/

Finally, by using css vars we have the option to add a small animation to color transitions, which is nice.

Link tags

The two different css files (dark and light) are loaded via link tags using a media query to ensure only the required css forms part of the critical path. Unused css is still loaded but with the lowest priority, This is useful as it enables mode switching.

Toggle

I'm using a web component provided by the Chrome team, dark-mode-toggle. It's actually quite nice and seems a viable option (it's restylable) but we could also implement our own.

It respects prefers-color-scheme automatically.

The only feature I added to this off the shelf solution is a listener that changes the class on the body tag when the toggle is clicked.

Support SSR

Dark mode + SSR is slightly tricky as the server needs to be aware of the mode the client is in. If not, you either have to delay the first render until you know their preference or you get flash of unstyled content.

There's a user preference header that gets sent based on a user's system preference, we can read that and decide what to render on the client. This header would also need to be added to the Vary header, splitting the cache.

Not solved

The user preference header contains the system setting but we also need to send any local, site specific, preference using that to override the system value. This is, I presume, possible with a cookie.

Change entire page background colour to further improve transitions

[mxdvl]

I like this implementation, but as I mention on cache splitting, there’s a lot that can be done with that minimal amount of JS in the <head>.

If it was a PR, I would add comments there.

Why are we not simply doing:

<link
	rel="stylesheet"
	href="${CDN}static/frontend/css/dark.css"
	media="(prefers-color-scheme: dark)"
/>

<link
	rel="stylesheet"
	href="${CDN}static/frontend/css/light.css"
	media="(prefers-color-scheme: light)"
/>

But need to pass the preference as a prop to the document?

[oliverlloyd]

That sounds like an extremely fair comment. I have a hazy recollection that the added complexity did do something but it's extremely possible there's a better way to achieve this - that spike was just a very rough exploration

[oliverlloyd]

Useful Reading

General

https://css-tricks.com/a-complete-guide-to-dark-mode-on-the-web/
https://web.dev/prefers-color-scheme/
https://markoskon.com/dark-mode-in-react/

Css Variables

https://epicreact.dev/css-variables/

Toggle

https://github.com/GoogleChromeLabs/dark-mode-toggle

Color Scheme

https://web.dev/color-scheme/
https://drafts.csswg.org/css-color-adjust/#color-scheme-prop
https://html.spec.whatwg.org/multipage/semantics.html#meta-color-scheme

User Preference Headers

https://web.dev/user-preference-media-features-headers/

[oliverlloyd]

Do we need to split the cache?

To prevent a flash of unstyled content I think we need to serve the user with html that already has the correct css inlined for their preferred mode, dark or light. If we don't do this, the browser will first render the default, light css, and then replace it with what it reads from the browser. Causing the flash.

The only other way to prevent this that I can think of - other than splitting the cache - is to delay rendering until we have the user's preference. Not ideal!

Are there other approaches?

[mxdvl]

I’ve added a performance measure… and the results on my (powerful) machine is less than half a millisecond. It’s probably not a bottleneck!

[bryophyta]

something to consider is that (as far as I'm aware) prefers-color-scheme is scoped to the browser, and presumably we would want to allow users to override their browser preference for our site (I do this on github, for instance).

If the user has expressed a preference before, we could store the value e.g. in localStorage and read it at the same time as (or, I guess, just before) the matchMedia query. When I've done this before I haven't noticed any significant rendering lag, but checking for and reading from localStorage might add a bit more overhead so I guess this should be factored in, if we go that route?

[bryophyta]

personally I like the method of setting a class at the top of the page, but just for reference I read this pretty in-depth article a while ago, where if I remember rightly the author actually has different css assets fetched using a similar js query before the page loads. tbh I think a lot of it went over my head at the time, and it's also been a little while, so I can't remember the details and claimed advantages, but thought I'd link it here for reference.

[bryophyta]

given recent discussions more broadly, it would also be interesting to see if either or both approaches could be fruitfully used at the edge... 🤔

[bryophyta]

(I hadn't realised that this thread was part of a much longer discussion, so I see now that that article and most of the rest of what I said has already been linked in the discussion above 🤦‍♂️)

[mxdvl]

Rollout strategy

I think we should consider what are essential requirements, and what can be added after an initial rollout. Allowing “users to opt in and out of dark mode using a toggle, regardless of platform-level preferences” might not need to be in the initial dark mode support.

3-step which can overlap

1. Roll-out dark mode using only the prefers-color-scheme media feature. This should be gradual, so as to catch major issues along the way
2. Find out how many users want to opt for something different than their system. This can be achieved with a fake toggle that records an intent, a 404 test, tracking views on an article that explains what we’ll do or something else entirely.
3. If we see a desire for it, we build the feature that allows users to switch.

[oliverlloyd]

Do we want to wait until we have dark mode support for fronts as well as articles before rolling out? Navigating between the two could be jarring otherwise

[oliverlloyd]

Maybe Galleries is an option if we're looking for a way to get code live?

[SiAdcock]

This sounds like a great strategy, paired with the blocking JavaScript that adds the dark / light class to the body.

1. I suspect standard articles would be a good place to start, as it gives us a "showpiece" for stakeholders. We can add this functionality behind a feature flag, which would mitigate the jarring impact of switching between fronts and the various artiocle formats for most users.
2. This is a slick idea 👌 We should put this to UX

[mxdvl]

I’ve measured the performance of the blocking javascript and it’s around a single millisecond. We could probably start the rollout with support for both system default and customisation.

[hdoeleman]

hello everyone,

there doesn't seem to be much progress on this. Would it be pôssible to implement one option and put it live, and then see where (if needed) any improvements could be made ?

As a user of the web version of the Guardian, it's becoming extremely annoying that there is no dark mode.

[mxdvl]

Thank you for voicing your interest!

It is unlikely that we are able to tackle dark mode on www.theguardian.com until the migration from frontend to dotcom-rendering is completed. The next milestone is rendering “fronts”.

In the meantime, I can suggest you install our iOS our Android app, which already supports dark mode.