From 9e4af60361f2269ab56832742f642855d08fb93d Mon Sep 17 00:00:00 2001
From: Darius Cepulis <dcepulis@mux.com>
Date: Wed, 29 Oct 2025 23:28:55 -0500
Subject: [PATCH] docs: initial concepts and recipes (#147)

---
 site/src/components/HomePageDemo/Base.tsx     |   2 +
 site/src/components/HomePageDemo/Eject.tsx    |   2 +
 site/src/components/HomePageDemo/index.tsx    |   8 +-
 site/src/components/NavBar/NavBar.astro       |   2 +-
 site/src/components/docs/Container.astro      |   7 -
 site/src/components/docs/DocsLink.astro       |   7 +-
 site/src/components/docs/SidebarItem.astro    |   2 +-
 site/src/components/frames/Minimal.astro      |  33 ++++
 site/src/components/home/HeroVideo.tsx        |   4 +-
 site/src/components/home/config.ts            |   3 -
 site/src/components/typography/H5.astro       |   2 +-
 site/src/config/docs/sidebar.ts               |  53 +++---
 site/src/consts.ts                            |  18 ++
 .../content/docs/concepts/architecture.mdx    | 128 ++++++++++++++
 site/src/content/docs/concepts/skins.mdx      | 156 ++++++++++++++++++
 .../content/docs/concepts/ui-components.mdx   | 101 ++++++++++++
 .../src/content/docs/concepts/v10-roadmap.mdx |  81 +++++++++
 .../content/docs/how-to/customize-skins.mdx   |   6 +
 site/src/content/docs/how-to/installation.mdx | 116 +++++++++++++
 site/src/content/docs/how-to/write-guides.mdx |  16 +-
 .../fullscreen-button.mdx                     |   1 -
 .../{resources => reference}/mute-button.mdx  |   1 -
 .../{resources => reference}/play-button.mdx  |   1 -
 .../{resources => reference}/time-slider.mdx  |   1 -
 .../volume-slider.mdx                         |   1 -
 .../react/FrostedSkin/FrostedSkinDemo.tsx     |  27 +++
 .../FullscreenButton/FullscreenButtonDemo.tsx |   5 +-
 .../react/MinimalSkin/MinimalSkinDemo.tsx     |  26 +++
 .../react/MuteButton/MuteButtonDemo.tsx       |   5 +-
 .../react/PlayButton/PlayButtonDemo.tsx       |   5 +-
 .../react/TimeSlider/TimeSliderDemo.tsx       |   5 +-
 .../react/VolumeSlider/VolumeSliderDemo.tsx   |   5 +-
 site/src/layouts/Base.astro                   |   2 -
 site/src/layouts/Blog.astro                   |   2 +
 site/src/layouts/Docs.astro                   |  10 +-
 site/src/pages/index.astro                    |   9 +-
 site/src/utils/docs/__tests__/title.test.ts   |   8 +-
 37 files changed, 777 insertions(+), 84 deletions(-)
 delete mode 100644 site/src/components/docs/Container.astro
 create mode 100644 site/src/components/frames/Minimal.astro
 delete mode 100644 site/src/components/home/config.ts
 create mode 100644 site/src/content/docs/concepts/architecture.mdx
 create mode 100644 site/src/content/docs/concepts/skins.mdx
 create mode 100644 site/src/content/docs/concepts/ui-components.mdx
 create mode 100644 site/src/content/docs/concepts/v10-roadmap.mdx
 create mode 100644 site/src/content/docs/how-to/customize-skins.mdx
 create mode 100644 site/src/content/docs/how-to/installation.mdx
 rename site/src/content/docs/{resources => reference}/fullscreen-button.mdx (97%)
 rename site/src/content/docs/{resources => reference}/mute-button.mdx (97%)
 rename site/src/content/docs/{resources => reference}/play-button.mdx (97%)
 rename site/src/content/docs/{resources => reference}/time-slider.mdx (98%)
 rename site/src/content/docs/{resources => reference}/volume-slider.mdx (98%)
 create mode 100644 site/src/examples/react/FrostedSkin/FrostedSkinDemo.tsx
 create mode 100644 site/src/examples/react/MinimalSkin/MinimalSkinDemo.tsx

diff --git a/site/src/components/HomePageDemo/Base.tsx b/site/src/components/HomePageDemo/Base.tsx
index 2a789577..3448d52b 100644
--- a/site/src/components/HomePageDemo/Base.tsx
+++ b/site/src/components/HomePageDemo/Base.tsx
@@ -56,6 +56,7 @@ export default function BaseDemo({ className }: { className?: string }) {
         aria-label="HTML implementation"
         titles={{ html: 'HTML', css: 'CSS', javascript: 'JavaScript' }}
         className={className}
+        maxWidth={false}
       >
         <TabsPanel tabsId="base-html" value="html">
           <ClientCode code={generateHTMLCode($skin, $media)} lang="html" />
@@ -76,6 +77,7 @@ export default function BaseDemo({ className }: { className?: string }) {
       aria-label="React implementation"
       titles={{ react: 'React' }}
       className={className}
+      maxWidth={false}
     >
       <TabsPanel tabsId="base-react" value="react">
         <ClientCode code={generateReactCode($skin, $media)} lang="tsx" />
diff --git a/site/src/components/HomePageDemo/Eject.tsx b/site/src/components/HomePageDemo/Eject.tsx
index dc2ee374..54ec3fc1 100644
--- a/site/src/components/HomePageDemo/Eject.tsx
+++ b/site/src/components/HomePageDemo/Eject.tsx
@@ -36,6 +36,7 @@ export default function EjectDemo({ className }: { className?: string }) {
         aria-label="HTML implementation"
         titles={{ html: 'HTML', css: 'CSS', javascript: 'JavaScript' }}
         className={className}
+        maxWidth={false}
       >
         <TabsPanel tabsId="eject-html" value="html">
           <ClientCode code={generateHTMLCode($skin, $media)} lang="html" />
@@ -56,6 +57,7 @@ export default function EjectDemo({ className }: { className?: string }) {
       aria-label="React implementation"
       titles={{ react: 'React', css: 'CSS Module' }}
       className={className}
+      maxWidth={false}
     >
       <TabsPanel tabsId="eject-react" value="react">
         <ClientCode code={generateReactCode($skin, $media)} lang="tsx" />
diff --git a/site/src/components/HomePageDemo/index.tsx b/site/src/components/HomePageDemo/index.tsx
index 38dba474..f32cd7a5 100644
--- a/site/src/components/HomePageDemo/index.tsx
+++ b/site/src/components/HomePageDemo/index.tsx
@@ -9,19 +9,19 @@ interface Props {
 export default function HomePageDemo({ className }: Props) {
   return (
     <section className={clsx('grid gap-x-9 gap-y-6 lg:grid-cols-2', className)}>
-      <section className="grid grid-rows-subgrid row-span-2 mb-6">
+      <section className="grid grid-rows-subgrid row-span-2">
         <header className="max-w-3xl">
           <h2 className="text-h5 font-semibold lg:text-h4 mb-1">Assemble your player</h2>
           <p>Feel at home with your framework, skin, and media source</p>
         </header>
-        <BaseDemo className="lg:h-100" />
+        <BaseDemo className="lg:h-100 m-0" />
       </section>
-      <section className="grid grid-rows-subgrid row-span-2 mb-6">
+      <section className="grid grid-rows-subgrid row-span-2">
         <header className="max-w-3xl">
           <h2 className="text-h5 font-semibold lg:text-h4 mb-1">Take full control</h2>
           <p>Make your player truly your own with fully-editable components</p>
         </header>
-        <EjectDemo className="lg:h-100" />
+        <EjectDemo className="lg:h-100 m-0" />
       </section>
     </section>
   );
diff --git a/site/src/components/NavBar/NavBar.astro b/site/src/components/NavBar/NavBar.astro
index 8dfc0edb..b457a76c 100644
--- a/site/src/components/NavBar/NavBar.astro
+++ b/site/src/components/NavBar/NavBar.astro
@@ -36,7 +36,7 @@ const { class: className, dark = false } = Astro.props;
   style="height: var(--nav-h);"
 >
   <!-- Logo -->
-  <a href="/" class="flex items-center px-3 text-h5">Video.js</a>
+  <a href="/" class="flex items-center px-3 text-h5">Video.js v10</a>
 
   <!-- Desktop nav links -->
   <div class="hidden sm:flex -mb-px pr-3">
diff --git a/site/src/components/docs/Container.astro b/site/src/components/docs/Container.astro
deleted file mode 100644
index badcf6a7..00000000
--- a/site/src/components/docs/Container.astro
+++ /dev/null
@@ -1,7 +0,0 @@
----
-// Simple container component for constraining content width in documentation
----
-
-<div class="w-full max-w-3xl mx-auto">
-  <slot />
-</div>
diff --git a/site/src/components/docs/DocsLink.astro b/site/src/components/docs/DocsLink.astro
index 6da6b12e..4bc73adb 100644
--- a/site/src/components/docs/DocsLink.astro
+++ b/site/src/components/docs/DocsLink.astro
@@ -2,11 +2,12 @@
 import { isValidFramework, isValidStyleForFramework } from '@/types/docs';
 import { resolveDocsLinkUrl } from '@/utils/docs/routing';
 import type { HTMLAttributes } from 'astro/types';
+import A from '../typography/A.astro';
 
 interface Props extends Omit<HTMLAttributes<'a'>, 'href'> {
   slug: string;
 }
-const { slug, ...rest } = Astro.props;
+const { slug } = Astro.props;
 
 const { framework: paramFramework, style: paramStyle } = Astro.params;
 if (!paramFramework || !isValidFramework(paramFramework)) {
@@ -23,6 +24,6 @@ const { url: href } = resolveDocsLinkUrl({
 });
 ---
 
-<a href={href} {...rest}>
+<A href={href}>
   <slot />
-</a>
+</A>
diff --git a/site/src/components/docs/SidebarItem.astro b/site/src/components/docs/SidebarItem.astro
index c1ee43db..6b4c4cec 100644
--- a/site/src/components/docs/SidebarItem.astro
+++ b/site/src/components/docs/SidebarItem.astro
@@ -29,7 +29,7 @@ const isActive = containsActivePath(item);
 
 {
   isSection(item) ? (
-    <details open class="group" style={`padding-left: calc(var(--spacing) * ${depth * 4})`}>
+    <details open class="group my-4 first:mt-0" style={`padding-left: calc(var(--spacing) * ${depth * 4})`}>
       <summary
         class:list={[
           'py-2 flex items-center gap-4 ',
diff --git a/site/src/components/frames/Minimal.astro b/site/src/components/frames/Minimal.astro
new file mode 100644
index 00000000..73befffc
--- /dev/null
+++ b/site/src/components/frames/Minimal.astro
@@ -0,0 +1,33 @@
+---
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Minimal frame component for wrapping documentation demos.
+ *
+ * Provides a styled container with rounded borders and background
+ * matching the site's Tabs component aesthetic.
+ *
+ * Usage:
+ * ```mdx
+ * import Minimal from '@/components/frames/Minimal.astro';
+ *
+ * <MinimalFrame>
+ *   <MyDemo client:load />
+ * </MinimalFrame>
+ * ```
+ */
+
+type Props = {
+  class?: string;
+};
+const { class: className } = Astro.props;
+---
+
+<div
+  class={twMerge(
+    'w-full max-w-3xl mx-auto flex rounded-lg overflow-hidden border border-light-40 dark:border-dark-80 bg-light-100 dark:bg-dark-110',
+    className,
+  )}
+>
+  <slot />
+</div>
diff --git a/site/src/components/home/HeroVideo.tsx b/site/src/components/home/HeroVideo.tsx
index f08b4a62..bbf3ebd8 100644
--- a/site/src/components/home/HeroVideo.tsx
+++ b/site/src/components/home/HeroVideo.tsx
@@ -1,7 +1,7 @@
 import { useStore } from '@nanostores/react';
 import { FrostedSkin, MediaProvider, MinimalSkin, Video } from '@videojs/react';
+import { VJS8_DEMO_VIDEO } from '@/consts';
 import { skin } from '@/stores/homePageDemos';
-import { PLAYBACK_ID } from './config';
 import '@videojs/react/skins/frosted.css';
 import '@videojs/react/skins/minimal.css';
 
@@ -15,7 +15,7 @@ export default function HeroVideo({ className, poster }: { className?: string; p
       <SkinComponent className={className}>
         <Video
           // @ts-expect-error -- types are incorrect
-          src={`https://stream.mux.com/${PLAYBACK_ID}.m3u8`}
+          src={VJS8_DEMO_VIDEO.hls}
           poster={poster}
           playsInline
         />
diff --git a/site/src/components/home/config.ts b/site/src/components/home/config.ts
deleted file mode 100644
index 012268e8..00000000
--- a/site/src/components/home/config.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// video.js 8
-export const PLAYBACK_ID = 'UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA';
-export const THUMB_TIME = 0;
diff --git a/site/src/components/typography/H5.astro b/site/src/components/typography/H5.astro
index e61df1f5..b67d7020 100644
--- a/site/src/components/typography/H5.astro
+++ b/site/src/components/typography/H5.astro
@@ -12,7 +12,7 @@ const { as: Tag = 'h5', maxWidth = true, class: className, ...props } = Astro.pr
 ---
 
 <Tag
-  class={twMerge(clsx('font-medium @lg:text-md @3xl:text-h5 my-6', maxWidth && 'max-w-3xl mx-auto'), className)}
+  class={twMerge(clsx('font-medium @lg:text-md @3xl:text-h5 mb-6 mt-9', maxWidth && 'max-w-3xl mx-auto'), className)}
   {...props}
 >
   <slot />
diff --git a/site/src/config/docs/sidebar.ts b/site/src/config/docs/sidebar.ts
index f05a5b40..bfb21fcf 100644
--- a/site/src/config/docs/sidebar.ts
+++ b/site/src/config/docs/sidebar.ts
@@ -1,35 +1,36 @@
 import type { Sidebar } from '@/types/docs';
 
 export const sidebar: Sidebar = [
-  { sidebarLabel: 'Writing guides', slug: 'how-to/write-guides', devOnly: true },
-  { sidebarLabel: 'Getting started', contents: [{ slug: 'concepts/under-construction' }] },
+  {
+    sidebarLabel: 'Getting started',
+    contents: [
+      { slug: 'how-to/write-guides', sidebarLabel: 'Writing guides', devOnly: true },
+      { slug: 'how-to/installation' },
+      { slug: 'concepts/v10-roadmap', sidebarLabel: 'Roadmap' },
+    ],
+  },
+  {
+    sidebarLabel: 'Concepts',
+    contents: [
+      { slug: 'concepts/architecture' },
+      { slug: 'concepts/skins' },
+      { slug: 'concepts/ui-components' },
+    ],
+  },
+  {
+    sidebarLabel: 'How to',
+    contents: [
+      { slug: 'how-to/customize-skins' },
+    ],
+  },
   {
     sidebarLabel: 'Components',
     contents: [
-      { slug: 'resources/play-button' },
-      { slug: 'resources/mute-button' },
-      { slug: 'resources/fullscreen-button' },
-      { slug: 'resources/time-slider' },
-      { slug: 'resources/volume-slider' },
+      { slug: 'reference/play-button' },
+      { slug: 'reference/mute-button' },
+      { slug: 'reference/fullscreen-button' },
+      { slug: 'reference/time-slider' },
+      { slug: 'reference/volume-slider' },
     ],
   },
-  // {
-  //   sidebarLabel: 'Getting started',
-  //   contents: [
-  //     { slug: 'concepts/everyone' },
-  //   ],
-  // },
-  // {
-  //   sidebarLabel: 'Concepts',
-  //   contents: [
-  //     { slug: 'concepts/react-only', frameworks: ['react'] },
-  //     { slug: 'concepts/tailwind-only', styles: ['tailwind'] },
-  //   ],
-  // },
-  // {
-  //   sidebarLabel: 'How-To Guides',
-  //   contents: [
-  //     { slug: 'how-to/everyone' },
-  //   ],
-  // },
 ];
diff --git a/site/src/consts.ts b/site/src/consts.ts
index 1ceda612..2bcf9afc 100644
--- a/site/src/consts.ts
+++ b/site/src/consts.ts
@@ -3,3 +3,21 @@ export const SITE_DESCRIPTION = `For over 15 years, Video.js has been the world'
 export const GITHUB_REPO_URL = 'https://github.com/videojs/v10/';
 export const DISCORD_INVITE_URL = 'https://discord.gg/yyatwmQr';
 export const THEME_KEY = 'vjs-site-theme';
+
+/**
+ * Video source for demos and examples throughout the site,
+ * wherever JS is used. HTML examples use a separate hardcoded source.
+ */
+interface VideoSource {
+  id: string;
+  hls: string;
+  mp4: string;
+  poster: string;
+}
+
+export const VJS8_DEMO_VIDEO: VideoSource = {
+  id: 'UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA',
+  hls: 'https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA.m3u8',
+  mp4: 'https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/high.mp4',
+  poster: 'https://image.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/thumbnail.webp',
+};
diff --git a/site/src/content/docs/concepts/architecture.mdx b/site/src/content/docs/concepts/architecture.mdx
new file mode 100644
index 00000000..10fcb1dc
--- /dev/null
+++ b/site/src/content/docs/concepts/architecture.mdx
@@ -0,0 +1,128 @@
+---
+title: Architecture
+description: Understanding the three-tier architecture of Video.js v10 - State, UI, and Renderers
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import { TabsRoot, TabsPanel } from '@/components/Tabs';
+import DocsLink from '@/components/docs/DocsLink.astro';
+
+Video.js v10 is built around a three-tier architecture that separates concerns and maximizes flexibility. Each tier is designed to work independently or together, allowing you to use as much or as little of Video.js as you need.
+
+## The Three Tiers
+
+### 1. State Management
+
+<FrameworkCase frameworks={["react"]}>
+State is handled by `MediaProvider`, which creates a central store that all components can access. When you wrap your player in a `MediaProvider`, components automatically connect to the state.
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+State is handled by `media-provider`, which creates a central store that all components can access. When you wrap your player in a `media-provider`, components automatically connect to the state.
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<MediaProvider>
+  {/* All components inside automatically connect to state */}
+</MediaProvider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<media-provider>
+  <!-- All components inside automatically connect to state -->
+</media-provider>
+```
+</FrameworkCase>
+
+### 2. User Interface
+
+#### Skins
+Complete, pre-designed player UIs that package components and styles together:
+- Frosted (glassy design)
+- Minimal (clean, simple design)
+
+Want to learn more? <DocsLink slug="concepts/skins">Read the skins guide →</DocsLink>
+
+#### Components
+Most should use a skin as a starting point. However, if you want more control, you have two options.
+
+First, you can use eject a skin to customize it. <DocsLink slug="how-to/customize-skins">to learn more, check out our guide on customizing skins →</DocsLink>
+
+Next, you can use the individual, unstyled UI primitives, standalone or composed into custom designs:
+- Buttons (Play, Mute, Fullscreen)
+- Sliders (Time, Volume)
+- Displays (CurrentTime, Duration)
+- Compound components (Tooltip, Popover)
+
+Want to dive deeper? <DocsLink slug="concepts/ui-components">Explore UI components →</DocsLink>
+
+### 3. Media Renderers
+
+Media renderers are the components that actually display your media. They're essentially "players with no UI". They handle the video/audio rendering and expose a consistent API.
+
+<FrameworkCase frameworks={["react"]}>
+For now, we're starting with just a `<Video />` component, but we're looking forward to adding more in the future. From engines like HLS and DASH, to services like YouTube and Vimeo.
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+For now, we're starting with just the native HTML5 `<video />` component, but we're looking forward to adding more in the future. From engines like HLS and DASH, to services like YouTube and Vimeo.
+</FrameworkCase>
+
+## How It All Works Together
+
+Here's a complete example showing all three tiers:
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { MediaProvider, FrostedSkin, Video } from '@videojs/react';
+import '@videojs/react/skins/frosted.css';
+
+function Player() {
+  return (
+    // Tier 1: State Management
+    <MediaProvider>
+      {/* Tier 2: User Interface (Skin with components) */}
+      <FrostedSkin>
+        {/* Tier 3: Media Renderer */}
+        <Video src="video.mp4" />
+      </FrostedSkin>
+    </MediaProvider>
+  );
+}
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+<TabsRoot
+  aria-label="HTML implementation"
+  titles={{  html: 'HTML', javascript: 'JavaScript' }}
+  client:load
+>
+    <TabsPanel value="html" client:load>
+
+```html
+<!-- Tier 1: State Management -->
+<media-provider>
+  <!-- Tier 2: User Interface (Skin with components) -->
+  <media-skin-frosted>
+    <!-- Tier 3: Media Renderer -->
+    <video slot="media" src="video.mp4"></video>
+  </media-skin-frosted>
+</media-provider>
+```
+
+  </TabsPanel>
+
+  <TabsPanel value="javascript" client:load>
+
+```ts
+import { defineVjsPlayer } from '@videojs/html';
+import '@videojs/html/skins/frosted';
+
+defineVjsPlayer();
+```
+
+  </TabsPanel>
+
+</TabsRoot>
+</FrameworkCase>
\ No newline at end of file
diff --git a/site/src/content/docs/concepts/skins.mdx b/site/src/content/docs/concepts/skins.mdx
new file mode 100644
index 00000000..7cc6de76
--- /dev/null
+++ b/site/src/content/docs/concepts/skins.mdx
@@ -0,0 +1,156 @@
+---
+title: Skins
+description: Understanding skins in Video.js v10 - packaged sets of UI components and styles
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import { FrostedSkinDemo } from '@/examples/react/FrostedSkin/FrostedSkinDemo';
+import { MinimalSkinDemo } from '@/examples/react/MinimalSkin/MinimalSkinDemo';
+import MinimalFrame from '@/components/frames/Minimal.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+
+In Video.js v10, skins are **complete, packaged player designs** that include both UI components and their styles. This is a significant change from v8, where skins were purely CSS themes applied to a fixed component structure.
+
+## What's Different in v10?
+
+### Video.js v8 Skins
+- CSS-only themes
+- Applied to a fixed component structure
+- Limited customization without JavaScript
+
+### Video.js v10 Skins
+- **UI components + styles packaged together**
+- Each skin can have completely different components
+- Can address entirely different use cases
+- Only include the components they need
+
+## Built-in Skins
+
+### Frosted
+
+A modern, glassy design with backdrop blur effects and polished interactions.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { MediaProvider, FrostedSkin, Video } from '@videojs/react';
+import '@videojs/react/skins/frosted.css';
+
+<MediaProvider>
+  <FrostedSkin>
+    <Video src="video.mp4" />
+  </FrostedSkin>
+</MediaProvider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<media-provider>
+  <media-skin-frosted>
+    <video slot="media" src="video.mp4"></video>
+  </media-skin-frosted>
+</media-provider>
+```
+</FrameworkCase>
+
+<MinimalFrame class="rounded-3xl">
+  <FrostedSkinDemo client:load />
+</MinimalFrame>
+
+### Minimal
+
+A clean, straightforward design that focuses on simplicity and clarity.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { MediaProvider, MinimalSkin, Video } from '@videojs/react';
+import '@videojs/react/skins/minimal.css';
+
+<MediaProvider>
+  <MinimalSkin>
+    <Video src="video.mp4" />
+  </MinimalSkin>
+</MediaProvider>
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```html
+<media-provider>
+  <media-skin-minimal>
+    <video slot="media" src="video.mp4"></video>
+  </media-skin-minimal>
+</media-provider>
+```
+</FrameworkCase>
+
+<MinimalFrame>
+  <MinimalSkinDemo client:load />
+</MinimalFrame>
+
+## Customizing Skins
+
+Skins are designed to be ejected and modified for your specific needs.
+
+Ready to make it your own? <DocsLink slug="how-to/customize-skins">Learn how to customize a skin →</DocsLink>
+
+## Building Your Own Skin
+
+
+A skin is simply a component that:
+<FrameworkCase frameworks={["react"]}>
+1. Wraps content in a `MediaContainer`
+2. Includes a `children` prop (for the media renderer)
+3. Arranges UI components as desired
+4. Provides styles for those components
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+1. Wraps content in a `media-container`
+2. Includes a `<slot>` element (for the media renderer)
+3. Arranges UI components as desired
+4. Provides styles for those components
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { MediaContainer, PlayButton, TimeSlider } from '@videojs/react';
+
+export function CustomSkin({ children, className }) {
+  return (
+    <MediaContainer className={className}>
+      {children}
+      <div className="controls">
+        <PlayButton />
+        <TimeSlider.Root>
+          <TimeSlider.Track>
+            <TimeSlider.Progress />
+          </TimeSlider.Track>
+          <TimeSlider.Thumb />
+        </TimeSlider.Root>
+      </div>
+    </MediaContainer>
+  );
+}
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```html
+<media-provider>
+  <media-container class="custom-skin">
+    <slot></slot>
+    <div class="controls">
+      <vjs-play-button></vjs-play-button>
+      <vjs-time-slider>
+        <!-- Custom skin structure -->
+      </vjs-time-slider>
+    </div>
+  </media-container>
+</media-provider>
+```
+</FrameworkCase>
+
+Read more about components <DocsLink slug="concepts/ui-components">in the components guide →</DocsLink>
+
+## Coming Soon
+
+- More built-in skins for different use cases
+- CLI tool for ejecting and customizing skins
\ No newline at end of file
diff --git a/site/src/content/docs/concepts/ui-components.mdx b/site/src/content/docs/concepts/ui-components.mdx
new file mode 100644
index 00000000..3c7b4037
--- /dev/null
+++ b/site/src/content/docs/concepts/ui-components.mdx
@@ -0,0 +1,101 @@
+---
+title: UI Components
+description: Understanding Video.js v10's primitive-based component architecture
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+
+Video.js v10 components are built from **unstyled UI primitives**, taking inspiration from projects like [shadcn/ui](https://ui.shadcn.com/) and [Base UI](https://base-ui.com/). This approach gives you control over styling and behavior while handling the complex interactions for you.
+
+## Core Principles
+
+### 1. Primitive-Based Design
+
+Each primitive represents at most **one HTML element**, without internal elements.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<TimeSlider.Root>
+  <TimeSlider.Track>        {/* One element: the track */}
+    <TimeSlider.Progress /> {/* One element: the progress bar */}
+    <TimeSlider.Pointer />  {/* One element: hover indicator */}
+  </TimeSlider.Track>
+  <TimeSlider.Thumb />      {/* One element: the draggable thumb */}
+</TimeSlider.Root>
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```html
+<vjs-time-slider>
+  <div class="track">        <!-- One element: the track -->
+    <div class="progress"></div>  <!-- One element: the progress bar -->
+    <div class="pointer"></div>   <!-- One element: hover indicator -->
+  </div>
+  <div class="thumb"></div>       <!-- One element: the draggable thumb -->
+</vjs-time-slider>
+```
+</FrameworkCase>
+
+### 2. Compound Components
+
+Complex components are broken into smaller, composable pieces. This pattern is used for:
+
+- **Sliders** - Root, Track, Thumb, Progress, Pointer
+- **Tooltips** - Root, Trigger, Positioner, Popup, Arrow, Portal
+- **Popovers** - Root, Trigger, Positioner, Popup, Portal
+
+Each piece handles one concern, but they work together seamlessly.
+
+### 3. Built-in Accessibility
+
+Components include proper ARIA attributes, keyboard navigation, and focus management out of the box:
+
+- Buttons have correct roles and labels
+- Sliders support arrow key navigation
+- Focus is managed properly in tooltips and popovers
+- Screen readers get meaningful announcements
+
+### 4. Data Attributes for Styling
+
+Components expose state through data attributes, allowing pure CSS state styling:
+
+```css
+/* Style based on state without JavaScript */
+button[data-paused] {
+  /* Paused state */
+}
+
+button:not([data-paused]) {
+  /* Playing state */
+}
+```
+
+Common data attributes:
+- `data-paused` - Present when media is paused
+- `data-muted` - Present when audio is muted
+- `data-fullscreen` - Present when in fullscreen mode
+- `data-volume-level` - Values: `high`, `medium`, `low`, `off`
+
+## Available Components
+
+### Simple Components
+
+Single-element components that handle one piece of UI:
+
+- <DocsLink slug="reference/play-button">**PlayButton**</DocsLink> - Play/pause toggle
+- <DocsLink slug="reference/mute-button">**MuteButton**</DocsLink> - Audio mute toggle
+- <DocsLink slug="reference/fullscreen-button">**FullscreenButton**</DocsLink> - Fullscreen toggle
+- **CurrentTimeDisplay** - Current playback time
+- **DurationDisplay** - Total media duration
+- **PreviewTimeDisplay** - Time at hover position
+
+### Compound Components
+
+Multi-element components for complex interactions:
+
+- <DocsLink slug="reference/time-slider">**TimeSlider**</DocsLink> - Seekable timeline with progress
+- <DocsLink slug="reference/volume-slider">**VolumeSlider**</DocsLink> - Volume control slider
+- **Tooltip** - Hover tooltips with positioning
+- **Popover** - Click/hover popovers with collision detection
\ No newline at end of file
diff --git a/site/src/content/docs/concepts/v10-roadmap.mdx b/site/src/content/docs/concepts/v10-roadmap.mdx
new file mode 100644
index 00000000..e6f1b3bc
--- /dev/null
+++ b/site/src/content/docs/concepts/v10-roadmap.mdx
@@ -0,0 +1,81 @@
+---
+title: v10 Roadmap
+description: Timeline and milestones for Video.js v10 rebuild and the future of v8
+---
+
+Video.js v10 is a complete rebuild from the ground up, designed to be more modular, framework-flexible, and aligned with modern web development practices.
+
+## Current Versions
+
+### Version 8
+
+- Maintained with bug fixes and critical security patches only
+- No new features will be planned
+- Community contributions still welcome
+
+### Version 9
+
+- Reserved only for urgent API-breaking changes that cannot be avoided
+- Acts as a stopgap between v8 and the new v10 rebuild
+
+## October 30, 2025: Technical Preview
+
+
+**First public look** at Video.js v10, rebuilt from the ground up.
+
+**Goal:** Get feedback from early adopters and plugin authors.
+
+**What to expect:**
+- Limited feature set
+- Not production-ready
+- Existing plugins and integrations will not work with v10
+- Developers encouraged to check it out and give feedback
+
+## February 2026: v10 Beta Release
+
+Wider testing release to the community.
+
+**Core feature parity target:**
+- Basic control set (play, pause, seek, volume, fullscreen)
+- Adaptive streaming support via existing community engines
+- No plugin migrations yet, without plugin author contribution
+
+**What to expect:**
+- Close to stable, but API changes are still possible
+- Intended for experimental adoption in real-world projects
+- Developers encouraged to try it out and report issues
+
+## Mid-2026: v10 GA Release
+
+**Stable release** of Video.js v10
+
+**Feature targets:**
+- Core feature parity with v8 in terms of fundamentals
+- Feature parity with Media Chrome, Vidstack, Plyr, and Mux Player
+- Community encouraged to begin full reintegration projects
+- Plugin ecosystem migration begins in earnest
+
+**Engine development focus:**
+- Lightweight adaptive streaming
+- MoQ (Media over QUIC) support
+
+## Late-2026: Feature Parity with v8 Contrib
+
+**Extended feature parity** with Video.js "contrib" plugins:
+- Ads integration
+- Analytics support
+- Further community plugin migration dependent on contributions
+
+## End-of-Life Plan for Video.js v8
+
+### Mid-2026
+- v8/v9 moved to "video.js-legacy" repository and package
+- Hosted CDN copies will remain available
+
+### 2027 and Beyond
+- Security patches only
+- Community contributions de-prioritized
+
+---
+
+**Want to contribute?** Check out the [Video.js repository on GitHub](https://github.com/videojs) to get involved in the v10 rebuild.
diff --git a/site/src/content/docs/how-to/customize-skins.mdx b/site/src/content/docs/how-to/customize-skins.mdx
new file mode 100644
index 00000000..6cb3b6ce
--- /dev/null
+++ b/site/src/content/docs/how-to/customize-skins.mdx
@@ -0,0 +1,6 @@
+---
+title: Customize Skins
+description: Learn how to customize Video.js v10 skins by copying and modifying them
+---
+
+I'm going to put the eject examples here in another PR
\ No newline at end of file
diff --git a/site/src/content/docs/how-to/installation.mdx b/site/src/content/docs/how-to/installation.mdx
new file mode 100644
index 00000000..52829f92
--- /dev/null
+++ b/site/src/content/docs/how-to/installation.mdx
@@ -0,0 +1,116 @@
+---
+title: Installation
+description: Get started with Video.js v10 by choosing your framework, styles, skin, and media renderer
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import ServerCode from '@/components/Code/ServerCode.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+
+Welcome to Video.js v10! This guide will help you get up and running. In it, you'll make three key choices:
+
+1. **Framework** - React or HTML (vanilla JavaScript)
+2. **Skin** - The pre-built UI design you'll use, and how it's applied in your project
+3. **Renderer** - The component that displays your media
+
+## 1. Pick Your Framework
+
+Video.js v10 supports both React and vanilla JavaScript/HTML through Web Components. 
+
+First, select your preferred framework in the framework selector at the top of the <span class="hidden lg:inline">sidebar</span><span class="lg:hidden">page</span>.
+
+Then, install the appropriate package:
+
+<FrameworkCase frameworks={["react"]}>
+```bash
+npm install @videojs/react
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```bash
+npm install @videojs/html
+```
+</FrameworkCase>
+
+## 2. Pick Your Skin
+
+Skins are packaged sets of UI components and styles. Video.js v10 includes two built-in skins:
+
+- **Frosted** - Modern glassy design with backdrop blur effects
+- **Minimal** - Clean, simple design with straightforward controls
+
+Learn more about skins <DocsLink slug="concepts/skins">in the guide →</DocsLink>
+
+Currently, Video.js v10 uses CSS for styling these skins. More styling approaches (e.g, Tailwind CSS) are coming soon.
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import '@videojs/react/skins/frosted.css';
+// or
+import '@videojs/react/skins/minimal.css';
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```ts
+import '@videojs/html/skins/frosted';
+// or
+import '@videojs/html/skins/minimal';
+```
+</FrameworkCase>
+
+## 3. Pick Your Renderer
+
+<FrameworkCase frameworks={["react"]}>
+Media renderers display your video and audio content. For now, Video.js v10 includes `<Video />`, which supports HLS streams.
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+Media renderers display your video and audio content. For now, you should use the native HTML5 `<video>` element.
+</FrameworkCase>
+
+More renderers for formats like DASH, and services like YouTube and Vimeo are planned.
+
+## Basic Example
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+import { MediaProvider, FrostedSkin, Video } from '@videojs/react';
+import '@videojs/react/skins/frosted.css';
+
+export default function App() {
+  return (
+    <MediaProvider>
+      <FrostedSkin>
+        <Video
+          src="https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA.m3u8"
+          poster="https://image.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/thumbnail.webp"
+          playsInline
+        />
+      </FrostedSkin>
+    </MediaProvider>
+  );
+}
+```
+</FrameworkCase>
+<FrameworkCase frameworks={["html"]}>
+```ts
+import { defineVjsPlayer } from '@videojs/html';
+import '@videojs/html/skins/frosted';
+
+defineVjsPlayer();
+
+document.body.innerHTML = `
+  <media-provider>
+    <media-skin-frosted>
+      <video
+        slot="media"
+        src="https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA.m3u8"
+        poster="https://image.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/thumbnail.webp"
+        playsinline
+      ></video>
+    </media-skin-frosted>
+  </media-provider>
+`;
+```
+</FrameworkCase>
+
+That's it! You now have a fully functional Video.js player. Go forth and play.
\ No newline at end of file
diff --git a/site/src/content/docs/how-to/write-guides.mdx b/site/src/content/docs/how-to/write-guides.mdx
index 37be28e0..d71cb631 100644
--- a/site/src/content/docs/how-to/write-guides.mdx
+++ b/site/src/content/docs/how-to/write-guides.mdx
@@ -5,9 +5,10 @@ description: 'A guide on writing documentation for the Video.js project, and a t
 
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';
 import StyleCase from '@/components/docs/StyleCase.astro';
-import Container from '@/components/docs/Container.astro';
+import Minimal from '@/components/frames/Minimal.astro';
 import ServerCode from '@/components/Code/ServerCode.astro';
 import { TabsRoot, TabsPanel } from '@/components/Tabs.tsx';
+import DocsLink from '@/components/docs/DocsLink.astro';
 
 ## What kind of guide are you writing?
 I haven't written this section yet, but when I do, it'll rehash [Diátaxis](https://diataxis.fr/).
@@ -354,17 +355,16 @@ function Component() {
 
 There are two main patterns for displaying live demos, depending on whether you want to show code alongside the demo.
 
-### Option 1: Standalone Demo with Container
+### Option 1: Standalone Demo with Minimal Frame
 
-Use the `<Container>` component to constrain standalone demos to a readable width:
+Use the `<MinimalFrame>` frame component to wrap standalone demos with a styled border and background:
 
 ```mdx
 import { MyDemo } from '@/examples/react/MyDemo';
-import Container from '@/components/docs/Container.astro';
-
-<Container>
+import MinimalFrame from '@/components/frames/Minimal.astro';
+<MinimalFrame>
   <MyDemo client:load />
-</Container>
+</MinimalFrame>
 ```
 
 This is best for demos that don't need accompanying code, or when the code is shown separately elsewhere on the page.
@@ -397,4 +397,4 @@ import ServerCode from '@/components/Code/ServerCode.astro';
 </TabsRoot>
 ```
 
-The demo will appear at the bottom of the tabs component, creating a cohesive unit of code and preview. This pattern is used throughout our resource documentation (see [PlayButton](/docs/framework/react/style/css/resources/play-button) for an example).
\ No newline at end of file
+The demo will appear at the bottom of the tabs component, creating a cohesive unit of code and preview. This pattern is used throughout our resource documentation (see <DocsLink slug="reference/play-button">PlayButton</DocsLink> for an example).
\ No newline at end of file
diff --git a/site/src/content/docs/resources/fullscreen-button.mdx b/site/src/content/docs/reference/fullscreen-button.mdx
similarity index 97%
rename from site/src/content/docs/resources/fullscreen-button.mdx
rename to site/src/content/docs/reference/fullscreen-button.mdx
index 57870317..0bcdbf24 100644
--- a/site/src/content/docs/resources/fullscreen-button.mdx
+++ b/site/src/content/docs/reference/fullscreen-button.mdx
@@ -12,7 +12,6 @@ import htmlStr from '@/examples/html/fullscreen-button/snippet.html?raw';
 import htmlCssStr from '@/examples/html/fullscreen-button/fullscreen-button.css?raw';
 import htmlJsStr from '@/examples/html/fullscreen-button/fullscreen-button.js?raw';
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';
-import Container from '@/components/docs/Container.astro';
 import ServerCode from '@/components/Code/ServerCode.astro';
 import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
diff --git a/site/src/content/docs/resources/mute-button.mdx b/site/src/content/docs/reference/mute-button.mdx
similarity index 97%
rename from site/src/content/docs/resources/mute-button.mdx
rename to site/src/content/docs/reference/mute-button.mdx
index dc811251..9605a0a1 100644
--- a/site/src/content/docs/resources/mute-button.mdx
+++ b/site/src/content/docs/reference/mute-button.mdx
@@ -12,7 +12,6 @@ import htmlStr from '@/examples/html/mute-button/snippet.html?raw';
 import htmlCssStr from '@/examples/html/mute-button/mute-button.css?raw';
 import htmlJsStr from '@/examples/html/mute-button/mute-button.js?raw';
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';
-import Container from '@/components/docs/Container.astro';
 import ServerCode from '@/components/Code/ServerCode.astro';
 import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
diff --git a/site/src/content/docs/resources/play-button.mdx b/site/src/content/docs/reference/play-button.mdx
similarity index 97%
rename from site/src/content/docs/resources/play-button.mdx
rename to site/src/content/docs/reference/play-button.mdx
index 3811b9ac..321e3537 100644
--- a/site/src/content/docs/resources/play-button.mdx
+++ b/site/src/content/docs/reference/play-button.mdx
@@ -12,7 +12,6 @@ import htmlStr from '@/examples/html/play-button/snippet.html?raw';
 import htmlCssStr from '@/examples/html/play-button/play-button.css?raw';
 import htmlJsStr from '@/examples/html/play-button/play-button.js?raw';
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';
-import Container from '@/components/docs/Container.astro';
 import ServerCode from '@/components/Code/ServerCode.astro';
 import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
diff --git a/site/src/content/docs/resources/time-slider.mdx b/site/src/content/docs/reference/time-slider.mdx
similarity index 98%
rename from site/src/content/docs/resources/time-slider.mdx
rename to site/src/content/docs/reference/time-slider.mdx
index a4e4d66b..1b0f8af6 100644
--- a/site/src/content/docs/resources/time-slider.mdx
+++ b/site/src/content/docs/reference/time-slider.mdx
@@ -12,7 +12,6 @@ import htmlHorizontalStr from '@/examples/html/time-slider/snippet-horizontal.ht
 import htmlVerticalStr from '@/examples/html/time-slider/snippet-vertical.html?raw';
 import htmlCssStr from '@/examples/html/time-slider/time-slider.css?raw';
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';
-import Container from '@/components/docs/Container.astro';
 import ServerCode from '@/components/Code/ServerCode.astro';
 import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
diff --git a/site/src/content/docs/resources/volume-slider.mdx b/site/src/content/docs/reference/volume-slider.mdx
similarity index 98%
rename from site/src/content/docs/resources/volume-slider.mdx
rename to site/src/content/docs/reference/volume-slider.mdx
index 267deb88..6e69ed75 100644
--- a/site/src/content/docs/resources/volume-slider.mdx
+++ b/site/src/content/docs/reference/volume-slider.mdx
@@ -12,7 +12,6 @@ import htmlHorizontalStr from '@/examples/html/volume-slider/snippet-horizontal.
 import htmlVerticalStr from '@/examples/html/volume-slider/snippet-vertical.html?raw';
 import htmlCssStr from '@/examples/html/volume-slider/volume-slider.css?raw';
 import FrameworkCase from '@/components/docs/FrameworkCase.astro';
-import Container from '@/components/docs/Container.astro';
 import ServerCode from '@/components/Code/ServerCode.astro';
 import { TabsRoot, TabsPanel } from '@/components/Tabs';
 
diff --git a/site/src/examples/react/FrostedSkin/FrostedSkinDemo.tsx b/site/src/examples/react/FrostedSkin/FrostedSkinDemo.tsx
new file mode 100644
index 00000000..cfab9b5c
--- /dev/null
+++ b/site/src/examples/react/FrostedSkin/FrostedSkinDemo.tsx
@@ -0,0 +1,27 @@
+import { FrostedSkin, MediaProvider, Video } from '@videojs/react';
+import { VJS8_DEMO_VIDEO } from '@/consts';
+import '@videojs/react/skins/frosted.css';
+
+/**
+ * Live demo of the FrostedSkin design.
+ *
+ * Features demonstrated:
+ * - Glassmorphic controls with backdrop blur
+ * - Tooltips on hover for all buttons
+ * - Vertical volume slider in a popover
+ * - Time preview on timeline hover
+ * - Smooth animations and transitions
+ */
+export function FrostedSkinDemo() {
+  return (
+    <MediaProvider>
+      <FrostedSkin className="w-full aspect-video rounded-3xl">
+        <Video
+          src={VJS8_DEMO_VIDEO.hls}
+          poster={VJS8_DEMO_VIDEO.poster}
+          playsInline
+        />
+      </FrostedSkin>
+    </MediaProvider>
+  );
+}
diff --git a/site/src/examples/react/FullscreenButton/FullscreenButtonDemo.tsx b/site/src/examples/react/FullscreenButton/FullscreenButtonDemo.tsx
index ca4d190c..9706b618 100644
--- a/site/src/examples/react/FullscreenButton/FullscreenButtonDemo.tsx
+++ b/site/src/examples/react/FullscreenButton/FullscreenButtonDemo.tsx
@@ -1,4 +1,5 @@
 import { MediaContainer, MediaProvider, Video } from '@videojs/react';
+import { VJS8_DEMO_VIDEO } from '@/consts';
 import { BasicFullscreenButton } from './BasicFullscreenButton';
 
 /**
@@ -11,8 +12,8 @@ export function FullscreenButtonDemo() {
     <MediaProvider>
       <MediaContainer style={{ position: 'relative' }}>
         <Video
-          src="https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA.m3u8"
-          poster="https://image.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/thumbnail.webp"
+          src={VJS8_DEMO_VIDEO.hls}
+          poster={VJS8_DEMO_VIDEO.poster}
           muted
         />
         <div style={{ position: 'absolute', bottom: '1rem', right: '1rem', zIndex: 10 }}>
diff --git a/site/src/examples/react/MinimalSkin/MinimalSkinDemo.tsx b/site/src/examples/react/MinimalSkin/MinimalSkinDemo.tsx
new file mode 100644
index 00000000..033cd5ef
--- /dev/null
+++ b/site/src/examples/react/MinimalSkin/MinimalSkinDemo.tsx
@@ -0,0 +1,26 @@
+import { MediaProvider, MinimalSkin, Video } from '@videojs/react';
+import { VJS8_DEMO_VIDEO } from '@/consts';
+import '@videojs/react/skins/minimal.css';
+
+/**
+ * Live demo of the MinimalSkin design.
+ *
+ * Features demonstrated:
+ * - Clean, uncluttered interface
+ * - Inline time display
+ * - Simple, direct interactions
+ * - Lightweight and fast
+ */
+export function MinimalSkinDemo() {
+  return (
+    <MediaProvider>
+      <MinimalSkin className="w-full aspect-video">
+        <Video
+          src={VJS8_DEMO_VIDEO.hls}
+          poster={VJS8_DEMO_VIDEO.poster}
+          playsInline
+        />
+      </MinimalSkin>
+    </MediaProvider>
+  );
+}
diff --git a/site/src/examples/react/MuteButton/MuteButtonDemo.tsx b/site/src/examples/react/MuteButton/MuteButtonDemo.tsx
index 0df0456c..921562e9 100644
--- a/site/src/examples/react/MuteButton/MuteButtonDemo.tsx
+++ b/site/src/examples/react/MuteButton/MuteButtonDemo.tsx
@@ -1,4 +1,5 @@
 import { MediaContainer, MediaProvider, Video } from '@videojs/react';
+import { VJS8_DEMO_VIDEO } from '@/consts';
 import { BasicMuteButton } from './BasicMuteButton';
 
 /**
@@ -11,8 +12,8 @@ export function MuteButtonDemo() {
     <MediaProvider>
       <MediaContainer style={{ position: 'relative' }}>
         <Video
-          src="https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA.m3u8"
-          poster="https://image.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/thumbnail.webp"
+          src={VJS8_DEMO_VIDEO.hls}
+          poster={VJS8_DEMO_VIDEO.poster}
           muted
         />
         <div style={{ position: 'absolute', bottom: '1rem', left: '1rem', zIndex: 10 }}>
diff --git a/site/src/examples/react/PlayButton/PlayButtonDemo.tsx b/site/src/examples/react/PlayButton/PlayButtonDemo.tsx
index e5c27ce6..ef0d9e6e 100644
--- a/site/src/examples/react/PlayButton/PlayButtonDemo.tsx
+++ b/site/src/examples/react/PlayButton/PlayButtonDemo.tsx
@@ -1,4 +1,5 @@
 import { MediaContainer, MediaProvider, Video } from '@videojs/react';
+import { VJS8_DEMO_VIDEO } from '@/consts';
 import { BasicPlayButton } from './BasicPlayButton';
 
 /**
@@ -11,8 +12,8 @@ export function PlayButtonDemo() {
     <MediaProvider>
       <MediaContainer style={{ position: 'relative' }}>
         <Video
-          src="https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA.m3u8"
-          poster="https://image.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/thumbnail.webp"
+          src={VJS8_DEMO_VIDEO.hls}
+          poster={VJS8_DEMO_VIDEO.poster}
           muted
         />
         <div style={{ position: 'absolute', bottom: '1rem', left: '1rem', zIndex: 10 }}>
diff --git a/site/src/examples/react/TimeSlider/TimeSliderDemo.tsx b/site/src/examples/react/TimeSlider/TimeSliderDemo.tsx
index 6fa9e73f..30fed387 100644
--- a/site/src/examples/react/TimeSlider/TimeSliderDemo.tsx
+++ b/site/src/examples/react/TimeSlider/TimeSliderDemo.tsx
@@ -1,4 +1,5 @@
 import { MediaContainer, MediaProvider, Video } from '@videojs/react';
+import { VJS8_DEMO_VIDEO } from '@/consts';
 import { BasicTimeSlider } from './BasicTimeSlider';
 
 /**
@@ -11,8 +12,8 @@ export function TimeSliderDemo() {
     <MediaProvider>
       <MediaContainer style={{ position: 'relative' }}>
         <Video
-          src="https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA.m3u8"
-          poster="https://image.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/thumbnail.webp"
+          src={VJS8_DEMO_VIDEO.hls}
+          poster={VJS8_DEMO_VIDEO.poster}
           muted
         />
         <div style={{ position: 'absolute', bottom: '1rem', left: '1rem', right: '1rem', zIndex: 10 }}>
diff --git a/site/src/examples/react/VolumeSlider/VolumeSliderDemo.tsx b/site/src/examples/react/VolumeSlider/VolumeSliderDemo.tsx
index 8c39de36..17875bb0 100644
--- a/site/src/examples/react/VolumeSlider/VolumeSliderDemo.tsx
+++ b/site/src/examples/react/VolumeSlider/VolumeSliderDemo.tsx
@@ -1,4 +1,5 @@
 import { MediaContainer, MediaProvider, Video } from '@videojs/react';
+import { VJS8_DEMO_VIDEO } from '@/consts';
 import { BasicVolumeSlider } from './BasicVolumeSlider';
 
 /**
@@ -11,8 +12,8 @@ export function VolumeSliderDemo() {
     <MediaProvider>
       <MediaContainer style={{ position: 'relative' }}>
         <Video
-          src="https://stream.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA.m3u8"
-          poster="https://image.mux.com/UZMwOY6MgmhFNXLbSFXAuPKlRPss5XNA/thumbnail.webp"
+          src={VJS8_DEMO_VIDEO.hls}
+          poster={VJS8_DEMO_VIDEO.poster}
           muted
         />
         <div style={{ position: 'absolute', bottom: '1rem', right: '1rem', zIndex: 10 }}>
diff --git a/site/src/layouts/Base.astro b/site/src/layouts/Base.astro
index 6a9e02b9..7c022ffd 100644
--- a/site/src/layouts/Base.astro
+++ b/site/src/layouts/Base.astro
@@ -7,7 +7,6 @@ import { SITE_TITLE } from '@/consts';
 
 import '@/styles/globals.css';
 
-import FooterEasterEgg from '@/components/FooterEasterEgg.astro';
 import Posthog from '@/components/Posthog.astro';
 import ThemeInit from '@/components/ThemeInit.astro';
 
@@ -89,7 +88,6 @@ const fullTitle = Array.isArray(title)
     {/* BaseUI requires body.relative and div.isolate */}
     <div class="isolate">
       <slot />
-      <FooterEasterEgg />
     </div>
   </body>
 </html>
diff --git a/site/src/layouts/Blog.astro b/site/src/layouts/Blog.astro
index fe8246dc..e234f2ae 100644
--- a/site/src/layouts/Blog.astro
+++ b/site/src/layouts/Blog.astro
@@ -2,6 +2,7 @@
 import NavBar from '@/components/NavBar/NavBar.astro';
 import Footer from '@/components/Footer.astro';
 import Base from './Base.astro';
+import FooterEasterEgg from '@/components/FooterEasterEgg.astro';
 
 interface Props {
   title: string | string[];
@@ -20,4 +21,5 @@ const { title, description } = Astro.props;
     </main>
     <Footer class="mt-auto" />
   </div>
+  <FooterEasterEgg />
 </Base>
diff --git a/site/src/layouts/Docs.astro b/site/src/layouts/Docs.astro
index a031fda5..e6398806 100644
--- a/site/src/layouts/Docs.astro
+++ b/site/src/layouts/Docs.astro
@@ -10,6 +10,7 @@ import Footer from '@/components/Footer.astro';
 import Base from './Base.astro';
 import { Selectors } from '@/components/docs/Selectors';
 import { getDocTitle } from '@/utils/docs/title';
+import FooterEasterEgg from '@/components/FooterEasterEgg.astro';
 
 type Props<F extends SupportedFramework = SupportedFramework> = {
   doc: CollectionEntry<'docs'>;
@@ -42,9 +43,12 @@ const docTitles = new Map(allDocs.map((d) => [d.id, getDocTitle(d, framework)]))
         <Selectors client:load currentFramework={framework} currentStyle={style} currentSlug={slug} />
       </DocsSidebar>
     </aside>
-    <div class="flex flex-col">
-      <slot />
-      <Footer class="mt-auto" />
+    <div>
+      <div class="flex flex-col" style="min-height:calc(100vh - var(--nav-h));">
+        <slot />
+        <Footer class="mt-auto" />
+      </div>
+      <FooterEasterEgg class="lg:col-start-2" />
     </div>
   </div>
 </Base>
diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro
index 1e4cd272..b8af4a28 100644
--- a/site/src/pages/index.astro
+++ b/site/src/pages/index.astro
@@ -4,14 +4,14 @@ import HeroVideo from '@/components/home/HeroVideo';
 import construction from '@/assets/construction.svg?raw';
 import NavBar from '@/components/NavBar/NavBar.astro';
 import Footer from '@/components/Footer.astro';
-import { SITE_DESCRIPTION, SITE_TITLE } from '@/consts';
+import { SITE_DESCRIPTION, SITE_TITLE, VJS8_DEMO_VIDEO } from '@/consts';
 import Base from '@/layouts/Base.astro';
 import HomePageDemo from '@/components/HomePageDemo';
 import HomePageControls from '@/components/home/HomePageControls';
-import { PLAYBACK_ID } from '@/components/home/config';
 import { CircleCheck, Clock } from 'lucide-react';
+import FooterEasterEgg from '@/components/FooterEasterEgg.astro';
 
-const poster = `https://image.mux.com/${PLAYBACK_ID}/thumbnail.webp?time=0`;
+const poster = `${VJS8_DEMO_VIDEO.poster}?time=0`;
 ---
 
 <Base title={SITE_TITLE} description={SITE_DESCRIPTION}>
@@ -45,7 +45,7 @@ const poster = `https://image.mux.com/${PLAYBACK_ID}/thumbnail.webp?time=0`;
     </div>
   </header>
   <!-- padding corresponds to negative margin on player -->
-  <main class="@container pt-11 pb-36 md:pt-21 lg:pt-32 px-6 md:px-10 w-full max-w-7xl mx-auto min-h-64">
+  <main class="@container pt-11 pb-30 lg:pb-50 md:pt-21 lg:pt-32 px-6 md:px-10 w-full max-w-7xl mx-auto min-h-64">
     <HomePageControls client:idle className="col-span-full my-10 sm:my-12 lg:mb-15" />
     <HomePageDemo client:idle className="mb-6 lg:mb-30" />
     <section class="rounded-3xl">
@@ -103,4 +103,5 @@ const poster = `https://image.mux.com/${PLAYBACK_ID}/thumbnail.webp?time=0`;
     </section>
   </main>
   <Footer />
+  <FooterEasterEgg />
 </Base>
diff --git a/site/src/utils/docs/__tests__/title.test.ts b/site/src/utils/docs/__tests__/title.test.ts
index eddce745..82c00778 100644
--- a/site/src/utils/docs/__tests__/title.test.ts
+++ b/site/src/utils/docs/__tests__/title.test.ts
@@ -5,7 +5,7 @@ import { getDocTitle } from '../title';
 describe('getDocTitle', () => {
   // Mock fixtures
   const mockDocWithFrameworkTitle: CollectionEntry<'docs'> = {
-    id: 'resources/play-button',
+    id: 'reference/play-button',
     collection: 'docs',
     data: {
       title: 'PlayButton',
@@ -17,7 +17,7 @@ describe('getDocTitle', () => {
     },
     // Mock required Astro fields
     body: '',
-    slug: 'resources/play-button',
+    slug: 'reference/play-button',
   } as CollectionEntry<'docs'>;
 
   const mockDocWithoutFrameworkTitle: CollectionEntry<'docs'> = {
@@ -32,7 +32,7 @@ describe('getDocTitle', () => {
   } as CollectionEntry<'docs'>;
 
   const mockDocWithPartialFrameworkTitle: CollectionEntry<'docs'> = {
-    id: 'resources/mute-button',
+    id: 'reference/mute-button',
     collection: 'docs',
     data: {
       title: 'MuteButton',
@@ -43,7 +43,7 @@ describe('getDocTitle', () => {
       },
     },
     body: '',
-    slug: 'resources/mute-button',
+    slug: 'reference/mute-button',
   } as CollectionEntry<'docs'>;
 
   describe('with frameworkTitle defined', () => {