uswds-jekyll 5.3.0 → 5.4.0

data/_sass/uswds/src/components/_skipnav.scss

@@ -10,7 +10,8 @@
   transition: $project-easing;
   z-index: z-index(100);
 
-  &:focus {
+  &:focus,
+  &.usa-focus {
     background: color("white");
     left: 0;
     position: absolute;

data/_sass/uswds/src/components/_summary-box.scss

@@ -0,0 +1,67 @@
+$summary-box-context: "Summary Box";
+
+.usa-summary-box {
+  @include typeset($theme-summary-box-font-family);
+  @include border-box-sizing;
+  @include set-text-and-bg(
+    $theme-summary-box-background-color,
+    $theme-summary-box-text-color,
+    $context: $summary-box-context
+  );
+  @include u-radius($theme-summary-box-border-radius);
+  border: $theme-summary-box-border-width color($theme-summary-box-border-color)
+    solid;
+  padding: units(3);
+  position: relative;
+
+  .usa-list {
+    &:last-child {
+      margin-bottom: 0;
+    }
+  }
+
+  * + & {
+    margin-top: units(2);
+  }
+}
+
+.usa-summary-box__body {
+  display: table-cell;
+  vertical-align: top;
+}
+
+.usa-summary-box__heading {
+  @include typeset($theme-summary-box-font-family, "lg", 2);
+  margin-top: 0;
+  margin-bottom: units(1);
+}
+
+.usa-summary-box__text {
+  @include u-margin-y(0);
+}
+
+.usa-summary-box__text:only-child {
+  margin-bottom: $theme-summary-box-border-width;
+  padding-top: units(0.5);
+}
+
+.usa-summary-box__link {
+  @include set-link-from-bg(
+    $theme-summary-box-background-color,
+    $theme-summary-box-link-color,
+    $context: $summary-box-context
+  );
+  &[href^="#"] {
+    $link-tokens: get-link-tokens-from-bg(
+      $theme-summary-box-background-color,
+      $theme-summary-box-link-color,
+      $context: $summary-box-context
+    );
+    &:visited {
+      color: color(nth($link-tokens, 1));
+    }
+    &:hover {
+      color: color(nth($link-tokens, 2));
+    }
+  }
+}

data/_sass/uswds/src/core/_functions.scss

@@ -22,6 +22,43 @@ General-purpose functions
 ----------------------------------------
 */
 
+/*
+----------------------------------------
+uswds-error()
+----------------------------------------
+Allow the system to pass an error as text
+to test error states in unit testing
+----------------------------------------
+*/
+
+$_error-output-override: false !default;
+@function uswds-error($message, $override: $_error-output-override) {
+  @if $override {
+    @return "Error: #{$message}";
+  }
+
+  @error "#{$message}";
+}
+
+/*
+----------------------------------------
+error-not-token()
+----------------------------------------
+Returns a common not-a-token error.
+----------------------------------------
+*/
+
+@function error-not-token($token, $type, $valid-token-map: false) {
+  $valid-token-message: if(
+    $valid-token-map,
+    " Valid tokens: #{map-keys($valid-token-map)}",
+    ""
+  );
+  @return uswds-error(
+    "'#{$token}' is not a valid USWDS #{$type} token.#{$valid-token-message}"
+  );
+}
+
 /*
 ----------------------------------------
 map-deep-get()
@@ -403,8 +440,7 @@ not exist in the typeface-token map.
 
 @function validate-typeface-token($typeface-token) {
   @if not map-has-key($all-typeface-tokens, $typeface-token) {
-    @error '`#{$typeface-token}` is not a valid typeface token. '
-      + 'Valid tokens: #{map-keys($all-typeface-tokens)} ';
+    @return error-not-token($typeface-token, "typeface", $all-typeface-tokens);
   }
 
   @return $typeface-token;
@@ -481,15 +517,13 @@ withholds certain errors.
 
 @function utility-font($family, $scale) {
   @if not map-has-key($project-cap-heights, $family) {
-    @error '#{$family} is not a valid font family token. '
-      + 'Valid tokens: #{map-keys($project-cap-heights)}';
+    @return error-not-token($family, "font family", $project-cap-heights);
   }
 
   $quote-scale: smart-quote($scale);
 
   @if not map-get($all-type-scale, $quote-scale) {
-    @error '`#{$scale}` is not a valid font scale token. '
-      + 'Valid tokens: #{map-keys($all-type-scale)}';
+    @return error-not-token($scale, "font scale", $all-type-scale);
   }
 
   $this-cap: map-get($project-cap-heights, $family);
@@ -524,13 +558,11 @@ a family and a line-height scale unit
   $scale: smart-quote(nth($props, 2));
 
   @if not map-has-key($project-cap-heights, $family) {
-    @error '#{$family} is not a valid font family token. '
-      + 'Valid tokens: #{map-keys($project-cap-heights)}';
+    @return error-not-token($family, "font family", $project-cap-heights);
   }
 
   @if not map-get($system-line-height, $scale) {
-    @error '`#{$scale}` is not a valid line-height token. '
-      + 'Valid tokens: #{map-keys($system-line-height)}';
+    @return error-not-token($scale, "line-height", $system-line-height);
   }
 
   @if not map-get($project-cap-heights, $family) {
@@ -725,8 +757,7 @@ Get a value from the system type scale
   }
 
   @if not map-has-key($system-type-scale, $scale) {
-    @error '`#{$scale}` is not a valid type scale token. '
-      + 'Valid tokens: #{map-keys($system-type-scale)}';
+    @return error-not-token($scale, "type scale", $system-type-scale);
   }
 
   @return map-get($system-type-scale, $scale);
@@ -747,7 +778,7 @@ grid.
   $gap-size: smart-quote($gap-size);
 
   @if not map-has-key($spacing-to-value, $gap-size) {
-    @error '`#{$gap-size}` is not a valid USWDS gap size token.';
+    @return error-not-token($gap-size, "gap size");
   }
 
   $numeric-eq: map-get($spacing-to-value, $gap-size);
@@ -877,9 +908,7 @@ functions and mixins.
 
   // TODO: what are these last two cases? Evaluate.
   @if not(type-of($value) == "number" and not unitless($value)) {
-    @error '`#{$value}` is not a valid `#{$property}` token. '
-      + 'You should correct this. Standard `#{$property}` tokens: '
-      + ' #{map-keys($our-standard-values)}';
+    @return error-not-token($value, $property, $our-standard-values);
   }
 
   @if $theme-show-compile-warnings {
@@ -1064,7 +1093,7 @@ Includes helper functions
 
 /*
 ----------------------------------------
-decompose()
+decompose-color-token()
 ----------------------------------------
 Convert a color token into into a list
 of form [family], [grade], [variant]
@@ -1073,11 +1102,11 @@ Vivid variants return "vivid" as the
 variant.
 
 If neither grade nor variant exists,
-returns 'null'
+returns 'false'
 ----------------------------------------
 */
 
-@function decompose($token) {
+@function decompose-color-token($token) {
   $separator: "-";
   $family: false;
   $grade: false;
@@ -1086,28 +1115,51 @@ returns 'null'
     "black": 100,
     "white": 0,
   );
-
-  $token: get-color-token-assignment($token);
-  $split: str-split($token, $separator);
-  $grade: nth($split, length($split));
-
-  @if str-index($grade, "v") {
-    $variant: "vivid";
-    $grade: str-slice($grade, 1, (str-index($grade, "v") - 1));
-  }
-
-  @if length($split) == 3 {
-    $family: nth($split, 1) + $separator + nth($split, 2);
+  $token: if($token == "ink", "base-darkest", $token);
+  // If there's no separator, set family and grade
+  @if not str-index($token, $separator) {
+    $family: $token;
+    $grade: if(
+      map-has-key($exceptions, $family),
+      map-get($exceptions, $family),
+      "root"
+    );
   } @else {
-    $family: nth($split, 1);
-  }
-
-  $grade: to-number($grade);
-
-  @if map-has-key($exceptions, $family) {
-    $grade: map-get($exceptions, $family);
+    $split: str-split($token, $separator);
+    $last: nth($split, length($split));
+    // If the last string is over 3 char, it's a theme token
+    @if str-length($last) > 3 {
+      @if $last == "vivid" {
+        $variant: "vivid";
+        $grade: "root";
+      } @else if $last == "warm" or $last == "cool" {
+        $grade: "root";
+      } @else {
+        $grade: $last;
+      }
+      // Otherwise treat as system token
+    } @else {
+      // Determine if it's a vivid variant
+      @if str-index($last, "v") {
+        $variant: "vivid";
+        $grade: str-slice($last, 1, (str-index($last, "v") - 1));
+      } @else {
+        $grade: $last;
+      }
+      // Make sure the grade is a number
+      $grade: if(type-of($grade) == "string", to-number($grade), $grade);
+    }
+    // Collect compound-word families
+    $is-compound-family: false;
+    @if length($split) == 3 or index($split, "warm") or index($split, "cool") {
+      $is-compound-family: true;
+    }
+    @if $is-compound-family {
+      $family: nth($split, 1) + $separator + nth($split, 2);
+    } @else {
+      $family: nth($split, 1);
+    }
   }
-
   @return $family, $grade, $variant;
 }
 
@@ -1130,17 +1182,17 @@ results than expected.
     "white-transparent";
 
   @each $token, $value in $map {
-    $family: nth(decompose($token), 1);
-    $grade: nth(decompose($token), 2);
+    $family: nth(decompose-color-token($token), 1);
+    $grade: nth(decompose-color-token($token), 2);
     @if not $value {
       // empty block
     } @else if not index($exceptions, $family) {
-      $computed: get-color-grade($value);
+      $computed: calculate-grade($value);
       @debug "Checked #{$family}-#{$grade}";
       @if $grade <= 5 {
         // empty block
       } @else if $computed != $grade {
-        @warn "#{$token} (#{$value}) lum: #{luminance($value)} is not in the range #{map-get($system-luminance-grade-ranges, $grade)}";
+        @warn "#{$token} (#{$value}) lum: #{luminance($value)} is not in the range #{map-get($system-color-grades, $grade)}";
       }
     }
   }
@@ -1197,75 +1249,147 @@ string
 
 /*
 ----------------------------------------
-get-color-token-assignment()
+is-system-color-token()
+----------------------------------------
+Return whether a token is a system
+color token
+----------------------------------------
+*/
+
+@function is-system-color-token($token) {
+  @if map-has-key($system-color-shortcodes, $token) {
+    @return true;
+  }
+  @return false;
+}
+
+/*
+----------------------------------------
+is-theme-color-token()
+----------------------------------------
+Return whether a token is a theme
+color token
+----------------------------------------
+*/
+
+@function is-theme-color-token($token) {
+  @if map-has-key($project-color-shortcodes, $token) {
+    @return true;
+  }
+  @return false;
+}
+
+/*
+----------------------------------------
+color-token-assignment()
 ----------------------------------------
 Get the system token equivalent of any
 theme color token
 ----------------------------------------
 */
 
-@function get-color-token-assignment($color-token) {
-  $system-token: $color-token;
-  $grade: null;
+@function color-token-assignment($color-token) {
+  @if is-system-color-token($color-token) {
+    $system-token: $color-token;
+    @return $system-token;
+  }
 
-  @if map-has-key($assignments-theme-color, $color-token) {
-    $system-token: map-get($assignments-theme-color, $system-token);
-  } @else if not map-has-key($system-color-shortcodes, $color-token) {
-    @error "'#{$color-token}' is not a valid color token.";
+  @if not is-theme-color-token($color-token) {
+    @return error-not-token($color-token, "color");
   }
 
-  @return $system-token;
+  $theme-token: $color-token;
+  $theme-token-assignment: map-get($assignments-theme-color, $theme-token);
+  @return $theme-token-assignment;
 }
 
 /*
 ----------------------------------------
-get-color-grade()
+is-color-token()
+----------------------------------------
+Returns whether a given string is a
+USWDS color token.
+----------------------------------------
+*/
+
+@function is-color-token($token) {
+  $is-color-token: if(map-has-key($all-color-shortcodes, $token), true, false);
+  @return $is-color-token;
+}
+
+/*
+----------------------------------------
+calculate-grade()
 ----------------------------------------
 Derive the grade equivalent any color,
 even non-token colors
 ----------------------------------------
 */
 
-@function get-color-grade($color-token) {
+@function calculate-grade($color-token) {
+  $transparency-error: "USWDS can't calculate the grade of a transparent color. Avoid using transparency in theme colors and text.";
   $grade: null;
   $lum: null;
-  $color: false;
+  $custom-color: false;
+  $color-token-assignment: false;
 
+  // Determine if the color is a custom color
   @if type-of($color-token) == "color" {
-    $color: $color-token;
-  } @else if type-of(get-color-token-assignment($color-token)) == "color" {
-    $color: get-color-token-assignment($color-token);
-  }
-
-  @if $color {
-    $lum: luminance($color);
-
-    @each $grade, $range in $system-luminance-grade-ranges {
-      $min: nth($range, 1);
-      $max: nth($range, 2);
-      $next-max: false;
-      @if $grade < 100 {
-        @if $grade == 5 {
-          $next-max: nth(map-get($system-luminance-grade-ranges, 10), 2);
-        } @else {
-          $next-max: nth(
-            map-get($system-luminance-grade-ranges, ($grade + 10)),
-            2
-          );
-        }
-      }
-      @if ($lum >= $min) and ($lum <= $max) {
-        @return $grade;
+    $custom-color: $color-token;
+  } @else {
+    $color-token-assignment: color-token-assignment($color-token);
+    @if type-of($color-token-assignment) == "color" {
+      $custom-color: color-token-assignment($color-token);
+    }
+  }
+
+  // If it's custom, compare its rLum to USWDS grade rLum ranges
+  @if $custom-color {
+    // If the color uses transparency, throw an error
+    @if alpha($custom-color) != 1 {
+      @return uswds-error($transparency-error);
+    }
+    $lum: luminance($custom-color);
+    // Cycle through grades, knowing current AND next grade
+    $our-grades: map-keys($system-color-grades);
+    $grade-count: length($our-grades);
+    @for $i from 1 through $grade-count {
+      $this-grade: nth($our-grades, $i);
+      $this-grade-min: map-deep-get($system-color-grades, $this-grade, "min");
+      $this-grade-max: map-deep-get($system-color-grades, $this-grade, "max");
+      $next-grade: if($i < $grade-count, nth($our-grades, $i + 1), false);
+      $next-grade-min: if(
+        $next-grade,
+        map-deep-get($system-color-grades, $next-grade, "min"),
+        false
+      );
+      // If the lum fits the range, assign a USWDS grade
+      // Otherwise, set a grade midway between two USWDS grades
+      @if ($lum >= $this-grade-min) and ($lum <= $this-grade-max) {
+        @return $this-grade;
       }
-      @if $next-max and ($lum < $min) and ($lum > $next-max) {
-        @return $grade + 4.9;
+      @if ($lum > $this-grade-max) and ($lum < $next-grade-min) {
+        $custom-grade-midpoint: ($this-grade + $next-grade) / 2;
+        $custom-grade: $custom-grade-midpoint;
+        @return $custom-grade;
       }
     }
   }
 
-  $system-token: get-color-token-assignment($color-token);
-  $grade: nth(decompose($system-token), 2);
-  @return $grade;
+  @if not is-color-token($color-token-assignment) {
+    @return error-not-token($color-token-assignment, "color");
+  }
+
+  $system-token: $color-token-assignment;
+  $token-split: decompose-color-token($system-token);
+  $token-family: color-token-family($token-split);
+  // If the color uses transparency, throw an error
+  @if str-index($token-family, "transparent") {
+    @return uswds-error($transparency-error);
+  }
+  // Otherwise, return token grade
+  $token-grade: color-token-grade($token-split);
+  @return $token-grade;
 }
 
 /*
@@ -1328,9 +1452,7 @@ Derive a color from a color shortcode
     }
   }
 
-  @error '`#{$value}` is not a valid USWDS color token. '
-      + 'See designsystem.digital.gov/design-tokens/color '
-      + 'for more information.';
+  @return error-not-token($value, "color");
 }
 
 /*
@@ -1346,7 +1468,7 @@ Derive a color from a color triplet:
 //
 // [family]
 // ex: color('primary')
-//     - the default in a theme palette family
+//     - the root in a theme palette family
 //
 // [family], [grade]
 // ex: color('red', 50)
@@ -1402,9 +1524,9 @@ Derive a color from a color triplet:
     @return get-system-color($color-family, $color-grade, $color-variant);
   }
 
-  // non-number grades are associated with non-default theme colors
+  // non-number grades are associated with non-root theme colors
   // ex: ('base', 'darker')
-  // default theme colors have no grade
+  // root theme colors have no grade
   // ex: ('base')
   @if map-has-key($all-project-colors, $color-family) {
     @if not
@@ -1415,8 +1537,7 @@ Derive a color from a color triplet:
         + '#{map-keys(map-get($all-project-colors, $color-family))}';
     }
   } @else {
-    @error '`#{$color-family}` is not a valid theme family token. '
-      + 'Valid family tokens: #{map-keys($all-project-colors)}';
+    @return error-not-token($color-family, "theme family", $all-project-colors);
   }
   @return map-deep-get($all-project-colors, $color-family, $color-grade);
 }
@@ -1438,9 +1559,7 @@ the desired final units (currently rem)
   );
 
   @if not map-has-key($project-spacing-standard, $converted) {
-    @error '`#{$value}` is not a valid spacing unit token. '
-      + 'Valid spacing unit tokens: '
-      + '#{map-keys($project-spacing-standard)}';
+    @return error-not-token($value, "spacing unit", $project-spacing-standard);
   }
 
   @return map-get($project-spacing-standard, $converted);
@@ -1489,8 +1608,7 @@ border-radii
   @if map-has-key($all-border-radius, $value) {
     @return map-get($all-border-radius, $value);
   } @else {
-    @error '`#{$value}` is not a valid border radius token. '
-      + 'Valid tokens: #{map-keys($all-border-radius)}';
+    @return error-not-token($value, "border radius", $all-border-radius);
   }
 }
 
@@ -1650,12 +1768,10 @@ Get type scale value from a [family] and
   $our-scale: smart-quote($scale);
 
   @if not map-has-key($project-cap-heights, $our-family) {
-    @error '#{$our-family} is not a valid font family token. '
-      + 'Valid tokens: #{map-keys($project-cap-heights)}';
+    @return error-not-token($our-family, "font family", $project-cap-heights);
   }
   @if not map-get($all-type-scale, $our-scale) {
-    @error '`#{$our-scale}` is not a valid font scale token. '
-      + 'Valid token: #{map-keys($all-type-scale)}';
+    @return error-not-token($our-scale, "font scale", $all-type-scale);
   }
 
   $this-cap: map-get($project-cap-heights, $our-family);
@@ -1698,257 +1814,553 @@ system z-index
   @return z-index($value);
 }
 
-@function get-token-from-bg(
-  $bg-color,
-  $preferred-text-color: "white",
-  $fallback-text-color: "ink",
-  $wcag-target: "AA"
-) {
-  $magic-numbers: (
-    "AA": 50,
-    "AAA": 70,
-    "AA-large": 40,
+/*
+----------------------------------------
+magic-number()
+----------------------------------------
+Returns the magic number of two color
+grades. Takes numbers or color tokens.
+
+magic-number(50, 10)
+return: 40
+
+magic-number("red-50", "red-10")
+return: 40
+----------------------------------------
+*/
+
+@function magic-number($grade-1, $grade-2) {
+  $grade-1: if(
+    type-of($grade-1) == "number",
+    $grade-1,
+    calculate-grade($grade-1)
+  );
+  $grade-2: if(
+    type-of($grade-2) == "number",
+    $grade-2,
+    calculate-grade($grade-2)
   );
-  $target-magic-number: map-get($magic-numbers, $wcag-target);
-  $grade-bg: get-color-grade($bg-color);
-  $grade-preferred: get-color-grade($preferred-text-color);
-  $magic-num-preferred: abs($grade-bg - $grade-preferred);
-  $color: false;
+  $magic-number: abs($grade-1 - $grade-2);
+  @return $magic-number;
+}
 
-  //@debug "Background grade: #{$grade-bg} | Preferred text grade: #{$grade-preferred} | Magic number: #{$magic-num-preferred} | Target: #{$target-magic-number}";
+/*
+----------------------------------------
+get-default()
+----------------------------------------
+Returns the default value from a map
+of project defaults
 
-  @if $magic-num-preferred >= $target-magic-number {
-    $color: $preferred-text-color;
-  } @else {
-    $grade-fallback: get-color-grade($fallback-text-color);
-    $magic-num-fallback: abs($grade-bg - $grade-fallback);
-    $color: $fallback-text-color;
-  }
+get-default("bg-color")
+> $theme-body-background-color
+----------------------------------------
+*/
+
+@function get-default($var) {
+  $value: map-get($project-defaults, $var);
+  @return $value;
+}
+
+/*
+----------------------------------------
+get-color-token-from-bg()
+----------------------------------------
+Returns an accessible foreground color
+token, given a background, preferred
+color, fallback color, and WCAG target
 
-  @if not $color {
-    @error "Neither '#{$preferred-text-color}' nor '#{$fallback-text-color}' have #{$wcag-target} contrast on a '#{$bg-color}' background.";
+returns: color-token
+
+get-color-token-from-bg(
+  "black",
+  "red-60",
+  "red-10",
+  "AA")
+> "red-10"
+----------------------------------------
+*/
+
+@function get-color-token-from-bg(
+  $bg-color: "default",
+  $preferred-text-token: "default",
+  $fallback-text-token: "default",
+  $wcag-target: "AA",
+  $context: false,
+  $for: false
+) {
+  $for-text: if($for, "#{$for} ", "");
+  $context-text: if($context, "[#{$context}] ", "");
+  // Set defaults
+  @if $bg-color == "default" {
+    $bg-color: get-default("bg-color");
+  }
+  @if $preferred-text-token == "default" {
+    $preferred-text-token: get-default("preferred-text-token");
+  }
+  @if $fallback-text-token == "default" {
+    $fallback-text-token: get-default("fallback-text-token");
+  }
+  $target-magic-number: map-get($system-wcag-magic-numbers, $wcag-target);
+  $bg-grade: calculate-grade($bg-color);
+  $our-color-tokens: ($preferred-text-token, $fallback-text-token);
+  $accessible-text-token: false;
+  $accessible-text-grade: false;
+  // Get the text color token
+  // Check both text tokens.
+  // Accept a token if it has specified accessible contrast.
+  $best-token: false;
+  $best-magic-number: 0;
+  @each $token in $our-color-tokens {
+    @if not $accessible-text-token {
+      $token-grade: calculate-grade($token);
+      $this-magic-number: magic-number($token-grade, $bg-grade);
+      @if $this-magic-number > $best-magic-number {
+        $best-magic-number: $this-magic-number;
+        $best-token: $token;
+      }
+      @if is-accessible-magic-number($token-grade, $bg-grade, $wcag-target) {
+        $accessible-text-token: $token;
+        $accessible-text-grade: $token-grade;
+      }
+    }
+  }
+  // If neither is accessible,
+  // warn the user and use the Preferred token
+  @if not $accessible-text-token {
+    $accessible-text-token: $best-token;
+    @if $theme-show-compile-warnings {
+      @warn "#{$context-text}Neither the specified preferred #{$for-text}color token (`#{$preferred-text-token}`) nor the fallback #{$for-text}color token (`#{$fallback-text-token}`) have #{$wcag-target} contrast on a `#{$bg-color}` background. Using `#{$best-token}`. Please check your source code and project settings.";
+    }
   }
 
-  @return $color;
+  @return $accessible-text-token;
 }
 
-@function get-color-from-bg(
-  $bg-color,
-  $preferred-text-color: "white",
-  $fallback-text-color: "ink",
-  $wcag-target: "AA"
+/*
+----------------------------------------
+get-link-tokens-from-bg()
+----------------------------------------
+Get accessible link colors for a given
+background color
+
+returns: link-token, hover-token
+
+get-link-tokens-from-bg(
+  "black",
+  "red-60",
+  "red-10",
+  "AA")
+> "red-10", "red-5"
+
+get-link-tokens-from-bg(
+  "black",
+  "red-60v",
+  "red-10v",
+  "AA-large")
+> "red-60v", "red-50v"
+
+get-link-tokens-from-bg(
+  "black",
+  "red-5v",
+  "red-60v",
+  "AA")
+> "red-5v", "white"
+
+get-link-tokens-from-bg(
+  "black",
+  "white",
+  "red-60v",
+  "AA")
+> "white", "white"
+----------------------------------------
+*/
+
+@function get-link-tokens-from-bg(
+  $bg-color: "default",
+  $preferred-link-token: "default",
+  $fallback-link-token: "default",
+  $wcag-target: "AA",
+  $context: false
 ) {
-  $color: get-token-from-bg(
+  $context-text: if($context, "[#{$context}] ", "");
+  $is-default: false;
+  $is-default-preferred: false;
+  $is-default-fallback: false;
+  $default-reverse: false;
+  $default-standard: false;
+  @if $bg-color == "default" {
+    $bg-color: get-default("bg-color");
+  }
+  @if $preferred-link-token == "default" {
+    $preferred-link-token: get-default("preferred-link-token");
+    $default-reverse: true;
+  }
+  @if $fallback-link-token == "default" {
+    $fallback-link-token: get-default("fallback-link-token");
+    $standard-reverse: true;
+  }
+  $bg-grade: calculate-grade($bg-color);
+  $preferred-hover-token: false;
+  $default-hover-token: false;
+  $accessible-hover-token: false;
+  $accessible-link-token: get-color-token-from-bg(
     $bg-color,
-    $preferred-text-color,
-    $fallback-text-color,
-    $wcag-target
+    $preferred-link-token,
+    $fallback-link-token,
+    $wcag-target,
+    $context,
+    $for: "link"
   );
-  @return color($color);
+  $accessible-link-grade: calculate-grade($accessible-link-token);
+  // Get the hover color token
+  // If link is lighter than bg set $is-reverse to true
+  $is-reverse: if($accessible-link-grade < $bg-grade, true, false);
+  // If using defaults, set the default hover
+  // $link-kind is used for error messaging
+  $link-kind: false;
+  @if $is-reverse {
+    @if $default-reverse {
+      $default-hover-token: $theme-link-reverse-hover-color;
+      $link-kind: "default reverse";
+    }
+  } @else if $default-standard {
+    $default-hover-token: $theme-link-hover-color;
+    $link-kind: "default";
+  }
+  @if $default-hover-token {
+    $default-hover-grade: calculate-grade($default-hover-token);
+    @if is-accessible-magic-number(
+      $default-hover-grade,
+      $bg-grade,
+      $wcag-target
+    )
+    {
+      $accessible-hover-token: $default-hover-token;
+    }
+    @if not $accessible-hover-token and $theme-show-compile-warnings {
+      @warn "#{$context-text}The #{$link-kind} link hover (`#{$default-hover-token}`) does not have #{$wcag-target} contrast on a #{$bg-color} background. Please update your project settings.";
+    }
+  }
+  @if not $accessible-hover-token {
+    $direction: if($is-reverse, "lighter", "darker");
+    $hover-token: next-token($accessible-link-token, $direction);
+    // Use the next token, if it is valid
+    @if $hover-token {
+      $accessible-hover-token: $hover-token;
+      // Otherwise use the token itself as hover, and warn.
+    } @else {
+      $accessible-hover-token: $accessible-link-token;
+      @if $theme-show-compile-warnings {
+        @warn "#{$context-text}A `#{$accessible-hover-token}` link does not have #{$direction} hover available. Hover set to link color.";
+      }
+    }
+  }
+  @return $accessible-link-token, $accessible-hover-token;
 }
 
-@function get-link-tokens-from-bg(
-  $bg-color,
-  $preferred-link-color: $theme-link-color,
-  $fallback-link-color: $theme-link-reverse-color,
-  $wcag-target: "AA"
-) {
-  $magic-numbers: (
-    "AA": 50,
-    "AAA": 70,
-    "AA-large": 40,
-  );
-  $grade-step: 10;
-  $found: false;
-  $decomposed: false;
+/*
+----------------------------------------
+color-token-type()
+----------------------------------------
+Returns the type of a color token.
+
+Returns: "system" | "theme"
+----------------------------------------
+*/
 
-  @if $preferred-link-color == default {
-    $preferred-link-color: $theme-link-color;
+@function color-token-type($token) {
+  $type: if(is-system-color-token($token), "system", false);
+  @if not $type {
+    $type: if(is-theme-color-token($token), "theme", false);
+  }
+  @if not $type {
+    @return error-not-token($token, "color");
   }
+  @return $type;
+}
 
-  $target-magic-number: map-get($magic-numbers, $wcag-target);
-  $bg-grade: get-color-grade($bg-color);
-  $our-color-tokens: ($preferred-link-color, $fallback-link-color);
+/*
+----------------------------------------
+color-token-family()
+----------------------------------------
+Returns the family of a color token.
 
-  $link-token: false;
-  $hover-token: false;
+Returns: color-family
 
-  @each $color-token in $our-color-tokens {
-    //@debug "color token: " + $color-token;
-    // If the color token is a custom color, set a $custom flag
-    $custom: if(
-      type-of(map-get($assignments-theme-color, $color-token)) == "color",
-      true,
-      false
-    );
+color-token-family("accent-warm-vivid")
+> "accent-warm"
 
-    // Only get a link color if one has not yet been found
-    @if not $found {
-      $link-grade-token: get-color-grade($color-token);
-      $link-grade: if($link-grade-token < 10, 0, $link-grade-token);
-      $link-magic-number: abs($bg-grade - $link-grade);
-      $token-darker: false;
-      $token-lighter: false;
-      $link-family: false;
-      $link-vivid: false;
-      $hover-grade: false;
-      $hover-vivid: false;
-
-      // If the link color is custom, output theme tokens, not system tokens
-      @if $custom {
-        //@debug "uses custom color.";
-        $custom-token: $color-token;
-        $custom-token-lighter: false;
-        $custom-token-darker: false;
-        $custom-split: str-split($custom-token, "-");
-        $custom-grade: false;
-        $custom-grade-lighter: false;
-        $custom-grade-darker: false;
-        //@debug "custom split:" + $custom-split;
-
-        // set family as the first string in the split
-        $custom-family: nth($custom-split, 1);
-
-        // ignore vivid in token calculations, treat as default
-        @if index($custom-split, "vivid") {
-          $custom-split: remove($custom-split, "vivid");
-        }
-
-        // set family and grade for "accent" families, since their family includes the split character
-        @if $custom-family == "accent" {
-          $custom-family: $custom-family + "-" + nth($custom-split, 2);
-          $custom-grade: if(
-            length($custom-split) == 3,
-            nth($custom-split, 3),
-            "default"
-          );
-        } @else {
-          $custom-grade: if(
-            length($custom-split) == 2,
-            nth($custom-split, 2),
-            "default"
-          );
-        }
-
-        //@debug "custom family: " + $custom-family;
-        //@debug "custom grade: " + $custom-grade;
-
-        $custom-family-lighter: $custom-family;
-        $custom-family-darker: $custom-family;
-        $custom-grade-index: index($uswds-color-theme-grades, $custom-grade);
-
-        // If it's the lightest grade, use "white" for the lighter family
-        @if $custom-grade-index == 1 {
-          $custom-family-lighter: "white";
-        } @else {
-          $custom-grade-lighter: nth(
-            $uswds-color-theme-grades,
-            ($custom-grade-index - 1)
-          );
-        }
-        //@debug "lighter grade: " + $custom-grade-lighter;
-        // If it's the darkest grade, use "black" for the lighter family
-        @if $custom-grade-index == length($uswds-color-theme-grades) {
-          $custom-family-darker: "black";
-        } @else {
-          $custom-grade-darker: nth(
-            $uswds-color-theme-grades,
-            ($custom-grade-index + 1)
-          );
-        }
-        //@debug "darker grade: " + $custom-grade-darker;
-
-        // If any calculated grade is "default", don't output the grade
-        $custom-grade-darker: if(
-          $custom-grade-darker == "default",
-          false,
-          $custom-grade-darker
-        );
-        $custom-grade-lighter: if(
-          $custom-grade-lighter == "default",
-          false,
-          $custom-grade-lighter
-        );
-
-        // Build the custom lighter and darker tokens
-        $token-darker: if(
-          $custom-grade-darker,
-          $custom-family + "-" + $custom-grade-darker,
-          $custom-family-darker
-        );
-        $token-lighter: if(
-          $custom-grade-lighter,
-          $custom-family + "-" + $custom-grade-lighter,
-          $custom-family-lighter
-        );
-      } @else {
-        //@debug "not custom";
-        $decomposed: decompose($color-token);
-      }
+color-token-family("red-50v")
+> "red"
 
-      @if $link-grade == 0 {
-        @warn 'Tokens with grades less than 10 (including "white") aren\'t valid link color tokens, since they have no lighter hover states.';
-      } @else if $link-grade == 100 {
-        @warn '"black" isn\'t a valid link color token, since it has no darker hover state.';
-      }
+color-token-variant(("red", 50, "vivid"))
+> "red"
+----------------------------------------
+*/
+
+@function color-token-family($color-token) {
+  $split: if(
+    type-of($color-token) == "list",
+    $color-token,
+    decompose-color-token($color-token)
+  );
+  $family: nth($split, 1);
+  @return $family;
+}
+
+/*
+----------------------------------------
+color-token-grade()
+----------------------------------------
+Returns the grade of a USWDS color token.
+
+Returns: color-grade
+
+color-token-grade("accent-warm")
+> "root"
+
+color-token-grade("accent-warm-vivid")
+> "root"
+
+color-token-grade("accent-warm-darker")
+> "darker"
+
+color-token-grade("red-50v")
+> 50
+
+color-token-variant(("red", 50, "vivid"))
+> 50
+----------------------------------------
+*/
+
+@function color-token-grade($color-token) {
+  $split: if(
+    type-of($color-token) == "list",
+    $color-token,
+    decompose-color-token($color-token)
+  );
+  $grade: nth($split, 2);
+  @return $grade;
+}
+
+/*
+----------------------------------------
+color-token-variant()
+----------------------------------------
+Returns the variant of color token.
+
+Returns: "vivid" | false
+
+color-token-variant("accent-warm")
+> false
+
+color-token-variant("accent-warm-vivid")
+> "vivid"
+
+color-token-variant("red-50v")
+> "vivid"
+
+color-token-variant(("red", 50, "vivid"))
+> "vivid"
+----------------------------------------
+*/
 
-      // Check that link meets contrast target
-      @else if $link-magic-number >= $target-magic-number {
-        $found: true;
-        // Calculate additional link properties
-
-        $link-token: $color-token;
-        @if not $custom {
-          $link-family: nth($decomposed, 1);
-          //@debug "link family: " + $link-family;
-          $link-vivid: "";
-          @if nth($decomposed, 3) {
-            $link-vivid: "v";
-          }
-        }
-
-        // If link is darker than bg, use darker hover
-        // Exclude black as it has no darker hover
-        @if ($link-grade > $bg-grade) and ($link-grade != 100) {
-          //@debug "Link is darker than background";
-          @if $token-darker {
-            //@debug "Getting darker token...";
-            $hover-token: $token-darker;
-          } @else {
-            $hover-grade: $link-grade + $grade-step;
-            $hover-vivid: if($hover-grade == 90, "", $link-vivid);
-            $hover-token: if(
-              $hover-grade == 100,
-              "black",
-              #{$link-family}-#{$hover-grade}#{$hover-vivid}
-            );
-          }
-        }
-
-        // If link is lighter than bg, use lighter hover
-        // Exclude white equivalents as they have no lighter hover
-        @else if ($link-grade != 0) and ($link-grade != 100) {
-          //@debug "Link is lighter than background";
-          @if $token-lighter {
-            //@debug "Getting lighter token...";
-            $hover-token: $token-lighter;
-          } @else {
-            $hover-grade: $link-grade - $grade-step;
-            $hover-token: if(
-              $hover-grade == 0,
-              "white",
-              #{$link-family}-#{$hover-grade}#{$link-vivid}
-            );
-          }
-        }
+@function color-token-variant($color-token) {
+  $split: if(
+    type-of($color-token) == "list",
+    $color-token,
+    decompose-color-token($color-token)
+  );
+  $variant: nth($split, 3);
+  @return $variant;
+}
+
+/*
+----------------------------------------
+next-token()
+----------------------------------------
+Returns next "darker" or "lighter" color
+token of the same token type and variant.
+
+Returns: color-token | false
+
+next-token("accent-warm", "lighter")
+> "accent-warm-light"
+
+next-token("gray-10", "lighter")
+> "gray-5"
+
+next-token("gray-5", "lighter")
+> "white"
+
+next-token("white", "lighter")
+> false
+
+next-token("red-50v", "darker")
+> "red-60v"
+
+next-token("red-50", "darker")
+> "red-60"
+
+next-token("red-80v", "darker")
+> "red-90"
+
+next-token("red-90", "darker")
+> "black"
+
+next-token("white", "darker")
+> "gray-5"
+
+next-token("black", "lighter")
+> "gray-90"
+----------------------------------------
+*/
+
+@function next-token($token, $direction) {
+  $next-token: false;
+  $type: color-token-type($token);
+  $token-split: decompose-color-token($token);
+  // 1. System case
+  @if $type == "system" {
+    // transparent tokens return don't have a next token
+    @if $token == "transparent" {
+      @return false;
+    }
+    // black and white tokens use the gray family for next
+    $current-family: if(
+      $token == "white" or $token == "black",
+      "gray",
+      color-token-family($token-split)
+    );
+    // black- and white-transparent tokens don't have a next
+    @if str-index($current-family, "-transparent") {
+      @return false;
+    }
+    $current-grade: color-token-grade($token-split);
+    // Nothing can be darker than black or lighter than white
+    @if $direction == "darker" and $current-grade == 100 {
+      @return false;
+    }
+    @if $direction == "lighter" and $current-grade == 0 {
+      @return false;
+    }
+    // Grades under 5 should be treated as 5
+    @if $current-grade > 0 and $current-grade < 5 {
+      $current-grade: 5;
+    }
+    $system-grade-list: map-keys($system-color-grades);
+    $current-grade-index: index($system-grade-list, $current-grade);
+    // Note: System grades go from darkest (100) to lightest (0)
+    $next-grade: if(
+      $direction == "darker",
+      nth($system-grade-list, ($current-grade-index - 1)),
+      nth($system-grade-list, ($current-grade-index + 1))
+    );
+    $output-grade: $next-grade;
+    // Keep the same vivid variant as the parent
+    // Note: Grade 90 has no vivid variant
+    @if color-token-variant($token-split) == "vivid" and ($next-grade < 90) {
+      $output-grade: $next-grade + "v";
+    }
+    // Use black and white tokens for grades 100 and 0...
+    @if $next-grade == 100 {
+      $next-token: "black";
+    } @else if $next-grade == 0 {
+      $next-token: "white";
+      // ...Otherwise output token in expected form
+    } @else {
+      $next-token: $current-family + "-" + $output-grade;
+    }
+    // 2. Theme case
+  } @else {
+    $current-grade: color-token-grade($token-split);
+    // Vivid theme token should be considered root for ordering
+    $current-grade: if($current-grade == "vivid", "root", $current-grade);
+    $current-family: color-token-family($token-split);
+    // Ink should be considered base-darkest
+    // TODO: Should it?
+    @if $token == "ink" {
+      $current-family: "base";
+      $current-grade: "darkest";
+    }
+    // Black is darker than darkest
+    @if $direction == "darker" and $current-grade == "darkest" {
+      @return "black";
+    }
+    // White is lighter than lightest
+    @if $direction == "lighter" and $current-grade == "lightest" {
+      @return "white";
+    }
+    $theme-grade-list: map-keys($theme-color-grades);
+    $current-grade-index: index($theme-grade-list, $current-grade);
+    // Note: Theme grades go from `lightest` to `darkest`
+    $next-grade: if(
+      $direction == "darker",
+      nth($theme-grade-list, ($current-grade-index + 1)),
+      nth($theme-grade-list, ($current-grade-index - 1))
+    );
+    // Exclude `root` from token output
+    @if $next-grade == "root" {
+      @return $current-family;
+    } @else {
+      $next-token: $current-family + "-" + $next-grade;
+    }
+    // If the next color is set to false, use black/white instead
+    @if not color-token-assignment($next-token) {
+      @if $direction == "darker" {
+        @return "black";
+      }
+      @if $direction == "lighter" {
+        @return "white";
       }
     }
   }
+  @return $next-token;
+}
 
-  @if not $hover-token {
-    @error 'Neither "#{$preferred-link-color}" nor "#{$fallback-link-color}" can be #{$wcag-target} contrast links and hovers on a "#{$bg-color}" background.';
-  }
+/*
+----------------------------------------
+wcag-magic-number()
+----------------------------------------
+Returns the magic number of a specific
+wcag grade:
+
+"AA"
+"AA-Large"
+"AAA"
+
+wcag-magic-number("AA")
+> 50
+----------------------------------------
+*/
+
+@function wcag-magic-number($wcag-target) {
+  $wcag-magic-number: map-get($system-wcag-magic-numbers, $wcag-target);
+  @return $wcag-magic-number;
+}
+
+/*
+----------------------------------------
+is-accessible-magic-number()
+----------------------------------------
+Returns whether two grades achieve
+specified target color contrast
+
+Returns: true | false
 
-  //@debug "#{$link-token}, #{$hover-token}";
-  @return $link-token, $hover-token;
+is-accessible-magic-number(10, 50, "AA")
+> false
+
+is-accessible-magic-number(10, 60, "AA")
+> true
+----------------------------------------
+*/
+
+@function is-accessible-magic-number($grade-1, $grade-2, $wcag-target) {
+  $target-magic-number: wcag-magic-number($wcag-target);
+  $magic-number: magic-number($grade-1, $grade-2);
+  @if $magic-number >= $target-magic-number {
+    @return true;
+  }
+  @return false;
 }