BD Video

BD Video is the full player: a large centre play/pause button, a seek scrubber with time display, mute and fullscreen buttons, keyboard shortcuts, and timed link cards that surface over the frame. Author two elements — a .bd-video container and a .bd-video-player <video> inside it — then switch features on with data-bd-* attributes on the container. Everything else (buttons, scrubber, cue slot, icon sprite) is built by assets/js/bd-video.js at init, so the markup stays two elements no matter how many features run. Companion styles live in bd-video.css.

For a decorative loop with no controls, use a plain <video autoplay muted loop playsinline> instead — this component is for video the visitor is meant to operate.

Anatomy

Every feature is off until its attribute is present. All attributes are booleans on the .bd-video container.

Always on, no attribute needed: the centre play/pause button, click-the-video-to-toggle, controls that auto-hide after 3s idle, keyboard shortcuts, state-aware aria-labels, and the reduced-motion carve-out.

The component consumes design-system tokens only through namespaced --bd-video-* tokens with literal fallbacks, so it works on pages without design-system.css.

Configuration

Define window.bdVideoConfig before the script loads. Every key is optional.

Name the destination in cueLabel — the default suits a studio showreel linking to case studies; a product tour linking to docs would set cueLabel: "Read the guide".

Basic usage

<div class="bd-video" role="region" aria-label="Video player"
     data-bd-scrubber data-bd-mute data-bd-fullscreen>
  <video class="bd-video-player"
         src="/assets/video/showreel.mp4"
         poster="/assets/images/showreel-poster.jpg"
         aria-label="Studio showreel"
         playsinline
         preload="metadata"></video>
</div>

A muted autoplay preview adds the unmute prompt. In preview state the player runs silent and the centre button invites a start; the first play/unmute restarts from zero with sound.

<div class="bd-video" role="region" aria-label="Video player"
     data-bd-scrubber data-bd-mute data-bd-fullscreen data-bd-unmute-prompt data-bd-pause-offscreen>
  <video class="bd-video-player"
         src="/assets/video/showreel.mp4"
         poster="/assets/images/showreel-poster.jpg"
         aria-label="Studio showreel"
         autoplay muted loop playsinline preload="auto"></video>
</div>

Timed cue cards

data-bd-cues reads an inline JSON block inside the container and shows one link card at a time over the frame. start, end, title, href and image are required; excerpt is optional. Entries are validated (invalid ones are dropped with a console warning), sorted by start, and their thumbnails preloaded.

<div class="bd-video" role="region" aria-label="Video player" data-bd-scrubber data-bd-cues>
  <video class="bd-video-player"
         src="/assets/video/showreel.mp4"
         poster="/assets/images/showreel-poster.jpg"
         aria-label="Studio showreel"
         playsinline></video>
  <script type="application/json" data-bd-cues-data>
  [
    {
      "start": 0.3,
      "end": 10,
      "title": "Verizon HBCU",
      "excerpt": "Sold out Gen-Z show in 3 cities.",
      "href": "/work/verizon-hbcu.html",
      "image": "/assets/images/work/verizon/sidebar_verizon.jpg"
    }
  ]
  </script>
</div>

Clicking a card pauses the video and navigates — exiting fullscreen first when the player is fullscreen. Cues are suppressed during preview, during scrubbing, and for 800ms after a preview exit. Hovering a card holds it open past its end time (released on mouse leave, with a 3s fallback for touch).

JavaScript

Include assets/js/bd-video.js once per page. It self-initialises on DOMContentLoaded and exits early when the page has no .bd-video-player.

A client-side router must call both: cleanupBdVideo() before the swap, initBdVideo(container) on the entering container.

Events

Both deferred-autoplay paths have a 4s watchdog, so a router that never dispatches its event still plays.

The same state is mirrored on the container as data-bd-state="preview | playing | paused" — the attribute is the CSS and adapter hook; the event is the notification.

Pairing with BD Cursor

When the container carries data-cursor-badge, the player drives the custom cursor: the riding glyph tracks play/pause and mute state, the scrubber is carved out with data-cursor-native so seeking keeps the OS pointer, and a cue card swaps to the cueLabel float label. Each swap dispatches bd-cursor:refresh so the change lands under a stationary pointer.

The icon sprite bd-cursor loads must contain play, pause, sound-off, sound-on, full-screen and arrow-top-right. A missing symbol renders a cursorless region with no error.

Without bd-cursor the pairing is inert: no data-cursor-* attributes means no cursor work, and bd-video.css's single .bd-cursor-ready rule (isolated in its own section at the end of the file) never matches. The player's own icons come from a scoped #bd-video-* sprite it injects itself — it never depends on a host page's sprite.

Accessibility

What is accessible today:

