feat: add link styles

packages/components-css/link-css/src/_mixin.scss

@@ -1,3 +1,79 @@
 @mixin nl-link {
-  // stylelint-disable: block-no-empty
+  --_nl-link-forced-colors-color: linktext;
+
+  color: var(--_nl-link-state-color, var(--nl-link-color, var(--_nl-link-forced-colors-color)));
+  text-decoration-color: var(
+    --_nl-link-state-text-decoration-color,
+    var(--nl-link-text-decoration-color, currentColor)
+  );
+  text-decoration-line: var(--_nl-link-state-text-decoration-line, var(--nl-link-text-decoration-line, underline));
+
+  /* Ensure text is readable even with letters below the baseline and ensure a difference between default or hover and focus state. */
+  text-decoration-skip-ink: all;
+  text-decoration-thickness: max(
+    var(--_nl-link-state-text-decoration-thickness, var(--nl-link-text-decoration-thickness)),
+    1px
+  );
+  text-underline-offset: var(--nl-link-text-underline-offset);
+}
+
+@mixin nl-link--hover {
+  --_nl-link-forced-colors-color: linktext;
+  --_nl-link-state-color: var(--nl-link-hover-color);
+  --_nl-link-state-text-decoration-line: var(--nl-link-hover-text-decoration-line);
+  --_nl-link-state-text-decoration-thickness: var(--nl-link-hover-text-decoration-thickness);
+
+  /* Ensure underline is extra visible between default or hover and focus states. */
+  text-decoration-skip-ink: none;
+}
+
+@mixin nl-link--active {
+  --_nl-link-forced-colors-color: activetext;
+  --_nl-link-state-color: var(--nl-link-active-color);
+}
+
+@mixin nl-link--placeholder {
+  --_nl-link-forced-colors-color: GrayText;
+  --_nl-link-state-color: var(--nl-link-placeholder-color);
+
+  cursor: var(--nl-link-placeholder-cursor, not-allowed);
+  font-weight: var(--nl-link-placeholder-font-weight);
+
+  /* Ensure visible difference between links and placeholder links */
+  text-decoration-line: none;
+}
+
+@mixin nl-link--current {
+  cursor: var(--nl-link-current-cursor, normal);
+  font-weight: var(--nl-link-current-font-weight);
+}
+
+/**
+ * Simulate forced-colors mode.
+ */
+@mixin nl-link--forced-colors {
+  /* Some others choose `transparent` to trigger `currentColor` for `inverse-outline-color`,
+   * however this doesn't guarantee significant contrast between `outline-color` and `inverse-outline-color`.
+   * That's why we use `Highlight` vs `HighlightText`.
+   */
+  --nl-focus-outline-color: Highlight;
+  --nl-focus-inverse-outline-color: HighlightText;
+  --nl-link-color: linktext;
+  --nl-link-hover-color: linktext;
+  --nl-link-focus-color: linktext;
+  --nl-link-active-color: activetext;
+  --nl-link-placeholder-color: GrayText;
+}
+
+/**
+ * Link around inline-block, inline-flex and inline-grid elements like image or badge.
+ * Changing the `display: inline` to `inline-block` for the link ensures the focus outline is rendered around the entire box in all browsers.
+ */
+@mixin nl-link--inline-box-content {
+  color: unset;
+  display: inline-block;
+  text-decoration-line: unset;
+  text-decoration-skip-ink: unset;
+  text-decoration-thickness: unset;
+  text-underline-offset: unset;
 }

packages/components-css/link-css/src/html/_mixin.scss

@@ -1,7 +1,31 @@
 @use "../mixin";
 
