@repobit/dex-system-design 1.0.1 → 2.0.1

package/src/components/avatar/avatar.stories.js

@@ -23,7 +23,7 @@ there is no image.
 |---|---|---|
 | \`src\` | image URL — omit to fall back to initials | \`''\` |
 | \`name\` | the person's name | \`''\` |
-| \`size\` | \`small\`, \`default\`, \`large\` | \`default\` |
+| \`size\` | \`sm\`, \`md\`, \`lg\` — \`small\` / \`default\` / \`large\` still resolve | \`md\` |
 
 ### Always pass a name
 \`name\` does two jobs. It is the source of the initials when there is no \`src\`,
@@ -31,9 +31,13 @@ and it is the accessible name in both cases — the wrapper carries
 \`role="img"\` with \`aria-label\` from \`name\`, and the inner image is given an
 empty \`alt\` so it is not announced twice.
 
-Without a \`name\` the accessible name falls back to the literal string
-"Avatar", which tells a screen reader user nothing. Pass one even when you have
-an image.
+Without a \`name\` the avatar has nothing to say, so it is hidden from assistive
+technology rather than announced — it used to be an image named "Avatar", which
+tells a screen reader user nothing. Pass one even when you have an image.
+
+### When the image does not load
+A \`src\` that fails to load falls back to the initials, the same as no \`src\`
+at all. A new \`src\` gets its own chance to load.
 
 ### How the initials are derived
 The first letter of each whitespace-separated word, capped at two characters
@@ -57,9 +61,9 @@ first and last.
     },
     size: {
       control    : { type: 'select' },
-      options    : ['small', 'default', 'large'],
+      options    : ['sm', 'md', 'lg'],
       description: 'Diameter of the avatar.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'md' }, category: 'Appearance' }
     }
   }
 };

package/src/components/awards/awards-flex.css.js

@@ -203,136 +203,21 @@ export const awardsFlexCSS = css`
     margin: 0;
   }
 
-  /* === DOTS === */
-  /* Dots and the pause control share one row; the dots keep their own spacing
-     so the treatment is unchanged when no control is shown. */
-  .bd-awardsflex-controls {
-    display: flex;
-    align-items: center;
-    gap: var(--spacing-16);
-  }
-
-  .bd-awardsflex-dots {
-    display: flex;
-    /* The buttons below carry their own 24px of target, so the space between
-       two dots now comes from the boxes rather than from a gap. Adding one on
-       top would push them apart without making either easier to hit. */
-    gap: 0;
+  /* === SLIDE CONTROLS ===
+     bd-pagination-dots, which also runs the autoplay clock. This file used to
+     draw its own dots and pause button -- a dot row that called itself a
+     tablist with no tabpanels, resting dots at neutral-300 (2.10:1 on the
+     tint, under the 3:1 a control needs), and a setInterval the dots knew
+     nothing about. The atom owns all of that now; the margin is all that is
+     left to decide here. */
+  bd-pagination-dots {
     margin-top: var(--spacing-8);
   }
 
-  .bd-awardsflex-autoplay-toggle {
-    margin-top: var(--spacing-8);
-    padding: var(--spacing-2) var(--spacing-8);
-    background: transparent;
-    border: var(--border-width-1) solid var(--color-border-default);
-    border-radius: var(--radius-full);
-    color: var(--color-text-muted);
-    font-family: var(--typography-fontFamily-sans);
-    /* no role: four roles sit at this size and each fails differently, so the
-       size stays a primitive. Note the weight is not declared here at all --
-       it inherits 400 -- which is why two of these are about what adopting a
-       role would ADD.
-       .
-       caption-default matches every value exactly, including the colour token:
-       xs / 400 / 1.5 / tracking 0 / sans, and its own colour axis is
-       --color-text-muted, which is what this rule already declares two lines
-       up. It renders as the same pixels. It is declined anyway, because
-       vertical-rhythm.stories.js documents it as "text under an image or a
-       figure" and this is the visible label of a toggle button. A
-       five-axis-plus-colour identity is the most seductive form of choosing a
-       role by its value rather than its meaning -- not an exemption from
-       CLAUDE.md's rule against that, but the case the rule is for.
-       .
-       caption-small carries the same wrong meaning and adds
-       letterSpacing-wide, which has no job on a five-letter word.
-       .
-       label-small is the right family -- "a small label: a badge, a tag, a
-       field hint" -- but the wrong result: it would declare a weight of 500
-       where nothing is declared today, and add wide tracking, making the
-       control bolder and 2.2px wider. This control is deliberately recessive:
-       muted, 2px of vertical padding, sitting beside the carousel dots as
-       chrome whose job is not to compete with the quote cards. Adopting a role
-       should not invert that.
-       .
-       control-label-small is the right meaning -- built for the name of a
-       control -- and fails on the leading. See the line below. */
-    font-size: var(--typography-fontSize-xs);
-    /* no role: and this leading in particular cannot move. The line box is
-       18px, which with 2px of padding and a 1px border makes the button
-       exactly 24px -- the same 24px as the .bd-awardsflex-dot buttons it shares
-       a row with, which are 24 square deliberately for the WCAG 2.5.8 target
-       size the comment further down explains.
-       .
-       control-label-small would take the line box to 15px and the button to
-       21px, misaligning it from the dots. Its tight leading exists for controls
-       whose height is DERIVED from padding + fontSize x lineHeight, the way
-       form-field computes one. This button's height is not derived -- it is
-       matched to a sibling. So the constraint is a pixel alignment between two
-       controls in one row, and nothing else in this file says so: a later pass
-       adopting control-label-small on meaning alone would quietly break the
-       row. */
-    line-height: var(--typography-lineHeight-normal);
-    cursor: pointer;
-  }
-
-  .bd-awardsflex-autoplay-toggle:hover {
-    color: var(--color-text-primary);
-    border-color: var(--color-border-strong);
-  }
-
-  .bd-awardsflex-autoplay-toggle:focus-visible {
-    /* the one focus ring — see Foundations/Focus */
-    outline: none;
-    box-shadow: var(--focus-outline-primary);
-    border-radius: var(--focus-outline-radius);
-  }
-
-  /* An 8px dot was an 8px target, which is a third of what WCAG 2.5.8 asks and
-     close enough to its neighbour that the 24px circles would have overlapped
-     as well. The button is the target and the dot is only what you see, so the
-     button is 24 square and the dot is drawn inside it at the size it always
-     was. Nothing about the component looks bigger; the part you can hit does. */
-  .bd-awardsflex-dot {
-    width: var(--dimension-24);
-    height: var(--dimension-24);
-    display: grid;
-    place-items: center;
-    border: none;
-    background: transparent;
-    padding: 0;
-    cursor: pointer;
-  }
-
-  .bd-awardsflex-dot::before {
-    content: "";
-    width: var(--spacing-8);
-    height: var(--spacing-8);
-    border-radius: 50%;
-    background: var(--color-neutral-300);
-    transition: background var(--transition-duration-normal) var(--transition-easing-ease),
-      transform var(--transition-duration-normal) var(--transition-easing-ease);
-  }
-
-  .bd-awardsflex-dot.active::before {
-    /* The current slide's mark, and it takes the indicator role now that the
-       role is not named for a shape. --indicator-color IS blue-500, so nothing
-       moves; what changes is that this dot and the tab/nav underlines can no
-       longer drift apart, which is the reason the role exists.
-       .
-       The geometry stays local on purpose: an underline slides its width, a dot
-       scales, so --indicator-underline-height and its transition are not this
-       component's to borrow. */
-    background: var(--indicator-color);
-    transform: scale(1.2);
-  }
-
-  .bd-awardsflex-dot:focus-visible {
-    /* the one focus ring — see Foundations/Focus. It follows the target, not
-       the dot, so keyboard focus is visible at the size the button really is. */
-    outline: none;
-    box-shadow: var(--focus-outline-primary);
-    border-radius: var(--radius-full);
+  @media (prefers-reduced-motion: reduce) {
+    .bd-awardsflex-carousel-track {
+      transition: none;
+    }
   }
 
   @media ${unsafeCSS(below('sm'))} {
@@ -342,12 +227,29 @@ export const awardsFlexCSS = css`
       min-height: var(--bd-awardsflex-min-height-mobile, 280px);
     }
 
-    .bd-awardsflex-quotes-row,
-    .bd-awardsflex-carousel-slide {
+    /* The static row stacks. The carousel slide does not: below sm it holds
+       one card, and in a column the card's 200px flex-basis became its
+       height. In the row it fills the width and takes its own height. */
+    .bd-awardsflex-quotes-row {
       flex-direction: column;
       align-items: center;
     }
 
+    /* A stacked card is as tall as what it holds. In the column, the card's
+       200px flex-basis became its height and the 160px min-height had nothing
+       left to do -- it keeps cards that stand side by side the same height,
+       and stacked cards stand side by side with nothing. Measured at 390:
+       200px cards whose content ended at 111 and 132. The width is the
+       column's, so a short quote no longer hugs its source line.
+       .
+       The carousel slide keeps the min-height: there it stops the section
+       jumping in height from one slide to the next. */
+    .bd-awardsflex-quotes-row .bd-awardsflex-quote-card {
+      flex: none;
+      width: 100%;
+      min-height: 0;
+    }
+
     .bd-awardsflex-quote-card {
       max-width: none;
     }

package/src/components/awards/awards-flex.js

@@ -10,11 +10,19 @@ import "../icons/pc-mag-readers-icon.js";
 import "../icons/top-product-icon.js";
 import "../heading/heading.js";
 import "../paragraph/paragraph.js";
+import "../pagination-dots/pagination-dots.js";
 import { awardsFlexCSS } from "./awards-flex.css.js";
 import { ensembleCSS } from "../shared/ensemble.css.js";
+import { below } from "../shared/token-scales.js";
 
-
-const GROUP_SIZE = 3; // how many quote cards are visible per carousel page
+/* How many quote cards one carousel slide holds: three side by side, and one
+   below sm. Three used to stack in a column on a phone, so a slide was about
+   1065px tall with every card on screen at once, and the dots paged between
+   two such stacks. One card a slide gives the phone a carousel again -- six
+   awards are six slides and six dots -- at about half the height. Drawn in the
+   foundation Figma file as Awards carousel, breakpoint=mobile. */
+const GROUP_SIZE = 3;
+const GROUP_SIZE_NARROW = 1;
 
 export class AwardsFlex extends LitElement {
   static properties = {
@@ -27,9 +35,10 @@ export class AwardsFlex extends LitElement {
     subtext      : { type: String },
     badges       : { type: Array },
     _slide       : { state: true },
-    _paused      : { state: true },
-    _userStopped : { state: true },
-    _reduceMotion: { state: true }
+    _groupSize   : { state: true },
+    _hovered     : { state: true },
+    _focusWithin : { state: true },
+    _live        : { state: true }
   };
 
   static styles = [tokens, ensembleCSS, awardsFlexCSS];
@@ -45,33 +54,43 @@ export class AwardsFlex extends LitElement {
     this.subtext = "";
     this.badges = [];
     this._slide = 0;
-    this._paused = false;
-    /* Hover/focus pause is transient. A user who presses Stop means it, and
-       must not have it undone by the pointer leaving the carousel — so the two
-       are separate pieces of state. */
-    this._userStopped = false;
-    this._reduceMotion = false;
-    this._timer = null;
+    this._groupSize = GROUP_SIZE;
+    /* The pointer or focus on the slides holds the autoplay -- a hold, which
+       lifts by itself. Stopping it for good is the atom's: a visitor who picks
+       a dot has chosen a slide, and it stays. */
+    this._hovered = false;
+    this._focusWithin = false;
+    /* The slides' live region. Off while they change on their own, so a
+       screen reader is not read a new set of quotes every few seconds; polite
+       once they are still, so a change the visitor asks for is announced.
+       bd-pagination-dots says which, through bd-toggle. */
+    this._live = "polite";
   }
 
   connectedCallback() {
     super.connectedCallback();
-    /* WCAG 2.2.2: content that moves on its own must be pausable, and under
-       prefers-reduced-motion it should not start at all. Watched rather than
-       read once, so a reader who changes the setting is honoured live. */
+    /* Watched rather than read once: a slide is a layout, and a phone turned
+       sideways crosses the breakpoint. */
     if (typeof window !== "undefined" && window.matchMedia) {
-      this._motionQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
-      this._reduceMotion = this._motionQuery.matches;
-      this._onMotionChange = () => { this._reduceMotion = this._motionQuery.matches; };
-      this._motionQuery.addEventListener("change", this._onMotionChange);
+      this._narrowQuery = window.matchMedia(below("sm"));
+      this._onNarrowChange = () => this._setGroupSize(this._narrowQuery.matches ? GROUP_SIZE_NARROW : GROUP_SIZE);
+      this._narrowQuery.addEventListener("change", this._onNarrowChange);
+      this._onNarrowChange();
     }
-    this._maybeStartAutoplay();
   }
 
   disconnectedCallback() {
     super.disconnectedCallback();
-    this._motionQuery?.removeEventListener("change", this._onMotionChange);
-    this._stopAutoplay();
+    this._narrowQuery?.removeEventListener("change", this._onNarrowChange);
+  }
+
+  /* Changing the slide size keeps the visitor on the slide that holds the card
+     they were looking at: its first card, re-paged. */
+  _setGroupSize(size) {
+    if (size === this._groupSize) return;
+    const firstCard = this._slide * this._groupSize;
+    this._groupSize = size;
+    this._slide = Math.floor(firstCard / size);
   }
 
   updated(changed) {
@@ -80,23 +99,20 @@ export class AwardsFlex extends LitElement {
       changed.has("carousel") ||
       changed.has("layout") ||
       changed.has("badges") ||
-      changed.has("_paused") ||
-      changed.has("_userStopped") ||
-      changed.has("_reduceMotion")
+      changed.has("_groupSize")
     ) {
       // if the badge set shrank, make sure the current slide index is still valid
       if (this._slide >= this._slidesCount) {
         this._slide = 0;
       }
-      this._maybeStartAutoplay();
     }
   }
 
   get _groups() {
-    // chunk badges into pages of GROUP_SIZE for the carousel
+    // chunk badges into slides of _groupSize for the carousel
     const groups = [];
-    for (let i = 0; i < this.badges.length; i += GROUP_SIZE) {
-      groups.push(this.badges.slice(i, i + GROUP_SIZE));
+    for (let i = 0; i < this.badges.length; i += this._groupSize) {
+      groups.push(this.badges.slice(i, i + this._groupSize));
     }
     return groups;
   }
@@ -105,52 +121,11 @@ export class AwardsFlex extends LitElement {
     return this.layout === "quotes" ? this._groups.length : 0;
   }
 
-  _maybeStartAutoplay() {
-    this._stopAutoplay();
-    const canAutoplay =
-      this.autoplay &&
-      this.carousel &&
-      this.layout === "quotes" &&
-      this._slidesCount > 1 &&
-      !this._paused &&
-      !this._userStopped &&
-      !this._reduceMotion;
-
-    if (!canAutoplay) return;
-
-    this._timer = setInterval(() => {
-      this._slide = (this._slide + 1) % this._slidesCount;
-    }, Math.max(1000, this.autoplayDelay));
-  }
-
-  _stopAutoplay() {
-    if (this._timer) {
-      clearInterval(this._timer);
-      this._timer = null;
-    }
-  }
-
-  _onMouseEnter() {
-    if (this.autoplay) this._paused = true;
-  }
-
-  _onMouseLeave() {
-    if (this.autoplay) this._paused = false;
-  }
-
-  _toggleAutoplay() {
-    this._userStopped = !this._userStopped;
-  }
-
-  /** True when the carousel is actually able to move on its own. */
+  /** True when the carousel is able to move on its own. */
   get _autoplayOffered() {
     return this.autoplay && this.carousel && this.layout === "quotes" && this._slidesCount > 1;
   }
 
-  _goTo(i) {
-    this._slide = i;
-  }
-
   _iconHeight() {
     if (this.layout === "grid") return 64;
     if (this.layout === "quotes") return 56;
@@ -202,48 +177,22 @@ export class AwardsFlex extends LitElement {
     `;
   }
 
-  /**
-   * The pause/stop control WCAG 2.2.2 requires of anything that starts moving
-   * on its own and keeps going. Hovering or focusing the carousel already
-   * paused it, but that is not a mechanism a keyboard or touch user can rely
-   * on, and it cannot express "leave it stopped".
-   *
-   * Its name states the action it performs, which is what a screen reader
-   * announces on focus. It sits beside the dots rather than inside them: that
-   * container is a tablist and a plain button is not a valid child of one.
-   */
-  _renderAutoplayToggle() {
-    if (!this._autoplayOffered) return nothing;
-    const stopped = this._userStopped || this._reduceMotion;
-    return html`
-      <button
-        type="button"
-        class="bd-awardsflex-autoplay-toggle"
-        @click=${this._toggleAutoplay}
-        aria-label=${stopped ? "Play slideshow" : "Pause slideshow"}
-      >${stopped ? "Play" : "Pause"}</button>
-    `;
-  }
-
+  /* bd-pagination-dots, which runs the clock too, so the progress in the
+     current pill and the change of slide are one thing. WCAG 2.2.2's way to
+     stop it is the dots themselves: picking one stops autoplay for good. */
   _renderDots() {
     if (!this.carousel || this._slidesCount < 2) return nothing;
     return html`
-      <div class="bd-awardsflex-controls">
-      <div class="bd-awardsflex-dots" role="tablist" aria-label="Slide navigation">
-        ${this._groups.map(
-          (_, i) => html`
-            <button
-              class="bd-awardsflex-dot ${i === this._slide ? "active" : ""}"
-              role="tab"
-              aria-selected="${i === this._slide}"
-              aria-label="Go to page ${i + 1}"
-              @click=${() => this._goTo(i)}
-            ></button>
-          `
-        )}
-      </div>
-      ${this._renderAutoplayToggle()}
-      </div>
+      <bd-pagination-dots
+        count=${this._slidesCount}
+        current=${this._slide + 1}
+        label="Awards"
+        ?autoplay=${this._autoplayOffered}
+        delay=${this.autoplayDelay}
+        ?held=${this._hovered || this._focusWithin}
+        @bd-change=${e => { this._slide = e.detail.current - 1; }}
+        @bd-toggle=${e => { this._live = e.detail.moving ? "off" : "polite"; }}
+      ></bd-pagination-dots>
     `;
   }
 
@@ -252,18 +201,19 @@ export class AwardsFlex extends LitElement {
     return html`
       <div
         class="bd-awardsflex-carousel-viewport"
-        @mouseenter=${this._onMouseEnter}
-        @mouseleave=${this._onMouseLeave}
-        @focusin=${this._onMouseEnter}
-        @focusout=${this._onMouseLeave}
+        @mouseenter=${() => { this._hovered = true; }}
+        @mouseleave=${() => { this._hovered = false; }}
+        @focusin=${() => { this._focusWithin = true; }}
+        @focusout=${e => { this._focusWithin = e.currentTarget.contains(e.relatedTarget); }}
       >
         <div
           class="bd-awardsflex-carousel-track"
           style="transform: translateX(${offset}%);"
+          aria-live=${this._live}
         >
           ${this._groups.map(
-            (group) => html`
-              <div class="bd-awardsflex-carousel-slide">
+            (group, i) => html`
+              <div class="bd-awardsflex-carousel-slide" ?inert=${i !== this._slide}>
                 ${group.map((a) => this._renderQuoteCard(a))}
               </div>
             `

package/src/components/awards/awards-flex.stories.js

@@ -22,9 +22,11 @@ Badges render real icon components from \`components/icons\` (e.g. \`<bd-pc-mag-
 \`<bd-av-comparatives-icon>\`) — pass the icon's slug via the \`icon\` field on each badge
 object, and \`AwardsFlex\` maps it to the matching \`<bd-*-icon>\` custom element internally.
 
-When \`layout="quotes"\` and \`carousel\` is set, badges are paginated 3 per page. With 6
-badges that's 2 pages, with 9 badges 3 pages, and so on — the carousel slides a full page
-of 3 cards at a time.
+When \`layout="quotes"\` and \`carousel\` is set, badges are paginated 3 per slide, and
+1 per slide below the \`sm\` breakpoint (576px). With 6 badges that's 2 slides on a wide
+screen and 6 on a phone — the dots follow the count. The carousel slides a full slide at
+a time; crossing the breakpoint keeps the visitor on the slide that holds the card they
+were looking at.
 
 ### Usage
 \`\`\`html
@@ -45,7 +47,7 @@ of 3 cards at a time.
 |-------------------|------------------------------------|-------------|----------------------------------------------------------------------|
 | \`background\`      | \`"white" \\| "tint"\`               | \`"white"\`   | Section background                                                  |
 | \`layout\`          | \`"compact" \\| "grid" \\| "quotes"\` | \`"compact"\` | Badge size/arrangement, or badges paired with quote cards            |
-| \`carousel\`        | Boolean                           | \`false\`     | Only for \`layout="quotes"\` — paginate 3 cards at a time             |
+| \`carousel\`        | Boolean                           | \`false\`     | Only for \`layout="quotes"\` — 3 cards a slide, 1 below \`sm\`        |
 | \`autoplay\`        | Boolean                           | \`false\`     | Auto-advance carousel pages. Requires \`carousel\` + \`layout="quotes"\` and 2+ pages (7+ badges is unnecessary — 2 pages start at 4 badges) |
 | \`autoplay-delay\`  | Number (ms)                       | \`4000\`      | Time between auto-advances. Minimum enforced: 1000ms                 |
 | \`headline\`        | String                            | \`""\`        | Optional heading                                                    |
@@ -86,7 +88,7 @@ Autoplay pauses automatically on mouse hover or keyboard focus within the carous
     },
     carousel: {
       control    : "boolean",
-      description: "Paginate quote cards 3 at a time (layout=\"quotes\" only)",
+      description: "Paginate quote cards 3 a slide, 1 below sm (layout=\"quotes\" only)",
       table      : { category: "Appearance" }
     },
     autoplay: {
@@ -170,7 +172,7 @@ const threeBadgesWithQuotes = [
   }
 ];
 
-// Six badges with quotes — needed so the carousel has 2+ pages (3 cards per page)
+// Six badges with quotes — needed so the carousel has 2+ slides (3 a slide, 1 below sm)
 const sixBadgesWithQuotes = [
   ...threeBadgesWithQuotes,
   {

package/src/components/back/back.css.js

@@ -47,7 +47,12 @@ export default css`
        4px for as long as it was focused. That token is the default for
        elements with no radius, which is what Foundations/Focus says. */
     .bd-back:focus-visible {
-      outline: none;
+      /* forced-colors mode does not paint box-shadow, so the ring
+         vanishes there; it does paint an outline, in a system colour. This one
+         is transparent everywhere else, and the offset lands it on the ring's
+         outer band. */
+      outline: var(--border-width-2) solid transparent;
+      outline-offset: var(--focus-outline-offset);
       box-shadow: var(--focus-outline-primary);
     }
 

package/src/components/back/back.js

@@ -30,27 +30,39 @@ export class BdBack extends LitElement {
     this.ariaLabel = null;
   }
 
+  /** Without an href there is no destination to link to, only history. */
   handleClick() {
-    if (this.href) {
-      window.location.href = this.href;
-    } else {
-      window.history.back();
-    }
+    window.history.back();
   }
 
+  /* A real link when there is somewhere to go. With href this used to be a
+     <button> that set window.location.href on click, so the destination was
+     invisible to everything that reads links: no middle-click or
+     Cmd/Ctrl-click into a new tab, no "copy link", no status-bar URL, and a
+     screen reader announced a button and listed it under none of the page's
+     links. Without href it stays a button, because history.back() is an
+     action, not a place. */
   render() {
-    return html`
+    const content = html`<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" aria-hidden="true" class="mi-solid mi-arrow-back" viewBox="0 0 24 24">
+  <path d="M19 11H7.83l4.88-4.88c.39-.39.39-1.03 0-1.42a.996.996 0 0 0-1.41 0l-6.59 6.59a.996.996 0 0 0 0 1.41l6.59 6.59a.996.996 0 1 0 1.41-1.41L7.83 13H19c.55 0 1-.45 1-1s-.45-1-1-1"/>
+</svg>
+      <span class="bd-back-label">${this.label}</span>`;
+
+    return this.href
+      ? html`
+    <a
+      class="bd-back"
+      href="${this.href}"
+      aria-label="${this.ariaLabel ?? nothing}"
+    >${content}</a>
+  `
+      : html`
     <button
       type="button"
       class="bd-back"
       aria-label="${this.ariaLabel ?? nothing}"
       @click="${this.handleClick}"
-    >
-<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" aria-hidden="true" class="mi-solid mi-arrow-back" viewBox="0 0 24 24">
-  <path d="M19 11H7.83l4.88-4.88c.39-.39.39-1.03 0-1.42a.996.996 0 0 0-1.41 0l-6.59 6.59a.996.996 0 0 0 0 1.41l6.59 6.59a.996.996 0 1 0 1.41-1.41L7.83 13H19c.55 0 1-.45 1-1s-.45-1-1-1"/>
-</svg>
-      <span class="bd-back-label">${this.label}</span>
-    </button>
+    >${content}</button>
   `;
   }
 

package/src/components/back/back.stories.js

@@ -20,8 +20,8 @@ export default {
 \`\`\`
 
 ### Behavior
-- If \`href\` is provided, clicking navigates to that URL via \`window.location.href\`
-- If \`href\` is empty, clicking calls \`window.history.back()\`
+- If \`href\` is provided, it renders a real link to that URL, so it opens in a new tab, can be copied, and is announced as a link
+- If \`href\` is empty, it renders a button that calls \`window.history.back()\`
 - Always renders a left-pointing arrow SVG icon alongside the label
         `
       }
@@ -69,7 +69,7 @@ export const WithHref = {
   parameters: {
     docs: {
       description: {
-        story: '`href` is set to `/`. Clicking navigates to the home page via `window.location.href`.'
+        story: '`href` is set to `/`, so it renders a link to the home page.'
       }
     }
   }

package/src/components/badge/badge.js

@@ -71,12 +71,15 @@ export class BdBadge extends LitElement {
     if (!this.icon || this.mode === 'dot') return '';
 
     // currentColor makes the icon follow the tone's text colour, so there is
-    // no per-tone icon colour to keep in step
+    // no per-tone icon colour to keep in step.
+    // size is a step on the icon scale, not pixels. This said size="16", which
+    // is no step, so both icons fell back to the xl they were drawn at and a
+    // badge with an icon measured 40px tall beside 23px ones; sm is the 16.
     switch (this.icon) {
       case 'individual':
-        return html`<bd-individual-icon size="16" color="currentColor"></bd-individual-icon>`;
+        return html`<bd-individual-icon size="sm" color="currentColor"></bd-individual-icon>`;
       case 'family':
-        return html`<bd-family-icon size="16" color="currentColor"></bd-family-icon>`;
+        return html`<bd-family-icon size="sm" color="currentColor"></bd-family-icon>`;
       default:
         return '';
     }