diff --git a/site/scripts/api-docs-builder/src/index.ts b/site/scripts/api-docs-builder/src/index.ts
index 1d1eef80..38379321 100644
--- a/site/scripts/api-docs-builder/src/index.ts
+++ b/site/scripts/api-docs-builder/src/index.ts
@@ -309,6 +309,7 @@ function instantiatesCore(filePath: string): boolean {
   }
 }
 
+/** String search heuristic — a comment containing `stateAttrMap` would also match. */
 function usesDataAttrs(filePath: string): boolean {
   try {
     return fs.readFileSync(filePath, 'utf-8').includes('stateAttrMap');
diff --git a/site/scripts/api-docs-builder/src/parts-handler.ts b/site/scripts/api-docs-builder/src/parts-handler.ts
index 64bcf03c..a89ef6f5 100644
--- a/site/scripts/api-docs-builder/src/parts-handler.ts
+++ b/site/scripts/api-docs-builder/src/parts-handler.ts
@@ -94,6 +94,7 @@ export function extractSubPartProps(filePath: string, program: ts.Program, local
         if (name === 'children' || !member.type) continue;
 
         let typeStr = checker.typeToString(checker.getTypeFromTypeNode(member.type));
+        // Only strips trailing ` | undefined`; other orderings (e.g., `undefined | string`) pass through.
         if (member.questionToken) typeStr = typeStr.replace(/ \| undefined$/, '');
 
         const propDef: PropDef = { type: typeStr };
diff --git a/site/src/components/docs/api-reference/CSSVarRow.astro b/site/src/components/docs/api-reference/CSSVarRow.astro
index 8539edc1..6589b5f0 100644
--- a/site/src/components/docs/api-reference/CSSVarRow.astro
+++ b/site/src/components/docs/api-reference/CSSVarRow.astro
@@ -11,7 +11,7 @@ interface Props {
 
 const { name, description, componentName } = Astro.props;
 
-const id = `${componentName}-css-var-${name}`;
+const id = `${componentName}-css-var-${name.replace(/^--/, '')}`;
 ---
 
 <DetailRow id={id} name={name} type="" description={description} colspan={2}>
diff --git a/site/src/components/docs/demos/time-slider/html/css/BasicUsage.astro b/site/src/components/docs/demos/time-slider/html/css/BasicUsage.astro
deleted file mode 100644
index e7e95f49..00000000
--- a/site/src/components/docs/demos/time-slider/html/css/BasicUsage.astro
+++ /dev/null
@@ -1,10 +0,0 @@
----
-import HtmlDemo from '@/components/docs/demos/HtmlDemo.astro';
-import html from './BasicUsage.html?raw';
-import './BasicUsage.css';
----
-
-<HtmlDemo html={html} />
-<script>
-  import './BasicUsage.ts';
-</script>
diff --git a/site/src/components/docs/demos/time-slider/html/css/BasicUsage.css b/site/src/components/docs/demos/time-slider/html/css/BasicUsage.css
deleted file mode 100644
index d7dd8684..00000000
--- a/site/src/components/docs/demos/time-slider/html/css/BasicUsage.css
+++ /dev/null
@@ -1,30 +0,0 @@
-.html-time-slider-basic,
-.html-time-slider-basic media-container {
-  display: block;
-  position: relative;
-}
-
-.html-time-slider-basic video {
-  width: 100%;
-}
-
-.html-time-slider-basic__slider {
-  position: absolute;
-  bottom: 0;
-  left: 0;
-  right: 0;
-  height: 20px;
-  cursor: pointer;
-  background: rgba(255, 255, 255, 0.3);
-}
-
-.html-time-slider-basic__slider::before {
-  content: "";
-  position: absolute;
-  top: 0;
-  left: 0;
-  height: 100%;
-  width: var(--media-slider-fill);
-  background: white;
-  pointer-events: none;
-}
diff --git a/site/src/components/docs/demos/time-slider/html/css/BasicUsage.html b/site/src/components/docs/demos/time-slider/html/css/BasicUsage.html
deleted file mode 100644
index 2e633011..00000000
--- a/site/src/components/docs/demos/time-slider/html/css/BasicUsage.html
+++ /dev/null
@@ -1,12 +0,0 @@
-<video-player class="html-time-slider-basic">
-    <media-container>
-        <video
-            src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
-            autoplay
-            muted
-            playsinline
-            loop
-        ></video>
-        <media-time-slider class="html-time-slider-basic__slider"></media-time-slider>
-    </media-container>
-</video-player>
diff --git a/site/src/components/docs/demos/time-slider/html/css/BasicUsage.ts b/site/src/components/docs/demos/time-slider/html/css/BasicUsage.ts
deleted file mode 100644
index d40811aa..00000000
--- a/site/src/components/docs/demos/time-slider/html/css/BasicUsage.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-import '@videojs/html/video/player';
-import '@videojs/html/ui/time-slider';
diff --git a/site/src/components/docs/demos/time-slider/react/css/BasicUsage.css b/site/src/components/docs/demos/time-slider/react/css/BasicUsage.css
deleted file mode 100644
index 9f11b9bb..00000000
--- a/site/src/components/docs/demos/time-slider/react/css/BasicUsage.css
+++ /dev/null
@@ -1,28 +0,0 @@
-.react-time-slider-basic {
-  position: relative;
-}
-
-.react-time-slider-basic video {
-  width: 100%;
-}
-
-.react-time-slider-basic__slider {
-  position: absolute;
-  bottom: 0;
-  left: 0;
-  right: 0;
-  height: 20px;
-  cursor: pointer;
-  background: rgba(255, 255, 255, 0.3);
-}
-
-.react-time-slider-basic__slider::before {
-  content: "";
-  position: absolute;
-  top: 0;
-  left: 0;
-  height: 100%;
-  width: var(--media-slider-fill);
-  background: white;
-  pointer-events: none;
-}
diff --git a/site/src/components/docs/demos/time-slider/react/css/BasicUsage.tsx b/site/src/components/docs/demos/time-slider/react/css/BasicUsage.tsx
deleted file mode 100644
index dea15914..00000000
--- a/site/src/components/docs/demos/time-slider/react/css/BasicUsage.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-import { createPlayer, TimeSlider } from '@videojs/react';
-import { Video, videoFeatures } from '@videojs/react/video';
-
-import './BasicUsage.css';
-
-const Player = createPlayer({ features: videoFeatures });
-
-export default function BasicUsage() {
-  return (
-    <Player.Provider>
-      <Player.Container className="react-time-slider-basic">
-        <Video
-          src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
-        <TimeSlider.Root className="react-time-slider-basic__slider" />
-      </Player.Container>
-    </Player.Provider>
-  );
-}
diff --git a/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.astro b/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.astro
deleted file mode 100644
index e7e95f49..00000000
--- a/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.astro
+++ /dev/null
@@ -1,10 +0,0 @@
----
-import HtmlDemo from '@/components/docs/demos/HtmlDemo.astro';
-import html from './BasicUsage.html?raw';
-import './BasicUsage.css';
----
-
-<HtmlDemo html={html} />
-<script>
-  import './BasicUsage.ts';
-</script>
diff --git a/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.css b/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.css
deleted file mode 100644
index 29febaca..00000000
--- a/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.css
+++ /dev/null
@@ -1,60 +0,0 @@
-.html-volume-slider-basic,
-.html-volume-slider-basic media-container {
-  display: block;
-  position: relative;
-}
-
-.html-volume-slider-basic video {
-  width: 100%;
-}
-
-.html-volume-slider-basic__mute-button {
-  position: absolute;
-  bottom: 10px;
-  left: 10px;
-  background: rgba(255, 255, 255, 0.7);
-  backdrop-filter: blur(10px);
-  color: black;
-  border: 1px solid rgba(255, 255, 255, 0.3);
-  border-radius: 9999px;
-  padding-block: 8px;
-  padding-inline: 20px;
-  cursor: pointer;
-}
-
-.html-volume-slider-basic__mute-button .show-when-muted {
-  display: none;
-}
-.html-volume-slider-basic__mute-button .show-when-unmuted {
-  display: none;
-}
-.html-volume-slider-basic__mute-button[data-muted] .show-when-muted {
-  display: inline;
-}
-.html-volume-slider-basic__mute-button:not([data-muted]) .show-when-unmuted {
-  display: inline;
-}
-
-.html-volume-slider-basic__slider {
-  position: absolute;
-  bottom: 10px;
-  right: 10px;
-  width: 100px;
-  height: 20px;
-  cursor: pointer;
-  background: rgba(255, 255, 255, 0.3);
-  backdrop-filter: blur(10px);
-  border-radius: 9999px;
-}
-
-.html-volume-slider-basic__slider::before {
-  content: "";
-  position: absolute;
-  top: 0;
-  left: 0;
-  height: 100%;
-  width: var(--media-slider-fill);
-  background: white;
-  border-radius: 9999px;
-  pointer-events: none;
-}
diff --git a/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.html b/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.html
deleted file mode 100644
index 6bd411ca..00000000
--- a/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.html
+++ /dev/null
@@ -1,16 +0,0 @@
-<video-player class="html-volume-slider-basic">
-    <media-container>
-        <video
-            src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
-            autoplay
-            muted
-            playsinline
-            loop
-        ></video>
-        <media-mute-button class="html-volume-slider-basic__mute-button">
-            <span class="show-when-muted">Unmute</span>
-            <span class="show-when-unmuted">Mute</span>
-        </media-mute-button>
-        <media-volume-slider class="html-volume-slider-basic__slider"></media-volume-slider>
-    </media-container>
-</video-player>
diff --git a/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.ts b/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.ts
deleted file mode 100644
index bc487687..00000000
--- a/site/src/components/docs/demos/volume-slider/html/css/BasicUsage.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import '@videojs/html/video/player';
-import '@videojs/html/ui/mute-button';
-import '@videojs/html/ui/volume-slider';
diff --git a/site/src/components/docs/demos/volume-slider/react/css/BasicUsage.css b/site/src/components/docs/demos/volume-slider/react/css/BasicUsage.css
deleted file mode 100644
index 4d7ead44..00000000
--- a/site/src/components/docs/demos/volume-slider/react/css/BasicUsage.css
+++ /dev/null
@@ -1,45 +0,0 @@
-.react-volume-slider-basic {
-  position: relative;
-}
-
-.react-volume-slider-basic video {
-  width: 100%;
-}
-
-.react-volume-slider-basic__mute-button {
-  position: absolute;
-  bottom: 10px;
-  left: 10px;
-  background: rgba(255, 255, 255, 0.7);
-  backdrop-filter: blur(10px);
-  color: black;
-  border: 1px solid rgba(255, 255, 255, 0.3);
-  border-radius: 9999px;
-  padding-block: 8px;
-  padding-inline: 20px;
-  cursor: pointer;
-}
-
-.react-volume-slider-basic__slider {
-  position: absolute;
-  bottom: 10px;
-  right: 10px;
-  width: 100px;
-  height: 20px;
-  cursor: pointer;
-  background: rgba(255, 255, 255, 0.3);
-  backdrop-filter: blur(10px);
-  border-radius: 9999px;
-}
-
-.react-volume-slider-basic__slider::before {
-  content: "";
-  position: absolute;
-  top: 0;
-  left: 0;
-  height: 100%;
-  width: var(--media-slider-fill);
-  background: white;
-  border-radius: 9999px;
-  pointer-events: none;
-}
diff --git a/site/src/components/docs/demos/volume-slider/react/css/BasicUsage.tsx b/site/src/components/docs/demos/volume-slider/react/css/BasicUsage.tsx
deleted file mode 100644
index 9e180dca..00000000
--- a/site/src/components/docs/demos/volume-slider/react/css/BasicUsage.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-import { createPlayer, MuteButton, VolumeSlider } from '@videojs/react';
-import { Video, videoFeatures } from '@videojs/react/video';
-
-import './BasicUsage.css';
-
-const Player = createPlayer({ features: videoFeatures });
-
-export default function BasicUsage() {
-  return (
-    <Player.Provider>
-      <Player.Container className="react-volume-slider-basic">
-        <Video
-          src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
-        <MuteButton
-          className="react-volume-slider-basic__mute-button"
-          render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>}
-        />
-        <VolumeSlider.Root className="react-volume-slider-basic__slider" />
-      </Player.Container>
-    </Player.Provider>
-  );
-}
diff --git a/site/src/content/docs/reference/popover.mdx b/site/src/content/docs/reference/popover.mdx
index 24dc510d..9b8d626a 100644
--- a/site/src/content/docs/reference/popover.mdx
+++ b/site/src/content/docs/reference/popover.mdx
@@ -66,7 +66,7 @@ The `side` and `align` props control popup placement relative to the trigger. Th
 
 ## Styling
 
-Use [CSS custom properties](#css-custom-properties) for positioning offsets:
+Use [CSS custom properties](#root-css-custom-properties) for positioning offsets:
 
 ```css
 media-popover {
diff --git a/site/src/content/docs/reference/time-slider.mdx b/site/src/content/docs/reference/time-slider.mdx
index 93fa76fd..a6230253 100644
--- a/site/src/content/docs/reference/time-slider.mdx
+++ b/site/src/content/docs/reference/time-slider.mdx
@@ -43,7 +43,7 @@ Seeking is throttled via the `commitThrottle` prop (default 100ms) to avoid over
 
 ## Styling
 
-Use [CSS custom properties](#css-custom-properties) to style the fill, pointer, and buffer levels:
+Use [CSS custom properties](#root-css-custom-properties) to style the fill, pointer, and buffer levels:
 
 ```css
 media-time-slider::before {
diff --git a/site/src/content/docs/reference/volume-slider.mdx b/site/src/content/docs/reference/volume-slider.mdx
index 06d07519..6afe2658 100644
--- a/site/src/content/docs/reference/volume-slider.mdx
+++ b/site/src/content/docs/reference/volume-slider.mdx
@@ -41,7 +41,7 @@ Controls the media volume level. The slider maps its 0–100 internal range to t
 
 ## Styling
 
-Use [CSS custom properties](#css-custom-properties) to style the fill and pointer levels:
+Use [CSS custom properties](#root-css-custom-properties) to style the fill and pointer levels:
 
 ```css
 media-volume-slider::before {