From a6e76572627858d9d281a63eb5244476759dbd5e Mon Sep 17 00:00:00 2001
From: Matyas Forian-Szabo <matyas.szabo@instructure.com>
Date: Mon, 17 Nov 2025 20:32:17 +0100
Subject: [PATCH] fix(ui-link): fix Link outline styles and overrides

The issue was that View's CSS specificity was higher, so it took precedence over Link's own styles.
This fix increases specificity higher and adds an example to test it

Fixes INSTUI-4854
---
 packages/ui-link/src/Link/README.md | 63 ++++++++++++++++++++++++++++-
 packages/ui-link/src/Link/styles.ts | 23 ++++++-----
 2 files changed, 75 insertions(+), 11 deletions(-)

diff --git a/packages/ui-link/src/Link/README.md b/packages/ui-link/src/Link/README.md
index 64c3980e51..6a895d1565 100644
--- a/packages/ui-link/src/Link/README.md
+++ b/packages/ui-link/src/Link/README.md
@@ -10,7 +10,13 @@ describes: Link
 ---
 type: example
 ---
-<Text>The quick brown fox <Link href="https://instructure.github.io/instructure-ui/">jumps</Link> over the lazy dog.</Text>
+  <div>
+<Text>The quick brown fox <Link href="https://instructure.github.io/instructure-ui/"
+                                themeOverride={{
+                                  focusOutlineColor: 'pink'
+                                }}>jumps</Link> over the lazy dog.</Text>
+<Link color="link-inverse" href="https://instructure.github.io/instructure-ui/">jumps</Link>
+</div>
 ```
 
 ```js
@@ -18,7 +24,9 @@ type: example
 type: example
 ---
 <View background="primary-inverse" as="div">
-  <Text color="primary-inverse">The quick brown fox <Link color="link-inverse" href="https://instructure.github.io/instructure-ui/">jumps</Link> over the lazy dog.</Text>
+  <Text color="primary-inverse">The quick brown fox <Link color="link-inverse" href="https://instructure.github.io/instructure-ui/" themeOverride={{
+    focusInverseIconOutlineColor: 'pink'
+  }}>jumps</Link> over the lazy dog.</Text>
 </View>
 ```
 
@@ -154,6 +162,57 @@ type: example
 </div>
 ```
 
+### Theme overrides
+
+Examples showing how theme overrides work for Link:
+
+```js
+---
+type: example
+---
+<div>
+  <Text>The quick brown fox <Link
+    href="https://instructure.github.io/instructure-ui/"
+    themeOverride={{
+      focusOutlineWidth: '0.5rem',
+      focusOutlineStyle: 'dashed',
+      focusOutlineBorderRadius: '0',
+      focusOutlineColor: 'pink'
+    }}>jumps</Link> over the lazy dog.
+  </Text>
+</div>
+```
+
+```js
+---
+type: example
+---
+<View background="primary-inverse" as="div">
+  <Text color="primary-inverse">The quick brown fox <Link
+    color="link-inverse"
+    href="https://instructure.github.io/instructure-ui/"
+    themeOverride={{
+      focusOutlineWidth: '0.5rem',
+      focusOutlineStyle: 'dashed',
+      focusOutlineBorderRadius: '0',
+      focusInverseOutlineColor: 'green'
+  }}
+  >jumps</Link> over the lazy dog.</Text>
+  <br />
+  <Text color="primary-inverse">The quick brown fox <Link
+    color="link-inverse"
+    href="https://instructure.github.io/instructure-ui/"
+    renderIcon={<IconUserLine />}
+    themeOverride={{
+      focusOutlineWidth: '0.5rem',
+      focusOutlineStyle: 'dashed',
+      focusOutlineBorderRadius: '0',
+      focusInverseIconOutlineColor: 'red'
+  }}
+  >jumps</Link> over the lazy dog.</Text>
+</View>
+```
+
 ### Guidelines
 
 ```js
diff --git a/packages/ui-link/src/Link/styles.ts b/packages/ui-link/src/Link/styles.ts
index f7480867bf..5121d1d0a7 100644
--- a/packages/ui-link/src/Link/styles.ts
+++ b/packages/ui-link/src/Link/styles.ts
@@ -80,12 +80,8 @@ const generateStyle = (
     fontWeight: componentTheme.fontWeight,
     transition: 'outline-color 0.2s',
     verticalAlign: 'baseline',
-
     // set up focus styles
     outlineColor: 'transparent',
-    outlineWidth: componentTheme.focusOutlineWidth,
-    outlineStyle: componentTheme.focusOutlineStyle,
-    borderRadius: componentTheme.focusOutlineBorderRadius,
     outlineOffset: '0.25rem',
     textUnderlineOffset: componentTheme.textUnderlineOffset,
 
@@ -96,7 +92,10 @@ const generateStyle = (
         alignItems: 'center'
       }),
 
-    '&:focus': {
+    '&&&&&&:focus': {
+      outlineWidth: componentTheme.focusOutlineWidth,
+      outlineStyle: componentTheme.focusOutlineStyle,
+      borderRadius: componentTheme.focusOutlineBorderRadius,
       outlineColor: componentTheme.focusOutlineColor
     },
     '&[aria-disabled]': {
@@ -114,7 +113,8 @@ const generateStyle = (
     ...baseStyles,
     cursor: 'pointer',
     color: componentTheme.color,
-    '&:focus': {
+    // This needs stronger specificity than `View`
+    '&&&&&:focus': {
       color: componentTheme.color,
       outlineColor: componentTheme.focusOutlineColor
     },
@@ -147,10 +147,15 @@ const generateStyle = (
 
   const inverseStyles = {
     color: componentTheme.colorInverse,
-    '&:focus': {
-      outlineColor: componentTheme.focusInverseIconOutlineColor
+    '&&&&&:focus': {
+      outlineColor: componentTheme.focusInverseOutlineColor
     },
-    '&:hover, &:focus, &:active': {
+    ...(renderIcon && {
+      '&&&&&:focus': {
+        outlineColor: componentTheme.focusInverseIconOutlineColor
+      }
+    }),
+    '&:hover, &&&&&:focus, &:active': {
       color: componentTheme.colorInverse
     }
   }