From 4d01016a828cf43ca9ad438cb551acbc2f5b98df Mon Sep 17 00:00:00 2001
From: Tom J Nowell <contact@tomjn.com>
Date: Thu, 24 Sep 2026 18:19:19 +0100
Subject: [PATCH] Put the icon and label in a row despite core's button styles

Core's button stylesheet sets display: inline-block on every .wp-block-button__link, and the row rule was in :where(), so it never applied. The icon and label sat side by side as top aligned inline boxes, so the icon rode above the text and the button grew taller. The display and alignment now carry a class each, and the gap stays in :where() for themes to change.
---
 CLAUDE.md      |  7 ++++---
 README.md      |  7 ++++---
 src/style.scss | 16 ++++++++++++----
 3 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 27384c3..990874b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -93,9 +93,10 @@ rendered class stop agreeing.
 hence the `hm-button-icon__label` guard near the top of `render()`.
 
 **Single-mechanism choices a cleanup would undo:** icon side is the order
-`render()` writes the two children in, not a flex direction. The layout rule in
-`src/style.scss` is wrapped in `:where()` so it carries no specificity and any theme
-rule wins.
+`render()` writes the two children in, not a flex direction. The gap and alignment in
+`src/style.scss` are wrapped in `:where()` so any theme rule wins. The `display` rule
+beside them is not, on purpose: core's button stylesheet sets `display: inline-block`
+on the link, and a zero-specificity rule loses to it on every site.
 
 **Uploaded SVGs are inlined unsanitised, on purpose.** `uploaded_icon_markup()`
 checks the mime type and writes the file into the page, which makes an
diff --git a/README.md b/README.md
index 4ab91d8..adbc840 100644
--- a/README.md
+++ b/README.md
@@ -66,9 +66,10 @@ would read as a glitch.
 ### Styling
 
 The plugin's stylesheet is deliberately thin: it stops the icon squashing and
-recolours a registered one to `currentcolor`. The layout rule that puts the icon
-and label in a row is written in `:where()`, so it holds no specificity and a
-theme's own button rules always win.
+recolours a registered one to `currentcolor`. The rule that puts the icon and
+label in a row carries just enough specificity to beat core's own
+`display: inline-block` on the button link. The gap and alignment are written
+in `:where()`, so they hold no specificity and a theme's own button rules win.
 
 A **Color** override does not add a class or a rule; it is a `style="color: …"`
 on the `<svg>` itself, which is what `currentcolor` then resolves to instead of
diff --git a/src/style.scss b/src/style.scss
index 64a739f..44f0c22 100644
--- a/src/style.scss
+++ b/src/style.scss
@@ -6,13 +6,21 @@
  * colour, and that a hidden label stays available to a screen reader. How the
  * button itself looks is the theme's business.
  *
- * The layout rule is written in `:where()` so it holds no specificity at all.
- * A theme that already lays its buttons out as a flex row overrides it with
- * any selector it likes; one that does not gets a sensible arrangement free.
+ * The row itself needs enough specificity to beat core's button stylesheet,
+ * which sets `display: inline-block` on every `.wp-block-button__link`. Without
+ * the row the icon and label sit side by side as inline boxes, top aligned, so
+ * the icon rides above the text and the button grows taller.
  */
-:where(.hm-has-button-icon) > :where(.wp-block-button__link) {
+.hm-has-button-icon > .wp-block-button__link {
 	display: inline-flex;
 	align-items: center;
+}
+
+/**
+ * The spacing is written in `:where()` so it holds no specificity at all, and a
+ * theme can change it with any selector it likes.
+ */
+:where(.hm-has-button-icon) > :where(.wp-block-button__link) {
 	justify-content: center;
 	gap: 0.5em;
 }