[mdo]

This new docs page is intended to answer questions for where to put custom CSS (see #22891), how to customize and extend Sass maps and variables, and more. Ideally it'll replace the Options page. Much more still to come, but would love early feedback.

Closes #22891.

[mdo]

Still needs something to solve #23418 and #23450.

[tkuther]

I think the new doc isn't clear enough at this part:

For example, to modify an existing color in our $theme-colors map, add the following to your custom Sass file:
 $theme-colors: (
 "primary": $red,
 "danger": $orange
 );

Where in my custom.scss would I put this? If I put this before the @import bootstrap/scss/variables; I also need to define $red and $orange first (because they are defined in _variables.scss which I import later on)

If I put it after the @import bootstrap/scss/variables;, $red and $orange are defined, but my $theme-colors override won't work because it's !default in _variables.scss which requires it to be redefined before the import. I'm aware this would be the wrong order anyway, just stating that this could be confusing.

[mdo]

@tkuther Does the variable section cover that for you? Might just need another link to refer back to that section to connect Sass maps to that section since it's not immediately clear maps and variables are connected.

bootstrap/docs/4.0/getting-started/theming.md

Lines 62 to 79 in 0071bf5

	### Variable defaults
	Every Sass variable in Bootstrap 4 includes the `!default` flag allowing you to override the variable's default value in your own Sass without modifying Bootstrap's source code. Copy and paste variables as needed, modify their values, and remove the `!default` flag. If a variable has already been assigned, then it won't be re-assigned by the default values in Bootstrap.
	Variable overrides within the same Sass file can come before or after the default variables. However, when overriding across Sass files, your overrides must come before you import Bootstrap's Sass files.
	Here's an example that changes the `background-color` and `color` for the `<body>` when importing and compiling Bootstrap via npm:
	{% highlight scss %}
	// Your variable overrides
	$body-bg: #000;
	$body-color: #111;
	// Bootstrap and its default variables
	@import "node_modules/bootstrap/scss/bootstrap";
	{% endhighlight %}
	Repeat as necessary for any variable in Bootstrap, including the global options below.

[tkuther]

@mdo it does cover it, sure.

I'm just saying the example isn't clear because it reads "add following to your custom Sass file", but it actually requires two lines more to get it working that way. A link back to the variable defaults section would be enough to make it more clear, or even provide a full example like

$red: #f44336;
$orange: #ff9800;

$theme-colors: (
 "primary": $red,
 "danger": $orange
 );

I guess that could avoid some head scratching.

[mdo]

Moved away from those variables—they were meant to pull from the included color variables in Bootstrap, but I can see the confusion. Moved to hex values.