From db46bfc03f3a22752ef6bd91ae577d893872a216 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 24 Jun 2023 14:44:40 +0200 Subject: Merging upstream version 5.3.0+dfsg. Signed-off-by: Daniel Baumann --- site/content/docs/5.3/migration.md | 737 +++++++++++++++++++++++++++++++++++++ 1 file changed, 737 insertions(+) create mode 100644 site/content/docs/5.3/migration.md (limited to 'site/content/docs/5.3/migration.md') diff --git a/site/content/docs/5.3/migration.md b/site/content/docs/5.3/migration.md new file mode 100644 index 0000000..99575b5 --- /dev/null +++ b/site/content/docs/5.3/migration.md @@ -0,0 +1,737 @@ +--- +layout: docs +title: Migrating to v5 +description: Track and review changes to the Bootstrap source files, documentation, and components to help you migrate from v4 to v5. +group: migration +aliases: "/migration/" +toc: true +--- + +## v5.3.0 + +If you're migrating from our previous alpha releases of v5.3.0, please review their changes in addition to this section. + +### Helpers + +- [Colored links]({{< docsref "/helpers/colored-links" >}}) once again have `!important` so they work better with our newly added link utilities. + +### Utilities + +- Added new `.d-inline-grid` [display utility]({{< docsref "/utilities/display" >}}). + +## v5.3.0-alpha2 + +If you're migrating from our previous alpha release of v5.3.0, please review the changes listed below. + +### CSS variables + +- Removed several duplicate and unused root CSS variables. + +### Color modes + +- Dark mode colors are now derived from our theme colors (e.g., `$primary`) in Sass, rather than color specific tints or shades (e.g., `$blue-300`). This allows for a more automated dark mode when customizing the default theme colors. + +- Added Sass maps for generating theme colors for dark mode text, subtle background, and subtle border. + +- [Snippet examples]({{< docsref "/examples#snippets" >}}) are now ready for dark mode with updated markup and reduced custom styles. + +- Added `color-scheme: dark` to dark mode CSS to change OS level controls like scrollbars + +- Form validation `border-color` and text `color` states now respond to dark mode, thanks to new Sass and CSS variables. + +- Dropped recently added form control background CSS variables and reassigned the Sass variables to use CSS variables instead. This simplifies the styling across color modes and avoids an issue where form controls in dark mode wouldn't update properly. + +- Our `box-shadow`s will once again always stay dark instead of inverting to white when in dark mode. + +- Improved HTML and JavaScript for our color mode toggle script. The selector for changing the active SVG has been improved, and the markup made more accessible with ARIA attributes. + +- Improved docs code syntax colors and more across light and dark modes. + +### Typography + +- We no longer set a color for `$headings-color-dark` or `--bs-heading-color` for dark mode. To avoid several problems of headings within components appearing the wrong color, we've set the Sass variable to `null` and added a `null` check like we use on the default light mode. + +### Components + +- Cards now have a `color` set on them to improve rendering across color modes. + +- Added new `.nav-underline` variant for our navigation with a simpler bottom border under the active nav link. [See the docs for an example.]({{< docsref "/components/navs-tabs#underline" >}}) + +- Navs now have new `:focus-visible` styles that better match our custom button focus styles. + +### Helpers + +- Added new `.icon-link` helper to quickly place and align Bootstrap Icons alongside a textual link. Icon links support our new link utilities, too. + +- Added new focus ring helper for removing the default `outline` and setting a custom `box-shadow` focus ring. + +### Utilities + +- Renamed Sass and CSS variables `${color}-text` to `${color}-text-emphasis` to match their associated utilities. + +- Added new `.link-body-emphasis` helper alongside our [colored links]({{< docsref "/helpers/colored-links" >}}). This creates a colored link using our color mode responsive emphasis color. + +- Added new link utilities for link color opacity, underline offset, underline color, and underline opacity. [Explore the new links utilities.]({{< docsref "/utilities/link" >}}) + +- CSS variable based `border-width` utilities have been reverted to set their property directly (as was done prior to v5.2.0). This avoids inheritance issues across nested elements, including tables. + +- Added new `.border-black` utility to match our `.text-black` and `.bg-black` utilities. + +- Deprecated Deprecated the `.text-muted` utility and `$text-muted` Sass variable. It's been replaced by `.text-body-secondary` and `$body-secondary-color`. + +### Docs + +- Examples are now displayed with the appropriate light or dark color mode as dictated by the setting in our docs. Each example has an individual color mode picker. + +- Improved included JavaScript for live Toast demo. + +- Added `twbs/examples` repo contents to the top of the Examples page. + +### Tooling + +- Added SCSS testing via True to help test our utilities API and other customizations. + +- Replaced instances of our bootstrap-npm-starter project with the newer and more complete [twbs/examples repo](https://github.com/twbs/examples). + +
+ +For a complete list of changes, [see the v5.3.0-alpha2 project on GitHub](https://github.com/orgs/twbs/projects/13). + +## v5.3.0-alpha1 + +
+ +### Color modes! + +Learn more by reading the new [color modes documentation]({{< docsref "/customize/color-modes" >}}). + +- **Global support for light (default) and dark color modes.** Set color mode globally on the `:root` element, on groups of elements and components with a wrapper class, or directly on components, with `data-bs-theme="light|dark"`. Also included is a new `color-mode()` mixin that can output a ruleset with the `data-bs-theme` selector or a media query, depending on your preference. + + Deprecated Color modes replace dark variants for components, so `.btn-close-white`, `.carousel-dark`, `.dropdown-menu-dark`, and `.navbar-dark` are deprecated. + +- **New extended color system.** We've added new theme colors (but not in `$theme-colors`) for a more nuanced, system-wide color palette with new secondary, tertiary, and emphasis colors for `color` and `background-color`. These new colors are available as Sass variables, CSS variables, and utilities. + +- We've also expanded our theme color Sass variables, CSS variables, and utilities to include text emphasis, subtle background colors, and subtle border colors. These are available as Sass variables, CSS variables, and utilities. + +- Adds new `_variables-dark.scss` stylesheet to house dark-mode specific overrides. This stylesheet should be imported immediately after the existing `_variables.scss` file in your import stack. + + ```diff + diff --git a/scss/bootstrap.scss b/scss/bootstrap.scss + index 8f8296def..449d70487 100644 + --- a/scss/bootstrap.scss + +++ b/scss/bootstrap.scss + @@ -6,6 +6,7 @@ + // Configuration + @import "functions"; + @import "variables"; + +@import "variables-dark"; + @import "maps"; + @import "mixins"; + @import "utilities"; + ``` + +### CSS variables + +- Restores CSS variables for breakpoints, though we don't use them in our media queries as they're not supported. However, these can be useful in JS-specific contexts. + +- Per the color modes update, we've added new utilities for new Sass CSS variables `secondary` and `tertiary` text and background colors, plus `{color}-bg-subtle`, `{color}-border-subtle`, and `{color}-text-emphasis` for our theme colors. These new colors are available through Sass and CSS variables (but not our color maps) with the express goal of making it easier to customize across multiple colors modes like light and dark. + +- Adds additional variables for alerts, `.btn-close`, and `.offcanvas`. + +- The `--bs-heading-color` variable is back with an update and dark mode support. First, we now check for a `null` value on the associated Sass variable, `$headings-color`, before trying to output the CSS variable, so by default it's not present in our compiled CSS. Second, we use the CSS variable with a fallback value, `inherit`, allowing the original behavior to persist, but also allowing for overrides. + +- Converts links to use CSS variables for styling `color`, but not `text-decoration`. Colors are now set with `--bs-link-color-rgb` and `--bs-link-opacity` as `rgba()` color, allowing you to customize the translucency with ease. The `a:hover` pseudo-class now overrides `--bs-link-color-rgb` instead of explicitly setting the `color` property. + +- `--bs-border-width` is now being used in more components for greater control over default global styling. + +- Adds new root CSS variables for our `box-shadow`s, including `--bs-box-shadow`, `--bs-box-shadow-sm`, `--bs-box-shadow-lg`, and `--bs-box-shadow-inset`. + +### Components + +#### Alert + +- Alert variants are now styled via CSS variables. + +- Deprecated The `.alert-variant()` mixin is now deprecated. We now [use a Sass loop]({{< docsref "/components/alerts#sass-loops" >}}) directly to modify the component's default CSS variables for each variant. + +#### List group + +- List group item variants are now styled via CSS variables. + +- Deprecated The `.list-group-variant()` mixin is now deprecated. We now [use a Sass loop]({{< docsref "/components/list-group#sass-loops" >}}) directly to modify the component's default CSS variables for each variant. + +#### Dropdowns + +- Deprecated The `.dropdown-menu-dark` class has been deprecated and replaced with `data-bs-theme="dark"` on the dropdown or any parent element. [See the docs for an example.]({{< docsref "/components/dropdowns#dark-dropdowns" >}}) + +#### Close button + +- Deprecated The `.btn-close-white` class has been deprecated and replaced with `data-bs-theme="dark"` on the close button or any parent element. [See the docs for an example.]({{< docsref "/components/close-button#dark-variant" >}}) + +#### Navbar + +- Deprecated The `.navbar-dark` class has been deprecated and replaced with `data-bs-theme="dark"` on the navbar or any parent element. [See the docs for updated examples.]({{< docsref "/components/navbar#color-schemes" >}}) + +### Progress bars + +The markup for [progress bars]({{< docsref "/components/progress" >}}) has been updated in v5.3.0. Due to the placement of `role` and various `aria-` attributes on the inner `.progress-bar` element, **some screen readers were not announcing zero value progress bars**. Now, `role="progressbar"` and the relevant `aria-*` attributes are on the outer `.progress` element, leaving the `.progress-bar` purely for the visual presentation of the bar and optional label. + +While we recommend adopting the new markup for improved compatibility with all screen readers, note that the legacy progress bar structure will continue to work as before. + +```html + +
+
+
+ + +
+
+
+``` + +We've also introduced a new `.progress-stacked` class to more logically wrap [multiple progress bars]({{< docsref "/components/progress#multiple-bars" >}}) into a single stacked progress bar. + +```html + +
+
+
+
+
+ + +
+
+
+
+
+
+
+
+
+
+
+``` + +### Forms + +- `.form-control` is now styled with CSS variables to support color modes. This includes the addition of two new root CSS variables for the default and disabled form control backgrounds. + +- `.form-check` and `.form-switch` components are now built with CSS variables for setting the `background-image`. The usage here differs from other components in that the various focus, active, etc states for each component aren't set on the base class. Instead, the states override one variable (e.g., `--bs-form-switch-bg`). + +- Floating form labels now have a `background-color` to fix support for `