docs(packages[badges]): Size variants demo and CSS class reference

why: Document the new xs/sm/lg/xl size API alongside existing badge demos.
what:
- sab_demo.py: size variants row (xs through xl side-by-side)
- sphinx-autodoc-badges.md: badge_size param, sab-xs–sab-xl in CSS table,
  note that explicit sizes override context selectors

Author: tony

docs/_ext/sab_demo.py

@@ -37,6 +37,18 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
                 p += nodes.literal(text=label)
             return p
 
+        result.append(_section("Size variants (xs / sm / default / lg / xl)"))
+        result.append(
+            _row(
+                build_badge("xs", size="xs", tooltip="Extra small"),
+                build_badge("sm", size="sm", tooltip="Small"),
+                build_badge("md", tooltip="Default (no size class)"),
+                build_badge("lg", size="lg", tooltip="Large"),
+                build_badge("xl", size="xl", tooltip="Extra large"),
+                label='build_badge("lg", size="lg")',
+            )
+        )
+
         result.append(_section("Filled (default)"))
         result.append(
             _row(
@@ -102,9 +114,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
                 build_badge("gamma", tooltip="Third"),
             ]
         )
-        result.append(
-            _row(group, label="build_badge_group([...badges...])")
-        )
+        result.append(_row(group, label="build_badge_group([...badges...])"))
 
         result.append(_section("Toolbar (push-right in flex heading)"))
         tb = build_toolbar(
@@ -125,9 +135,7 @@ def _row(*badge_nodes: nodes.Node, label: str = "") -> nodes.paragraph:
         heading_p += tb
         heading_container += heading_p
         result.append(heading_container)
-        result.append(
-            _row(label="build_toolbar(build_badge_group([...]))")
-        )
+        result.append(_row(label="build_toolbar(build_badge_group([...]))"))
 
         return result
 

docs/packages/sphinx-autodoc-badges.md

@@ -76,6 +76,9 @@ Every variant rendered by the real `build_badge` / `build_badge_group` /
       * - ``badge_style``
         - ``"full"``
         - Structural variant: ``"full"``, ``"icon-only"``, ``"inline-icon"``.
+      * - ``badge_size``
+        - ``""``
+        - Optional size: ``"xs"``, ``"sm"``, ``"lg"``, or ``"xl"``. Empty means default.
       * - ``tabindex``
         - ``"0"``
         - ``"0"`` for keyboard-focusable, ``""`` to skip.
@@ -182,12 +185,25 @@ All classes use the `sab-` prefix (**s**phinx **a**utodoc **b**adges).
 * - `sab-toolbar`
   - `build_toolbar()`
   - Flex push-right (`margin-left: auto`) for title rows.
+* - `sab-xs`
+  - `build_badge(size="xs")` / `BadgeNode(..., badge_size="xs")`
+  - Extra small (dense tables, tight UI).
+* - `sab-sm`
+  - `build_badge(size="sm")`
+  - Small inline badges.
+* - `sab-lg`
+  - `build_badge(size="lg")`
+  - Large (section titles, callouts).
+* - `sab-xl`
+  - `build_badge(size="xl")`
+  - Extra large (hero / landing emphasis).
 ```
 
 ## Context-aware sizing
 
 Badge size adapts automatically based on where it appears in the document.
-No extra classes needed — CSS selectors handle it.
+CSS selectors handle it. Explicit size classes (`sab-xs` … `sab-xl`) override
+contextual sizing when present (higher specificity than context rules).
 
 ```{list-table}
 :header-rows: 1