From 2e97821c3d52bb8bc08b918766949bf6a2889f1b Mon Sep 17 00:00:00 2001
From: Robbert Broersma <git@robbertbroersma.nl>
Date: Wed, 18 Sep 2024 14:17:28 +0200
Subject: [PATCH] style: move the Link `text-underline` effect from `focus` to
 `focus-visible`

---
 .changeset/famous-seahorses-smell.md          | 15 ++++++++++
 components/link/src/_mixin.scss               | 17 +++++++++--
 components/link/src/tokens.json               | 28 +++++++++++++++++++
 .../src/component/utrecht/link.tokens.json    |  4 ++-
 4 files changed, 61 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/famous-seahorses-smell.md

diff --git a/.changeset/famous-seahorses-smell.md b/.changeset/famous-seahorses-smell.md
new file mode 100644
index 00000000000..3921b616ffa
--- /dev/null
+++ b/.changeset/famous-seahorses-smell.md
@@ -0,0 +1,15 @@
+---
+"@utrecht/link-css": minor
+---
+
+Move the Link `text-underline` effect from `focus` to `focus-visible`. The goal is to not change the `text-underline` appearance during the flow of moving the mouse over the link (`:hover`) and then clicking the link (`:focus` + `:active`).
+
+Add new `focus-visible` tokens for Link:
+
+- `utrecht.link.focus-visible.text-decoration`
+- `utrecht.link.focus-visible.text-decoration-thickness`
+
+The following tokens are now deprecated:
+
+- `utrecht.link.focus.text-decoration`
+- `utrecht.link.focus.text-decoration-thickness`
diff --git a/components/link/src/_mixin.scss b/components/link/src/_mixin.scss
index 4d07781a385..5f863dc3ea7 100644
--- a/components/link/src/_mixin.scss
+++ b/components/link/src/_mixin.scss
@@ -112,8 +112,6 @@ however browsers don't seem to have implemented great looking supixel tweening y
 
 @mixin utrecht-link--focus {
   --_utrecht-link-state-color: var(--utrecht-link-focus-color);
-  --_utrecht-link-state-text-decoration: var(--utrecht-link-focus-text-decoration);
-  --_utrecht-link-state-text-decoration-thickness: var(--utrecht-link-focus-text-decoration-thickness);
 
   background-color: var(--utrecht-link-focus-background-color, transparent);
   text-decoration-skip: none;
@@ -142,6 +140,21 @@ however browsers don't seem to have implemented great looking supixel tweening y
    */
   @include utrecht-focus-visible;
 
+  /*
+   * The following tokens are deprecated, but we keep them for backwards compatibility for now:
+   * 
+   * `--utrecht-link-focus-text-decoration`
+   * `--utrecht-link-focus-text-decoration-thickness`
+   */
+  --_utrecht-link-state-text-decoration: var(
+    --utrecht-link-focus-visible-text-decoration,
+    var(--utrecht-link-focus-text-decoration)
+  );
+  --_utrecht-link-state-text-decoration-thickness: var(
+    --utrecht-link-focus-visible-text-decoration-thickness,
+    var(--utrecht-link-focus-text-decoration-thickness)
+  );
+
   z-index: var(--utrecht-stack-focus-z-index, 1);
 }
 
diff --git a/components/link/src/tokens.json b/components/link/src/tokens.json
index f697f0156e9..78a22545514 100644
--- a/components/link/src/tokens.json
+++ b/components/link/src/tokens.json
@@ -76,6 +76,34 @@
           },
           "type": "color"
         },
+        "text-decoration": {
+          "$extensions": {
+            "nl.nldesignsystem.css.property": {
+              "syntax": ["inherit", "none", "underline"],
+              "inherits": true
+            },
+            "nl.nldesignsystem.fallback": ["utrecht.link.text-decoration"],
+            "nl.nldesignsystem.figma.supports-token": true,
+            "nl.nldesignsystem.deprecated": true,
+            "nl.nldesignsystem.redirect": "utrecht.link.focus-visible.text-decoration"
+          },
+          "type": "textDecoration"
+        },
+        "text-decoration-thickness": {
+          "$extensions": {
+            "nl.nldesignsystem.css.property": {
+              "syntax": "<length>",
+              "inherits": true
+            },
+            "nl.nldesignsystem.fallback": ["utrecht.link.text-decoration-thickness"],
+            "nl.nldesignsystem.figma.supports-token": false,
+            "nl.nldesignsystem.deprecated": true,
+            "nl.nldesignsystem.redirect": "utrecht.link.focus-visible.text-decoration-thickness"
+          },
+          "type": "other"
+        }
+      },
+      "focus-visible": {
         "text-decoration": {
           "$extensions": {
             "nl.nldesignsystem.css.property": {
diff --git a/proprietary/design-tokens/src/component/utrecht/link.tokens.json b/proprietary/design-tokens/src/component/utrecht/link.tokens.json
index c14dcf3b93a..e5c7b206548 100644
--- a/proprietary/design-tokens/src/component/utrecht/link.tokens.json
+++ b/proprietary/design-tokens/src/component/utrecht/link.tokens.json
@@ -12,7 +12,9 @@
         "color": { "value": "{utrecht.link.color}" }
       },
       "focus": {
-        "color": { "value": "{utrecht.color.blue.40}" },
+        "color": { "value": "{utrecht.color.blue.40}" }
+      },
+      "focus-visible": {
         "text-decoration": { "value": "none" }
       },
       "hover": {