docs(site): add skin API references

.agents/skills/write-api-reference/references/demo-patterns.md

@@ -16,18 +16,20 @@ site/src/components/docs/demos/{component}/
     └── BasicUsage.css        # Styles
 ```
 
-## BEM Naming
+## CSS Scoping
 
-Block = `{framework}-{component}-{variant}`, element = `__{part}`:
+Give every demo a unique root class using `{framework}-{component}-{variant}`. Use flat semantic names for additional
+component or part hooks:
 
 ```
-html-play-button-basic              /* HTML framework, block */
-html-play-button-basic__button      /* HTML framework, element */
-react-play-button-basic             /* React framework, block */
-react-play-button-basic__button     /* React framework, element */
+html-play-button-basic          /* HTML framework, root */
+html-play-button-basic-button   /* HTML framework, button */
+react-play-button-basic         /* React framework, root */
+react-play-button-basic-button  /* React framework, button */
 ```
 
-The framework prefix (`html-` / `react-`) prevents CSS leaking between HTML and React demos on the same page (both render but one is hidden).
+The framework prefix (`html-` / `react-`) prevents CSS leaking between HTML and React demos on the same page (both
+render but one is hidden). React and HTML demos for the same variant should use matching semantic hooks.
 
 ## HTML Demo Files
 
@@ -58,7 +60,7 @@ The `.astro` wrapper is required because only Astro `<script>` tags go through V
         playsinline
         loop
     ></video>
-    <media-mute-button class="html-mute-button-basic__button">
+    <media-mute-button class="html-mute-button-basic-button">
         <span class="show-when-muted">Unmute</span>
         <span class="show-when-unmuted">Mute</span>
     </media-mute-button>
@@ -80,7 +82,7 @@ The `.astro` wrapper is required because only Astro `<script>` tags go through V
   width: 100%;
 }
 
-.html-mute-button-basic__button {
+.html-mute-button-basic-button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
@@ -95,10 +97,10 @@ The `.astro` wrapper is required because only Astro `<script>` tags go through V
 }
 
 /* State-based visibility via data attributes */
-.html-mute-button-basic__button .show-when-muted { display: none; }
-.html-mute-button-basic__button .show-when-unmuted { display: none; }
-.html-mute-button-basic__button[data-muted] .show-when-muted { display: inline; }
-.html-mute-button-basic__button:not([data-muted]) .show-when-unmuted { display: inline; }
+.html-mute-button-basic-button .show-when-muted { display: none; }
+.html-mute-button-basic-button .show-when-unmuted { display: none; }
+.html-mute-button-basic-button[data-muted] .show-when-muted { display: inline; }
+.html-mute-button-basic-button:not([data-muted]) .show-when-unmuted { display: inline; }
 ```
 
 ### .ts (registration imports)
@@ -139,7 +141,7 @@ export default function BasicUsage() {
           loop
         />
         <MuteButton
-          className="react-mute-button-basic__button"
+          className="react-mute-button-basic-button"
           render={(props, state) => (
             <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>
           )}
@@ -159,7 +161,7 @@ Key patterns:
 
 ### .css (styles)
 
-Same base styling as HTML but with `react-` BEM prefix:
+Use the same semantic hooks as HTML with the `react-` demo prefix:
 
 ```css
 .react-mute-button-basic {
@@ -170,7 +172,7 @@ Same base styling as HTML but with `react-` BEM prefix:
   width: 100%;
 }
 
-.react-mute-button-basic__button {
+.react-mute-button-basic-button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
@@ -195,26 +197,26 @@ Components expose state via `data-*` attributes. CSS toggles visibility:
 
 ```css
 /* Hide all by default */
-.html-play-button-basic__button .show-when-paused { display: none; }
-.html-play-button-basic__button .show-when-playing { display: none; }
+.html-play-button-basic-button .show-when-paused { display: none; }
+.html-play-button-basic-button .show-when-playing { display: none; }
 
 /* Show based on state */
-.html-play-button-basic__button[data-paused] .show-when-paused { display: inline; }
-.html-play-button-basic__button:not([data-paused]) .show-when-playing { display: inline; }
+.html-play-button-basic-button[data-paused] .show-when-paused { display: inline; }
+.html-play-button-basic-button:not([data-paused]) .show-when-playing { display: inline; }
 ```
 
 For multi-value attributes (e.g., `data-volume-level`):
 
 ```css
-.html-mute-button-volume-levels__button .level-off,
-.html-mute-button-volume-levels__button .level-low,
-.html-mute-button-volume-levels__button .level-medium,
-.html-mute-button-volume-levels__button .level-high {
+.html-mute-button-volume-levels-button .level-off,
+.html-mute-button-volume-levels-button .level-low,
+.html-mute-button-volume-levels-button .level-medium,
+.html-mute-button-volume-levels-button .level-high {
   display: none;
 }
 
-.html-mute-button-volume-levels__button[data-volume-level="off"] .level-off { display: inline; }
-.html-mute-button-volume-levels__button[data-volume-level="low"] .level-low { display: inline; }
+.html-mute-button-volume-levels-button[data-volume-level="off"] .level-off { display: inline; }
+.html-mute-button-volume-levels-button[data-volume-level="low"] .level-low { display: inline; }
 ```
 
 ### React: Render prop
@@ -240,9 +242,9 @@ For multi-value attributes (e.g., `data-volume-level`):
 HTML uses `:not()` combinators to handle mutually exclusive states:
 
 ```css
-.html-play-button-basic__button[data-paused]:not([data-ended]) .show-when-paused { display: inline; }
-.html-play-button-basic__button:not([data-paused]) .show-when-playing { display: inline; }
-.html-play-button-basic__button[data-ended] .show-when-ended { display: inline; }
+.html-play-button-basic-button[data-paused]:not([data-ended]) .show-when-paused { display: inline; }
+.html-play-button-basic-button:not([data-paused]) .show-when-playing { display: inline; }
+.html-play-button-basic-button[data-ended] .show-when-ended { display: inline; }
 ```
 
 React uses nested ternary in the render prop:
@@ -263,7 +265,7 @@ render={(props, state) => (
 All button demos share this base overlay style:
 
 ```css
-.__button {
+.demo-button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;

site/src/components/docs/api-reference/ComponentImports.astro

@@ -2,7 +2,10 @@
 import type { BundledLanguage } from 'shiki';
 
 import ServerCode from '@/components/Code/ServerCode.astro';
+import RegistryInstall from '@/components/docs/RegistryInstall.astro';
 import CodeFrame from '@/components/typography/CodeFrame.astro';
+import { isValidFramework } from '@/types/docs';
+import { registryItemForComponent } from '@/utils/installation/shadcn-registry';
 import FrameworkCase from '../FrameworkCase.astro';
 
 interface Props {
@@ -11,6 +14,10 @@ interface Props {
 }
 
 const { component, html } = Astro.props;
+const framework = Astro.params.framework;
+if (!isValidFramework(framework)) throw new Error(`Unsupported framework: ${framework ?? 'missing'}.`);
+
+const registryItem = framework === 'react' ? await registryItemForComponent(component) : null;
 
 const imports: Array<{ code: string; framework: 'react' | 'html'; lang: BundledLanguage }> = [
   {
@@ -35,3 +42,15 @@ const imports: Array<{ code: string; framework: 'react' | 'html'; lang: BundledL
     </FrameworkCase>
   ))
 }
+
+{
+  registryItem ? (
+    <>
+      <h3 id="editable-source">Editable styled source</h3>
+      <p>
+        Install the styled component and its exact dependencies with Shadcn, or copy the same generated files manually.
+      </p>
+      <RegistryInstall framework="react" item={registryItem} />
+    </>
+  ) : null
+}

site/src/components/docs/api-reference/PresetReference.astro

@@ -12,6 +12,7 @@ import { isValidFramework } from '@/types/docs';
 import type { PresetReference as PresetReferenceType } from '@/types/preset-reference';
 import DocsLink from '../DocsLink.astro';
 import FrameworkCase from '../FrameworkCase.astro';
+import { skinGuides } from '../skins/skinGuides';
 import InlineMarkdown from './InlineMarkdown.astro';
 
 const entries = await getCollection('presetReference');
@@ -34,6 +35,17 @@ const { framework } = Astro.params;
 const pkg = framework && isValidFramework(framework) ? `@videojs/${framework}` : '@videojs/html';
 
 const listFormat = new Intl.ListFormat('en', { style: 'long', type: 'unit' });
+
+function getSkinReferenceSlug(name: string): string | undefined {
+  const entry = Object.entries(skinGuides).find(([, skin]) =>
+    skin.reactSkin === name || skin.htmlSkin === name
+  );
+  if (!entry) return;
+
+  return entry[0] === 'background'
+    ? 'reference/background-video-skin'
+    : `reference/${entry[0]}-skin`;
+}
 ---
 
 <ContentWidth>
@@ -125,16 +137,27 @@ const listFormat = new Intl.ListFormat('en', { style: 'long', type: 'unit' });
                       <dd>
                         <FrameworkCase frameworks={["react"]}>
                           {preset.react.skins.length > 0
-                            ? preset.react.skins.map((skin) => (
-                                <div class="mb-2 last:mb-0">
+                            ? preset.react.skins.map((skin) => {
+                                const slug = getSkinReferenceSlug(skin.name);
+                                const component = (
                                   <MarkdownCode class="inline-block whitespace-nowrap">{`<${skin.name}>`}</MarkdownCode>
-                                  {skin.cssImport && (
-                                    <div class="mt-0.5">
-                                      <MarkdownCode class="inline-block text-code whitespace-nowrap">{`import '${skin.cssImport}';`}</MarkdownCode>
-                                    </div>
-                                  )}
-                                </div>
-                              ))
+                                );
+
+                                return (
+                                  <div class="mb-2 last:mb-0">
+                                    {slug ? (
+                                      <DocsLink slug={slug}>{component}</DocsLink>
+                                    ) : (
+                                      component
+                                    )}
+                                    {skin.cssImport && (
+                                      <div class="mt-0.5">
+                                        <MarkdownCode class="inline-block text-code whitespace-nowrap">{`import '${skin.cssImport}';`}</MarkdownCode>
+                                      </div>
+                                    )}
+                                  </div>
+                                );
+                              })
                             : "–"}
                         </FrameworkCase>
                         <FrameworkCase frameworks={["html"]}>
@@ -145,13 +168,22 @@ const listFormat = new Intl.ListFormat('en', { style: 'long', type: 'unit' });
                                     (s) => s.tagName ?? s.name,
                                   ),
                                 )
-                                .map((part) =>
-                                  part.type === "element" ? (
+                                .map((part) => {
+                                  if (part.type !== "element") {
+                                    return <span>{part.value}</span>;
+                                  }
+
+                                  const slug = getSkinReferenceSlug(part.value);
+                                  const element = (
                                     <MarkdownCode class="inline-block whitespace-nowrap">{`<${part.value}>`}</MarkdownCode>
+                                  );
+
+                                  return slug ? (
+                                    <DocsLink slug={slug}>{element}</DocsLink>
                                   ) : (
-                                    <span>{part.value}</span>
-                                  ),
-                                )
+                                    element
+                                  );
+                                })
                             : "–"}
                         </FrameworkCase>
                       </dd>

site/src/components/docs/demos/add-background-video/html/css/BasicUsage.css

@@ -9,38 +9,38 @@
   isolation: isolate;
 }
 
