@repobit/dex-system-design 1.0.1 → 2.0.0

package/src/components/spinner/spinner.stories.js

@@ -22,16 +22,19 @@ unknown. When you know the proportion done, use \`<bd-progress>\` instead.
 ### Props
 | Prop | Values | Default |
 |---|---|---|
-| \`size\` | \`small\`, \`default\`, \`large\` | \`default\` |
+| \`size\` | \`sm\`, \`md\`, \`lg\` — \`small\` / \`default\` / \`large\` still resolve | \`md\` |
 | \`label\` | the accessible name | \`Loading\` |
 
 ### Accessibility
-It carries \`role="status"\` with \`aria-label\` from \`label\`, so the wait is
-announced politely rather than interrupting. Give it a specific \`label\` where
+\`label\` is the text of a visually hidden \`role="status"\` region, so the wait
+is announced politely rather than interrupting. The text arrives just after
+the region does, which is what lets a screen reader treat it as news, and a
+later change to \`label\` is announced too. Give it a specific \`label\` where
 you can — "Checking your licence" is more use than the default "Loading".
 
-Under \`prefers-reduced-motion\` it stops spinning and pulses instead, so it
-still reads as active without rotating.
+Under \`prefers-reduced-motion\` it stops spinning: the arc stays, still and
+at full contrast, and the disc behind it pulses, so it still reads as active
+without rotating and never fades below 3:1.
 
 ### Note on colour
 The spinner's track and head are fixed at \`--color-neutral-200\` and
@@ -47,9 +50,9 @@ let the two converge.
   argTypes: {
     size: {
       control    : { type: 'select' },
-      options    : ['small', 'default', 'large'],
+      options    : ['sm', 'md', 'lg'],
       description: 'Diameter of the spinner.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: "default" }, category: 'Appearance' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'md' }, category: 'Appearance' }
     },
     label: {
       control    : 'text',

package/src/components/switch/switch.css.js

@@ -58,10 +58,22 @@ export const switchCSS = css`
     flex: none;
   }
 
+  /* The thumb's inset and travel are derived from the two boxes they sit
+     between, in px like those boxes. They were --spacing-2 and --spacing-16,
+     which are rem, inside a track that is --dimension-* and so is not: at a
+     24px root the thumb rode 3px in and travelled 24px, and finished at 47px
+     in a 40px track. A knob has to stay on the track it belongs to at any text
+     size, so all four lengths are now one unit. Inset is half the height left
+     over; travel is the width left over after both insets: 2px and 16px. */
+  .track {
+    --bd-switch-inset: calc((var(--dimension-24) - var(--dimension-20)) / 2);
+    --bd-switch-travel: calc(var(--dimension-40) - var(--dimension-20) - 2 * var(--bd-switch-inset));
+  }
+
   .thumb {
     position: absolute;
-    top: var(--spacing-2);
-    left: var(--spacing-2);
+    top: var(--bd-switch-inset);
+    left: var(--bd-switch-inset);
     width: var(--dimension-20);
     height: var(--dimension-20);
     /* the knob on the track, white on both tracks: --color-action-on-fill,
@@ -81,13 +93,19 @@ export const switchCSS = css`
      If a second component ever needs it, that is when it earns a name. */
   label:hover .track { background: var(--color-neutral-500); }
   :host([checked]) label:hover .track { background: var(--color-action-primary-hover); }
-  :host([checked]) .thumb { transform: translateX(var(--spacing-16)); }
+  :host([checked]) .thumb { transform: translateX(var(--bd-switch-travel)); }
 
   /* the one focus ring — see Foundations/Focus. On the row rather than the
      track, so the target and the indicator are the same shape here as on
      bd-checkbox and bd-radio. */
   label:has(input:focus-visible) {
     box-shadow: var(--focus-outline-primary);
+    /* 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);
     border-radius: var(--focus-outline-radius);
   }
 

package/src/components/switch/switch.js

@@ -31,7 +31,14 @@ export class BdSwitch extends LitElement {
           ?disabled=${this.disabled}
           @change=${e => {
             this.checked = e.target.checked;
-            this.dispatchEvent(new CustomEvent('bd-change', { detail: this.checked }));
+            // bubbles and composed, as every sibling form atom's event is: with
+            // neither, it reached a listener on the switch and nothing above
+            // it, so a form wrapper delegating bd-change heard nothing
+            this.dispatchEvent(new CustomEvent('bd-change', {
+              detail  : this.checked,
+              bubbles : true,
+              composed: true
+            }));
           }}
         />
         <span class="track"><span class="thumb"></span></span>

package/src/components/switch/switch.stories.js

@@ -33,7 +33,8 @@ Content can also come from the default slot, which renders after \`label\` — s
 set one or the other, not both.
 
 ### Events
-\`bd-change\` — fires on toggle with \`detail\` set to the new boolean.
+\`bd-change\` — fires on toggle with \`detail\` set to the new boolean. It bubbles and
+is composed, so a form wrapper can listen for it on itself.
 
 ### Accessibility
 It is a real \`<input type="checkbox">\` with \`role="switch"\`, inside a

package/src/components/tab-list/tab-list.css.js

@@ -111,7 +111,12 @@ export const tabListCSS = css`
 
   .bd-tab-button:focus-visible {
     /* the one focus ring — see Foundations/Focus */
-    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);
     border-radius: var(--focus-outline-radius);
   }

