@repobit/dex-system-design 0.25.12 → 1.0.0

package/src/components/video-player/video-player.css.js

@@ -14,7 +14,7 @@ export default css`
     border: none;
     background: none;
     cursor: pointer;
-    border-radius: var(--radius-lg, 16px);
+    border-radius: var(--radius-lg);
     overflow: hidden;
   }
 
@@ -22,8 +22,8 @@ export default css`
     width: 100%;
     height: auto;
     display: block;
-    border-radius: var(--radius-lg, 16px);
-    transition: transform 300ms ease;
+    border-radius: var(--radius-lg);
+    transition: transform var(--transition-duration-slow) var(--transition-easing-ease);
   }
 
   .bd-video-thumb:hover img {
@@ -39,7 +39,7 @@ export default css`
     height: 64px;
     pointer-events: none;
     filter: drop-shadow(0 4px 12px rgba(0,0,0,0.3));
-    transition: transform 300ms ease;
+    transition: transform var(--transition-duration-slow) var(--transition-easing-ease);
   }
 
   .bd-video-thumb:hover .bd-video-play-btn {
@@ -55,9 +55,12 @@ export default css`
     position: relative;
     width: 100%;
     padding-bottom: 56.25%;
-    border-radius: var(--radius-lg, 16px);
+    border-radius: var(--radius-lg);
     overflow: hidden;
-    background: var(--color-neutral-900);
+    /* The media frame, --color-surface-media: around a video, dark in every theme.
+       This read --color-surface-inverse until dark mode decision 15 -- the
+       polarity flip, which would turn a letterbox light in a dark theme. */
+    background: var(--color-surface-media);
   }
 
   .bd-video-player iframe,
@@ -78,18 +81,71 @@ export default css`
     height: 32px;
     border-radius: 50%;
     border: none;
-    background: rgba(0,0,0,0.6);
-    color: white;
+    /* no role: NOT a scrim, though it looks like one next to the modal's. This
+       is the close button's own ground -- a 32px circle that has to carry a
+       white glyph over whatever frame the video happens to be showing, so the
+       darkness is doing contrast work for the icon rather than dimming content
+       behind a dialog. Two declarations, one control, no role.
+       .
+       Mixed over the palette rather than written as a raw rgba, for the same
+       reason as the modal's scrim: this follows --color-neutral-1000 where a
+       literal black follows nothing. Pixel-identical to the rgba it replaces. */
+    background: color-mix(in srgb, var(--color-neutral-1000) 60%, transparent);
+    color: var(--color-text-on-media);
     font-size: 16px;
     cursor: pointer;
     display: flex;
     align-items: center;
     justify-content: center;
-    z-index: 10;
-    transition: background 150ms ease;
+    /* Above the video surface it sits on; nothing else in this shadow root
+       is positioned. */
+    z-index: var(--z-raised);
+    transition: background var(--transition-duration-fast) var(--transition-easing-ease);
   }
 
   .bd-video-close:hover {
-    background: rgba(0,0,0,0.9);
+    /* no role: the same control ground at 90% under the pointer -- it gets more
+       opaque rather than changing hue. Same reasoning as the rest state above,
+       and no role for the same reason. Pixel-identical to the rgba it
+       replaces. */
+    background: color-mix(in srgb, var(--color-neutral-1000) 90%, transparent);
+  }
+
+  /* The one focus ring, on both controls. This sheet had no :focus-visible
+     rule at all, so the two buttons fell back to the browser's outline:
+     measured on the thumbnail with a real Tab, outline 1px auto
+     rgb(0, 95, 204) and box-shadow none, where every other control in this
+     package draws --focus-outline-primary. The two-colour ring also matters
+     more here than most places -- the close button sits on video, so a
+     single-colour outline has no guaranteed ground to contrast against, and
+     the white inner band is what makes it visible on any frame.
+
+     The ring follows each control's own shape: the thumbnail keeps its
+     --radius-lg corner and the close button is a circle. */
+  .bd-video-thumb:focus-visible,
+  .bd-video-close:focus-visible {
+    outline: none;
+    box-shadow: var(--focus-outline-primary);
+  }
+
+  /* The thumbnail lifts on hover and the play mark grows. Measured before
+     this: with prefers-reduced-motion: reduce both still reported a 0.3s
+     transition, so the scale ran for a reader who asked for less motion.
+     The transform is dropped as well as the transition -- a scale that
+     arrives instantly is still motion the reader did not ask for. */
+  @media (prefers-reduced-motion: reduce) {
+    .bd-video-thumb img,
+    .bd-video-play-btn,
+    .bd-video-close {
+      transition: none;
+    }
+
+    .bd-video-thumb:hover img {
+      transform: none;
+    }
+
+    .bd-video-thumb:hover .bd-video-play-btn {
+      transform: translate(-50%, -50%);
+    }
   }
 `;

