Support adding theme colors

[chalin]

Discussed in #1842

^{Originally posted by @rkranendonk February 7, 2024}

I worked out how to redefine one of the existing colors by adding a line like $orange: #fe5400;.
But how can I define a new color? I tried adding $newcolor: #E4C1F9; to _variables_project.scss, but if I then use that in _index.md, e.g. {{% blocks/lead color="newcolor" %}} it just defaults to white/none.
What step am I missing here?

Related:

• Versions of needed dependencies is not clearly documented #1836

[chalin]

Projects can't modify theme colors easily -- as @CsatariGergely mention, it's just hard to change colors in Bootstrap. At least, Docsy will need to extra mechanism to handle this specific issue. After some quick tests, here's how I got it to work:

diff --git a/assets/scss/main.scss b/assets/scss/main.scss
index 540fdc6..cb20f50 100644
--- a/assets/scss/main.scss
+++ b/assets/scss/main.scss
@@ -12,6 +12,7 @@
 @import "../vendor/Font-Awesome/scss/solid.scss";
 @import "../vendor/Font-Awesome/scss/brands.scss";
 
+@import "variables_project_after_bs";
 @import "support/utilities";
 @import "colors";
 @import "table";

Then add your color definitions to your-project/assets/scss/_variables_project_after_bs.scss, e.g.:

$custom-colors: (
  "my-color": #900
);

// Merge the maps
$theme-colors: map-merge($theme-colors, $custom-colors);

Then you can use the color like this: {{% blocks/section color="my-color" type="row" %}}.

[marshalc]

Can confirm, is hard - side note of this as I'm presently reimplementing our solution to this: #552 (comment)

We haven't added "extra" colours yet to the range (though we'd like to), but we have had some success at overriding the colour theme. I'm having to rediscover how I plumbed this originally (and make a better job of documenting it for later recall), but you can see our modified content in https://github.com/ouhft/docsy/tree/ouhft-broken/assets/scss. In this setup we have a range of colour themes that a user can select through the Hugo config, which results in one of our colour packs being included inline on the base template (e.g. https://github.com/ouhft/docsy/blob/ouhft-broken/assets/scss/nhs-colour/docsy/cyan/_config-colours.scss) and then these values are picked up by the other scss scripts in the build.

I'm not convinced this is the best approach to this problem, so welcome alternative (and easier) mechanisms being suggested!

---

Updated to add: The minimal set of changes we've added to have a choice of "primary colour" in the theme (options being: amber, blue (Default), brown, cyan, deep-orange, deep-purple, green, grey, indigo, light-blue, light-green, lime, orange, pink, purple, red, teal, & yellow.) is to the following...

First change picks up the Hugo config item for primary_colour, and then adds it to the toCSS include path...

--- a/layouts/partials/head-css.html
+++ b/layouts/partials/head-css.html
 
 {{ $scssMain := "scss/main.scss"}}
+
+{{ $configColour := (or .Site.Params.ui.primary_colour "blue") }}
+{{ $configColourPath := (print "assets/scss/nhs-colour/docsy/" $configColour "/") }}
+
 {{ if not hugo.IsProduction }}
 {{/* Note the missing postCSS. This makes it snappier to develop in Chrome, but makes it look sub-optimal in other browsers. */}}
-{{ $css := resources.Get $scssMain | toCSS (dict "enableSourceMap" true) }}
+{{ $css := resources.Get $scssMain | toCSS (dict "enableSourceMap" true "includePaths" (slice $configColourPath)) }}
 <link href="{{ $css.RelPermalink }}" rel="stylesheet">
 {{ else }}
-{{ $css := resources.Get $scssMain | toCSS (dict "enableSourceMap" false) | postCSS | minify | fingerprint }}
+{{ $css := resources.Get $scssMain | toCSS (dict "enableSourceMap" false "includePaths" (slice $configColourPath)) | postCSS | minify | fingerprint }}
 <link rel="preload" href="{{ $css.RelPermalink }}" as="style">
 <link href="{{ $css.RelPermalink }}" rel="stylesheet" integrity="{{ $css.Data.integrity }}">
 {{ end }}

Which means when the project variables goes looking for config-colours it finds one specific example...

--- a/assets/scss/_variables_project.scss
+++ b/assets/scss/_variables_project.scss
 
+// Theme colours
+// Primary colours are set in config now!
+// References `/assets/scss/nhs-colour/docsy/$COLOUR$/_config-colours.scss`
+// This links to layouts/partials/head-css.html which will insert the correct base path to find the correct _config-colours.scss
+@import "config-colours";
+
+// Fixed elements
+$success: $clr-light-green !default;
+$info: $clr-teal !default;
+$warning: $clr-deep-orange !default;
+$danger: $clr-red !default;
+$blue: $clr-indigo-200 !default;
+$orange: $clr-orange !default;

From a folder of possibilities (e.g. https://github.com/ouhft/docsy/tree/0-8-0%2Bnhs-colours/assets/scss/nhs-colour/docsy)... where we define the following overrides:

--- /dev/null
+++ b/assets/scss/nhs-colour/docsy/indigo/_config-colours.scss

+@import "nhs-colour/nhs-colour";
+
+// This class exists only to confirm visually in the rendered output that this file has been successfully included
+.indigoFlibble { 
+    color: #fff;
+}
+
+// Primary and related to Primary
+$primary: $clr-indigo !default;
+$primary-light: $clr-indigo-a200 !default;
+$light: $clr-indigo-400 !default;
+$dark: $clr-indigo-700 !default;
+
+$link-color: $clr-indigo-a400 !default;
+$link-decoration: none !default;
+$link-hover-color: $clr-indigo-a700 !default;
+$link-hover-decoration: underline !default;
+
+
+// Secondary and related to secondary
+$secondary: $clr-purple !default;
+$code-color: $clr-purple-700 !default;

The various colours are pulled from a master colour file based on a corporate brand guide, but you can set your own (or crib from others like Google's Material design - which these were originally based on).

Hopefully that'll help someone else (and if nothing else, act as a reminder for me when I forget again in 6 months). Also: Some of the colour combos need some more work - the contrast values aren't acceptable against white for several here, so I'm likely to turn them into "dark" theme colours in due course.

[chalin]

The following PR implements the simple solution proposed in #1845 (comment):

• Support for adding and modifying theme colors #1893