How do colors work and how to change them?

pHneutre · March 20, 2025, 10:12am

Sorry for the broad subject but I’ve been puzzling over this and I cannot find an appropriate tutorial or even explanation.

Whenever I need to change a color anywhere on Discourse, I follow this path:

Is the color managed by a theme component? If not,
Does it seem to be managed by /admin/customize/colors? If not,
Open dev tools and try to find the matching CSS

But then I’m lost because I find things like var(--primary-low) and I have no idea where these are defined, though they look related to the notion of primary color in /admin/customize/colors. So:

How are these var() things defined?
What is the recommended way to modify them consistently?

Canapin · March 20, 2025, 11:15am

The colors are (calculated) here:

github.com/discourse/discourse

app/assets/stylesheets/common/foundation/color_transformations.scss

main

// standard color transformations, use these if possible, and add any new dark-light-diffs here
// any variables defined here can be added in theme color schemes
// all variables should have the !default flag

@use "sass:string";

// primary
$primary-very-low: dark-light-diff($primary, $secondary, 97%, -82%) !default;
$primary-low: dark-light-diff($primary, $secondary, 90%, -78%) !default;
$primary-low-mid: dark-light-diff($primary, $secondary, 70%, -45%) !default;
$primary-medium: dark-light-diff($primary, $secondary, 50%, -35%) !default;
$primary-high: dark-light-diff($primary, $secondary, 30%, -25%) !default;
$primary-very-high: dark-light-diff($primary, $secondary, 15%, -10%) !default;

// primary-numbers
$primary-50: dark-light-diff($primary, $secondary, 97%, -82%) !default;
$primary-100: dark-light-diff($primary, $secondary, 94%, -80%) !default;
$primary-200: dark-light-diff($primary, $secondary, 90%, -78%) !default;
$primary-300: dark-light-diff($primary, $secondary, 80%, -60%) !default;
$primary-400: dark-light-diff($primary, $secondary, 70%, -45%) !default;

This file has been truncated. show original

The CSS variables are defined here:

github.com/discourse/discourse

app/assets/stylesheets/color_definitions.scss

main

// This file maps all SCSS color variables to CSS custom properties.
// It is compiled to CSS separately from the rest of the app.
// The source variables come from color_transformations.scss and variables.scss
:root {
  color-scheme: #{schemeType()};

  --scheme-type: #{schemeType()};
  --primary: #{$primary};
  --secondary: #{$secondary};
  --tertiary: #{$tertiary};
  --quaternary: #{$quaternary};
  --header_background: #{$header_background};
  --header_primary: #{$header_primary};
  --highlight: #{$highlight};
  --danger: #{$danger};
  --success: #{$success};
  --love: #{$love};
  --d-selected: #{$selected};
  --d-hover: #{$hover};
  --always-black-rgb: 0, 0, 0;

This file has been truncated. show original

If you want to override let’s say --primary-medium, you can add this to your theme:

:root {
    --primary-high: red;
}

However, I don’t know how to use the color transformation functions, which need SCSS variables.

I see that @import "common/foundation/variables"; is not required as “core and theme variables are now injected before any SCSS file is compiled”, but I couldn’t have it working nonetheless. I’ll pass the mic to more knowledgeable users

ondrej · March 20, 2025, 1:13pm

You can check the style guide

You can check the /styleguide/atoms/colors for colours too. You have to enable in your site settings by searching for ‘styleguide’

For example: https://meta.discourse.org/styleguide/atoms/colors

pHneutre · March 20, 2025, 1:24pm

Wow, first time I hear of styleguide, thanks.
So I understand custom CSS is the only way to modify these styles, as @Canapin said, right? ( for confirming if you want)

awesomerobot · March 20, 2025, 1:37pm

This method is probably the easiest, it will work for any of the automatically generated colors

but you can also override colors in a theme’s about.json file as described here Override values for auto-generated color variables

Topic		Replies	Views
Referencing Discourse theme color variables in custom theme component? Support css	3	30	March 21, 2025
Use Discourse Core Variables in your Theme Developer Guides how-to , theme-guides	0	11627	January 9, 2018
Custom CSS isn't applied to my Discourse Support	18	2705	March 4, 2021
Update themes and plugins to support automatic dark mode Developer Guides how-to , auto-dark , theme-guides	6	3722	September 17, 2020
What about an easier styling/theming system? Feature	54	15218	October 3, 2014

How do colors work and how to change them?

Related topics