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

system · April 19, 2025, 1:37pm

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.

Topic		Replies	Views
Use Discourse Core Variables in your Theme Developer Guides how-to , theme-guides	0	11837	January 9, 2018
Referencing Discourse theme color variables in custom theme component? Support css	4	69	April 20, 2025
Styling Discourse with variables: Show & Tell Dev dev-news	1	155	August 5, 2025
Reference for full color customization Dev	4	1288	February 14, 2023
Challenges creating a custom color palette Dev	8	143	January 29, 2025

How do colors work and how to change them?

Related topics