From 4e856ba0557428661d2e2184e8d0a1ff37cb601d Mon Sep 17 00:00:00 2001
From: Marco D'Auria <marco.dauria@siemens.com>
Date: Mon, 23 Feb 2026 12:19:56 +0100
Subject: [PATCH] docs(buttons): add selection buttons composition variants

---
 docs/components/buttons-menus/button-group.md | 37 ++++++++++++++++
 .../examples/buttons/selection-buttons.html   | 44 +++++--------------
 2 files changed, 48 insertions(+), 33 deletions(-)

diff --git a/docs/components/buttons-menus/button-group.md b/docs/components/buttons-menus/button-group.md
index 740bd7dcfa..f445f2baab 100644
--- a/docs/components/buttons-menus/button-group.md
+++ b/docs/components/buttons-menus/button-group.md
@@ -218,4 +218,41 @@ For selection-based button groups that represent different states or views, use
 </div>
 ```
 
+**Composition variants**
+
+There are two ways to compose a selection button:
+
+**Input wrapped inside label** — nest the input directly inside a `<label>` element, removing the need for `for`/`id`.
+This variant is required for icon-only buttons to support and display **tooltips** correctly:
+
+```html
+<div class="btn-group" role="group" aria-label="Layout selection">
+  <label>
+    <input type="checkbox" class="btn-check" aria-label="One pane" siTooltip="One pane" checked />
+    <si-icon class="btn btn-icon icon" icon="element-layout-pane-1" />
+  </label>
+
+  <label>
+    <input type="checkbox" class="btn-check" aria-label="Two panes" siTooltip="Two panes" />
+    <si-icon class="btn btn-icon icon" icon="element-layout-pane-2" />
+  </label>
+</div>
+```
+
+**`for` / `id` linking** — place the input before the label and connect them via matching `for` and `id` attributes.
+This is the standard HTML pattern and works well for text labels:
+
+```html
+<div class="btn-group" role="group" aria-label="View selection">
+  <input type="radio" class="btn-check" name="view" id="view-day" checked />
+  <label class="btn" for="view-day">Day</label>
+
+  <input type="radio" class="btn-check" name="view" id="view-week" />
+  <label class="btn" for="view-week">Week</label>
+
+  <input type="radio" class="btn-check" name="view" id="view-month" />
+  <label class="btn" for="view-month">Month</label>
+</div>
+```
+
 <si-docs-component example="buttons/selection-buttons" height="350"></si-docs-component>
diff --git a/src/app/examples/buttons/selection-buttons.html b/src/app/examples/buttons/selection-buttons.html
index f26c47e6a5..d10b65f7ae 100644
--- a/src/app/examples/buttons/selection-buttons.html
+++ b/src/app/examples/buttons/selection-buttons.html
@@ -40,9 +40,7 @@
         aria-label="One pane"
         checked
       />
-      <span class="btn btn-icon">
-        <si-icon class="icon" icon="element-layout-pane-1" />
-      </span>
+      <si-icon class="btn btn-icon icon" icon="element-layout-pane-1" />
     </label>
 
     <label>
@@ -53,9 +51,7 @@
         siTooltip="Two panes"
         aria-label="Two panes"
       />
-      <span class="btn btn-icon">
-        <si-icon class="icon" icon="element-layout-pane-2" />
-      </span>
+      <si-icon class="btn btn-icon icon" icon="element-layout-pane-2" />
     </label>
 
     <label>
@@ -66,9 +62,7 @@
         siTooltip="Three panes"
         aria-label="Three panes"
       />
-      <span class="btn btn-icon">
-        <si-icon class="icon" icon="element-layout-pane-3" />
-      </span>
+      <si-icon class="btn btn-icon icon" icon="element-layout-pane-3" />
     </label>
   </div>
 </div>
@@ -105,37 +99,27 @@ <h4>Multi-select</h4>
 <div class="btn-group mb-6" role="group" aria-label="Category filter">
   <label>
     <input type="checkbox" class="btn-check" siTooltip="Garden" aria-label="Garden" checked />
-    <span class="btn btn-icon">
-      <si-icon class="icon" icon="element-garden" />
-    </span>
+    <si-icon class="btn btn-icon icon" icon="element-garden" />
   </label>
 
   <label>
     <input type="checkbox" class="btn-check" siTooltip="Mobile" aria-label="Mobile" />
-    <span class="btn btn-icon">
-      <si-icon class="icon" icon="element-smartphone" />
-    </span>
+    <si-icon class="btn btn-icon icon" icon="element-smartphone" />
   </label>
 
   <label>
     <input type="checkbox" class="btn-check" siTooltip="Cloud" aria-label="Cloud" checked />
-    <span class="btn btn-icon">
-      <si-icon class="icon" icon="element-cloud" />
-    </span>
+    <si-icon class="btn btn-icon icon" icon="element-cloud" />
   </label>
 
   <label>
     <input type="checkbox" class="btn-check" siTooltip="AI" aria-label="AI" />
-    <span class="btn btn-icon">
-      <si-icon class="icon" icon="element-ai" />
-    </span>
+    <si-icon class="btn btn-icon icon" icon="element-ai" />
   </label>
 
   <label>
     <input type="checkbox" class="btn-check" siTooltip="Network" aria-label="Network" />
-    <span class="btn btn-icon">
-      <si-icon class="icon" icon="element-network" />
-    </span>
+    <si-icon class="btn btn-icon icon" icon="element-network" />
   </label>
 </div>
 
@@ -294,16 +278,12 @@ <h4>Sizing</h4>
         siTooltip="Heating"
         aria-label="Heating"
       />
-      <span class="btn btn-icon">
-        <si-icon class="icon" icon="element-sun" />
-      </span>
+      <si-icon class="btn btn-icon icon" icon="element-sun" />
     </label>
 
     <label>
       <input type="radio" class="btn-check" name="btnradio8" siTooltip="Water" aria-label="Water" />
-      <span class="btn btn-icon">
-        <si-icon class="icon" icon="element-water" />
-      </span>
+      <si-icon class="btn btn-icon icon" icon="element-water" />
     </label>
 
     <label>
@@ -314,9 +294,7 @@ <h4>Sizing</h4>
         siTooltip="Cooling"
         aria-label="Cooling"
       />
-      <span class="btn btn-icon">
-        <si-icon class="icon" icon="element-cooling-state" />
-      </span>
+      <si-icon class="btn btn-icon icon" icon="element-cooling-state" />
     </label>
   </div>