Move the browserslist commentary into the docs

The rationale had grown to roughly 50 comment lines, and the approach page
embeds this file in full, so all of it rendered there ahead of the queries
it was meant to explain. Prose belongs on a page that can format it.

Move the parts the docs did not already cover onto the browsers and devices
page: why `last 2 major versions` carries our mobile coverage, why
`unreleased versions` is worth eight points, how to measure coverage and why
not to trust browserslist.dev, which features the floors do and do not give
us, and which prefixes the excluded engines would add. Leave behind a
pointer to that page and the two rules a person editing the file must not
get wrong.

Both pages now read the query lines out of the file through `fileMatch`
instead of hand-copying them. That is what drifted in the first place: the
page still claimed Chrome 130 and Safari 18 after the floors briefly moved
to 123 and 17.5. The regex is anchored on the first and last query, so a
restructure fails the docs build rather than shipping stale versions.

The resolved target list, the derived oxc targets, and the build output are
all unchanged.

Author: mdo

.browserslistrc

@@ -1,75 +1,28 @@
 # https://github.com/browserslist/browserslist#readme
 #
-# Browserslist joins every line below with OR, not AND. The `>=` lines do not
-# restrict `last 2 major versions`; they add older versions of each engine on
-# top of it. `last 2 major versions` is the line that carries mobile coverage,
-# because caniuse tracks Chrome for Android as one unversioned entry.
+# Read the docs before you change anything here. The support policy, the reason
+# behind each floor, the features these floors do and do not give us, and how to
+# measure coverage all live in one place:
+# https://getbootstrap.com/docs/6.0/getting-started/browsers-devices/
 #
-# Run `npx browserslist --coverage` for the real coverage figure. It reports
-# about 85% today. Do not read the number off browserslist.dev, because that
-# site pins an old caniuse-db and reports a different result.
+# Two rules for editing this file:
+#   1. Never set a floor below `light-dark()`: Chrome 123, Firefox 120,
+#      Safari 17.5. Lightning CSS lowers `light-dark()` to a custom-property
+#      polyfill below those versions, and the polyfill breaks `data-bs-theme`.
+#   2. Run `npx browserslist --coverage` after any change, then update the
+#      versions and the coverage figure on the docs page above.
 
 last 2 major versions
 not dead
-
-# caniuse gives the newest Safari a null release date, but that version already
-# holds most of Safari's usage share. Both range queries and `last N versions`
-# skip unreleased versions, so this line is worth about 8 points of coverage.
-# It costs nothing, because the version is newer than every floor below.
 unreleased versions
 
-# These floors are the platform baseline for the whole v6.x line. We cannot raise
-# them in a minor release, so they cap what every future 6.x feature may use.
-# Each floor sits on the newest feature we already depend on, not the oldest one
-# we could tolerate:
-#   - `:has()` needs Firefox 121. We use it in forms, button groups and cards.
-#   - `content-visibility` needs Firefox 125 and Safari 18. The accordion
-#     transitions it with `allow-discrete`.
-#   - `<details name>` needs Firefox 130. It drives exclusive accordions.
-#   - Unprefixed `backdrop-filter` needs Safari and iOS 18. Dialog and Drawer
-#     blur their `::backdrop`. Below 18, Autoprefixer adds `-webkit-` copies.
-#   - `text-wrap: balance` needs Chrome 130. We ship it as a utility.
-# `light-dark()` sets the hard lower bound (Chrome 123, Firefox 120, Safari 17.5).
-# Below it, Lightning CSS lowers `light-dark()` to a custom-property polyfill, and
-# that polyfill breaks `data-bs-theme` dark mode. Never go below that bound.
 Chrome >= 130
 Edge >= 130
 Firefox >= 132
 iOS >= 18.0
 Safari >= 18.0
 
