It’s time to prepare your Drupal modules for Admin’s dark mode

Drupal 12 is coming this December, and it has some big changes in store for the administration UI.

Drupal’s default administration theme is changing from Claro to Admin (yes, that’s really the name). Its machine name is default_admin.

Admin is based on the Gin contrib theme, but includes a number of improvements and simplifications. Gin itself was based on Claro, which was forked from Seven, so there’s quite a family tree here.

But there’s one change that module maintainers should start paying attention to right now: dark mode.

Dark mode is coming to Drupal core

One of the biggest features of the new Admin theme is built-in dark mode support.

By default, Admin uses the auto color scheme. That means if a content editor has dark mode enabled in their operating system, Drupal’s administration UI will automatically use dark mode too.

For module maintainers, this means supporting dark mode isn’t really optional. Your module’s UI needs to look good regardless of which color scheme the user has enabled.

If you’re testing this now, you’ll want to test against Drupal 11.4.4 or newer, which includes the latest CSS custom property names used by Admin.

Image

Your module’s CSS probably needs some attention

If your module’s administration CSS contains hard-coded colors, there’s a good chance something will look broken in dark mode.

The Paragraphs module is a good example. It contains several hard-coded colors that look perfectly reasonable in a light administration theme but don't work when the surrounding UI switches to dark mode.

This kind of CSS was common when modules needed to work across older administration themes, but dark mode changes the equation.

Image

The fix is easier than you think!

The Admin theme provides a set of CSS custom properties that modules can use instead of hard-coded colors.

For example, you might have something like this:

.my-module-panel {
  background: #fff;
  color: #232429;
  border: 1px solid #d4d4d8;
}

Instead, you can use Admin's semantic color variables, with your existing colors as fallbacks:

.my-module-panel {
  background: var(--admin-color-bg-surface, #fff);
  color: var(--admin-color-text, #232429);
  border: 1px solid var(--admin-color-border, #d4d4d8);
}

So instead of:

background: #fff;

you use:

background: var(--admin-color-bg-surface, #fff);

When Admin is active, the theme provides the appropriate value for the current color scheme. If that custom property isn't defined, such as when the module is being displayed using Claro, the browser falls back to the original #fff.

That means you can add dark mode support without breaking compatibility with existing administration themes.

We have documentation explaining how this works, which variables are available, and where modules should use them:

https://www.drupal.org/docs/core-modules-and-themes/core-themes/default-admin-theme/making-your-module-compatible-with-the-admin-theme-and-dark-mode

Putting it into practice

To see how well this works on a real-world module, I opened the Support dark mode in Drupal 12's new Admin theme issue in the Paragraphs issue queue.

And, partly to test how good the documentation is (and partly because I’m lazy), I pointed Claude Code at the documentation and the issue and told it to get to work.

The job ended up being a little less trivial than I expected because Paragraphs still uses Sass. But Claude Code did a great job working through it and producing an MR.

I manually reviewed the changes, made sure the approach made sense, and did some basic testing. Overall, it was surprisingly straightforward.

That’s also a pretty good sign that the documentation is doing its job: if an LLM can take an existing module with hard-coded colors, follow the documentation, and produce a solid starting point for dark mode support, maintainers should be able to make these changes without a huge amount of work.

Now is the time to test your module

December and the Drupal 12.0.0 release are sneaking up faster than you might think.

If you maintain a module that provides any administration UI, now is a great time to:

1. Test it with Drupal 11.4.4 or newer and the new Admin theme.
2. Switch the theme between light and dark mode within theme settings.
3. Click through every piece of UI your module provides.
4. Look for hard-coded colors that don't work in both modes.
5. Replace those colors with the appropriate Admin CSS custom properties.

And while you're testing, you might even find a few bugs that are still hiding in the new Admin theme itself. If you do, please open an issue!

If you run into problems or aren't sure how your module should handle something, feel free to reach out to me on Drupal Slack (@mherchel). I’m happy to help.

Let’s get contrib ready for dark mode before Drupal 12 ships!