@videojs/html 10.0.0-rc.2 → 10.0.0-rc.3

package/docs/{how-to/cast-to-airplay-and-chromecast.md → guides/casting.md}

@@ -4,23 +4,17 @@ Send playback to AirPlay and Google Cast devices, with availability detection an
 
 Send playback to an Apple TV over AirPlay or a Chromecast over Google Cast while the browser stays in control.
 
-Note
-
-Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+> **Note**
+>
+> Using a pre-built [skin](./skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](./ui-components.md).
 
 ## Recommended approach
 
-Use the [GoogleCast extension](../reference/google-cast.md) with a [CastButton](../reference/cast-button.md), and add an [AirPlayButton](../reference/airplay-button.md) for Safari. The prebuilt skins already include both buttons; add `GoogleCast` next to a streaming media component to enable the configurable Cast route.
-
-Stop AirPlay Start AirPlay Stop casting Start casting
-
-index.html
-
-index.css
+Use the [`<google-cast>` extension](../reference/components/google-cast.md) with a [`<media-cast-button>`](../reference/components/cast-button.md), and add an [`<media-airplay-button>`](../reference/components/airplay-button.md) for Safari. The prebuilt skins already include both buttons; add `<google-cast>` next to a streaming media component to enable the configurable Cast route.
 
-index.ts
+**index.html**
 
-```
+```html
 <video-player class="video-player">
   <media-container>
     <hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hlsjs-video>