package/src/components/terminal/terminal-cursor.js

@@ -32,6 +32,17 @@ class TerminalCursor extends LitElement {
           opacity: 0;
         }
       }
+
+      /* A cursor that blinks for as long as the page is open is exactly the
+         motion the setting exists for, and this one had no guard: every
+         other animated element in the package stops or softens under
+         prefers-reduced-motion. Here it stops, and the cursor stays shown --
+         a steady block still says "this is where the terminal is". */
+      @media (prefers-reduced-motion: reduce) {
+        .bd-terminal-cursor {
+          animation: none;
+        }
+      }
     `
   ];
 

package/src/components/terminal/terminal-message.js

@@ -160,7 +160,7 @@ class TerminalMessage extends LitElement {
           ${this.items && this.items.length
             ? html`
                 <bd-list class="bd-terminalmsg-list">
-                  ${this.items.map((item) => html`<bd-li variant="bullet" size="sm" color="var(--color-neutral-0)">${item}</bd-li>`)}
+                  ${this.items.map((item) => html`<bd-li variant="bullet" size="sm" color="inverse">${item}</bd-li>`)}
                 </bd-list>
               `
             : nothing}

package/src/components/termsOfUse/terms.css.js

@@ -12,7 +12,12 @@ export default css`
 
   .bd-terms-text-a:focus-visible{
     /* the one focus ring — see Foundations/Focus */
-    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);
     border-radius: var(--focus-outline-radius);
   }

package/src/components/textarea/textarea.stories.js

@@ -119,6 +119,11 @@ The vertical resize handle is left enabled, so a user can grow the field beyond
       control    : 'boolean',
       description: 'Blocks editing.',
       table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    name: {
+      control    : 'text',
+      description: 'Carried on the bd-change detail as { value, name }, for your own submit handling. NOT submitted with a form — the <textarea> is in a shadow root.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Content' }
     }
   }
 };
@@ -127,6 +132,24 @@ export const Default = () => html`
   <bd-textarea label="What happened?" placeholder="Tell us what happened"></bd-textarea>
 `;
 
+/**
+ * `name` reaches no form -- the <textarea> is in this element's shadow root --
+ * so it is carried on the event instead. Type, then click away: the line
+ * below shows the bd-change detail as it arrives.
+ */
+export const NameOnTheEvent = {
+  name  : 'name on the event',
+  render: () => html`
+    <bd-textarea
+      label="What happened?"
+      name="incident"
+      rows="2"
+      @bd-change=${e => { e.currentTarget.nextElementSibling.textContent = `bd-change detail: ${JSON.stringify(e.detail)}`; }}
+    ></bd-textarea>
+    <p style="font-family: var(--typography-fontFamily-mono); font-size: var(--typography-fontSize-sm)">bd-change detail: (type, then click away)</p>
+  `
+};
+
 export const Sizes = {
   name  : 'All Sizes',
   render: () => html`

package/src/components/tooltip/tooltip.css.js

@@ -64,8 +64,31 @@ export const tooltipCSS = css`
     transition: opacity var(--transition-duration-fast) var(--transition-easing-smooth);
   }
 
+  /* Shown means reachable. WCAG 1.4.13 asks that the pointer can move onto
+     content that appeared on hover without it disappearing. With
+     pointer-events: none left on, the pointer passed through the bubble to
+     whatever lay beneath it, the host lost :hover, and the bubble hid. The
+     bubble is in this shadow tree, so hovering it keeps :host(:hover). */
   :host(:hover) .bubble,
