Support for adding and modifying theme colors

Author: chalin

assets/scss/_variables_project.scss

@@ -1,7 +1,4 @@
 /*
-
-Nothing defined here. The Hugo project that uses this theme can override theme variables by adding a file to:
-
-assets/scss/_variables_project.scss
-
+Projects can override this file. For details, see:
+https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files
 */

assets/scss/_variables_project_after_bs.scss

@@ -0,0 +1,4 @@
+/*
+Projects can override this file. For details, see:
+https://www.docsy.dev/docs/adding-content/lookandfeel/#project-style-files
+*/

assets/scss/main.scss

@@ -1,6 +1,6 @@
 @import "../vendor/bootstrap/scss/functions";
 
-@import "_variables_forward";
+@import "variables_forward";
 @import "variables_project";
 @import "variables";
 @import "support/mixins";
@@ -12,6 +12,8 @@
 @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";

userguide/content/en/docs/adding-content/lookandfeel.md

@@ -22,26 +22,29 @@ Prism for highlighting.
 
 ## Project style files
 
-To customize your project's look and feel, create your own version of either or
-both of the following Docsy placeholder files (note the **`_project.scss`**
-suffixes):
-
-- [`assets/scss/`**`_variables_project.scss`**][_variables_project] is where you
-  add project-specific definitions of theme variables such as [site
-  colors](#site-colors), as well as any additional Bootstrap variable values you
-  want to set. You can find a list of Docsy's theme variables and their default
-  values in [`assets/scss/`**`_variables.scss`**][_variables].  For information
-  about other Bootstrap 5 variables, see [Variable defaults] and Bootstrap's
-  [`_variables.scss`] file.
-- [`assets/scss/`**`_styles_project.scss`**][_styles_project] is where you can
-  add your own custom SCSS styles, including overriding any of the styles in
-  Docsy's theme SCSS files.
-
-[_styles_project]: https://github.com/google/docsy/blob/main/assets/scss/_styles_project.scss
-[_variables_project]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project.scss
-[_variables]: https://github.com/google/docsy/blob/main/assets/scss/_variables.scss
-[`_variables.scss`]: https://github.com/twbs/bootstrap/blob/v5.2.3/scss/_variables.scss
-[variable defaults]: https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults
+To customize your project's look and feel, create your own version of the
+following Docsy placeholder files (note the **`_project*.scss`** suffixes) and
+place them inside your project's `assets/scss/` folder:
+
+- **`_variables_project.scss`**[^vp] and<br>
+  **`_variables_project_after_bs.scss`**[^vpabs] :
+
+  Use these files to add project-specific definitions of theme variables such as
+  [site colors](#site-colors) (explained in the next section), as well as any
+  additional Bootstrap variable values you want to set. You can find a list of
+  Docsy's theme variables and their default values in `_variables.scss`[^v]. For
+  information about other Bootstrap 5 variables, see [Variable defaults] and
+  Bootstrap's `_variables.scss`[^bv] file.
+
+- **`_styles_project.scss`**[^sp] is where you can add your own custom SCSS
+  styles, including overriding any of the styles in Docsy's theme SCSS files.
+
+[^bv]: https://github.com/twbs/bootstrap/blob/v5.3.3/scss/_variables.scss
+[^sp]: https://github.com/google/docsy/blob/main/assets/scss/_styles_project.scss
+[^v]: https://github.com/google/docsy/blob/main/assets/scss/_variables.scss
+[^vp]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project.scss
+[^vpabs]: https://github.com/google/docsy/blob/main/assets/scss/_variables_project_after_bs.scss
+
 
 {{% alert title="Tip" %}}
 PostCSS (autoprefixing of CSS browser-prefixes) is not enabled when running in server mode (it is a little slow), so Chrome is the recommended choice for development.
@@ -50,8 +53,8 @@ PostCSS (autoprefixing of CSS browser-prefixes) is not enabled when running in s
 ## Site colors
 
 To customize your site's colors, add SCSS variable overrides to
-`assets/scss/_variables_project.scss`. For example, you can set the primary and
-secondary site colors as follows:
+**`assets/scss/_variables_project.scss`**. For example, you can set the primary
+and secondary site colors as follows:
 
 ```scss
 $primary: #390040;
@@ -62,6 +65,24 @@ The theme has features such as gradient backgrounds (`$enable-gradients`) and
 shadows (`$enable-shadows`) enabled by default. These can also be toggled in
 your project variables file by setting the variables to `false`.
 
+To can add colors to or modify Bootstrap's [color maps], use
+**`assets/scss/_variables_project_after_bs.scss`**. For example:
+
+```scss
+$custom-colors: (
+  "my-favorite-color": purple
+);
+
+$theme-colors: map-merge($theme-colors, $custom-colors);
+```
+
+Learn how to modify maps, see [Maps and loops] and [Adding theme colors].
+
+[Adding theme colors]: https://getbootstrap.com/docs/5.3/customize/color-modes/#adding-theme-colors
+[color maps]: https://getbootstrap.com/docs/5.3/customize/color/#color-sass-maps
+[Maps and loops]: https://getbootstrap.com/docs/5.3/customize/sass/#maps-and-loops
+[variable defaults]: https://getbootstrap.com/docs/5.3/customize/sass/#variable-defaults
+
 ## Fonts
 
 The theme uses [Open Sans](https://fonts.google.com/specimen/Open+Sans) as its primary font. To disable Google Fonts and use a system font, set this SCSS variable in `assets/scss/_variables_project.scss`: