@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/link/link.css.js

@@ -1,166 +1,217 @@
 import { css } from "lit";
 
+/**
+ * bd-link.
+ *
+ * The base rule reads --typography-link-default-*, which had fourteen tokens
+ * and no consumer: the component re-spelled every one of them in primitives.
+ * The underline offset was a 2px literal in seven places, on a property the
+ * length rule does not check, so nothing could see it and nothing could change
+ * it in one move.
+ *
+ * Colour comes from the semantic text roles. The default was --color-blue-500,
+ * which is 4.53:1 on white — the step CLAUDE.md names as the one to avoid for
+ * text, and the atom's own bold variant already avoided it.
+ */
 export default css`
   .bd-link {
     display: inline-flex;
     align-items: center;
     gap: var(--spacing-4);
-    color: var(--color-blue-500);
-    text-decoration: none;
     font-family: var(--typography-fontFamily-sans);
-    font-size: var(--typography-fontSize-base);
-    font-weight: var(--typography-fontWeight-normal);
-    line-height: var(--typography-lineHeight-normal);
-    transition: all 0.15s ease-in-out;
+    font-size: var(--typography-link-standalone-fontSize);
+    font-weight: var(--typography-link-default-fontWeight);
+    line-height: var(--typography-link-standalone-lineHeight);
+    color: var(--bd-link-color, var(--color-text-brand));
+    text-decoration: none;
+    text-underline-offset: var(--typography-link-underlineOffset);
     cursor: pointer;
-  }
-
-  /* Primary (default) */
+    /* the properties that actually change, rather than all: a link that
+       animates every property also animates the ones it inherits */
+    transition: color var(--transition-duration-fast) var(--transition-easing-smooth),
+      text-decoration-color var(--transition-duration-fast) var(--transition-easing-smooth);
+  }
+
+  /* ---- inline ------------------------------------------------------------
+     A link in a sentence is that sentence's text, so it takes its type from
+     the sentence. --typography-link-default-* is the role that says so: size,
+     leading, tracking and family are all inherit. Four of those axes had no
+     consumer, because the base rule above reads the standalone role instead --
+     1rem and 1.5 regardless of context -- which is why an inline link measured
+     16px inside a 12px caption and inside a 32px lede alike.
+
+     display returns to inline as well. An inline-flex box does not hug its
+     own text: in a 220px column the same link measured the full 220px where a
+     plain <a> measured 209px, so it does not sit in the line the way a real
+     inline element does. The gap and align-items above go inert with it, which
+     is correct here -- an inline link is a run of text, not a row. */
+  :host([inline]) .bd-link {
+    display: inline;
+    font-size: var(--typography-link-default-fontSize);
+    line-height: var(--typography-link-default-lineHeight);
+    letter-spacing: var(--typography-link-default-letterSpacing);
+    font-family: var(--typography-link-default-fontFamily);
+  }
+
+  /* ---- kinds ------------------------------------------------------------ */
   .bd-link--primary {
-    color: var(--color-blue-500);
+    color: var(--bd-link-color, var(--color-text-brand));
   }
-
   .bd-link--primary:hover {
-    color: var(--color-blue-700);
+    color: var(--color-text-brand-hover);
     text-decoration: underline;
-    text-underline-offset: 2px;
   }
 
-  /* Secondary */
   .bd-link--secondary {
-    color: var(--color-neutral-600);
+    color: var(--bd-link-color, var(--color-text-muted));
   }
-
   .bd-link--secondary:hover {
-    color: var(--color-neutral-800);
+    color: var(--color-text-secondary);
     text-decoration: underline;
-    text-underline-offset: 2px;
-  }
-
-  /* ============================================
-     ACTIVE STATE - FONT WEIGHT 700
-     ============================================ */
-  
-  .bd-link--active {
-    font-weight: 700 !important;
-  }
-
-  /* Poți adăuga și alte stiluri pentru active dacă dorești */
-  .bd-link--active.bd-link--primary {
-    color: var(--color-neutral-900);
-  }
-
-  .bd-link--active.bd-link--secondary {
-    color: var(--color-neutral-900);
-  }
-
-  
-  .bd-link--no-underline:hover,
-  .bd-link--no-underline.bd-link--primary:hover,
-  .bd-link--no-underline.bd-link--secondary:hover,
-  .bd-link--no-underline.bd-link--danger:hover,
-  .bd-link--no-underline.bd-link--bold:hover,
-  .bd-link--no-underline.bd-link--subtle:hover {
-    text-decoration: none !important;
   }
 
-
-
-  .bd-link--no-underline.bd-link--secondary:hover {
-    color: var(--color-neutral-800) !important;
+  .bd-link--subtle {
+    color: var(--bd-link-color, var(--color-text-subtle));
+    text-decoration: none;
   }
-
-  /* Light variant for dark backgrounds */
-  .bd-link--light {
-    color: var(--color-neutral-0);
+  .bd-link--subtle:hover {
+    color: var(--color-text-secondary);
+    text-decoration: underline;
   }
 
-  .bd-link--light:hover {
-    color: var(--color-neutral-0);
+  .bd-link--bold {
+    color: var(--bd-link-color, var(--color-text-brand));
+    /* no role: the bold modifier on a link -- a state or modifier weight, not a text-content
+       type. See button.css.js's .button--bold for the argument. */
+    font-weight: var(--typography-fontWeight-semibold);
     text-decoration: none;
   }
+  .bd-link--bold:hover {
+    color: var(--color-text-brand-hover);
+    text-decoration: underline;
+  }
 
-  /* Danger */
+  /* Red on a link is the error role, not bd-button's accent. The button's red
+     is this system's conversion colour and it deliberately has no danger kind;
+     a link is the opposite case — red text reads as a warning about where the
+     link goes, so it takes --color-text-error and says so. */
   .bd-link--danger {
-    color: var(--color-red-500);
+    color: var(--bd-link-color, var(--color-text-error));
   }
-
   .bd-link--danger:hover {
-    color: var(--color-red-700);
+    color: var(--color-text-error);
     text-decoration: underline;
-    text-underline-offset: 2px;
   }
 
-  /* Subtle */
-  .bd-link--subtle {
-    color: var(--color-neutral-500);
-    text-decoration: none;
+  /* ---- surface ----------------------------------------------------------
+     The same attribute bd-button uses to say the same thing. It replaces the
+     light kind, which described the surface rather than the link and could
+     not be combined with any of the kinds above. */
+  :host([surface="dark"]) .bd-link,
+  :host([surface="dark"]) .bd-link--primary,
+  :host([surface="dark"]) .bd-link--secondary,
+  :host([surface="dark"]) .bd-link--subtle,
+  :host([surface="dark"]) .bd-link--bold {
+    color: var(--color-text-inverse);
   }
 
-  .bd-link--subtle:hover {
-    color: var(--color-neutral-700);
+  /* Colour only. This rule used to carry text-decoration: underline as well,
+     and at (0,4,0) it outweighed .bd-link--no-underline:hover at (0,2,0) --
+     so a link explicitly asking for no underline got one anyway, but only on a
+     dark surface. Measured: dark/primary/no-underline went none -> underline on
+     hover, where the same link on a light surface stayed none.
+
+     The underline is the kinds' business, and every kind already declares it. */
+  :host([surface="dark"]) .bd-link:hover {
+    color: var(--color-text-inverse);
+  }
+
+  /* ---- modifiers --------------------------------------------------------
+     Ordered after the kinds rather than marked !important. Four declarations
+     carried it before, which made the atom unoverridable by a consuming page —
+     the exact failure the cascade-layer token work was done to avoid. */
+  .bd-link--underline {
     text-decoration: underline;
-    text-underline-offset: 2px;
+  }
+  .bd-link--underline:hover {
+    text-decoration-thickness: var(--typography-link-underlineThickness);
   }
 
-  /* Bold */
-  .bd-link--bold {
-    color: var(--color-blue-600);
-    font-weight: var(--typography-fontWeight-semibold);
+  .bd-link--no-underline,
+  .bd-link--no-underline:hover {
     text-decoration: none;
   }
 
-  .bd-link--bold:hover {
-    color: var(--color-blue-800);
-    text-decoration: underline;
-    text-underline-offset: 2px;
+  .bd-link--active {
+    /* no role: a link in its active state -- a state or modifier weight, not a text-content
+       type. See button.css.js's .button--bold for the argument. */
+    font-weight: var(--typography-fontWeight-bold);
+    color: var(--color-text-primary);
   }
 
-  /* Underline modifier */
-  .bd-link--underline {
-    text-decoration: underline;
-    text-underline-offset: 2px;
-  }
+  /* The current item does not move under the pointer.
 
-  .bd-link--underline:hover {
-    text-decoration-thickness: 2px;
+     --active and --primary are both present on a current nav item, and
+     .bd-link--primary:hover at (0,2,0) outweighs .bd-link--active at (0,1,0)
+     -- so without this rule hovering the page you are already on turned it
+     back to the brand ink, which is the one thing that colour is not supposed
+     to mean here. Measured on bd-page-switcher before the wayfinding family
+     review: current + hover reported action/primary-active, the only one of
+     the three that recoloured an item the reader had already arrived at.
+
+     Same specificity as the kind hovers and declared after them, so it wins
+     on order. */
+  .bd-link--active:hover {
+    color: var(--color-text-primary);
   }
 
-  /* Disabled state */
-  .bd-link--disabled {
-    color: var(--color-neutral-400);
+  /* ---- states ----------------------------------------------------------- */
+  .bd-link--disabled,
+  span.bd-link--disabled {
+    color: var(--color-text-disabled);
     cursor: not-allowed;
     text-decoration: none;
     pointer-events: none;
   }
 
-  /* Focus styles */
   .bd-link:focus {
     outline: none;
   }
 
   .bd-link:focus-visible {
-    outline: 2px solid var(--color-blue-300);
-    outline-offset: 2px;
-    border-radius: 2px;
-  }
-
-  /* Ensure disabled span has same display */
-  .bd-link.bd-link--disabled {
-    display: inline-flex;
-    align-items: center;
+    /* the one focus ring — see Foundations/Focus. A two-colour ring whose
+       white inner band keeps it visible on a coloured or dark surface, which a
+       single-colour outline cannot do. */
+    outline: none;
+    box-shadow: var(--focus-outline-primary);
+    border-radius: var(--focus-outline-radius);
   }
 
-  /* Additional specificity for edge cases */
   a.bd-link {
     cursor: pointer;
   }
 
+  /* There is no element-qualified reset here, and that is the point.
+
+     The anchor's underline is already off: .bd-link sets text-decoration none,
+     and an author rule beats the UA stylesheet whatever its specificity. What
+     the old a.bd-link:not(.bd-link--underline) rule added was weight -- (0,2,1)
+     against the (0,2,0) of every .bd-link--<kind>:hover -- so the hover
+     underline each of the five kinds declares lost the cascade and never
+     painted. Measured on light surfaces: primary, secondary, subtle, bold and
+     danger all went none -> none across a hover. On a dark surface the same
+     hover underlined, because that rule is (0,4,0) and outweighed the reset.
+
+     The kinds and the modifiers sort themselves out on class weight alone, in
+     source order: --underline and --no-underline are declared after the kinds,
+     so they still win. */
   span.bd-link {
     cursor: default;
   }
 
-  span.bd-link--disabled {
-    cursor: not-allowed;
+  @media (prefers-reduced-motion: reduce) {
+    .bd-link {
+      transition: none;
+    }
   }
-`;
+`;

package/src/components/link/link.js

@@ -1,39 +1,87 @@
 import { LitElement, html } from "lit";
-import { tokens } from "../../tokens/tokens.js";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
 import linkCSS from "./link.css.js";
+import { fontSize, color } from "../shared/token-scales.js";
+
+/**
+ * The anchor -- or, when disabled, the span -- is exposed as `part="link"`.
+ *
+ * It is the element that carries the ink, the padding and the focus ring, and
+ * until now nothing outside this shadow root could reach it. That is not a
+ * theoretical gap: bd-breadcrumb's mobile layout put a full-width padded pill
+ * on the bd-link HOST, and the anchor inside stayed the width of its own text,
+ * so a 343x40 row offered a 43x24 target -- 7.5% of what it looked like. A
+ * part is the seam for the cases where the box a consumer needs to style and
+ * the box the browser makes focusable have to be the same box.
+ *
+ * It is a seam, not a licence to restyle the atom: reach for a variant first.
+ */
+
+/**
+ * kind values that described something else, mapped onto what they meant so
+ * existing markup keeps working. `light` said "on a dark surface", which is
+ * what the surface attribute says now.
+ */
+const LEGACY_KINDS = { light: "primary" };
+const VARIANTS = ["primary", "secondary", "subtle", "bold", "danger"];
 
 class BdLink extends LitElement {
   static properties = {
     href       : { type: String },
     target     : { type: String },
-    kind       : { type: String,  reflect: true },
+    variant    : { type: String,  reflect: true },
+    /** @deprecated pass `variant`. */
+    kind       : { type: String },
     underline  : { type: Boolean, reflect: true },
     noUnderline: { type: Boolean, attribute: "no-underline" },
     disabled   : { type: Boolean, reflect: true },
     fontSize   : { type: String,  attribute: "font-size" },
+    /* The link is a run of text in a sentence and takes its type from that
+       sentence. Off by default: 62 of the 66 bd-link usages in this package
+       rely on the standalone role's 1rem, so inheriting cannot be the default
+       without repositioning all of them. */
+    inline     : { type: Boolean, reflect: true },
     color      : { type: String },
-    active     : { type: Boolean, reflect: true }
+    active     : { type: Boolean, reflect: true },
+    /* The surface the link sits on, the same attribute bd-button uses. It
+       replaces kind="light", which described the surface rather than the link
+       and so could not be combined with any of the real kinds. */
+    surface    : { type: String,  reflect: true }
   };
 
   constructor() {
     super();
     this.href        = "#";
     this.target      = "_self";
-    this.kind        = "primary";
+    this.variant     = "primary";
+    this.kind        = "";
     this.underline   = false;
     this.noUnderline = false;
     this.disabled    = false;
     this.fontSize    = "";
+    this.inline      = false;
     this.color       = "";
     this.active      = false;
+    this.surface     = "light";
   }
 
-  static styles = [tokens, linkCSS];
+  willUpdate(changed) {
+    if (!changed.has("kind") && !changed.has("variant")) return;
+    if (changed.has("kind") && this.kind) this.variant = this.kind;
+    // light meant "this link is on a dark surface", which the surface
+    // attribute says now
+    if (this.variant === "light") this.surface = "dark";
+    if (LEGACY_KINDS[this.variant]) this.variant = LEGACY_KINDS[this.variant];
+    if (!VARIANTS.includes(this.variant)) this.variant = "primary";
+  }
+
+  static styles = [linkCSS];
 
   get _classes() {
     return [
       "bd-link",
-      `bd-link--${this.kind}`,
+      `bd-link--${this.variant}`,
       this.underline ? "bd-link--underline" : "",
       this.noUnderline ? "bd-link--no-underline" : "",
       this.active ? "bd-link--active" : "",
@@ -41,17 +89,43 @@ class BdLink extends LitElement {
     ].filter(Boolean).join(" ");
   }
 
+  /**
+   * font-size is a type-scale step and color is a semantic role; both are
+   * resolved to token references by shared/token-scales.js, and anything off
+   * the scale is dropped.
+   *
+   * `color` is emitted as --bd-link-color rather than as `color`, and that is
+   * the whole of the fix. A style attribute beats every rule in this
+   * stylesheet, so a link with a colour prop had NO hover, NO active and NO
+   * disabled appearance -- the resting ink won in all four states. Measured on
+   * bd-anchor-nav, which passes color="strong": rest, hover and mouse-down all
+   * reported neutral-900 at weight 400, so the links were inert under the
+   * pointer. Four sites pass the prop today and all four were affected.
+   *
+   * As a custom property it is the *resting* colour instead: the kind rules
+   * below read it through a var() fallback, and the :hover, --active and
+   * --disabled rules keep plain `color` declarations, so they win the way they
+   * were always meant to.
+   *
+   * font-size is not emitted at all when inline is set, because the two ask
+   * contradictory questions: inline means the sentence decides the size. It is
+   * dropped here rather than left to lose a specificity argument in the
+   * stylesheet -- this is a style attribute, so it would beat
+   * :host([inline]) and pull the link back out of the line box that mode
+   * exists to keep it in.
+   */
   get _inlineStyle() {
-    const styles = [];
-    if (this.fontSize) styles.push(`font-size: ${this.fontSize}`);
-    if (this.color)    styles.push(`color: ${this.color}`);
-    return styles.join("; ");
+    return [
+      ["font-size", this.inline ? "" : fontSize(this.fontSize)],
+      ["--bd-link-color", color(this.color)]
+    ].filter(([, v]) => v).map(([prop, v]) => `${prop}: ${v}`)
+      .join("; ");
   }
 
   render() {
     if (this.disabled) {
       return html`
-        <span class="${this._classes}" style="${this._inlineStyle}">
+        <span part="link" class="${this._classes}" style="${this._inlineStyle}">
           <slot></slot>
         </span>
       `;
@@ -59,6 +133,7 @@ class BdLink extends LitElement {
 
     return html`
       <a
+        part="link"
         class="${this._classes}"
         style="${this._inlineStyle}"
         href="${this.href}"