-  :host(:focus-within) .bubble { opacity: 1; }
+  :host(:focus-within) .bubble { opacity: 1; pointer-events: auto; }
+
+  /* Escape hides it while the pointer or focus is still there; see the note
+     on _showing in tooltip.js. Same specificity as the rule above and later,
+     so it wins, and it takes pointer events away with the opacity. */
+  :host(:hover) .bubble--dismissed,
+  :host(:focus-within) .bubble--dismissed { opacity: 0; pointer-events: none; }
+
+  /* The bubble floats --spacing-8 above the trigger, and the pointer has to
+     cross that gap to reach it: this fills it, so the host stays hovered
+     across the way. It inherits pointer-events from the bubble, so it catches
+     nothing while the bubble is hidden. */
+  .bubble::after {
+    content: "";
+    position: absolute;
+    inset-inline: 0;
+    top: 100%;
+    bottom: calc(-1 * var(--spacing-8));
+  }
 
   @media (prefers-reduced-motion: reduce) {
     .bubble { transition: none; }

package/src/components/tooltip/tooltip.js

@@ -1,18 +1,24 @@
-import { LitElement, html } from 'lit';
+import { LitElement, html, nothing } from 'lit';
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import '../../tokens/tokens.js';
 import { tooltipCSS } from './tooltip.css.js';
 
+let descriptionIds = 0;
+
 export class BdTooltip extends LitElement {
   static styles = [tooltipCSS];
 
   static properties = {
-    text: { type: String }
+    text      : { type: String },
+    /* Set by Escape and cleared once neither the pointer nor focus is on the
+       tooltip any more, so the next hover or focus shows it again. */
+    _dismissed: { type: Boolean, state: true }
   };
 
   constructor() {
     super();
     this.text = '';
+    this._dismissed = false;
   }
 
   /* The bubble is centred on its trigger and is wider than it, so near a
@@ -119,7 +125,31 @@ export class BdTooltip extends LitElement {
        Both boxes, because they move for different reasons: the host changes
        when the trigger resizes, the bubble when its own text reflows.
        ResizeObserver fires once on observe, which is the settled first pass. */
-    if (typeof ResizeObserver === 'undefined') return;
+    this._observe();
+  }
+
+  /* ESCAPE. WCAG 1.4.13 asks that content shown on hover or focus can be
+     dismissed without moving the pointer or focus. The pointer may be over the
+     trigger while focus is anywhere on the page, so the key is heard on the
+     document, and only acted on while this bubble is actually showing.
+
+     Capture phase, and the event is marked handled with preventDefault rather
+     than stopped: a tooltip is the innermost thing that can be open, so its
+     Escape should not also close a native <dialog> it sits in, and a dialog's
+     cancel is exactly what preventDefault on that keydown withholds.
+     Propagation is left alone, as bd-modal leaves it, so a page that wants to
+     hear the key still does. */
+  get _showing() {
+    return !this._dismissed && (this.matches(':hover') || this.matches(':focus-within'));
+  }
+
+  /* Started on first render and again on every reconnect. It used to start
+     only in firstUpdated, and disconnectedCallback tears it down, so a tooltip
+     moved in the DOM -- removed and re-inserted, which a framework reordering
+     a list does -- came back with no observer and never re-placed itself when
+     its trigger or text changed size. */
+  _observe() {
+    if (typeof ResizeObserver === 'undefined' || this._ro) return;
     this._ro = new ResizeObserver(() => this._place());
     this._ro.observe(this);
     const bubble = this.renderRoot?.querySelector('.bubble');
@@ -128,27 +158,127 @@ export class BdTooltip extends LitElement {
 
   connectedCallback() {
     super.connectedCallback();
+    // a first connection is handled by firstUpdated, once the bubble exists
+    if (this.hasUpdated) this._observe();
     this._onShow = () => this._place();
     /* Both reveals the stylesheet already honours, and resize because the
        measurement is only true for the width it was taken at. */
     this.addEventListener('mouseenter', this._onShow);
     this.addEventListener('focusin', this._onShow);
     window.addEventListener('resize', this._onShow);
+
+    this._onKeydown = e => {
+      if (e.key !== 'Escape' || e.defaultPrevented || !this._showing) return;
+      e.preventDefault();
+      this._dismissed = true;
+    };
+    /* Back to normal once the pointer and focus have both gone: a pointer
+       leaving while focus stays inside keeps it dismissed, and the reverse. */
+    this._onLeave = e => {
+      if (!this._dismissed) return;
+      const pointerGone = e.type === 'mouseleave' || !this.matches(':hover');
+      const focusGone = e.type === 'focusout'
+        ? !this.contains(e.relatedTarget) && !this.shadowRoot.contains(e.relatedTarget)
+        : !this.matches(':focus-within');
+      if (pointerGone && focusGone) this._dismissed = false;
+    };
+    document.addEventListener('keydown', this._onKeydown, true);
+    this.addEventListener('mouseleave', this._onLeave);
+    this.addEventListener('focusout', this._onLeave);
   }
 
   disconnectedCallback() {
     this.removeEventListener('mouseenter', this._onShow);
     this.removeEventListener('focusin', this._onShow);
     window.removeEventListener('resize', this._onShow);
+    document.removeEventListener('keydown', this._onKeydown, true);
+    this.removeEventListener('mouseleave', this._onLeave);
+    this.removeEventListener('focusout', this._onLeave);
     this._ro?.disconnect();
     this._ro = undefined;
     super.disconnectedCallback();
   }
 
+  /* DESCRIBING THE TRIGGER.
+     The bubble had role="tooltip" and nothing pointed at it, so a screen
+     reader landing on the trigger heard its name and not the tooltip, and
+     the bubble's text sat in the page as a stray line. It cannot be pointed
+     at directly: the bubble is in this shadow root and the trigger is not,
+     and an id reference never crosses that boundary. So the trigger is
+     described from its own side:
+
+       a native control   aria-describedby names a hidden copy of the text,
+                          kept as a child of this element in a hidden slot --
+                          the same tree as the trigger, so the reference
+                          resolves
+       bd-button,         the text goes to its description property, which
+       bd-button-link,    wires aria-describedby inside its own shadow root,
+       bd-link            where its real control is
+
+     Once described, the bubble is hidden from assistive technology so the
+     text is not read twice. Any other custom element as trigger keeps the
+     bubble exposed and goes undescribed -- its control is out of reach. */
+  _describe() {
+    this._undescribe();
+    const slot = this.shadowRoot?.querySelector('slot');
+    const trigger = slot?.assignedElements()[0];
+    if (!trigger || !this.text) return;
+
+    // a custom element that has not upgraded yet has no description to set:
+    // come back once it has
+    if (trigger.localName.includes('-') && !customElements.get(trigger.localName)) {
+      customElements.whenDefined(trigger.localName).then(() => this._describe());
+      return;
+    }
+
+    if ('description' in trigger && trigger.localName.includes('-')) {
+      trigger.description = this.text;
+      this._described = { trigger, kind: 'property' };
+    } else if (!trigger.localName.includes('-')) {
+      const node = document.createElement('span');
+      node.id = `bd-tooltip-description-${++descriptionIds}`;
+      node.slot = 'description';
+      node.hidden = true;
+      node.textContent = this.text;
+      this.append(node);
+      const ids = (trigger.getAttribute('aria-describedby') || '').split(/\s+/).filter(Boolean);
+      trigger.setAttribute('aria-describedby', [...ids, node.id].join(' '));
+      this._described = { trigger, kind: 'idref', node };
+    }
+    this.requestUpdate();
+  }
+
+  _undescribe() {
+    const d = this._described;
+    if (!d) return;
+    if (d.kind === 'property') {
+      d.trigger.description = '';
+    } else {
+      const ids = (d.trigger.getAttribute('aria-describedby') || '').split(/\s+/).filter(t => t && t !== d.node.id);
+      if (ids.length) d.trigger.setAttribute('aria-describedby', ids.join(' '));
+      else d.trigger.removeAttribute('aria-describedby');
+      d.node.remove();
+    }
+    this._described = null;
+    this.requestUpdate();
+  }
+
+  updated(changed) {
+    if (changed.has('text') && this.hasUpdated) this._describe();
+  }
+
   render() {
     return html`
-      <slot></slot>
-      <span class="bubble" role="tooltip">${this.text}</span>
+      <slot @slotchange=${() => this._describe()}></slot>
+      <!-- the trigger's description: hidden, but slotted, because a node
+           assigned to no slot is not in the flat tree and Chrome then drops
+           an aria-describedby that points at it -->
+      <span hidden><slot name="description"></slot></span>
+      <span
+        class="bubble ${this._dismissed ? 'bubble--dismissed' : ''}"
+        role="tooltip"
+        aria-hidden="${this._described ? 'true' : nothing}"
+      >${this.text}</span>
     `;
   }
 }

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

@@ -33,23 +33,29 @@ Anything required to complete a task belongs in visible text or in
 \`<bd-help-text>\`, because a tooltip is unreachable on touch, invisible in
 print, and gone the moment the pointer leaves.
 
-### Accessibility caveats
-The bubble carries \`role="tooltip"\`, but this element does **not** wire up
-\`aria-describedby\` between the trigger and the bubble. A screen reader
-therefore has no link from the control to its description, so the tooltip text
-may never be announced.
+### Accessibility
+The trigger is described by the tooltip: a screen reader reads the \`text\`
+after the trigger's name. How depends on the trigger, because the bubble sits
+in this element's shadow root and an \`aria-describedby\` cannot point into it:
 
-Until that is connected, describe the trigger directly as well:
+- **a native control** — \`<button>\`, \`<a>\`, \`<input>\` — gets
+  \`aria-describedby\` naming a hidden copy of the text kept inside the
+  tooltip, added to any ids it already lists and removed when it leaves;
+- **\`bd-button\`, \`bd-button-link\` and \`bd-link\`** get the text through
+  their \`description\` property, which wires the description inside their own
+  shadow root, where the real control is;
+- **any other custom element** cannot be reached, so it is not described and
+  the bubble stays exposed instead. Prefer a native control, a
+  \`bd-button\` or a \`bd-link\` as the trigger.
 
-\`\`\`html
-<bd-tooltip text="Blocks trackers">
-  <bd-button aria-describedby="trackers-hint">What is this?</bd-button>
-</bd-tooltip>
-<span id="trackers-hint" hidden>Blocks trackers across every browser</span>
-\`\`\`
+Once the trigger is described, the bubble itself is hidden from assistive
+technology, so the text is not read twice.
 
-There is also no dismiss-on-Escape and no delay before showing, both of which
-WCAG 1.4.13 asks of content that appears on hover.
+The bubble meets WCAG 1.4.13. It is hoverable: the pointer can move from the
+trigger onto the bubble, across the gap between them, and it stays open. It is
+dismissible: Escape hides it without moving the pointer or focus, and it shows
+again on the next hover or focus. That Escape is marked handled, so a native
+\`<dialog>\` the tooltip sits in stays open on the same keypress.
         `
       }
     }

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

