mirror of
https://github.com/twbs/bootstrap.git
synced 2024-12-01 13:24:25 +01:00
Rewrite Theming docs as Customize section
- Broke up existing theming page into separate pages - Audited and updated each new docs page (some pages include some TBD sections) - Update sidenav to reflect changes - Fix links that pointed to the old Theming page - Update docs styles to reflect recent changes - Rewrite some bits in the Migration page
This commit is contained in:
Mark Otto
Mark Otto
parent
85ac2fc35e
commit
f6e2f4c656
9
scss/bootstrap.scss
vendored
9
scss/bootstrap.scss
vendored
@ -5,16 +5,14 @@
|
||||
* Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
|
||||
*/
|
||||
|
||||
// scss-docs-start import-stack
|
||||
// Configuration
|
||||
|
||||
@import "functions";
|
||||
@import "variables";
|
||||
@import "mixins";
|
||||
@import "utilities";
|
||||
|
||||
|
||||
// Layout & components
|
||||
|
||||
@import "root";
|
||||
@import "reboot";
|
||||
@import "type";
|
||||
@ -44,12 +42,9 @@
|
||||
@import "carousel";
|
||||
@import "spinners";
|
||||
|
||||
|
||||
// Helpers
|
||||
|
||||
@import "helpers";
|
||||
|
||||
|
||||
// Utilities
|
||||
|
||||
@import "utilities/api";
|
||||
// scss-docs-end import-stack
|
||||
|
||||
@ -117,3 +117,16 @@
|
||||
.bd-cyan-700 { color: color-contrast($cyan-700); background-color: $cyan-700; }
|
||||
.bd-cyan-800 { color: color-contrast($cyan-800); background-color: $cyan-800; }
|
||||
.bd-cyan-900 { color: color-contrast($cyan-900); background-color: $cyan-900; }
|
||||
|
||||
.bd-gray-100 { color: color-contrast($gray-100); background-color: $gray-100; }
|
||||
.bd-gray-200 { color: color-contrast($gray-200); background-color: $gray-200; }
|
||||
.bd-gray-300 { color: color-contrast($gray-300); background-color: $gray-300; }
|
||||
.bd-gray-400 { color: color-contrast($gray-400); background-color: $gray-400; }
|
||||
.bd-gray-500 { color: color-contrast($gray-500); background-color: $gray-500; }
|
||||
.bd-gray-600 { color: color-contrast($gray-600); background-color: $gray-600; }
|
||||
.bd-gray-700 { color: color-contrast($gray-700); background-color: $gray-700; }
|
||||
.bd-gray-800 { color: color-contrast($gray-800); background-color: $gray-800; }
|
||||
.bd-gray-900 { color: color-contrast($gray-900); background-color: $gray-900; }
|
||||
|
||||
.bd-white { color: color-yiq($white); background-color: $white; }
|
||||
.bd-black { color: color-yiq($black); background-color: $black; }
|
||||
|
||||
@ -29,6 +29,7 @@
|
||||
> .table {
|
||||
max-width: 100%;
|
||||
margin-bottom: 1.5rem;
|
||||
@include font-size(.875rem);
|
||||
|
||||
@include media-breakpoint-down(md) {
|
||||
display: block;
|
||||
|
||||
133
site/content/docs/4.3/customize/color.md
Normal file
133
site/content/docs/4.3/customize/color.md
Normal file
@ -0,0 +1,133 @@
|
||||
---
|
||||
layout: docs
|
||||
title: Color
|
||||
description: Bootstrap is supported by an extensive color system that themes our styles and components. This enables more comprehensive customization and extension for any project.
|
||||
group: customize
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Theme colors
|
||||
|
||||
We use a subset of all colors to create a smaller color palette for generating color schemes, also available as Sass variables and a Sass map in Bootstrap's `scss/_variables.scss` file.
|
||||
|
||||
<div class="row">
|
||||
{{< theme-colors.inline >}}
|
||||
{{- range (index $.Site.Data "theme-colors") }}
|
||||
<div class="col-md-4">
|
||||
<div class="p-3 mb-3 bg-{{ .name }} {{ if or (eq .name "light") (eq .name "warning") }}text-dark{{ else }}text-white{{ end }}">{{ .name | title }}</div>
|
||||
</div>
|
||||
{{ end -}}
|
||||
{{< /theme-colors.inline >}}
|
||||
</div>
|
||||
|
||||
All these colors are available as a Sass map, `$theme-colors`.
|
||||
|
||||
{{< highlight scss >}}
|
||||
$theme-colors: (
|
||||
"primary": $primary,
|
||||
"secondary": $secondary,
|
||||
"success": $success,
|
||||
"info": $info,
|
||||
"warning": $warning,
|
||||
"danger": $danger,
|
||||
"light": $light,
|
||||
"dark": $dark
|
||||
) !default;
|
||||
{{< /highlight >}}
|
||||
|
||||
Check out [our Sass maps and loops docs]({{< docsref "/customize/sass#maps-and-loops" >}}) for how to modify these colors.
|
||||
|
||||
## All colors
|
||||
|
||||
All Bootstrap colors are available as Sass variables and a Sass map in `scss/_variables.scss` file. To avoid increased file sizes, we don't create text or background color classes for each of these variables. Instead, we choose a subset of these colors for a [theme palette](#theme-colors).
|
||||
|
||||
<div class="row font-monospace">
|
||||
{{< theme-colors.inline >}}
|
||||
{{- range $color := $.Site.Data.colors }}
|
||||
{{- if (and (not (eq $color.name "white")) (not (eq $color.name "gray")) (not (eq $color.name "gray-dark"))) }}
|
||||
<div class="col-md-4 mb-3">
|
||||
<div class="p-3 mb-2 swatch-{{ $color.name }}">
|
||||
<strong class="d-block">${{ $color.name }}</strong>
|
||||
{{ $color.hex }}
|
||||
</div>
|
||||
{{ range (seq 100 100 900) }}
|
||||
<div class="p-3 bd-{{ $color.name }}-{{ . }}">${{ $color.name }}-{{ . }}</div>
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end -}}
|
||||
{{ end -}}
|
||||
|
||||
<div class="col-md-4 mb-3">
|
||||
<div class="p-3 mb-2 bd-gray-500">
|
||||
<strong class="d-block">$gray-500</strong>
|
||||
#adb5bd
|
||||
</div>
|
||||
{{- range $.Site.Data.grays }}
|
||||
<div class="p-3 bd-gray-{{ .name }}">$gray-{{ .name }}</div>
|
||||
{{ end -}}
|
||||
</div>
|
||||
{{< /theme-colors.inline >}}
|
||||
|
||||
<div class="col-md-4 mb-3">
|
||||
<div class="p-3 mb-2 bd-black text-white">
|
||||
<strong class="d-block">$black</strong>
|
||||
#000
|
||||
</div>
|
||||
<div class="p-3 mb-2 bd-white border">
|
||||
<strong class="d-block">$white</strong>
|
||||
#fff
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
### Notes on Sass
|
||||
|
||||
Sass cannot programmatically generate variables, so we manually created variables for every tint and shade ourselves. We specify the midpoint value (e.g., `$blue-500`) and use custom color functions to tint (lighten) or shade (darken) our colors via Sass's `mix()` color function.
|
||||
|
||||
Using `mix()` is not the same as `lighten()` and `darken()`—the former blends the specified color with white or black, while the latter only adjusts the lightness value of each color. The result is a much more complete suite of colors, as [shown in this CodePen demo](https://codepen.io/emdeoh/pen/zYOQOPB).
|
||||
|
||||
Our `tint-color()` and `shade-color()` functions use `mix()` alongside our `$theme-color-interval` variable, which specifies a stepped percentage value for each mixed color we produce. See the `scss/_functions.scss` and `scss/_variables.scss` files for the full source code.
|
||||
|
||||
## Color Sass maps
|
||||
|
||||
Bootstrap's source Sass files include three maps to help you quickly and easily loop over a list of colors and their hex values.
|
||||
|
||||
- `$colors` lists all our available base (`500`) colors
|
||||
- `$theme-colors` lists all semantically named theme colors (shown below)
|
||||
- `$grays` lists all tins and shades of gray
|
||||
|
||||
Within `scss/_variables.scss`, you'll find Bootstrap's color variables and Sass map. Here's an example of the `$colors` Sass map:
|
||||
|
||||
{{< highlight scss >}}
|
||||
$colors: (
|
||||
"blue": $blue,
|
||||
"indigo": $indigo,
|
||||
"purple": $purple,
|
||||
"pink": $pink,
|
||||
"red": $red,
|
||||
"orange": $orange,
|
||||
"yellow": $yellow,
|
||||
"green": $green,
|
||||
"teal": $teal,
|
||||
"cyan": $cyan,
|
||||
"white": $white,
|
||||
"gray": $gray-600,
|
||||
"gray-dark": $gray-800
|
||||
) !default;
|
||||
{{< /highlight >}}
|
||||
|
||||
Add, remove, or modify values within the map to update how they're used in many other components. Unfortunately at this time, not _every_ component utilizes this Sass map. Future updates will strive to improve upon this. Until then, plan on making use of the `${color}` variables and this Sass map.
|
||||
|
||||
### Example
|
||||
|
||||
Here's how you can use these in your Sass:
|
||||
|
||||
{{< highlight scss >}}
|
||||
.alpha { color: $purple; }
|
||||
.beta {
|
||||
color: $yellow-300;
|
||||
background-color: $indigo-900;
|
||||
}
|
||||
{{< /highlight >}}
|
||||
|
||||
[Color utility classes]({{< docsref "/utilities/colors" >}}) are also available for setting `color` and `background-color` using the `500` color values.
|
||||
33
site/content/docs/4.3/customize/components.md
Normal file
33
site/content/docs/4.3/customize/components.md
Normal file
@ -0,0 +1,33 @@
|
||||
---
|
||||
layout: docs
|
||||
title: Components
|
||||
description: Learn how and why we build nearly all our components responsively and with base and modifier classes.
|
||||
group: customize
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Base classes
|
||||
|
||||
Bootstrap's components are largely built with a base-modifier nomenclature. We group as many shared properties as possible into a base class, like `.btn`, and then group individual styles for each variant into modifier classes, like `.btn-primary` or `.btn-success`.
|
||||
|
||||
To build our modifier classes, we use Sass's `@each` loops to iterate over a Sass map. This is especially helpful for generating variants of a component by our `$theme-colors` and creating responsive variants for each breakpoint. As you customize these Sass maps and recompile, you'll automatically see your changes reflected in these loops.
|
||||
|
||||
Check out [our Sass maps and loops docs]({{< docsref "/customize/sass#maps-and-loops" >}}) for how to customize these loops and extend Bootstrap's base-modifier approach to your own code.
|
||||
|
||||
## Modifiers
|
||||
|
||||
Many of Bootstrap's components are built with a base-modifier class approach. This means the bulk of the styling is contained to a base class (e.g., `.btn`) while style variations are confined to modifier classes (e.g., `.btn-danger`). These modifier classes are built from the `$theme-colors` map to make customizing the number and name of our modifier classes.
|
||||
|
||||
Here are two examples of how we loop over the `$theme-colors` map to generate modifiers to the `.alert` and `.list-group` components.
|
||||
|
||||
{{< scss-docs name="alert-modifiers" file="scss/_alert.scss" >}}
|
||||
|
||||
{{< scss-docs name="list-group-modifiers" file="scss/_list-group.scss" >}}
|
||||
|
||||
## Responsive
|
||||
|
||||
These Sass loops aren't limited to color maps, either. You can also generate responsive variations of your components. Take for example our responsive alignment of the dropdowns where we mix an `@each` loop for the `$grid-breakpoints` Sass map with a media query include.
|
||||
|
||||
{{< scss-docs name="responsive-breakpoints" file="scss/_dropdown.scss" >}}
|
||||
|
||||
Should you need to modify your `$grid-breakpoints`, your changes will apply to all the loops iterating over that map.
|
||||
40
site/content/docs/4.3/customize/css-variables.md
Normal file
40
site/content/docs/4.3/customize/css-variables.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
layout: docs
|
||||
title: CSS variables
|
||||
description: Use Bootstrap's CSS custom properties for fast and forward-looking design and development.
|
||||
group: customize
|
||||
toc: true
|
||||
---
|
||||
|
||||
Bootstrap includes around two dozen [CSS custom properties (variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) in its compiled CSS. These provide easy access to commonly used values like our theme colors, breakpoints, and primary font stacks when working in your browser's Inspector, a code sandbox, or general prototyping.
|
||||
|
||||
## Available variables
|
||||
|
||||
Here are the variables we include (note that the `:root` is required). They're located in our `_root.scss` file.
|
||||
|
||||
{{< highlight css >}}
|
||||
{{< root.inline >}}
|
||||
{{- $css := readFile "dist/css/bootstrap.css" -}}
|
||||
{{- $match := findRE ":root {([^}]*)}" $css 1 -}}
|
||||
|
||||
{{- if (eq (len $match) 0) -}}
|
||||
{{- errorf "Got no matches for :root in %q!" $.Page.Path -}}
|
||||
{{- end -}}
|
||||
|
||||
{{- index $match 0 -}}
|
||||
|
||||
{{< /root.inline >}}
|
||||
{{< /highlight >}}
|
||||
|
||||
## Examples
|
||||
|
||||
CSS variables offer similar flexibility to Sass's variables, but without the need for compilation before being served to the browser. For example, here we're resetting our page's font and link styles with CSS variables.
|
||||
|
||||
{{< highlight css >}}
|
||||
body {
|
||||
font: 1rem/1.5 var(--font-family-sans-serif);
|
||||
}
|
||||
a {
|
||||
color: var(--blue);
|
||||
}
|
||||
{{< /highlight >}}
|
||||
40
site/content/docs/4.3/customize/optimize.md
Normal file
40
site/content/docs/4.3/customize/optimize.md
Normal file
@ -0,0 +1,40 @@
|
||||
---
|
||||
layout: docs
|
||||
title: Optimize
|
||||
description: Keep your projects lean, responsive, and maintainable so you can deliver the best experience and focus on more important jobs.
|
||||
group: customize
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Lean Sass imports
|
||||
|
||||
When using Sass in your asset pipeline, make sure you optimize Bootstrap by only `@import`ing the components you need. Your largest optimizations will likely come from the `Layout & Components` section of our `bootstrap.scss`.
|
||||
|
||||
{{< scss-docs name="import-stack" file="scss/bootstrap.scss" >}}
|
||||
|
||||
|
||||
If you're not using a component, comment it out or delete it entirely. For example, if you're not using the carousel, remove that import to save some file size in your compiled CSS. Keep in mind there are some dependencies across Sass imports that may make it more difficult to omit a file.
|
||||
|
||||
## Lean JavaScript
|
||||
|
||||
Bootstrap's JavaScript includes every component in our primary dist files (`bootstrap.js` and `bootstrap.min.js`), and even our primary dependency (Popper.js) with our bundle files (`bootstrap.bundle.js` and `bootstrap.bundle.min.js`). While you're customizing via Sass, be sure to remove related JavaScript.
|
||||
|
||||
## Autoprefixer browserslist.rc
|
||||
|
||||
Bootstrap depends on Autoprefixer to automatically add browser prefixes to certain CSS properties. Prefixes are dictated by our `browserslist.rc` file, found in the root of the Bootstrap repo. Customizing this list of browsers and recompiling the Sass will automatically remove some CSS from your compiled CSS, if there are vendor prefixes unique to that browser or version.
|
||||
|
||||
## Use Purge CSS
|
||||
|
||||
_Help wanted with this section, please consider opening a PR. Thanks!_
|
||||
|
||||
## Minify and gzip
|
||||
|
||||
Whenever possible, be sure to compress all the code you serve to your visitors. If you're using Bootstrap dist files, try to stick to the minified versions (indicated by the `.min.css` and `.min.js` extensions). If you're building Bootstrap from the source with your own build system, be sure to implement your own minifiers for HTML, CSS, and JS.
|
||||
|
||||
## Nonblocking files
|
||||
|
||||
_Help wanted with this section, please consider opening a PR. Thanks!_
|
||||
|
||||
## Always use https
|
||||
|
||||
_Help wanted with this section, please consider opening a PR. Thanks!_
|
||||
28
site/content/docs/4.3/customize/options.md
Normal file
28
site/content/docs/4.3/customize/options.md
Normal file
@ -0,0 +1,28 @@
|
||||
---
|
||||
layout: docs
|
||||
title: Options
|
||||
description: Quickly customize Bootstrap with built-in variables to easily toggle global CSS preferences for controlling style and behavior.
|
||||
group: customize
|
||||
---
|
||||
|
||||
Customize Bootstrap with our built-in custom variables file and easily toggle global CSS preferences with new `$enable-*` Sass variables. Override a variable's value and recompile with `npm run test` as needed.
|
||||
|
||||
You can find and customize these variables for key global options in Bootstrap's `scss/_variables.scss` file.
|
||||
|
||||
{{< table "table text-left" >}}
|
||||
| Variable | Values | Description |
|
||||
| ------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| `$spacer` | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{< docsref "/utilities/spacing" >}}). |
|
||||
| `$enable-rounded` | `true` (default) or `false` | Enables predefined `border-radius` styles on various components. |
|
||||
| `$enable-shadows` | `true` or `false` (default) | Enables predefined `box-shadow` styles on various components. |
|
||||
| `$enable-gradients` | `true` or `false` (default) | Enables predefined gradients via `background-image` styles on various components. |
|
||||
| `$enable-transitions` | `true` (default) or `false` | Enables predefined `transition`s on various components. |
|
||||
| `$enable-reduced-motion` | `true` (default) or `false` | Enables the [`prefers-reduced-motion` media query]({{< docsref "/getting-started/accessibility#reduced-motion" >}}), which suppresses certain animations/transitions based on the users' browser/operating system preferences. |
|
||||
| `$enable-grid-classes` | `true` (default) or `false` | Enables the generation of CSS classes for the grid system (e.g. `.row`, `.col-md-1`, etc.). |
|
||||
| `$enable-caret` | `true` (default) or `false` | Enables pseudo element caret on `.dropdown-toggle`. |
|
||||
| `$enable-button-pointers` | `true` (default) or `false` | Add "hand" cursor to non-disabled button elements. |
|
||||
| `$enable-rfs` | `true` (default) or `false` | Globally enables [RFS]({{< docsref "/getting-started/rfs" >}}). |
|
||||
| `$enable-validation-icons` | `true` (default) or `false` | Enables `background-image` icons within textual inputs and some custom forms for validation states. |
|
||||
| `$enable-deprecation-messages` | `true` or `false` (default) | Set to `true` to show warnings when using any of the deprecated mixins and functions that are planned to be removed in `v5`. |
|
||||
| `$enable-important-utilities` | `true` (default) or `false` | Enables the `!important` suffix in utility classes. |
|
||||
{{< /table >}}
|
||||
21
site/content/docs/4.3/customize/overview.md
Normal file
21
site/content/docs/4.3/customize/overview.md
Normal file
@ -0,0 +1,21 @@
|
||||
---
|
||||
layout: docs
|
||||
title: Customize
|
||||
description: Learn how to theme, customize, and extend Bootstrap with Sass, a boatload of global options, an expansive color system, and more.
|
||||
group: customize
|
||||
toc: false
|
||||
aliases: "/docs/4.3/customize/"
|
||||
sections:
|
||||
- title: Sass
|
||||
description: Utilize our source Sass files to take advantage of variables, maps, mixins, and functions.
|
||||
- title: Options
|
||||
description: Customize Bootstrap with built-in variables to easily toggle global CSS preferences.
|
||||
- title: Color
|
||||
description: Learn about and customize the color systems that support the entire toolkit.
|
||||
- title: Components
|
||||
description: Learn how we build nearly all our components responsively and with base and modifier classes.
|
||||
- title: CSS variables
|
||||
description: Use Bootstrap's CSS custom properties for fast and forward-looking design and development.
|
||||
- title: Optimize
|
||||
description: Keep your projects lean, responsive, and maintainable so you can deliver the best experience.
|
||||
---
|
||||
243
site/content/docs/4.3/customize/sass.md
Normal file
243
site/content/docs/4.3/customize/sass.md
Normal file
@ -0,0 +1,243 @@
|
||||
---
|
||||
layout: docs
|
||||
title: Sass
|
||||
description: Utilize our source Sass files to take advantage of variables, maps, mixins, and functions to help you build faster and customize your project.
|
||||
group: customize
|
||||
toc: true
|
||||
---
|
||||
|
||||
Utilize our source Sass files to take advantage of variables, maps, mixins, and more. In our build we've increased the Sass rounding precision to 6 (by default it's 5) to prevent issues with browser rounding.
|
||||
|
||||
## File structure
|
||||
|
||||
Whenever possible, avoid modifying Bootstrap's core files. For Sass, that means creating your own stylesheet that imports Bootstrap so you can modify and extend it. Assuming you're using a package manager like npm, you'll have a file structure that looks like this:
|
||||
|
||||
{{< highlight text >}}
|
||||
your-project/
|
||||
├── scss
|
||||
│ └── custom.scss
|
||||
└── node_modules/
|
||||
└── bootstrap
|
||||
├── js
|
||||
└── scss
|
||||
{{< /highlight >}}
|
||||
|
||||
If you've downloaded our source files and aren't using a package manager, you'll want to manually setup something similar to that structure, keeping Bootstrap's source files separate from your own.
|
||||
|
||||
{{< highlight text >}}
|
||||
your-project/
|
||||
├── scss
|
||||
│ └── custom.scss
|
||||
└── bootstrap/
|
||||
├── js
|
||||
└── scss
|
||||
{{< /highlight >}}
|
||||
|
||||
## Importing
|
||||
|
||||
In your `custom.scss`, you'll import Bootstrap's source Sass files. You have two options: include all of Bootstrap, or pick the parts you need. We encourage the latter, though be aware there are some requirements and dependencies across our components. You also will need to include some JavaScript for our plugins.
|
||||
|
||||
{{< highlight scss >}}
|
||||
// Custom.scss
|
||||
// Option A: Include all of Bootstrap
|
||||
|
||||
@import "../node_modules/bootstrap/scss/bootstrap";
|
||||
{{< /highlight >}}
|
||||
|
||||
{{< highlight scss >}}
|
||||
// Custom.scss
|
||||
// Option B: Include parts of Bootstrap
|
||||
|
||||
// Required
|
||||
@import "../node_modules/bootstrap/scss/functions";
|
||||
@import "../node_modules/bootstrap/scss/variables";
|
||||
@import "../node_modules/bootstrap/scss/mixins";
|
||||
|
||||
// Optional
|
||||
@import "../node_modules/bootstrap/scss/reboot";
|
||||
@import "../node_modules/bootstrap/scss/type";
|
||||
@import "../node_modules/bootstrap/scss/images";
|
||||
@import "../node_modules/bootstrap/scss/code";
|
||||
@import "../node_modules/bootstrap/scss/grid";
|
||||
{{< /highlight >}}
|
||||
|
||||
With that setup in place, you can begin to modify any of the Sass variables and maps in your `custom.scss`. You can also start to add parts of Bootstrap under the `// Optional` section as needed. We suggest using the full import stack from our `bootstrap.scss` file as your starting point.
|
||||
|
||||
## 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.
|
||||
|
||||
You will find the complete list of Bootstrap's variables in `scss/_variables.scss`. Some variables are set to `null`, these variables don't output the property unless they are overridden in your configuration.
|
||||
|
||||
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";
|
||||
{{< /highlight >}}
|
||||
|
||||
Repeat as necessary for any variable in Bootstrap, including the global options below.
|
||||
|
||||
## Maps and loops
|
||||
|
||||
Bootstrap 4 includes a handful of Sass maps, key value pairs that make it easier to generate families of related CSS. We use Sass maps for our colors, grid breakpoints, and more. Just like Sass variables, all Sass maps include the `!default` flag and can be overridden and extended.
|
||||
|
||||
Some of our Sass maps are merged into empty ones by default. This is done to allow easy expansion of a given Sass map, but comes at the cost of making _removing_ items from a map slightly more difficult.
|
||||
|
||||
### Modify map
|
||||
|
||||
All variables in the `$theme-colors` map are defined as standalone variables. To modify an existing color in our `$theme-colors` map, add the following to your custom Sass file:
|
||||
|
||||
{{< highlight scss >}}
|
||||
$primary: #0074d9;
|
||||
$danger: #ff4136;
|
||||
{{< /highlight >}}
|
||||
|
||||
Later on, theses variables are set in Bootstrap's `$theme-colors` map:
|
||||
|
||||
{{< highlight scss >}}
|
||||
$theme-colors: (
|
||||
"primary": $primary,
|
||||
"danger": $danger
|
||||
);
|
||||
{{< /highlight >}}
|
||||
|
||||
### Add to map
|
||||
|
||||
To add a new color to `$theme-colors`, add the new key and value:
|
||||
|
||||
{{< highlight scss >}}
|
||||
$theme-colors: (
|
||||
"custom-color": #900
|
||||
);
|
||||
{{< /highlight >}}
|
||||
|
||||
### Remove from map
|
||||
|
||||
To remove colors from `$theme-colors`, or any other map, use `map-remove`. Be aware you must insert it between our requirements and options:
|
||||
|
||||
{{< highlight scss >}}
|
||||
// Required
|
||||
@import "../node_modules/bootstrap/scss/functions";
|
||||
@import "../node_modules/bootstrap/scss/variables";
|
||||
@import "../node_modules/bootstrap/scss/mixins";
|
||||
|
||||
$theme-colors: map-remove($theme-colors, "info", "light", "dark");
|
||||
|
||||
// Optional
|
||||
@import "../node_modules/bootstrap/scss/root";
|
||||
@import "../node_modules/bootstrap/scss/reboot";
|
||||
@import "../node_modules/bootstrap/scss/type";
|
||||
...
|
||||
{{< /highlight >}}
|
||||
|
||||
## Required keys
|
||||
|
||||
Bootstrap assumes the presence of some specific keys within Sass maps as we used and extend these ourselves. As you customize the included maps, you may encounter errors where a specific Sass map's key is being used.
|
||||
|
||||
For example, we use the `primary`, `success`, and `danger` keys from `$theme-colors` for links, buttons, and form states. Replacing the values of these keys should present no issues, but removing them may cause Sass compilation issues. In these instances, you'll need to modify the Sass code that makes use of those values.
|
||||
|
||||
## Functions
|
||||
|
||||
### Colors
|
||||
|
||||
In Bootstrap 5, we've dropped the `color()`, `theme-color()` and `gray()` functions because the values are also available as standalone variables. So instead of using `theme-color("primary")`, you can now just use the `$primary` variable.
|
||||
|
||||
{{< highlight scss >}}
|
||||
.custom-element {
|
||||
color: $gray-100;
|
||||
background-color: $dark;
|
||||
}
|
||||
{{< /highlight >}}
|
||||
|
||||
We also have a function for getting a particular _level_ of color. Negative level values will lighten the color, while higher levels will darken.
|
||||
|
||||
{{< scss-docs name="color-level" file="scss/_functions.scss" >}}
|
||||
|
||||
In practice, you'd call the function and pass in two parameters: the name of the color from `$theme-colors` (e.g., primary or danger) and a numeric level.
|
||||
|
||||
{{< highlight scss >}}
|
||||
.custom-element {
|
||||
color: color-level($primary, -10);
|
||||
}
|
||||
{{< /highlight >}}
|
||||
|
||||
### Color contrast
|
||||
|
||||
In order to meet [WCAG 2.0 accessibility standards for color contrast](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html), authors **must** provide [a contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG20/quickref/20160105/Overview.php#visual-audio-contrast-contrast), with very few exceptions.
|
||||
|
||||
An additional function we include in Bootstrap is the color contrast function, `color-contrast`. It utilizes the [WCAG 2.0 algorithm](https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests) for calculating contrast thresholds based on [relative luminance](https://www.w3.org/WAI/GL/wiki/Relative_luminance) in a `sRGB` colorspace to automatically return a light (`#fff`) or dark (`#111`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
|
||||
|
||||
For example, to generate color swatches from our `$theme-colors` map:
|
||||
|
||||
{{< highlight scss >}}
|
||||
@each $color, $value in $theme-colors {
|
||||
.swatch-#{$color} {
|
||||
color: color-contrast($value);
|
||||
}
|
||||
}
|
||||
{{< /highlight >}}
|
||||
|
||||
It can also be used for one-off contrast needs:
|
||||
|
||||
{{< highlight scss >}}
|
||||
.custom-element {
|
||||
color: color-contrast(#000); // returns `color: #fff`
|
||||
}
|
||||
{{< /highlight >}}
|
||||
|
||||
You can also specify a base color with our color map functions:
|
||||
|
||||
{{< highlight scss >}}
|
||||
.custom-element {
|
||||
color: color-contrast($dark); // returns `color: #fff`
|
||||
}
|
||||
{{< /highlight >}}
|
||||
|
||||
### Escape SVG
|
||||
|
||||
We use the `escape-svg` function to escape the `<`, `>` and `#` characters for SVG background images.
|
||||
|
||||
### Add and Subtract functions
|
||||
|
||||
We use the `add` and `subtract` functions to wrap the CSS `calc` function. The primary purpose of these functions is to avoid errors when a "unitless" `0` value is passed into a `calc` expression. Expressions like `calc(10px - 0)` will return an error in all browsers, despite being mathematically correct.
|
||||
|
||||
Example where the calc is valid:
|
||||
|
||||
{{< highlight scss >}}
|
||||
$border-radius: .25rem;
|
||||
$border-width: 1px;
|
||||
|
||||
.element {
|
||||
// Output calc(.25rem - 1px) is valid
|
||||
border-radius: calc($border-radius - $border-width);
|
||||
}
|
||||
|
||||
.element {
|
||||
// Output the same calc(.25rem - 1px) as above
|
||||
border-radius: subtract($border-radius, $border-width);
|
||||
}
|
||||
{{< /highlight >}}
|
||||
|
||||
Example where the calc is invalid:
|
||||
|
||||
{{< highlight scss >}}
|
||||
$border-radius: .25rem;
|
||||
$border-width: 0;
|
||||
|
||||
.element {
|
||||
// Output calc(.25rem - 0) is invalid
|
||||
border-radius: calc($border-radius - $border-width);
|
||||
}
|
||||
|
||||
.element {
|
||||
// Output .25rem
|
||||
border-radius: subtract($border-radius, $border-width);
|
||||
}
|
||||
{{< /highlight >}}
|
||||
@ -35,7 +35,7 @@ This means that you will have to make sure to add both of them to your `package.
|
||||
|
||||
To enjoy the full potential of Bootstrap and customize it to your needs, use the source files as a part of your project's bundling process.
|
||||
|
||||
First, create your own `_custom.scss` and use it to override the [built-in custom variables]({{< docsref "/getting-started/theming" >}}). Then, use your main Sass file to import your custom variables, followed by Bootstrap:
|
||||
First, create your own `_custom.scss` and use it to override the [built-in custom variables]({{< docsref "/customize/sass" >}}). Then, use your main Sass file to import your custom variables, followed by Bootstrap:
|
||||
|
||||
{{< highlight scss >}}
|
||||
@import "custom";
|
||||
|
||||
@ -42,9 +42,9 @@ Changes to our source Sass files and compiled CSS.
|
||||
- Line heights are dropped from several components to simplify our codebase. The `button-size()` and `pagination-size()` do not accept line height parameters anymore. [See #29271](https://github.com/twbs/bootstrap/pull/29271)
|
||||
- The `button-variant()` mixin now accepts 3 optional color parameters, for each button state, to override the color provided by `color-contrast()`. By default, these parameters will find which color provides more contrast against the button state's background color with `color-contrast()`.
|
||||
- The `button-outline-variant()` mixin now accepts an additional argument, `$active-color`, for setting the button's active state text color. By default, this parameter will find which color provides more contrast against the button's active background color with `color-contrast()`.
|
||||
- Ditch the Sass map merges, which makes it easier to remove redundant values. Keep in mind you now have to define all values in the Sass maps like `$theme-colors`. Check out how to deal with Sass maps on the [theming documentation]({{< docsref "/getting-started/theming#maps-and-loops" >}}).
|
||||
- `color-yiq()` function is renamed to `color-contrast()` since it's not related to YIQ colorspace anymore — [See #30168](https://github.com/twbs/bootstrap/pull/30168/) — and related variables are renamed alongside:
|
||||
- `$yiq-contrasted-threshold` is renamed `$min-contrast-ratio`,
|
||||
- Ditch the Sass map merges, which makes it easier to remove redundant values. Keep in mind you now have to define all values in the Sass maps like `$theme-colors`. Check out how to deal with [Sass maps]({{< docsref "/customize/sass#maps-and-loops" >}}).
|
||||
- `color-yiq()` function and related variables are renamed to `color-contrast()` since it's not related to YIQ colorspace anymore. [See #30168.](https://github.com/twbs/bootstrap/pull/30168/)
|
||||
- `$yiq-contrasted-threshold` is renamed `$min-contrast-ratio`.
|
||||
- `$yiq-text-dark` and `$yiq-text-light` are respectively renamed `$color-contrast-dark` and `$color-contrast-light`.
|
||||
|
||||
## JavaScript
|
||||
@ -54,6 +54,14 @@ Changes to our source and compiled JavaScript files.
|
||||
- Dropped jQuery dependency and rewrote plugins to be in regular JavaScript.
|
||||
- Removed underscore from public static methods like `_getInstance()` → `getInstance()`.
|
||||
|
||||
## Color system
|
||||
|
||||
We've updated the color system that powers Bootstrap to improve color contrast and provide a much more extensive set of colors.
|
||||
|
||||
- Updated blue and pink base colors (`-500`) to ensure AA contrast.
|
||||
- Added new tints and shades for every color, providing nine separate colors for each base color.
|
||||
- To support our color system, we've added new custom `tint()` and `shade()` functions to mix our colors appropriately.
|
||||
|
||||
## Grid and layout
|
||||
|
||||
Changes to any layout tools and our grid system.
|
||||
|
||||
@ -39,7 +39,7 @@ Similar to the contextual text color classes, easily set the background of an el
|
||||
|
||||
## Background gradient
|
||||
|
||||
When `$enable-gradients` is set to `true` (default is `false`), you can use `.bg-gradient-` utility classes. [Learn about our Sass options]({{< docsref "/getting-started/theming#sass-options" >}}) to enable these classes and more.
|
||||
When `$enable-gradients` is set to `true` (default is `false`), you can use `.bg-gradient-` utility classes. [Learn about our Sass options]({{< docsref "/customize/sass" >}}) to enable these classes and more.
|
||||
|
||||
{{< markdown >}}
|
||||
{{< colors.inline >}}
|
||||
|
||||
@ -5,13 +5,21 @@
|
||||
- title: Contents
|
||||
- title: Browsers & devices
|
||||
- title: JavaScript
|
||||
- title: Theming
|
||||
- title: Build tools
|
||||
# - title: Best practices # TODO: Write this content
|
||||
- title: Webpack
|
||||
- title: Accessibility
|
||||
- title: RFS
|
||||
|
||||
- title: Customize
|
||||
pages:
|
||||
- title: Overview
|
||||
- title: Sass
|
||||
- title: Options
|
||||
- title: Color
|
||||
- title: Components
|
||||
- title: CSS variables
|
||||
- title: Optimize
|
||||
|
||||
- title: Layout
|
||||
pages:
|
||||
- title: Breakpoints
|
||||
|
||||
Loading…
Reference in New Issue
Block a user