-.add-background-video-html-demo__visual,
-.add-background-video-html-demo__poster,
-.add-background-video-html-demo__media {
+.add-background-video-html-demo-visual,
+.add-background-video-html-demo-poster,
+.add-background-video-html-demo-media {
   position: absolute;
   inset: 0;
   width: 100%;
   height: 100%;
 }
 
-.add-background-video-html-demo__visual {
+.add-background-video-html-demo-visual {
   pointer-events: none;
 }
 
-.add-background-video-html-demo__visual::after {
+.add-background-video-html-demo-visual::after {
   position: absolute;
   inset: 0;
   content: "";
   background: linear-gradient(90deg, rgb(0 0 0 / 85%), rgb(0 0 0 / 55%));
 }
 
-.add-background-video-html-demo__poster,
-.add-background-video-html-demo__media {
+.add-background-video-html-demo-poster,
+.add-background-video-html-demo-media {
   display: block;
   object-fit: cover;
 }
 
-.add-background-video-html-demo__media {
+.add-background-video-html-demo-media {
   --media-object-fit: cover;
   --media-object-position: center;
 }
 
-.add-background-video-html-demo__content {
+.add-background-video-html-demo-content {
   position: relative;
   z-index: 1;
   display: grid;
@@ -50,13 +50,13 @@
   padding: 2rem;
 }
 
-.add-background-video-html-demo__content h3 {
+.add-background-video-html-demo-content h3 {
   margin: 0;
   font-size: 1.75rem;
   line-height: 1.1;
 }
 
-.add-background-video-html-demo__content a {
+.add-background-video-html-demo-content a {
   width: fit-content;
   padding: 0.625rem 1rem;
   color: black;
@@ -65,13 +65,13 @@
   border-radius: 0.25rem;
 }
 
-.add-background-video-html-demo__content a:focus-visible {
+.add-background-video-html-demo-content a:focus-visible {
   outline: 0.2rem solid white;
   outline-offset: 0.2rem;
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .add-background-video-html-demo__media {
+  .add-background-video-html-demo-media {
     display: none;
   }
 }

site/src/components/docs/demos/add-background-video/html/css/BasicUsage.html

@@ -1,12 +1,12 @@
 <section class="add-background-video-html-demo">
-  <div class="add-background-video-html-demo__visual" aria-hidden="true">
-    <img class="add-background-video-html-demo__poster" src="{{VJS10_DEMO_BACKGROUND_VIDEO_POSTER}}" alt="" />
+  <div class="add-background-video-html-demo-visual" aria-hidden="true">
+    <img class="add-background-video-html-demo-poster" src="{{VJS10_DEMO_BACKGROUND_VIDEO_POSTER}}" alt="" />
     <background-video
-      class="add-background-video-html-demo__media"
+      class="add-background-video-html-demo-media"
       src="{{VJS10_DEMO_BACKGROUND_VIDEO_MP4}}"
     ></background-video>
   </div>
-  <div class="add-background-video-html-demo__content">
+  <div class="add-background-video-html-demo-content">
     <h3>Build the next great video experience</h3>
     <a href="#common-variations">Compare source options</a>
   </div>