@@ -38,7 +32,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player {
   position: relative;
   display: block;
@@ -99,37 +96,41 @@ index.ts
   filter: grayscale(1);
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
 import '@videojs/html/extensions/google-cast';
 import '@videojs/html/media/hlsjs-video';
 import '@videojs/html/ui/airplay-button';
 import '@videojs/html/ui/cast-button';
 ```
 
-The demo pairs the streaming media component with the `GoogleCast` extension in React or `<google-cast>` in HTML. Without that extension, `CastButton` drives the browser’s native Remote Playback API instead, which does not provide Video.js receiver or load-request configuration.
+The demo pairs the streaming media element with the `<google-cast>` extension. Without that extension, `<media-cast-button>` drives the browser’s native Remote Playback API instead, which does not provide Video.js receiver or load-request configuration.
 
 ## How it works
 
-The [remote playback feature](../reference/feature-remote-playback.md) gives AirPlay and Google Cast one state shape:
+The [remote playback feature](../reference/api/feature-remote-playback.md) gives AirPlay and Google Cast one state shape:
 
-*   `remotePlaybackAvailability` is `'available'` when a remote device can be reached, `'unavailable'` when the API exists but no device is reachable, and `'unsupported'` when the browser has no remote playback route.
-*   `remotePlaybackState` is `'disconnected'`, `'connecting'`, or `'connected'`.
-*   `toggleRemotePlayback()` opens the browser’s device picker, or disconnects an active session.
+- `remotePlaybackAvailability` is `'available'` when a remote device can be reached, `'unavailable'` when the API exists but no device is reachable, and `'unsupported'` when the browser has no remote playback route.
+- `remotePlaybackState` is `'disconnected'`, `'connecting'`, or `'connected'`.
+- `toggleRemotePlayback()` opens the browser’s device picker, or disconnects an active session.
 
 AirPlay uses WebKit’s presentation APIs. Google Cast uses a sender and receiver: the browser sends the receiver a media URL and then controls playback. Your UI reads the same Video.js state for either route.
 
 While connected, playback actions — play, pause, seek, volume — proxy to the remote device, and player state keeps reflecting the remote session. Local playback is suspended.
 
-The Google Cast SDK loads only when the `GoogleCast` extension is present in a Chromium browser. Players without that extension and browsers that cannot cast do not load it.
+The Google Cast SDK loads only when the `<google-cast>` extension is present in a Chromium browser. Players without that extension and browsers that cannot cast do not load it.
 
 ## Availability and constraints
 
-*   Remote playback is asynchronous and can fail mid-session when a device or network disappears. React to `remotePlaybackState` rather than assuming a request succeeds.
-*   Google Cast works only in Chromium-based browsers; elsewhere its route reports `'unsupported'`.
-*   AirPlay works only in Safari; availability requires an AirPlay device reachable on the network.
-*   The remote device fetches the source and tracks itself. Localhost, VPN-only, expired, or cross-origin URLs without the necessary CORS headers will fail on the receiver even if they play in the browser.
-*   Set `disableRemotePlayback` on the media element to opt out entirely.
+- Remote playback is asynchronous and can fail mid-session when a device or network disappears. React to `remotePlaybackState` rather than assuming a request succeeds.
+- Google Cast works only in Chromium-based browsers; elsewhere its route reports `'unsupported'`.
+- AirPlay works only in Safari; availability requires an AirPlay device reachable on the network.
+- The remote device fetches the source and tracks itself. Localhost, VPN-only, expired, or cross-origin URLs without the necessary CORS headers will fail on the receiver even if they play in the browser.
+- Set the `disableremoteplayback` attribute on the media element to opt out entirely.
 
 ## Common variations
 
@@ -137,17 +138,15 @@ The Google Cast SDK loads only when the `GoogleCast` extension is present in a C
 
 By default, Video.js sends the current source to Google’s Default Media Receiver. Set `receiver` when you have your own receiver application:
 
-html
-
-```
+```html
 <google-cast receiver="YOUR_APP_ID"></google-cast>
 ```
 
-Use `src` and `contentType` when the receiver should load a different source than the browser. `streamType` and `customData` let you describe that source and attach application-specific data. See the [GoogleCast reference](../reference/google-cast.md) for the exact option types and HTML property mapping.
+Use `src` and `contentType` when the receiver should load a different source than the browser. `streamType` and `customData` let you describe that source and attach application-specific data. See the [`<google-cast>` reference](../reference/components/google-cast.md) for the exact option types and attribute-to-property mapping.
 
 ### Read connection state
 
-Use `remotePlaybackAvailability` to decide whether to offer a route and `remotePlaybackState` to show whether it is disconnected, connecting, or connected. `CastButton` and `AirPlayButton` already apply these states to their presentation; read them directly only when another part of your app needs them.
+Use `remotePlaybackAvailability` to decide whether to offer a route and `remotePlaybackState` to show whether it is disconnected, connecting, or connected. `<media-cast-button>` and `<media-airplay-button>` already apply these states to their presentation; read them directly only when another part of your app needs them.
 
 ## Troubleshooting
 
@@ -163,17 +162,19 @@ The receiver cannot fetch the media. Confirm the source URL is reachable from th
 
 The user dismissed the picker or the device disconnected. `remotePlaybackState` returns to `'disconnected'`; drive your UI from that state.
 
-## Related components
+## Related pages
+
+### Components
 
-*   [Cast button](../reference/cast-button.md)
-*   [AirPlay button](../reference/airplay-button.md)
-*   [GoogleCast](../reference/google-cast.md)
+- [media-cast-button](../reference/components/cast-button.md): Accessible Cast toggle button with state reflection and keyboard support
+- [media-airplay-button](../reference/components/airplay-button.md): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
+- [google-cast](../reference/components/google-cast.md): Options for the Google Cast extension that configures the receiver and load request
 
-## Related API
+### API
 
-*   [Remote playback feature](../reference/feature-remote-playback.md)
-*   [HlsJsVideo](../reference/hlsjs-video.md)
+- [Remote Playback](../reference/api/feature-remote-playback.md): Remote playback state and actions for the player store
+- [hlsjs-video](../reference/components/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
 
-## Related guides
+### Guides
 
-*   [Media sources](../concepts/media-sources.md)
+- [Media sources](./media-sources.md): Set what a media element plays and how its engine plays it with the structured source property

package/docs/guides/cdn.md

@@ -0,0 +1,102 @@
+# CDN
+
+Understand the browser-ready bundles, stylesheets, and URL layout published by the Video.js CDN
+
+Start with the [CDN Installation Guide](./installation-cdn.md) to load Video.js and add a working player. This guide documents the browser-ready files the CDN serves and the layout rules behind their URLs.
+
+## CDN URLs
+
+Every file the CDN serves follows one URL pattern:
+
+```plaintext
+https://cdn.jsdelivr.net/npm/@videojs/cdn@<version>/<file>
+```
+
+> **Caution: Pin all your CDN URLs to the same version.**
+>
+> Bundles share content-hashed chunks that change between releases. A tag like `@latest` re-resolves over time, so two files might come from different releases and load duplicate modules that no longer share state.
+
+## Player bundles
+
+Each installation [preset](./presets.md) ships its bundles at the package root: one per skin choice, plus a player-only bundle. For the video preset:
+
+| File | Registers |
+| --- | --- |
+| `video.js` | `<video-player>`, `<video-skin>`, and the UI elements the skin composes |
+| `video-minimal.js` | `<video-player>`, `<video-minimal-skin>`, and the UI elements the minimal skin composes |
+| `video-player.js` | `<video-player>` alone, for markup without a packaged skin |
+
+The other presets follow the same pattern. Background video is the exception: one bundle, `background.js`, registers the player, the skin, and the `<background-video>` media element.
+
+A skin bundle registers every UI element its skin is built from. Any element the skin does not compose is its own bundle under `ui/`.
+
+## UI element bundles
+
+Each [UI element](./ui-components.md) is its own bundle under `ui/`, for markup that a skin bundle does not already cover: a player-only bundle, [skin source](./customize-skins.md#style-skin-source) that adds a component the packaged skin lacks, or a [dialog](../reference/components/dialog.md) your page opens beside a packaged skin.
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video-player.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/ui/play-button.js"></script>
+```
+
+Each path mirrors its npm subpath: `ui/play-button.js` registers the element that `@videojs/html/ui/play-button` does. Compound components list one bundle per part in their reference page’s Import section, and all of the bundles share chunks with the player.
+
+## Media bundles
+
+The default presets play through the browser’s own `<video>` and `<audio>`. Every other [media element](./media-sources.md) is its own bundle under `media/`, loaded beside the player bundle:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/hlsjs-video.js"></script>
+```
+
+Each path mirrors its npm subpath. Elements with more than one playback engine keep the extra flavors in a directory named for the element, such as `media/mux-video/spf.js`. Load one flavor per page: every flavor claims the same tag name, and the first registration wins.
+
+## Extension bundles
+
+Each [extension](./architecture.md) is its own bundle under `extensions/`, loaded beside the player and media bundles:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/extensions/mux-data.js"></script>
+```
+
+As with media, each path mirrors its npm subpath: `extensions/mux-data.js` registers the element that `@videojs/html/extensions/mux-data` does.
+
+## Locales
+
+English ships inside the skin bundles. Each other locale is a bundle under `locales/` that registers its translations on import. Load it before the player script to avoid a flash of English:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/locales/es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/video.js"></script>
+```
+
+One bundle exists per locale pack, plus bare-language aliases such as `pt`. For custom strings, see [Internationalize the player](./internationalization.md).
+
+## Stylesheets
+
+The skin bundles inline their CSS, so no `<link>` is required to render. The separate `.css` files do the jobs a bundle cannot:
+
+- `global.css` holds the light-DOM rules. Link it in `<head>` and the player reserves its space before the elements upgrade. The background preset uses `background.css` instead.
+- The skin sheets, such as `video.css` beside `video.js`, style declaratively rendered skins.
+- `shadow.css` holds the shadow-root integration rules that hand-written shadow skins build on.
+
+[Self-host the player](./self-hosting.md) shows both in use.
+
+## Development bundles
+
+Every JavaScript entry has a `.dev.js` sibling, such as `video.dev.js`, built with development warnings on. Swap the suffix while debugging; swap it back to ship.
+
+## Shared chunks
+
+Everything else at the root, including content-hashed files such as `adapter-<hash>.js`, is a shared chunk the entries import by relative path. Entries share these chunks, so loading several bundles stays cheap. Chunk names change every release: never link a chunk directly, and never copy a lone entry file. To mirror the CDN, copy the whole package directory and keep its layout; [Self-host the player](./self-hosting.md) covers it.
+
+## Related pages
+
+### Guides
+
+- [CDN Installation Guide](./installation-cdn.md): Load Video.js from jsDelivr and build an HTML video player without installing Video.js packages
+- [Self-host the player](./self-hosting.md): Serve the Video.js HTML player from your own origin for offline, air-gapped, or restricted-network deployments
+- [Internationalize the player](./internationalization.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.

package/docs/guides/content-security-policy.md

@@ -0,0 +1,37 @@
+# Content Security Policy
+
+Allow the media, images, workers, and styles a Video.js player needs when your page enforces a Content Security Policy
+
+Content Security Policy (CSP) limits which resources a page can load. Video.js uses the URLs you configure for media, posters, thumbnails, and captions. Some HLS renderers also create blob URLs or web workers, so your policy must allow those resources too.
+
+## Allow player resources
+
+- `media-src` must allow your media URLs.
+- `img-src` must allow any poster or thumbnail image URLs.
+- `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
+- `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
+- `worker-src blob:` is required when using the `hls.js` player variants.
+- `style-src 'unsafe-inline'` is required for some player UI and HTML player styling behavior.
+
+## Recommended policy
+
+```http
+Content-Security-Policy:
+  script-src 'self';
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' https: data: blob:;
+  media-src 'self' https: blob:;
+  connect-src 'self' https:;
+  worker-src 'self' blob:;
+```
+
+This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
+
+Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.
+
+## Related pages
+
+### Guides
+
+- [Installation](./installation.md): Install Video.js packages and build an accessible, customizable video player with composable controls
+- [Self-host the player](./self-hosting.md): Serve the Video.js HTML player from your own origin for offline, air-gapped, or restricted-network deployments

package/docs/{how-to/show-and-hide-controls.md → guides/controls.md}

@@ -2,25 +2,17 @@
 
 Show controls while the user is active, hide them during playback, and toggle them by touch.
 
-Show controls while the user is active, fade them out during undisturbed playback, and bring them back on interaction.
-
-Note
-
-Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+> **Note**
+>
+> Using a pre-built [skin](./skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](./ui-components.md).
 
 ## Recommended approach
 
-Wrap your control UI in [Controls](../reference/controls.md). It reads controls visibility from player state, so the whole control bar shows and hides as one unit.
-
-Play Pause
-
-index.html
+Wrap your control UI in [`<media-controls>`](../reference/components/controls.md). It reads controls visibility from player state, so the whole control bar shows and hides as one unit.
 
-index.css
+**index.html**
 
-index.ts
-
-```
+```html
 <video-player class="video-player">
   <media-container>
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
@@ -40,7 +32,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .video-player media-container {
   position: relative;
   display: block;
@@ -121,21 +116,27 @@ index.ts
   display: inline;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
 import '@videojs/html/ui/controls';
+import '@videojs/html/ui/controls-backdrop';
+import '@videojs/html/ui/controls-content';
+import '@videojs/html/ui/controls-group';
 import '@videojs/html/ui/play-button';
 import '@videojs/html/ui/time';
 ```
 
 ## How it works
 
-The [controls feature](../reference/feature-controls.md) tracks activity on the player container:
+The [controls feature](../reference/api/feature-controls.md) tracks activity on the player container:
 
-*   `userActive` is `true` while the user interacts — pointer movement, keyboard input, or focus — and flips to `false` after two seconds of inactivity.
-*   `controlsVisible` derives from activity and playback: controls stay visible while paused or while a remote playback session is connecting or connected, regardless of idle state.
-*   `toggleControls()` flips visibility, for wiring to custom triggers.
+- `userActive` is `true` while the user interacts — pointer movement, keyboard input, or focus — and flips to `false` after two seconds of inactivity.
+- `controlsVisible` derives from activity and playback: controls stay visible while paused or while a remote playback session is connecting or connected, regardless of idle state.
+- `toggleControls()` flips visibility, for wiring to custom triggers.
 
 On touch devices, a tap on the media toggles the controls instead of relying on pointer movement, and mid-gesture movement doesn’t flicker visibility.
 
@@ -143,20 +144,18 @@ The feature needs the player container for activity tracking; without a containe
 
 ## Availability and constraints
 
-*   Activity tracking listens on the player container, so controls placed outside it don’t keep the player “active” — put control UI inside the container.
-*   Keyboard focus counts as activity: controls stay reachable for keyboard and assistive-technology users while focus is inside them.
-*   Touch and mouse behave differently by design — mouse movement shows controls, touch requires a tap. Test both.
-*   The idle delay is fixed at two seconds.
+- Activity tracking listens on the player container, so controls placed outside it don’t keep the player “active” — put control UI inside the container.
+- Keyboard focus counts as activity: controls stay reachable for keyboard and assistive-technology users while focus is inside them.
+- Touch and mouse behave differently by design — mouse movement shows controls, touch requires a tap. Test both.
+- The idle delay is fixed at two seconds.
 
 ## Common variations
 
 ### Always-visible controls
 
-Set `visibility="always"` on [Controls](../reference/controls.md). The controls stay visible and report the user as active while the feature keeps tracking activity for anything else that needs it. The packaged audio skins use this mode.
+Set `visibility="always"` on [`<media-controls>`](../reference/components/controls.md). The controls stay visible and report the user as active while the feature keeps tracking activity for anything else that needs it. The packaged audio skins use this mode.
 
-html
-
-```
+```html
 <media-controls visibility="always">
   <media-controls-content class="controls">...</media-controls-content>
 </media-controls>
@@ -178,18 +177,20 @@ A tap on the media toggles controls. If a custom overlay covers the media and sw
 
 ### Controls flicker on Android while tapping
 
-Use the skin gestures (`tap` with the `toggleControls` action) rather than adding your own tap handlers next to the built-in behavior; competing handlers invert each other. See [Add keyboard shortcuts and gestures](./add-keyboard-shortcuts-and-gestures.md).
+Use the skin gestures (`tap` with the `toggleControls` action) rather than adding your own tap handlers next to the built-in behavior; competing handlers invert each other. See [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md).
+
+## Related pages
 
-## Related components
+### Components
 
-*   [Controls](../reference/controls.md)
-*   [Player container](../reference/player-container.md)
+- [media-controls](../reference/components/controls.md): Container component for composing and auto-hiding video player controls on user interaction
+- [media-container](../reference/components/player-container.md): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
 
-## Related API
+### API
 
-*   [Controls feature](../reference/feature-controls.md)
+- [Controls](../reference/api/feature-controls.md): User activity and controls visibility state for the player store
 
-## Related guides
+### Guides
 
-*   [Add keyboard shortcuts and gestures](./add-keyboard-shortcuts-and-gestures.md)
-*   [Accessibility](../concepts/accessibility.md)
+- [Add keyboard shortcuts and gestures](./keyboard-shortcuts.md): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
+- [Accessibility](./accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

package/docs/guides/customize-skins.md

@@ -0,0 +1,141 @@
+# Customize skins
+
+Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
+
+Start with the path that matches the change you want:
+
+| If you want to… | Use this path |
+| --- | --- |
+| Change colors, typography, sizing, or how the poster fills the player | [Style a packaged skin](#style-a-packaged-skin). The skin stays in the Video.js package, and you set its supported CSS properties. |
+| Add, remove, rearrange, or deeply restyle controls; change layout or interactions | [Style skin source](#style-skin-source). The `shadcn` CLI adds the skin source to your project so you can change it. |
+
+## Style a packaged skin
+
+Use a packaged skin’s public settings to match it to your site without copying its source into your project.
+
+### Set the skin’s styles
+
+Packaged skins expose [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for their supported visual changes. Set them on the skin or any element that contains it:
+
+```html
+<video-skin style="--media-accent-color: #f5c518; --media-border-radius: 1rem">
+  <video src="video.mp4"></video>
+</video-skin>
+```
+
+| Property name | What it changes | Value | Example |
+| --- | --- | --- | --- |
+| `--media-accent-color` | Slider fills, highlighted controls and menu items, and primary actions | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `#f5c518` |
+| `--media-accent-text-color` | Text and icons shown on the accent color | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `black` |
+| `--media-border-color` | The hairline around the player | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `transparent` |
+| `--media-border-radius` | The player corner radius | A valid [border-radius value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-radius#values) | `1rem` |
+| `--media-font-family` | The player interface font stack | A valid [font-family value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family) | `Roboto, sans-serif` |
+| `--media-object-fit` | How the media and poster fill the player | A valid [object-fit value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-fit) | `cover` |
+| `--media-object-position` | Where the media and poster sit when they do not fill the player | A valid [object-position value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-position) | `top` |
+| `--media-scale-unit` | The base size for skin spacing, icons, and text | [`<length>`](https://developer.mozilla.org/en-US/docs/Web/CSS/length) | `1rem` |
+
+If you omit `--media-accent-text-color`, the skins choose a contrasting text color from `--media-accent-color` using [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/contrast-color). Set it only when you want a different result.
+
+The skins use [`Inter`](https://rsms.me/inter/) when your page loads it and fall back to the system UI font. Video.js does not load the webfont for you. Set `--media-font-family` to use another font.
+
+The media element and poster share `--media-object-fit` and `--media-object-position`, so a `cover` poster stays aligned with `cover` video. See [Add a poster and loading placeholder](./poster.md).
+
+### Set the color scheme
+
+The audio skins adapt their main palette for light and dark mode using [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark). They read the inherited [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme), so set it on the player or an element that contains it:
+
+```css
+:root {
+  color-scheme: light dark;
+}
+```
+
+The video skins keep their dark controls in both color schemes. Only their hairline border follows the scheme, and `--media-border-color` replaces it.
+
+### Scale from the document font size
+
+The skins derive control spacing, icon sizes, and text from `--media-scale-unit`. It defaults to `16px`, so the player does not change with the document root font size or your app’s Tailwind spacing scale. Set it to `1rem` to make the interface scale from the document root font size:
+
+```css
+.player {
+  --media-scale-unit: 1rem;
+}
+```
+
+In fullscreen, the skins increase the unit up to 1.75 times on displays 1920 pixels and wider. This keeps controls legible from a distance.
+
+You can also add your own class names to the skins.
+
+### Know where packaged styling stops
+
+The properties above are the public styling settings for packaged skins. Do not depend on the elements, class names, or other custom properties inside a packaged skin. They may change between releases.
+
+Packaged video skins also let you replace the poster through the `poster` slot.
+
+See [`<media-poster>`](../reference/components/poster.md).
+
+Packaged skins do not provide settings for adding, removing, or rearranging controls, or for replacing built-in feedback and interactions. To make those changes, [add the source for the closest skin to your project](#style-skin-source) and edit it directly.
+
+## Style skin source
+
+If a packaged skin is close to the interface you want, add its source to your project and edit it. The source contains the skin’s controls, layout, styles, and interactions.
+
+Video.js publishes skin source in an installable catalog. The [`shadcn` CLI](https://ui.shadcn.com/docs/cli) adds that source to your project, whether you use React or HTML.
+
+The selected skin is generally placed under `components/videojs/<preset>`, with shared controls and styles alongside it under `components/videojs`. The exact root follows the components alias in `components.json`. The CLI can also install package dependencies, update `components.json`, and add shared styles to your main CSS file.
+
+> **Note**
+>
+> Commit your work before installing or updating source. You can then review every file the CLI adds or replaces.
+
+### Add the source
+
+The Shadcn installation guide handles project setup, lets you choose the skin and styling, and shows how to use the installed source in a working player.
+
+- [Install Video.js with Shadcn](./installation-shadcn.md): Add editable skin source and build a working React or HTML player
+
+### Use the installed skin
+
+The skin directory contains `skin.html`, `skin.ts`, and `skin.css`. Keep importing the player and media from `@videojs/html`. Import the installed `skin.ts` once, then paste the markup from `skin.html` inside your player around the media element.
+
+### Edit the installed files
+
+Start with the file that owns the change you want:
+
+| Goal | Where to start |
+| --- | --- |
+| Add, remove, or rearrange controls | `skin.html` |
+| Change default colors, surfaces, shadows, sizes, or motion across skins | `components/videojs/styles/themes/theme.css` |
+| Change only the Minimal theme or one media preset | `components/videojs/styles/themes/minimal.css`, `components/videojs/styles/video/theme.css`, or `components/videojs/styles/audio/theme.css` |
+| Change one control’s appearance | That control’s classes or stylesheet |
+| Change one control’s interaction | That control’s module |
+
+The `skin.html` file contains the layout. The `skin.ts` module registers the custom elements and loads `skin.css`. Elements use class names that start with `media-`; change a class in `skin.html` or a rule in the stylesheet to change one part of the interface.
+
+### Inspect or update the skin source
+
+Use the CLI’s `search` command to find source and `view` to inspect it before installation:
+
+```bash
+npx shadcn@latest search @videojs --query volume
+npx shadcn@latest view @videojs/video
+```
+
+Installed files belong to your project, so an update replaces your local copy. Commit your changes, reinstall with `--overwrite`, and review the resulting version-control diff before keeping it:
+
+```bash
+npx shadcn@latest add @videojs/video --overwrite
+```
+
+To understand how skins fit into Video.js, read [Skins](./skins.md). To create a control instead of editing one, follow [Build your own component](./build-your-own-component.md).
+
+## Related pages
+
+### Components
+
+- [video-skin](../reference/components/video-skin.md): The video preset's default skin with the modern, frosted look
+
+### Guides
+
+- [Skins](./skins.md): Packaged player designs that include both UI components and their styles.
+- [Build your own UI component](./build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.