@@ -36,7 +36,7 @@ class TrustPanel extends LitElement {
     return html`
       <div class="bd-trustpanel-card">
         ${card.eyebrow
-          ? html`<bd-p variant="regular" font-weight="semibold" class="bd-trustpanel-card-eyebrow">${card.eyebrow}</bd-p>`
+          ? html`<bd-p variant="eyebrow" class="bd-trustpanel-card-eyebrow">${card.eyebrow}</bd-p>`
           : nothing}
 
         <div class="bd-trustpanel-card-logos">
@@ -66,7 +66,7 @@ class TrustPanel extends LitElement {
     return html`
       <div class="bd-ensemble bd-trustpanel-wrapper">
         ${this.eyebrow
-          ? html`<bd-p variant="regular" font-weight="semibold" class="bd-trustpanel-eyebrow"><slot name="eyebrow">${this.eyebrow}</slot></bd-p>`
+          ? html`<bd-p variant="eyebrow" class="bd-trustpanel-eyebrow"><slot name="eyebrow">${this.eyebrow}</slot></bd-p>`
           : nothing}
 
         ${this.title

package/src/components/video/video.js

@@ -9,9 +9,13 @@ export class BdVideo extends LitElement {
   static properties = {
     src     : { type: String },
     poster  : { type: String },
-    controls: { type: Boolean },
+    /* On unless told otherwise -- see the story's Notes. A default-on boolean
+       cannot be turned off by leaving the attribute out, so the attribute
+       reads controls="false" as off; the property takes false as it is. */
+    controls: { converter: { fromAttribute: value => value !== 'false' } },
     muted   : { type: Boolean },
-    loop    : { type: Boolean }
+    loop    : { type: Boolean },
+    _media  : { state: true }
   };
 
   constructor() {
@@ -21,8 +25,38 @@ export class BdVideo extends LitElement {
     this.controls = true;
     this.muted = false;
     this.loop = false;
+    this._media = [];
   }
 
+  /* WHY THE TRACKS ARE COPIED IN.
+     This rendered <video><slot></slot></video>, and a media element builds
+     its text tracks and sources only from real <track> and <source> children
+     -- a slot is neither, so the captions the story told readers to slot in
+     never reached the player. The <track> and <source> children are now
+     copied into the <video> itself, and copied again whenever they change. */
+  connectedCallback() {
+    super.connectedCallback();
+    this._collect();
+    this._observer = new MutationObserver(() => this._collect());
+    this._observer.observe(this, { childList: true, subtree: true, attributes: true });
+  }
+
+  disconnectedCallback() {
+    this._observer?.disconnect();
+    super.disconnectedCallback();
+  }
+
+  _collect() {
+    this._media = [...this.children]
+      .filter(el => el.localName === 'track' || el.localName === 'source')
+      .map(el => el.cloneNode(true));
+  }
+
+  /* muted is a property, not only an attribute. The attribute is read once,
+     when the media loads -- it is what lets a muted video autoplay -- and
+     changing it afterwards mutes nothing, so muted = true on a playing video
+     left the sound on. Both are set: the attribute for the load, the
+     property for every change after it. */
   render() {
     return html`
       <video
@@ -30,9 +64,10 @@ export class BdVideo extends LitElement {
         poster=${this.poster || nothing}
         ?controls=${this.controls}
         ?muted=${this.muted}
+        .muted=${this.muted}
         ?loop=${this.loop}
         playsinline
-      ><slot></slot></video>
+      >${this._media}</video>
     `;
   }
 }

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

@@ -29,9 +29,10 @@ export default {
 | \`muted\` | boolean | \`false\` |
 | \`loop\` | boolean | \`false\` |
 
-### Captions go in the slot
-Anything slotted is passed through into the \`<video>\`, which is how you supply
-\`<track>\` elements. **Recorded video needs captions** — WCAG 1.2.2 at level A —
+### Captions go inside the element
+\`<track>\` and \`<source>\` children are copied into the \`<video>\` — a media
+element only reads tracks and sources from its own children — and copied again
+when they change. That is how you supply captions. **Recorded video needs captions** — WCAG 1.2.2 at level A —
 and this element does nothing to add them for you.
 
 ### Notes
@@ -41,7 +42,11 @@ screen.
 \`controls\` defaults to \`true\` on purpose: a video a user cannot pause is a
 2.2.2 failure the moment it plays for more than five seconds. If you turn
 controls off, the video must also be \`muted\` and \`loop\` and behave as
-decoration.
+decoration. In HTML that is \`controls="false"\`: leaving the attribute out
+cannot turn off a default that is on. From script, \`.controls = false\`.
+
+\`muted\` follows the property as well as the attribute, so changing it on a
+playing video takes effect.
 
 There is no \`autoplay\` prop, deliberately — autoplay with sound is both
 disruptive and blocked by most browsers anyway.
@@ -91,7 +96,7 @@ export const Default = () => html`
  * them.
  */
 export const Decorative = () => html`
-    <bd-video poster="/images/bd-header-img.jpg" ?controls=${false} muted loop></bd-video>
+    <bd-video poster="/images/bd-header-img.jpg" controls="false" muted loop></bd-video>
   `;
 
 /**

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

@@ -124,7 +124,12 @@ export default css`
      --radius-lg corner and the close button is a circle. */
   .bd-video-thumb:focus-visible,
   .bd-video-close: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/tokens/elevation.stories.js

@@ -75,15 +75,14 @@ export const Shadows = () => {
   const surface = all.filter(token => !token.includes('focus'));
   const rings = all.filter(token => token.includes('focus'));
 
-  const ladder = ['--shadow-sm', '--shadow-md', '--shadow-lg', '--shadow-xl', '--shadow-2xl'];
+  const ladder = ['--shadow-sm', '--shadow-md', '--shadow-lg', '--shadow-xl'];
 
   return html`
     ${elevationStyles}
     ${docsPage({
       title: 'Elevation',
       lede : html`Shadows are the only elevation mechanism in the system — there is no z-index
-        scale. <code>sm</code> through <code>2xl</code> form a ladder;
-        <code>--shadow-inner</code> is an inset press state.`,
+        scale. <code>sm</code> through <code>xl</code> form a ladder.`,
       note    : referenceNote,
       children: html`
         ${refSection({