• Keyboard shortcuts, active while focus is inside the player: Space or K toggles play, M toggles mute, F toggles fullscreen, ← / → seek 5 seconds. Letter keys match lowercase only, and M / F need their feature attribute present.
• The scrubber is a real slider: role="slider", tabindex="0", aria-label="Seek", and live aria-valuemin / aria-valuemax / aria-valuenow / aria-valuetext (spoken as "1 minute 4 seconds of 3 minutes 20 seconds"). Focused, it takes ← → ↑ ↓ for 5-second steps, PageUp / PageDown for 10% of duration, and Home / End for start and end.
• Every generated control has a focus ring: a 2px :focus-visible outline with offset on the centre button, unmute prompt, mute button, fullscreen button, scrubber and cue card.
• Icon and accessible name never diverge: every code path that swaps the centre, mute or fullscreen icon rewrites that button's aria-label in the same step. Hover tooltips duplicate those labels and carry no unique information; the visible 1:23 / 5:30 readout is aria-hidden, because the scrubber's aria-valuetext already carries it.
• Auto-hide respects focus: when the 3s idle timer fires with focus inside the player, the controls stay up.
• Cue cards have a live region: the cue region is aria-live="polite", and its aria-label is written once per cue rather than on every loop.
• Reduced motion is honoured: autoplay is stripped, the deferred-autoplay marker is dropped, the video is paused, and control transitions are switched off.

Known gaps beyond captions — treat these as constraints when placing a player, and as the roadmap after captions:

• Controls hidden by the idle timer stay in the tab order at opacity: 0, and focus arriving afterwards does not bring them back (2.4.7). The mute button suppressed by the unmute prompt (.is-mute-hidden) is invisible and focusable the same way.
• There are no play / pause / ended listeners, so state changed outside the component's own handlers leaves the centre button's label stale (4.1.2): a video that ends, the offscreen soft-pause, a rejected play(), and the browser's own context-menu or picture-in-picture controls.
• Space is handled at the player root, so it toggles playback rather than activating the focused button (2.1.1), and the arrow shortcuts have no modifier guard, so Alt + ← seeks instead of going back (2.1.4).
• Below 768px a preview player hides the centre button; with no data-bd-mute or data-bd-fullscreen that configuration leaves no keyboard-operable play control at all (2.1.1). Ship at least one control button on mobile preview players.
• Fullscreen uses the unprefixed API only, so the button and F are a silent no-op on iOS Safari, and fullscreen neither traps focus nor makes the rest of the page inert (2.4.3).
• The focus ring is white on whatever video frame sits behind it, so 3:1 against adjacent colour is not guaranteed (1.4.11), and data-tooltip tooltips are hover-only (1.4.13 — mitigated by their labels duplicating the accessible name).

Author requirements:

• Must label the player: role="region" and an aria-label on the container. The script never reads them — nothing generated depends on it, so the obligation is entirely the author's.
• Must give the <video> an aria-label naming the content, and a poster so the frame is never blank before playback.
• Must keep data-bd-mute on any player that carries audio: without it there is no in-player way to silence sound, which fails 1.4.2 Audio Control, Level A for anything that autoplays past 3 seconds.
• Must not rely on the centre button being present on small screens in preview state — the CSS hides it there. Tapping the video or the unmute prompt starts playback, and the button returns once the video is paused; see the keyboard gap above for the configuration to avoid.

Usage rules

Do

• Author the two elements and let the script build the rest — the controls are generated, not authored
• Turn on only the features the placement needs; every attribute adds a control the visitor must parse
• Pair data-bd-unmute-prompt with autoplay muted — it is the affordance that makes a silent autoplay honest
• Add data-bd-pause-offscreen to any autoplaying player on a long page, so scrolled-past video stops costing battery
• Call cleanupBdVideo() before a router swap and initBdVideo(container) after it

Don't

• Don't use bd-video for decorative background loops — a plain <video> with no controls is lighter and needs no JS
• Don't ship a player for video with speech until captions land (see above)
• Don't hand-author the centre button, controls bar or scrubber — the script owns that DOM and removes stale copies
• Don't re-theme by overriding .bd-video-* rules; override the --bd-video-* tokens instead
• Don't put a data-bd-pause-offscreen player in persistent chrome outside the router's swapped container — its observer is torn down on nav and only re-created on the entering container

CSS reference

This section documents how the component is built. For usage, see the sections above.

Styles ship as their own file, dist/css/bd-video.css, linked after design-system.css.

Tokens

Every token is scoped under .bd-video and resolves through a design-system variable with a literal fallback, so the component themes inside the system and still renders outside it.

Cue colours deliberately never inherit semantic tokens like --text-primary: those flip in dark mode, the video behind them does not.

Three tokens are declared for completeness but currently unreferenced: --bd-video-duration-mobile-scrubber, --bd-video-space-2xl, --bd-video-radius-m.

Selectors

State classes

Key rules

Buttons cancel the global :active press transform: the centred controls use transform for positioning, so replacing it would move the hit zone out from under the pointer mid-click.

The scrubber gets a 30px ::before hit area extending above the 8px track, so seeking is reachable on touch.

Under 768px the centre button is hidden in preview state only (tapping the video or the unmute prompt starts playback), the unmute prompt moves to the top-right, buttons grow to 48px, and cue cards drop the thumbnail and excerpt for a text-plus-arrow row.

Use in another product

The design system installs once per product:

npm install github:bydefaultstudio/design-system-dist#semver:^4.7.0

This component's styles ship as dist/css/bd-video.css — copy it into the product's served assets and link it after design-system.css. Its behaviour ships as dist/js/bd-video.js — copy it into the product's served assets and include it once per page:

<script src="assets/js/bd-video.js" defer></script>