Skip to content

Add dark mode - #294

Merged
kress04 merged 1 commit into
masterfrom
feature/dark-mode
Sep 8, 2026
Merged

Add dark mode#294
kress04 merged 1 commit into
masterfrom
feature/dark-mode

Conversation

@martinfrancois

Copy link
Copy Markdown
Contributor

Adds a dark theme. It follows the operating system by default, and a toggle in
the navbar overrides that. The choice is remembered.

Bulma compiles its colours into static rules, so rather than rebuilding the
framework this is an override layer in _sass/dark-mode.scss keyed on a
data-theme attribute, set before first paint so there is no flash. Without
JavaScript the same rules still apply through a prefers-color-scheme media
query, and the toggle is hidden, because there it could not work.

Two changes land in light mode as well:

The header scrim goes from 0.4 to 0.55 black in both modes rather than only
in dark. The header text is noticeably easier to read and the page still looks
the same, so there was no reason to keep two values.

Transparent images now have a white background behind them. Several logos
and diagrams in posts are drawn without a background of their own, so on a dark
page their black text and lines ended up too close to the page colour to be
visible: the AdoptOpenJDK logo lost its whole wordmark, and the Tiberius
diagrams lost their titles and edge labels. 56 of the 152 images used across
posts are drawn on transparency. The rule is written for every image, but a
solid photo covers the background completely, so it only ever shows where an
image is see-through. It sits behind the picture itself and not the space around
it, so nothing moves in either mode.

Three decisions a reviewer might question:

  • Applying it to every image, rather than only the ones that need it.
    Picking them out fails silently: whoever adds the next diagram has to
    remember, and forgetting makes the image vanish in dark mode. Applying it
    everywhere costs nothing, since a solid image hides it.
  • White, not a softer off-white. Off-white saves about 10% of luminance,
    which is not the difference it sounds like, and it costs contrast: the palest
    label in the Tiberius diagrams reads 7.94:1 on white against 7.16:1 on
    off-white. White also leaves light mode untouched.
  • No second set of images for dark mode. Diagrams drawn for a dark page
    would look better than the same diagrams on a white background, and it is
    doable, but it means a dark version of every affected image kept in step from
    then on. That is more than this change should carry: the white background
    already makes them readable, and dark mode is a clear improvement over not
    having it. Worth revisiting later for the diagrams that deserve it.

Also worth knowing: on mobile the toggle sits inside the burger menu, and there
is a print block, because browsers drop background colours and keep text colour,
which put near-white text on paper.

Checked in a browser at both breakpoints: system following, an explicit choice
surviving a reload and a system flip, no JavaScript, blocked localStorage, a
corrupt stored value, printing, and the burger menu. A pixel diff against master
shows light mode differing in exactly two places: the navbar, where the toggle
shifts the links, and the darker header band.

It follows the operating system by default, and a toggle in the navbar overrides
that. The choice is remembered.

Bulma compiles its colours into static rules, so rather than rebuilding the
framework this is an override layer in _sass/dark-mode.scss keyed on a
data-theme attribute, set before first paint so there is no flash. Without
JavaScript the same rules still apply through a prefers-color-scheme media
query, and the toggle is hidden, because there it could not work.

Two changes land in light mode as well.

The scrim over the page header goes from 0.4 to 0.55 black in both modes rather
than only in dark. The header text is noticeably easier to read and the page
still looks the same, so there was no reason to keep two values.

Transparent images now have a white background behind them. Several logos and
diagrams in posts are drawn without a background of their own, so on a dark page
their black text and lines ended up too close to the page colour to be visible:
the AdoptOpenJDK logo lost its whole wordmark, and the Tiberius diagrams lost
their titles and edge labels. 56 of the 152 images used across posts are drawn
on transparency. The rule is written for every image, but a solid photo covers
the background completely, so it only ever shows where an image is see-through.
It sits behind the picture itself and not the space around it, so nothing moves
in either mode.

Applying it to every image rather than only the ones that need it, because
picking them out fails silently: whoever adds the next diagram has to remember,
and forgetting makes the image vanish in dark mode.

White rather than a softer off-white. Off-white saves about 10% of luminance,
which is not the difference it sounds like, and it costs contrast: the palest
label in the Tiberius diagrams reads 7.94:1 on white against 7.16:1 on
off-white. White also leaves light mode untouched.

No second set of images for dark mode. Diagrams drawn for a dark page would look
better than the same diagrams on a white background, and it is doable, but it
means a dark version of every affected image kept in step from then on. That is
more than this change should carry, and worth revisiting later for the diagrams
that deserve it.

On mobile the toggle sits inside the burger menu. There is a print block,
because browsers drop background colours and keep text colour, which put
near-white text on paper.
@martinfrancois
martinfrancois requested a review from kress04 August 28, 2026 23:19

@kress04 kress04 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested it on Safari and Chrome in Desktop view - both looking good. Before approving it I want to make sure that no Cookies are being used. I didn't see any in the rendered preview but maybe you can clarify @martinfrancois ?

The same applies to the topic of JavaScript. If I understand correctly, JS is not necessarily needed to read the DevHub. But a visitor can only use dark mode when using JS. Correct, @martinfrancois ?

As for the three questions written in the PR:

  1. Applying it to every image, rather than only the ones that need it.

The proposed solution should imo be a global definition so that authors and editors don't need to think about it any longer.

  1. White, not a softer off-white.

Definitely White respectively the background color of light mode (which should be white).

  1. No second set of images for dark mode.

Definitely no second image for dark mode!

@martinfrancois

Copy link
Copy Markdown
Contributor Author

@kress04 Thanks for testing in Safari and Chrome!

This change introduces no cookies. When a visitor uses the toggle, it saves light or dark under the theme key in localStorage so the choice survives a reload. It stores nothing until the visitor makes that choice.

Dark mode also works without JavaScript. CSS follows the visitor's system colour preference automatically. JavaScript is needed only for the manual toggle and remembering that override. With JavaScript disabled, the toggle is hidden and the DevHub remains readable in either theme.

Agreed on the image handling. The shared CSS rule gives post and featured images a white background, so authors don't need to configure individual images or maintain separate dark-mode versions.

@kress04
kress04 merged commit 724b427 into master Sep 8, 2026
3 checks passed
@kress04
kress04 deleted the feature/dark-mode branch September 8, 2026 10:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants