Add new link utilities, icon link helper, and update colored link helpers (#37762)

* Add new link utilities, update colored link helpers

* Remove commented out code

* Fixes

* Remove examples changes

* Fixes and copy

* Fix icon-link instances on homepage

* Bump bundlewatch

* Fix node-sass issue for rgba() function bug

* More bundlewatch

* One more time after merge

* Add callout for a11y

* Hover and focus-visible

* Add a11y callouts

* Remove duplicate for now

* More code review feedback

5 files changed, 85 insertions, 2 deletions

diff --git a/scss/_helpers.scss b/scss/_helpers.scss
index 6126781cd..13f2752c9 100644
--- a/scss/_helpers.scss
+++ b/scss/_helpers.scss
@@ -2,6 +2,7 @@
 @import "helpers/color-bg";
 @import "helpers/colored-links";
 @import "helpers/focus-ring";
+@import "helpers/icon-link";
 @import "helpers/ratio";
 @import "helpers/position";
 @import "helpers/stacks";
diff --git a/scss/_maps.scss b/scss/_maps.scss
index 6418a3f6c..9a5cc96b6 100644
--- a/scss/_maps.scss
+++ b/scss/_maps.scss
@@ -116,6 +116,8 @@ $utilities-border-subtle: (
 ) !default;
 // scss-docs-end utilities-border-colors
 
+$utilities-links-underline: map-loop($utilities-colors, rgba-css-var, "$key", "link-underline") !default;
+
 $negative-spacers: if($enable-negative-margins, negativify-map($spacers), null) !default;
 
 $gutters: $spacers !default;
diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 5134688e9..d017d117f 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -609,6 +609,56 @@ $utilities: map-merge(
       values: $utilities-text-emphasis-colors
     ),
     // scss-docs-end utils-color
+    // scss-docs-start utils-links
+    "link-opacity": (
+      css-var: true,
+      class: link-opacity,
+      state: hover,
+      values: (
+        10: .1,
+        25: .25,
+        50: .5,
+        75: .75,
+        100: 1
+      )
+    ),
+    "link-offset": (
+      property: text-underline-offset,
+      class: link-offset,
+      state: hover,
+      values: (
+        1: .125em,
+        2: .25em,
+        3: .375em,
+      )
+    ),
+    "link-underline": (
+      // css-var: true,
+      property: text-decoration-color,
+      class: link-underline,
+      local-vars: (
+        "link-underline-opacity": 1
+      ),
+      values: map-merge(
+        $utilities-links-underline,
+        (
+          null: rgba(var(--#{$prefix}link-color-rgb), var(--#{$prefix}link-underline-opacity, 1)),
+        )
+      )
+    ),
+    "link-underline-opacity": (
+      css-var: true,
+      class: link-underline-opacity,
+      state: hover,
+      values: (
+        10: .1,
+        25: .25,
+        50: .5,
+        75: .75,
+        100: 1
+      ),
+    ),
+    // scss-docs-end utils-links
     // scss-docs-start utils-bg-color
     "background-color": (
       property: background-color,
diff --git a/scss/helpers/_colored-links.scss b/scss/helpers/_colored-links.scss
index 0e03039bb..06c8ce412 100644
--- a/scss/helpers/_colored-links.scss
+++ b/scss/helpers/_colored-links.scss
@@ -1,11 +1,17 @@
+// stylelint-disable function-name-case
+
+// All-caps `RGBA()` function used because of this Sass bug: https://github.com/sass/node-sass/issues/2251
 @each $color, $value in $theme-colors {
   .link-#{$color} {
-    color: $value if($enable-important-utilities, !important, null);
+    --#{$prefix}link-color-rgb: #{to-rgb($value)};
+    text-decoration-color: RGBA(to-rgb($value), var(--#{$prefix}link-underline-opacity, 1));
 
     @if $link-shade-percentage != 0 {
       &:hover,
       &:focus {
-        color: if(color-contrast($value) == $color-contrast-light, shade-color($value, $link-shade-percentage), tint-color($value, $link-shade-percentage)) if($enable-important-utilities, !important, null);
+        $hover-color: if(color-contrast($value) == $color-contrast-light, shade-color($value, $link-shade-percentage), tint-color($value, $link-shade-percentage));
+        --#{$prefix}link-color-rgb: #{to-rgb($hover-color)};
+        text-decoration-color: RGBA(to-rgb($hover-color), var(--#{$prefix}link-underline-opacity, 1));
       }
     }
   }
diff --git a/scss/helpers/_icon-link.scss b/scss/helpers/_icon-link.scss
new file mode 100644
index 000000000..712dd02c7
--- /dev/null
+++ b/scss/helpers/_icon-link.scss
@@ -0,0 +1,24 @@
+.icon-link {
+  display: inline-flex;
+  gap: .375rem;
+  align-items: center;
+  text-decoration-color: rgba(var(--#{$prefix}link-color-rgb), var(--#{$prefix}link-opacity, .5));
+  text-underline-offset: .5rem;
+  backface-visibility: hidden;
+
+  > .bi {
+    flex-shrink: 0;
+    width: 1em;
+    height: 1em;
+    @include transition(.2s ease-in-out transform);
+  }
+}
+
+.icon-link-hover {
+  &:hover,
+  &:focus-visible {
+    > .bi {
+      transform: var(--#{$prefix}icon-link-transform, translate3d(.25em, 0, 0));
+    }
+  }
+}