更新主题和插件以支持自动暗模式

[Discourse]

Previously, all colors in Discourse were stored as SCSS variables. To support automatic dark mode color scheme switching, we have converted these colors in core to custom CSS properties. You can easily see the full list in the inspector now:

Themes and plugins need to switch all the $color SCSS variables used in stylesheets to the --color CSS property equivalents. In most cases, this is a simple find and replace task:

-   background-color: $primary-very-low;
+   background-color: var(--primary-very-low);

But there are some cases where a theme or a plugin is using a more complex variation of a color, for example, when darkening or lightening using SCSS color functions. These cases require a more complex refactoring, and for this we have added the capacity to extend color definitions in themes and plugins.

In plugins

This commit in the discourse-encrypt plugin is a good and simple example of such a refactor. It moves a mix($color1, $color2) SCSS declaration into a separate file and stores it as a CSS custom property. Then the new file is registered as a :color_definitions asset which ensures that the newly declared color property is included in the color definitions stylesheet.

In themes

In themes, you can do the same thing by declaring CSS custom properties in the common/color_definitions.scss stylesheet. You can look at this commit in the graceful theme for an example.

Some additional notes

• when using transparent colors via the rgba($color, 0.5) function, SCSS accepts HEX and RGB colors in the first parameter, whereas CSS custom properties only accept an RGB color. That is why we have introduced the hexToRGB() helper and some properties with the --rgb suffix in the color definitions. An example:

// color_definitions.scss
:root {
  --primary: #{$primary};
  --primary-rgb: #{hexToRGB($primary)};
}

// other stylesheet
.element {
  background-color: rgba(var(--primary-rgb), 0.05);
}

• note that in the snippet above, the SCSS variable is interpolated when passed to a custom property. That is a requirement in SCSS, see Sass: Property Declarations for more details.
• the CSS var() declaration can fallback to a second value if the first one is not available, as in, when writing var(--color1, red), CSS will fallback to the red color if the --color1 property is not found. In plugins, we use the SCSS color variables as fallbacks to ensure compatibility with previous versions of Discourse. So the earlier example, would look like this with a fallback:

-   background-color: $primary-very-low;
+   background-color: var(--primary-very-low, $primary-very-low);

---

This document is version controlled - suggest changes on github.

[pfaffman (Jay Pfaffman)]

@pmusaraj

Themes and plugins need to switch all the $color SCSS variables used in stylesheets to the --color CSS property equivalents. I

I’m not very good at this stuff and it’ll take me a while to figure this out myself. . . Does this mean that all themes that referred to colors before are now going to be broken?

[pmusaraj (Penar Musaraj)]

No, not at all. SCSS variables in themes will continue to work for a long time.

But any colors outputted via SCSS variables will stay static, i.e. they cannot be dynamically switched to a new color scheme when a browser goes from normal to dark mode. So those themes/plugins will continue to work, they just won’t be compatible with automatic dark mode switching.

[tomtjes (Thomas Reintjes)]

Thanks for the instructions. Is there a way to also change a background image depending on dark/light mode? (I’ve used the theme switcher component to do that.) Would a CSS class indicating the mode be possible?

[pmusaraj (Penar Musaraj)]

Great question, I tried this and noticed that we didn’t properly support using background images or theme variables in the special color definitions stylesheet. So I made some fixes in core, and you should be able to do this now (make sure you pull the latest core).

So, if you have two images in your theme or theme component, with SCSS vars of $bg-light and $bg-dark respectively, you can add this to your color_definitions.scss stylesheet:

$bg: url(dark-light-choose($bg-light, $bg-dark));

:root {
  --custom-bg: #{$bg};
}

And then you can use var(--custom-bg) in your regular stylesheet.

[riking (Kane York)]

For an image, all you need to do is the vanilla prefers-dark-theme CSS media query.

[pmusaraj (Penar Musaraj)]

@riking

vanilla prefers-dark-theme CSS media query

That won’t work well in all cases, because the media query is not aware of the user’s preferences. Users can disable auto-dark-mode switching, but the media query won’t be aware of that, and it will result in the background meant for the dark color scheme being rendered.

[j127]

Discourse 是否也可以为 <body> 添加一个 CSS 类来表示配色方案或配色方案 ID？这似乎会容易得多。

我正在尝试解决主题转换中的一个问题，我需要大量的不同的 CSS 规则和变量，这在 color_definitions.scss 文件中变成了一个复杂的混乱。

如果我能在主题中的一个隔离的 SCSS 文件中做到这一点，那么用 color_definitions.scss 来解决一个需要很长时间才能弄清楚的问题，只需要 5 分钟：

body.dark-palette .some-thing {
  // 一些样式
}

body.light-palette .some-thing {
  // 一些样式
}

[pmusaraj (Penar Musaraj)]

是的，您可能会在颜色定义文件中遇到许多代码行，尤其是在处理渐变时。

在我看来，这仍然是最合适的位置。它确实远离了使用它的元素，但它是一个方便的单一位置，可以处理基于浅色/深色模式切换的颜色/渐变。

另一种方法是使用类似这样的方法：

@container style(--scheme-type: light){
  body{
    background: red;
  }
}

我们的颜色方案带有一个 --scheme-type 属性，浅色方案为 light，深色方案为 dark。最近的浏览器支持容器查询，因此这应该可以在不向页面主体添加类的情况下完成您在此处尝试完成的任务。

[j127]

我的 CSS/SCSS 技能不是很好。也许对于精通这些技术的人来说会更容易。

它弄乱了 color_definitions.scss 文件，所以我把它移到了 scss/ 中的另一个文件中，这样我就可以导入它了。我不确定该如何命名，所以它看起来是这样的。

我认为使用 body 类（或者更多示例）会更容易，但无论如何，它目前是有效的。我不知道容器查询是如何工作的，但我以后会研究它。

[panic]

请注意，截至今天（2025/11/14），Firefox 不支持 自定义属性的样式查询。