@repobit/dex-system-design 1.0.1 → 2.0.0

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 '';
     }

package/src/components/badge/badge.stories.js

@@ -1,7 +1,7 @@
 import { html } from 'lit';
 import './badge.js';
 
-const TONES    = ['default', 'primary', 'success', 'warning', 'error', 'info'];
+const TONES    = ['neutral', 'brand', 'success', 'warning', 'error', 'info'];
 const SIZES    = ['sm', 'md', 'lg'];
 const VARIANTS = ['shade', 'fill'];
 
@@ -35,10 +35,10 @@ matched to the token that already carries it.
 ### Usage
 \`\`\`html
 <bd-badge tone="success" variant="shade">Save 44%</bd-badge>
-<bd-badge tone="primary" variant="fill" size="sm">New</bd-badge>
+<bd-badge tone="brand" variant="fill" size="sm">New</bd-badge>
 <bd-badge mode="count" tone="error" variant="fill">3</bd-badge>
 <bd-badge mode="dot" tone="warning" variant="fill"></bd-badge>
-<bd-badge tone="primary" variant="fill" icon="family">Family Pack</bd-badge>
+<bd-badge tone="brand" variant="fill" icon="family">Family Pack</bd-badge>
 \`\`\`
 
 ### Props
@@ -46,7 +46,7 @@ matched to the token that already carries it.
 |---|---|---|
 | \`mode\` | \`text\`, \`dot\`, \`count\` | \`text\` |
 | \`size\` | \`sm\`, \`md\`, \`lg\` | \`md\` |
-| \`tone\` | \`default\`, \`primary\`, \`success\`, \`warning\`, \`error\`, \`info\` | \`default\` |
+| \`tone\` | \`neutral\`, \`brand\`, \`success\`, \`warning\`, \`error\`, \`info\` | \`neutral\` |
 | \`variant\` | \`shade\`, \`fill\` | \`shade\` |
 | \`icon\` | \`individual\`, \`family\`, \`''\` | \`''\` |
 | \`label\` | any string — accessible name for \`mode="dot"\` | tone name |
@@ -107,7 +107,7 @@ matched to the token that already carries it.
       control    : { type: 'select' },
       options    : TONES,
       description: 'Semantic colour pairing.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: 'default' }, category: 'Appearance' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'neutral' }, category: 'Appearance' }
     },
     variant: {
       control    : { type: 'inline-radio' },
@@ -135,7 +135,7 @@ matched to the token that already carries it.
   args: {
     mode   : 'text',
     size   : 'md',
-    tone   : 'default',
+    tone   : 'neutral',
     variant: 'shade',
     icon   : '',
     label  : '',
@@ -172,7 +172,7 @@ export const Sizes = {
   render    : () => html`
     ${VARIANTS.map(variant => html`
       ${row(variant, SIZES.map(size => html`
-        <bd-badge size="${size}" tone="primary" variant="${variant}">${size}</bd-badge>
+        <bd-badge size="${size}" tone="brand" variant="${variant}">${size}</bd-badge>
       `))}
     `)}
   `
@@ -212,7 +212,7 @@ export const WithIcon = {
       <bd-badge tone="success" icon="family">Family Pack</bd-badge>
     `)}
     ${row('fill', html`
-      <bd-badge variant="fill" tone="primary" icon="individual">Individual</bd-badge>
+      <bd-badge variant="fill" tone="brand" icon="individual">Individual</bd-badge>
       <bd-badge variant="fill" tone="success" icon="family">Family Pack</bd-badge>
     `)}
   `
@@ -220,11 +220,15 @@ export const WithIcon = {
 
 export const Legacy = {
   name      : 'Legacy variants',
-  parameters: { docs: { description: { story: 'Pre-`ds-badge` markup still renders, mapped onto the new axes.' } } },
+  parameters: { docs: { description: { story: 'Pre-`ds-badge` markup still renders, mapped onto the new axes: the old variants, and the two retired tone names, `default` (now `neutral`) and `primary` (now `brand`). Write the new names; these are here so a page still using the old ones is shown to work.' } } },
   render    : () => html`
     ${row('mapped', html`
       <bd-badge variant="bd-light-blue">bd-light-blue</bd-badge>
       <bd-badge variant="bd-light-green">bd-light-green</bd-badge>
     `)}
+    ${row('tones', html`
+      <bd-badge tone="default">tone="default" → neutral</bd-badge>
+      <bd-badge tone="primary">tone="primary" → brand</bd-badge>
+    `)}
   `
 };

package/src/components/bento-grid/bento-grid.js

@@ -220,7 +220,7 @@ class BentoGrid extends LitElement {
             <div class="bd-bentogrid-header">
               ${this.eyebrow
                 ? html`
-                    <bd-p variant="regular" class="bd-bentogrid-eyebrow">
+                    <bd-p variant="eyebrow" class="bd-bentogrid-eyebrow">
                       <slot name="eyebrow">${this.eyebrow}</slot>
                     </bd-p>
                   `

package/src/components/blockquote/blockquote.css.js

@@ -4,8 +4,17 @@ import { css } from 'lit';
 export const blockquoteCSS = css`
   :host { display: block; }
 
+  /* .quote is the outer element: the <figure> when there is an attribution,
+     the bare <blockquote> when there is not. The bar and the type live on it,
+     so the caption inherits the quotation's family and leading the way the
+     <footer> did when it sat inside the <blockquote> -- the rhythm the note
+     below is about. */
+  figure,
   blockquote {
     margin: 0;
+  }
+
+  .quote {
     padding-left: var(--spacing-16);
     border-left: var(--border-width-4) solid var(--color-border-brand);
     font-family: var(--typography-body-large-fontFamily);
@@ -15,7 +24,7 @@ export const blockquoteCSS = css`
     color: var(--color-text-primary);
   }
 
-  footer {
+  figcaption {
     margin-top: var(--spacing-8);
     font-size: var(--typography-caption-default-fontSize);
     /* no role: two roles are each a near-miss, from opposite directions, and
@@ -24,8 +33,8 @@ export const blockquoteCSS = css`
        .
        label-small matches this text's size and weight exactly -- but adopting
        it would add letterSpacing-wide, which has no job on mixed-case sentence
-       text because nothing here crowds, and would replace the 1.625 leading
-       this inherits from the quote it attributes with 1.5. That inherited
+       text because nothing here crowds, and would replace the leading this
+       inherits from the quote it attributes with 1.5. That inherited
        rhythm is the one thing in this rule that means something: the credit
        line sits on the same measure as the quotation it belongs to, where 1.5
        merely comes attached to the role.

package/src/components/blockquote/blockquote.js

@@ -17,12 +17,19 @@ export class BdBlockquote extends LitElement {
     this.attribution = '';
   }
 
+  /* WHERE THE ATTRIBUTION GOES.
+     It used to be a <footer> inside the <blockquote>, and everything inside a
+     blockquote is the quotation, so the name of the person quoted was read as
+     part of what they said. The HTML spec's pattern puts the credit outside
+     the quote: a <figure> holding the <blockquote> and a <figcaption>. With
+     no attribution there is no caption, so the bare <blockquote> renders, as
+     before -- a figure with nothing to name it would only add an empty
+     "figure" for a screen reader to step through. */
   render() {
-    return html`
-      <blockquote cite=${this.cite || nothing}>
-        <slot></slot>${this.attribution ? html`<footer>\u2014 ${this.attribution}</footer>` : nothing}
-      </blockquote>
-    `;
+    const quote = html`<blockquote class=${this.attribution ? nothing : 'quote'} cite=${this.cite || nothing}><slot></slot></blockquote>`;
+    return this.attribution
+      ? html`<figure class="quote">${quote}<figcaption>\u2014 ${this.attribution}</figcaption></figure>`
+      : quote;
   }
 }
 

package/src/components/blockquote/blockquote.stories.js

@@ -28,9 +28,11 @@ optional attribution.
 | \`cite\` | URL of the source | \`''\` |
 
 ### Notes
-\`attribution\` renders as a \`<footer>\` inside the \`<blockquote>\`, prefixed with
-an em dash. That is the pairing the HTML spec recommends for a credit that
-belongs to the quote itself.
+\`attribution\` renders as a \`<figcaption>\`, prefixed with an em dash, beside
+the \`<blockquote>\` inside a \`<figure>\`. That is the HTML spec's pattern for
+crediting a quotation: everything inside a \`<blockquote>\` is the quote, so the
+name of the person quoted belongs outside it. Without an attribution there is
+no figure, only the \`<blockquote>\`.
 
 \`cite\` maps to the native \`cite\` attribute. It is **metadata only** — browsers
 do not render it and it is not a link, so if the source should be visible or
@@ -42,7 +44,7 @@ clickable, put it in \`attribution\` or in the slotted content.
   argTypes: {
     attribution: {
       control    : 'text',
-      description: 'Who said it. Renders as a footer inside the blockquote, prefixed with an em dash.',
+      description: 'Who said it. Renders as a figcaption beside the blockquote in a figure, prefixed with an em dash.',
       table      : { type: { summary: 'string' }, defaultValue: { summary: "" }, category: 'Content' }
     },
     cite: {