Add new link utilities, icon link helper, and update colored link helpers

.bundlewatch.config.json

@@ -18,19 +18,19 @@
     },
     {
       "path": "./dist/css/bootstrap-utilities.css",
-      "maxSize": "10.75 kB"
+      "maxSize": "11.5 kB"
     },
     {
       "path": "./dist/css/bootstrap-utilities.min.css",
-      "maxSize": "10.0 kB"
+      "maxSize": "10.75 kB"
     },
     {
       "path": "./dist/css/bootstrap.css",
-      "maxSize": "31.5 kB"
+      "maxSize": "32.0 kB"
     },
     {
       "path": "./dist/css/bootstrap.min.css",
-      "maxSize": "29.5 kB"
+      "maxSize": "30.0 kB"
     },
     {
       "path": "./dist/js/bootstrap.bundle.js",

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";

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;

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,

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));
       }
     }
   }

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));
+    }
+  }
+}

site/assets/scss/_content.scss

@@ -124,26 +124,6 @@
   fill: currentcolor;
 }
 
-.icon-link {
-  display: flex;
-  align-items: center;
-  text-decoration-color: rgba($primary, .5);
-  text-underline-offset: .5rem;
-  backface-visibility: hidden;
-
-  .bi {
-    width: 1.5em;
-    height: 1.5em;
-    transition: .2s ease-in-out transform; // stylelint-disable-line property-disallowed-list
-  }
-
-  &:hover {
-    .bi {
-      transform: translate3d(5px, 0, 0);
-    }
-  }
-}
-
 .border-lg-start {
   @include media-breakpoint-up(lg) {
     border-left: var(--bs-border-width) solid var(--bs-border-color);

site/content/docs/5.3/examples/features/features.css

@@ -4,16 +4,6 @@
   border-radius: .75rem;
 }
 
-.icon-link > .bi {
-  margin-top: .125rem;
-  margin-left: .125rem;
-  fill: currentcolor;
-  transition: transform .25s ease-in-out;
-}
-.icon-link:hover > .bi {
-  transform: translate(.25rem);
-}
-
 .icon-square {
   width: 3rem;
   height: 3rem;

site/content/docs/5.3/examples/features/index.html

@@ -76,9 +76,9 @@ <h2 class="pb-2 border-bottom">Columns with icons</h2>
         </div>
         <h3 class="fs-2">Featured title</h3>
         <p>Paragraph of text beneath the heading to explain the heading. We'll add onto it with another sentence and probably just keep going until we run out of words.</p>
-        <a href="#" class="icon-link d-inline-flex align-items-center">
+        <a href="#" class="icon-link">
           Call to action
-          <svg class="bi" width="1em" height="1em"><use xlink:href="#chevron-right"/></svg>
+          <svg class="bi"><use xlink:href="#chevron-right"/></svg>
         </a>
       </div>
       <div class="feature col">
@@ -87,9 +87,9 @@ <h3 class="fs-2">Featured title</h3>
         </div>
         <h3 class="fs-2">Featured title</h3>
         <p>Paragraph of text beneath the heading to explain the heading. We'll add onto it with another sentence and probably just keep going until we run out of words.</p>
-        <a href="#" class="icon-link d-inline-flex align-items-center">
+        <a href="#" class="icon-link">
           Call to action
-          <svg class="bi" width="1em" height="1em"><use xlink:href="#chevron-right"/></svg>
+          <svg class="bi"><use xlink:href="#chevron-right"/></svg>
         </a>
       </div>
       <div class="feature col">
@@ -98,9 +98,9 @@ <h3 class="fs-2">Featured title</h3>
         </div>
         <h3 class="fs-2">Featured title</h3>
         <p>Paragraph of text beneath the heading to explain the heading. We'll add onto it with another sentence and probably just keep going until we run out of words.</p>
-        <a href="#" class="icon-link d-inline-flex align-items-center">
+        <a href="#" class="icon-link">
           Call to action
-          <svg class="bi" width="1em" height="1em"><use xlink:href="#chevron-right"/></svg>
+          <svg class="bi"><use xlink:href="#chevron-right"/></svg>
         </a>
       </div>
     </div>

site/content/docs/5.3/helpers/colored-links.md

@@ -3,19 +3,35 @@ layout: docs
 title: Colored links
 description: Colored links with hover states
 group: helpers
-toc: false
+toc: true
 ---
 
-You can use the `.link-*` classes to colorize links. Unlike the [`.text-*` classes]({{< docsref "/utilities/colors" >}}), these classes have a `:hover` and `:focus` state.
+## Link colors
+
+You can use the `.link-*` classes to colorize links. Unlike the [`.text-*` classes]({{< docsref "/utilities/colors" >}}), these classes have a `:hover` and `:focus` state. Some of the link styles use a relatively light foreground color, and should only be used on a dark background in order to have sufficient contrast.
 
 {{< example >}}
 {{< colored-links.inline >}}
 {{- range (index $.Site.Data "theme-colors") }}
-<a href="#" class="link-{{ .name }}">{{ .name | title }} link</a>
+<p><a href="#" class="link-{{ .name }}">{{ .name | title }} link</a></p>
 {{- end -}}
 {{< /colored-links.inline >}}
 {{< /example >}}
 
 {{< callout info >}}
-Some of the link styles use a relatively light foreground color, and should only be used on a dark background in order to have sufficient contrast.
+{{< partial "callouts/warning-color-assistive-technologies.md" >}}
 {{< /callout >}}
+
+## Link utilities
+
+{{< added-in "5.3.0" >}}
+
+Colored links can also be modified by our [link utilities]({{< docsref "/utilities/link/" >}}).
+
+{{< example >}}
+{{< colored-links.inline >}}
+{{- range (index $.Site.Data "theme-colors") }}
+<p><a href="#" class="link-{{ .name }} link-offset-2 link-underline-opacity-25 link-underline-opacity-100-hover">{{ .name | title }} link</a></p>
+{{- end -}}
+{{< /colored-links.inline >}}
+{{< /example >}}

site/content/docs/5.3/helpers/icon-link.md

@@ -0,0 +1,66 @@
+---
+layout: docs
+title: Icon link
+description: Quickly create stylized hyperlinks with Bootstrap Icons or other icons.
+group: helpers
+aliases: "/docs/5.3/icon-link/"
+toc: true
+added: 5.3
+---
+
+The icon link helper component modifies our default link styles to enhance their appearance and quickly align any pairing of icon and text. Alignment is set via inline flexbox styling and a default `gap` value. We stylize the underline with a custom offset and color. Icons are automatically sized to `1em` to best match their associated text's `font-size`.
+
+Icon links assume [Bootstrap Icons](https://icons.getbootstrap.com) are being used, but you can use any icon or image you like.
+
+{{< callout >}}
+Icons used here are likely to be purely decorative, which means they should be hidden from assistive technologies using `aria-hidden="true"`, as we've done in our examples. For icons that are more than decorative, provide an appropriate text alternative via `alt` for `<img>` elements `role="img"` and `aria-label` for SVGs.
+{{< /callout >}}
+
+## Example
+
+Take a regular `<a>` element, add `.icon-link`, and insert an icon on either the left or right of your link text. The icon is automatically sized, placed, and colored.
+
+{{< example >}}
+<a class="icon-link" href="#">
+  <svg class="bi" aria-hidden="true"><use xlink:href="#box-seam"></use></svg>
+  Icon link
+</a>
+{{< /example >}}
+
+{{< example >}}
+<a class="icon-link" href="#">
+  Icon link
+  <svg class="bi" aria-hidden="true"><use xlink:href="#arrow-right"></use></svg>
+</a>
+{{< /example >}}
+
+## Style on hover
+
+Add `.icon-link-hover` to move the icon to the right on hover.
+
+{{< example >}}
+<a class="icon-link icon-link-hover" href="#">
+  Icon link
+  <svg class="bi" aria-hidden="true"><use xlink:href="#arrow-right"></use></svg>
+</a>
+{{< /example >}}
+
+Customize the hover `transform` by overriding the `--bs-icon-link-transform` CSS variable:
+
+{{< example >}}
+<a class="icon-link icon-link-hover" style="--bs-icon-link-transform: translate3d(0, -.125rem, 0);" href="#">
+  <svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"></use></svg>
+  Icon link
+</a>
+{{< /example >}}
+
+## Pairs with link utilities
+
+Modify icon links with any of [our link utilities]({{< docsref "/utilities/link/" >}}) for modifying underline color and offset.
+
+{{< example >}}
+<a class="icon-link icon-link-hover link-success link-underline-success link-underline-opacity-25" href="#">
+  Icon link
+  <svg class="bi" aria-hidden="true"><use xlink:href="#arrow-right"></use></svg>
+</a>
+{{< /example >}}