@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/highlight/highlight.js

@@ -1,5 +1,6 @@
 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 "../heading/heading.js";
 import "../paragraph/paragraph.js";
 import highlightCSS from "./highlight.css.js";
@@ -11,7 +12,7 @@ class BdHighlightSection extends LitElement {
     as           : { type: String }
   };
 
-  static styles = [tokens, highlightCSS];
+  static styles = [highlightCSS];
 
   constructor() {
     super();
@@ -25,7 +26,7 @@ class BdHighlightSection extends LitElement {
     const highlightText = this.highlightText || "";
 
     const subtitleTemplate = this.subTitle
-      ? html`<bd-p kind="small" class="sub-title">${this.subTitle}</bd-p>`
+      ? html`<bd-p variant="small" class="sub-title">${this.subTitle}</bd-p>`
       : null;
 
     if (!highlightText || !fullText.includes(highlightText)) {
@@ -43,39 +44,29 @@ class BdHighlightSection extends LitElement {
       ${subtitleTemplate}
       <bd-h as="${this.as}" class="headline">
         ${before}
-        <span class="highlight">
-          <span class="highlight-text">${highlightText}</span>
-          <span class="highlight-right-anchor"></span>
-          <span class="highlight-deco left">
-            <svg class="highlight-svg-ellipse-top" viewBox="0 0 8 8">
+        <span class="highlight"><span class="highlight-anchor"
+          ><span class="highlight-deco left"
+          ><svg class="highlight-svg-ellipse-top" viewBox="0 0 8 8">
               <ellipse cx="4" cy="4" rx="4" ry="4" />
             </svg>
-            <svg class="highlight-svg-rect" viewBox="0 0 2 42">
+            <svg class="highlight-svg-rect" viewBox="0 0 2 42" preserveAspectRatio="none">
+              <rect x="0" y="0" width="2" height="42" />
+            </svg></span
+          ></span
+        ><span class="highlight-text">${highlightText}</span><span class="highlight-anchor"
+          ><span class="highlight-deco right"
+          ><svg class="highlight-svg-rect" viewBox="0 0 2 42" preserveAspectRatio="none">
               <rect x="0" y="0" width="2" height="42" />
             </svg>
-          </span>
-        </span>
+            <svg class="highlight-svg-ellipse-bottom" viewBox="0 0 8 8">
+              <ellipse cx="4" cy="4" rx="4" ry="4" />
+            </svg></span
+        ></span></span>
         ${after}
       </bd-h>
     `;
   }
 
-  updated() {
-    const anchor = this.renderRoot.querySelector(".highlight-right-anchor");
-    if (!anchor) return;
-
-    const deco = document.createElement("span");
-    deco.classList.add("highlight-deco", "right");
-    deco.innerHTML = `
-      <svg class="highlight-svg-rect" viewBox="0 0 2 42">
-        <rect x="0" y="0" width="2" height="42" />
-      </svg>
-      <svg class="highlight-svg-ellipse-bottom" viewBox="0 0 8 8">
-        <ellipse cx="4" cy="4" rx="4" ry="4" />
-      </svg>
-    `;
-    anchor.appendChild(deco);
-  }
 }
 
 customElements.define("bd-highlight", BdHighlightSection);

package/src/components/highlight/highlight.stories.js

@@ -2,7 +2,7 @@ import { html } from 'lit';
 import './highlight.js';
 
 export default {
-  title     : 'Components/Highlight',
+  title     : 'Atoms/Highlight',
   tags      : ['autodocs'],
   parameters: {
     docs: {
@@ -28,7 +28,12 @@ export default {
 - The right-side decoration is injected via \`updated()\` using direct DOM manipulation
 
 ### Notes
-- \`sub-title\` renders an \`<h6>\` above the headline
+- \`sub-title\` renders a \`bd-p kind="small"\` above the headline, **not** a heading
+- \`as\` sets the heading level of the headline, defaulting to \`h3\`. Choose it so
+  the page's heading order stays correct — it is not a size control
+- the component reads \`this.textContent\` during render, so the highlight is
+  resolved from the light DOM at first paint and does not follow later edits to
+  the slotted text
 - SVG decorations are injected via \`anchor.appendChild()\` in \`updated()\` — not re-injected on re-render if already present
         `
       }
@@ -42,8 +47,14 @@ export default {
     },
     subTitle: {
       control    : 'text',
-      description: 'Optional subtitle rendered as `<h6>` above the headline',
+      description: 'Optional line above the headline, rendered as a `bd-p kind="small"` — not a heading.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
+    },
+    as: {
+      control    : { type: 'select' },
+      options    : ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
+      description: 'Heading level of the headline, passed to the inner `bd-h`. Choose it for document structure, not for size.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'h3' }, category: 'Semantic' }
     }
   }
 };

package/src/components/icons/analysis-icon.js

@@ -1,23 +1,13 @@
 // icons/analysis-icon.js
-import { LitElement, css, html } from "lit";
-class AnalysisIcon extends LitElement {
+import { html } from "lit";
+import { BdIconElement } from "./icon-element.js";
+class AnalysisIcon extends BdIconElement {
+  static defaultSize = "2xl";
 
-  static properties = { size  : { type: Number },
-    color : { type: String },
-    width : { type: Number },
-    height: { type: Number } };
-
-  constructor() {
-    super();
-    this.width = 48;
-    this.height = 49;
-    this.color = "#006DFF"; }
-
-  static styles = css`:host { display: inline-flex; }`;
   render() {
     return html`
-      <svg width="${this.width}" height="${this.height}" viewBox="0 0 48 49" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
-        <path d="M19.5 3C13.5938 3 8.15625 6.1875 5.15625 11.25C2.25 16.4062 2.25 22.6875 5.15625 27.75C8.15625 32.9062 13.5938 36 19.5 36C25.3125 36 30.75 32.9062 33.75 27.75C36.6562 22.6875 36.6562 16.4062 33.75 11.25C30.75 6.1875 25.3125 3 19.5 3ZM19.5 39C8.71875 39 0 30.2812 0 19.5C0 8.8125 8.71875 0 19.5 0C30.1875 0 39 8.8125 39 19.5C39 24.375 37.2188 28.7812 34.3125 32.25L47.5312 45.4688C48.0938 46.0312 48.0938 47.0625 47.5312 47.625C46.9688 48.1875 45.9375 48.1875 45.375 47.625L32.1562 34.3125C28.7812 37.3125 24.2812 39 19.5 39ZM12 21C12 20.25 12.6562 19.5 13.5 19.5C14.25 19.5 15 20.25 15 21V27C15 27.8438 14.25 28.5 13.5 28.5C12.6562 28.5 12 27.8438 12 27V21ZM18 12C18 11.25 18.6562 10.5 19.5 10.5C20.25 10.5 21 11.25 21 12V27C21 27.8438 20.25 28.5 19.5 28.5C18.6562 28.5 18 27.8438 18 27V12ZM24 18C24 17.25 24.6562 16.5 25.5 16.5C26.25 16.5 27 17.25 27 18V27C27 27.8438 26.25 28.5 25.5 28.5C24.6562 28.5 24 27.8438 24 27V18Z" fill="${this.color}"/>
+      <svg viewBox="0 0 48 49" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+        <path d="M19.5 3C13.5938 3 8.15625 6.1875 5.15625 11.25C2.25 16.4062 2.25 22.6875 5.15625 27.75C8.15625 32.9062 13.5938 36 19.5 36C25.3125 36 30.75 32.9062 33.75 27.75C36.6562 22.6875 36.6562 16.4062 33.75 11.25C30.75 6.1875 25.3125 3 19.5 3ZM19.5 39C8.71875 39 0 30.2812 0 19.5C0 8.8125 8.71875 0 19.5 0C30.1875 0 39 8.8125 39 19.5C39 24.375 37.2188 28.7812 34.3125 32.25L47.5312 45.4688C48.0938 46.0312 48.0938 47.0625 47.5312 47.625C46.9688 48.1875 45.9375 48.1875 45.375 47.625L32.1562 34.3125C28.7812 37.3125 24.2812 39 19.5 39ZM12 21C12 20.25 12.6562 19.5 13.5 19.5C14.25 19.5 15 20.25 15 21V27C15 27.8438 14.25 28.5 13.5 28.5C12.6562 28.5 12 27.8438 12 27V21ZM18 12C18 11.25 18.6562 10.5 19.5 10.5C20.25 10.5 21 11.25 21 12V27C21 27.8438 20.25 28.5 19.5 28.5C18.6562 28.5 18 27.8438 18 27V12ZM24 18C24 17.25 24.6562 16.5 25.5 16.5C26.25 16.5 27 17.25 27 18V27C27 27.8438 26.25 28.5 25.5 28.5C24.6562 28.5 24 27.8438 24 27V18Z" fill="currentColor"/>
       </svg>
     `;
   }

package/src/components/icons/arrow-down-icon.js

@@ -1,26 +1,13 @@
 // icons/arrow-down-icon.js
-import { LitElement, css, html } from "lit";
-class ArrowDownIcon extends LitElement {
+import { html } from "lit";
+import { BdIconElement } from "./icon-element.js";
+class ArrowDownIcon extends BdIconElement {
+  static defaultSize = "md";
 
-
-  static properties = {
-    width : { type: Number },
-    height: { type: Number },
-    color : { type: String }
-  };
-
-  constructor() {
-    super();
-    this.width = 20;
-    this.height = 20;
-    this.color = "white"; }
-
-
-  static styles = css`:host { display: inline-flex; }`;
   render() {
     return html`
-      <svg xmlns="http://www.w3.org/2000/svg" width="${this.width}" height="${this.height}" viewBox="0 0 20 20" aria-hidden="true">
-        <path fill-rule="evenodd" clip-rule="evenodd" d="M9.99956 12.8662L3.5665 6.43311L2.68262 7.31699L9.55762 14.192C9.80169 14.4361 10.1974 14.4361 10.4415 14.192L17.3165 7.31699L16.4326 6.43311L9.99956 12.8662Z" fill="${this.color}"/>
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+        <path fill-rule="evenodd" clip-rule="evenodd" d="M9.99999 11.9823L3.56693 5.54919L1.79916 7.31696L9.11611 14.6339C9.60426 15.1221 10.3957 15.1221 10.8839 14.6339L18.2008 7.31696L16.433 5.54919L9.99999 11.9823Z" fill="currentColor"/>
       </svg>
     `;
   }

package/src/components/icons/arrow-icon.js

@@ -0,0 +1,44 @@
+// icons/arrow-icon.js
+import { html } from "lit";
+import { BdIconElement } from "./icon-element.js";
+
+/**
+ * The trailing arrow on bd-contact-button.
+ *
+ * Moved here from src/components/button/icons.js, which was the only place in
+ * the package registering an icon element outside this directory, and the only
+ * icon not extending BdIconElement. It carried its own :host and .arrow-icon
+ * rules -- inline-flex, height from --icon-sm-size, fill: currentColor -- which
+ * are exactly what the base class does, so the move deletes them rather than
+ * moving them. It now takes `size` from the icon scale like every sibling,
+ * where before it was fixed at sm whatever a consumer asked for.
+ *
+ * ARTWORK. Eclipse `arrow right fill`, exported from the Icon inventory table in the
+ * foundation Figma file. It replaces a 512x404.39 drawing of our own, and that
+ * changed the aspect ratio: the old box was 1.266 wide per unit of height, the
+ * new one is square. icon-element.js sizes by height with width auto, so at sm
+ * this arrow went from 20.26x16 to 16x16 -- narrower beside the same label.
+ *
+ * NAMING, WHICH IS THE CONFUSING PART. This is the only TRUE arrow in the set:
+ * a shaft with a head. bd-arrow-up-icon,
+ * bd-arrow-down-icon and bd-arrow-right-icon are CHEVRONS despite the name --
+ * carets with no shaft, on a 20x20 box. So "arrow" means two different drawings
+ * here, and a caller reaching for bd-arrow-right-icon expecting this one gets a
+ * chevron. Renaming is a public-API change and is not done here; it is recorded
+ * so the next person meets it in the file rather than in a review.
+ */
+class BdArrowIcon extends BdIconElement {
+  static defaultSize = "sm";
+
+  render() {
+    return html`
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+        <path fill-rule="evenodd" clip-rule="evenodd" d="M14.482 11.2501L10.9327 14.7993L12.7005 16.5671L19.2675 10L12.7005 3.43298L10.9327 5.20075L14.482 8.75006L1.875 8.75006V11.2501L14.482 11.2501Z" fill="currentColor"/>
+      </svg>
+    `;
+  }
+}
+
+customElements.define("bd-arrow-icon", BdArrowIcon);
+
+export { BdArrowIcon };

package/src/components/icons/arrow-right-icon.js

@@ -1,31 +1,38 @@
-import { LitElement, css, html } from "lit";
+// icons/arrow-right-icon.js
+import { html } from "lit";
+import { BdIconElement } from "./icon-element.js";
 
-class ArrowRightIcon extends LitElement {
-  static properties = {
-    width : { type: String },
-    height: { type: String },
-    color : { type: String }
-  };
-
-  constructor() {
-    super();
-    this.width = "20";
-    this.height = "20";
-    this.color = "currentColor";
-  }
-
-  static styles = css`
-    :host { display: inline-flex; }
-    svg { display: block; }
-  `;
+/**
+ * The third direction of the arrow family, and it is the same drawing as the
+ * other two rather than a new one.
+ *
+ * Note what this family actually is: bd-arrow-up-icon and bd-arrow-down-icon
+ * are CHEVRONS, not shafted arrows. This one keeps that, so "Learn more" gets a
+ * chevron affordance rather than the "→" character it replaces. That is a
+ * visible change and a deliberate one -- a shafted arrow would have been a new
+ * shape sitting beside two carets already called "arrow".
+ *
+ * ARTWORK. Eclipse `chevron right fill`. This used to be arrow-up's path under
+ * a rotate(90) transform, which guaranteed the two were the same drawing;
+ * Eclipse ships a chevron-right of its own, so the transform is gone and the
+ * three directions are now three separate paths that the library keeps in step.
+ *
+ * WEIGHT. Fill, which is what the other two chevrons are. It was briefly the
+ * light weight while arrow-up and arrow-down were on fill -- measured, the
+ * light edge offset is 1.250 against fill's 2.500 on a 20x20 box, so it read
+ * visibly thinner than its own family. Unlike the up/down pair it is not the
+ * other state of one control, so it never flickered; it was simply a family
+ * that did not agree. All three move together or not at all.
+ */
+class ArrowRightIcon extends BdIconElement {
+  static defaultSize = "md";
 
   render() {
     return html`
-      <svg xmlns="http://www.w3.org/2000/svg" width="${this.width}" height="${this.height}" viewBox="0 0 16 16" fill="none" aria-hidden="true">
-        <path d="M2.5 8h11M9 3.5 13.5 8 9 12.5" stroke="${this.color}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+        <path fill-rule="evenodd" clip-rule="evenodd" d="M14.6339 9.11614L7.31692 1.79919L5.54915 3.56696L11.9822 10L5.54915 16.4331L7.31691 18.2008L14.6339 10.8839C15.122 10.3958 15.122 9.60429 14.6339 9.11614Z" fill="currentColor"/>
       </svg>
     `;
   }
 }
-
-customElements.define("bd-arrow-right-icon", ArrowRightIcon);
+customElements.define("bd-arrow-right-icon", ArrowRightIcon);

package/src/components/icons/arrow-up-icon.js

@@ -1,26 +1,27 @@
 // icons/arrow-up-icon.js
-import { LitElement, css, html } from "lit";
+import { html } from "lit";
+import { BdIconElement } from "./icon-element.js";
 
-class ArrowUpIcon extends LitElement {
+/**
+ * ARTWORK. Eclipse `chevron up fill`, and the weight is the point.
+ *
+ * This briefly shipped as Eclipse `chevron up` -- the LIGHT weight -- while
+ * bd-arrow-down-icon was on fill. The two are the two states of one control:
+ * accordion.js renders up when open and down when closed, and bd-footer's
+ * country toggle does the same. Measured off the paths, fill is exactly 2.00x
+ * the light edge offset (2.500 against 1.250 on a 20x20 box), so the chevron
+ * visibly doubled in weight every time someone collapsed an accordion. Two
+ * legitimate library weights, wrong together.
+ *
+ * If this is ever moved back to light, bd-arrow-down-icon has to move with it.
+ */
+class ArrowUpIcon extends BdIconElement {
+  static defaultSize = "md";
 
-  static properties = {
-    width : { type: Number },
-    height: { type: Number },
-    color : { type: String }
-  };
-
-  constructor() {
-    super();
-    this.width = 20;
-    this.height = 20;
-    this.color = "white";
-  }
-
-  static styles = css`:host { display: inline-flex; }`;
   render() {
     return html`
-      <svg xmlns="http://www.w3.org/2000/svg" width="${this.width}" height="${this.height}" viewBox="0 0 20 20" aria-hidden="true">
-        <path fill-rule="evenodd" clip-rule="evenodd" d="M9.55762 5.80806C9.80169 5.56398 10.1974 5.56398 10.4415 5.80806L17.3165 12.6831L16.4326 13.5669L9.99956 7.13388L3.5665 13.5669L2.68262 12.6831L9.55762 5.80806Z" fill="${this.color}"/>
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+        <path fill-rule="evenodd" clip-rule="evenodd" d="M9.99999 8.01777L16.433 14.4508L18.2008 12.6831L10.8839 5.36612C10.3957 4.87796 9.60426 4.87796 9.1161 5.36612L1.79916 12.6831L3.56693 14.4508L9.99999 8.01777Z" fill="currentColor"/>
       </svg>
     `;
   }

package/src/components/icons/bd-ai-icon.js

@@ -18,7 +18,7 @@ class BdAiIcon extends LitElement {
   render() {
     return html`
 <svg width="${this.width}" height="${this.height}" viewBox="0 0 524.8 62.6" xmlns="http://www.w3.org/2000/svg">
-  <path fill="#006dff" d="M89.8,48.5v-17.8h10.5v-8.3h-10.5v-11.4h-6.2l-3.6,11.4h-9.5v.5l3.6,3.1c5.5,4.5,5.9,4.4,5.9,6.9v-2.2s0,18,0,18c0,12.8,9,15.1,17,13l4.9-7.8-.3-.2c-6.8,2-11.7,1.8-11.7-5.2ZM62.8,3.2c-3.6,0-6.2,2.8-6.2,5.9s2.6,5.9,6.2,5.9,6.4-2.5,6.4-5.9-2.8-5.9-6.4-5.9ZM37.2,31.2v-.2c6-1.8,10-6.1,10-12.7,0-10.5-9-14.5-17.7-14.5H8.4s-8.4,0-8.4,0v.9l3,2.5c3.6,2.9,4,3.5,4,6.1v48.4h20.8c10.9,0,21.9-3.9,21.9-16.5s-5.2-13.2-12.5-14ZM17.3,12.6h8.5c5.7,0,7.5.8,9.3,2.5,1.3,1.2,1.9,3,1.9,5s-.6,3.5-2,4.8c-1.7,1.6-4,2.4-8.3,2.4h-9.4v-14.7ZM26.8,52.8h-9.5v-16.7h9.9c8.3,0,12.2,2.1,12.2,8.2s-7.3,8.5-12.7,8.5ZM130.8,2.1l3.1,2c2.8,1.8,3.2,2.6,3.2,5.1v18.2h-.2c-2-2.5-6-6-13.3-6-11.2,0-19,9-19,20.6s7.3,20.6,19.4,20.6,10.6-2.1,13.5-6.9h.2l1,5.9h8.3V1.4h-16.1v.7ZM125.9,53.8c-7.2,0-11.5-5.6-11.5-11.8s4.3-11.8,11.5-11.8,11.5,5.6,11.5,11.8-4.3,11.8-11.5,11.8ZM52.7,23.1l1.6,1.3c3.5,2.7,3.7,3.2,3.7,6.5h0v30.8h9.8V22.4h-15.1v.6ZM376.8,21.4c-11.8,0-20.5,8.3-20.5,20.6s9.1,20.6,22.2,20.6,7.4-.7,10.5-1.9l5.6-9.3-.7-.4c-4.8,2.5-9.9,3.8-14.4,3.8-6.8,0-12.6-3.4-13.3-9.3h29.9c1.3-15.4-7-24-19.2-24ZM366.1,38.1c.7-5.6,4.3-9.3,10.1-9.3s9.9,3.6,10,9.3h-20.1ZM412.3,28.6h-.2v-6.2h-16.5v.4s2.5,1.6,2.5,1.6c4,2.5,4.2,3.3,4.2,8.2v29h9.8v-21c0-2.1,1.3-9.9,10.5-9.9s3.1.3,4.7.7v-9.5c-1.1-.3-2.3-.6-3.5-.6-5.2,0-9.5,2.7-11.6,7.2ZM334.1,2.1l1.4.9c4.7,3,5.3,3.9,5.3,9v15.4h-.3c-2-2.5-6-6-13.3-6-11.2,0-19,9-19,20.6s7.3,20.6,19.4,20.6,10.6-2.1,13.5-6.9h.2l1,5.9h8.3V1.4h-16.5v.7ZM329.6,53.8c-7.2,0-11.5-5.6-11.5-11.8s4.3-11.8,11.5-11.8,11.5,5.6,11.5,11.8-4.3,11.8-11.5,11.8ZM288.1,21.4c-4.4,0-9.3,2.2-12.5,7h-.2v-6h-8.4s-7.7,0-7.7,0v.4l2.4,1.6c4,2.5,4.3,3.3,4.3,8.2v29h9.8v-21.4c0-5.2,2.5-10,9-10s8,5.2,8,9.6v21.8h9.8v-24.8c0-9.1-5.3-15.4-14.6-15.4ZM239.8,21.4c-11.9,0-20.5,8.3-20.5,20.6s9.1,20.6,22.2,20.6,7.4-.7,10.5-1.9l5.6-9.3-.8-.4c-4.8,2.5-9.9,3.8-14.4,3.8-6.8,0-12.6-3.4-13.3-9.3h29.9c1.3-15.4-7-24-19.2-24ZM229.1,38.1c.7-5.6,4.3-9.3,10.1-9.3s9.9,3.6,10,9.3h-20.1ZM173.1,21.4c-11.9,0-20.5,8.3-20.5,20.6s9.1,20.6,22.2,20.6,7.4-.7,10.5-1.9l5.6-9.3-.7-.4c-4.8,2.5-9.9,3.8-14.4,3.8-6.8,0-12.6-3.4-13.3-9.3h29.9v-2.7c0-13.6-8.3-21.3-19.2-21.3ZM162.4,38.1c.7-5.6,4.3-9.3,10.1-9.3s9.9,3.6,10,9.3h-20.1ZM209.8,15.1c0-6.9,6.1-8.8,13.9-5.7l.5-.4-2.3-8.3c-15-3-22,3.7-22,14.4v7.2h-9.6v.6l5,4.1c3.9,3.1,4.6,3.8,4.6,7.1v27.6h9.8v-31h9.1v-8.4h-9.1v-7.1ZM524.8,9.6V3.9h-23.2v5.8h8.1v46.2h-8.1v5.8h23.2v-5.8h-8.1V9.6h8.1ZM467.4,3.9l-20.2,57.7h7l5.8-17h23.3l5.8,17h7.3l-20.2-57.7h-8.9ZM461.7,38.4l9.8-28.1h.4l9.8,28.1h-19.9Z"/>
+  <path fill="var(--color-blue-500)" d="M89.8,48.5v-17.8h10.5v-8.3h-10.5v-11.4h-6.2l-3.6,11.4h-9.5v.5l3.6,3.1c5.5,4.5,5.9,4.4,5.9,6.9v-2.2s0,18,0,18c0,12.8,9,15.1,17,13l4.9-7.8-.3-.2c-6.8,2-11.7,1.8-11.7-5.2ZM62.8,3.2c-3.6,0-6.2,2.8-6.2,5.9s2.6,5.9,6.2,5.9,6.4-2.5,6.4-5.9-2.8-5.9-6.4-5.9ZM37.2,31.2v-.2c6-1.8,10-6.1,10-12.7,0-10.5-9-14.5-17.7-14.5H8.4s-8.4,0-8.4,0v.9l3,2.5c3.6,2.9,4,3.5,4,6.1v48.4h20.8c10.9,0,21.9-3.9,21.9-16.5s-5.2-13.2-12.5-14ZM17.3,12.6h8.5c5.7,0,7.5.8,9.3,2.5,1.3,1.2,1.9,3,1.9,5s-.6,3.5-2,4.8c-1.7,1.6-4,2.4-8.3,2.4h-9.4v-14.7ZM26.8,52.8h-9.5v-16.7h9.9c8.3,0,12.2,2.1,12.2,8.2s-7.3,8.5-12.7,8.5ZM130.8,2.1l3.1,2c2.8,1.8,3.2,2.6,3.2,5.1v18.2h-.2c-2-2.5-6-6-13.3-6-11.2,0-19,9-19,20.6s7.3,20.6,19.4,20.6,10.6-2.1,13.5-6.9h.2l1,5.9h8.3V1.4h-16.1v.7ZM125.9,53.8c-7.2,0-11.5-5.6-11.5-11.8s4.3-11.8,11.5-11.8,11.5,5.6,11.5,11.8-4.3,11.8-11.5,11.8ZM52.7,23.1l1.6,1.3c3.5,2.7,3.7,3.2,3.7,6.5h0v30.8h9.8V22.4h-15.1v.6ZM376.8,21.4c-11.8,0-20.5,8.3-20.5,20.6s9.1,20.6,22.2,20.6,7.4-.7,10.5-1.9l5.6-9.3-.7-.4c-4.8,2.5-9.9,3.8-14.4,3.8-6.8,0-12.6-3.4-13.3-9.3h29.9c1.3-15.4-7-24-19.2-24ZM366.1,38.1c.7-5.6,4.3-9.3,10.1-9.3s9.9,3.6,10,9.3h-20.1ZM412.3,28.6h-.2v-6.2h-16.5v.4s2.5,1.6,2.5,1.6c4,2.5,4.2,3.3,4.2,8.2v29h9.8v-21c0-2.1,1.3-9.9,10.5-9.9s3.1.3,4.7.7v-9.5c-1.1-.3-2.3-.6-3.5-.6-5.2,0-9.5,2.7-11.6,7.2ZM334.1,2.1l1.4.9c4.7,3,5.3,3.9,5.3,9v15.4h-.3c-2-2.5-6-6-13.3-6-11.2,0-19,9-19,20.6s7.3,20.6,19.4,20.6,10.6-2.1,13.5-6.9h.2l1,5.9h8.3V1.4h-16.5v.7ZM329.6,53.8c-7.2,0-11.5-5.6-11.5-11.8s4.3-11.8,11.5-11.8,11.5,5.6,11.5,11.8-4.3,11.8-11.5,11.8ZM288.1,21.4c-4.4,0-9.3,2.2-12.5,7h-.2v-6h-8.4s-7.7,0-7.7,0v.4l2.4,1.6c4,2.5,4.3,3.3,4.3,8.2v29h9.8v-21.4c0-5.2,2.5-10,9-10s8,5.2,8,9.6v21.8h9.8v-24.8c0-9.1-5.3-15.4-14.6-15.4ZM239.8,21.4c-11.9,0-20.5,8.3-20.5,20.6s9.1,20.6,22.2,20.6,7.4-.7,10.5-1.9l5.6-9.3-.8-.4c-4.8,2.5-9.9,3.8-14.4,3.8-6.8,0-12.6-3.4-13.3-9.3h29.9c1.3-15.4-7-24-19.2-24ZM229.1,38.1c.7-5.6,4.3-9.3,10.1-9.3s9.9,3.6,10,9.3h-20.1ZM173.1,21.4c-11.9,0-20.5,8.3-20.5,20.6s9.1,20.6,22.2,20.6,7.4-.7,10.5-1.9l5.6-9.3-.7-.4c-4.8,2.5-9.9,3.8-14.4,3.8-6.8,0-12.6-3.4-13.3-9.3h29.9v-2.7c0-13.6-8.3-21.3-19.2-21.3ZM162.4,38.1c.7-5.6,4.3-9.3,10.1-9.3s9.9,3.6,10,9.3h-20.1ZM209.8,15.1c0-6.9,6.1-8.8,13.9-5.7l.5-.4-2.3-8.3c-15-3-22,3.7-22,14.4v7.2h-9.6v.6l5,4.1c3.9,3.1,4.6,3.8,4.6,7.1v27.6h9.8v-31h9.1v-8.4h-9.1v-7.1ZM524.8,9.6V3.9h-23.2v5.8h8.1v46.2h-8.1v5.8h23.2v-5.8h-8.1V9.6h8.1ZM467.4,3.9l-20.2,57.7h7l5.8-17h23.3l5.8,17h7.3l-20.2-57.7h-8.9ZM461.7,38.4l9.8-28.1h.4l9.8,28.1h-19.9Z"/>
 </svg>
     `;
   }

package/src/components/icons/brand-marks.stories.js

@@ -0,0 +1,279 @@
+// icons/brand-marks.stories.js
+import { html } from "lit";
+import "./av-comparatives-icon.js";
+import "./bd-ai-icon.js";
+import "./best-brands-icon.js";
+import "./brand-signature-icon.js";
+import "./pc-mag-2024-icon.js";
+import "./pc-mag-business-icon.js";
+import "./pc-mag-icon.js";
+import "./pc-mag-readers-icon.js";
+import "./top-product-icon.js";
+
+export default {
+  title     : 'Atoms/Brand mark',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+Nine wordmarks and award badges. They sat under **Atoms/Icon** and are not
+icons, which is why that section read as eight exceptions to its own rules.
+
+### Why they are separate
+An interface icon is a shape on a square grid: it takes a \`size\` step from
+\`--icon-*-size\`, it is drawn in \`currentColor\`, and it follows the text beside
+it. None of that is true here, and none of it should be.
+
+| | Interface icon | Brand mark |
+|---|---|---|
+| Size | \`size\` step on the icon scale | \`width\` / \`height\`, own aspect ratio |
+| Colour | \`currentColor\` | fixed — the mark's own |
+| Grid | square, 12–64px | 52×48, 68×37, 126×15 — whatever it was drawn at |
+| Renders into | shadow DOM | light DOM |
+
+A PC Mag badge is not a 24px glyph and must not be recoloured — retinting a
+third party's award mark misrepresents it. Forcing these onto the icon scale
+would make the system tidier and the marks wrong.
+
+### The two of ours behave differently from the other seven
+
+\`bd-ai-icon\` is the Bitdefender wordmark, and it is the first exception to
+"fixed colour": it is our own mark, so its fill is \`var(--color-blue-500)\` —
+the brand blue as a token, not a hex value baked into the artwork.
+
+\`bd-brand-signature-icon\` is the ninth and it is the *whole* right-hand column
+of that table, not just the colour cell. It is a \`BdIconElement\` like any
+interface icon: \`size\` from \`--icon-*-size\`, artwork in \`currentColor\`, both
+deprecated \`width\`/\`height\` props still honoured. Nothing about it needed an
+exception, because neither reason for the rules above applies to it — choosing
+the ink is not misrepresentation when the mark is your own, and a single path
+has no PNG to stop it scaling. It is filed here because it is a brand mark;
+it is used like an icon.
+
+So the table above describes the seven. Read it as "what a third party's raster
+badge needs", not as what this section is.
+
+### Usage
+\`\`\`html
+<bd-pc-mag-icon width="189" height="64"></bd-pc-mag-icon>
+<bd-top-product-icon width="48" height="52"></bd-top-product-icon>
+<bd-ai-icon width="126" height="15"></bd-ai-icon>
+\`\`\`
+
+Always set \`width\` and \`height\`: the defaults differ per mark, because each
+one is a different shape.
+
+### Accessibility
+These render \`aria-hidden="true"\` like the icons do, so they are decorative by
+default. An award badge usually *is* meaningful — it is a claim about the
+product — so when one carries information rather than decoration, put the text
+next to it or in a \`<bd-visually-hidden>\`, e.g. "PC Mag Editors' Choice 2024".
+        `
+      }
+    }
+  },
+  argTypes: {
+    width: {
+      control    : { type: 'number', min: 8, max: 400, step: 1 },
+      description: 'Rendered width in pixels. Defaults differ per mark, so set it explicitly.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: 'varies' }, category: 'Size' }
+    },
+    height: {
+      control    : { type: 'number', min: 8, max: 400, step: 1 },
+      description: 'Rendered height in pixels. Defaults differ per mark, so set it explicitly.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: 'varies' }, category: 'Size' }
+    }
+  }
+};
+
+export const AllMarks = {
+  name      : 'All marks',
+  parameters: {
+    controls: { disable: true },
+    docs    : {
+      description: {
+        story: `Each mark at its intrinsic size. The sizes have nothing in common
+because the artwork has nothing in common — that is the point of keeping them
+off the icon scale. The signature is the one that sets no size here, because
+it is the one that has a scale to take one from.`
+      }
+    }
+  },
+  render: () => html`
+    <style>
+      .marks-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+        gap: var(--spacing-24);
+      }
+      .mark-item {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: space-between;
+        gap: var(--spacing-8);
+        padding: var(--spacing-16);
+        min-height: var(--spacing-128);
+        border: var(--border-width-1) solid var(--color-border-subtle);
+        border-radius: var(--radius-md);
+      }
+      .mark-item span {
+        font-family: var(--typography-fontFamily-mono);
+        font-size: var(--typography-fontSize-xxs);
+        color: var(--color-text-muted);
+        text-align: center;
+      }
+    </style>
+    <div class="marks-grid">
+      <div class="mark-item">
+        <bd-ai-icon width="126" height="15"></bd-ai-icon>
+        <span>bd-ai-icon · 126×15</span>
+      </div>
+      <div class="mark-item">
+        <bd-brand-signature-icon></bd-brand-signature-icon>
+        <span>bd-brand-signature-icon · 182×24 (size="lg")</span>
+      </div>
+      <div class="mark-item">
+        <bd-av-comparatives-icon width="126" height="64"></bd-av-comparatives-icon>
+        <span>bd-av-comparatives-icon · 126×64</span>
+      </div>
+      <div class="mark-item">
+        <bd-best-brands-icon width="48" height="52"></bd-best-brands-icon>
+        <span>bd-best-brands-icon · 48×52</span>
+      </div>
+      <div class="mark-item">
+        <bd-pc-mag-icon width="189" height="64"></bd-pc-mag-icon>
+        <span>bd-pc-mag-icon · 189×64</span>
+      </div>
+      <div class="mark-item">
+        <bd-pc-mag-2024-icon width="48" height="52"></bd-pc-mag-2024-icon>
+        <span>bd-pc-mag-2024-icon · 48×52</span>
+      </div>
+      <div class="mark-item">
+        <bd-pc-mag-business-icon width="48" height="52"></bd-pc-mag-business-icon>
+        <span>bd-pc-mag-business-icon · 48×52</span>
+      </div>
+      <div class="mark-item">
+        <bd-pc-mag-readers-icon width="37" height="68"></bd-pc-mag-readers-icon>
+        <span>bd-pc-mag-readers-icon · 37×68</span>
+      </div>
+      <div class="mark-item">
+        <bd-top-product-icon width="48" height="52"></bd-top-product-icon>
+        <span>bd-top-product-icon · 48×52</span>
+      </div>
+    </div>
+  `
+};
+
+export const Wordmark = {
+  name  : 'Bitdefender wordmark',
+  args  : { width: 252, height: 30 },
+  render: ({ width, height }) => html`
+    <bd-ai-icon width="${width}" height="${height}"></bd-ai-icon>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `Our own mark, so it is the one here drawn from a token —
+\`var(--color-blue-500)\`. The third-party marks keep their own colours.`
+      }
+    }
+  }
+};
+
+export const AwardRow = {
+  name      : 'Awards in a row',
+  parameters: {
+    controls: { disable: true },
+    docs    : {
+      description: {
+        story: `How they actually appear on a page. They do not line up on a common
+grid and should be baseline- or bottom-aligned rather than centred on a shared
+box height.`
+      }
+    }
+  },
+  render: () => html`
+    <div style="display: flex; align-items: flex-end; gap: var(--spacing-24); flex-wrap: wrap">
+      <bd-av-comparatives-icon width="126" height="64"></bd-av-comparatives-icon>
+      <bd-best-brands-icon width="48" height="52"></bd-best-brands-icon>
+      <bd-pc-mag-2024-icon width="48" height="52"></bd-pc-mag-2024-icon>
+      <bd-top-product-icon width="48" height="52"></bd-top-product-icon>
+    </div>
+  `
+};
+
+export const BrandSignature = {
+  name      : 'Brand signature',
+  parameters: {
+    controls: { disable: true },
+    docs    : {
+      description: {
+        story: `The signature the hero lays over its image — Figma
+\`Mark/brand-signature\`, node 357:62.
+
+It takes its ink from whatever it sits in, which is the whole reason it is not
+drawn white: a baked white mark is invisible the moment somebody puts it on a
+light ground, which is exactly how \`bd-close-icon\` came to be invisible on a
+white page before the icon base class existed. The three rows below are the
+same element three times with no \`color\` prop set.
+
+Over an image it is white, and the contrast is the **scrim's** job rather than
+the mark's — \`bd-header\` paints a \`--color-blue-950\` band from 0% to 60%
+behind it. Without one, measured against a real product photo, the worst
+neighbourhood under the mark was **1.00:1** with a third of its area under the
+3:1 that WCAG 1.4.11 asks of a non-text graphic. With it: worst **8.64:1**. The
+band, its stops and why blue-950 rather than the brand blue are all written up
+in \`header.css.js\`.`
+      }
+    }
+  },
+  render: () => html`
+    <style>
+      .sig-row {
+        display: flex;
+        align-items: center;
+        gap: var(--spacing-16);
+        padding: var(--spacing-24);
+        border-radius: var(--radius-lg);
+        font-family: var(--typography-fontFamily-mono);
+        font-size: var(--typography-fontSize-xxs);
+      }
+      .sig-rows { display: grid; gap: var(--spacing-16); }
+      .sig-on-page {
+        background: var(--color-surface-default);
+        color: var(--color-text-primary);
+        border: var(--border-width-1) solid var(--color-border-subtle);
+      }
+      .sig-on-brand {
+        background: var(--color-action-primary);
+        color: var(--color-text-inverse);
+      }
+      .sig-on-scrim {
+        color: var(--color-text-inverse);
+        background:
+          linear-gradient(
+            to right,
+            color-mix(in srgb, var(--color-blue-950) 60%, transparent),
+            color-mix(in srgb, var(--color-blue-950) 60%, transparent)
+          ),
+          linear-gradient(120deg, var(--color-neutral-0), var(--color-blue-200));
+      }
+    </style>
+    <div class="sig-rows">
+      <div class="sig-row sig-on-page">
+        <bd-brand-signature-icon></bd-brand-signature-icon>
+        <span>on the page ground — text/primary</span>
+      </div>
+      <div class="sig-row sig-on-brand">
+        <bd-brand-signature-icon></bd-brand-signature-icon>
+        <span>on action/primary — text/inverse</span>
+      </div>
+      <div class="sig-row sig-on-scrim">
+        <bd-brand-signature-icon></bd-brand-signature-icon>
+        <span>white over the hero scrim — blue-950 at 60% on a pale image</span>
+      </div>
+    </div>
+  `
+};