-# What these floors buy us. Every item here is safe in any 6.x release with no
-# fallback, no prefix and no polyfill. Reach for these first:
-#   - Colors: `light-dark()`, `oklch()`, `color()` and `color-mix()`
-#   - Native CSS nesting, so compiled output can stay nested
-#   - `@layer`, which our layer order depends on
-#   - `:has()` and `:focus-visible` for contextual styling
-#   - Container queries, container query units and `subgrid`
-#   - `content-visibility`, `transition-behavior: allow-discrete` and
-#     `@starting-style`, which animate `<details>` and `<dialog>` open and closed
-#   - Native `<dialog>` with `::backdrop` and unprefixed `backdrop-filter`
-#   - `<details name>` for exclusive accordions
-#   - `text-wrap: balance`
-#   - Range syntax in media queries, such as `@media (width >= 1024px)`
-#
-# What these floors still do not buy. Do not use these in 6.x without a
-# fallback. Re-check with `npx browserslist` before you assume one has landed,
-# because Firefox is the blocker in almost every case:
-#   - Relative color syntax, `rgb(from ...)`: Chrome 131, Firefox 133. This sits
-#     one version above our Chrome floor, so revisit it first in v7.
-#   - View transitions: Firefox 144
-#   - `@scope`: Firefox 146
-#   - Anchor positioning: Firefox 147, Safari 26. This is the big one. It would
-#     let Menu, Tooltip, Popover and Combobox drop Floating UI.
-#   - Style container queries: Firefox 151
-#   - `text-box-trim`: Firefox 154
-#   - Scrollbar styling: Safari 26.2
-
-# Autoprefixer adds `-webkit-mask-*` for UC and QQ, and `-moz-column-gap` for
-# KaiOS. Those three engines hold under 0.8% of users between them, so we drop
-# them rather than ship the prefixes. KaiOS also broke floating labels
-# (see https://github.com/postcss/autoprefixer/issues/1533).
 not and_uc > 0
 not and_qq > 0
 not kaios > 0
-not op_mini all # proxy browser we don't target; only source of redundant -o-object-fit prefixes
+not op_mini all

site/src/content/docs/getting-started/approach.mdx

