Docs: add explanation of the base `.btn` class (#37275)

* Docs: add explanation of the base `.btn` class

and a callout reminding authors to at least define some focus styling if they intend to use it "naked"

* Turn callout into a warning

* Add initial heading

* Tweak callout wording

diff --git a/site/content/docs/5.3/components/buttons.md b/site/content/docs/5.3/components/buttons.md
index 396beec7f39b95e0940cce1333071780c210dd00..8d9ff0201c93b3b94cb9838a8c0e11ca171158aa 100644 (file)
--- a/site/content/docs/5.3/components/buttons.md
+++ b/site/content/docs/5.3/components/buttons.md
@@ -6,7 +6,21 @@ group: components
 toc: true
 ---
 
-## Examples
+## Base class
+
+Bootstrap has a base `.btn` class that sets up basic styles such as padding and content alignment. By default, `.btn` controls have a transparent border and background color, and lack any explicit focus and hover styles.
+
+{{< example >}}
+<button type="button" class="btn">Base class</button>
+{{< /example >}}
+
+The `.btn` class is intended to be used in conjunction with our additional predefined button styles, or to serve as a basis for your own custom styles.
+
+{{< callout warning >}}
+If you are using the `.btn` class on its own, remember to at least define some explicit `:focus` and/or `:focus-visible` styles.
+{{< /callout >}}
+
+## Predefined styles
 
 Bootstrap includes several predefined button styles, each serving its own semantic purpose, with a few extras thrown in for more control.