diff options
Diffstat (limited to '')
| -rw-r--r-- | site/content/docs/5.3/migration.md (renamed from site/content/docs/5.2/migration.md) | 239 |
1 files changed, 236 insertions, 3 deletions
diff --git a/site/content/docs/5.2/migration.md b/site/content/docs/5.3/migration.md index dbeb8f6..99575b5 100644 --- a/site/content/docs/5.2/migration.md +++ b/site/content/docs/5.3/migration.md @@ -7,6 +7,239 @@ 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. + +- <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> 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). + +<hr class="mb-4"> + +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 + +<hr class="mb-4"> + +### 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. + + <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> 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. + +- <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> 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. + +- <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> 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 + +- <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> 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 + +- <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> 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 + +- <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> 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 +<!-- Previous markup --> +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Basic example" style="width: 25%" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"></div> +</div> + +<!-- New markup --> +<div class="progress" role="progressbar" aria-label="Basic example" aria-valuenow="25" aria-valuemin="0" aria-valuemax="100"> + <div class="progress-bar" style="width: 25%"></div> +</div> +``` + +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 +<!-- Previous markup --> +<div class="progress"> + <div class="progress-bar" role="progressbar" aria-label="Segment one" style="width: 15%" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100"></div> + <div class="progress-bar bg-success" role="progressbar" aria-label="Segment two" style="width: 30%" aria-valuenow="30" aria-valuemin="0" aria-valuemax="100"></div> + <div class="progress-bar bg-info" role="progressbar" aria-label="Segment three" style="width: 20%" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100"></div> +</div> + +<!-- New markup --> +<div class="progress-stacked"> + <div class="progress" role="progressbar" aria-label="Segment one" aria-valuenow="15" aria-valuemin="0" aria-valuemax="100" style="width: 15%"> + <div class="progress-bar"></div> + </div> + <div class="progress" role="progressbar" aria-label="Segment two" aria-valuenow="30" aria-valuemin="0" aria-valuemax="100" style="width: 30%"> + <div class="progress-bar bg-success"></div> + </div> + <div class="progress" role="progressbar" aria-label="Segment three" aria-valuenow="20" aria-valuemin="0" aria-valuemax="100" style="width: 20%"> + <div class="progress-bar bg-info"></div> + </div> +</div> +``` + +### 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 `<textarea>` elements. Additional changes have been made to also support disabled states and more. + +- Fixed display of date and time inputs in WebKit based browsers. + +### Utilities + +- <span class="badge text-warning-emphasis bg-warning-subtle">Deprecated</span> `.text-muted` will be replaced by `.text-body-secondary` in v6. + + With the addition of the expanded theme colors and variables, the `.text-muted` variables and utility have been deprecated with v5.3.0. Its default value has also been reassigned to the new `--bs-secondary-color` CSS variable to better support color modes. It will be removed in v6.0.0. + +- Adds new `.overflow-x`, `.overflow-y`, and several `.object-fit-*` utilities. _The object-fit property is used to specify how an `<img>` or `<video>` should be resized to fit its container, giving us a responsive alternative to using `background-image` for a resizable fill/fit image._ + +- Adds new `.fw-medium` utility. + +- Added new [`.z-*` utilities]({{< docsref "/utilities/z-index" >}}) for `z-index`. + +- [Box shadow utilities]({{< docsref "/utilities/shadows" >}}) (and Sass variables) have been updated for dark mode. They now use `--bs-body-color-rgb` to generate the `rgba()` color values, allowing them to easily adapt to color modes based on the specified foreground color. + +For a complete list of changes, [see the v5.3.0 project on GitHub](https://github.com/twbs/bootstrap/projects/). + ## v5.2.0 <hr class="mb-4"> @@ -150,7 +383,7 @@ Want more information? [Read the v5.1.0 blog post.](https://blog.getbootstrap.co - Renamed "Navs" component page to "Navs & Tabs". - Renamed "Checks" page to "Checks & radios". - Redesigned the navbar and added a new subnav to make it easier to get around our sites and docs versions. -- Added new keyboard shortcut for the search field: <kbd>Ctrl + /</kbd>. +- Added new keyboard shortcut for the search field: <kbd><kbd>Ctrl</kbd> + <kbd>/</kbd></kbd>. ## Sass @@ -437,7 +670,7 @@ Want more information? [Read the v5.1.0 blog post.](https://blog.getbootstrap.co - Renamed `.rounded-left` and `.rounded-right` to `.rounded-start` and `.rounded-end`. - Renamed `.ml-*` and `.mr-*` to `.ms-*` and `.me-*`. - Renamed `.pl-*` and `.pr-*` to `.ps-*` and `.pe-*`. - - Renamed `.text-left` and `.text-right` to `.text-start` and `.text-end`. + - Renamed `.text-*-left` and `.text-*-right` to `.text-*-start` and `.text-*-end`. - <span class="badge bg-danger">Breaking</span> Disabled negative margins by default. @@ -457,7 +690,7 @@ Want more information? [Read the v5.1.0 blog post.](https://blog.getbootstrap.co - <span class="badge bg-danger">Breaking</span> Renamed `.font-weight-*` utilities as `.fw-*` for brevity and consistency. -- <span class="badge bg-danger">Breaking</span> Renamed `.font-style-*` utilities as `.fst-*` for brevity and consistency. +- <span class="badge bg-danger">Breaking</span> Renamed `.font-italic` utility to `.fst-italic` for brevity and consistency with new `.fst-normal` utility. - Added `.d-grid` to display utilities and new `gap` utilities (`.gap`) for CSS Grid and flexbox layouts. |