diff --git a/site/content/docs/5.0/components/badge.md b/site/content/docs/5.0/components/badge.md
index 50571d8856..de80d3b27a 100644
--- a/site/content/docs/5.0/components/badge.md
+++ b/site/content/docs/5.0/components/badge.md
@@ -6,10 +6,12 @@ group: components
toc: true
---
-## Example
+## Examples
Badges scale to match the size of the immediate parent element by using relative font sizing and `em` units. As of v5, badges no longer have focus or hover styles for links.
+### Headings
+
{{< example >}}
Example heading New
Example heading New
@@ -19,6 +21,8 @@ Badges scale to match the size of the immediate parent element by using relative
Example heading New
{{< /example >}}
+### Buttons
+
Badges can be used as part of links or buttons to provide a counter.
{{< example >}}
@@ -31,10 +35,28 @@ Note that depending on how they are used, badges may be confusing for users of s
Unless the context is clear (as with the "Notifications" example, where it is understood that the "4" is the number of notifications), consider including additional context with a visually hidden piece of additional text.
+### Positioned
+
+Use utilities to modify a `.badge` and position it in the corner of a link or button.
+
{{< example >}}
-