@@ -168,9 +168,9 @@ For improved cross-browser rendering, we use [Reboot]([[docsref:/content/reboot]
 
 ### Browser support
 
-You can find our supported range of browsers and their versions [in our `.browserslistrc` file]([[config:repo]]/blob/v[[config:current_version]]/.browserslistrc). The comments record why each floor sits where it does, and which platform features the floors do and do not give us. For a summary table instead, see [Browsers & devices]([[docsref:/getting-started/browsers-devices]]).
+You can find our supported range of browsers and their versions [in our `.browserslistrc` file]([[config:repo]]/blob/v[[config:current_version]]/.browserslistrc). See [Browsers & devices]([[docsref:/getting-started/browsers-devices]]) for the reason behind each version, and for the platform features these floors do and do not give us.
 
-<Code lang="plaintext" filePath=".browserslistrc" />
+<Code lang="plaintext" filePath=".browserslistrc" fileMatch="last 2 major versions[\s\S]+not op_mini all" />
 
 If you installed Bootstrap via npm, you can also find this file locally at `node_modules/bootstrap/.browserslistrc`.
 

site/src/content/docs/getting-started/browsers-devices.mdx

@@ -8,16 +8,7 @@ toc: true
 
 Bootstrap supports the **latest, stable releases** of all major browsers and platforms, plus a run of older versions of each engine. The exact policy lives in [our `.browserslistrc` file](https://github.com/twbs/bootstrap/blob/v6-dev/.browserslistrc):
 
-```text
-last 2 major versions
-not dead
-unreleased versions
-Chrome >= 130
-Edge >= 130
-Firefox >= 132
-iOS >= 18.0
-Safari >= 18.0
-```
+<Code lang="plaintext" filePath=".browserslistrc" fileMatch="last 2 major versions[\s\S]+not op_mini all" />
 
 Browserslist joins these lines with OR, not AND. The `>=` lines do not narrow `last 2 major versions`. They add every version above each floor, which is what sets our real minimums:
 
@@ -33,6 +24,15 @@ Browserslist joins these lines with OR, not AND. The `>=` lines do not narrow `l
 
 Alternative browsers built on these engines (Chromium-based browsers like Brave, Opera, or Vivaldi, and browsers using WebKit on iOS) are not explicitly tested, but should be fully supported at equivalent engine versions.
 
+### How to read the query list
+
+Two of those lines do more than they look like they do:
+
+- **`last 2 major versions` carries our mobile coverage.** caniuse tracks Chrome for Android as a single unversioned entry rather than one entry per release, so this line, not the `>=` floors, is what picks it up.
+- **`unreleased versions` is worth about eight points of coverage, and it costs nothing.** caniuse gives the newest Safari a null release date, yet that version already holds most of Safari’s usage share. Both range queries and `last N versions` skip unreleased versions, so without this line we would exclude the single most-used Safari. It cannot pull in anything old, because an unreleased version is newer than every floor.
+
+To measure coverage yourself, run `npx browserslist --coverage` in a clone of the repository. Do not read the figure off browserslist.dev: that site pins an older copy of caniuse-db and reports a materially different number.
+
 ### Why these versions?
 
 Bootstrap’s CSS is written against the modern platform baseline: [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark) for [color modes]([[docsref:/customize/color-modes]]), `oklch()` and `color-mix()` for the [color system]([[docsref:/customize/color]]), native CSS nesting, container queries, and `:has()`.
@@ -51,7 +51,7 @@ Our floors also have to last. They apply to the whole v6.x line, and we cannot r
 
 `light-dark()` sets the hard lower bound: Chrome 123, Firefox 120, and Safari 17.5. Below it, our build pipeline lowers `light-dark()` to a custom-property polyfill, and that polyfill breaks `data-bs-theme` dark mode. We will not go below that bound in any release.
 
-Together these targets cover about 85% of global browser usage. Run `npx browserslist --coverage` in a clone to check the current figure yourself.
+Together these targets cover about 85% of global browser usage.
 
 Unlike previous major versions, Bootstrap 6 does not ship fallbacks, prefixes, or polyfills for browsers below this floor. Pages will not render correctly in unsupported browsers—most visibly, colors depending on `light-dark()` will not resolve.
 
@@ -72,6 +72,37 @@ The table below lists the platform features v6 relies on and how each behaves at
 | Logical properties | Spacing, borders, and [RTL]([[docsref:/customize/rtl]]) support throughout | Fully supported above the floor |
 </BsTable>
 
+### Also safe to use
+
+The floors clear more of the platform than the components currently use. All of the following need no fallback, no vendor prefix, and no polyfill in any 6.x release, so reach for them first when you build on top of Bootstrap or contribute to it:
+
+- Native CSS nesting, so compiled output can stay nested
+- `@layer`, which our [layer order]([[docsref:/getting-started/approach]]) depends on
+- `:focus-visible` for keyboard-only focus styling
+- Container query units and `subgrid`
+- `content-visibility`, `transition-behavior: allow-discrete`, and `@starting-style`, which together animate `<details>` and `<dialog>` open and closed
+- Unprefixed `backdrop-filter`
+- `text-wrap: balance`
+- Range syntax in media queries, such as `@media (width >= 1024px)`
+
+### Not available yet
+
+These features sit above our floors, so v6 cannot use them without a fallback. Firefox is the blocker in nearly every case, which means Chrome support alone is never enough to tell you whether we can ship something.
+
+<BsTable>
+| Feature | First fully supported in |
+| --- | --- |
+| Relative color syntax, `rgb(from …)` | Chrome 131, Firefox 133 |
+| View transitions | Firefox 144 |
+| `@scope` | Firefox 146 |
+| Anchor positioning | Firefox 147, Safari 26 |
+| Style container queries | Firefox 151 |
+| `text-box-trim` | Firefox 154 |
+| Scrollbar styling | Safari 26.2 |
+</BsTable>
+
+Relative color syntax is the closest miss, one version above our Chrome floor. Anchor positioning is the one most worth waiting for: it would let Menu, Tooltip, Popover, and Combobox drop their [Floating UI](https://floating-ui.com/) dependency. Re-check these with `npx browserslist` before you assume one has landed.
+
 ## JavaScript
 
 Bootstrap’s JavaScript ships as **native ES modules only**. Load it with `<script type="module">`—a classic `<script src>` without `type="module"` will not execute it, and there is no global `window.bootstrap` object. See the [JavaScript getting-started guide]([[docsref:/getting-started/javascript]]) for loading patterns, including import maps for the bundle’s dependencies.
@@ -80,7 +111,7 @@ All browsers meeting the CSS support floor above fully support ES modules, `impo
 
 ## Mobile devices
 
-Generally speaking, Bootstrap supports the latest versions of each major platform’s default browsers. Note that proxy browsers (such as Opera Mini, Opera Mobile’s Turbo mode, UC Browser Mini, Amazon Silk) are not supported. We also exclude UC Browser, QQ Browser, and KaiOS. Together they hold under 1% of users, and targeting them only adds vendor prefixes to our CSS.
+Generally speaking, Bootstrap supports the latest versions of each major platform’s default browsers. Note that proxy browsers (such as Opera Mini, Opera Mobile’s Turbo mode, UC Browser Mini, Amazon Silk) are not supported. We also exclude UC Browser, QQ Browser, and KaiOS. Together they hold under 1% of users, and including them only adds vendor prefixes to our CSS: `-webkit-mask-*` for UC and QQ, and `-moz-column-gap` for KaiOS. KaiOS additionally [broke our floating labels](https://github.com/postcss/autoprefixer/issues/1533).
 
 <BsTable>
 | Platform | Supported browsers |