package/src/components/video-player/video-player.js

@@ -1,5 +1,7 @@
 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 "../icons/close-icon.js";
 import videoPlayerCSS from "./video-player.css.js";
 
 class BdVideoPlayer extends LitElement {
@@ -10,7 +12,7 @@ class BdVideoPlayer extends LitElement {
     _open   : { state: true }
   };
 
-  static styles = [tokens, videoPlayerCSS];
+  static styles = [videoPlayerCSS];
 
   constructor() {
     super();
@@ -24,12 +26,39 @@ class BdVideoPlayer extends LitElement {
     return this.src.includes("youtube.com") || this.src.includes("youtu.be");
   }
 
+  /**
+   * Opening replaces the thumbnail button with the player, which destroys the
+   * element that had focus. Measured with a real keyboard: Tab to the
+   * thumbnail, Enter, and document.activeElement was body -- the keyboard user
+   * was dropped to the top of the document by the act of pressing Play.
+   *
+   * Focus goes to the close button, which is the one control this component
+   * owns once the player is up. That also answers a reachability problem it
+   * would otherwise have: the close button follows the iframe in DOM order, so
+   * reaching it by Tab means traversing the embedded player's own tab stops
+   * first -- measured, six Tabs after opening never left the iframe. Landing on
+   * it directly means the way out is the first thing the keyboard has.
+   *
+   * Only when there is a thumbnail: without one the component renders the
+   * player immediately, owns no close button, and nothing has been displaced.
+   */
   _openVideo() {
     this._open = true;
+    if (!this.thumb) return;
+    this.updateComplete.then(() => {
+      this.renderRoot?.querySelector(".bd-video-close")?.focus();
+    });
   }
 
+  /**
+   * Closing destroys the close button the same way, so focus returns to the
+   * thumbnail it came from.
+   */
   _closeVideo() {
     this._open = false;
+    this.updateComplete.then(() => {
+      this.renderRoot?.querySelector(".bd-video-thumb")?.focus();
+    });
   }
 
   render() {
@@ -61,7 +90,9 @@ class BdVideoPlayer extends LitElement {
                   class="bd-video-close"
                   @click=${this._closeVideo}
                   aria-label="Close video"
-                >✕</button>
+                >
+                  <bd-close-icon size="xs" aria-hidden="true"></bd-close-icon>
+                </button>
               `
             : ""}
         </div>
@@ -82,7 +113,7 @@ class BdVideoPlayer extends LitElement {
         <span class="bd-video-play-btn" aria-hidden="true">
           <svg viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
             <circle cx="32" cy="32" r="32" fill="white" fill-opacity="0.9"/>
-            <path d="M26 20L46 32L26 44V20Z" fill="#006DFF"/>
+            <path d="M26 20L46 32L26 44V20Z" fill="var(--color-blue-500)"/>
           </svg>
         </span>
       </button>

package/src/components/video-player/video-player.stories.js

@@ -136,7 +136,7 @@ export const YouTubeAutoplayVideo = {
 export const DifferentThumbnails = {
   name  : 'Different Thumbnails',
   render: () => html`
-    <div style="display:grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 24px; max-width: 1200px; margin: 0 auto; padding: 20px;">
+    <div style="display:grid; grid-template-columns: repeat(auto-fill, minmax(min(300px, 100%), 1fr)); gap: 24px; max-width: 1200px; margin: 0 auto; padding: 20px;">
       <div>
         <h4 style="margin-bottom: 8px;">Thumbnail 1</h4>
         <bd-video-player 

package/src/components/visual-alignment.stories.js

@@ -0,0 +1,411 @@
+import { html } from 'lit';
+
+import './alert/alert.js';
+import './anchor/anchor-nav.js';
+import './back/back.js';
+import './badge/badge.js';
+import './bento-grid/bento-item.js';
+import './breadcrumb/breadcrumb.js';
+import './card-features/card-features.js';
+import './cards/card.js';
+import './carousel/carousel.js';
+import './compare/compare.js';
+import './divider/divider-vertical.js';
+import './footer/footer-nav-menu.js';
+import './heading/heading.js';
+import './light-carousel/light-carousel.js';
+import './page-switcher/page-switcher.js';
+import './paragraph/paragraph.js';
+import './tab-list/tab-list.js';
+import './tag/tag.js';
+import { tabListCSS } from './tab-list/tab-list.css.js';
+
+/**
+ * Composed components rendered next to the components they are supposed to
+ * agree with.
+ *
+ * `Atoms/Control Alignment` does this for atoms and says why: the lint can
+ * prove every value came from a token and still cannot prove two components
+ * ended up looking the same. The same gap exists a layer up, and it is where
+ * the section title came to mean 48, 36, 32 and 24 at once, and where one card
+ * in the family kept a corner the other five had stopped using.
+ *
+ * These exist to be looked at. Nothing here is a usage example — do not copy
+ * these compositions into a page.
+ */
+export default {
+  title     : 'Foundations/Visual Alignment',
+  tags      : ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs  : {
+      description: {
+        component: `
+Cross-component comparisons. Each story puts components that share a visual
+role in one frame, so the system can be judged as a system.
+
+Read each one by asking whether these look like they came from the same place.
+Where they do not, the difference is either a decision or a finding — and the
+point of the story is that you can tell which.
+        `
+      }
+    }
+  }
+};
+
+const label = text => html`
+  <p style="margin:0 0 var(--spacing-8);font:var(--typography-fontWeight-semibold) var(--typography-fontSize-xs)/1.4 var(--typography-fontFamily-mono);color:var(--color-text-muted)">
+    ${text}
+  </p>`;
+
+/* Several of these components carry their own fixed width -- the carousel item
+   is 350px -- so a row of them is wider than a phone no matter how it wraps.
+   It scrolls inside its own container rather than taking the page with it,
+   which is what this package already does for wide reference tables. */
+const row = children => html`
+  <div style="overflow-x:auto">
+    <div style="display:flex;flex-wrap:wrap;gap:var(--spacing-24);align-items:flex-start;min-width:min-content">
+      ${children}
+    </div>
+  </div>`;
+
+const cell = (name, node) => html`
+  <div style="flex:0 1 auto;min-width:0">${label(name)}${node}</div>`;
+
+/* ---------------------------------------------------------------- cards --- */
+
+export const CardFamily = {
+  name  : 'Card family',
+  render: () => html`
+    <p style="max-width:70ch;color:var(--color-text-secondary)">
+      Every card in the family sits on <code>--color-surface-container</code> with
+      32px of padding and no resting shadow, and none of them draws an edge. Every
+      cell below measures the same at desktop width: 16px corner, no border, 32px
+      inset. This page used to exist because they differed.
+    </p>
+    <p style="max-width:70ch;color:var(--color-text-secondary)">
+      <b>The inset holds at every width.</b> LightCarousel used to be the one exception,
+      dropping its padding to 1.5em at 1024 and 1em at 480 while every other card held
+      <code>--spacing-32</code> — so at this page's own default viewport that cell
+      measured 24px, not 32. It was never a decision, just two em literals carried
+      forward, and it is gone. A card in a narrowing track is still a card: the track
+      gives way, not the card's own breathing room.
+    </p>
+    <p style="max-width:70ch;color:var(--color-text-secondary)">
+      Whether a card has an edge is no longer a component decision. It follows from
+      what the card sits on — no edge on the page ground, where the tonal step is the
+      separation; an edge on a tinted section, where no tonal step is available. See
+      <i>A card's ground and its edge</i> in the package README, and
+      <code>Foundations/Surfaces</code>. The two cards that drew an edge on the page
+      ground — Bento and the Carousel item — dropped it under that rule. Interactivity
+      never predicted an edge and still does not.
+    </p>
+    ${row(html`
+      ${cell('bd-card-item · 16px, no border', html`
+        <bd-card-item title="Machine Learning">
+          <bd-p variant="small">Behaviour learned from millions of daily threats.</bd-p>
+        </bd-card-item>`)}
+      ${cell('bd-card-features-item · 16px, no border', html`
+        <bd-card-features-item title="Scam Copilot">
+          <bd-p variant="small">Behaviour learned from millions of daily threats.</bd-p>
+        </bd-card-features-item>`)}
+      ${cell('bd-light-carousel-item · 16px, no border', html`
+        <bd-light-carousel-item title="Machine Learning">
+          <bd-p variant="small">Behaviour learned from millions of daily threats.</bd-p>
+        </bd-light-carousel-item>`)}
+      ${cell('bd-bento-item · 16px, no border — was 1px', html`
+        <bd-bento-item title="Machine Learning">
+          <bd-p variant="small">Behaviour learned from millions of daily threats.</bd-p>
+        </bd-bento-item>`)}
+      ${cell('bd-carousel-item · 16px, no border — was 24px and 2px', html`
+        <bd-carousel-item title="Machine Learning" modalText="Opens a modal.">
+          <bd-p variant="small">Behaviour learned from millions of daily threats.</bd-p>
+        </bd-carousel-item>`)}
+      ${cell('compare-card · 16px, no border — was 24px', html`
+        <compare-card
+          title="Best Protection"
+          description="Scale of 0-6. Higher is better."
+        ></compare-card>`)}
+    `)}`,
+  parameters: {
+    docs: {
+      description: {
+        story: `Nothing differs any more, and the two that used to are worth keeping
+                on the page for the reasons they gave.
+
+                The compare card had no argument: same surface, same inset, no elevation,
+                no card-level interaction, no recorded reason. It went first.
+
+                The carousel item did have one — it is draggable and its plus button opens
+                a modal, where the others are static — and it went anyway. Behaviour earns
+                a state, a cue or a control; it does not earn a different corner. The
+                question the two of them settle is what counts as a reason to leave a
+                family, and behaving differently turned out not to be enough on its own.`
+      }
+    }
+  }
+};
+
+/* ----------------------------------------------------------- section titles - */
+
+export const SectionTitles = {
+  name  : 'Section title roles',
+  render: () => html`
+    <p style="max-width:70ch;color:var(--color-text-secondary)">
+      Two roles, and the question that picks between them: would the page still make
+      sense with this title deleted and its content left in place? If not it is
+      anchoring a region, and it is a page section.
+    </p>
+    <div style="display:grid;gap:var(--spacing-40);max-width:80ch">
+      <div>
+        ${label('PAGE SECTION · bd-h visual-level="h2" · 36/700')}
+        <bd-h as="h2" visual-level="h2">What is AI Guardian?</bd-h>
+        <bd-p variant="small">Overview, Process Steps, Trust Panel, Comparison Panel.</bd-p>
+      </div>
+      <div>
+        ${label('COMPONENT SECTION · bd-h visual-level="h3" · 32/600')}
+        <bd-h as="h2" visual-level="h3">Need help? We have answers.</bd-h>
+        <bd-p variant="small">LightCarousel, CardFeatures, Awards, Tabs, Terms.</bd-p>
+      </div>
+      <div>
+        ${label('ITEM TITLE · bd-h visual-level="h5" fontWeight="bold" · 20/700')}
+        <bd-h as="h3" visual-level="h5" fontWeight="bold">Machine Learning</bd-h>
+        <bd-p variant="small">The title of one card inside a collection.</bd-p>
+      </div>
+      <div>
+        ${label('LONG TITLE · the component section, wrapping')}
+        <bd-h as="h2" visual-level="h3">
+          A section title long enough to wrap onto a second and very probably a third line
+        </bd-h>
+      </div>
+    </div>`,
+  parameters: {
+    docs: {
+      description: {
+        story: `The level and the size are separate: every heading here is semantically
+                what its position requires, and visually what its responsibility requires.
+                Two components render a section title at 48/700 — the card section and the
+                hero — and both are recorded P4 exceptions rather than a third role.`
+      }
+    }
+  }
+};
+
+/* -------------------------------------------------------------- navigation - */
+
+const NAV_ITEMS = [
+  { title: 'AI Guardian', href: '#one', active: true },
+  { title: 'Skill Scanner', href: '#two' }
+];
+
+export const NavigationStates = {
+  name  : 'Navigation current state',
+  render: () => html`
+    <p style="max-width:70ch;color:var(--color-text-secondary)">
+      Two models, and they are not the same question. The link navigations mark where
+      you are; the tab list marks which panel is showing. Every one of them carries a
+      cue that is not colour.
+    </p>
+    <div style="display:grid;gap:var(--spacing-40)">
+      <div>
+        ${label('bd-page-switcher · current is heavier and darker')}
+        <bd-page-switcher .items=${NAV_ITEMS}></bd-page-switcher>
+      </div>
+      <div>
+        ${label('bd-breadcrumb · current is heavier, larger and darker')}
+        <bd-breadcrumb>
+          <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+          <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+          <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
+        </bd-breadcrumb>
+      </div>
+    </div>`,
+  parameters: {
+    docs: {
+      description: {
+        story: `Tabs used to run the opposite way and be left alone here, on the argument
+                that its items are buttons with role="tab" and aria-selected inside a
+                tablist rather than links. The ARIA contract is still exactly that and does
+                not change. What changed is the ink: a label with an action behind it is
+                painted like a link in this package, whatever element carries it, so the
+                unselected tabs are brand blue and the selected one settles to plain text
+                at bold — the same three-step contract the link navigations use. Measured
+                across all three: resting is blue-600 at 400, current is text-primary at
+                700, both at 16px. Its underline carries the state either way.
+
+                The two rows above read alike, and measurement is why. The page
+                switcher's current item is darker and heavier than its neighbours, which
+                are brand blue rather than muted — the sizes match at 16px. The
+                breadcrumb's current item is the same 14px as its links and one weight
+                step above them, which is a change P6C.2 made: the links asked bd-link for
+                \`size="small"\`, a property bd-link does not have, so they rendered 16px
+                against a 14px current item, and the current item's medium weight was
+                declared on a span whose text lives inside bd-p and never arrived.`
+      }
+    }
+  }
+};
+
+/* The whole family in one frame, grouped by what each member is responsible for
+   rather than by what it looks like. The point of the grouping is that two of
+   these are not supposed to converge with the others.
+
+   bd-footer-nav sits on the masthead blue it is always used on. It is the one
+   member whose links are the consumer's own anchors rather than bd-link, which
+   is why it is the only one that had to be given the focus ring explicitly —
+   tab through it here and the ring should be the same two-colour ring as
+   everywhere else, white band inside blue. */
+const FAMILY_TABS = [
+  { label: 'Windows' }, { label: 'macOS' }, { label: 'iOS' }
+];
+
+const group = (title, note, node) => html`
+  <section style="display:grid;gap:var(--spacing-8)">
+    <h3 style="margin:0;font:var(--typography-fontWeight-semibold) var(--typography-fontSize-base)/var(--typography-lineHeight-tight) var(--typography-fontFamily-sans);color:var(--color-text-primary)">
+      ${title}
+    </h3>
+    <p style="margin:0;max-width:74ch;font:var(--typography-fontWeight-normal) var(--typography-fontSize-sm)/var(--typography-lineHeight-normal) var(--typography-fontFamily-sans);color:var(--color-text-secondary)">
+      ${note}
+    </p>
+    <div style="padding-top:var(--spacing-8)">${node}</div>
+  </section>`;
+
+export const NavigationFamily = {
+  name  : 'Navigation family',
+  render: () => html`
+    <style>${tabListCSS.cssText}</style>
+    <p style="max-width:74ch;color:var(--color-text-secondary)">
+      Seven components, five responsibilities. They share a vocabulary — one focus ring,
+      one selected-underline role, one ink scale — and they are not meant to share an
+      appearance: a breadcrumb answers "where am I", a tab list answers "which panel is
+      showing", and a back control answers neither.
+    </p>
+    <div style="display:grid;gap:var(--spacing-48)">
+      ${group(
+        '1 · Current location, in a set of pages',
+        'bd-page-switcher. aria-current="page". The current item is the darkest and the heaviest and carries the 3px selected underline; the others are brand blue, because they are links. Three cues, none of them colour alone.',
+        html`<bd-page-switcher .items=${NAV_ITEMS}></bd-page-switcher>`
+      )}
+      ${group(
+        '2 · Current location, inside one page',
+        'bd-anchor-nav. aria-current="location" — a different claim from "page", and the reason the two do not share the attribute value. Below md the same nav becomes a disclosure: the trigger takes a control edge and the expanded panel and its chevron take the one blue that means expanded.',
+        html`<bd-anchor-nav .items=${NAV_ITEMS.map(i => ({ title: i.title, href: i.href }))}></bd-anchor-nav>`
+      )}
+      ${group(
+        '3 · Path to the current location',
+        'bd-breadcrumb. aria-current="page" on the last item, which is text rather than a link. One type size across the row; the links are brand blue and the current item is default ink one weight step up. Hover adds an underline — the cue that is not colour — and at mobile widths the row becomes a stack of full-width targets.',
+        html`
+          <bd-breadcrumb>
+            <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+            <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+            <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
+          </bd-breadcrumb>`
+      )}
+      ${group(
+        '4 · Selection, not location',
+        'bd-tab-list. role="tablist", aria-selected, roving tabindex, arrow keys. The polarity is deliberately the other way round: the unselected tabs are the actionable ones and read as brand blue, and the selected one settles to plain ink. It shares the underline role with 1 and 2 and shares nothing else, because it is not saying where you are.',
+        html`<bd-tab-list .tabs=${FAMILY_TABS} .selected=${0} label="Platform"></bd-tab-list>`
+      )}
+      ${group(
+        '5 · Leaving, rather than arriving',
+        'bd-back. A button, not a link — it may call history.back() and have no href at all — so it has no current state to show and takes a control shape instead: a filled hover, a pressed state, and its own 8px corner that the focus ring follows. Below md it steps up a type size and gains vertical padding, which is the touch target growing where fingers are.',
+        html`<bd-back label="Back"></bd-back>`
+      )}
+      ${group(
+        '6 · Global navigation, on the masthead',
+        'bd-footer-nav. The links here are the page\'s own anchors, slotted in, with bd-divider-vertical between them — so the composed rhythm is 33px in a row (16 either side of a 1px divider) and 16px stacked, where the declared gap is 16 at both. Tab into it: the ring is the same one, which it was not before P6C.2.',
+        html`
+          <div style="background:var(--color-blue-600);padding:var(--spacing-24) var(--spacing-16)">
+            <bd-footer-nav>
+              <a href="/legal">Legal Information</a>
+              <bd-divider-vertical></bd-divider-vertical>
+              <a href="/privacy">Privacy Policy</a>
+              <bd-divider-vertical></bd-divider-vertical>
+              <a href="/cookies">Cookies</a>
+            </bd-footer-nav>
+          </div>`
+      )}
+    </div>`,
+  parameters: {
+    layout: 'padded',
+    docs  : {
+      description: {
+        story: `Read this at 375 and at 1440. Four of the six change shape between those
+                widths and each change is a different mechanism: the anchor nav swaps a row
+                of links for a disclosure, the breadcrumb swaps a row for a stack of
+                full-width targets, the footer nav drops its dividers and stacks, and the
+                back control changes type size. The page switcher and the tab list both
+                simply wrap.
+
+                What should NOT differ across the six: the focus ring, the 3px underline
+                where there is one, and the ink scale. What should: everything that follows
+                from the responsibility — whether there is a current state at all, whether
+                the item is a link or a button, and whether hover is an invitation or a
+                no-op.`
+      }
+    }
+  }
+};
+
+/* ------------------------------------------------------- feedback & status - */
+
+const TONES = ['info', 'success', 'warning', 'error'];
+
+export const StatusFamily = {
+  name  : 'Status Family',
+  render: () => html`
+    <p style="max-width:74ch;color:var(--color-text-secondary)">
+      One message surface, one filled chip and one outlined label, carrying the same four
+      tones. Every value here is read from the shared --status-* roles rather than from the
+      palette steps those roles happen to point at today.
+    </p>
+    <div style="display:grid;gap:var(--spacing-32)">
+      <div>
+        ${label('bd-alert · the feedback message: neutral ink, a 4px tone rule, --radius-md')}
+        <div style="display:grid;gap:var(--spacing-12)">
+          ${TONES.map(tone => html`
+            <bd-alert tone=${tone} heading="Heading.">A message that explains what happened.</bd-alert>
+          `)}
+        </div>
+      </div>
+      <div>
+        ${label('bd-badge · the filled status chip, above bd-tag · the outlined label')}
+        <div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--spacing-12)">
+          ${TONES.map(tone => html`<bd-badge tone=${tone}>${tone}</bd-badge>`)}
+        </div>
+        <div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--spacing-12);margin-top:var(--spacing-12)">
+          ${TONES.map(tone => html`<bd-tag tone=${tone}>${tone}</bd-tag>`)}
+        </div>
+      </div>
+    </div>`,
+  parameters: {
+    layout: 'padded',
+    docs  : {
+      description: {
+        story: `Three components, four tones, one semantic system. Read down a column rather
+                than across a row: the info surface under bd-alert and the info tint under
+                bd-tag are the same value because both name \`--status-info-surface\`, not
+                because someone matched two palette steps by eye.
+
+                bd-badge and bd-tag are deliberately not identical, and P7C left both alone.
+                A tag is an outlined label — 1px \`--status-*-border\` around the plain tint.
+                A badge is a filled chip — no border, the stronger tint. Measured at 1440
+                they stand 24px and 23px tall, which is arithmetic rather than drift: the tag
+                spends its extra pixel on the border it draws. The difference you can see
+                maps to a difference that is real.
+
+                This story replaced a Banner vs Alert comparison that P6C.3 left here to put
+                a decision in front of a person. P7C answered it, and bd-banner was retired.
+                It was not in \`package.json\` exports and not in the component manifest, so
+                it was never part of the published surface; it had no consumer anywhere in
+                this repository outside its own stories; its first commit is titled "banner
+                component for testing"; and it drew the same four tinted surfaces as bd-alert
+                by naming \`--color-blue-50\` and its neighbours directly. That last point is
+                what made it worth removing rather than polishing. Retinting
+                \`--status-info-surface\` would have moved bd-alert, bd-tag and bd-badge and
+                left bd-banner behind, so the duplication was not only visual — it was
+                invisible to the token system that is supposed to hold this family together.`
+      }
+    }
+  }
+};

package/src/components/visually-hidden/visually-hidden.css.js

@@ -0,0 +1,24 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const visuallyHiddenCSS = css`
+  /* Removed from view but kept in the accessibility tree. Not display:none,
+     which would remove it from the tree as well. */
+  :host {
+    position: absolute;
+    /* no token: 1px is the clip idiom's own measure, not a border. It was
+       spelled --border-width-1, which resolves to the same pixel and reads as
+       a category error — the lint already sanctions the literal here, as it
+       does the -1px below. */
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+`;
+
+export default visuallyHiddenCSS;

package/src/components/visually-hidden/visually-hidden.js

@@ -0,0 +1,16 @@
+import { LitElement, html } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { visuallyHiddenCSS } from './visually-hidden.css.js';
+
+export class BdVisuallyHidden extends LitElement {
+  static styles = [visuallyHiddenCSS];
+
+  render() {
+    return html`
+      <slot></slot>
+    `;
+  }
+}
+
+customElements.define('bd-visually-hidden', BdVisuallyHidden);