scribble dark-mode

[dr-neptune]

Hi folks!

I have taken a crack at making a dark-mode for scribble that is enacted with a media-query for prefers-color-scheme: dark per this issue: #285

Here are some screenshots (in the real version the sidebar stays constant):

[sorawee]

The theme generally looks really nice! A couple of random thoughts:

I personally prefer more contrast (especially for code, like identifiers).

I notice the font change. E.g., this is how headings look from my computer, which doesn't look like the screenshot. Does the change happen because your computer doesn't support Fira? Or is it something else?

Do you think it makes sense to change the finger point from an image (https://docs.racket-lang.org/reference/finger.png) to a unicode text, so that the color changes accordingly in the dark mode?

Have you checked documentation pages that display graphics (e.g., the output is a filled black square)? Do they work well?

Do you plan to add an explicit button to switch the theme (probably not as a part of this PR, but in the future)?

[github-actions]

Resyntax analyzed 0 files in this pull request and found no issues.

[dr-neptune]

The theme generally looks really nice! A couple of random thoughts:

I personally prefer more contrast (especially for code, like identifiers).

I can put together a higher contrast version and post screenshots here. I also prefer higher contrast, but part of the appeal of lower contrast is that it is less jarring at night-time.

I notice the font change. E.g., this is how headings look from my computer, which doesn't look like the screenshot. Does the change happen because your computer doesn't support Fira? Or is it something else?

This is because my computer doesn't have Fira installed and I was using a locally downloaded html file. I am looking forward to seeing it with Fira. There is a reference to "manual-fonts.css" within the code, but I wasn't able to find the file it resolves to. My assumption is that once merged, it will display correctly

Do you think it makes sense to change the finger point from an image (https://docs.racket-lang.org/reference/finger.png) to a unicode text, so that the color changes accordingly in the dark mode?

This does make sense, I'll have to dig around in the repo to do this

Have you checked documentation pages that display graphics (e.g., the output is a filled black square)? Do they work well?

I have not. I can try out something. Do you have a good candidate page in mind?

Do you plan to add an explicit button to switch the theme (probably not as a part of this PR, but in the future)?

I hadn't planned this far ahead. This just uses a media query which goes off of the operating system settings. While a button to toggle would be nice, my hunch is that it may require more scribble internal knowledge than I currently have.

[soegaard]

It's a nice start, but I think it will be quite an amount of work to get all pages to look reasonable with the new color scheme.

On the screen shot I noticed the color of the hand hasn't changed from black to white:

When it comes to svg-images @sschwarzer and I looked at supporting dark mode in the glossary.
If the images are simple black and white images, one can use CSS to swap the colors.

https://git.sr.ht/~sschwarzer/racket-glossary/tree/main/item/fix-svgs.rkt

[dr-neptune]

@soegaard I agree that it will be difficult to make everything look good, but I think this is an overfitting problem (overfitting to the light theme) that might be overcome with people having a dark theme in mind when crafting their docs. The finger and most images I've come across are pngs which are not amenable to changing colors with css.

As an example, here is documentation on pict (which embeds each image as a png file):

re: using the svg selector:
Do you have a reference page I could use? Right now I'm hesitant to blanket apply a style to svgs as I'm not sure exactly what that might change. Will changing the media-query for svgs to have color: white, background-color: black also remove color from svgs that have color?

@sorawee Given that the finger is referenced from the main racket repo, I would have to change the image to a text character there. Do you think that it would be worth changing the finger since it is a racket docs specific thing or would it be better to keep downstream it's own thing?

Finally, I still owe a higher contrast version mock-up. Will work on that. My apologies for the delays, I haven't had much free time this week

[soegaard]

@soegaard I agree that it will be difficult to make everything look good, but I think this is an overfitting problem (overfitting to the light theme) that might be overcome with people having a dark theme in mind when crafting their docs.

That suggests to me that an explicit button to switch themes is needed.

Wrt. to png vs svg. Use the ++convert flag for Scribble to get svgs instead of pngs.

++convert <fmt>
     prefer image conversion to <fmt> (in given order)
      <fmt> as one of: ps pdf svg png gif

re: using the svg selector:
Do you have a reference page I could use? Right now I'm hesitant to blanket apply a style to svgs as I'm not sure exactly what that might change. Will changing the media-query for svgs to have color: white, background-color: black also remove color from svgs that have color?

The color properties affect the color for points and lines that haven't elsewhere been given a color.
For transparent svg's there is no need to use the background color property.

I don't have a reference page to point you to. Maybe the Glossary - but I can't remember if Stefan actually enabled it, or just experimented with it.

[soegaard]

Schwarzer reminded me of this thread on dark mode:

https://todo.sr.ht/~sschwarzer/racket-glossary/4

[jackfirth]

Getting even the basic cases working (as this PR already does) would be hugely valuable in my opinion. How do we feel about merging this without figuring out the SVG issue and defer that to follow-up work?

As for an explicit toggle: that does seem useful, but not strictly necessary for an MVP. The operating system and browser already have those toggles. There are also browser extensions that give you client-side per-site toggles if people really want to disable it without affecting other sites. That seems like a good enough workaround before we implement our own toggle.

I'm really excited for this feature, if you couldn't tell. My insomniac coding habits have made this an issue for me for years.

[otherjoel]

that might be overcome with people having a dark theme in mind when crafting their docs

I just want to say I am very opposed to this notion in particular. Authors are the wrong people on which to place the burden for getting good results in various schemes and themes the system might offer. If people want to use dark mode that’s fine but Scribble needs to do 100% of the work to make documents accessible in that scenario.

edit to add: Scribble "doing 100% of the work" would include offering facilities that get good results by default in all offered themes. Images are a hard problem here. If an author needs to use an image to convey some concept and the image has poor visibility in dark mode, then Scribble could either adjust the image with CSS, or offer some alternative function(s) that would cover the use case without needing an image. But whatever the case, I still propose that 100% of cases where documents look bad in dark mode be considered bugs in Scribble, not bugs in the document.

[sschwarzer]

Authors are the wrong people on which to place the burden for getting good results in various schemes and themes the system might offer.

I especially agree with this statement. It's difficult enough to come up with the actual content and it's hard to motivate oneself to put in more effort to support a dark mode (or any other theme).

Honestly, I guess I only invested so much time in dark mode for the glossary because I used to use dark mode myself and wanted to support current dark mode users. But I don't think this should be expected from authors. Besides, dark mode support can also be difficult to test. For example, I was surprised that I couldn't get a good dark mode experience with the DarkReader plugin, but it worked with the dark mode in the browser.

So my recommendation would be to strive for some automatic "best effort" support in Scribble and not require extra markup from documentation authors (unless it's trivial to add, maybe). But even then there's still the risk that some automatism makes it more difficult to get a good result because the automatism interferes with dark mode handling in operating systems, browsers and plugins in unexpected ways.

[dr-neptune]

If I understand correctly, the way forward seems to be to make dark mode a toggleable button? The image handling pieces may need to come later

[soegaard]

If I understand correctly, the way forward seems to be to make dark mode a toggleable button? The image handling pieces may need to come later.

Yes.

Alternatively, one could also make dark-mode an opt-in for authors.
That is, an author that wants dark-mode could require, say, scribble/dark-mode.
This way, the author is involved and expected to check that both modes work.
Even with this solution, a toggle would be good thing.