From 11519625ed1599bc24394a27b727b57be5c9c396 Mon Sep 17 00:00:00 2001
From: Lindsay M <126139086+lindsaym-fa@users.noreply.github.com>
Date: Fri, 18 Jul 2025 09:47:24 -0400
Subject: [PATCH] Use margin for `<wa-icon>` spacing in native buttons (#1197)

---
 packages/webawesome/docs/docs/utilities/native.md | 13 +++++++++++++
 packages/webawesome/src/styles/native.css         | 11 ++++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/packages/webawesome/docs/docs/utilities/native.md b/packages/webawesome/docs/docs/utilities/native.md
index 6d0759dfc..cfeb25f89 100644
--- a/packages/webawesome/docs/docs/utilities/native.md
+++ b/packages/webawesome/docs/docs/utilities/native.md
@@ -380,6 +380,19 @@ Add the `wa-pill` class to give buttons rounded edges.
 <button class="wa-pill">Pill button</button>
 ```
 
+When using `<wa-icon>` within a button, wrap adjacent label text in `<span>` or similar to automatically add margin between the icon and the label, just like the `start` and `end` slots of `<wa-button>`.
+
+```html {.example}
+<button>
+  <wa-icon name="plane-departure"></wa-icon>
+  <span>Start Icon</span>
+</button>
+<button>
+  <span>End Icon</span>
+  <wa-icon name="plane-arrival"></wa-icon>
+</button>
+```
+
 ### Form controls
 
 Create a variety of form controls with `<input type="">`, `<select>`, and `<textarea>`. Each control closely matches the appearance of the corresponding Web Awesome component.
diff --git a/packages/webawesome/src/styles/native.css b/packages/webawesome/src/styles/native.css
index a58798169..466d141f0 100644
--- a/packages/webawesome/src/styles/native.css
+++ b/packages/webawesome/src/styles/native.css
@@ -564,7 +564,6 @@
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    gap: 0.5em;
 
     height: var(--wa-form-control-height);
     padding: 0 var(--wa-form-control-padding-inline);
@@ -709,6 +708,16 @@
     &.wa-pill {
       border-radius: var(--wa-border-radius-pill);
     }
+
+    /* Adds space between icons and adjacent elements
+     * Prefer sibling selectors over :first-child/:last-child to avoid extra space when an icon is used alone */
+    & > wa-icon:has(+ *) {
+      margin-inline-end: 0.75em;
+    }
+
+    & > * + wa-icon {
+      margin-inline-start: 0.75em;
+    }
   }
   /* #endregion */