From: Christian Oliff <christian_oliff@trimble.com>
Date: Wed, 3 Jun 2026 21:14:37 +0000 (+0900)
Subject: docs: fix wording and responsive utility examples (#42458)
X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=ac4cf140dec1a048413fc008481e2a63b6ca3599;p=thirdparty%2Fbootstrap.git

docs: fix wording and responsive utility examples (#42458)

Copy edits across several docs pages: clarify .btn usage and theme classes (button.mdx); correct repeated/awkward 'drawer' phrasing and update responsive breakpoint syntax to the colon form (drawer.mdx); remove duplicated 'drawer' wording and clean navbar responsive copy (navbar.mdx); update Sass guidance from @import to @use/@forward terminology (customize/optimize.mdx); clarify 'modal' → 'modal dialog' and update form validation guidance to use data-bs-validate and :user-invalid (getting-started/approach.mdx); and revise display utility docs to show the new .{breakpoint}:d-{value} syntax with example adjustments (utilities/display.mdx).
---

diff --git a/site/src/content/docs/components/button.mdx b/site/src/content/docs/components/button.mdx
index c32e0c020c..795f5b64ef 100644
--- a/site/src/content/docs/components/button.mdx
+++ b/site/src/content/docs/components/button.mdx
@@ -15,7 +15,7 @@ Buttons have a standard `.btn` class that sets up basic styles such as padding a
 
 <Example code={`<button type="button" class="btn">Base class</button>`} />
 
-The `.btn` class is intended to be a starting point for your own custom button styles, while our provided button variants  used in conjunction with our button variants, or to serve as a basis for your own custom styles.
+The `.btn` class is intended to be a starting point for your own custom button styles, while our provided button variants can be used alongside `.theme-*` classes or as a basis for your own custom styles.
 
 ## Playground
 
diff --git a/site/src/content/docs/components/drawer.mdx b/site/src/content/docs/components/drawer.mdx
index 2671626803..af74c0ecb5 100644
--- a/site/src/content/docs/components/drawer.mdx
+++ b/site/src/content/docs/components/drawer.mdx
@@ -17,7 +17,7 @@ Drawer builds on the native `<dialog>` element and our Dialog component to manag
 - **Built-in backdrop** via `::backdrop` (modal only) closes the drawer on click; set `backdrop: "static"` to lock clicks outside, or `backdrop: false` to hide it.
 - **Escape key handling** closes the drawer by default; set `keyboard: false` to disable.
 - **Swipe to dismiss** — drawer auto-wires a placement-aware swipe (swipe left to close `drawer-start` in LTR, swipe down to close `drawer-bottom`, etc.).
-- **Responsive placement** — `.sm-drawer`, `.md-drawer`, and up stay drawer-like below their breakpoint and collapse inline above it, making drawers useful as responsive navbars.
+- **Responsive placement** — `.sm:drawer`, `.md:drawer`, and up stay drawer-like below their breakpoint and collapse inline above it, making drawers useful as responsive navbars.
 - **Only one drawer can be shown at a time** (enforced by the data API).
 - **Animated open and close** — drawer slides back out to its placement-specific off-screen position on close, with the `::backdrop` fading alongside it when opened modally. When authoring custom CSS, qualify your `[open]` rules with `:not(.hiding)` so the exit transition can fall through to the base state; add `.drawer-instant` to skip animations.
 
@@ -27,7 +27,7 @@ Drawer builds on the native `<dialog>` element and our Dialog component to manag
 
 ### Drawer components
 
-Below is an drawer example that is shown by default (via `open` and `.show` on the `<dialog>`). Drawer includes support for a header with a close button and an optional body class for some initial `padding`. We suggest that you include drawer headers with dismiss actions whenever possible, or provide an explicit dismiss action.
+Below is a drawer example that is shown by default (via `open` and `.show` on the `<dialog>`). Drawer includes support for a header with a close button and an optional body class for some initial `padding`. We suggest that you include drawer headers with dismiss actions whenever possible, or provide an explicit dismiss action.
 
 <Example class="bd-example-drawer p-0 bg-1 overflow-hidden" code={`<dialog class="drawer drawer-start show" open tabindex="-1" id="drawer" aria-labelledby="drawerLabel">
     <div class="drawer-header">
@@ -41,7 +41,7 @@ Below is an drawer example that is shown by default (via `open` and `.show` on t
 
 ### Live demo
 
-Use the buttons below to show and hide an drawer element via JavaScript. You can use a link with the `href` attribute, or a button with the `data-bs-target` attribute. In both cases, the `data-bs-toggle="drawer"` is required.
+Use the buttons below to show and hide a drawer element via JavaScript. You can use a link with the `href` attribute, or a button with the `data-bs-target` attribute. In both cases, the `data-bs-toggle="drawer"` is required.
 
 <Example code={`<a class="btn-solid theme-primary" data-bs-toggle="drawer" href="#drawerExample" role="button" aria-controls="drawerExample">
     Link with href
@@ -74,7 +74,7 @@ Use the buttons below to show and hide an drawer element via JavaScript. You can
 
 ### Body scrolling
 
-Scrolling the `<body>` element is disabled when an drawer and its backdrop are visible. Use the `data-bs-scroll` attribute to enable `<body>` scrolling.
+Scrolling the `<body>` element is disabled when a drawer and its backdrop are visible. Use the `data-bs-scroll` attribute to enable `<body>` scrolling.
 
 <Example code={`<button class="btn-solid theme-primary" type="button" data-bs-toggle="drawer" data-bs-target="#drawerScrolling" aria-controls="drawerScrolling">Enable body scrolling</button>
 
@@ -176,7 +176,7 @@ Add `.drawer-translucent` to the drawer panel to blur and saturate the backgroun
 
 ## Responsive
 
-Responsive drawer classes hide content outside the viewport from a specified breakpoint and down. Above that breakpoint, the contents within will behave as usual. For example, `.lg:drawer` hides content in an drawer below the `lg` breakpoint, but shows the content above the `lg` breakpoint. Responsive drawer classes are available for each breakpoint.
+Responsive drawer classes hide content outside the viewport from a specified breakpoint and down. Above that breakpoint, the contents within will behave as usual. For example, `.lg:drawer` hides content in a drawer below the `lg` breakpoint, but shows the content above the `lg` breakpoint. Responsive drawer classes are available for each breakpoint.
 
 - `.drawer`
 - `.sm:drawer`
@@ -326,7 +326,7 @@ Add `data-bs-toggle="drawer"` and a `data-bs-target` or `href` to the element to
 <JsDismiss name="drawer" />
 
 <Callout type="warning">
-While both ways to dismiss an drawer are supported, keep in mind that dismissing from outside an drawer does not match the [ARIA Authoring Practices Guide dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/). Do this at your own risk.
+While both ways to dismiss a drawer are supported, keep in mind that dismissing from outside a drawer does not match the [ARIA Authoring Practices Guide dialog (modal) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/). Do this at your own risk.
 </Callout>
 
 ### Via JavaScript
@@ -354,9 +354,9 @@ const drawerList = [...drawerElementList].map(drawerEl => new bootstrap.Drawer(d
 
 <Callout name="danger-async-methods" type="danger" />
 
-Activates your content as an drawer element. Accepts an optional options `object`.
+Activates your content as a drawer element. Accepts an optional options `object`.
 
-You can create an drawer instance with the constructor, for example:
+You can create a drawer instance with the constructor, for example:
 
 ```js
 const bsDrawer = new bootstrap.Drawer('#myDrawer')
@@ -368,9 +368,9 @@ const bsDrawer = new bootstrap.Drawer('#myDrawer')
 | `dispose` | Destroys an element’s drawer. |
 | `getInstance` | *Static* method which allows you to get the drawer instance associated with a DOM element. |
 | `getOrCreateInstance` | *Static* method which allows you to get the drawer instance associated with a DOM element, or create a new one in case it wasn’t initialized. |
-| `hide` | Hides an drawer element. **Returns to the caller before the drawer element has actually been hidden** (i.e. before the `hidden.bs.drawer` event occurs). |
-| `show` | Shows an drawer element. **Returns to the caller before the drawer element has actually been shown** (i.e. before the `shown.bs.drawer` event occurs). |
-| `toggle` | Toggles an drawer element to shown or hidden. **Returns to the caller before the drawer element has actually been shown or hidden** (i.e. before the `shown.bs.drawer` or `hidden.bs.drawer` event occurs). |
+| `hide` | Hides a drawer element. **Returns to the caller before the drawer element has actually been hidden** (i.e. before the `hidden.bs.drawer` event occurs). |
+| `show` | Shows a drawer element. **Returns to the caller before the drawer element has actually been shown** (i.e. before the `shown.bs.drawer` event occurs). |
+| `toggle` | Toggles a drawer element to shown or hidden. **Returns to the caller before the drawer element has actually been shown or hidden** (i.e. before the `shown.bs.drawer` or `hidden.bs.drawer` event occurs). |
 </BsTable>
 
 ### Events
@@ -381,10 +381,10 @@ Bootstrap’s drawer class exposes a few events for hooking into drawer function
 | Event type | Description |
 | --- | --- |
 | `hide.bs.drawer` | This event is fired immediately when the `hide` method has been called. |
-| `hidden.bs.drawer` | This event is fired when an drawer element has been hidden from the user (will wait for CSS transitions to complete). |
+| `hidden.bs.drawer` | This event is fired when a drawer element has been hidden from the user (will wait for CSS transitions to complete). |
 | `hidePrevented.bs.drawer` | This event is fired when the drawer is shown, its backdrop is `static` and a click outside of the drawer is performed. The event is also fired when the escape key is pressed and the `keyboard` option is set to `false`. |
 | `show.bs.drawer` | This event fires immediately when the `show` instance method is called. |
-| `shown.bs.drawer` | This event is fired when an drawer element has been made visible to the user (will wait for CSS transitions to complete). |
+| `shown.bs.drawer` | This event is fired when a drawer element has been made visible to the user (will wait for CSS transitions to complete). |
 </BsTable>
 
 ```js
diff --git a/site/src/content/docs/components/navbar.mdx b/site/src/content/docs/components/navbar.mdx
index 50bf3b858a..1e8d6a7558 100644
--- a/site/src/content/docs/components/navbar.mdx
+++ b/site/src/content/docs/components/navbar.mdx
@@ -555,11 +555,11 @@ Fixed navbars use `position: fixed`, meaning they’re pulled from the normal fl
 
 ## Responsive behaviors
 
-Navbars can use `.navbar-toggler`, and `.lg:navbar-expand{-sm|-md|-lg|-xl|-2xl}` classes to determine when their content appears in an drawer drawer or inline. In combination with other utilities, you can easily choose when to show or hide particular elements.
+Navbars can use `.navbar-toggler`, and `.lg:navbar-expand{-sm|-md|-lg|-xl|-2xl}` classes to determine when their content appears in a drawer or inline. In combination with other utilities, you can easily choose when to show or hide particular elements.
 
-For navbars that never collapse, add the `.lg:navbar-expand` class on the navbar. For navbars that always show the drawer drawer, don’t add any `.lg:navbar-expand` class.
+For navbars that never collapse, add the `.lg:navbar-expand` class on the navbar. For navbars that always show the drawer, don’t add any `.lg:navbar-expand` class.
 
-### Drawer drawer
+### Drawer
 
 By default, navbars use the [drawer component]([[docsref:/components/drawer]]) for their responsive behavior. This provides a modern drawer-style menu that slides in from any side of the screen.
 
@@ -622,7 +622,7 @@ These examples omit the `.lg:navbar-expand` class to always show the drawer beha
 
 Navbar togglers are left-aligned by default, but should they follow a sibling element like a `.navbar-brand`, they’ll automatically be aligned to the far right. Reversing your markup will reverse the placement of the toggler.
 
-These examples omit the `.lg:navbar-expand` class to always show the collapsed state with the toggler visible. Click the toggler to open the drawer drawer.
+These examples omit the `.lg:navbar-expand` class to always show the collapsed state with the toggler visible. Click the toggler to open the drawer.
 
 With no `.navbar-brand` shown (hidden inside the drawer):
 
diff --git a/site/src/content/docs/customize/optimize.mdx b/site/src/content/docs/customize/optimize.mdx
index b6118aa094..00042f5ffd 100644
--- a/site/src/content/docs/customize/optimize.mdx
+++ b/site/src/content/docs/customize/optimize.mdx
@@ -4,13 +4,13 @@ description: Keep your projects lean, responsive, and maintainable so you can de
 toc: true
 ---
 
-## Lean Sass imports
+## Lean Sass setup
 
-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`.
+When using Sass in your asset pipeline, make sure you optimize Bootstrap by only `@use`ing the partials you need. Your largest optimizations will likely come from the `Layout & Components` section of our `bootstrap.scss`.
 
 <ScssDocs 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.
+If you’re not using a component, comment it out or delete its `@forward` entry entirely. For example, if you’re not using the carousel, remove that line to save file size in your compiled CSS. Keep in mind there are some dependencies across Sass partials that may make it more difficult to omit a file.
 
 ## Lean JavaScript
 
diff --git a/site/src/content/docs/getting-started/approach.mdx b/site/src/content/docs/getting-started/approach.mdx
index 7508f513eb..656d6c8ce5 100644
--- a/site/src/content/docs/getting-started/approach.mdx
+++ b/site/src/content/docs/getting-started/approach.mdx
@@ -218,7 +218,7 @@ Components built with overlays also have a predefined z-index scale, beginning a
 
 <ScssDocs name="zindex-levels-map" file="scss/_config.scss" />
 
-Each overlay component increases its `z-index` value slightly in such a way that common UI principles allow user focused or hovered elements to remain in view at all times. For example, a modal is document blocking (e.g., you cannot take any other action save for the modal’s action), so we put that above our navbars.
+Each overlay component increases its `z-index` value slightly in such a way that common UI principles allow user focused or hovered elements to remain in view at all times. For example, a modal dialog is document blocking (e.g., you cannot take any other action save for the dialog’s action), so we put that above our navbars.
 
 Learn more about this in our [`z-index` layout page]([[docsref:/layout/z-index]]).
 
@@ -226,7 +226,7 @@ Learn more about this in our [`z-index` layout page]([[docsref:/layout/z-index]]
 
 Whenever possible, we prefer HTML and CSS over JavaScript—they’re more accessible to people of all experience levels and faster in the browser. That’s why our first-class JavaScript API is `data` attributes—it lets you write more HTML instead of JavaScript. Read more in [our JavaScript overview]([[docsref:/getting-started/javascript#data-attributes]]).
 
-Our styles build on fundamental browser behaviors. For example, while you can put `.btn` on nearly any element, we prefer `<button>`s and `<a>`s for their semantic value. Similarly, we use native `:valid`/`:invalid` pseudo-elements for form validation rather than custom plugins.
+Our styles build on fundamental browser behaviors. For example, while you can put `.btn` on nearly any element, we prefer `<button>`s and `<a>`s for their semantic value. For form validation, we scope styles behind `data-bs-validate` and use the `:user-invalid` pseudo-class so feedback appears only after user interaction—not on initial page load.
 
 ### Utilities
 
diff --git a/site/src/content/docs/utilities/display.mdx b/site/src/content/docs/utilities/display.mdx
index 932448f234..3b3dafc00a 100644
--- a/site/src/content/docs/utilities/display.mdx
+++ b/site/src/content/docs/utilities/display.mdx
@@ -17,7 +17,7 @@ Display utility classes that apply to all [breakpoints]([[docsref:/layout/breakp
 As such, the classes are named using the format:
 
 - `.d-{value}` for `xs`
-- `.d-{breakpoint}-{value}` for `sm`, `md`, `lg`, `xl`, and `2xl`.
+- `.{breakpoint}:d-{value}` for `sm`, `md`, `lg`, `xl`, and `2xl` (for example, `.md:d-none`).
 
 Where *value* is one of:
 
@@ -57,9 +57,9 @@ There’s no more clearfix helper in Bootstrap 6 as it’s an outdated technique
 
 For faster mobile-friendly development, use responsive display classes for showing and hiding elements by device. Avoid creating entirely different versions of the same site, instead hide elements responsively for each screen size.
 
-To hide elements simply use the `.d-none` class or one of the `.d-{sm,md,lg,xl,2xl}-none` classes for any responsive screen variation.
+To hide elements simply use the `.d-none` class or one of the `.{sm,md,lg,xl,2xl}:d-none` classes for any responsive screen variation.
 
-To show an element only on a given interval of screen sizes you can combine one `.d-*-none` class with a `.d-*-*` class, for example `.d-none .md:d-block .xl:d-none` will hide the element for all screen sizes except on medium and large devices.
+To show an element only on a given interval of screen sizes you can combine one `.{breakpoint}:d-none` class with a `.{breakpoint}:d-block` class, for example `.d-none .md:d-block .xl:d-none` will hide the element for all screen sizes except on medium and large devices.
 
 <BsTable>
 | Screen size | Class |