From 360b525b4bf1c3df80e4461ff29290e4b2c1586b Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Mon, 5 Jan 2026 13:56:08 +0100
Subject: [PATCH] Fix FontAwesome 7 icon overflows (#3885)

---
 .changeset/tidy-flies-burn.md         |  6 ++++++
 packages/gitbook/e2e/internal.spec.ts |  2 +-
 packages/gitbook/e2e/util.ts          | 11 +++++-----
 packages/icons/src/Icon.tsx           | 29 +++++++++++++++++++--------
 4 files changed, 34 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/tidy-flies-burn.md

diff --git a/.changeset/tidy-flies-burn.md b/.changeset/tidy-flies-burn.md
new file mode 100644
index 000000000..8d785563c
--- /dev/null
+++ b/.changeset/tidy-flies-burn.md
@@ -0,0 +1,6 @@
+---
+"gitbook": patch
+"@gitbook/icons": patch
+---
+
+Switch icon masking method to fix visual cutoffs in FA7
diff --git a/packages/gitbook/e2e/internal.spec.ts b/packages/gitbook/e2e/internal.spec.ts
index 5bbc27561..4d0cf5305 100644
--- a/packages/gitbook/e2e/internal.spec.ts
+++ b/packages/gitbook/e2e/internal.spec.ts
@@ -1291,7 +1291,7 @@ const testCases: TestsCase[] = [
                 name: 'Redirect to Quickstart page',
                 url: 'sections-2/redirect-test',
                 run: async (page) => {
-                    await expect(page.locator('h1')).toHaveText('Quickstart');
+                    await expect(page.locator('h1')).toContainText('Quickstart');
                 },
                 screenshot: false,
             },
diff --git a/packages/gitbook/e2e/util.ts b/packages/gitbook/e2e/util.ts
index 6b62dea8c..0957d83d0 100644
--- a/packages/gitbook/e2e/util.ts
+++ b/packages/gitbook/e2e/util.ts
@@ -417,14 +417,15 @@ export async function waitForIcons(page: Page) {
                 return true;
             }
 
-            // url("https://ka-p.fontawesome.com/releases/v6.6.0/svgs/light/moon.svg?v=2&token=a463935e93")
-            const maskImage = window.getComputedStyle(icon).getPropertyValue('mask-image');
-            const urlMatch = maskImage.match(/url\("([^"]+)"\)/);
-            const url = urlMatch?.[1];
+            const maskImage = icon.querySelector('[data-testid="mask-image"]');
+            if (!maskImage) {
+                throw new Error('No mask-image element');
+            }
 
+            const url = maskImage.getAttribute('href');
             // If URL is invalid we throw an error.
             if (!url) {
-                throw new Error('No mask-image');
+                throw new Error('No mask-image url');
             }
 
             // If the URL is already queued for loading, we return the state.
diff --git a/packages/icons/src/Icon.tsx b/packages/icons/src/Icon.tsx
index d1eedd06e..92e1f7fb4 100644
--- a/packages/icons/src/Icon.tsx
+++ b/packages/icons/src/Icon.tsx
@@ -51,23 +51,36 @@ export const Icon = React.forwardRef(function Icon(
 
     const [iconStyle, icon] = getIconStyle(propIconStyle, propIcon);
     const url = getIconAssetURL(context, iconStyle, icon);
+    const maskId = React.useId();
 
     return (
         <svg
             ref={ref}
             {...rest}
             style={{
-                maskImage: `url(${url})`,
-                WebkitMaskImage: `url(${url})`,
-                maskRepeat: 'no-repeat',
-                WebkitMaskRepeat: 'no-repeat',
-                maskPosition: 'center',
-                WebkitMaskPosition: 'center',
-                backgroundColor: 'currentColor',
                 ...(size ? { width: size, height: size } : {}),
                 ...rest.style,
             }}
             className={`gb-icon ${className}`}
-        />
+        >
+            <title>{icon}</title>
+            <defs>
+                <mask
+                    id={maskId}
+                    style={{
+                        maskType: 'alpha',
+                    }}
+                >
+                    <image
+                        data-testid="mask-image"
+                        href={url}
+                        width="100%"
+                        height="100%"
+                        preserveAspectRatio="xMidYMid meet"
+                    />
+                </mask>
+            </defs>
+            <rect width="100%" height="100%" fill="currentColor" mask={`url(#${maskId})`} />
+        </svg>
     );
 });