Fix underline-opacity utility composition with themed colors (#42697)

underline-opacity hardcoded --link-color, so pairing it with a themed
underline-color utility (or hovering) reset the underline back to the
link color instead of fading the intended theme color. Route
underline-color through a shared --underline-color custom property,
same pattern as our bg/fg/border opacity utilities, and have
underline-opacity read from it with currentcolor as a fallback.

Author: mdo

scss/_theme.scss

@@ -46,17 +46,21 @@
 }
 
 // Generate opacity values using color-mix()
-@function theme-opacity-values($color-var, $opacities: $util-opacity) {
+// $fallback lets the referenced $color-var fall back to another color (e.g. currentcolor)
+// when it hasn't been set by a companion color utility.
+@function theme-opacity-values($color-var, $fallback: null, $opacities: $util-opacity) {
   $result: ();
+  // stylelint-disable-next-line scss/at-function-named-arguments, @stylistic/function-whitespace-after
+  $color: if(sass($fallback): var($color-var, $fallback); else: var($color-var));
 
   @each $key, $value in $opacities {
     @if $key == 100 {
       // For 100%, use direct variable reference (more efficient)
-      $result: map.merge($result, ($key: var($color-var)));
+      $result: map.merge($result, ($key: $color));
     } @else {
       // For other values, use color-mix()
       $percentage: $key * 1%;
-      $result: map.merge($result, ($key: color-mix(in oklch, var($color-var) $percentage, transparent)));
+      $result: map.merge($result, ($key: color-mix(in oklch, $color $percentage, transparent)));
     }
   }
 

scss/_utilities.scss

@@ -803,15 +803,18 @@ $utilities: map.merge(
       )
     ),
     "underline-color": (
-      property: text-decoration-color,
+      property: (
+        "--underline-color": null,
+        "text-decoration-color": var(--underline-color)
+      ),
       class: underline,
       values: theme-color-values("fg"),
     ),
     "underline-opacity": (
       property: text-decoration-color,
       class: underline,
       state: hover,
-      values: theme-opacity-values(--link-color)
+      values: theme-opacity-values(--underline-color, currentcolor)
     ),
     "underline-thickness": (
       property: text-decoration-thickness,

site/src/content/docs/helpers/icon-link.mdx

@@ -78,7 +78,7 @@ Customize the icon link Sass variables to modify all icon link styles across you
 
 Modify icon links with any of [our link utilities]([[docsref:/utilities/link/]]) for modifying underline color and offset.
 
-<Example code={`<a class="icon-link icon-link-hover theme-success underline-success underline-25 underline-offset-3" href="#">
+<Example code={`<a class="icon-link icon-link-hover theme-success underline-success underline-30 hover:underline-80 underline-offset-3" href="#">
     Icon link
     <svg xmlns="http://www.w3.org/2000/svg" class="bi" viewBox="0 0 16 16" aria-hidden="true">
       <path d="M1 8a.5.5 0 0 1 .5-.5h11.793l-3.147-3.146a.5.5 0 0 1 .708-.708l4 4a.5.5 0 0 1 0 .708l-4 4a.5.5 0 0 1-.708-.708L13.293 8.5H1.5A.5.5 0 0 1 1 8z"/>

site/src/content/docs/utilities/text-decoration.mdx

@@ -40,7 +40,7 @@ Change the underline’s color independent of the text color.
 
 ### Opacity
 
-Change the underline’s opacity. Requires adding `.underline-{color}` to first set an `rgba()` color we use to then modify the alpha opacity.
+Change the underline’s opacity. Fades the current text color by default, or pair with `.underline-{color}` to first set a color that the opacity is then mixed against.
 
 <Example code={`<p><a class="underline-10" href="#">Underline opacity 10</a></p>
 <p><a class="underline-20" href="#">Underline opacity 20</a></p>
@@ -53,6 +53,10 @@ Change the underline’s opacity. Requires adding `.underline-{color}` to first
 <p><a class="underline-90" href="#">Underline opacity 90</a></p>
 <p><a class="underline-100" href="#">Underline opacity 100</a></p>`} />
 
+Pair an opacity class with a color class to fade that specific color instead of the default text color:
+
+<Example code={`<a class="theme-success underline-success underline-30 hover:underline-80" href="#">Faded success underline</a>`} />
+
 ### Thickness
 
 Change the thickness of the underline.