-@mixin a {
-  a {
+@mixin nl-link--html-a {
+  /* link styles should only apply to links with `href`, not on disabled links */
+  a:any-link {
     @include mixin.nl-link;
   }
+
+  /* 
+ * IMPORTANT: states rely heavily on the CSS order
+ * Keep the order as follows
+ * 1. :visited (not used for privacy reasons)
+ * 2. :hover
+ * 3. :active
+ * 4. :focus (not used for user friendliness)
+ * 5. :focus-visible (todo)
+ */
+
+  a:any-link:hover {
+    @include mixin.nl-link--hover;
+  }
+
+  a:any-link:active {
+    @include mixin.nl-link--active;
+  }
+
+  /* placeholder styles as fallback for all links without `href` attribute when aria-disabled is used properly */
+  a[role="link" i][aria-disabled="true" i] {
+    @include mixin.nl-link--placeholder;
+  }
 }

packages/components-css/link-css/src/html/link.scss

@@ -1,3 +1,3 @@
 @use "./mixin";
 
-@include mixin.a;
+@include mixin.nl-link--html-a;

packages/components-css/link-css/src/link.scss

@@ -1,5 +1,37 @@
 @use "./mixin";
 
-.nl-link {
+/* link styles should only apply to links with `href`, not on disabled links */
+.nl-link:any-link {
   @include mixin.nl-link;
 }
+
+/* 
+ * IMPORTANT: states rely heavily on the CSS order
+ * Keep the order as follows
+ * 1. :visited (not used for privacy reasons)
+ * 2. :hover
+ * 3. :active
+ * 4. :focus (not used for user friendliness)
+ * 5. :focus-visible (todo)
+ */
+
+.nl-link:any-link:hover {
+  @include mixin.nl-link--hover;
+}
+
+.nl-link:any-link:active {
+  @include mixin.nl-link--active;
+}
+
+.nl-link--current:any-link {
+  @include mixin.nl-link--current;
+}
+
+.nl-link--inline-box-content:any-link {
+  @include mixin.nl-link--inline-box-content;
+}
+
+/* placeholder styles can be used as fallback for all links without `href` attribute */
+.nl-link--placeholder {
+  @include mixin.nl-link--placeholder;
+}

packages/components-css/link-css/src/test.scss

@@ -0,0 +1,17 @@
+@use "./mixin";
+
+/* 
+ * Used for stories in Storybook
+ */
+
+.nl-link--hover {
+  @include mixin.nl-link--hover;
+}
+
+.nl-link--active {
+  @include mixin.nl-link--active;
+}
+
+.nl-link--current {
+  @include mixin.nl-link--current;
+}

packages/tokens/link-tokens/tokens.json

@@ -8,20 +8,6 @@
             "nl.nldesignsystem.figma-implementation": true
           },
           "$type": "color"
-        },
-        "text-decoration": {
-          "$extensions": {
-            "nl.nldesignsystem.css-property-syntax": ["inherit", "none", "underline"],
-            "nl.nldesignsystem.figma-implementation": true
-          },
-          "$type": "textDecoration"
-        },
-        "text-decoration-thickness": {
-          "$extensions": {
-            "nl.nldesignsystem.css-property-syntax": "<length>",
-            "nl.nldesignsystem.figma-implementation": false
-          },
-          "$type": "other"
         }
       },
       "color": {
@@ -31,22 +17,31 @@
         },
         "$type": "color"
       },
-      "focus-visible": {
-        "background-color": {
+      "current": {
+        "cursor": {
           "$extensions": {
-            "nl.nldesignsystem.css-property-syntax": "<color>",
-            "nl.nldesignsystem.figma-implementation": true
+            "nl.nldesignsystem.css-property-syntax": ["<url>", "pointer", "*"],
+            "nl.nldesignsystem.figma-implementation": false
           },
-          "$type": "color"
+          "$type": "other"
         },
+        "font-weight": {
+          "$extensions": {
+            "nl.nldesignsystem.css-property-syntax": "<number>",
+            "nl.nldesignsystem.figma-implementation": false
+          },
+          "$type": "fontWeights"
+        }
+      },
+      "hover": {
         "color": {
           "$extensions": {
             "nl.nldesignsystem.css-property-syntax": "<color>",
             "nl.nldesignsystem.figma-implementation": true
           },
           "$type": "color"
         },
-        "text-decoration": {
+        "text-decoration-line": {
           "$extensions": {
             "nl.nldesignsystem.css-property-syntax": ["inherit", "none", "underline"],
             "nl.nldesignsystem.figma-implementation": true
@@ -61,30 +56,30 @@
           "$type": "other"
         }
       },
-      "hover": {
+      "placeholder": {
         "color": {
           "$extensions": {
             "nl.nldesignsystem.css-property-syntax": "<color>",
             "nl.nldesignsystem.figma-implementation": true
           },
           "$type": "color"
         },
-        "text-decoration": {
+        "cursor": {
           "$extensions": {
-            "nl.nldesignsystem.css-property-syntax": ["inherit", "none", "underline"],
-            "nl.nldesignsystem.figma-implementation": true
+            "nl.nldesignsystem.css-property-syntax": ["<url>", "pointer", "*"],
+            "nl.nldesignsystem.figma-implementation": false
           },
-          "$type": "textDecoration"
+          "$type": "other"
         },
-        "text-decoration-thickness": {
+        "font-weight": {
           "$extensions": {
-            "nl.nldesignsystem.css-property-syntax": "<length>",
+            "nl.nldesignsystem.css-property-syntax": "<number>",
             "nl.nldesignsystem.figma-implementation": false
           },
-          "$type": "other"
+          "$type": "fontWeights"
         }
       },
-      "text-decoration": {
+      "text-decoration-line": {
         "$extensions": {
           "nl.nldesignsystem.css-property-syntax": ["inherit", "none", "underline"],
           "nl.nldesignsystem.figma-implementation": true