@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/tooltip/tooltip.stories.js

@@ -0,0 +1,161 @@
+import { html } from 'lit';
+import '../badge/badge.js';
+import './tooltip.js';
+import '../button/button.js';
+
+export default {
+  title     : 'Atoms/Tooltip',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdTooltip** shows a short explanatory bubble when the wrapped content is
+hovered or focused.
+
+### Usage
+\`\`\`html
+<bd-tooltip text="Blocks trackers across every browser">
+  <bd-button variant="ghost">What is this?</bd-button>
+</bd-tooltip>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`text\` | the tooltip content | \`''\` |
+
+The trigger goes in the default slot.
+
+### What it is for, and what it is not
+A tooltip supplements — it must never be the only place information appears.
+Anything required to complete a task belongs in visible text or in
+\`<bd-help-text>\`, because a tooltip is unreachable on touch, invisible in
+print, and gone the moment the pointer leaves.
+
+### Accessibility caveats
+The bubble carries \`role="tooltip"\`, but this element does **not** wire up
+\`aria-describedby\` between the trigger and the bubble. A screen reader
+therefore has no link from the control to its description, so the tooltip text
+may never be announced.
+
+Until that is connected, describe the trigger directly as well:
+
+\`\`\`html
+<bd-tooltip text="Blocks trackers">
+  <bd-button aria-describedby="trackers-hint">What is this?</bd-button>
+</bd-tooltip>
+<span id="trackers-hint" hidden>Blocks trackers across every browser</span>
+\`\`\`
+
+There is also no dismiss-on-Escape and no delay before showing, both of which
+WCAG 1.4.13 asks of content that appears on hover.
+        `
+      }
+    }
+  },
+  argTypes: {
+    text: {
+      control    : 'text',
+      description: 'The tooltip content. Supplementary only — never the sole place information appears.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
+    }
+  }
+};
+
+export const Default = () => html`
+    <bd-tooltip text="Blocks trackers across every browser">
+      <bd-button size="sm">Hover me</bd-button>
+    </bd-tooltip>
+  `;
+
+/**
+ * ### The bubble cannot currently be snapshotted
+ *
+ * `.bubble` sits at `opacity: 0` and is raised only by `:host(:hover)` and
+ * `:host(:focus-within)`. Neither is reachable from a story: hover needs a live
+ * pointer, and `:focus-within` needs the document itself to hold focus, which a
+ * backgrounded or headless renderer does not guarantee.
+ *
+ * So every snapshot of this component records an **invisible** tooltip, and a
+ * change to the bubble's padding, colour, radius or shadow lands unreviewed.
+ * `bd-tooltip` exposes only `text` — there is no `open` attribute to set.
+ *
+ * Adding one would make the bubble testable, snapshottable, and controllable
+ * from a parent that already knows the tooltip should be showing. Until then,
+ * the two stories below cover the trigger and the layout around it, and the
+ * bubble is verified by hand.
+ */
+export const LongText = () => html`
+    <div style="padding: var(--spacing-64) var(--spacing-64) var(--spacing-16)">
+      <bd-tooltip
+        text="Blocks trackers, cryptominers and fingerprinting scripts across every browser on every device on your account"
+      >
+        <bd-button size="sm">Long description</bd-button>
+      </bd-tooltip>
+    </div>
+  `;
+
+/**
+ * The bubble is `position: absolute; left: 50%` with no `max-width` and
+ * `white-space: nowrap`, so it is centred on the trigger and grows in both
+ * directions. Against a narrow trigger near the edge of its container it
+ * overflows — measured at 42px past the left edge in the frame above.
+ *
+ * Rendered here at three trigger widths so the overhang is visible without
+ * needing the bubble itself to be.
+ */
+export const TriggerWidths = () => html`
+    <div style="display: grid; gap: var(--spacing-16); justify-items: start">
+      <bd-tooltip text="Short"><bd-button size="sm">S</bd-button></bd-tooltip>
+      <bd-tooltip text="A medium-length description">
+        <bd-button size="md">Medium trigger</bd-button>
+      </bd-tooltip>
+      <bd-tooltip text="Short">
+        <bd-button size="lg">A considerably wider trigger</bd-button>
+      </bd-tooltip>
+    </div>
+  `;
+
+export const ViewportEdges = {
+  name  : 'At the viewport edges',
+  render: () => html`
+    <p style="max-width:70ch;color:var(--color-text-secondary);font-family:var(--typography-fontFamily-sans)">
+      Hover or Tab to each trigger. The bubble is centred on its trigger and is wider than it, so
+      at an edge it would paint off the page; the component measures the overhang and shifts the
+      bubble back, keeping an 8px gutter. Narrow the window to see the shift grow.
+    </p>
+    <div style="position:relative;height:180px;margin-top:var(--spacing-64)">
+      <span style="position:absolute;left:0;top:0">
+        <bd-tooltip text="Pinned to the left edge of the viewport, with enough text to be wider than its trigger">
+          <bd-badge tone="brand">left edge</bd-badge>
+        </bd-tooltip>
+      </span>
+      <span style="position:absolute;left:50%;top:0;transform:translateX(-50%)">
+        <bd-tooltip text="Centred, so no shift is needed and none is applied">
+          <bd-badge tone="brand">centre</bd-badge>
+        </bd-tooltip>
+      </span>
+      <span style="position:absolute;right:0;top:0">
+        <bd-tooltip text="Pinned to the right edge of the viewport, with enough text to be wider than its trigger">
+          <bd-badge tone="brand">right edge</bd-badge>
+        </bd-tooltip>
+      </span>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `The collision behaviour P6C.0 added, which until now nothing rendered — every other
+                tooltip story sits in the middle of the canvas where the shift is always 0.
+
+                Measured across 320/360/375/390/430/480/576/768/1024/1440, on hover and on real
+                keyboard Tab: the bubble's left edge never goes below 8px and its right edge never
+                past the viewport minus 8. The shift is what does it — 69px at the left edge of a
+                320px viewport for the short bubble, 199px at 1440 for the long one — and it is
+                exactly 0 for the centred trigger, whose bubble centre matches its trigger centre
+                to the pixel.`
+      }
+    }
+  }
+};

package/src/components/trust-panel/trust-panel.css.js

@@ -1,53 +1,65 @@
-import { css } from "lit";
+import { css, unsafeCSS } from "lit";
+import { below } from "../shared/token-scales.js";
 
 export default css`
   :host {
     display: block;
     font-family: var(--typography-fontFamily-sans);
-    background: var(--color-blue-50);
+    background: var(--status-brand-surface);
   }
 
   .bd-trustpanel-wrapper {
-    max-width: var(--layout-ensemble-max-width, 1200px);
-    margin: 0 auto;
-    padding: var(--spacing-48) var(--layout-ensemble-inline-padding, var(--spacing-24));
+    padding-block: var(--spacing-48);
     box-sizing: border-box;
   }
 
   .bd-trustpanel-eyebrow {
     display: block;
     margin: 0 0 var(--spacing-8);
-    color: var(--color-blue-600);
-    font-weight: var(--typography-fontWeight-medium);
+    color: var(--color-text-brand);
   }
 
   .bd-trustpanel-title {
     margin: 0 0 var(--spacing-16);
-    color: var(--color-neutral-900);
-    line-height: var(--typography-lineHeight-tight, 1.1);
   }
 
   .bd-trustpanel-description {
     display: block;
     margin: 0 0 var(--spacing-40);
-    color: var(--color-neutral-600);
+    color: var(--color-text-muted);
     max-width: 80ch;
   }
 
   .bd-trustpanel-inline-link {
-    color: var(--color-blue-500);
-    font-weight: var(--typography-fontWeight-medium);
-    text-decoration: none;
+    /* bd-link owns colour, weight, underline and the focus ring now. What is
+       left here is the one thing the parent legitimately decides: that this
+       link does not break across lines mid-phrase in running text.
+
+       It used to be a bare anchor with text-decoration none, which left colour
+       as the only thing marking it as a link inside a muted paragraph, and it
+       had no focus treatment beyond the browser default outline. */
     white-space: nowrap;
   }
 
   .bd-trustpanel-card-link {
-    color: var(--color-blue-500);
-    font-weight: var(--typography-fontWeight-semibold);
+    /* 16px on this tint, where blue-500 is 4.2:1. text-brand is what the link
+       atom itself uses for a primary link, so this stops diverging from it. */
+    color: var(--color-text-brand);
+    /* link-standalone: this is a link that stands on its own -- a card's call
+       to action, not a link inside a sentence, which is what link-default's
+       inherit-everything shape is for. The size was inherited at 16px and the
+       role names base, so declaring it changes nothing and stops the size
+       depending on whatever encloses the card. The weight moves 600 -> 500,
+       the same step already accepted for the accordion title and the
+       accordion-bg question. The leading is the real gain: it was undeclared
+       and computing to the font's own metric, which CLAUDE.md rule 2 says is
+       not a typography contract. */
+    font-size: var(--typography-link-standalone-fontSize);
+    font-weight: var(--typography-link-standalone-fontWeight);
+    line-height: var(--typography-link-standalone-lineHeight);
     text-decoration: none;
     white-space: nowrap;
   }
-  .bd-trustpanel-inline-link:hover,
   .bd-trustpanel-card-link:hover {
     text-decoration: underline;
   }
@@ -66,21 +78,45 @@ export default css`
   }
 
   .bd-trustpanel-stat-divider {
-    border-top: 2px solid var(--color-blue-500);
+    border-top: 2px solid var(--color-border-brand);
     margin-bottom: var(--spacing-16);
   }
 
   .bd-trustpanel-stat-value {
-    color: var(--color-blue-500);
-    font-size: var(--typography-fontSize-3xl, 2rem);
-    font-weight: var(--typography-fontWeight-bold, 700);
+    /* --color-text-brand, the role, not --color-blue-500. CLAUDE.md is explicit
+       that blue-500 is 4.53:1 on pure white and fails on any tint, and this
+       statistic sits on the panel's blue-50 ground -- text on a tint, which is
+       the case the rule names.
+       .
+       It was not failing: measured 4.20:1 at 32px/700, and WCAG's large-text
+       bar is 3:1, so it passed on the exemption rather than on the number. The
+       role takes it to 5.72:1 and it passes without needing the exemption,
+       which is the difference worth having on a figure people read across a
+       room.
+       .
+       Visible, and small: the statistic darkens one step of blue. */
+    color: var(--color-text-brand);
+    font-size: var(--typography-fontSize-3xl);
+    font-weight: var(--typography-fontWeight-bold);
+    /* no token: 1.1 is neither --typography-lineHeight-none (1) nor -tight
+       (1.25), and choosing between them changes the height of a rendered
+       statistic. P5E recorded it as a design-review item and P5E.1 is
+       explicitly not the phase that decides it. */
     line-height: 1.1;
     margin-bottom: var(--spacing-4);
   }
 
   .bd-trustpanel-stat-label {
-    color: var(--color-neutral-600);
-    font-size: var(--typography-fontSize-sm);
+    color: var(--color-text-muted);
+    /* The sentence under a statistic, and it wraps to two lines at most widths.
+       Supporting body copy rather than a form label: label-default would put it
+       at weight 500, and this is prose describing a number, not a control's
+       name. The stat value above it keeps its own leading and is untouched. */
+    font-size: var(--typography-body-small-fontSize);
+    font-weight: var(--typography-body-small-fontWeight);
+    line-height: var(--typography-body-small-lineHeight);
+    letter-spacing: var(--typography-body-small-letterSpacing);
+    font-family: var(--typography-body-small-fontFamily);
   }
 
   /* === CARDS === */
@@ -92,14 +128,18 @@ export default css`
 
 
   .bd-trustpanel-card {
-    background: var(--color-neutral-0, #fff);
-    border: 1px solid var(--color-neutral-100, #e5e7eb);
-    border-radius: var(--radius-2xl);
-    padding: var(--spacing-32);
+    background: var(--color-surface-default);
+    border: var(--border-width-1) solid var(--color-border-container);
+    border-radius: var(--card-radius);
+    padding: var(--card-padding);
     box-sizing: border-box;
     display: flex;
     flex-direction: column;
-    transition: transform 0.25s ease, box-shadow 0.25s ease;
+    /* normal, not 250ms: a hover lift is the most repeated interaction on
+       the page, and 250 was a fifth of a second off the scale for no reason
+       anyone recorded. bento-item ran the same lift at the same value. */
+    transition: transform var(--transition-duration-normal) var(--transition-easing-ease),
+      box-shadow var(--transition-duration-normal) var(--transition-easing-ease);
   }
 
   .bd-trustpanel-card:hover {
@@ -107,11 +147,24 @@ export default css`
     box-shadow: 0px 14px 40px #00000012;
   }
 
+  /* The shadow stays and the movement goes. Turning the transition off alone
+     would only make the lift instant, which is the same 3px of travel with
+     less warning; the transform is the part someone asking for reduced motion
+     is asking not to see. The shadow still says the card is hovered. */
+  @media (prefers-reduced-motion: reduce) {
+    .bd-trustpanel-card {
+      transition: none;
+    }
+
+    .bd-trustpanel-card:hover {
+      transform: none;
+    }
+  }
+
   .bd-trustpanel-card-eyebrow {
     display: block;
     margin: 0 0 var(--spacing-16);
-    color: var(--color-blue-600);
-    font-weight: var(--typography-fontWeight-medium);
+    color: var(--color-text-brand);
   }
 
   .bd-trustpanel-card-logos {
@@ -130,13 +183,12 @@ export default css`
 
   .bd-trustpanel-card-title {
     margin: 0 0 var(--spacing-12);
-    color: var(--color-neutral-900);
   }
 
   .bd-trustpanel-card-description {
     display: block;
     margin: 0 0 var(--spacing-16);
-    color: var(--color-neutral-600);
+    color: var(--color-text-muted);
     flex: 1;
   }
 
@@ -147,7 +199,7 @@ export default css`
     }
   }
 
-  @media (max-width: 767px) {
+  @media ${unsafeCSS(below('md'))} {
     .bd-trustpanel-stats {
       grid-template-columns: repeat(2, 1fr);
     }
@@ -161,7 +213,7 @@ export default css`
     }
 
     .bd-trustpanel-card {
-      padding: var(--spacing-24);
+      padding: var(--card-padding-compact);
     }
   }
 `;

package/src/components/trust-panel/trust-panel.js

@@ -1,8 +1,11 @@
 import { LitElement, html, nothing } from "lit";
 import { tokens } from "../../tokens/tokens.js";
 import "../heading/heading.js";
+import "../link/link.js";
 import "../paragraph/paragraph.js";
 import trustPanelCSS from "./trust-panel.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
+import "../icons/arrow-right-icon.js";
 
 class TrustPanel extends LitElement {
   static properties = {
@@ -15,7 +18,7 @@ class TrustPanel extends LitElement {
     cards      : { type: Array }  // [{ eyebrow, title, description, linkLabel, linkHref }] — logos slotted per card
   };
 
-  static styles = [tokens, trustPanelCSS];
+  static styles = [tokens, ensembleCSS, trustPanelCSS];
 
   constructor() {
     super();
@@ -33,7 +36,7 @@ class TrustPanel extends LitElement {
     return html`
       <div class="bd-trustpanel-card">
         ${card.eyebrow
-          ? html`<bd-p kind="regular" font-weight="var(--typography-fontWeight-semibold, 600)" class="bd-trustpanel-card-eyebrow">${card.eyebrow}</bd-p>`
+          ? html`<bd-p variant="regular" font-weight="semibold" class="bd-trustpanel-card-eyebrow">${card.eyebrow}</bd-p>`
           : nothing}
 
         <div class="bd-trustpanel-card-logos">
@@ -45,13 +48,13 @@ class TrustPanel extends LitElement {
           : nothing}
 
         ${card.description
-          ? html`<bd-p kind="regular" class="bd-trustpanel-card-description">${card.description}</bd-p>`
+          ? html`<bd-p variant="regular" class="bd-trustpanel-card-description">${card.description}</bd-p>`
           : nothing}
 
         ${card.linkLabel
           ? html`
               <a class="bd-trustpanel-card-link" href=${card.linkHref || "#"}>
-                ${card.linkLabel} <span aria-hidden="true">→</span>
+                ${card.linkLabel} <bd-arrow-right-icon size="xs" aria-hidden="true"></bd-arrow-right-icon>
               </a>
             `
           : nothing}
@@ -61,9 +64,9 @@ class TrustPanel extends LitElement {
 
   render() {
     return html`
-      <div class="bd-trustpanel-wrapper">
+      <div class="bd-ensemble bd-trustpanel-wrapper">
         ${this.eyebrow
-          ? html`<bd-p kind="regular" font-weight="var(--typography-fontWeight-semibold, 600)" class="bd-trustpanel-eyebrow"><slot name="eyebrow">${this.eyebrow}</slot></bd-p>`
+          ? html`<bd-p variant="regular" font-weight="semibold" class="bd-trustpanel-eyebrow"><slot name="eyebrow">${this.eyebrow}</slot></bd-p>`
           : nothing}
 
         ${this.title
@@ -72,13 +75,18 @@ class TrustPanel extends LitElement {
 
         ${this.description
           ? html`
-              <bd-p kind="regular" class="bd-trustpanel-description">
+              <bd-p variant="regular" class="bd-trustpanel-description">
                 <slot name="description">${this.description}</slot>
                 ${this.linkLabel
                   ? html`
-                      <a class="bd-trustpanel-inline-link" href=${this.linkHref}>
-                        ${this.linkLabel} <span aria-hidden="true">→</span>
-                      </a>
+                      <bd-link
+                        class="bd-trustpanel-inline-link"
+                        href=${this.linkHref}
+                        underline
+                        font-size="inherit"
+                      >
+                        ${this.linkLabel} <bd-arrow-right-icon size="xs" aria-hidden="true"></bd-arrow-right-icon>
+                      </bd-link>
                     `
                   : nothing}
               </bd-p>

package/src/components/trust-panel/trust-panel.stories.js

@@ -2,7 +2,7 @@ import { html } from "lit";
 import "./trust-panel.js";
 
 export default {
-  title     : "Components/Trust Panel",
+  title     : "Modules/Trust Panel",
   component : "bd-trust-panel",
   tags      : ["autodocs"],
   parameters: {