0
0
mirror of https://github.com/twbs/bootstrap.git synced 2025-01-30 22:52:24 +01:00

Sass docs updates (#37897)

* Add maps

* Redesign scss-docs rendering

* Update other CSS sections

* Fix linter
This commit is contained in:
Mark Otto 2023-01-16 18:57:24 -08:00 committed by GitHub
parent eec5015520
commit 20ab8219a0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
22 changed files with 133 additions and 46 deletions

View File

@ -6,6 +6,7 @@
$theme-colors-rgb: map-loop($theme-colors, to-rgb, "$value") !default;
// scss-docs-end theme-colors-rgb
// scss-docs-start theme-text-map
$theme-colors-text: (
"primary": $primary-text,
"secondary": $secondary-text,
@ -16,7 +17,9 @@ $theme-colors-text: (
"light": $light-text,
"dark": $dark-text,
) !default;
// scss-docs-end theme-text-map
// scss-docs-start theme-bg-subtle-map
$theme-colors-bg-subtle: (
"primary": $primary-bg-subtle,
"secondary": $secondary-bg-subtle,
@ -27,7 +30,9 @@ $theme-colors-bg-subtle: (
"light": $light-bg-subtle,
"dark": $dark-bg-subtle,
) !default;
// scss-docs-end theme-bg-subtle-map
// scss-docs-start theme-border-subtle-map
$theme-colors-border-subtle: (
"primary": $primary-border-subtle,
"secondary": $secondary-border-subtle,
@ -38,12 +43,14 @@ $theme-colors-border-subtle: (
"light": $light-border-subtle,
"dark": $dark-border-subtle,
) !default;
// scss-docs-end theme-border-subtle-map
$theme-colors-text-dark: null !default;
$theme-colors-bg-subtle-dark: null !default;
$theme-colors-border-subtle-dark: null !default;
@if $enable-dark-mode {
// scss-docs-start theme-text-dark-map
$theme-colors-text-dark: (
"primary": $primary-text-dark,
"secondary": $secondary-text-dark,
@ -54,7 +61,9 @@ $theme-colors-border-subtle-dark: null !default;
"light": $light-text-dark,
"dark": $dark-text-dark,
) !default;
// scss-docs-end theme-text-dark-map
// scss-docs-start theme-bg-subtle-dark-map
$theme-colors-bg-subtle-dark: (
"primary": $primary-bg-subtle-dark,
"secondary": $secondary-bg-subtle-dark,
@ -65,7 +74,9 @@ $theme-colors-border-subtle-dark: null !default;
"light": $light-bg-subtle-dark,
"dark": $dark-bg-subtle-dark,
) !default;
// scss-docs-end theme-bg-subtle-dark-map
// scss-docs-start theme-border-subtle-dark-map
$theme-colors-border-subtle-dark: (
"primary": $primary-border-subtle-dark,
"secondary": $secondary-border-subtle-dark,
@ -76,6 +87,7 @@ $theme-colors-border-subtle-dark: null !default;
"light": $light-border-subtle-dark,
"dark": $dark-border-subtle-dark,
) !default;
// scss-docs-end theme-border-subtle-dark-map
}
// Utilities maps

View File

@ -7,6 +7,7 @@
//
// scss-docs-start sass-dark-mode-vars
// scss-docs-start theme-text-dark-variables
$primary-text-dark: $blue-300 !default;
$secondary-text-dark: $gray-300 !default;
$success-text-dark: $green-300 !default;
@ -15,7 +16,9 @@ $warning-text-dark: $yellow-300 !default;
$danger-text-dark: $red-300 !default;
$light-text-dark: $gray-100 !default;
$dark-text-dark: $gray-300 !default;
// scss-docs-end theme-text-dark-variables
// scss-docs-start theme-bg-subtle-dark-variables
$primary-bg-subtle-dark: $blue-900 !default;
$secondary-bg-subtle-dark: $gray-900 !default;
$success-bg-subtle-dark: $green-900 !default;
@ -24,7 +27,9 @@ $warning-bg-subtle-dark: $yellow-900 !default;
$danger-bg-subtle-dark: $red-900 !default;
$light-bg-subtle-dark: $gray-800 !default;
$dark-bg-subtle-dark: mix($gray-800, $black) !default;
// scss-docs-end theme-bg-subtle-dark-variables
// scss-docs-start theme-border-subtle-dark-variables
$primary-border-subtle-dark: $blue-700 !default;
$secondary-border-subtle-dark: $gray-700 !default;
$success-border-subtle-dark: $green-700 !default;
@ -33,6 +38,7 @@ $warning-border-subtle-dark: $yellow-800 !default;
$danger-border-subtle-dark: $red-700 !default;
$light-border-subtle-dark: $gray-700 !default;
$dark-border-subtle-dark: $gray-800 !default;
// scss-docs-end theme-border-subtle-dark-variables
$body-color-dark: $gray-500 !default;
$body-bg-dark: $gray-900 !default;

View File

@ -321,6 +321,7 @@ $theme-colors: (
) !default;
// scss-docs-end theme-colors-map
// scss-docs-start theme-text-variables
$primary-text: $blue-700 !default;
$secondary-text: $gray-700 !default;
$success-text: $green-700 !default;
@ -329,7 +330,9 @@ $warning-text: $yellow-800 !default;
$danger-text: $red-700 !default;
$light-text: $gray-700 !default;
$dark-text: $gray-700 !default;
// scss-docs-end theme-text-variables
// scss-docs-start theme-bg-subtle-variables
$primary-bg-subtle: $blue-100 !default;
$secondary-bg-subtle: $gray-100 !default;
$success-bg-subtle: $green-100 !default;
@ -338,7 +341,9 @@ $warning-bg-subtle: $yellow-100 !default;
$danger-bg-subtle: $red-100 !default;
$light-bg-subtle: mix($gray-100, $white) !default;
$dark-bg-subtle: $gray-400 !default;
// scss-docs-end theme-bg-subtle-variables
// scss-docs-start theme-border-subtle-variables
$primary-border-subtle: $blue-200 !default;
$secondary-border-subtle: $gray-200 !default;
$success-border-subtle: $green-200 !default;
@ -347,6 +352,7 @@ $warning-border-subtle: $yellow-200 !default;
$danger-border-subtle: $red-200 !default;
$light-border-subtle: $gray-200 !default;
$dark-border-subtle: $gray-500 !default;
// scss-docs-end theme-border-subtle-variables
// Characters which are escaped by the escape-svg function
$escaped-characters: (

View File

@ -380,6 +380,7 @@
.highlight {
margin-bottom: 0;
@include border-top-radius(0);
}
.bd-example {
@ -398,6 +399,12 @@
background-color: var(--bd-pre-bg);
}
.bd-scss-docs {
.highlight-toolbar {
@include border-top-radius(calc(var(--bs-border-radius) + 1px));
}
}
.focused {
outline: 0;
box-shadow: var(--#{$variable-prefix}focus-ring-offset), var(--#{$variable-prefix}focus-ring-x, 0) var(--#{$variable-prefix}focus-ring-y, 0) var(--#{$variable-prefix}focus-ring-blur) var(--#{$variable-prefix}focus-ring-width) var(--#{$variable-prefix}focus-ring-color);

View File

@ -347,9 +347,9 @@ Add `.carousel-dark` to the `.carousel` for darker controls, indicators, and cap
The transition duration of `.carousel-item` can be changed with the `$carousel-transition-duration` Sass variable before compiling or custom styles if you're using the compiled CSS. If multiple transitions are applied, make sure the transform transition is defined first (e.g. `transition: transform 2s ease, opacity .5s ease-out`).
## Sass
## CSS
### Variables
### Sass variables
Variables for all carousels:

View File

@ -100,9 +100,9 @@ If your control element is targeting a single collapsible element i.e. the `
Note that Bootstrap's current implementation does not cover the various *optional* keyboard interactions described in the [ARIA Authoring Practices Guide accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) - you will need to include these yourself with custom JavaScript.
## Sass
## CSS
### Variables
### Sass variables
{{< scss-docs name="collapse-transition" file="scss/_variables.scss" >}}

View File

@ -26,8 +26,8 @@ Aligning the figure's caption is easy with our [text utilities]({{< docsref "/ut
</figure>
{{< /example >}}
## Sass
## CSS
### Variables
### Sass variables
{{< scss-docs name="figure-variables" file="scss/_variables.scss" >}}

View File

@ -823,13 +823,13 @@ Use `.table-responsive{-sm|-md|-lg|-xl|-xxl}` as needed to create responsive tab
{{< /tables.inline >}}
{{< /highlight >}}
## Sass
## CSS
### Variables
### Sass variables
{{< scss-docs name="table-variables" file="scss/_variables.scss" >}}
### Loop
### Sass loop
{{< scss-docs name="table-loop" file="scss/_variables.scss" >}}

View File

@ -269,9 +269,9 @@ Align terms and descriptions horizontally by using our grid system's predefined
In Bootstrap 5, we've enabled responsive font sizes by default, allowing text to scale more naturally across device and viewport sizes. Have a look at the [RFS page]({{< docsref "/getting-started/rfs" >}}) to find out how this works.
## Sass
## CSS
### Variables
### Sass variables
Headings have some dedicated variables for sizing and spacing.
@ -281,6 +281,6 @@ Miscellaneous typography elements covered here and in [Reboot]({{< docsref "/con
{{< scss-docs name="type-variables" file="scss/_variables.scss" >}}
### Mixins
### Sass mixins
There are no dedicated mixins for typography, but Bootstrap does use [Responsive Font Sizing (RFS)]({{< docsref "/getting-started/rfs" >}}).

View File

@ -300,9 +300,9 @@ Different variants of `.btn`, such at the various outlined styles, are supported
<label class="btn btn-outline-danger" for="danger-outlined">Danger radio</label>
{{< /example >}}
## Sass
## CSS
### Variables
### Sass variables
Variables for checks:

View File

@ -312,8 +312,8 @@ Input groups include support for custom selects and custom file inputs. Browser
</div>
{{< /example >}}
## Sass
## CSS
### Variables
### Sass variables
{{< scss-docs name="input-group-variables" file="scss/_variables.scss" >}}

View File

@ -105,11 +105,11 @@ If none of these are present, assistive technologies may resort to using the `pl
While using visually hidden content (`.visually-hidden`, `aria-label`, and even `placeholder` content, which disappears once a form field has content) will benefit assistive technology users, a lack of visible label text may still be problematic for certain users. Some form of visible label is generally the best approach, both for accessibility and usability.
## Sass
## CSS
Many form variables are set at a general level to be re-used and extended by individual form components. You'll see these most often as `$input-btn-*` and `$input-*` variables.
### Variables
### Sass variables
`$input-btn-*` variables are shared global variables between our [buttons]({{< docsref "/components/buttons" >}}) and our form components. You'll find these frequently reassigned as values to other component-specific variables.

View File

@ -42,8 +42,8 @@ By default, range inputs "snap" to integer values. To change this, you can speci
<input type="range" class="form-range" min="0" max="5" step="0.5" id="customRange3">
{{< /example >}}
## Sass
## CSS
### Variables
### Sass variables
{{< scss-docs name="form-range-variables" file="scss/_variables.scss" >}}

View File

@ -74,8 +74,8 @@ Add the `disabled` boolean attribute on a select to give it a grayed out appeara
</select>
{{< /example >}}
## Sass
## CSS
### Variables
### Sass variables
{{< scss-docs name="form-select-variables" file="scss/_variables.scss" >}}

View File

@ -349,19 +349,19 @@ If your form layout allows it, you can swap the `.{valid|invalid}-feedback` clas
</form>
{{< /example >}}
## Sass
## CSS
### Variables
### Sass variables
{{< scss-docs name="form-feedback-variables" file="scss/_variables.scss" >}}
### Mixins
### Sass mixins
Two mixins are combined together, through our [loop](#loop), to generate our form validation feedback styles.
{{< scss-docs name="form-validation-mixins" file="scss/mixins/_forms.scss" >}}
### Map
### Sass map
This is the validation Sass map from `_variables.scss`. Override or extend this to generate different or additional states.
@ -369,7 +369,7 @@ This is the validation Sass map from `_variables.scss`. Override or extend this
Maps of `$form-validation-states` can contain three optional parameters to override tooltips and focus styles.
### Loop
### Sass loop
Used to iterate over `$form-validation-states` map values to generate our validation styles. Any modifications to the above Sass map will be reflected in your compiled CSS via this loop.

View File

@ -80,6 +80,6 @@ Create an inline form with `.hstack`:
</div>
{{< /example >}}
## Sass
## CSS
{{< scss-docs name="stacks" file="scss/helpers/_stacks.scss" >}}

View File

@ -409,11 +409,11 @@ To nest your content with the default grid, add a new `.row` and set of `.col-sm
</div>
{{< /example >}}
## Sass
## CSS
When using Bootstrap's source Sass files, you have the option of using Sass variables and mixins to create custom, semantic, and responsive page layouts. Our predefined grid classes use these same variables and mixins to provide a whole suite of ready-to-use classes for fast responsive layouts.
### Variables
### Sass variables
Variables and maps determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below.
@ -427,7 +427,7 @@ $grid-row-columns: 6;
{{< scss-docs name="container-max-widths" file="scss/_variables.scss" >}}
### Mixins
### Sass mixins
Mixins are used in conjunction with the grid variables to generate semantic CSS for individual grid columns.

View File

@ -83,11 +83,11 @@ Or, choose from any of the `.bg-opacity` utilities:
<div class="bg-success p-2 text-dark bg-opacity-10">This is 10% opacity success background</div>
{{< /example >}}
## Sass
## CSS
In addition to the following Sass functionality, consider reading about our included [CSS custom properties]({{< docsref "/customize/css-variables" >}}) (aka CSS variables) for colors and more.
### Variables
### Sass variables
Most `background-color` utilities are generated by our theme colors, reassigned from our generic color palette variables.
@ -101,7 +101,13 @@ Grayscale colors are also available, but only a subset are used to generate any
{{< scss-docs name="gray-color-variables" file="scss/_variables.scss" >}}
### Map
Variables for setting `background-color` in `.bg-*-subtle` utilities in light and dark mode:
{{< scss-docs name="theme-bg-subtle-variables" file="scss/_variables.scss" >}}
{{< scss-docs name="theme-bg-subtle-dark-variables" file="scss/_variables-dark.scss" >}}
### Sass maps
Theme colors are then put into a Sass map so we can loop over them to generate our utilities, component modifiers, and more.
@ -115,11 +121,17 @@ RGB colors are generated from a separate Sass map:
{{< scss-docs name="theme-colors-rgb" file="scss/_maps.scss" >}}
And background color opacities build on that with their own map that's consumed by the utilities API:
Background color opacities build on that with their own map that's consumed by the utilities API:
{{< scss-docs name="utilities-bg-colors" file="scss/_maps.scss" >}}
### Mixins
Color mode background colors are also available as a Sass map:
{{< scss-docs name="theme-bg-subtle-map" file="scss/_maps.scss" >}}
{{< scss-docs name="theme-bg-subtle-dark-map" file="scss/_maps.scss" >}}
### Sass mixins
**No mixins are used to generate our background utilities**, but we do have some additional mixins for other situations where you'd like to create your own gradients.
@ -127,7 +139,7 @@ And background color opacities build on that with their own map that's consumed
{{< scss-docs name="gradient-mixins" file="scss/mixins/_gradients.scss" >}}
### Utilities API
## Utilities API
Background utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})

View File

@ -166,6 +166,20 @@ Use the scaling classes for larger or smaller rounded corners. Sizes range from
{{< scss-docs name="border-radius-variables" file="scss/_variables.scss" >}}
Variables for setting `border-color` in `.border-*-subtle` utilities in light and dark mode:
{{< scss-docs name="theme-border-subtle-variables" file="scss/_variables.scss" >}}
{{< scss-docs name="theme-border-subtle-dark-variables" file="scss/_variables-dark.scss" >}}
### Sass maps
Color mode adaptive border colors are also available as a Sass map:
{{< scss-docs name="theme-border-subtle-map" file="scss/_maps.scss" >}}
{{< scss-docs name="theme-border-subtle-dark-map" file="scss/_maps.scss" >}}
### Sass mixins
{{< scss-docs name="border-radius-mixins" file="scss/mixins/_border-radius.scss" >}}

View File

@ -87,11 +87,11 @@ Or, choose from any of the `.text-opacity` utilities:
Sometimes contextual classes cannot be applied due to the specificity of another selector. In some cases, a sufficient workaround is to wrap your element's content in a `<div>` or more semantic element with the desired class.
## Sass
## CSS
In addition to the following Sass functionality, consider reading about our included [CSS custom properties]({{< docsref "/customize/css-variables" >}}) (aka CSS variables) for colors and more.
### Variables
### Sass variables
Most `color` utilities are generated by our theme colors, reassigned from our generic color palette variables.
@ -103,7 +103,15 @@ Grayscale colors are also available, but only a subset are used to generate any
{{< scss-docs name="gray-color-variables" file="scss/_variables.scss" >}}
### Map
{{< scss-docs name="theme-text-map" file="scss/_maps.scss" >}}
Variables for setting colors in `.text-*-emphasis` utilities in light and dark mode:
{{< scss-docs name="theme-text-variables" file="scss/_variables.scss" >}}
{{< scss-docs name="theme-text-dark-variables" file="scss/_variables-dark.scss" >}}
### Sass maps
Theme colors are then put into a Sass map so we can loop over them to generate our utilities, component modifiers, and more.
@ -117,10 +125,16 @@ RGB colors are generated from a separate Sass map:
{{< scss-docs name="theme-colors-rgb" file="scss/_maps.scss" >}}
And color opacities build on that with their own map that's consumed by the utilities API:
Color opacities build on that with their own map that's consumed by the utilities API:
{{< scss-docs name="utilities-text-colors" file="scss/_maps.scss" >}}
Color mode adaptive text colors are also available as a Sass map:
{{< scss-docs name="theme-text-map" file="scss/_maps.scss" >}}
{{< scss-docs name="theme-text-dark-map" file="scss/_maps.scss" >}}
### Utilities API
Color utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})

View File

@ -137,19 +137,23 @@ Decorate text in components with text decoration classes.
<a href="#" class="text-decoration-none">This link has its text decoration removed</a>
{{< /example >}}
## Sass
## CSS
### Variables
### Sass variables
Default type and font related Sass variables:
{{< scss-docs name="font-variables" file="scss/_variables.scss" >}}
### Maps
### Sass maps
Font-size utilities are generated from this map, in combination with our utilities API.
{{< scss-docs name="font-sizes" file="scss/_variables.scss" >}}
### Utilities API
{{< scss-docs name="theme-text-map" file="scss/_maps.scss" >}}
## Utilities API
Font and text utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})

View File

@ -39,5 +39,17 @@
{{- $match = replace $match " !default" "" -}}
{{- end -}}
{{- highlight $match "scss" "" -}}
<div class="bd-example-snippet bd-code-snippet bd-scss-docs">
<div class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-bottom">
<a class="font-monospace text-body-secondary text-decoration-none small" href="{{ .Site.Params.repo }}/blob/v{{ .Site.Params.current_version }}/{{ $file | replaceRE `\\` "/" }}">
{{- $file -}}
</a>
<div class="d-flex ms-auto">
<button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">
<svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"/></svg>
</button>
</div>
</div>
{{- highlight $match "scss" "" -}}
</div>
{{- end -}}