ki-video

A themed video surface: a calm poster facade with exactly one accessible play control over a slotted native <video> element. From the first activation on, playback, scrubbing, volume, captions and fullscreen belong to the native player — Kimen ships no custom chrome.

<ki-video label="Play the product tour">
<video poster="/tour-poster.jpg" preload="none">
  <source src="/tour.webm" type="video/webm" />
  <source src="/tour.mp4" type="video/mp4" />
  <track kind="captions" src="/tour.en.vtt" srclang="en" label="English" />
</video>
</ki-video>

The facade contract

Slot exactly one native <video> carrying its own poster, sources and <track> captions, and omit controls — the component enables the native chrome the moment the facade yields. Playback begins only by explicit user activation, never on scroll, hover or visibility: preexisting autoplay and controls on the slotted media are cleared when it arrives, and any playback already running is paused.

API reference

When to use: playable content the person deliberately chooses to watch — product tours, talks, tutorials, announcements — presented as a poster with one play control. Slot exactly one native <video> carrying its own poster, sources and <track> captions, omit controls (the component enables the native chrome the moment the facade yields, FR-002), and give the control a label (required: the accessible name of the play button).

When not to use: decorative background or ambient loops (plain CSS and <video> are the tool), audio-only content (a future audio component), embeds from streaming platforms that ship their own player chrome (use their embed), or static imagery (use an image, not a video). autoplay on the slotted media is unsupported: the facade's contract is that playback begins only by explicit user activation — never on scroll, hover or visibility — so preexisting autoplay and controls on the slotted media are cleared when it arrives, and any playback already running is paused (FR-003; the native chrome returns at activation).

Properties & attributes

Attribute	Property	Type	Default	Description
label	label	string | undefined	–	Accessible name of the play control ("Play the product tour"). The control is a real button exposing role button with exactly this name; the frame contributes no role, name or state of its own (FR-004, FR-005). Documented as required: no default human-language string is baked in, and an unlabeled control renders but fails the accessibility audit (015-ki-progress precedent). The label is never rendered visually.

Slots

Slot	Description
(default)	Exactly one native <video> element carrying its own poster, sources and <track> captions.

CSS parts

Part	Description
frame	The media frame: radius, clipping, the themed surface.
play	The play control: overlay scrim, glass container and glyph.

CSS custom properties

The public styling contract of ki-video: reassign these tokens at :root or on a subtree — never override internals.

Token	Description
--ki-effect-component-primary-default-shadow	MarsUI Component_effect/primary_default: drop 0/1/1/-0.5 plus inner White/12 0/3/3. Pair with backdrop-filter blur(var(--ki-effect-component-backdrop-blur)) — CSS cannot mix backdrop blur into box-shadow.
--ki-effect-component-primary-hover-shadow	MarsUI Component_effect/primary_hover: drops 0/20/20/-12 + 0/3/3/-1.5 + 0/1/1/-0.5 plus inner White/18 0/3/3. Pair with backdrop-filter blur(var(--ki-effect-component-backdrop-blur)).
--ki-motion-duration-fast	Fast interaction transition duration.
--ki-motion-duration-medium-1	M3 md.sys.motion.duration.medium1 (250ms). onmars: MarsUI moderate step (240ms, 2x the 120ms base).
--ki-motion-easing-out	Decelerating interaction transition easing curve.
--ki-motion-easing-standard-accelerate	Utility exit curve. M3 md.sys.motion.easing.standard-accelerate. onmars: the MarsUI accelerate curve (ki.easing.in).
--ki-typography-family-body	semantic font family for typography family body.
--ki-video-backdrop-blur	dimension used by the video component for the glass backdrop of the scrim and the play container (MarsUI Blur/24, identical to the button glass). material3 resolves to blur none via the semantic override.
--ki-video-focus-ring-color	color used by the video component for the play control focus ring: the keyboard-reachable facade control (FR-004, S6) adopts the ki-dialog/ki-icon-button focus-ring pair verbatim.
--ki-video-focus-ring-offset	dimension used by the video component for the play control focus ring offset (ki-dialog precedent).
--ki-video-focus-ring-width	dimension used by the video component for the play control focus ring width (ki-dialog precedent).
--ki-video-frame-radius	dimension used by the video component for the frame corners: Radius/big_component/radius_xs, the exact variable bound to the Size=md Video frame (node 12089:6570, specs/025-ki-video/design-extraction.md) — the sm frame's radius_md is the scale demo, not a second API value.
--ki-video-motion-duration	duration used by the video component for the facade dismissal fade: the Figma set documents no motion, so onmars resolves the single transition to the fast semantic duration (FR-013; disabled under reduced motion by construction, 024 precedent).
--ki-video-play-bg	color used by the video component for the play container surface: Surface/inverse_white, the exact variable bound to the Icon_button fill (black over light, white over dark) — the control carries its own surface so glyph contrast never depends on the poster imagery (FR-008).
--ki-video-play-border-color	color used by the video component for the play container bevel: Outline/primary_button_top, the exact variable bound to the Icon_button stroke — the verified ki-button glass bevel.
--ki-video-play-border-width	dimension used by the video component for the play container bevel width (MarsUI hairline stroke, ki-icon-button precedent).
--ki-video-play-fg	color used by the video component for the play glyph: Text/inverse_black, the counterpart of the inverse container surface (white over light, black over dark) — the glyph inherits it via currentColor; the -bg/-fg pair is swept by the contrast gate (FR-008).
--ki-video-play-icon-size	dimension used by the video component for the play glyph: the 28px Icon/Placeholder_xl slot measured inside the Size=md play container (the ki-icon-button xl icon size).
--ki-video-play-radius	dimension used by the video component for the play container shape: Radius/component/radius_xl, the exact variable bound to the Size=md Icon_button instance (14px, the ki-icon-button xl radius).
--ki-video-play-shadow	shadow used by the video component for the play control (MarsUI stacks Elevation/e6 on the button_wrap beneath the Component_effect/primary_default inner White/12 highlight — the measured master stack).
--ki-video-play-size	dimension used by the video component for the play container box: the 56px Icon_button instance of the Size=md Video (the ki-icon-button xl box; the sm variant's 40px box is the scale demo).
--ki-video-scrim-color	color used by the video component for the overlay scrim behind the play control: Inverse_white/alpha_6, the exact variable bound to the Play halo on both Video variants (Black/5 light, White/5 dark) — the scheme flip rides the semantic layer.
--ki-video-scrim-padding	dimension used by the video component for the scrim clearance around the play container: Space/3xl, the exact variable bound as the Size=md Play halo padding (16px on every side).
--ki-video-scrim-radius	dimension used by the video component for the overlay scrim shape: Radius/component/radius_6xl, the exact variable bound to the Size=md Play halo (28px pill-cornered square).

Accessibility

label is required — it names the play control (“Play the product tour”). Captions travel with the slotted media as native <track> elements, so the native player’s caption UI works untouched. For decorative background loops use plain CSS and <video>; for platform embeds that ship their own chrome, use their embed.

Workshop

Open ki-video in Storybook