From b1c802279463e749766aabdafbcf5282c008ee09 Mon Sep 17 00:00:00 2001
From: Darius Cepulis <dcepulis@mux.com>
Date: Fri, 13 Feb 2026 14:04:55 -0600
Subject: [PATCH] chore(site): audit and encode docs patterns (#535)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 .claude/skills/README.md                      |  10 +-
 .claude/skills/api-reference/SKILL.md         | 101 ++++
 .../references/builder-conventions.md         |  85 ++++
 .../api-reference/references/demo-patterns.md | 274 +++++++++++
 .../api-reference/references/mdx-structure.md | 225 +++++++++
 .claude/skills/api/SKILL.md                   |   2 +-
 .claude/skills/aria/SKILL.md                  |   2 +-
 .claude/skills/claude-update/SKILL.md         |   2 +-
 .claude/skills/component/SKILL.md             |   3 +-
 .claude/skills/create-skill/SKILL.md          |   2 +-
 .claude/skills/design/SKILL.md                |   2 +-
 .claude/skills/docs/SKILL.md                  | 435 +++++++----------
 .claude/skills/docs/examples/good-bad.md      | 310 ------------
 .claude/skills/docs/examples/tone-samples.md  | 282 -----------
 .claude/skills/docs/patterns/ai-readiness.md  | 332 -------------
 .claude/skills/docs/patterns/code-examples.md | 382 +++++++--------
 .../docs/patterns/progressive-disclosure.md   | 303 ------------
 .claude/skills/docs/patterns/props-tables.md  | 255 ----------
 .../docs/references/component-libraries.md    |  15 +-
 .../skills/docs/references/multi-framework.md |  28 --
 .../skills/docs/references/state-tooling.md   |   3 +-
 .../skills/docs/references/writing-style.md   | 149 ++++++
 .claude/skills/docs/review/agents.md          | 236 +++------
 .claude/skills/docs/review/checklist.md       |  59 +++
 .claude/skills/docs/review/issue-format.md    |  96 ----
 .claude/skills/docs/review/merge-template.md  | 120 -----
 .claude/skills/docs/review/templates.md       | 168 +++++++
 .claude/skills/docs/review/workflow.md        |  93 ++--
 .../skills/docs/templates/api-reference.md    | 460 ------------------
 .../skills/docs/templates/component-page.md   | 421 ----------------
 .claude/skills/docs/templates/concept.md      |  90 ++++
 .claude/skills/docs/templates/guide.md        | 330 -------------
 .claude/skills/docs/templates/handbook.md     | 251 ----------
 .claude/skills/docs/templates/how-to.md       |  98 ++++
 .../skills/docs/templates/migration-guide.md  | 313 ------------
 .claude/skills/docs/templates/readme.md       | 278 +++--------
 .claude/skills/gh-issue/SKILL.md              |   3 +-
 .claude/skills/review-branch/SKILL.md         |   7 +-
 .claude/skills/rfc/SKILL.md                   |   2 +-
 CLAUDE.md                                     |  17 +-
 CONTRIBUTING.md                               |   2 +-
 .../html/css/BasicUsage.css                   |  10 +-
 .../html/css/BasicUsage.html                  |   6 +-
 .../react/css/BasicUsage.css                  |  10 +-
 .../react/css/BasicUsage.tsx                  |   6 +-
 .../demos/controls/html/css/BasicUsage.css    |  24 +-
 .../demos/controls/html/css/BasicUsage.html   |  10 +-
 .../demos/controls/react/css/BasicUsage.css   |  16 +-
 .../demos/controls/react/css/BasicUsage.tsx   |  10 +-
 .../fullscreen-button/html/css/BasicUsage.css |  14 +-
 .../html/css/BasicUsage.html                  |   4 +-
 .../react/css/BasicUsage.css                  |   6 +-
 .../react/css/BasicUsage.tsx                  |   4 +-
 .../demos/mute-button/html/css/BasicUsage.css |  14 +-
 .../mute-button/html/css/BasicUsage.html      |   4 +-
 .../mute-button/html/css/VolumeLevels.astro   |  10 +
 .../mute-button/html/css/VolumeLevels.css     |  41 ++
 .../mute-button/html/css/VolumeLevels.html    |  15 +
 .../mute-button/html/css/VolumeLevels.ts      |   2 +
 .../mute-button/react/css/BasicUsage.css      |   6 +-
 .../mute-button/react/css/BasicUsage.tsx      |   4 +-
 .../mute-button/react/css/VolumeLevels.css    |  21 +
 .../mute-button/react/css/VolumeLevels.tsx    |  35 ++
 .../demos/pip-button/html/css/BasicUsage.css  |  14 +-
 .../demos/pip-button/html/css/BasicUsage.html |   4 +-
 .../demos/pip-button/react/css/BasicUsage.css |   6 +-
 .../demos/pip-button/react/css/BasicUsage.tsx |   4 +-
 .../demos/play-button/html/css/BasicUsage.css |  26 +-
 .../play-button/html/css/BasicUsage.html      |   6 +-
 .../play-button/react/css/BasicUsage.css      |   6 +-
 .../play-button/react/css/BasicUsage.tsx      |   9 +-
 .../docs/demos/poster/html/css/BasicUsage.css |  20 +-
 .../demos/poster/html/css/BasicUsage.html     |   6 +-
 .../demos/poster/react/css/BasicUsage.css     |  10 +-
 .../demos/poster/react/css/BasicUsage.tsx     |   6 +-
 .../demos/seek-button/html/css/BasicUsage.css |  16 +-
 .../seek-button/html/css/BasicUsage.html      |   8 +-
 .../seek-button/react/css/BasicUsage.css      |   8 +-
 .../seek-button/react/css/BasicUsage.tsx      |   8 +-
 .../demos/time/html/css/CurrentDuration.css   |   6 +-
 .../demos/time/html/css/CurrentDuration.html  |   4 +-
 .../docs/demos/time/html/css/CurrentTime.css  |   6 +-
 .../docs/demos/time/html/css/CurrentTime.html |   4 +-
 .../time/html/css/CustomNegativeSign.css      |   6 +-
 .../time/html/css/CustomNegativeSign.html     |   4 +-
 .../demos/time/html/css/CustomSeparator.css   |   6 +-
 .../demos/time/html/css/CustomSeparator.html  |   4 +-
 .../docs/demos/time/html/css/Remaining.css    |   6 +-
 .../docs/demos/time/html/css/Remaining.html   |   4 +-
 .../demos/time/react/css/CurrentDuration.css  |   6 +-
 .../demos/time/react/css/CurrentDuration.tsx  |   4 +-
 .../docs/demos/time/react/css/CurrentTime.css |   6 +-
 .../docs/demos/time/react/css/CurrentTime.tsx |   4 +-
 .../time/react/css/CustomNegativeSign.css     |   6 +-
 .../time/react/css/CustomNegativeSign.tsx     |   4 +-
 .../demos/time/react/css/CustomSeparator.css  |   6 +-
 .../demos/time/react/css/CustomSeparator.tsx  |   4 +-
 .../docs/demos/time/react/css/Remaining.css   |   6 +-
 .../docs/demos/time/react/css/Remaining.tsx   |   4 +-
 site/src/content/docs/how-to/write-guides.mdx |  52 +-
 .../docs/reference/buffering-indicator.mdx    |   8 +
 site/src/content/docs/reference/controls.mdx  |  33 ++
 .../docs/reference/fullscreen-button.mdx      |  61 ++-
 .../content/docs/reference/mute-button.mdx    |  62 +++
 .../src/content/docs/reference/pip-button.mdx |  27 +
 .../content/docs/reference/play-button.mdx    |  30 ++
 site/src/content/docs/reference/poster.mdx    |  20 +
 .../content/docs/reference/seek-button.mdx    |   8 +
 site/src/content/docs/reference/time.mdx      |  36 ++
 .../docs/reference/write-references.mdx       | 205 ++++++++
 site/src/docs.config.ts                       |   5 +
 111 files changed, 2680 insertions(+), 4642 deletions(-)
 create mode 100644 .claude/skills/api-reference/SKILL.md
 create mode 100644 .claude/skills/api-reference/references/builder-conventions.md
 create mode 100644 .claude/skills/api-reference/references/demo-patterns.md
 create mode 100644 .claude/skills/api-reference/references/mdx-structure.md
 delete mode 100644 .claude/skills/docs/examples/good-bad.md
 delete mode 100644 .claude/skills/docs/examples/tone-samples.md
 delete mode 100644 .claude/skills/docs/patterns/ai-readiness.md
 delete mode 100644 .claude/skills/docs/patterns/progressive-disclosure.md
 delete mode 100644 .claude/skills/docs/patterns/props-tables.md
 delete mode 100644 .claude/skills/docs/references/multi-framework.md
 create mode 100644 .claude/skills/docs/references/writing-style.md
 create mode 100644 .claude/skills/docs/review/checklist.md
 delete mode 100644 .claude/skills/docs/review/issue-format.md
 delete mode 100644 .claude/skills/docs/review/merge-template.md
 create mode 100644 .claude/skills/docs/review/templates.md
 delete mode 100644 .claude/skills/docs/templates/api-reference.md
 delete mode 100644 .claude/skills/docs/templates/component-page.md
 create mode 100644 .claude/skills/docs/templates/concept.md
 delete mode 100644 .claude/skills/docs/templates/guide.md
 delete mode 100644 .claude/skills/docs/templates/handbook.md
 create mode 100644 .claude/skills/docs/templates/how-to.md
 delete mode 100644 .claude/skills/docs/templates/migration-guide.md
 create mode 100644 site/src/components/docs/demos/mute-button/html/css/VolumeLevels.astro
 create mode 100644 site/src/components/docs/demos/mute-button/html/css/VolumeLevels.css
 create mode 100644 site/src/components/docs/demos/mute-button/html/css/VolumeLevels.html
 create mode 100644 site/src/components/docs/demos/mute-button/html/css/VolumeLevels.ts
 create mode 100644 site/src/components/docs/demos/mute-button/react/css/VolumeLevels.css
 create mode 100644 site/src/components/docs/demos/mute-button/react/css/VolumeLevels.tsx
 create mode 100644 site/src/content/docs/reference/write-references.mdx

diff --git a/.claude/skills/README.md b/.claude/skills/README.md
index 4c7ef226..f18bde6e 100644
--- a/.claude/skills/README.md
+++ b/.claude/skills/README.md
@@ -10,8 +10,9 @@ Specialized knowledge for AI agents working on Video.js 10.
 | Building HTML components   | `component` + `aria`               |
 | Building React components  | `component` + `aria`               |
 | Writing documentation      | `docs`                             |
-| Writing Design Docs / RFCs | `design` or `rfc`                  |
-| Reviewing API/architecture | `api` → `review/workflow.md`       |
+| Writing component reference| `api-reference`                     |
+| Writing Design Docs / RFCs | `design` or `rfc`                        |
+| Reviewing API/architecture | `api` → `review/workflow.md`             |
 | Reviewing documentation    | `docs` → `review/workflow.md`      |
 | Reviewing components       | `component` → `review/workflow.md` |
 | Reviewing accessibility    | `aria` → `review/workflow.md`      |
@@ -33,7 +34,8 @@ Specialized knowledge for AI agents working on Video.js 10.
 | [component](component/SKILL.md)         | Build headless UI components — compound patterns, state, styling       | Yes         |
 | [create-skill](create-skill/SKILL.md)   | Create new skills with proper structure and conventions                | No          |
 | [design](design/SKILL.md)               | Write Design Docs — decisions you own, component specs, feature designs| No          |
-| [docs](docs/SKILL.md)                   | Write Video.js 10 documentation                                        | Yes         |
+| [api-reference](api-reference/SKILL.md) | Scaffold component API reference pages                          | No          |
+| [docs](docs/SKILL.md)                   | Write Video.js 10 documentation (concepts, how-to, READMEs)    | Yes         |
 | [gh-issue](gh-issue/SKILL.md)           | Analyze GitHub issues and create implementation plans                  | No          |
 | [git](git/SKILL.md)                     | Git workflow — commit messages, PRs, branch naming, scope inference    | No          |
 | [review-branch](review-branch/SKILL.md) | Review branch changes and suggest improvements                         | No          |
@@ -56,7 +58,7 @@ skill/
 | Skill               | Review Focus                                      |
 | ------------------- | ------------------------------------------------- |
 | `api/review/`       | API design, architecture, DX, type safety         |
-| `docs/review/`      | Documentation quality — tone, structure, examples |
+| `docs/review/`       | Documentation quality — tone, structure, examples |
 | `component/review/` | Component architecture, state, props, styling     |
 | `aria/review/`      | Accessibility — ARIA, keyboard, focus, WCAG       |
 
diff --git a/.claude/skills/api-reference/SKILL.md b/.claude/skills/api-reference/SKILL.md
new file mode 100644
index 00000000..f4c42557
--- /dev/null
+++ b/.claude/skills/api-reference/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: api-reference
+description: >-
+  Scaffold API reference documentation for Video.js 10 components. Validates
+  the api-docs-builder output, checks design docs and linked PRs for context,
+  creates the MDX reference page with anatomy, prose sections, demos, and the
+  ApiReference component. Triggers: "api reference", "reference page",
+  "scaffold api docs", "add api docs", "component reference".
+---
+
+# API Reference
+
+Scaffold a complete API reference page for a Video.js 10 component.
+
+## Usage
+
+```
+/api-reference [component-name]
+```
+
+- `component-name` (optional): kebab-case component name (e.g., `play-button`). If omitted, will prompt.
+
+## Arguments
+
+$ARGUMENTS
+
+## Reference Material
+
+Load these files based on task:
+
+| Need | Load |
+|------|------|
+| Builder naming conventions | `references/builder-conventions.md` |
+| MDX page structure | `references/mdx-structure.md` |
+| Demo file patterns | `references/demo-patterns.md` |
+| Component libraries reference | `docs` skill → `references/component-libraries.md` |
+| Component patterns | `component` skill |
+| Accessibility | `aria` skill |
+| Design docs | `internal/design/` |
+
+## Your Tasks
+
+### Step 1: Gather context
+
+Accept component name as argument (kebab-case).
+
+1. Read the core file at `packages/core/src/core/ui/{name}/{name}-core.ts` — extract Props, State, behavior
+2. Read data-attrs file at `packages/core/src/core/ui/{name}/{name}-data-attrs.ts` — extract data attributes
+3. Check `packages/react/src/ui/{name}/index.parts.ts` — detect if multi-part
+4. Search `internal/design/` for matching design doc: `internal/design/**/*{name}*`. If no design doc is found, proceed — the core file is the primary source of truth; design docs are supplementary context.
+5. Read the HTML element file(s) for tag names at `packages/html/src/ui/{name}/`
+6. (Optional) Use `git log --oneline --all -- packages/core/src/core/ui/{name}` to find the commit that added the component, then check linked PRs via `gh pr list --search` for additional context. This enriches understanding but steps 1-3 and 5 are sufficient to build the reference page.
+
+### Step 2: Validate api-docs-builder compatibility
+
+1. Run `pnpm -F site api-docs` and check for errors
+2. Read the generated JSON at `site/src/content/generated-api-reference/{name}.json`
+3. Verify the JSON has expected sections (props, state, dataAttributes, platforms.html.tagName)
+4. For multi-part: verify each part appears in `parts` with correct names
+
+If JSON is missing or incomplete, diagnose which convention isn't met. Load `references/builder-conventions.md` for the full list of naming requirements and common failures. Propose fixes: either adjust the component to match conventions, or add a name override — prefer aligning with conventions unless there's good reason not to.
+
+### Step 3: Determine relevant prose sections
+
+Based on design docs, core logic, and component complexity, decide which sections to include between `## Anatomy` and `## Examples`. Not all are required — include only what adds value:
+
+- **Behavior** — include when the component has state transitions, timing, interaction logic, or non-obvious behavior (e.g., Controls auto-hide, BufferingIndicator delay, Time formatting). Skip for trivial components.
+- **Styling** — include when the component has data attributes for CSS targeting. Show CSS selector patterns. Always include for components with 2+ data attributes.
+- **Accessibility** — include when the component has ARIA attributes, keyboard interactions, or screen reader considerations. Always include for interactive components (buttons, sliders).
+- Other sections may be relevant depending on the component (e.g., "Platform Support" for features with availability detection).
+
+### Step 4: Create demos
+
+Create at least a BasicUsage demo in both HTML and React. Load `references/demo-patterns.md` for the full file structure and conventions.
+
+- HTML demo: 4 files (`.astro`, `.html`, `.css`, `.ts`)
+- React demo: 2 files (`.tsx`, `.css`)
+- Follow BEM naming: `{framework}-{component}-{variant}__{element}`
+- CSS uses data-attribute selectors for state-based styling
+- React uses `render` prop for state-based rendering
+- Video source: `https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4`
+- Poster image: `https://image.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/thumbnail.jpg`
+- Consider additional demos for features not covered by BasicUsage
+
+### Step 5: Create MDX reference page
+
+Load `references/mdx-structure.md` for the full structure template.
+
+1. Create `site/src/content/docs/reference/{name}.mdx`
+2. Add to sidebar in `site/src/docs.config.ts` (alphabetically within Components section)
+3. Structure: frontmatter → imports → Anatomy → prose sections → Examples → `<ApiReference />`
+4. Run `pnpm dev` from root and verify the page renders in both HTML and React framework modes
+
+## Related Skills
+
+| Need | Use |
+|------|-----|
+| Building UI components | `component` skill |
+| Accessibility patterns | `aria` skill |
+| Documentation standards | `docs` skill |
+| API design principles | `api` skill |
diff --git a/.claude/skills/api-reference/references/builder-conventions.md b/.claude/skills/api-reference/references/builder-conventions.md
new file mode 100644
index 00000000..6e4fa088
--- /dev/null
+++ b/.claude/skills/api-reference/references/builder-conventions.md
@@ -0,0 +1,85 @@
+# Builder Conventions
+
+Naming and file placement conventions required by the api-docs-builder at `site/scripts/api-docs-builder/`.
+
+## File Locations
+
+| File | Path | Purpose |
+|------|------|---------|
+| Core | `packages/core/src/core/ui/{name}/{name}-core.ts` | Props, State, defaultProps |
+| Data attrs | `packages/core/src/core/ui/{name}/{name}-data-attrs.ts` | Data attribute definitions |
+| HTML element | `packages/html/src/ui/{name}/{name}-element.ts` | Custom element with `static tagName` |
+| React parts | `packages/react/src/ui/{name}/index.parts.ts` | Multi-part detection (optional) |
+
+## Naming Requirements
+
+The builder derives PascalCase from kebab-case using `kebabCase` from es-toolkit. All interfaces and exports must follow this pattern:
+
+| Convention | Example (play-button) |
+|-----------|----------------------|
+| Props interface | `PlayButtonProps` |
+| State interface | `PlayButtonState` |
+| Core class | `PlayButtonCore` |
+| Data attrs export | `PlayButtonDataAttrs` |
+| HTML element class | `PlayButtonElement` |
+| HTML tag name | `static tagName = 'media-play-button'` |
+
+## NAME_OVERRIDES
+
+When kebab-to-pascal conversion doesn't produce the correct name, add an override in `site/scripts/api-docs-builder/src/index.ts`:
+
+```ts
+const NAME_OVERRIDES: Record<string, string> = {
+  'pip-button': 'PiPButton',
+};
+```
+
+Use overrides only when the standard conversion fails (e.g., acronyms like PiP). Prefer aligning component naming with the standard conversion when possible.
+
+## Multi-Part Components
+
+**Detection**: Presence of `packages/react/src/ui/{name}/index.parts.ts`.
+
+**Primary part identification**: The part whose HTML element file is `{name}-element.ts` (not `{name}-{part}-element.ts`). The primary part receives the shared core props/state/data-attrs.
+
+**Non-primary parts**: Each gets its own element file at `{name}-{part}-element.ts`. Element class must be `{Name}{Part}Element` (e.g., `TimeGroupElement`).
+
+**Part descriptions**: Extracted from JSDoc on the React component export:
+```tsx
+/** Displays a formatted time value. */
+export const Value = ...;
+```
+
+## JSDoc Extraction
+
+- **Data attribute descriptions**: From JSDoc comments on each property in the data-attrs export object
+- **Part descriptions**: From JSDoc on React component exports in their `.tsx` files
+- **Prop/state descriptions**: From JSDoc on interface properties in the core file
+
+## Common Failures
+
+The builder fails silently for many issues — data just won't appear in the JSON:
+
+| Symptom | Cause |
+|---------|-------|
+| No JSON generated | Core file missing or Props interface not found |
+| Empty props | Interface not named `{PascalCase}Props` |
+| Empty state | Interface not named `{PascalCase}State` |
+| No data attributes | File missing or export not named `{PascalCase}DataAttrs` |
+| No HTML tag | Element file missing or no `static tagName` |
+| No part descriptions | Missing JSDoc on React component exports |
+| Wrong PascalCase | Need a `NAME_OVERRIDES` entry |
+
+## Validation
+
+```bash
+# Generate JSON
+pnpm -F site api-docs
+
+# Check output
+cat site/src/content/generated-api-reference/{name}.json
+
+# Verify schema
+# The builder validates against ComponentApiReferenceSchema before writing.
+# Schema errors are logged as errors and cause exit code 1.
+```
diff --git a/.claude/skills/api-reference/references/demo-patterns.md b/.claude/skills/api-reference/references/demo-patterns.md
new file mode 100644
index 00000000..45d64079
--- /dev/null
+++ b/.claude/skills/api-reference/references/demo-patterns.md
@@ -0,0 +1,274 @@
+# Demo Patterns
+
+File structure and conventions for interactive component demos.
+
+## Directory Structure
+
+```
+site/src/components/docs/demos/{component}/
+├── html/css/
+│   ├── BasicUsage.astro     # Astro wrapper (renders HTML, imports CSS, bundles script)
+│   ├── BasicUsage.html      # Markup only (no <style> or <script>)
+│   ├── BasicUsage.css       # Styles
+│   └── BasicUsage.ts        # Side-effect imports for custom element registration
+└── react/css/
+    ├── BasicUsage.tsx        # React component
+    └── BasicUsage.css        # Styles
+```
+
+## BEM Naming
+
+Block = `{framework}-{component}-{variant}`, element = `__{part}`:
+
+```
+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 */
+```
+
+The framework prefix (`html-` / `react-`) prevents CSS leaking between HTML and React demos on the same page (both render but one is hidden).
+
+## HTML Demo Files
+
+### .astro wrapper
+
+```astro
+---
+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>
+```
+
+The `.astro` wrapper is required because only Astro `<script>` tags go through Vite's bundling pipeline.
+
+### .html (markup only)
+
+```html
+<video-player class="html-mute-button-basic">
+    <video
+        src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
+        autoplay
+        muted
+        playsinline
+        loop
+    ></video>
+    <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>
+</video-player>
+```
+
+- No `<style>` or `<script>` tags
+- Video attributes: `autoplay muted playsinline loop`
+- State labels use CSS class names toggled by data attributes
+
+### .css (styles)
+
+```css
+.html-mute-button-basic {
+  position: relative;
+}
+
+.html-mute-button-basic video {
+  width: 100%;
+}
+
+.html-mute-button-basic__button {
+  padding-block: 8px;
+  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-inline: 20px;
+  cursor: pointer;
+}
+
+/* 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; }
+```
+
+### .ts (registration imports)
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/mute-button';
+```
+
+Import registration for:
+- `@videojs/html/video/player` — always needed (registers `<video-player>`)
+- `@videojs/html/ui/{component}` — registers the component's custom element
+
+## React Demo Files
+
+### .tsx (component)
+
+```tsx
+import { createPlayer, features, MuteButton, Video } from '@videojs/react';
+
+import './BasicUsage.css';
+
+const Player = createPlayer({ features: [...features.video] });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="react-mute-button-basic">
+        <Video
+          src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <MuteButton
+          className="react-mute-button-basic__button"
+          render={(props, state) => (
+            <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+
+Key patterns:
+- `createPlayer({ features: [...features.video] })` creates the player
+- Video attributes: `autoPlay muted playsInline loop` (React camelCase)
+- `render` prop for state-based rendering: `render={(props, state) => ...}`
+- Spread `{...props}` on the rendered element for accessibility attributes
+
+### .css (styles)
+
+Same base styling as HTML but with `react-` BEM prefix:
+
+```css
+.react-mute-button-basic {
+  position: relative;
+}
+
+.react-mute-button-basic video {
+  width: 100%;
+}
+
+.react-mute-button-basic__button {
+  padding-block: 8px;
+  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-inline: 20px;
+  cursor: pointer;
+}
+```
+
+React CSS files typically don't need data-attribute selectors since the `render` prop handles state-based rendering. Include them only when CSS state reflection is used.
+
+## State Reflection Patterns
+
+### HTML: Data attribute selectors
+
+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; }
+
+/* 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; }
+```
+
+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 {
+  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; }
+```
+
+### React: Render prop
+
+```tsx
+<MuteButton
+  render={(props, state) => (
+    <button {...props}>
+      {state.volumeLevel === 'off'
+        ? 'Off'
+        : state.volumeLevel === 'low'
+          ? 'Low'
+          : state.volumeLevel === 'medium'
+            ? 'Medium'
+            : 'High'}
+    </button>
+  )}
+/>
+```
+
+### Three-state pattern (Play/Pause/Replay)
+
+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; }
+```
+
+React uses nested ternary in the render prop:
+
+```tsx
+render={(props, state) => (
+  <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
+)}
+```
+
+## Video Sources
+
+- **Video**: `https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4`
+- **Poster**: `https://image.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/thumbnail.jpg`
+
+## Base Button Styles
+
+All button demos share this base overlay style:
+
+```css
+.__button {
+  padding-block: 8px;
+  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-inline: 20px;
+  cursor: pointer;
+}
+```
diff --git a/.claude/skills/api-reference/references/mdx-structure.md b/.claude/skills/api-reference/references/mdx-structure.md
new file mode 100644
index 00000000..bd9ad629
--- /dev/null
+++ b/.claude/skills/api-reference/references/mdx-structure.md
@@ -0,0 +1,225 @@
+# MDX Structure
+
+Structure and conventions for API reference MDX pages at `site/src/content/docs/reference/`.
+
+## Frontmatter
+
+```yaml
+---
+title: MuteButton              # PascalCase component name
+frameworkTitle:
+  html: media-mute-button      # HTML custom element tag name
+description: A button component for muting and unmuting audio playback
+---
+```
+
+- `title`: PascalCase React component name
+- `frameworkTitle.html`: The `static tagName` from the HTML element file
+- `description`: One-line description of the component
+
+## Page Structure
+
+```
+frontmatter
+imports (React demos, HTML demos)
+## Anatomy
+## Behavior       (if applicable)
+## Styling        (if applicable)
+## Accessibility  (if applicable)
+## Examples
+### BasicUsage
+### [Additional demos]
+<ApiReference component="{PascalCase}" />
+```
+
+## Imports Section
+
+### React demo imports
+
+```mdx
+{/* React demos */}
+import BasicUsageDemoReact from "@/components/docs/demos/{component}/react/css/BasicUsage";
+import basicUsageReactTsx from "@/components/docs/demos/{component}/react/css/BasicUsage.tsx?raw";
+import basicUsageReactCss from "@/components/docs/demos/{component}/react/css/BasicUsage.css?raw";
+```
+
+- Component import: default export from `.tsx` (no extension needed)
+- Source imports: `?raw` suffix for displaying source code in tabs
+
+### HTML demo imports
+
+```mdx
+{/* HTML demos */}
+import BasicUsageDemoHtml from "@/components/docs/demos/{component}/html/css/BasicUsage.astro";
+import basicUsageHtml from "@/components/docs/demos/{component}/html/css/BasicUsage.html?raw";
+import basicUsageHtmlCss from "@/components/docs/demos/{component}/html/css/BasicUsage.css?raw";
+import basicUsageHtmlTs from "@/components/docs/demos/{component}/html/css/BasicUsage.ts?raw";
+```
+
+- `.astro` wrapper: renders live demo
+- `.html`, `.css`, `.ts`: `?raw` imports for source tabs
+
+### Import naming convention
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| React component | `{DemoName}DemoReact` | `BasicUsageDemoReact` |
+| React source | `{demoName}React{Ext}` | `basicUsageReactTsx` |
+| HTML component | `{DemoName}DemoHtml` | `BasicUsageDemoHtml` |
+| HTML source | `{demoName}Html` / `{demoName}Html{Ext}` | `basicUsageHtml`, `basicUsageHtmlCss` |
+
+## Anatomy Section
+
+```mdx
+## Anatomy
+
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<MuteButton />
+```
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+```html
+<media-mute-button></media-mute-button>
+```
+</FrameworkCase>
+```
+
+For multi-part components, show composed usage:
+
+```mdx
+<FrameworkCase frameworks={["react"]}>
+```tsx
+<Time.Group>
+  <Time.Value type="current" />
+  <Time.Separator />
+  <Time.Value type="duration" />
+</Time.Group>
+```
+</FrameworkCase>
+```
+
+## Prose Sections
+
+### Behavior
+
+Explain state transitions, timing, and interaction logic. Use tables for enumerated states:
+
+```mdx
+## Behavior
+
+Toggles mute on and off. Exposes a derived `volumeLevel` based on the current volume and mute state:
+
+| Level | Condition |
+|-------|-----------|
+| `off` | Muted or volume is 0 |
+| `low` | Volume < 0.5 |
+```
+
+### Styling
+
+Show data attributes as a table, then CSS selector patterns:
+
+```mdx
+## Styling
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `data-muted` | Present / absent | Present when audio is muted |
+| `data-volume-level` | `"off"` \| `"low"` \| `"medium"` \| `"high"` | Current volume level |
+
+Use `data-volume-level` for multi-level icon switching:
+
+```css
+media-mute-button[data-volume-level="off"] .icon-off { display: inline; }
+```
+```
+
+### Accessibility
+
+Describe ARIA attributes, keyboard interactions, and label overrides:
+
+```mdx
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: "Unmute" when muted, "Mute" when unmuted. Override with the `label` prop. Keyboard activation: <kbd>Enter</kbd> / <kbd>Space</kbd>.
+```
+
+## Examples Section
+
+### Nesting pattern
+
+```mdx
+## Examples
+
+### Basic Usage
+
+<FrameworkCase frameworks={["react"]}>
+  <StyleCase styles={["css"]}>
+    <Demo files={[
+      { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
+      { title: "App.css", code: basicUsageReactCss, lang: "css" },
+    ]}>
+      <BasicUsageDemoReact client:idle />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+  <StyleCase styles={["css"]}>
+    <Demo files={[
+      { title: "index.html", code: basicUsageHtml, lang: "html" },
+      { title: "index.css", code: basicUsageHtmlCss, lang: "css" },
+      { title: "index.ts", code: basicUsageHtmlTs, lang: "ts" },
+    ]}>
+      <BasicUsageDemoHtml />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
+```
+
+Key details:
+- React demos use `client:idle` for hydration
+- HTML demos render server-side (no `client:*` directive)
+- React source tabs: `App.tsx`, `App.css`
+- HTML source tabs: `index.html`, `index.css`, `index.ts`
+
+## ApiReference Component
+
+Always the last element in the file:
+
+```mdx
+<ApiReference component="MuteButton" />
+```
+
+The component auto-renders Props, State, Data Attributes for single-part and all Parts for multi-part.
+
+## Sidebar Entry
+
+Add to `site/src/docs.config.ts` in the Components section, alphabetically:
+
+```ts
+{
+  sidebarLabel: 'Components',
+  contents: [
+    // sorted alphabetically
+    { slug: 'reference/buffering-indicator' },
+    { slug: 'reference/controls' },
+    // ...
+    { slug: 'reference/{name}' },  // <-- insert alphabetically
+    // ...
+  ],
+},
+```
+
+## Required Astro Component Imports
+
+Every reference MDX needs these at the top of the imports:
+
+```mdx
+import ApiReference from "@/components/docs/api-reference/ApiReference.astro";
+import FrameworkCase from "@/components/docs/FrameworkCase.astro";
+import StyleCase from "@/components/docs/StyleCase.astro";
+import Demo from "@/components/docs/demos/Demo.astro";
+```
diff --git a/.claude/skills/api/SKILL.md b/.claude/skills/api/SKILL.md
index 5575075a..9fa1bbf1 100644
--- a/.claude/skills/api/SKILL.md
+++ b/.claude/skills/api/SKILL.md
@@ -107,4 +107,4 @@ For reviewing APIs and architecture, load `review/workflow.md`.
 | ---------------------- | ----------------- |
 | Building UI components | `component` skill |
 | Accessibility patterns | `aria` skill      |
-| Documentation          | `docs` skill      |
+| Documentation          | `docs` skill |
diff --git a/.claude/skills/aria/SKILL.md b/.claude/skills/aria/SKILL.md
index 86724370..a3553b70 100644
--- a/.claude/skills/aria/SKILL.md
+++ b/.claude/skills/aria/SKILL.md
@@ -73,4 +73,4 @@ For structured accessibility reviews, load the review workflow:
 | ---------------------- | ----------------- |
 | Building UI components | `component` skill |
 | API design principles  | `api` skill       |
-| Documentation          | `docs` skill      |
+| Documentation          | `docs` skill |
diff --git a/.claude/skills/claude-update/SKILL.md b/.claude/skills/claude-update/SKILL.md
index 0a3f4a8d..a0fb33d2 100644
--- a/.claude/skills/claude-update/SKILL.md
+++ b/.claude/skills/claude-update/SKILL.md
@@ -27,7 +27,7 @@ update AI documentation to incorporate them as appropriate.
 | Component patterns            | `component` skill    |
 | Accessibility                 | `aria` skill         |
 | API design / DX               | `api` skill          |
-| Documentation                 | `docs` skill         |
+| Documentation                 | `docs` skill   |
 
 **Decision:** Ask "Who needs this?" — if domain-specific, use a skill.
 
diff --git a/.claude/skills/component/SKILL.md b/.claude/skills/component/SKILL.md
index 4b080d77..1d951e08 100644
--- a/.claude/skills/component/SKILL.md
+++ b/.claude/skills/component/SKILL.md
@@ -215,4 +215,5 @@ For structured component reviews, load the review workflow:
 | ---------------------- | ------------ |
 | Accessibility patterns | `aria` skill |
 | API design principles  | `api` skill  |
-| Documentation patterns | `docs` skill |
+| Documentation patterns | `docs` skill         |
+| Component API reference  | `api-reference` skill |
diff --git a/.claude/skills/create-skill/SKILL.md b/.claude/skills/create-skill/SKILL.md
index 1d18819b..4fe8016d 100644
--- a/.claude/skills/create-skill/SKILL.md
+++ b/.claude/skills/create-skill/SKILL.md
@@ -55,7 +55,7 @@ Is this domain-specific knowledge?
 
 | Type          | Characteristics                                              | Examples                              |
 | ------------- | ------------------------------------------------------------ | ------------------------------------- |
-| **Knowledge** | Domain expertise, reference-heavy, may have review workflow  | `api`, `component`, `aria`, `docs`    |
+| **Knowledge** | Domain expertise, reference-heavy, may have review workflow  | `api`, `component`, `aria`, `docs` |
 | **Workflow**  | Conventions, processes, templates                            | `git`, `rfc`                          |
 | **Command**   | Procedural steps, forked context, restricted tools           | `commit-pr`, `gh-issue`, `review-branch` |
 
diff --git a/.claude/skills/design/SKILL.md b/.claude/skills/design/SKILL.md
index 1f3edba3..39bdda59 100644
--- a/.claude/skills/design/SKILL.md
+++ b/.claude/skills/design/SKILL.md
@@ -202,4 +202,4 @@ Before finalizing a Design Doc:
 | Proposals needing buy-in   | `rfc` skill       |
 | API design principles      | `api` skill       |
 | Building UI components     | `component` skill |
-| Writing documentation      | `docs` skill      |
+| Writing documentation      | `docs` skill |
diff --git a/.claude/skills/docs/SKILL.md b/.claude/skills/docs/SKILL.md
index 2ba5839a..57c589f5 100644
--- a/.claude/skills/docs/SKILL.md
+++ b/.claude/skills/docs/SKILL.md
@@ -1,298 +1,213 @@
 ---
 name: docs
 description: >-
-  Write and review documentation for Video.js 10. Use for writing docs, guides, READMEs,
-  JSDoc comments, or reviewing existing documentation. For docs review, load review/workflow.md.
-  Triggers: "write docs", "create guide", "review docs", "audit documentation".
+  Write and review documentation for Video.js 10 — site pages, READMEs, and JSDoc.
+  Use for writing concept pages, how-to guides, package READMEs, and inline API docs.
+  Component reference pages use the `api-reference` skill instead.
+  Triggers: "write docs", "create guide", "review docs", "audit documentation",
+  "write README", "JSDoc", "inline docs".
 ---
 
 # Docs
 
 Write documentation for Video.js 10.
 
-## Reference Material
+## Before you start
 
-Load these files based on task:
+Read the relevant sources of truth before writing any documentation:
 
-| Task                       | Load                                   |
-| -------------------------- | -------------------------------------- |
-| Any docs task              | This file (SKILL.md)                   |
-| README documentation       | `templates/readme.md`                  |
-| Component docs             | `references/component-libraries.md`    |
-| Multi-framework docs       | `references/multi-framework.md` (TODO) |
-| Web Components             | `references/component-libraries.md`    |
-| Studying exemplary docs    | `references/gold-standard.md`          |
-| State/config/tooling docs  | `references/state-tooling.md`          |
-| Error/troubleshooting docs | `patterns/error-docs.md`               |
+| Source | What it covers |
+|--------|----------------|
+| `site/CLAUDE.md` | Site architecture, MDX components, demos, routing, collections, Tailwind config |
+| `site/src/content/docs/how-to/write-guides.mdx` | Living reference with rendered examples of every MDX component |
+| `CLAUDE.md` (repo root) | JSDoc conventions (Minimal JSDoc, No Obvious Comments sections) |
 
-| Pattern needed          | Load                                 |
-| ----------------------- | ------------------------------------ |
-| Props/attributes tables | `patterns/props-tables.md`           |
-| Code examples           | `patterns/code-examples.md`          |
-| Progressive disclosure  | `patterns/progressive-disclosure.md` |
-| AI/agent readiness      | `patterns/ai-readiness.md`           |
+This skill adds writing guidance on top of those. When in doubt, the source files win.
 
-| Starting from scratch | Load                           |
-| --------------------- | ------------------------------ |
-| README                | `templates/readme.md`          |
-| API reference         | `templates/api-reference.md`   |
-| Component page        | `templates/component-page.md`  |
-| Guide/tutorial        | `templates/guide.md`           |
-| Handbook page         | `templates/handbook.md`        |
-| Migration guide       | `templates/migration-guide.md` |
+## Reference material
 
-## Principles
+| Task | Load |
+|------|------|
+| Writing style and voice | `references/writing-style.md` |
+| Notes on effective component library docs | `references/component-libraries.md` |
+| Notes on effective general developer tool docs | `references/gold-standard.md` |
+| Notes on effective state tooling docs | `references/state-tooling.md` |
+| Concept page from scratch | `templates/concept.md` |
+| How-to guide from scratch | `templates/how-to.md` |
+| Package README from scratch | `templates/readme.md` |
+| Code example conventions | `patterns/code-examples.md` |
+| Error documentation patterns | `patterns/error-docs.md` |
+| Review workflow (multi-agent) | `review/workflow.md` |
+| Review checklist (single-agent) | `review/checklist.md` |
+| Review agent prompts | `review/agents.md` |
+| Review issue/report templates | `review/templates.md` |
+| Component reference page | `api-reference` skill |
 
-### Fast
+## Documentation types
 
-- Optimize for static generation
-- Fast search (Pagefind or Algolia)
+### Site documentation (Diataxis)
 
-### Readable
+The site follows the [Diataxis](https://diataxis.fr/) framework:
 
-- Be concise — every token must earn its place
-- Avoid jargon and idioms
-- Optimize for skimming (bold, lists, headings)
-- Simple first-time experience, reveal complexity gradually
-- Many code examples you can copy/paste
+| Mode | Directory | Purpose |
+|------|-----------|---------|
+| Concept | `concepts/` | Explain how and why things work |
+| How-to | `how-to/` | Achieve a specific outcome with step-by-step instructions |
+| Reference | `reference/` | Component API docs — owned by `api-reference` skill |
 
-### Helpful
+**When in doubt, write a concept page.** Most new documentation should be concept pages.
 
-- Document workarounds even for product gaps
-- Include migration guides for breaking changes
-- Easy to leave feedback
+| Concept page | How-to guide |
+|---|---|
+| **Preferred** — default choice | Use sparingly |
+| Reference while working | Learning from scratch |
+| One concept per page | Multi-step narrative |
+| Scannable, minimal prose | Explains "why" at each step |
+| No prerequisites | Has prerequisites |
+| Jump in anywhere | Sequential |
 
-### AI-Native
+### Package documentation
 
-- Prefer code over "click here"
-- Prefer prompts over lengthy tutorials
-- Serve `llms.txt` as docs directory
-- Support `.md` URL suffix for markdown view
+| Type | Location | Purpose |
+|------|----------|---------|
+| README | `packages/{name}/README.md` | First impression — install, quick example, concepts |
+| JSDoc | Inline in source | API docs for editors and generated references |
 
-### Agent-Ready
+## JSDoc
 
-- Pages easy to copy as markdown
-- Ship docs in package (JSDoc, README)
-- Include `AGENTS.md` with library
-- Self-contained examples with all imports
+CLAUDE.md (repo root) defines the hard rules — no redundant `@param`/`@returns`, no obvious comments, minimal JSDoc. This section adds a decision framework for **when** to write JSDoc.
 
-### Polished
-
-- Every heading linkable with stable anchors
-- Cross-link related guides, APIs, examples
-- Good metadata for search
-
-### Accessible
-
-- Alt tags on images
-- Respect `prefers-reduced-motion`
-
-## Tone & Style
-
-Direct. Confident. Friendly but not chatty.
-
-```markdown
-// ❌ Wordy
-In order to create a new player instance, you'll need to call the
-createPlayer function and pass in a configuration object.
-
-// ✅ Direct
-Create a player:
-
-const player = createPlayer({ src: 'video.mp4' });
-```
-
-**Rules:**
-
-- **Sentence case for headings** — capitalize only the first word and proper nouns (e.g., "Choose your JS framework", not "Choose Your JS Framework")
-- Active voice, second person ("you")
-- Short sentences
-- No filler ("In order to", "basically", "simply")
-- No hedging ("might", "could", "perhaps")
-- Code does the heavy lifting
-
-## Do/Don't Pattern
-
-Show why something is better:
-
-```markdown
-### Requesting State Changes
-
-// ❌ Don't — mutate directly
-video.volume = 0.5; // No coordination, no error handling
-
-// ✅ Do — use store actions
-player.setVolume(0.5); // Managed, observable, integrated with store
-```
-
-## Familiar Terms
-
-Explain using ecosystem patterns:
-
-```markdown
-// ✅ Good
-Requests work like HTTP — you ask, the target responds asynchronously.
-
-// ✅ Good
-State flows down like React context. Events bubble up like DOM events.
-```
-
-## Cross-Linking
-
-- Reference related pages liberally
-- Repetition across pages is okay — users land anywhere
-- Add "See also" sections
-
-## Documentation Types
-
-**Prefer handbooks.** Most documentation should be handbook pages — one concept, quickly scannable. Use guides only for true tutorials that build something from scratch.
-
-### README
-
-**Light** (has site docs): Description, install, one example, link.
-
-**Comprehensive** (no site docs): Full API, progressive examples.
-
-### Handbook (Preferred)
-
-Bite-sized reference pages. One concept, quickly scannable. Users skim while building.
-
-**Use for:** Concepts, patterns, configuration, troubleshooting, "how do I X?"
-
-Reference: Base UI handbook (styling, composition, TypeScript, forms).
-
-```markdown
-## Styling
-
-Style components using data attributes and CSS variables.
-
-.slider[data-dragging] {
-cursor: grabbing;
-}
-
-### Data Attributes
-
-Components expose state via `data-*` attributes...
-
-### CSS Variables
-
-Dynamic values for sizing and transforms...
-
-**See also:** [Tailwind Integration](/handbook/tailwind)
-```
-
-### Guides (Rare)
-
-Narrative tutorials. Step-by-step, teaches "why", builds toward something complete.
-
-**Use sparingly for:** Getting Started, Building X from Scratch. Most "guide-like" content should be a handbook page instead.
-
-Reference: Tailwind Core Concepts.
-
-```markdown
-## Building a Custom Player
-
-This guide walks through building a player from scratch.
-
-### Prerequisites
-
-...
-
-### Step 1: Set up the store
-
-...
-
-### Step 2: Create the UI
-
-...
-
-### What's next?
-
-...
-```
-
-**Handbook vs Guides:**
-
-| Handbook                 | Guides                       |
-| ------------------------ | ---------------------------- |
-| **Preferred**            | Use sparingly                |
-| Reference while working  | Learning from scratch        |
-| One concept per page     | Multi-step narrative         |
-| Scannable, minimal prose | Explains "why"               |
-| Base UI style            | Tailwind Core Concepts style |
-
-### API Reference
-
-Structure: Example → Anatomy → Options → Returns → Data Attributes → See Also
-
-See `templates/api-reference.md` for full template.
-
-### Component Pages
-
-Structure: Example → Features → Installation → Anatomy → API Reference → Examples → Accessibility
-
-See `templates/component-page.md` for full template.
-
-## Video.js 10 Architecture
-
-When documenting, understand the package hierarchy:
-
-| Package                 | Subpaths                        | Purpose                                 | Doc Focus                          |
-| ----------------------- | ------------------------------- | --------------------------------------- | ---------------------------------- |
-| `@videojs/utils`        | `/dom`, `/predicate`, `/events` | Shared utilities                        | Utility reference                  |
-| `@videojs/store`        | `/html`, `/react`               | State management                        | Features, requests, error handling |
-| `@videojs/core`         | `/dom`                          | Runtime-agnostic logic + media features | API reference, concepts            |
-| `@videojs/html`         | `/skins/frosted`                | Web Components                          | Component docs, styling            |
-| `@videojs/react`        | —                               | React adapter                           | Components, hooks                  |
-| `@videojs/react-native` | —                               | React Native adapter                    | Mobile-specific guides             |
-
-**Dependency flow:** `utils → store → core → html / react / react-native`
-
-Document `@videojs/store` as state primitives (features, requests, guards).
-Document `@videojs/html` as Web Components with controllers and mixins.
-Document framework adapters with framework-native idioms.
-
-## Output Locations
+### Decision tree
 
 ```
-packages/{name}/README.md          — readme (primary docs until site launches)
-packages/{name}/CLAUDE.md          — agent instructions
-site/src/content/docs/api/         — API reference
-site/src/content/docs/handbook/    — handbook
-site/src/content/docs/guides/      — guides
-site/src/content/docs/components/  — components
-site/public/llms.txt               — AI docs index
+Is the export public (used outside the package)?
+├─ No → Skip JSDoc
+└─ Yes → Is the name self-documenting?
+         ├─ Yes (e.g., `supportsIdleCallback()`) → Skip JSDoc
+         └─ No → Does it have complex generics or non-obvious behavior?
+                  ├─ Yes → JSDoc with @param/@example as needed
+                  └─ No → One-sentence summary
 ```
 
-> **Note:** Site structure (`site/src/content/docs/`) not yet created.
-> Package READMEs are the primary documentation until the site launches.
+### Patterns (from the codebase)
+
+**Minimal** — One-sentence summary when the name is mostly clear but context helps:
+
+```ts
+// packages/utils/src/number/number.ts
+/** Clamp a value between min and max (inclusive). */
+export function clamp(value: number, min: number, max: number): number {
+```
+
+**With example** — Summary + `@example` when usage isn't obvious from the signature:
+
+```ts
+// packages/store/src/react/hooks/use-store.ts
+/**
+ * Access store state and actions.
+ *
+ * Without selector: Returns the store, does NOT subscribe to changes.
+ * With selector: Returns selected state, re-renders when selected state changes (shallowEqual).
+ *
+ * @example
+ * ```tsx
+ * // Store access (no subscription) - access actions, subscribe without re-render
+ * function Controls() {
+ *   const { setVolume } = useStore(store);
+ * }
+ *
+ * // Selector-based subscription - re-renders when paused changes
+ * function PlayButton() {
+ *   const paused = useStore(store, (s) => s.paused);
+ *   return <button>{paused ? 'Play' : 'Pause'}</button>;
+ * }
+ * ```
+ */
+```
+
+**With params** — `@param`/`@returns` for complex generics where TypeScript alone isn't enough:
+
+```ts
+// packages/store/src/core/combine.ts
+/**
+ * Combines multiple slices into a single slice.
+ *
+ * @param slices - The slices to combine.
+ * @returns A new slice that represents the combination of the input slices.
+ */
+export function combine<Target, const Slices extends Slice<Target, any>[]>(
+  ...slices: Slices
+): Slice<Target, UnionSliceState<Slices>> {
+```
+
+## Writing principles
+
+For full guidelines, load `references/writing-style.md`. The essentials:
+
+- **Direct.** No filler ("In order to", "basically", "simply"). No hedging ("might", "could").
+- **Code-first.** Show the code, then explain. Not the other way around.
+- **Scannable.** Bold, lists, headings, tables. Walls of text become tables or lists.
+- **Self-contained examples.** Include all imports. Use realistic values, not `foo`/`bar`.
+- **Show output.** When the result isn't obvious, add a comment showing expected output.
+- **Progressive.** Start with the simplest version. Add complexity in later examples.
+- **Cross-link.** End pages with "See also" linking related concepts and references. Repetition across pages is fine — readers land anywhere.
+
+### Do/don't contrasts
+
+Use `// ❌ Don't` / `// ✅ Do` pairs to show why something is better. Effective for common mistakes, API misuse, and style guidance. Always explain *why* the wrong way is wrong.
+
+### Callout types
+
+Use `<Aside>` (never `:::note` syntax):
+
+| Type | When |
+|------|------|
+| `note` | Supplementary info, not critical |
+| `tip` | Optimization or best practice |
+| `caution` | Could cause problems if ignored |
+| `danger` | Will break things if ignored |
+
+## MDX components
+
+Full documentation is in `site/CLAUDE.md`. Quick reference:
+
+| Component | Purpose |
+|-----------|---------|
+| `<FrameworkCase frameworks={["react"]}>` | Show content for specific framework only |
+| `<StyleCase styles={["css"]}>` | Show content for specific style only |
+| `<Aside type="note">` | Callout box (note, tip, caution, danger) |
+| `<TabsRoot client:idle>` | Tabbed content container |
+| `<ServerCode code={variable} lang="ts" />` | Render code from variable or `?raw` import |
+| `<MinimalFrame>` | Bordered container for demos/iframes |
+| `<DocsLink slug="reference/play-button">` | Framework-aware internal link |
+| `<Demo files={[...]}>` | Code viewer with live preview |
+
+Key gotchas:
+- All `<Tab*>` components require `client:idle` — never `client:visible`
+- No H1 — page title comes from frontmatter
+- Only `.mdx` files, never `.md`
 
 ## Process
 
-1. Determine doc type (handbook preferred; guide only for true tutorials)
-2. Load relevant reference/pattern/template files
-3. Check existing style in codebase
-4. Write concise draft with examples
-5. Add do/don't where helpful
-6. Add cross-links to related pages
-7. Verify examples pass linting and types
-8. Cut anything unnecessary
+1. Determine doc type — site page (concept preferred), README, or JSDoc
+2. Load the relevant template or reference
+3. Check existing docs for style and patterns
+4. Write concise draft — code before prose
+5. Add do/don't contrasts where helpful
+6. Add cross-links and "See also" section
+7. **Site pages only:** Add page to sidebar in `site/src/docs.config.ts`
+8. **Site pages only:** Verify it renders for all framework combinations
 
 ## Review
 
-For reviewing existing documentation against these standards, load `review/workflow.md`.
+- **Quick review** (single agent): Load `review/checklist.md`
+- **Full review** (multi-agent): Load `review/workflow.md`
 
-| File                                                 | Content                         |
-| ---------------------------------------------------- | ------------------------------- |
-| [review/workflow.md](review/workflow.md)             | Review process and checklists   |
-| [review/agents.md](review/agents.md)                 | Full prompts for each sub-agent |
-| [review/issue-format.md](review/issue-format.md)     | Issue format with examples      |
-| [review/merge-template.md](review/merge-template.md) | Final report template           |
+## Related skills
 
-## Related Skills
-
-| Need                   | Use               |
-| ---------------------- | ----------------- |
+| Need | Use |
+|------|-----|
+| Component reference pages | `api-reference` skill |
 | Building UI components | `component` skill |
-| Accessibility patterns | `aria` skill      |
-| API design principles  | `api` skill       |
+| Accessibility patterns | `aria` skill |
+| API design principles | `api` skill |
diff --git a/.claude/skills/docs/examples/good-bad.md b/.claude/skills/docs/examples/good-bad.md
deleted file mode 100644
index 21d0f414..00000000
--- a/.claude/skills/docs/examples/good-bad.md
+++ /dev/null
@@ -1,310 +0,0 @@
-# Do/Don't Examples
-
-Collection of good/bad patterns for Video.js documentation.
-
-## Tone & Voice
-
-### Wordy vs Direct
-
-```markdown
-// ❌ Wordy
-In order to create a new player instance, you will first need to
-import the createPlayer function from the core package, and then
-you can call it with a configuration object that contains your options.
-
-// ✅ Direct
-Create a player:
-
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({ src: 'video.mp4' });
-```
-
-### Hedging vs Confident
-
-```markdown
-// ❌ Hedging
-You might want to consider using the request API, which could
-potentially help with handling async operations.
-
-// ✅ Confident
-Use the request API for async operations.
-```
-
-### Passive vs Active
-
-```markdown
-// ❌ Passive
-The player can be created by calling createPlayer.
-
-// ✅ Active
-Call createPlayer to create a player.
-```
-
-### Explaining vs Showing
-
-```markdown
-// ❌ Over-explaining
-The subscribe function returns an unsubscribe function that you should
-call when you want to stop receiving updates. This is important for
-preventing memory leaks in your application.
-
-// ✅ Code speaks
-const unsubscribe = player.subscribe(callback);
-
-// Later, cleanup:
-unsubscribe();
-```
-
-## Code Examples
-
-### Missing Imports
-
-```markdown
-// ❌ Assumes imports exist
-const player = createPlayer({ src: 'video.mp4' });
-
-// ✅ Self-contained
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({ src: 'video.mp4' });
-```
-
-### Unrealistic Values
-
-```markdown
-// ❌ Meaningless
-const foo = createBar({ baz: 'qux' });
-
-// ✅ Realistic
-const player = createPlayer({ src: 'video.mp4' });
-```
-
-### No Output Shown
-
-```markdown
-// ❌ What does this return?
-player.state.currentTime;
-
-// ✅ Shows expected value
-player.state.currentTime;
-// => 45.2
-```
-
-### Complex Without Progression
-
-```markdown
-// ❌ Throws everything at once
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-  muted: true,
-  loop: false,
-  preload: 'metadata',
-  crossOrigin: 'anonymous',
-  poster: 'poster.jpg',
-  playbackRate: 1,
-  tracks: [
-    { kind: 'subtitles', src: 'en.vtt', label: 'English', default: true },
-  ],
-  plugins: [analyticsPlugin()],
-});
-
-// ✅ Progressive disclosure
-
-// Basic:
-const player = createPlayer({ src: 'video.mp4' });
-
-// With autoplay:
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-  muted: true, // Required for autoplay
-});
-
-// Full configuration — see [Options Reference](/api/options)
-```
-
-## State & Requests
-
-### Mutating State
-
-```markdown
-// ❌ Don't — state is readonly
-player.state.volume = 0.5;
-player.state.currentTime = 30;
-
-// ✅ Do — use requests
-await player.request.setVolume(0.5);
-await player.request.seek(30);
-```
-
-### Ignoring Async
-
-```markdown
-// ❌ Don't — ignores result
-player.request.play();
-
-// ✅ Do — handle result
-const result = await player.request.play();
-if (!result.success) {
-  console.error(result.error);
-}
-```
-
-### Sync vs Async Access
-
-```markdown
-// ❌ Don't — wrong API for reading
-const time = await player.request.getCurrentTime();
-
-// ✅ Do — state is synchronous
-const time = player.state.currentTime;
-```
-
-## Event Handling
-
-### Memory Leaks
-
-```markdown
-// ❌ Don't — no cleanup
-useEffect(() => {
-  player.on('play', handlePlay);
-}, []);
-
-// ✅ Do — cleanup on unmount
-useEffect(() => {
-  player.on('play', handlePlay);
-  return () => player.off('play', handlePlay);
-}, []);
-```
-
-### Recreating Handlers
-
-```markdown
-// ❌ Don't — new function every render
-<Player onTimeUpdate={(t) => setTime(t)} />
-
-// ✅ Do — stable reference
-const handleTimeUpdate = useCallback((t) => setTime(t), []);
-<Player onTimeUpdate={handleTimeUpdate} />
-```
-
-## Component Patterns
-
-### Inline Logic
-
-```markdown
-// ❌ Don't — logic in JSX
-<div className={player.state.playing ? 'playing' : 'paused'}>
-  {player.state.currentTime > 0 && player.state.currentTime < player.state.duration && (
-    <span>{formatTime(player.state.currentTime)}</span>
-  )}
-</div>
-
-// ✅ Do — extract logic
-const { playing, currentTime, duration } = player.state;
-const showTime = currentTime > 0 && currentTime < duration;
-
-<div className={playing ? 'playing' : 'paused'}>
-  {showTime && <span>{formatTime(currentTime)}</span>}
-</div>
-```
-
-### Missing Compound Parts
-
-```markdown
-// ❌ Don't — incomplete anatomy
-<Slider value={volume}>
-  <SliderThumb />
-</Slider>
-
-// ✅ Do — complete structure
-<Slider.Root value={volume}>
-  <Slider.Track>
-    <Slider.Range />
-  </Slider.Track>
-  <Slider.Thumb />
-</Slider.Root>
-```
-
-## Styling
-
-### Inline Styles
-
-```markdown
-// ❌ Don't — hard to maintain
-<div style={{ color: playing ? 'green' : 'red' }}>
-
-// ✅ Do — use data attributes
-<div data-playing={playing}>
-
-[data-playing="true"] { color: green; }
-[data-playing="false"] { color: red; }
-```
-
-### Magic Numbers
-
-```markdown
-// ❌ Don't — unexplained values
-.slider-thumb {
-  left: calc(50% - 8px);
-}
-
-// ✅ Do — use CSS variables
-.slider-thumb {
-  --thumb-size: 16px;
-  left: calc(var(--percent) - var(--thumb-size) / 2);
-}
-```
-
-## Documentation Structure
-
-### Wall of Text
-
-```markdown
-// ❌ Don't — overwhelming
-The player state object contains all the current values of the player
-including the current time, duration, volume, muted state, playing state,
-paused state, ended state, and many other properties that you can access
-synchronously at any time to get the current state of the player.
-
-// ✅ Do — scannable
-### State Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `currentTime` | `number` | Current playback time |
-| `duration` | `number` | Total duration |
-| `volume` | `number` | Volume (0-1) |
-| `muted` | `boolean` | Muted state |
-| `playing` | `boolean` | Playing state |
-```
-
-### Missing Context
-
-```markdown
-// ❌ Don't — where does this go?
-player.use(myPlugin);
-
-// ✅ Do — show full context
-import { createPlayer } from '@videojs/core';
-import { myPlugin } from './plugins/my-plugin';
-
-const player = createPlayer({ src: 'video.mp4' });
-player.use(myPlugin, { option: 'value' });
-```
-
-### No See Also
-
-```markdown
-// ❌ Don't — dead end
-That's how events work.
-
-// ✅ Do — guide further reading
-## See Also
-
-- [State Management](/handbook/state) — Reading player state
-- [Event Reference](/api/events) — All available events
-- [Custom Events Guide](/guides/custom-events) — Creating your own
-```
diff --git a/.claude/skills/docs/examples/tone-samples.md b/.claude/skills/docs/examples/tone-samples.md
deleted file mode 100644
index e4c7fcfc..00000000
--- a/.claude/skills/docs/examples/tone-samples.md
+++ /dev/null
@@ -1,282 +0,0 @@
-# Tone & Voice Samples
-
-Reference samples showing the target voice for Video.js documentation.
-
-## Core Voice Attributes
-
-| Attribute | Description | Example |
-|-----------|-------------|---------|
-| **Direct** | Get to the point | "Create a player:" not "To create a player..." |
-| **Confident** | No hedging | "Use requests" not "You might want to use" |
-| **Friendly** | Warm but not chatty | Technical but approachable |
-| **Code-first** | Show, don't tell | Example before explanation |
-
-## Quick Start Sample
-
-```markdown
-## Quick Start
-
-Install Video.js:
-
-npm install @videojs/core
-
-Create a player:
-
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({ src: 'video.mp4' });
-
-Attach to a video element:
-
-const video = document.querySelector('video');
-await player.attach(video);
-
-[Full getting started guide →](/guides/getting-started)
-```
-
-**Why this works:**
-- Immediate value (code in seconds)
-- No preamble or explanation
-- Action-oriented headings
-- Links to more detail
-
-## Concept Explanation Sample
-
-```markdown
-## State Management
-
-Player state is a readonly snapshot of current values.
-
-const { currentTime, volume, playing } = player.state;
-
-State updates through requests, not direct mutation:
-
-// ❌ This won't work
-player.state.volume = 0.5;
-
-// ✅ Use requests
-await player.request.setVolume(0.5);
-
-Requests are async because they coordinate with the media element.
-They return a result indicating success or failure:
-
-const result = await player.request.play();
-if (!result.success) {
-  // Handle autoplay blocked, etc.
-}
-```
-
-**Why this works:**
-- Concept in one sentence
-- Code example immediately
-- Do/don't shows contrast
-- Brief "why" explanation
-- No fluff or padding
-
-## API Reference Sample
-
-```markdown
-## createPlayer
-
-Creates a player instance.
-
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-});
-
-### Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `src` | `string` | — | Media source URL |
-| `autoplay` | `boolean` | `false` | Start playing when ready |
-| `muted` | `boolean` | `false` | Start muted |
-
-### Returns
-
-`Player` — A player instance. See [Player API](/api/player).
-
-### Example
-
-const player = createPlayer({
-  src: 'https://example.com/video.mp4',
-  autoplay: true,
-  muted: true,
-});
-
-await player.attach(document.querySelector('video'));
-```
-
-**Why this works:**
-- Function name as heading
-- One-line description
-- Immediate code example
-- Clean options table
-- Return type linked
-- Complete example
-
-## Error Documentation Sample
-
-```markdown
-## Handling Errors
-
-Players emit `error` events when something goes wrong:
-
-player.on('error', (error) => {
-  console.error(error.code, error.message);
-});
-
-### Error Codes
-
-| Code | Name | Description |
-|------|------|-------------|
-| `1` | `MEDIA_ERR_ABORTED` | Fetching aborted |
-| `2` | `MEDIA_ERR_NETWORK` | Network error |
-| `3` | `MEDIA_ERR_DECODE` | Decoding failed |
-| `4` | `MEDIA_ERR_SRC_NOT_SUPPORTED` | Source not supported |
-
-### Common Fixes
-
-**MEDIA_ERR_SRC_NOT_SUPPORTED**
-
-Check that:
-- URL is accessible (no CORS issues)
-- Format is supported by browser
-- File exists and isn't corrupted
-
-const player = createPlayer({
-  src: 'video.mp4',
-  crossOrigin: 'anonymous', // Enable CORS
-});
-```
-
-**Why this works:**
-- Shows how to catch errors first
-- Reference table for lookup
-- Actionable troubleshooting
-- Code solution included
-
-## Warning/Note Sample
-
-```markdown
-:::note
-Autoplay requires `muted: true` in most browsers due to autoplay policies.
-:::
-
-:::warning
-Calling `destroy()` removes all event listeners. Store references to
-handlers if you need to reattach them.
-:::
-
-:::tip
-Use `preload: 'metadata'` for faster initial load when autoplay is off.
-:::
-```
-
-**When to use each:**
-- **Note**: Supplementary info, not critical
-- **Warning**: Could cause problems if ignored
-- **Tip**: Optimization or best practice
-
-## Migration Sample
-
-```markdown
-## Migrating to v10
-
-### Player Creation
-
-// ❌ v9
-const player = videojs('my-video', { sources: [{ src: 'video.mp4' }] });
-
-// ✅ v10
-const player = createPlayer({ src: 'video.mp4' });
-await player.attach(document.getElementById('my-video'));
-
-### Accessing State
-
-// ❌ v9 — methods
-const time = player.currentTime();
-
-// ✅ v10 — properties
-const time = player.state.currentTime;
-
-Run the codemod to automate most changes:
-
-npx @videojs/codemod v9-to-v10
-```
-
-**Why this works:**
-- Before/after code pairs
-- Clear v9/v10 labels
-- Automated migration offered
-- Minimal explanation needed
-
-## Words to Avoid
-
-| Avoid | Use Instead |
-|-------|-------------|
-| "In order to" | "To" |
-| "Basically" | (delete) |
-| "Simply" | (delete) |
-| "Just" | (delete) |
-| "Very" | (delete) |
-| "Actually" | (delete) |
-| "You might want to" | "Use" |
-| "It should be noted that" | (delete, just say it) |
-| "Please note that" | (delete, just say it) |
-| "As you can see" | (delete) |
-| "Obviously" | (delete) |
-| "Clearly" | (delete) |
-
-## Sentence Patterns
-
-### Task-Oriented
-
-```markdown
-// ✅ Good — starts with action
-Create a player with autoplay enabled.
-Subscribe to state changes.
-Handle errors using the error event.
-
-// ❌ Avoid — passive or wordy
-A player can be created with autoplay enabled.
-You can subscribe to state changes if you want.
-Errors can be handled by using the error event.
-```
-
-### Linking Concepts
-
-```markdown
-// ✅ Good — natural link
-See [Events](/handbook/events) for the full list.
-Learn more in the [State Guide](/guides/state).
-
-// ❌ Avoid — awkward phrasing  
-For more information about events, please refer to the Events page.
-You can find additional details in the State Guide documentation.
-```
-
-## Length Guidelines
-
-| Content Type | Target Length |
-|--------------|---------------|
-| Function description | 1 sentence |
-| Concept intro | 1-2 sentences |
-| Handbook page | 300-500 words |
-| Guide section | 100-200 words |
-| Code comments | < 10 words |
-
-## Checklist
-
-When reviewing docs for tone:
-
-- [ ] No filler words (basically, simply, just)
-- [ ] Active voice throughout
-- [ ] Code appears before explanation
-- [ ] Sentences under 20 words
-- [ ] No hedging (might, could, perhaps)
-- [ ] Links are natural, not awkward
-- [ ] Headings are actions or nouns
diff --git a/.claude/skills/docs/patterns/ai-readiness.md b/.claude/skills/docs/patterns/ai-readiness.md
deleted file mode 100644
index 2ca3b5f1..00000000
--- a/.claude/skills/docs/patterns/ai-readiness.md
+++ /dev/null
@@ -1,332 +0,0 @@
-# AI/Agent Readiness Pattern
-
-How to make documentation consumable by AI assistants and coding agents.
-
-## llms.txt
-
-Provide documentation in a single, AI-optimized file.
-
-### Structure
-
-```markdown
-# Video.js 10
-
-> A framework-agnostic media player library.
-
-## Quick Start
-
-npm install @videojs/core
-
-import { createPlayer } from '@videojs/core';
-const player = createPlayer({ src: 'video.mp4' });
-
-## Core Concepts
-
-- [State Management](/docs/concepts/state.md)
-- [Requests](/docs/concepts/requests.md)
-- [Events](/docs/concepts/events.md)
-
-## API Reference
-
-- [createPlayer](/docs/api/create-player.md)
-- [Player](/docs/api/player.md)
-
-## Adapters
-
-- [React](/docs/adapters/react.md)
-- [Vue](/docs/adapters/vue.md)
-- [Svelte](/docs/adapters/svelte.md)
-```
-
-### Sizes
-
-Provide multiple versions for different context windows:
-
-| File | Size | Content |
-|------|------|---------|
-| `llms.txt` | ~10k tokens | Overview + links |
-| `llms-small.txt` | ~5k tokens | Quick ref only |
-| `llms-full.txt` | ~50k tokens | Complete docs |
-
-### URL Pattern
-
-```
-https://videojs.com/llms.txt
-https://videojs.com/llms-small.txt
-https://videojs.com/llms-full.txt
-https://videojs.com/docs/api/player.md  # Direct markdown
-```
-
-## AGENTS.md
-
-Include in package root for AI coding agents.
-
-```markdown
-# AGENTS.md
-
-## Project
-
-Video.js 10 - Framework-agnostic media player.
-
-## Structure
-
-packages/
-├── core/          # Framework-agnostic logic
-├── dom/           # Vanilla JS components
-├── react/         # React adapter
-├── vue/           # Vue adapter
-├── svelte/        # Svelte adapter
-└── solid/         # Solid adapter
-
-## Commands
-
-# Install dependencies
-pnpm install
-
-# Build all packages
-pnpm build
-
-# Run tests
-pnpm test
-
-# Lint
-pnpm lint
-
-# Type check
-pnpm typecheck
-
-## Code Style
-
-- TypeScript strict mode
-- Prefer `const` over `let`
-- Use named exports
-- Document public APIs with TSDoc
-- Test files: `*.test.ts`
-
-## Key Files
-
-- `packages/core/src/player.ts` — Main player class
-- `packages/core/src/state.ts` — State management
-- `packages/core/src/request.ts` — Request system
-
-## Testing
-
-# Run all tests
-pnpm test
-
-# Run specific package
-pnpm --filter @videojs/core test
-
-# Watch mode
-pnpm test --watch
-```
-
-## TSDoc/JSDoc
-
-Document all public exports:
-
-```ts
-/**
- * Creates a new player instance.
- *
- * @param options - Configuration options
- * @returns A new Player instance
- *
- * @example
- * ```ts
- * import { createPlayer } from '@videojs/core';
- *
- * const player = createPlayer({
- *   src: 'video.mp4',
- *   autoplay: true,
- * });
- * ```
- *
- * @remarks
- * The player must be attached to a media element before playback.
- * Use {@link Player.attach} to connect to an element.
- *
- * @see {@link PlayerOptions} for all configuration options
- * @see {@link Player} for the returned instance type
- */
-export function createPlayer(options: PlayerOptions): Player {
-  // ...
-}
-```
-
-### Required Tags
-
-| Tag | Usage |
-|-----|-------|
-| `@param` | Every parameter |
-| `@returns` | Non-void return |
-| `@example` | At least one |
-| `@throws` | If can throw |
-| `@see` | Related items |
-
-### Optional Tags
-
-| Tag | Usage |
-|-----|-------|
-| `@remarks` | Implementation details |
-| `@defaultValue` | Default values |
-| `@deprecated` | Deprecation notice |
-| `@since` | Version introduced |
-| `@beta` / `@alpha` | Stability |
-
-## Self-Contained Examples
-
-AI agents need examples that work without external context:
-
-```ts
-// ❌ Bad — requires context
-player.play();
-
-// ✅ Good — self-contained
-import { createPlayer } from '@videojs/core';
-
-const video = document.querySelector('video');
-const player = createPlayer({ src: 'video.mp4' });
-
-await player.attach(video);
-await player.play();
-```
-
-### Include All Imports
-
-```ts
-// ❌ Assumes imports exist
-const player = createPlayer(options);
-
-// ✅ Shows exactly what to import
-import { createPlayer } from '@videojs/core';
-import type { PlayerOptions } from '@videojs/core';
-
-const options: PlayerOptions = { src: 'video.mp4' };
-const player = createPlayer(options);
-```
-
-### Show Expected Output
-
-```ts
-console.log(player.state);
-// Output:
-// {
-//   currentTime: 0,
-//   duration: 120,
-//   paused: true,
-//   volume: 1,
-//   muted: false,
-// }
-```
-
-### Include Error Cases
-
-```ts
-try {
-  await player.play();
-} catch (error) {
-  // Error: NotAllowedError - Autoplay blocked by browser
-}
-```
-
-## Markdown Export
-
-Every documentation page should be available as raw markdown:
-
-```markdown
-## Viewing as Markdown
-
-This page is available in markdown format:
-[View as Markdown](/docs/api/player.md)
-```
-
-Or automatic via URL suffix:
-
-```
-/docs/api/player       → HTML page
-/docs/api/player.md    → Raw markdown
-```
-
-## Context Window Optimization
-
-Write docs that work within token limits:
-
-### Chunk by Concept
-
-```markdown
-<!-- Good: One concept per section -->
-## State
-
-The player state is a readonly object...
-
-## Requests
-
-Requests are used to change state...
-```
-
-### Avoid Redundancy
-
-```markdown
-<!-- Bad: Repeats information -->
-The `play()` method plays the video. When you call `play()`,
-the video will start playing.
-
-<!-- Good: Concise -->
-`play()` starts playback.
-```
-
-### Front-Load Important Info
-
-```markdown
-<!-- Good: Key info first -->
-## createPlayer
-
-Creates a player instance. Returns `Player`.
-
-const player = createPlayer({ src: 'video.mp4' });
-
-### Options
-...
-```
-
-## MCP Server
-
-For advanced integration, provide an MCP server:
-
-```json
-{
-  "name": "videojs-docs",
-  "version": "1.0.0",
-  "tools": [
-    {
-      "name": "search_docs",
-      "description": "Search Video.js documentation",
-      "parameters": {
-        "query": { "type": "string" }
-      }
-    },
-    {
-      "name": "get_api",
-      "description": "Get API reference for a symbol",
-      "parameters": {
-        "symbol": { "type": "string" }
-      }
-    }
-  ]
-}
-```
-
-## Testing AI Readability
-
-Checklist for AI-friendly docs:
-
-- [ ] llms.txt at docs root
-- [ ] AGENTS.md in package root
-- [ ] All exports have TSDoc
-- [ ] Examples include imports
-- [ ] Examples are runnable
-- [ ] Pages available as markdown
-- [ ] No broken internal links
-- [ ] Code blocks have language tags
-- [ ] Types are documented or inferrable
diff --git a/.claude/skills/docs/patterns/code-examples.md b/.claude/skills/docs/patterns/code-examples.md
index d51c748d..37b63dee 100644
--- a/.claude/skills/docs/patterns/code-examples.md
+++ b/.claude/skills/docs/patterns/code-examples.md
@@ -1,6 +1,6 @@
 # Code Examples Pattern
 
-How to write effective code examples for documentation.
+How to write effective code examples across documentation — site pages, READMEs, and JSDoc.
 
 ## Core Principles
 
@@ -15,16 +15,28 @@ How to write effective code examples for documentation.
 ```tsx
 // ❌ Missing imports — won't work when copied
 function App() {
-  const player = usePlayer();
-  return <Player src="video.mp4" />;
+  return (
+    <Player.Container>
+      <Video src="video.mp4" />
+      <PlayButton />
+    </Player.Container>
+  );
 }
 
 // ✅ Complete — copy, paste, run
-import { Player, usePlayer } from '@videojs/react';
+import { createPlayer, features, PlayButton, Video } from '@videojs/react';
+
+const Player = createPlayer({ features: [...features.video] });
 
 function App() {
-  const player = usePlayer();
-  return <Player src="video.mp4" />;
+  return (
+    <Player.Provider>
+      <Player.Container>
+        <Video src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4" />
+        <PlayButton />
+      </Player.Container>
+    </Player.Provider>
+  );
 }
 ```
 
@@ -34,310 +46,254 @@ function App() {
 
 ```ts
 // ✅ Let inference work — cleaner
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-});
-// player is inferred as Player
+const store = createStore<HTMLMediaElement>()(volumeSlice);
 
 // ❌ Redundant annotation
-const player: Player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-});
+const store: Store<HTMLMediaElement, VolumeState> = createStore<HTMLMediaElement>()(volumeSlice);
 ```
 
 ### Annotate When Helpful
 
 ```ts
 // ✅ Annotation clarifies complex return
-function usePlayerState(): {
-  state: PlayerState;
-  request: RequestAPI;
-} {
-  // ...
-}
+import type { InferSliceState } from '@videojs/store';
 
-// ✅ Annotation shows expected shape
-const options: PlayerOptions = {
-  src: 'video.mp4',
-  tracks: [
-    { kind: 'subtitles', src: 'en.vtt', label: 'English' },
-  ],
-};
+type VolumeState = InferSliceState<typeof volumeSlice>;
+// { volume: number; muted: boolean; setVolume: ...; toggleMute: ... }
 ```
 
 ### Show Type Imports
 
 ```ts
-// ✅ Show type imports for complex types
-import type { PlayerOptions, TextTrack } from '@videojs/core';
-
-const tracks: TextTrack[] = [
-  { kind: 'subtitles', src: 'en.vtt', label: 'English' },
-];
+// ✅ Separate type imports
+import { createStore, defineSlice } from '@videojs/store';
+import type { InferStoreState } from '@videojs/store';
 ```
 
-## Framework Tabs
+## Framework-Specific Code
 
-Use tabs for multi-framework examples:
+Site pages use `<FrameworkCase>` and `<StyleCase>` to show code per framework. Never use generic `<Tabs>` for framework switching.
+
+**React:**
 
-````markdown
-<Tabs>
-<Tab label="React">
 ```tsx
-import { Player } from '@videojs/react';
+import { createPlayer, features, PlayButton, Video } from '@videojs/react';
 
-function App() {
-  return <Player src="video.mp4" />;
+const Player = createPlayer({ features: [...features.video] });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="player">
+        <Video
+          src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+        />
+        <PlayButton
+          render={(props, state) => (
+            <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
 }
 ```
-</Tab>
-<Tab label="Vue">
-```vue
-<script setup>
-import { Player } from '@videojs/vue';
-</script>
 
-<template>
-  <Player src="video.mp4" />
-</template>
-```
-</Tab>
-<Tab label="Svelte">
-```svelte
-<script>
-  import { Player } from '@videojs/svelte';
-</script>
+**HTML:**
 
-<Player src="video.mp4" />
+```html
+<video-player class="player">
+  <video
+    src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
+    autoplay
+    muted
+    playsinline
+  ></video>
+  <media-play-button>
+    <span class="show-when-paused">Play</span>
+    <span class="show-when-playing">Pause</span>
+  </media-play-button>
+</video-player>
 ```
-</Tab>
-<Tab label="Vanilla">
-```ts
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({
-  target: document.getElementById('player'),
-  src: 'video.mp4',
-});
-```
-</Tab>
-</Tabs>
-````
 
 ## Progressive Examples
 
-Start simple, add complexity:
+Start simple, add complexity in later sections:
 
 ```markdown
 ## Basic Usage
 
-const player = createPlayer({ src: 'video.mp4' });
-
-## With Options
-
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-  muted: true,
+const volumeSlice = defineSlice<HTMLMediaElement>()({
+  state: () => ({ volume: 1 }),
+  attach: ({ target, set, signal }) => {
+    const sync = () => set({ volume: target.volume });
+    target.addEventListener('volumechange', sync, { signal });
+  },
 });
 
-## With Event Handling
+## With Actions
 
-const player = createPlayer({
-  src: 'video.mp4',
-  onPlay: () => console.log('Playing'),
-  onError: (e) => console.error(e),
+const volumeSlice = defineSlice<HTMLMediaElement>()({
+  state: ({ target }) => ({
+    volume: 1,
+    setVolume(value: number) {
+      target().volume = Math.max(0, Math.min(1, value));
+    },
+  }),
+  attach: ({ target, set, signal }) => {
+    const sync = () => set({ volume: target.volume });
+    sync();
+    target.addEventListener('volumechange', sync, { signal });
+  },
 });
 
-## Full Configuration
+## Combining Slices
 
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-  muted: true,
-  loop: false,
-  preload: 'metadata',
-  tracks: [
-    { kind: 'subtitles', src: 'en.vtt', label: 'English', default: true },
-  ],
-  onPlay: () => analytics.track('video_play'),
-  onError: (e) => errorReporter.capture(e),
-});
+const mediaSlice = combine(volumeSlice, playbackSlice);
+const store = createStore<HTMLMediaElement>()(mediaSlice);
 ```
 
-## Highlight Key Lines
+## Do/Don't Contrasts
 
-Use comments to draw attention:
+Use `// ❌ Don't` / `// ✅ Do` pairs. Always explain *why* the wrong way is wrong:
 
 ```ts
-const player = createPlayer({
-  src: 'video.mp4',
-  // highlight-next-line
-  autoplay: true, // ← Starts playing automatically
-});
+// ❌ Don't — creates new Set on every render
+const trackedRef = useRef(new Set<string>());
+
+// ✅ Do — initializer only runs once
+const [tracked] = useState(() => new Set<string>());
 ```
 
-Or diff-style:
-
 ```ts
-const player = createPlayer({
-  src: 'video.mp4',
-- autoplay: false,
-+ autoplay: true,
-});
+// ❌ Don't — redundant type annotation
+const value = someFunction() as SomeType;
+
+// ✅ Do — let inference work
+const value = someFunction();
 ```
 
 ## Show Output
 
-Include expected output as comments:
+Include expected output as comments when the result isn't obvious:
 
 ```ts
-console.log(player.state.currentTime);
-// => 0
+import type { InferSliceState } from '@videojs/store';
 
-await player.request.seek(30);
-console.log(player.state.currentTime);
-// => 30
+type VolumeState = InferSliceState<typeof volumeSlice>;
+// { volume: number; setVolume: (value: number) => void }
+
+const store = createStore<HTMLMediaElement>()(volumeSlice);
+store.attach(videoElement);
+
+const { volume } = store;
+// volume: 1
 ```
 
 ## Error Examples
 
-Show what errors look like:
+Show what errors look like and how to handle them:
 
 ```ts
-// This will throw:
-player.play();
-// => Error: Player not attached to media element
+import { isStoreError } from '@videojs/store';
 
-// Do this instead:
-await player.attach(videoElement);
-player.play();
-```
-
-## Interactive Examples
-
-Link to StackBlitz/CodeSandbox:
-
-```markdown
-```tsx
-import { Player } from '@videojs/react';
-
-function App() {
-  return <Player src="video.mp4" />;
+try {
+  await store.play();
+} catch (error) {
+  if (isStoreError(error)) {
+    switch (error.code) {
+      case 'NO_TARGET':
+        // No media element attached
+        break;
+      case 'DESTROYED':
+        // Store was destroyed
+        break;
+    }
+  }
 }
 ```
 
-[Open in StackBlitz →](https://stackblitz.com/edit/videojs-react-basic)
-```
-
-## Copy Buttons
-
-All code blocks should have copy functionality. In MDX:
-
-```mdx
-<CodeBlock copy>
-const player = createPlayer({ src: 'video.mp4' });
-</CodeBlock>
-```
-
 ## Filename Headers
 
-Show which file the code belongs to:
+Show which file code belongs to when multiple files are involved:
 
 ````markdown
 ```tsx title="App.tsx"
-import { Player } from '@videojs/react';
+import { createPlayer, features, PlayButton, Video } from '@videojs/react';
+import './App.css';
 
-export function App() {
-  return <Player src="video.mp4" />;
+const Player = createPlayer({ features: [...features.video] });
+
+export default function App() {
+  return (
+    <Player.Provider>
+      <Player.Container className="player">
+        <Video src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4" />
+        <PlayButton />
+      </Player.Container>
+    </Player.Provider>
+  );
 }
 ```
 
-```css title="player.css"
+```css title="App.css"
 .player {
   --player-accent-color: #3b82f6;
 }
 ```
 ````
 
-## Do/Don't Examples
-
-Show contrast:
-
-```markdown
-### Event Handling
-
-// ❌ Don't — inline handlers get recreated
-<Player
-  onTimeUpdate={(t) => setTime(t)}
-/>
-
-// ✅ Do — stable callback reference
-const handleTimeUpdate = useCallback((t) => setTime(t), []);
-<Player onTimeUpdate={handleTimeUpdate} />
-```
-
 ## Realistic Values
 
 ```ts
 // ❌ Meaningless
-const foo = createBar({ baz: 'qux' });
+const slice = defineSlice<Foo>()({
+  state: () => ({ bar: 'baz' }),
+});
 
 // ✅ Realistic
-const player = createPlayer({
-  src: 'https://example.com/video.mp4',
-  poster: 'https://example.com/poster.jpg',
+const volumeSlice = defineSlice<HTMLMediaElement>()({
+  state: () => ({ volume: 1, muted: false }),
+  attach: ({ target, set, signal }) => {
+    const sync = () => set({ volume: target.volume, muted: target.muted });
+    sync();
+    target.addEventListener('volumechange', sync, { signal });
+  },
 });
 ```
 
 ## Console Examples
 
-For CLI documentation:
+For installation and CLI:
 
 ```bash
 # Install the package
-npm install @videojs/core
+npm install @videojs/store
 
 # Or with other package managers
-pnpm add @videojs/core
-yarn add @videojs/core
+pnpm add @videojs/store
 ```
 
-## API Response Examples
+## Demo Files (Site Pages)
 
-For async operations:
+Live demos in reference pages use the `<Demo>` component with `?raw` imports for source code display. See the `api-reference` skill for full patterns.
 
-```ts
-const result = await player.request.play();
-// => { success: true, state: 'playing' }
+```mdx
+import BasicUsageDemo from "@/components/docs/demos/play-button/react/css/BasicUsage";
+import basicUsageTsx from "@/components/docs/demos/play-button/react/css/BasicUsage.tsx?raw";
+import basicUsageCss from "@/components/docs/demos/play-button/react/css/BasicUsage.css?raw";
 
-const error = await player.request.play();
-// => { success: false, error: { code: 'NOT_ALLOWED', message: '...' } }
-```
-
-## Configuration Comparison
-
-Show equivalent configs:
-
-```markdown
-### JavaScript
-
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-});
-
-### HTML Data Attributes
-
-<video
-  data-player
-  data-src="video.mp4"
-  data-autoplay
-></video>
-
-### React Props
-
-<Player src="video.mp4" autoplay />
+<FrameworkCase frameworks={["react"]}>
+  <StyleCase styles={["css"]}>
+    <Demo files={[
+      { title: "App.tsx", code: basicUsageTsx, lang: "tsx" },
+      { title: "App.css", code: basicUsageCss, lang: "css" },
+    ]}>
+      <BasicUsageDemo client:idle />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
 ```
diff --git a/.claude/skills/docs/patterns/progressive-disclosure.md b/.claude/skills/docs/patterns/progressive-disclosure.md
deleted file mode 100644
index 86e1b474..00000000
--- a/.claude/skills/docs/patterns/progressive-disclosure.md
+++ /dev/null
@@ -1,303 +0,0 @@
-# Progressive Disclosure Pattern
-
-How to layer information for different audiences.
-
-## Four-Tier Information Hierarchy
-
-| Tier | Purpose | Audience | Length |
-|------|---------|----------|--------|
-| **Quick Start** | First success in <5 min | Everyone | 1 page |
-| **Concepts** | Mental models | Learning | 2-5 pages |
-| **Guides** | Task completion | Building | Per-task |
-| **API Reference** | Complete spec | Referencing | Comprehensive |
-
-## Quick Start Pattern
-
-Goal: Working code in under 5 minutes.
-
-```markdown
-## Quick Start
-
-### Install
-
-npm install @videojs/react
-
-### Use
-
-import { Player } from '@videojs/react';
-
-function App() {
-  return <Player src="video.mp4" />;
-}
-
-That's it. [See the full guide →](/guides/getting-started)
-```
-
-**Rules:**
-- Max 3 code blocks
-- No configuration options
-- No edge cases
-- Link to "full guide" for more
-
-## Expandable Sections
-
-Use `<details>` for optional depth:
-
-```markdown
-## Configuration
-
-const player = createPlayer({ src: 'video.mp4' });
-
-<details>
-<summary>All configuration options</summary>
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `src` | `string` | — | Source URL |
-| `autoplay` | `boolean` | `false` | Auto-start |
-| `muted` | `boolean` | `false` | Start muted |
-| ... | ... | ... | ... |
-
-</details>
-```
-
-## Tabbed Complexity
-
-Simple → Advanced in tabs:
-
-```markdown
-## Creating a Player
-
-<Tabs>
-<Tab label="Basic">
-const player = createPlayer({ src: 'video.mp4' });
-</Tab>
-<Tab label="With Options">
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-  muted: true,
-  tracks: [{ kind: 'subtitles', src: 'en.vtt' }],
-});
-</Tab>
-<Tab label="Full Control">
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-  muted: true,
-  loop: false,
-  preload: 'metadata',
-  crossOrigin: 'anonymous',
-  tracks: [
-    { kind: 'subtitles', src: 'en.vtt', label: 'English', default: true },
-    { kind: 'subtitles', src: 'es.vtt', label: 'Español' },
-  ],
-  plugins: [analyticsPlugin(), adsPlugin()],
-  onPlay: () => console.log('play'),
-  onError: (e) => console.error(e),
-});
-</Tab>
-</Tabs>
-```
-
-## "See Also" Sections
-
-End every page with related content:
-
-```markdown
-## See Also
-
-- [Events Guide](/guides/events) — Listen to player events
-- [Styling Guide](/guides/styling) — Customize appearance
-- [API Reference](/api/player) — Full Player API
-```
-
-## Callout Boxes
-
-For important asides without breaking flow:
-
-```markdown
-:::note
-The player must be attached before calling `play()`.
-:::
-
-:::warning
-`autoplay` requires `muted` in most browsers.
-:::
-
-:::tip
-Use `preload="metadata"` for faster initial load.
-:::
-```
-
-## Inline Links
-
-Link concepts on first mention:
-
-```markdown
-Create a [player](/api/player) and attach it to a 
-[media element](/concepts/media-elements). The player uses
-[requests](/concepts/requests) to coordinate state changes.
-```
-
-## Layered Examples
-
-Same feature, increasing detail:
-
-```markdown
-## Playing Media
-
-### Basic
-
-player.play();
-
-### With Error Handling
-
-try {
-  await player.play();
-} catch (error) {
-  if (error.name === 'NotAllowedError') {
-    // Autoplay blocked, show play button
-  }
-}
-
-### With Request API
-
-const result = await player.request.play();
-
-if (!result.success) {
-  switch (result.error.code) {
-    case 'NOT_ALLOWED':
-      // Show play button
-      break;
-    case 'NOT_SUPPORTED':
-      // Show format error
-      break;
-  }
-}
-```
-
-## Feature Flags
-
-Document experimental features separately:
-
-```markdown
-## Experimental Features
-
-:::warning
-These features may change or be removed.
-:::
-
-### Picture-in-Picture
-
-Enable with the `experimentalPiP` flag:
-
-const player = createPlayer({
-  src: 'video.mp4',
-  experimentalPiP: true,
-});
-```
-
-## Version-Specific Content
-
-Show version differences:
-
-```markdown
-## Migration from v9
-
-<Tabs>
-<Tab label="v9 (Old)">
-videojs('player', { sources: [{ src: 'video.mp4' }] });
-</Tab>
-<Tab label="v10 (New)">
-createPlayer({ src: 'video.mp4' });
-</Tab>
-</Tabs>
-
-### What Changed
-
-| v9 | v10 |
-|----|-----|
-| `videojs()` function | `createPlayer()` |
-| `sources` array | `src` string |
-| jQuery-style API | Modern async API |
-```
-
-## Audience Markers
-
-Signal who content is for:
-
-```markdown
-## Advanced: Custom Tech
-
-> This section is for library authors building custom playback engines.
-
-A Tech is the abstraction layer between the player and the media element...
-```
-
-## Prerequisites
-
-State requirements upfront:
-
-```markdown
-## Building Plugins
-
-### Prerequisites
-
-- Familiarity with the [Player API](/api/player)
-- Understanding of [Events](/concepts/events)
-- Node.js 18+
-
-### Before You Start
-
-Complete the [Getting Started](/guides/getting-started) guide first.
-```
-
-## Summary Boxes
-
-TL;DR for skimmers:
-
-```markdown
-## State Management
-
-:::summary
-- State is readonly — use requests to change it
-- Requests are async and can fail
-- Subscribe to state changes with `subscribe()`
-:::
-
-The player uses a unidirectional data flow...
-```
-
-## Code Annotations
-
-Explain complex code inline:
-
-```ts
-const player = createPlayer({
-  src: 'video.mp4',
-  // 1. Autoplay requires muted in most browsers
-  autoplay: true,
-  muted: true,
-  // 2. Preload metadata for faster start
-  preload: 'metadata',
-  // 3. Enable CORS for cross-origin sources
-  crossOrigin: 'anonymous',
-});
-```
-
-## Skip Links
-
-Let users jump to what they need:
-
-```markdown
-## Player Configuration
-
-**Jump to:** [Basic](#basic) | [Sources](#sources) | [Tracks](#tracks) | [Events](#events) | [Plugins](#plugins)
-
-### Basic
-...
-
-### Sources
-...
-```
diff --git a/.claude/skills/docs/patterns/props-tables.md b/.claude/skills/docs/patterns/props-tables.md
deleted file mode 100644
index 5d5aa61d..00000000
--- a/.claude/skills/docs/patterns/props-tables.md
+++ /dev/null
@@ -1,255 +0,0 @@
-# Props Tables Pattern
-
-Consistent formats for documenting props, data attributes, CSS variables, and events.
-
-## Props Table Format
-
-```markdown
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `src` | `string` | — | Media source URL |
-| `autoplay` | `boolean` | `false` | Start playing automatically |
-| `muted` | `boolean` | `false` | Start muted |
-| `loop` | `boolean` | `false` | Loop playback |
-| `controls` | `boolean` | `true` | Show default controls |
-| `onPlay` | `() => void` | — | Called when playback starts |
-```
-
-### Conventions
-
-**Required props:** No default, use `—` or mark with `*`
-
-```markdown
-| `src`* | `string` | — | Media source URL (required) |
-```
-
-**Optional props:** Always show default
-
-```markdown
-| `volume` | `number` | `1` | Initial volume (0-1) |
-```
-
-**Callback props:** `on` prefix, show signature
-
-```markdown
-| `onTimeUpdate` | `(time: number) => void` | — | Called on time change |
-```
-
-**Enum props:** Show all options
-
-```markdown
-| `preload` | `'auto' \| 'metadata' \| 'none'` | `'metadata'` | Preload behavior |
-```
-
-**Complex types:** Link to type definition
-
-```markdown
-| `tracks` | [`TextTrack[]`](#texttrack) | `[]` | Text tracks (captions, subtitles) |
-```
-
-## Data Attributes Table Format
-
-```markdown
-| Attribute | Values | Description |
-|-----------|--------|-------------|
-| `data-state` | `'idle' \| 'loading' \| 'ready' \| 'error'` | Current player state |
-| `data-playing` | `''` | Present during playback |
-| `data-paused` | `''` | Present when paused |
-| `data-muted` | `''` | Present when muted |
-| `data-fullscreen` | `''` | Present in fullscreen |
-| `data-orientation` | `'horizontal' \| 'vertical'` | Slider orientation |
-```
-
-### Boolean Attributes
-
-For boolean state, document presence/absence:
-
-```markdown
-| `data-playing` | Present when playing, absent when not |
-```
-
-### State Attributes
-
-For state machines, show all values:
-
-```markdown
-| `data-state` | `'idle'` | Initial state |
-| | `'loading'` | Loading media |
-| | `'ready'` | Ready to play |
-| | `'playing'` | Currently playing |
-| | `'paused'` | Paused |
-| | `'ended'` | Playback ended |
-| | `'error'` | Error occurred |
-```
-
-### Usage Examples
-
-Always follow with CSS example:
-
-```css
-/* Style based on state */
-.player[data-loading] {
-  opacity: 0.5;
-}
-
-.player[data-playing] .play-icon {
-  display: none;
-}
-
-.player[data-paused] .pause-icon {
-  display: none;
-}
-```
-
-## CSS Variables Table Format
-
-```markdown
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--player-accent-color` | `#3b82f6` | Primary accent color |
-| `--player-bg` | `#000` | Background color |
-| `--player-controls-bg` | `rgba(0,0,0,0.7)` | Controls background |
-| `--player-slider-height` | `4px` | Slider track height |
-| `--player-thumb-size` | `12px` | Slider thumb size |
-```
-
-### With Scoping
-
-Document which component owns the variable:
-
-```markdown
-### Player Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--player-bg` | `#000` | Player background |
-
-### Slider Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--slider-height` | `4px` | Track height |
-```
-
-### Usage Examples
-
-```css
-/* Customize theme */
-.player {
-  --player-accent-color: #ef4444;
-  --player-bg: #1a1a1a;
-}
-
-/* Dynamic sizing */
-.slider {
-  --slider-height: 8px;
-}
-```
-
-## Events Table Format
-
-```markdown
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `play` | `void` | Playback started |
-| `pause` | `void` | Playback paused |
-| `ended` | `void` | Playback ended |
-| `timeupdate` | `{ currentTime: number }` | Current time changed |
-| `volumechange` | `{ volume: number, muted: boolean }` | Volume or muted changed |
-| `error` | `{ code: number, message: string }` | Error occurred |
-| `statechange` | `{ state: PlayerState }` | Any state changed |
-```
-
-### Event Payload Types
-
-Link to type definitions:
-
-```markdown
-| `error` | [`PlayerError`](#playererror) | Error occurred |
-```
-
-### Event Examples
-
-```ts
-player.on('timeupdate', ({ currentTime }) => {
-  console.log(`Time: ${currentTime}s`);
-});
-
-player.on('error', ({ code, message }) => {
-  console.error(`Error ${code}: ${message}`);
-});
-```
-
-## Methods Table Format
-
-```markdown
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `play()` | `() => Promise<void>` | Start playback |
-| `pause()` | `() => void` | Pause playback |
-| `seek()` | `(time: number) => void` | Seek to time |
-| `setVolume()` | `(volume: number) => void` | Set volume (0-1) |
-| `destroy()` | `() => void` | Cleanup player |
-```
-
-## Returns Table Format
-
-For functions/hooks:
-
-```markdown
-| Property | Type | Description |
-|----------|------|-------------|
-| `state` | `PlayerState` | Current state (readonly) |
-| `request` | `RequestAPI` | Methods to request changes |
-| `subscribe` | `(cb: Callback) => Unsubscribe` | Subscribe to updates |
-| `destroy` | `() => void` | Cleanup |
-```
-
-## Expandable Types
-
-For complex types, use collapsible details:
-
-```markdown
-| `options` | [`PlayerOptions`](#playeroptions) | Configuration |
-
-<details>
-<summary>PlayerOptions</summary>
-
-| Property | Type | Default |
-|----------|------|---------|
-| `src` | `string` | — |
-| `autoplay` | `boolean` | `false` |
-| `muted` | `boolean` | `false` |
-
-</details>
-```
-
-## Framework Variations
-
-### React Props
-
-```markdown
-| Prop | Type | Default |
-|------|------|---------|
-| `ref` | `React.Ref<PlayerRef>` | — |
-| `children` | `React.ReactNode` | — |
-| `className` | `string \| (state) => string` | — |
-```
-
-### Vue Props
-
-```markdown
-| Prop | Type | Default |
-|------|------|---------|
-| `modelValue` | `number` | — |
-| `@update:modelValue` | `(value: number) => void` | — |
-```
-
-### Svelte Props
-
-```markdown
-| Prop | Type | Default |
-|------|------|---------|
-| `bind:value` | `number` | — |
-| `$bindable` | ✓ | Can be bound |
-```
diff --git a/.claude/skills/docs/references/component-libraries.md b/.claude/skills/docs/references/component-libraries.md
index 199fab7d..05c6726d 100644
--- a/.claude/skills/docs/references/component-libraries.md
+++ b/.claude/skills/docs/references/component-libraries.md
@@ -24,7 +24,7 @@ Show component composition clearly:
 
 ```tsx
 // ✅ Clear anatomy
-import { Slider } from '@videojs/dom';
+import { Slider } from "@videojs/dom";
 
 <Slider.Root>
   <Slider.Track>
@@ -104,7 +104,7 @@ Document theming hooks:
 Document programmatic access:
 
 ```tsx
-import { Slider, useSliderContext } from '@videojs/dom';
+import { Slider, useSliderContext } from "@videojs/dom";
 
 function CustomThumb() {
   const slider = useSliderContext();
@@ -126,7 +126,7 @@ Document both high-level components and low-level hooks:
 ### Component API
 
 ```tsx
-import { Slider } from '@videojs/react';
+import { Slider } from "@videojs/react";
 
 <Slider defaultValue={50} />;
 ```
@@ -134,7 +134,7 @@ import { Slider } from '@videojs/react';
 ### Hook API
 
 ```tsx
-import { useSlider } from '@videojs/react';
+import { useSlider } from "@videojs/react";
 
 function CustomSlider() {
   const { rootProps, trackProps, thumbProps, state } = useSlider({
@@ -243,7 +243,12 @@ Show real-world compositions:
 
 ---
 
+## Applicable to Video.js
+
+The patterns above are drawn from many libraries. Not all apply to Video.js reference pages. Where existing patterns contradict the patterns outlined here, follow the existing patterns.
+
+---
+
 ## See Also
 
 - [Component Patterns](../../component/SKILL.md) — building headless components
-- [Multi-Framework Docs](multi-framework.md) — documenting across frameworks
diff --git a/.claude/skills/docs/references/multi-framework.md b/.claude/skills/docs/references/multi-framework.md
deleted file mode 100644
index c254c5d4..00000000
--- a/.claude/skills/docs/references/multi-framework.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Multi-Framework Documentation Patterns
-
-> **TODO:** Patterns for documenting multi-framework libraries not yet established.
-> This file will be expanded when Video.js adds Vue, Svelte, or Solid adapters.
-
-## Current Framework Support
-
-| Framework          | Package                 | Status    |
-| ------------------ | ----------------------- | --------- |
-| Vanilla/HTML       | `@videojs/html`         | Available |
-| React              | `@videojs/react`        | Available |
-| React Native       | `@videojs/react-native` | Available |
-
-## Placeholder Topics
-
-When multi-framework docs are needed, cover:
-
-- Framework selector UI (persisted choice)
-- Tabbed code examples
-- Framework-native idioms
-- API naming conventions per framework
-- TypeScript across frameworks
-- Migration guides between frameworks
-
-## References
-
-- [TanStack Query Docs](https://tanstack.com/query) — Multi-framework documentation example
-- [Ark UI Docs](https://ark-ui.com/) — Framework tabs pattern
diff --git a/.claude/skills/docs/references/state-tooling.md b/.claude/skills/docs/references/state-tooling.md
index 961c100d..b033e715 100644
--- a/.claude/skills/docs/references/state-tooling.md
+++ b/.claude/skills/docs/references/state-tooling.md
@@ -356,5 +356,4 @@ player.emit('custom:event', { data: 'value' });
 
 ## See Also
 
-- [State Patterns](../../dx/references/state-patterns.md) — state management patterns
-- [Multi-Framework Docs](multi-framework.md) — documenting across frameworks
+- [State Patterns](../../api/references/state.md) — state management patterns
diff --git a/.claude/skills/docs/references/writing-style.md b/.claude/skills/docs/references/writing-style.md
new file mode 100644
index 00000000..dc891e5a
--- /dev/null
+++ b/.claude/skills/docs/references/writing-style.md
@@ -0,0 +1,149 @@
+# Writing Style
+
+Full writing style guidelines for Video.js documentation.
+
+## Voice
+
+Direct. Confident. Friendly but not chatty. Write like you are talking to a peer — helpful, not formal or distant.
+
+```markdown
+// ❌ Wordy
+In order to create a new player instance, you'll need to call the
+createPlayer function and pass in a configuration object.
+
+// ✅ Direct
+Create a player:
+
+const player = createPlayer({ src: 'video.mp4' });
+```
+
+## Quick Rules
+
+- **Sentence case for headings** — capitalize only the first word and proper nouns (e.g., "Choose your JS framework", not "Choose Your JS Framework")
+- Active voice, second person ("you")
+- Short sentences
+- No filler ("In order to", "basically", "simply")
+- No hedging ("might", "could", "perhaps")
+- Code does the heavy lifting
+
+## Guidelines
+
+### Be human
+
+Write like you are talking to a peer. Friendly and helpful, not formal or distant. Read your writing out loud — if it sounds awkward, rewrite it.
+
+### Use simple words
+
+> "Don't use a five-dollar word when a fifty-cent word will do." — Mark Twain
+
+Simplify hard concepts into something easy to understand. If a piece of jargon is unavoidable, define it on first use.
+
+### Cut to the point
+
+Do not lean on flowery language. Simple and to the point is almost always an improvement. Every sentence should earn its place — delete ruthlessly.
+
+### Speak directly to the reader
+
+Use second person ("you") for the reader and first person plural ("we") for the project team. Do not talk about the reader in the third person.
+
+> **We** build the player so **you** don't have to.
+
+### Tell a story
+
+Do not just check boxes. Tell the reader a coherent story — they should be able to imagine themselves solving whatever problem you are describing.
+
+### Bias for words over symbols
+
+Spell out words rather than use symbols. Use "and" rather than "&". Exceptions: space-constrained contexts or deliberate stylistic choices.
+
+### Gender-neutral language
+
+Speak directly to the reader with "you." If a pronoun is needed, use "they" or "their" instead of "his" or "her." Avoid gendered group terms.
+
+### Headings: avoid gerunds
+
+Prefer "Write good headings" over "Writing good headings." Gerunds create ambiguity — "Meeting requirements" could mean "how to meet requirements" or "the requirements for this meeting."
+
+### Oxford comma
+
+Always use the serial comma when writing a list of three or more things.
+
+### Collaborative pronouns
+
+Use "we," "us," and "our" when talking about the project, team, or things we are working on.
+
+### Be precise, not vague
+
+Make claims as strong as possible without becoming false. Vague qualifications ("somewhat," "fairly") weaken writing. If a statement is true, say it directly.
+
+### Simplicity reveals mistakes
+
+Simple writing exposes unclear thinking. If you cannot explain something simply, you may not understand it well enough yet. Complexity should come from the ideas, not the language.
+
+## Words to avoid
+
+| Avoid | Use instead |
+|-------|-------------|
+| "In order to" | "To" |
+| "Basically" | (delete) |
+| "Simply" | (delete) |
+| "Just" | (delete) |
+| "Very" | (delete) |
+| "Actually" | (delete) |
+| "You might want to" | "Use" |
+| "It should be noted that" | (delete, say it directly) |
+| "Please note that" | (delete, say it directly) |
+| "As you can see" | (delete) |
+| "Obviously" / "Clearly" | (delete) |
+
+## Sentence patterns
+
+### Task-oriented (preferred)
+
+```markdown
+Create a player with autoplay enabled.
+Subscribe to state changes.
+Handle errors using the error event.
+```
+
+### Avoid passive or wordy
+
+```markdown
+// ❌ Passive
+A player can be created with autoplay enabled.
+
+// ❌ Wordy
+You can subscribe to state changes if you want.
+
+// ❌ Over-explaining
+The subscribe function returns an unsubscribe function
+that you should call when you want to stop receiving
+updates. This is important for preventing memory leaks
+in your application.
+
+// ✅ Code speaks
+const unsubscribe = store.subscribe(callback);
+
+// Later, cleanup:
+unsubscribe();
+```
+
+### Linking concepts
+
+```markdown
+// ✅ Natural
+See [Events](/concepts/events) for the full list.
+
+// ❌ Awkward
+For more information about events, please refer to the Events page.
+```
+
+## Length guidelines
+
+| Content type | Target |
+|---|---|
+| Function description | 1 sentence |
+| Concept intro | 1-2 sentences |
+| Concept page | 300-500 words |
+| How-to step section | 100-200 words |
+| Code comments | < 10 words |
diff --git a/.claude/skills/docs/review/agents.md b/.claude/skills/docs/review/agents.md
index a5d99b44..c39fbc4e 100644
--- a/.claude/skills/docs/review/agents.md
+++ b/.claude/skills/docs/review/agents.md
@@ -1,145 +1,120 @@
 # Agent Prompts
 
-Prompts for each review sub-agent.
+Prompts for parallel documentation review agents.
 
-## Coordinator Agent
+## Coordinator
 
+```
 You are the coordinator. Your job:
-
-1. Read the documentation file(s) to review
-2. Spawn 4 sub-agents with Task tool, each reviewing one dimension
+1. Read the documentation to review
+2. Spawn 3 sub-agents with Task tool
 3. Collect their reports
-4. Merge into final review using the template in `references/merge-template.md`
+4. Merge into final review
 
-Use this task structure:
+Tasks:
+- Task 1: Voice Review
+- Task 2: Structure Review
+- Task 3: Code Review
 
-```
-Task 1: Tone Review
-Task 2: Structure Review  
-Task 3: Code Review
-Task 4: AI Readiness Review
+Wait for all tasks, then synthesize using templates.md format.
 ```
 
-Wait for all tasks, then synthesize.
+---
 
-## Tone Review Agent
+## Sub-Agent: Voice Review
 
 ```
-You are reviewing documentation for tone and voice.
+You are reviewing documentation for writing quality and voice consistency.
 
-Load references:
-- docs/examples/tone-samples.md
-- docs/examples/good-bad.md
+Load: docs/references/writing-style.md
 
 Review for:
-1. Directness — No filler words (basically, simply, just, in order to)
-2. Confidence — No hedging (might, could, perhaps)
-3. Active voice — Not passive constructions
-4. Conciseness — Every sentence earns its place
-5. Code-first — Examples before explanations
 
-Use the standard issue format (CRITICAL/MAJOR/MINOR/NIT).
+1. **No filler** — Remove "basically", "simply", "just", "in order to", "actually", "really"
+2. **No hedging** — Remove "might", "could", "perhaps", "it seems", "you may want to"
+3. **Active voice** — "Video.js loads the source" not "The source is loaded by Video.js"
+4. **Direct address** — "You" not "the developer" or "one"
+5. **Sentence case headings** — "Add a custom theme" not "Add a Custom Theme"
+6. **No gerund headings** — "Add a theme" not "Adding a theme"
+7. **Concise** — Cut words that don't add meaning. Tighten sentences.
 
 Output:
 
-## Tone Review
+## Voice Review
 
 ### Score: X/10
 
 ### Issues
+[Use CRITICAL/MAJOR/MINOR/NIT format from templates.md]
 
-### [MINOR] Filler words in introduction
-
-**What:** Contains "In order to" and "basically"
-**Where:** Line 5
-**Why:** Dilutes message, unprofessional tone
-**Fix:** Delete filler words
-
-<!-- Before -->
-In order to basically understand events...
-
-<!-- After -->
-Events let you respond to player state changes.
-
----
-
-### Good Examples
-(Quote 1-2 lines with correct tone)
+### Good Patterns Found
+(1-2 examples)
 
 ### Summary
 (2-3 sentences)
 ```
 
-## Structure Review Agent
+---
+
+## Sub-Agent: Structure Review
 
 ```
-You are reviewing documentation structure.
+You are reviewing documentation structure, layout, and navigation.
 
-Load references:
-- docs/SKILL.md (Documentation Types section)
-- docs/patterns/progressive-disclosure.md
+Load:
+- docs/SKILL.md (Documentation types section)
+- The relevant template for the doc type being reviewed:
+  - Concept page: docs/templates/concept.md
+  - How-to guide: docs/templates/how-to.md
+  - Package README: docs/templates/readme.md
 
-Determine doc type (API ref, guide, handbook, component) and review:
-1. Correct structure — Matches template for doc type
-2. Progressive disclosure — Simple first, complexity later
-3. Cross-linking — Related pages linked
-4. See Also section — Present and relevant
-5. Headings — Actionable, scannable
+Review for:
 
-Use the standard issue format (CRITICAL/MAJOR/MINOR/NIT).
+1. **Correct doc type** — Is it the right type (concept vs how-to) for its content?
+2. **Matches template** — Does it follow the structure from its template?
+3. **Code-first** — Code appears before explanation, not after
+4. **Progressive** — Starts simple, adds complexity in later sections
+5. **Cross-links** — Has "See also" section linking related pages
+6. **Callouts** — Uses `<Aside>` (not `:::note`), correct severity
+7. **No H1** — Title comes from frontmatter only (site pages)
+8. **Sidebar** — Page added to `site/src/docs.config.ts` (site pages)
+9. **Framework rendering** — Works for all framework combinations (site pages)
 
 Output:
 
 ## Structure Review
 
-### Doc Type: [API Reference | Guide | Handbook | Component]
-
 ### Score: X/10
 
 ### Issues
+[Use CRITICAL/MAJOR/MINOR/NIT format from templates.md]
 
-### [MAJOR] Missing See Also section
-
-**What:** Page ends abruptly without related links
-**Where:** End of file
-**Why:** Readers hit dead end, can't discover related content
-**Fix:** Add See Also with relevant links
-
-<!-- After -->
-## See Also
-
-- [Related Concept](/handbook/related)
-- [API Reference](/api/relevant)
-
----
+### Good Patterns Found
+(1-2 examples)
 
 ### Summary
 (2-3 sentences)
 ```
 
-## Code Review Agent
+---
+
+## Sub-Agent: Code Review
 
 ```
-You are reviewing code examples in documentation.
+You are reviewing code examples in documentation for correctness and usability.
 
-Load references:
-- docs/patterns/code-examples.md
-- docs/patterns/props-tables.md
+Load: docs/patterns/code-examples.md
 
-Review code blocks for:
-1. Self-contained — All imports included
-2. Runnable — Would work if copy-pasted
-3. TypeScript — Types shown where helpful
-4. Realistic values — No foo/bar/baz
-5. Output shown — Expected results in comments
-6. Framework tabs — Multi-framework examples where needed
+Review for:
 
-Review tables for:
-1. Props format — Type, Default, Description columns
-2. Data attributes — Documented with values
-3. CSS variables — With defaults
-
-Use the standard issue format (CRITICAL/MAJOR/MINOR/NIT).
+1. **Imports shown** — All examples include necessary imports
+2. **Runnable** — Examples can be copied and run without modification
+3. **Realistic values** — Uses real-looking data, not "foo"/"bar"/"example"
+4. **Output shown** — Comments show expected output when result isn't obvious
+5. **Language tags** — All fenced code blocks have a language (ts, tsx, bash, etc.)
+6. **Self-contained** — Each example works standalone; no hidden dependencies
+7. **Explicit imports** — No ambient types; show where everything comes from
+8. **Clean markdown** — Proper fencing, no broken syntax, consistent formatting
 
 Output:
 
@@ -148,82 +123,27 @@ Output:
 ### Score: X/10
 
 ### Issues
+[Use CRITICAL/MAJOR/MINOR/NIT format from templates.md]
 
-### [CRITICAL] Example missing imports
-
-**What:** Code block has no import statement
-**Where:** Line 23
-**Why:** Copy-paste fails, agents can't use code
-**Fix:** Add imports
-
-<!-- Before -->
-const player = createPlayer({ src: 'video.mp4' });
-
-<!-- After -->
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({ src: 'video.mp4' });
-
----
-
-### Good Examples
-(Quote 1-2 well-done code blocks)
+### Good Patterns Found
+(1-2 examples)
 
 ### Summary
 (2-3 sentences)
 ```
 
-## AI Readiness Review Agent
-
-```
-You are reviewing documentation for AI/agent consumption.
-
-Load reference:
-- docs/patterns/ai-readiness.md
-
-Review for:
-1. Self-contained examples — Work without external context
-2. Explicit imports — All imports shown
-3. No assumed knowledge — Concepts explained or linked
-4. Clean markdown — Parseable, no broken formatting
-5. Linkable headings — Stable anchors
-6. Type information — Types visible or inferrable
-
-Use the standard issue format (CRITICAL/MAJOR/MINOR/NIT).
-
-Output:
-
-## AI Readiness Review
-
-### Score: X/10
-
-### Issues
-
-### [CRITICAL] Example requires external context
-
-**What:** Code references `config` variable defined elsewhere
-**Where:** Line 56
-**Why:** AI agents can't use this code without hunting for context
-**Fix:** Make example self-contained
-
-<!-- Before -->
-const player = createPlayer(config);
-
-<!-- After -->
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-});
-
 ---
 
-### Context Window Efficiency
-- Estimated tokens: X
-- Redundancy: [any repeated content]
-- Suggested cuts: [content that could be shorter]
+## Domain-Specific Focus
 
-### Summary
-(2-3 sentences)
-```
+### Site Pages (Concept / How-to)
+
+- Voice: Filler words are especially common in explanatory prose
+- Structure: Check Diataxis alignment — concepts explain, how-tos guide
+- Code: MDX component usage (`<Aside>`, `<FrameworkCase>`, `<Demo>`)
+
+### Package READMEs
+
+- Voice: Should be welcoming but concise — first impression
+- Structure: Install, quick example, concepts, community, license
+- Code: Quick example must be copy-paste ready with all imports
diff --git a/.claude/skills/docs/review/checklist.md b/.claude/skills/docs/review/checklist.md
new file mode 100644
index 00000000..ad1ff136
--- /dev/null
+++ b/.claude/skills/docs/review/checklist.md
@@ -0,0 +1,59 @@
+# Quick Review Checklist
+
+Single-agent checklist for fast documentation reviews without forking.
+
+## Voice
+
+See `references/writing-style.md` for full guidelines.
+
+- [ ] No filler words (basically, simply, just, in order to, actually, really)?
+- [ ] No hedging (might, could, perhaps, it seems)?
+- [ ] Active voice throughout?
+- [ ] Sentence case headings?
+- [ ] No gerund headings ("Add a theme" not "Adding a theme")?
+- [ ] Direct address ("you" not "the developer")?
+- [ ] Concise — no unnecessary words?
+
+## Structure
+
+See SKILL.md for doc types and templates.
+
+- [ ] Correct doc type (concept vs how-to)?
+- [ ] Matches template structure?
+- [ ] Code appears before explanation?
+- [ ] Progressive — starts simple, adds complexity?
+- [ ] Has "See also" section with related links?
+- [ ] `<Aside>` used correctly (not `:::note`)?
+- [ ] Correct callout types (note/tip/caution/danger)?
+- [ ] No H1 — title from frontmatter only (site pages)?
+
+## Code
+
+See `patterns/code-examples.md` for conventions.
+
+- [ ] All examples include imports?
+- [ ] Examples are runnable (copy-paste ready)?
+- [ ] Realistic values, not `foo`/`bar`?
+- [ ] Output shown when result isn't obvious?
+- [ ] All fenced code blocks have language tags?
+- [ ] Self-contained — no hidden dependencies?
+
+## Site Pages
+
+- [ ] Added to sidebar in `docs.config.ts`?
+- [ ] Renders for all framework combinations?
+- [ ] `client:idle` on all Tab components (never `client:visible`)?
+- [ ] MDX components used correctly (`<FrameworkCase>`, `<Demo>`, etc.)?
+
+## READMEs
+
+- [ ] Has npm badge and alpha warning?
+- [ ] Install command present?
+- [ ] Has working quick example with imports?
+- [ ] Code examples are self-contained?
+- [ ] Community section with Discord and Discussions links?
+- [ ] License section?
+
+## Related Skills
+
+For component reference pages, use the `api-reference` skill review process instead.
diff --git a/.claude/skills/docs/review/issue-format.md b/.claude/skills/docs/review/issue-format.md
deleted file mode 100644
index c24b46f3..00000000
--- a/.claude/skills/docs/review/issue-format.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Issue Format
-
-Standard format for all documentation review issues.
-
-## Template
-
-```markdown
-### [SEVERITY] Issue title
-
-**What:** Brief description of the problem
-**Where:** `path/to/file.md` line 42
-**Why:** Impact on readers/developers/agents
-**Fix:** Concrete suggestion
-
-<!-- Before -->
-Original problematic content
-
-<!-- After -->
-Fixed content
-```
-
-## Severity Levels
-
-| Level | Meaning | Examples |
-|-------|---------|----------|
-| `CRITICAL` | Blocks understanding, incorrect info | Wrong API, broken example, missing imports |
-| `MAJOR` | Significantly hurts quality | Wall of text, missing See Also, wrong doc type structure |
-| `MINOR` | Polish issues | Filler words, passive voice, inconsistent formatting |
-| `NIT` | Suggestions, not problems | Could be shorter, alternative phrasing |
-
-## Examples
-
-### Critical
-
-```markdown
-### [CRITICAL] Example missing imports
-
-**What:** Code example can't be copy-pasted
-**Where:** `guides/getting-started.md` line 45
-**Why:** Developers get errors, agents can't use the code
-**Fix:** Add import statement
-
-<!-- Before -->
-const player = createPlayer({ src: 'video.mp4' });
-
-<!-- After -->
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({ src: 'video.mp4' });
-```
-
-### Major
-
-```markdown
-### [MAJOR] No See Also section
-
-**What:** Page ends without linking related content
-**Where:** `handbook/events.md` (end of file)
-**Why:** Dead end — readers don't know where to go next
-**Fix:** Add See Also with 2-4 relevant links
-
-<!-- After -->
-## See Also
-
-- [State Management](/handbook/state)
-- [Player API](/api/player)
-- [Custom Events Guide](/guides/custom-events)
-```
-
-### Minor
-
-```markdown
-### [MINOR] Filler words
-
-**What:** Unnecessary words dilute the message
-**Where:** `api/player.md` line 12
-**Why:** Wastes reader attention, unprofessional tone
-**Fix:** Delete filler
-
-<!-- Before -->
-In order to basically create a player, you simply need to...
-
-<!-- After -->
-Create a player:
-```
-
-### Nit
-
-```markdown
-### [NIT] Could use tabs for frameworks
-
-**What:** Shows only React example
-**Where:** `guides/installation.md` line 30
-**Why:** Vue/Svelte/Solid users need to translate mentally
-**Fix:** Add framework tabs (optional improvement)
-```
diff --git a/.claude/skills/docs/review/merge-template.md b/.claude/skills/docs/review/merge-template.md
deleted file mode 100644
index b86d7dd1..00000000
--- a/.claude/skills/docs/review/merge-template.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# Merge Report Template
-
-Template for combining sub-agent reports into final review.
-
-## Template
-
-```markdown
-# Documentation Review: [filename]
-
-## Overall Score: X/10
-
-| Dimension | Score | Issues |
-|-----------|-------|--------|
-| Tone | X/10 | X critical, X major, X minor |
-| Structure | X/10 | X critical, X major, X minor |
-| Code | X/10 | X critical, X major, X minor |
-| AI Readiness | X/10 | X critical, X major, X minor |
-
-## Critical Issues
-
-[List all CRITICAL issues from all agents using standard format]
-
----
-
-## Major Issues
-
-[List all MAJOR issues from all agents using standard format]
-
----
-
-## Minor Issues
-
-[Condense into table]
-
-| Severity | Location | Issue | Fix |
-|----------|----------|-------|-----|
-| MINOR | Line 12 | Filler word "simply" | Delete |
-| MINOR | Line 34 | Passive voice | Use active |
-| NIT | Line 56 | Could add framework tabs | Optional |
-
----
-
-## Good Patterns Found
-
-- [Quote or describe what's working well]
-- [Another good example]
-
----
-
-## Summary
-
-[2-3 paragraph overall assessment: what's good, what needs work, priority order for fixes]
-
----
-
-<details>
-<summary>Full Tone Review</summary>
-
-[Complete tone review output]
-
-</details>
-
-<details>
-<summary>Full Structure Review</summary>
-
-[Complete structure review output]
-
-</details>
-
-<details>
-<summary>Full Code Review</summary>
-
-[Complete code review output]
-
-</details>
-
-<details>
-<summary>Full AI Readiness Review</summary>
-
-[Complete AI readiness review output]
-
-</details>
-```
-
-## PR Review Template
-
-For reviewing documentation changes in pull requests:
-
-```markdown
-# PR Documentation Review: #[number]
-
-## Changed Files
-
-| File | Status | Review |
-|------|--------|--------|
-| `docs/api/new-feature.md` | New | Full review |
-| `docs/guides/getting-started.md` | Modified | Diff review |
-
-## New Documentation
-
-### docs/api/new-feature.md
-
-[Full review using standard template]
-
-## Modified Documentation
-
-### docs/guides/getting-started.md
-
-**Changed sections:** Lines 45-60
-
-[Review of changed sections only]
-
-## Checklist
-
-- [ ] New features documented
-- [ ] Breaking changes in migration guide
-- [ ] Examples updated and runnable
-- [ ] Types/props documented
-- [ ] See Also sections updated
-```
diff --git a/.claude/skills/docs/review/templates.md b/.claude/skills/docs/review/templates.md
new file mode 100644
index 00000000..920e6584
--- /dev/null
+++ b/.claude/skills/docs/review/templates.md
@@ -0,0 +1,168 @@
+# Review Templates
+
+Issue format and report templates for documentation reviews.
+
+## Issue Format
+
+```markdown
+### [SEVERITY] Issue title
+
+**What:** Brief description
+**Where:** `path/to/file.mdx:42`
+**Why:** Impact on readers
+**Fix:** Concrete suggestion
+
+// Before
+problematic text or code
+
+// After
+improved text or code
+```
+
+## Severity Levels
+
+| Level      | Meaning                        | Examples                                           |
+| ---------- | ------------------------------ | -------------------------------------------------- |
+| `CRITICAL` | Broken example, wrong info     | Missing import, incorrect API, code won't run      |
+| `MAJOR`    | Missing section, unclear prose | No "See also", wrong doc type, wall of text        |
+| `MINOR`    | Suboptimal wording or layout   | Filler words, passive voice, could be more concise |
+| `NIT`      | Polish, phrasing preference    | Minor rewording, formatting tweak                  |
+
+---
+
+## Issue Examples
+
+### CRITICAL — Broken code example
+
+```markdown
+### [CRITICAL] Example missing import
+
+**What:** Code example uses `createPlayer` without importing it
+**Where:** `site/src/content/docs/concepts/player.mdx:45`
+**Why:** Readers who copy-paste get a ReferenceError
+**Fix:** Add import statement
+
+// Before
+const player = createPlayer({ src: 'video.mp4' });
+
+// After
+import { createPlayer } from '@videojs/html';
+
+const player = createPlayer({ src: 'video.mp4' });
+```
+
+### MAJOR — Missing cross-links
+
+```markdown
+### [MAJOR] No "See also" section
+
+**What:** Page ends without linking to related concepts
+**Where:** `site/src/content/docs/concepts/themes.mdx`
+**Why:** Readers can't discover related pages; reduces navigation
+**Fix:** Add See also section
+
+// After
+## See also
+
+- [Styling](/concepts/styling) — CSS custom properties reference
+- [Accessibility](/concepts/accessibility) — Color contrast requirements
+```
+
+### MINOR — Filler words
+
+```markdown
+### [MINOR] Filler words in explanation
+
+**What:** Paragraph contains "simply", "just", and "basically"
+**Where:** `site/src/content/docs/concepts/state.mdx:23`
+**Why:** Filler words dilute the message and add no meaning
+**Fix:** Remove filler, tighten sentence
+
+// Before
+You can simply just call the subscribe method to basically listen for changes.
+
+// After
+Call `subscribe` to listen for changes.
+```
+
+### NIT — Phrasing
+
+```markdown
+### [NIT] Gerund heading
+
+**What:** Heading uses gerund form
+**Where:** `site/src/content/docs/how-to/theming.mdx:30`
+**Why:** Imperative headings are more direct and scannable
+**Fix:** Use imperative form
+
+// Before
+## Customizing the controls
+
+// After
+## Customize the controls
+```
+
+---
+
+## Merge Report Template
+
+```markdown
+# Docs Review: [page or file name]
+
+## Overall Score: X/10
+
+| Dimension | Score | Critical | Major | Minor |
+| --------- | ----- | -------- | ----- | ----- |
+| Voice     | X/10  | X        | X     | X     |
+| Structure | X/10  | X        | X     | X     |
+| Code      | X/10  | X        | X     | X     |
+
+## Critical Issues
+
+[List all CRITICAL issues, full format]
+
+---
+
+## Major Issues
+
+[List all MAJOR issues, full format]
+
+---
+
+## Minor/Nit Issues
+
+| Severity | Location             | Issue            | Fix                |
+| -------- | -------------------- | ---------------- | ------------------ |
+| MINOR    | `concepts/foo.mdx:8` | Filler words     | Remove "basically" |
+| NIT      | `concepts/foo.mdx:30`| Gerund heading   | Use imperative     |
+
+---
+
+## Good Patterns Found
+
+- [What's working well]
+- [Worth preserving]
+
+---
+
+## Summary
+
+[2-3 paragraph assessment: strengths, weaknesses, priority order]
+
+---
+
+<details>
+<summary>Full Voice Review</summary>
+[Complete output]
+</details>
+
+<details>
+<summary>Full Structure Review</summary>
+[Complete output]
+</details>
+
+<details>
+<summary>Full Code Review</summary>
+[Complete output]
+</details>
+```
diff --git a/.claude/skills/docs/review/workflow.md b/.claude/skills/docs/review/workflow.md
index 2df2b861..5bbc2d60 100644
--- a/.claude/skills/docs/review/workflow.md
+++ b/.claude/skills/docs/review/workflow.md
@@ -1,19 +1,22 @@
 # Docs Review Workflow
 
-Review documentation against Video.js standards.
+Review documentation for writing quality, structure, and code example correctness.
 
 ## Process
 
 ```
-┌─────────────────────────────────────────────┐
-│              Coordinator                     │
-└──────────────────┬──────────────────────────┘
-     ┌─────────────┼─────────────┬─────────────┐
-     ▼             ▼             ▼             ▼
-┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
-│  Tone   │  │Structure│  │  Code   │  │   AI    │
-└─────────┘  └─────────┘  └─────────┘  └─────────┘
-     └─────────────┴─────────────┴─────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│                      Coordinator                            │
+└─────────────────────┬───────────────────────────────────────┘
+                      │
+        ┌─────────────┼─────────────┐
+        ▼             ▼             ▼
+   ┌─────────┐  ┌─────────┐  ┌─────────┐
+   │  Voice  │  │Structure│  │  Code   │
+   └─────────┘  └─────────┘  └─────────┘
+        │             │             │
+        └─────────────┴─────────────┘
+                      │
                       ▼
               ┌─────────────┐
               │   Merge     │
@@ -22,35 +25,36 @@ Review documentation against Video.js standards.
 
 ### 1. Gather Context
 
-Load the file(s) to review.
+- Single page: `site/src/content/docs/concepts/foo.mdx`
+- Package README: `packages/core/README.md`
+- PR diff: changed documentation files
 
 ### 2. Fork Reviews
 
-Spawn 4 sub-agents. See [agents.md](agents.md) for prompts.
+Spawn 3 sub-agents. See [agents.md](agents.md) for prompts.
 
-| Agent         | Reviews                           | Loads                                   |
-| ------------- | --------------------------------- | --------------------------------------- |
-| **Tone**      | Directness, hedging, active voice | `../examples/tone-samples.md`           |
-| **Structure** | Doc type, progressive disclosure  | `../patterns/progressive-disclosure.md` |
-| **Code**      | Imports, runnable, props tables   | `../patterns/code-examples.md`          |
-| **AI**        | Self-contained, clean markdown    | `../patterns/ai-readiness.md`           |
+| Agent     | Focus                               | References                      |
+| --------- | ----------------------------------- | ------------------------------- |
+| Voice     | Tone, clarity, filler, hedging      | `references/writing-style.md`   |
+| Structure | Doc type, template, layout, linking | SKILL.md + relevant template    |
+| Code      | Examples, imports, output, markdown | `patterns/code-examples.md`     |
 
 ### 3. Merge Report
 
-Combine findings using [merge-template.md](merge-template.md).
+Combine findings using template in [templates.md](templates.md).
 
-## Quick Review (No Fork)
+## Quick Review
 
-For fast single-agent reviews:
+For fast reviews without forking, use [checklist.md](checklist.md).
 
-- [ ] No filler words (basically, simply, just)
-- [ ] No hedging (might, could, perhaps)
-- [ ] Active voice
-- [ ] Code before explanation
-- [ ] All imports shown
-- [ ] Examples are runnable
-- [ ] Has See Also section
-- [ ] Matches doc type template
+## Severity Levels
+
+| Level      | Meaning                        | Action     |
+| ---------- | ------------------------------ | ---------- |
+| `CRITICAL` | Broken example, wrong info     | Must fix   |
+| `MAJOR`    | Missing section, unclear prose | Should fix |
+| `MINOR`    | Suboptimal wording or layout   | Consider   |
+| `NIT`      | Polish, phrasing preference    | Optional   |
 
 ## Issue Format
 
@@ -58,32 +62,21 @@ For fast single-agent reviews:
 ### [SEVERITY] Issue title
 
 **What:** Brief description
-**Where:** `path/to/file.md` line 42
+**Where:** `path/to/file.mdx:42`
 **Why:** Impact on readers
 **Fix:** Concrete suggestion
 
-<!-- Before -->
+// Before
+problematic text or code
 
-In order to create a player...
-
-<!-- After -->
-
-Create a player:
+// After
+improved text or code
 ```
 
-## Severity Levels
-
-| Level      | Use for                                          |
-| ---------- | ------------------------------------------------ |
-| `CRITICAL` | Blocks understanding — wrong API, broken example |
-| `MAJOR`    | Hurts quality — wall of text, missing See Also   |
-| `MINOR`    | Polish — filler words, passive voice             |
-| `NIT`      | Suggestions — could be shorter                   |
-
 ## References
 
-| File                                   | Content                         |
-| -------------------------------------- | ------------------------------- |
-| [agents.md](agents.md)                 | Full prompts for each sub-agent |
-| [issue-format.md](issue-format.md)     | Issue format with examples      |
-| [merge-template.md](merge-template.md) | Final report template           |
+| File                         | Contents                      |
+| ---------------------------- | ----------------------------- |
+| [agents.md](agents.md)       | Sub-agent prompts             |
+| [templates.md](templates.md) | Issue format, report template |
+| [checklist.md](checklist.md) | Quick single-agent checklist  |
diff --git a/.claude/skills/docs/templates/api-reference.md b/.claude/skills/docs/templates/api-reference.md
deleted file mode 100644
index 3c905147..00000000
--- a/.claude/skills/docs/templates/api-reference.md
+++ /dev/null
@@ -1,460 +0,0 @@
-# API Reference Template
-
-Use this template for documenting functions, classes, and modules.
-
----
-
-## Function Template
-
-```markdown
-## functionName
-
-Brief description of what the function does.
-
-import { functionName } from '@videojs/core';
-
-const result = functionName(arg1, arg2);
-
-### Parameters
-
-| Parameter | Type      | Description           |
-| --------- | --------- | --------------------- |
-| `arg1`    | `string`  | Description of arg1   |
-| `arg2`    | `Options` | Configuration options |
-
-### Options
-
-| Option    | Type      | Default     | Description |
-| --------- | --------- | ----------- | ----------- |
-| `option1` | `string`  | `'default'` | Description |
-| `option2` | `boolean` | `false`     | Description |
-
-### Returns
-
-`ReturnType` — Description of return value.
-
-| Property | Type     | Description |
-| -------- | -------- | ----------- |
-| `prop1`  | `string` | Description |
-| `prop2`  | `number` | Description |
-
-### Throws
-
-| Error           | Condition               |
-| --------------- | ----------------------- |
-| `TypeError`     | When arg1 is invalid    |
-| `NotFoundError` | When resource not found |
-
-### Examples
-
-#### Basic Usage
-
-const result = functionName('value');
-
-#### With Options
-
-const result = functionName('value', {
-option1: 'custom',
-option2: true,
-});
-
-### See Also
-
-- [relatedFunction](/api/related-function)
-- [Concept Guide](/guides/concept)
-```
-
----
-
-## Class Template
-
-```markdown
-## ClassName
-
-Brief description of the class.
-
-import { ClassName } from '@videojs/core';
-
-const instance = new ClassName(options);
-
-### Constructor
-
-#### Parameters
-
-| Parameter | Type           | Description   |
-| --------- | -------------- | ------------- |
-| `options` | `ClassOptions` | Configuration |
-
-#### Options
-
-| Option    | Type      | Default | Description     |
-| --------- | --------- | ------- | --------------- |
-| `option1` | `string`  | —       | Required option |
-| `option2` | `boolean` | `false` | Optional        |
-
-### Properties
-
-| Property         | Type     | Description        |
-| ---------------- | -------- | ------------------ |
-| `readonly prop1` | `string` | Read-only property |
-| `prop2`          | `number` | Writable property  |
-
-### Methods
-
-#### methodName()
-
-Description of method.
-
-instance.methodName(arg);
-
-**Parameters:**
-
-| Parameter | Type     | Description |
-| --------- | -------- | ----------- |
-| `arg`     | `string` | Description |
-
-**Returns:** `ReturnType` — Description.
-
-#### anotherMethod()
-
-Description of another method.
-
-await instance.anotherMethod();
-
-**Returns:** `Promise<void>`
-
-### Events
-
-| Event    | Payload            | Description   |
-| -------- | ------------------ | ------------- |
-| `event1` | `{ data: string }` | Fired when... |
-| `event2` | `void`             | Fired when... |
-
-### Example
-
-import { ClassName } from '@videojs/core';
-
-const instance = new ClassName({
-option1: 'value',
-});
-
-instance.on('event1', ({ data }) => {
-console.log(data);
-});
-
-await instance.methodName('arg');
-
-### See Also
-
-- [Related Class](/api/related-class)
-- [Usage Guide](/guides/usage)
-```
-
----
-
-## Hook Template (React/Vue/Solid)
-
-```markdown
-## useHookName
-
-Brief description of what the hook provides.
-
-import { useHookName } from '@videojs/react';
-
-function Component() {
-const { value, setValue } = useHookName();
-return <div>{value}</div>;
-}
-
-### Parameters
-
-| Parameter | Type          | Description   |
-| --------- | ------------- | ------------- |
-| `options` | `HookOptions` | Configuration |
-
-### Options
-
-| Option         | Type                 | Default | Description     |
-| -------------- | -------------------- | ------- | --------------- |
-| `initialValue` | `T`                  | —       | Initial value   |
-| `onChange`     | `(value: T) => void` | —       | Change callback |
-
-### Returns
-
-| Property   | Type                 | Description      |
-| ---------- | -------------------- | ---------------- |
-| `value`    | `T`                  | Current value    |
-| `setValue` | `(value: T) => void` | Update value     |
-| `reset`    | `() => void`         | Reset to initial |
-
-### Examples
-
-#### Basic
-
-function Player() {
-const { volume, setVolume } = useVolume();
-
-return (
-<input
-type="range"
-value={volume}
-onChange={(e) => setVolume(Number(e.target.value))}
-/>
-);
-}
-
-#### With Initial Value
-
-const { volume } = useVolume({ initialValue: 0.5 });
-
-### See Also
-
-- [useRelatedHook](/api/use-related-hook)
-- [State Guide](/guides/state)
-```
-
----
-
-## Module/Namespace Template
-
-```markdown
-## moduleName
-
-Brief description of the module.
-
-import \* as moduleName from '@videojs/core/module';
-
-// or specific imports
-import { func1, func2 } from '@videojs/core/module';
-
-### Exports
-
-| Export   | Type       | Description     |
-| -------- | ---------- | --------------- |
-| `func1`  | `Function` | Does X          |
-| `func2`  | `Function` | Does Y          |
-| `Const1` | `string`   | Constant value  |
-| `Type1`  | `type`     | Type definition |
-
-### func1
-
-[Full documentation...]
-
-### func2
-
-[Full documentation...]
-
-### Types
-
-#### Type1
-
-type Type1 = {
-prop1: string;
-prop2: number;
-};
-
-### Constants
-
-| Constant | Value     | Description |
-| -------- | --------- | ----------- |
-| `Const1` | `'value'` | Description |
-| `Const2` | `42`      | Description |
-```
-
----
-
-## Type Template
-
-```markdown
-## TypeName
-
-Brief description of the type.
-
-import type { TypeName } from '@videojs/core';
-
-const value: TypeName = {
-prop1: 'value',
-prop2: 42,
-};
-
-### Definition
-
-type TypeName = {
-prop1: string;
-prop2: number;
-prop3?: boolean;
-};
-
-### Properties
-
-| Property | Type      | Required | Description |
-| -------- | --------- | -------- | ----------- |
-| `prop1`  | `string`  | Yes      | Description |
-| `prop2`  | `number`  | Yes      | Description |
-| `prop3`  | `boolean` | No       | Description |
-
-### Usage
-
-function process(input: TypeName): void {
-console.log(input.prop1, input.prop2);
-}
-
-### Related Types
-
-- [RelatedType](/api/types/related-type)
-- [AnotherType](/api/types/another-type)
-```
-
----
-
-## Feature Template
-
-For `@videojs/store` features:
-
-```markdown
-## featureName
-
-Brief description of what state this feature manages.
-
-import { featureName } from '@videojs/core/dom';
-// or
-import { defineFeature } from '@videojs/store';
-
-const featureName = defineFeature<HTMLMediaElement>()({
-  state: ({ task }) => ({
-    property1: defaultValue,
-    property2: defaultValue,
-
-    actionName(input: InputType) {
-      return task({
-        key: 'actionKey',
-        handler({ target }) {
-          target.property = input;
-          return target.property;
-        },
-      });
-    },
-  }),
-
-  attach({ target, signal, set }) {
-    const sync = () => set({
-      property1: target.property1,
-      property2: target.property2,
-    });
-
-    sync();
-
-    listen(target, 'eventname', sync, { signal });
-  },
-});
-
-### State
-
-| Property    | Type   | Description |
-| ----------- | ------ | ----------- |
-| `property1` | `type` | Description |
-| `property2` | `type` | Description |
-
-### Actions
-
-| Action       | Input       | Output       | Description  |
-| ------------ | ----------- | ------------ | ------------ |
-| `actionName` | `InputType` | `OutputType` | What it does |
-
-### Type Inference
-
-import type { InferFeatureState, InferFeatureRequests } from '@videojs/store';
-
-type FeatureNameState = InferFeatureState<typeof featureName>;
-type FeatureNameRequests = InferFeatureRequests<typeof featureName>;
-
-### See Also
-
-- [Related Feature](/api/features/related)
-- [Store Guide](/guides/store)
-```
-
----
-
-## Controller Template
-
-For `@videojs/store/html` controllers:
-
-```markdown
-## ControllerName
-
-Brief description of what this controller does.
-
-import { ControllerName } from '@videojs/store/html';
-
-class MyElement extends ReactiveElement {
-#controller = new ControllerName(this, source, ...args);
-
-render() {
-return html`<div>${this.#controller.value}</div>`;
-}
-}
-
-### Constructor
-
-new ControllerName(host, source, ...args)
-
-#### Parameters
-
-| Parameter | Type                                   | Description             |
-| --------- | -------------------------------------- | ----------------------- |
-| `host`    | `ReactiveControllerHost & HTMLElement` | The host element        |
-| `source`  | `Store \| Context<Store>`              | Direct store or context |
-
-### Properties
-
-| Property | Type | Description       |
-| -------- | ---- | ----------------- |
-| `value`  | `T`  | The current value |
-
-### Lifecycle
-
-| Method               | Description                  |
-| -------------------- | ---------------------------- |
-| `hostConnected()`    | Called when host connects    |
-| `hostDisconnected()` | Called when host disconnects |
-
-### Example
-
-import { SnapshotController } from '@videojs/store/html';
-
-class PlayButton extends ReactiveElement {
-#state = new SnapshotController(this, store.state);
-#play = new RequestController(this, context, 'play');
-
-render() {
-return html\`
-<button @click=\${() => this.#play.value()}>
-\${this.#state.value.paused ? 'Play' : 'Pause'}
-</button>
-\`;
-}
-}
-
-### See Also
-
-- [Related Controller](/api/controllers/related)
-- [Web Components Guide](/guides/web-components)
-```
-
----
-
-## Checklist
-
-When writing API reference:
-
-- [ ] Brief description at top
-- [ ] Import statement shown
-- [ ] Basic example immediately after
-- [ ] All parameters documented
-- [ ] All options with types and defaults
-- [ ] Return value documented
-- [ ] Errors/throws documented if applicable
-- [ ] Multiple examples (basic → advanced)
-- [ ] See Also section with related items
-- [ ] Types linked or inline
diff --git a/.claude/skills/docs/templates/component-page.md b/.claude/skills/docs/templates/component-page.md
deleted file mode 100644
index b38f33ca..00000000
--- a/.claude/skills/docs/templates/component-page.md
+++ /dev/null
@@ -1,421 +0,0 @@
-# Component Page Template
-
-Use this template for documenting UI components.
-
----
-
-## Template
-
-```markdown
-## ComponentName
-
-Brief description of what the component does.
-
-<!-- Live demo here if possible -->
-
-<ComponentName defaultValue={50}>
-  <ComponentName.Track>
-    <ComponentName.Fill />
-  </ComponentName.Track>
-  <ComponentName.Thumb />
-</ComponentName>
-
-### Features
-
-- Feature one
-- Feature two
-- Feature three
-- Keyboard accessible
-
-### Installation
-
-npm install @videojs/dom
-
-### Anatomy
-
-Import and assemble the parts:
-
-import { ComponentName } from '@videojs/dom';
-
-<ComponentName.Root>
-<ComponentName.PartA />
-<ComponentName.PartB>
-<ComponentName.PartC />
-</ComponentName.PartB>
-</ComponentName.Root>
-
-### API Reference
-
-#### Root
-
-Container element. Renders a `<div>`.
-
-##### Props
-
-| Prop            | Type                      | Default | Description         |
-| --------------- | ------------------------- | ------- | ------------------- |
-| `value`         | `number`                  | —       | Controlled value    |
-| `defaultValue`  | `number`                  | `0`     | Initial value       |
-| `disabled`      | `boolean`                 | `false` | Disable interaction |
-| `onValueChange` | `(value: number) => void` | —       | Called on change    |
-
-##### Data Attributes
-
-| Attribute       | Description           |
-| --------------- | --------------------- |
-| `data-disabled` | Present when disabled |
-| `data-state`    | `'idle' \| 'active'`  |
-
-##### CSS Variables
-
-| Variable           | Default | Description    |
-| ------------------ | ------- | -------------- |
-| `--component-size` | `100%`  | Container size |
-
-#### PartA
-
-Description. Renders a `<div>`.
-
-##### Props
-
-| Prop        | Type     | Default | Description |
-| ----------- | -------- | ------- | ----------- |
-| `className` | `string` | —       | CSS class   |
-
-##### Data Attributes
-
-| Attribute    | Description   |
-| ------------ | ------------- |
-| `data-state` | Current state |
-
-#### PartB
-
-Description. Renders a `<div>`.
-
-[Continue for each part...]
-
-### Examples
-
-#### Basic
-
-<ComponentName.Root>
-<ComponentName.PartA />
-</ComponentName.Root>
-
-#### Controlled
-
-function ControlledExample() {
-const [value, setValue] = useState(50);
-
-return (
-<ComponentName.Root value={value} onValueChange={setValue}>
-<ComponentName.PartA />
-</ComponentName.Root>
-);
-}
-
-#### Disabled
-
-<ComponentName.Root disabled>
-<ComponentName.PartA />
-</ComponentName.Root>
-
-#### Custom Styling
-
-<ComponentName.Root className="custom-component">
-<ComponentName.PartA />
-</ComponentName.Root>
-
-.custom-component {
---component-size: 200px;
-}
-
-.custom-component[data-state='active'] {
-border-color: blue;
-}
-
-#### With Other Components
-
-<Player>
-  <ComponentName.Root>
-    <ComponentName.PartA />
-  </ComponentName.Root>
-</Player>
-
-### Accessibility
-
-Follows [WAI-ARIA Pattern Name](https://www.w3.org/WAI/ARIA/apg/patterns/...).
-
-#### Keyboard Interactions
-
-| Key         | Action     |
-| ----------- | ---------- |
-| `Enter`     | Activate   |
-| `Space`     | Activate   |
-| `ArrowUp`   | Increase   |
-| `ArrowDown` | Decrease   |
-| `Home`      | Minimum    |
-| `End`       | Maximum    |
-| `Tab`       | Move focus |
-
-#### ARIA Attributes
-
-| Attribute       | Value           |
-| --------------- | --------------- |
-| `role`          | `slider`        |
-| `aria-valuenow` | Current value   |
-| `aria-valuemin` | Minimum value   |
-| `aria-valuemax` | Maximum value   |
-| `aria-label`    | Accessible name |
-
-### See Also
-
-- [RelatedComponent](/components/related)
-- [Styling Guide](/handbook/styling)
-- [Accessibility Guide](/handbook/accessibility)
-```
-
----
-
-## Anatomy Diagram
-
-Show component structure visually:
-
-```
-┌─ Root ─────────────────────────────────┐
-│                                        │
-│  ┌─ Track ──────────────────────────┐  │
-│  │                                  │  │
-│  │  ┌─ Fill ─────────┐              │  │
-│  │  │████████████████│              │  │
-│  │  └────────────────┘              │  │
-│  │                                  │  │
-│  └──────────────────────────────────┘  │
-│                     ○ Thumb            │
-│                                        │
-└────────────────────────────────────────┘
-```
-
----
-
-## Framework Variations
-
-Include tabs for each framework:
-
-````markdown
-### Framework Examples
-
-<Tabs>
-<Tab label="React">
-```tsx
-import { Slider } from '@videojs/react';
-
-function VolumeSlider() {
-const [volume, setVolume] = useState(1);
-
-return (
-<Slider.Root value={volume} onValueChange={setVolume}>
-<Slider.Track>
-<Slider.Fill />
-</Slider.Track>
-<Slider.Thumb />
-</Slider.Root>
-);
-}
-````
-
-</Tab>
-<Tab label="Vue">
-```vue
-<script setup>
-import { Slider } from '@videojs/vue';
-import { ref } from 'vue';
-
-const volume = ref(1);
-</script>
-
-<template>
-  <Slider.Root v-model="volume">
-    <Slider.Track>
-      <Slider.Fill />
-    </Slider.Track>
-    <Slider.Thumb />
-  </Slider.Root>
-</template>
-````
-
-</Tab>
-<Tab label="Svelte">
-```svelte
-<script>
-  import { Slider } from '@videojs/svelte';
-  
-  let volume = 1;
-</script>
-
-<Slider.Root bind:value={volume}>
-<Slider.Track>
-<Slider.Fill />
-</Slider.Track>
-<Slider.Thumb />
-</Slider.Root>
-
-```
-</Tab>
-</Tabs>
-```
-
-````
-
----
-
-## Styling Section
-
-Always include styling examples:
-
-```markdown
-### Styling
-
-#### With CSS
-
-.slider[data-dragging] {
-cursor: grabbing;
-}
-
-.slider-thumb:focus-visible {
-outline: 2px solid blue;
-}
-
-#### With Tailwind
-
-<Slider.Root className="relative w-full h-2">
-<Slider.Track className="bg-gray-200 rounded-full h-full">
-<Slider.Fill className="bg-blue-500 rounded-full h-full" />
-</Slider.Track>
-<Slider.Thumb className="absolute w-4 h-4 bg-white rounded-full shadow" />
-</Slider.Root>
-
-#### CSS Variables Reference
-
-| Variable              | Default        | Description      |
-| --------------------- | -------------- | ---------------- |
-| `--slider-track-bg`   | `#e5e5e5`      | Track background |
-| `--slider-fill-bg`    | `currentColor` | Fill color       |
-| `--slider-thumb-size` | `16px`         | Thumb diameter   |
-```
-
----
-
-## Web Component Template
-
-For `@videojs/html` components built with `@videojs/element`:
-
-```markdown
-## element-name
-
-Brief description.
-
-### Registration
-
-import { ElementName } from '@videojs/html/path';
-
-// Default registration
-ElementName.define();
-
-// Custom tag name
-ElementName.define('custom-name');
-
-// With custom mixin
-import { createStore } from '@videojs/store/html';
-import { extendConfig } from '@videojs/html/video/skin';
-
-const { StoreMixin } = createStore(
-extendConfig({ features: [customFeature] })
-);
-
-ElementName.define('custom-name', StoreMixin);
-
-### HTML Usage
-
-<element-name>
-  <video src="video.mp4"></video>
-</element-name>
-
-### Attributes
-
-| Attribute | Type     | Default | Description  |
-| --------- | -------- | ------- | ------------ |
-| `src`     | `string` | —       | Media source |
-
-### Slots
-
-| Slot      | Description                            |
-| --------- | -------------------------------------- |
-| (default) | Media element (`<video>` or `<audio>`) |
-
-### Controllers Used
-
-| Controller            | Usage           | Purpose              |
-| --------------------- | --------------- | -------------------- |
-| `SnapshotController`  | `store.state`   | Track playback state |
-| `RequestController`   | `'play'`        | Play request         |
-
-### Events
-
-| Event       | Detail      | Description     |
-| ----------- | ----------- | --------------- |
-| `vjs:ready` | `{ store }` | Component ready |
-
-### CSS Custom Properties
-
-| Property             | Default | Description  |
-| -------------------- | ------- | ------------ |
-| `--vjs-accent-color` | `#fff`  | Accent color |
-
-### Example
-
-<vjs-frosted-skin>
-  <video
-    src="video.mp4"
-    poster="poster.jpg"
-  ></video>
-</vjs-frosted-skin>
-
-### Extending
-
-import { createStore } from '@videojs/store/html';
-import { extendConfig, FrostedSkinElement } from '@videojs/html/video/skin';
-import { chaptersFeature } from './features/chapters';
-
-const { StoreMixin } = createStore(
-extendConfig({ features: [chaptersFeature] })
-);
-
-FrostedSkinElement.define('my-player', StoreMixin);
-
-### See Also
-
-- [Controllers](/api/controllers)
-- [Creating Custom Elements](/guides/custom-elements)
-```
-
----
-
-## Checklist
-
-When writing component documentation:
-
-- [ ] Live demo at top
-- [ ] Features list (3-5 bullets)
-- [ ] Installation command
-- [ ] Anatomy with all parts
-- [ ] Props table for each part
-- [ ] Data attributes for each part
-- [ ] CSS variables table
-- [ ] Basic example
-- [ ] Controlled example
-- [ ] Styling example
-- [ ] Accessibility section
-- [ ] Keyboard interactions table
-- [ ] See Also section
-````
diff --git a/.claude/skills/docs/templates/concept.md b/.claude/skills/docs/templates/concept.md
new file mode 100644
index 00000000..67786365
--- /dev/null
+++ b/.claude/skills/docs/templates/concept.md
@@ -0,0 +1,90 @@
+# Concept Page Template
+
+Use for bite-sized explanation pages. One concept per page, quickly scannable.
+
+## Frontmatter
+
+```yaml
+---
+title: 'Your concept title'
+description: 'One-sentence summary for search and metadata'
+---
+```
+
+Optional — override the title per framework:
+
+```yaml
+---
+title: 'State management'
+description: 'How Video.js manages player state'
+frameworkTitle:
+  html: 'State management in HTML'
+  react: 'State management in React'
+---
+```
+
+## Page structure
+
+```mdx
+---
+title: 'Concept name'
+description: 'Brief description'
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import Aside from '@/components/Aside.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+
+One-sentence description of the concept. Show code immediately:
+
+{/* Minimal example — under 5 lines */}
+
+## How it works
+
+2-3 short paragraphs. Keep it brief — readers reference this while building,
+not when learning from scratch.
+
+<FrameworkCase frameworks={["react"]}>
+
+React-specific explanation or code example.
+
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+
+HTML-specific explanation or code example.
+
+</FrameworkCase>
+
+## Common patterns
+
+### Pattern name
+
+When to use this pattern.
+
+{/* Code example */}
+
+<Aside type="tip">
+Helpful optimization or best practice.
+</Aside>
+
+## Common pitfalls
+
+{/* ❌ Don't — explain why */}
+{/* ✅ Do — explain the fix */}
+
+## See also
+
+- <DocsLink slug="concepts/related-concept">Related concept</DocsLink>
+- <DocsLink slug="reference/related-component">Component reference</DocsLink>
+```
+
+## Checklist
+
+- [ ] Single concept per page
+- [ ] Code example in first 5 lines after description
+- [ ] Brief explanation (2-3 paragraphs max)
+- [ ] Framework-specific content uses `<FrameworkCase>`
+- [ ] Common pitfalls as do/don't
+- [ ] See also with 2-4 links
+- [ ] Scannable in under 2 minutes
diff --git a/.claude/skills/docs/templates/guide.md b/.claude/skills/docs/templates/guide.md
deleted file mode 100644
index c9077b75..00000000
--- a/.claude/skills/docs/templates/guide.md
+++ /dev/null
@@ -1,330 +0,0 @@
-# Guide Template
-
-Use this template for step-by-step tutorials that teach concepts.
-
-> **Use sparingly.** Most documentation should be handbook pages. Guides are only
-> for true tutorials: Getting Started, Building X from Scratch. If you're
-> documenting a single concept, use `templates/handbook.md` instead.
-
----
-
-## Template
-
-```markdown
-## Guide Title
-
-Brief description of what you'll build/learn.
-
-### What You'll Learn
-
-- Learning outcome 1
-- Learning outcome 2
-- Learning outcome 3
-
-### Prerequisites
-
-- [Getting Started](/guides/getting-started) completed
-- Basic knowledge of X
-- Node.js 18+
-
-### Time
-
-~15 minutes
-
----
-
-## Step 1: Setup
-
-Brief intro to this step.
-
-npm install @videojs/core
-
-Create your project structure:
-
-my-project/
-├── index.html
-├── main.ts
-└── styles.css
-
-> **Note:** You can also use the starter template:
-> `npx create-videojs-app my-project`
-
----
-
-## Step 2: Create the Player
-
-Explanation of what we're doing and why.
-
-import { createPlayer } from '@videojs/core';
-
-const player = createPlayer({
-src: 'video.mp4',
-});
-
-Let's break this down:
-
-- `createPlayer` — Factory function that creates a player instance
-- `src` — The video source URL
-
----
-
-## Step 3: Add Controls
-
-Now we'll add playback controls.
-
-import { createPlayer } from '@videojs/core';
-import { PlayButton, VolumeSlider } from '@videojs/dom';
-
-const player = createPlayer({ src: 'video.mp4' });
-
-const playButton = PlayButton({ player });
-const volume = VolumeSlider({ player });
-
-document.getElementById('controls').append(playButton, volume);
-
-:::tip
-The DOM components automatically sync with player state.
-:::
-
----
-
-## Step 4: Handle Events
-
-Listen to player events:
-
-player.on('play', () => {
-console.log('Playback started');
-});
-
-player.on('ended', () => {
-console.log('Video finished');
-});
-
-Common events:
-
-| Event   | Description      |
-| ------- | ---------------- |
-| `play`  | Playback started |
-| `pause` | Playback paused  |
-| `ended` | Video finished   |
-| `error` | Error occurred   |
-
----
-
-## Step 5: Style the Player
-
-Add custom styles:
-
-.player {
---player-accent-color: #3b82f6;
---player-bg: #000;
-}
-
-.player[data-fullscreen] {
-width: 100vw;
-height: 100vh;
-}
-
----
-
-## Complete Example
-
-Here's everything together:
-
-import { createPlayer } from '@videojs/core';
-import { PlayButton, VolumeSlider, Timeline } from '@videojs/dom';
-import './styles.css';
-
-// Create player
-const player = createPlayer({
-src: 'video.mp4',
-autoplay: false,
-});
-
-// Create controls
-const controls = document.getElementById('controls');
-controls.append(
-PlayButton({ player }),
-Timeline({ player }),
-VolumeSlider({ player }),
-);
-
-// Handle events
-player.on('error', (e) => {
-console.error('Player error:', e);
-});
-
-// Attach to video element
-const video = document.querySelector('video');
-await player.attach(video);
-
-[Open in StackBlitz →](https://stackblitz.com/edit/videojs-guide-example)
-
----
-
-## What's Next?
-
-You've learned the basics. Next steps:
-
-- [Add captions and subtitles](/guides/text-tracks)
-- [Build custom controls](/guides/custom-controls)
-- [Handle multiple sources](/guides/sources)
-
-### Related
-
-- [API Reference: createPlayer](/api/create-player)
-- [Handbook: Events](/handbook/events)
-- [Components: PlayButton](/components/play-button)
-```
-
----
-
-## Step Structure
-
-Each step should have:
-
-1. **Heading** — Clear action (`## Step N: Action`)
-2. **Intro** — Why we're doing this (1-2 sentences)
-3. **Code** — The code to write
-4. **Explanation** — What the code does
-5. **Notes/Tips** — Optional callouts
-
----
-
-## Callout Patterns
-
-```markdown
-:::note
-Additional context that's helpful but not required.
-:::
-
-:::tip
-Pro tip or best practice.
-:::
-
-:::warning
-Important caveat or common mistake.
-:::
-
-:::danger
-Critical warning — something that could break things.
-:::
-```
-
----
-
-## Progress Indicators
-
-Show progress through the guide:
-
-```markdown
-**Progress:** ██████░░░░ 60% complete
-```
-
-Or step indicators:
-
-```markdown
-Steps: [1] → [2] → **[3]** → [4] → [5]
-```
-
----
-
-## Code Evolution
-
-Show how code changes across steps:
-
-````markdown
-## Step 2
-
-Add event handling to our player:
-
-```ts
-const player = createPlayer({ src: 'video.mp4' });
-
-// highlight-start
-player.on('play', () => {
-  console.log('Playing');
-});
-// highlight-end
-```
-````
-
-Or use diff:
-
-```ts
-const player = createPlayer({ src: 'video.mp4' });
-
-+ player.on('play', () => {
-+   console.log('Playing');
-+ });
-```
-
----
-
-## Checkpoints
-
-Add verification points:
-
-```markdown
-## Step 3: Test It
-
-At this point, you should see:
-
-- [ ] Video element renders
-- [ ] Play button appears
-- [ ] Clicking play starts video
-
-If something's wrong, check:
-
-1. Is the video URL correct?
-2. Is the element attached?
-3. Check console for errors
-```
-
----
-
-## Branching Paths
-
-For guides with options:
-
-```markdown
-## Step 4: Choose Your Framework
-
-<Tabs>
-<Tab label="React">
-
-If you're using React, install the adapter:
-
-npm install @videojs/react
-
-[Continue with React →](#react-setup)
-
-</Tab>
-<Tab label="Vue">
-
-If you're using Vue, install the adapter:
-
-npm install @videojs/vue
-
-[Continue with Vue →](#vue-setup)
-
-</Tab>
-</Tabs>
-```
-
----
-
-## Checklist
-
-When writing guides:
-
-- [ ] Clear title stating what you'll build/learn
-- [ ] Prerequisites listed
-- [ ] Estimated time
-- [ ] Numbered steps with clear actions
-- [ ] Code examples at each step
-- [ ] Explanations of why, not just what
-- [ ] Complete working example at end
-- [ ] StackBlitz link for live testing
-- [ ] "What's Next" section with links
-- [ ] Related handbook/API pages linked
diff --git a/.claude/skills/docs/templates/handbook.md b/.claude/skills/docs/templates/handbook.md
deleted file mode 100644
index c6d211a0..00000000
--- a/.claude/skills/docs/templates/handbook.md
+++ /dev/null
@@ -1,251 +0,0 @@
-# Handbook Template
-
-Use this template for bite-sized reference pages. One concept, quickly scannable.
-
----
-
-## Template
-
-```markdown
-## Concept Name
-
-One-sentence description of the concept.
-
-### Quick Example
-
-// Minimal example showing the concept
-player.on('statechange', (state) => {
-  console.log(state);
-});
-
-### How It Works
-
-2-3 paragraphs explaining the concept. Keep it brief — users are
-referencing this while building, not learning from scratch.
-
-Key points:
-- Point one
-- Point two
-- Point three
-
-### Patterns
-
-#### Pattern A
-
-Description of when to use this pattern.
-
-// Code example
-const unsubscribe = player.subscribe((state) => {
-  updateUI(state);
-});
-
-// Cleanup
-unsubscribe();
-
-#### Pattern B
-
-Description of alternative pattern.
-
-// Code example
-player.on('volumechange', ({ volume }) => {
-  volumeDisplay.textContent = `${volume * 100}%`;
-});
-
-### Common Pitfalls
-
-#### Pitfall 1
-
-// ❌ Don't
-player.state.volume = 0.5; // Won't work
-
-// ✅ Do
-player.request.setVolume(0.5);
-
-#### Pitfall 2
-
-// ❌ Don't — memory leak
-useEffect(() => {
-  player.on('play', handler);
-}, []);
-
-// ✅ Do — cleanup
-useEffect(() => {
-  player.on('play', handler);
-  return () => player.off('play', handler);
-}, []);
-
-### Reference
-
-| Item | Description |
-|------|-------------|
-| `method1()` | Does X |
-| `method2()` | Does Y |
-| `property1` | Current X value |
-
-### See Also
-
-- [Related Concept](/handbook/related)
-- [API Reference](/api/relevant-api)
-- [Full Guide](/guides/detailed-guide)
-```
-
----
-
-## Handbook vs Guide
-
-| Handbook | Guide |
-|----------|-------|
-| Reference while working | Learning from scratch |
-| One concept per page | Multi-step narrative |
-| Scannable, minimal prose | Explains "why" |
-| ~500 words | ~1500 words |
-| No prerequisites | Has prerequisites |
-| Jump-in anywhere | Sequential steps |
-
----
-
-## Good Handbook Examples
-
-### Events (Short)
-
-```markdown
-## Events
-
-Subscribe to player events.
-
-player.on('play', () => console.log('Playing'));
-player.on('pause', () => console.log('Paused'));
-
-### Event List
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `play` | — | Playback started |
-| `pause` | — | Playback paused |
-| `ended` | — | Video ended |
-| `timeupdate` | `{ time }` | Time changed |
-| `volumechange` | `{ volume, muted }` | Volume changed |
-
-### Removing Listeners
-
-const handler = () => {};
-player.on('play', handler);
-player.off('play', handler);
-
-### See Also
-
-- [State](/handbook/state)
-- [Event API](/api/events)
-```
-
-### Styling (Medium)
-
-```markdown
-## Styling
-
-Style components with CSS using data attributes.
-
-.player[data-playing] .play-icon { display: none; }
-.player[data-paused] .pause-icon { display: none; }
-
-### Data Attributes
-
-Components expose state via `data-*` attributes:
-
-| Attribute | Component | Values |
-|-----------|-----------|--------|
-| `data-playing` | Player | boolean |
-| `data-paused` | Player | boolean |
-| `data-muted` | Player | boolean |
-| `data-fullscreen` | Player | boolean |
-| `data-dragging` | Slider | boolean |
-
-### CSS Variables
-
-Customize with CSS custom properties:
-
-.player {
-  --player-accent: #3b82f6;
-  --player-bg: #000;
-  --slider-height: 4px;
-}
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--player-accent` | `#fff` | Accent color |
-| `--player-bg` | `#000` | Background |
-| `--slider-height` | `4px` | Track height |
-
-### Tailwind
-
-<Slider.Root className="relative h-1 bg-gray-700">
-  <Slider.Fill className="absolute h-full bg-white" />
-  <Slider.Thumb className="absolute w-3 h-3 bg-white rounded-full" />
-</Slider.Root>
-
-### See Also
-
-- [Components](/components)
-- [Theming Guide](/guides/theming)
-```
-
----
-
-## Section Patterns
-
-### Quick Reference Table
-
-```markdown
-### Quick Reference
-
-| Task | Code |
-|------|------|
-| Play | `player.play()` |
-| Pause | `player.pause()` |
-| Seek | `player.seek(30)` |
-| Volume | `player.setVolume(0.5)` |
-| Mute | `player.setMuted(true)` |
-```
-
-### Comparison Table
-
-```markdown
-### State vs Requests
-
-| State | Requests |
-|-------|----------|
-| Readonly | Async methods |
-| Current values | Change values |
-| `player.state.volume` | `player.request.setVolume()` |
-| Synchronous read | Returns Promise |
-```
-
-### Decision Tree
-
-```markdown
-### Which API to Use?
-
-**Reading current value?**
-→ Use `player.state.propertyName`
-
-**Changing a value?**
-→ Use `player.request.methodName()`
-
-**Listening for changes?**
-→ Use `player.on('eventname', handler)`
-```
-
----
-
-## Checklist
-
-When writing handbook pages:
-
-- [ ] Single concept per page
-- [ ] Quick example at top (under 5 lines)
-- [ ] Brief explanation (2-3 paragraphs max)
-- [ ] Code patterns with labels
-- [ ] Common pitfalls as do/don't
-- [ ] Reference table if applicable
-- [ ] See Also with 2-4 links
-- [ ] Scannable in under 2 minutes
diff --git a/.claude/skills/docs/templates/how-to.md b/.claude/skills/docs/templates/how-to.md
new file mode 100644
index 00000000..2ba1cc52
--- /dev/null
+++ b/.claude/skills/docs/templates/how-to.md
@@ -0,0 +1,98 @@
+# How-to Guide Template
+
+Use for step-by-step guides that achieve a specific outcome.
+
+> **Use sparingly.** Most documentation should be concept pages. Only use how-to guides
+> when the reader needs multi-step instructions to build something specific.
+
+## Frontmatter
+
+```yaml
+---
+title: 'Achieve specific outcome'
+description: 'Step-by-step guide to accomplish X'
+---
+```
+
+## Page structure
+
+```mdx
+---
+title: 'Build a custom player'
+description: 'Step-by-step guide to building a player from scratch'
+---
+
+import FrameworkCase from '@/components/docs/FrameworkCase.astro';
+import Aside from '@/components/Aside.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+
+Brief description of what you'll build. One sentence.
+
+### Prerequisites
+
+- Familiarity with <DocsLink slug="concepts/prerequisite">prerequisite concept</DocsLink>
+- Node.js 18+
+
+## Step 1: Set up
+
+Brief intro — what we're doing and why.
+
+{/* Code for this step */}
+
+<Aside type="note">
+Supplementary context that isn't critical to the step.
+</Aside>
+
+## Step 2: Next action
+
+What we're doing and why.
+
+<FrameworkCase frameworks={["react"]}>
+
+{/* React-specific code */}
+
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+
+{/* HTML-specific code */}
+
+</FrameworkCase>
+
+## Step 3: Final step
+
+Last piece of the puzzle.
+
+{/* Code */}
+
+## Complete example
+
+Everything together in one runnable block:
+
+{/* Full working example with all imports */}
+
+## What's next?
+
+- <DocsLink slug="concepts/next-concept">Deeper concept</DocsLink>
+- <DocsLink slug="how-to/next-guide">Follow-up guide</DocsLink>
+- <DocsLink slug="reference/related-component">Component reference</DocsLink>
+```
+
+## Step structure
+
+Each step should have:
+
+1. **Heading** — clear action (`## Step N: Action`)
+2. **Intro** — why we're doing this (1-2 sentences)
+3. **Code** — the code to write
+4. **Explanation** — what the code does (only if not obvious)
+
+## Checklist
+
+- [ ] Clear title stating what you'll build or achieve
+- [ ] Prerequisites listed
+- [ ] Numbered steps with clear actions
+- [ ] Code example at each step
+- [ ] Framework-specific content uses `<FrameworkCase>`
+- [ ] Complete working example at end
+- [ ] "What's next?" section with links
diff --git a/.claude/skills/docs/templates/migration-guide.md b/.claude/skills/docs/templates/migration-guide.md
deleted file mode 100644
index 102ecff8..00000000
--- a/.claude/skills/docs/templates/migration-guide.md
+++ /dev/null
@@ -1,313 +0,0 @@
-# Migration Guide Template
-
-Use this template for version migration documentation.
-
----
-
-## Template
-
-```markdown
-## Migrating from vX to vY
-
-This guide covers migrating from Video.js X to Video.js Y.
-
-### Overview
-
-Video.js Y introduces [major changes]. This guide will help you update your code.
-
-**Estimated time:** 30-60 minutes for typical projects
-
-### Breaking Changes Summary
-
-| Change | Impact | Migration |
-|--------|--------|-----------|
-| `oldApi()` removed | High | Use `newApi()` |
-| Config format changed | Medium | Update config |
-| Event renamed | Low | Rename handlers |
-
-### Automated Migration
-
-Run the codemod to handle most changes automatically:
-
-npx @videojs/codemod v9-to-v10
-
-This handles:
-- ✅ API renames
-- ✅ Config format updates
-- ✅ Import path changes
-- ⚠️ Manual review needed for custom plugins
-
-### Step-by-Step Migration
-
-#### 1. Update Dependencies
-
-npm install @videojs/core@10
-
-If using framework adapters:
-
-npm install @videojs/react@10 @videojs/vue@10
-
-#### 2. Update Imports
-
-// ❌ v9
-import videojs from 'video.js';
-
-// ✅ v10
-import { createPlayer } from '@videojs/core';
-
-#### 3. Update Player Creation
-
-// ❌ v9
-const player = videojs('my-video', {
-  sources: [{ src: 'video.mp4', type: 'video/mp4' }],
-  autoplay: true,
-});
-
-// ✅ v10
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-});
-
-await player.attach(document.getElementById('my-video'));
-
-#### 4. Update Event Handlers
-
-// ❌ v9
-player.on('loadedmetadata', function() {
-  console.log(this.duration());
-});
-
-// ✅ v10
-player.on('loadedmetadata', () => {
-  console.log(player.state.duration);
-});
-
-#### 5. Update Method Calls
-
-| v9 | v10 |
-|----|-----|
-| `player.play()` | `await player.request.play()` |
-| `player.pause()` | `player.request.pause()` |
-| `player.currentTime(30)` | `player.request.seek(30)` |
-| `player.volume(0.5)` | `player.request.setVolume(0.5)` |
-| `player.muted(true)` | `player.request.setMuted(true)` |
-
-#### 6. Update State Access
-
-// ❌ v9 — getter methods
-const time = player.currentTime();
-const vol = player.volume();
-const dur = player.duration();
-
-// ✅ v10 — state object
-const { currentTime, volume, duration } = player.state;
-
-#### 7. Update Plugins
-
-// ❌ v9
-videojs.registerPlugin('myPlugin', function(options) {
-  const player = this;
-  // plugin code
-});
-
-player.myPlugin({ option: 'value' });
-
-// ✅ v10
-function myPlugin(player, options) {
-  // plugin code
-  return {
-    destroy() {
-      // cleanup
-    },
-  };
-}
-
-player.use(myPlugin, { option: 'value' });
-
-### Removed APIs
-
-These APIs have been removed with no direct replacement:
-
-| Removed | Alternative |
-|---------|-------------|
-| `player.tech()` | Use `player.state` for media info |
-| `player.el()` | Pass element to `attach()` |
-| `player.addClass()` | Use CSS classes directly |
-
-### Changed Behaviors
-
-#### Autoplay
-
-v10 follows browser autoplay policies more strictly:
-
-// v10 — autoplay requires muted
-const player = createPlayer({
-  src: 'video.mp4',
-  autoplay: true,
-  muted: true, // Required for autoplay in most browsers
-});
-
-#### Error Handling
-
-// v10 — requests can fail
-const result = await player.request.play();
-
-if (!result.success) {
-  console.error(result.error);
-}
-
-### Framework Adapter Changes
-
-#### React
-
-// ❌ v9
-import { Player } from 'video.js/react';
-
-<Player>
-  <source src="video.mp4" type="video/mp4" />
-</Player>
-
-// ✅ v10
-import { Player } from '@videojs/react';
-
-<Player src="video.mp4" />
-
-#### Vue
-
-// ❌ v9
-import VideoPlayer from 'video.js/vue';
-
-// ✅ v10
-import { Player } from '@videojs/vue';
-
-### TypeScript Changes
-
-Types are now included in the package:
-
-// ❌ v9
-npm install @types/video.js
-
-// ✅ v10 — types included
-import type { Player, PlayerOptions } from '@videojs/core';
-
-### CSS Changes
-
-// ❌ v9
-@import 'video.js/dist/video-js.css';
-
-// ✅ v10 — optional, components are unstyled
-@import '@videojs/dom/styles.css'; // Optional base styles
-
-### Testing Updates
-
-// ❌ v9
-const player = videojs(document.createElement('video'));
-
-// ✅ v10
-import { createTestPlayer } from '@videojs/test-utils';
-
-const player = createTestPlayer();
-
-### Troubleshooting
-
-#### "createPlayer is not a function"
-
-Check your import:
-
-// ❌ Wrong
-import createPlayer from '@videojs/core';
-
-// ✅ Correct
-import { createPlayer } from '@videojs/core';
-
-#### "Cannot read property 'play' of undefined"
-
-Ensure player is attached:
-
-const player = createPlayer({ src: 'video.mp4' });
-await player.attach(videoElement); // Don't forget this!
-await player.request.play();
-
-#### Plugin not working
-
-Update plugin registration:
-
-// Old way doesn't work
-videojs.registerPlugin('myPlugin', fn);
-
-// Use the new API
-player.use(myPlugin, options);
-
-### Getting Help
-
-- [GitHub Discussions](https://github.com/videojs/video.js/discussions)
-- [Discord](https://discord.gg/videojs)
-- [Migration FAQ](/guides/migration-faq)
-
-### Changelog
-
-See [CHANGELOG.md](https://github.com/videojs/video.js/blob/main/CHANGELOG.md) for complete list of changes.
-```
-
----
-
-## Codemod Documentation
-
-If providing automated migration:
-
-```markdown
-## Codemod
-
-### Installation
-
-npx @videojs/codemod --help
-
-### Usage
-
-# Dry run (preview changes)
-npx @videojs/codemod v9-to-v10 --dry
-
-# Apply changes
-npx @videojs/codemod v9-to-v10
-
-# Specific directory
-npx @videojs/codemod v9-to-v10 ./src
-
-### What It Transforms
-
-| Transform | Before | After |
-|-----------|--------|-------|
-| `imports` | `import videojs from 'video.js'` | `import { createPlayer } from '@videojs/core'` |
-| `creation` | `videojs('id', opts)` | `createPlayer(opts)` |
-| `methods` | `player.currentTime()` | `player.state.currentTime` |
-
-### Manual Review Required
-
-The codemod marks these for manual review:
-
-// TODO: @videojs/codemod - Review plugin registration
-player.myPlugin();
-
-// TODO: @videojs/codemod - Review tech access
-player.tech();
-```
-
----
-
-## Checklist
-
-When writing migration guides:
-
-- [ ] Overview with estimated time
-- [ ] Breaking changes summary table
-- [ ] Codemod instructions (if available)
-- [ ] Step-by-step with before/after code
-- [ ] API mapping table (old → new)
-- [ ] Removed APIs documented
-- [ ] Behavior changes explained
-- [ ] Framework-specific sections
-- [ ] TypeScript changes
-- [ ] CSS changes
-- [ ] Troubleshooting section
-- [ ] Links to help resources
diff --git a/.claude/skills/docs/templates/readme.md b/.claude/skills/docs/templates/readme.md
index c1abc68a..05bc42ba 100644
--- a/.claude/skills/docs/templates/readme.md
+++ b/.claude/skills/docs/templates/readme.md
@@ -1,274 +1,140 @@
 # README Template
 
-Use this template for package README files.
+Guide for writing package READMEs. See `packages/store/README.md` as the exemplar.
 
----
+## Light vs comprehensive
 
-## Decision: Light vs Comprehensive
+| Factor | Light | Comprehensive |
+|--------|-------|---------------|
+| Package has site docs | Yes — link to them | No — README is the primary docs |
+| API surface | Small, few exports | Large, many concepts |
+| Target audience | Already using Video.js | Evaluating or onboarding |
+| Examples needed | 1 quick example | Multiple, progressive |
 
-| Condition                        | Use           |
-| -------------------------------- | ------------- |
-| Site docs exist for this package | Light         |
-| No site docs yet                 | Comprehensive |
-| Internal/utility package         | Light         |
-| Primary entry point for users    | Comprehensive |
+Most packages should use the **light** template. Use comprehensive when the README is the primary documentation surface (e.g., `@videojs/store`).
 
-**Current state:**
-
-- `@videojs/store` — Comprehensive (exemplar)
-- `@videojs/core`, `@videojs/html`, `@videojs/react` — Need upgrade
-
----
-
-## Light Template
+## Light template
 
 ```markdown
-# @videojs/{package}
+# @videojs/{name}
 
 [![package-badge]][package]
 
 > **⚠️ Alpha - SUBJECT TO CHANGE** Not recommended for production use.
 
-One-sentence description of what this package provides.
+{One-sentence description of what this package does.}
 
-## Install
+```bash
+npm install @videojs/{name}
+```
 
-npm install @videojs/{package}
+## Usage
 
-## Quick Start
+```ts
+import { ... } from '@videojs/{name}';
 
-import { mainExport } from '@videojs/{package}';
+// Minimal working example
+```
 
-// 3-5 lines showing core usage
+## Documentation
 
-[Full documentation →](https://videojs.com/docs/{package})
+For full documentation, see the [Video.js docs](https://videojs.com/docs).
 
 ## Community
 
-- [Discord][discord]
-- [GitHub Discussions][discussions]
+If you need help with anything related to Video.js v10, or if you'd like to casually chat with other
+members:
+
+- [Join Discord Server][discord]
+- [See GitHub Discussions][gh-discussions]
 
 ## License
 
 [Apache-2.0](./LICENSE)
 
-[package]: https://www.npmjs.com/package/@videojs/{package}
-[package-badge]: https://img.shields.io/npm/v/@videojs/{package}/next
+[package]: https://www.npmjs.com/package/@videojs/{name}
+[package-badge]: https://img.shields.io/npm/v/@videojs/{name}/next?label=@videojs/{name}@next
 [discord]: https://discord.gg/JBqHh485uF
-[discussions]: https://github.com/videojs/v10/discussions
+[gh-discussions]: https://github.com/videojs/v10/discussions
 ```
 
----
+## Comprehensive template
 
-## Comprehensive Template
-
-Follow `@videojs/store` README structure:
-
-### Required Sections (in order)
-
-1. **Title + Badge**
-2. **Alpha Warning**
-3. **Overview** (2-3 sentences + install + minimal example)
-4. **Why?** (problem statement, what makes this different)
-5. **Core Concepts** (h3 per concept with code examples)
-6. **Advanced** (optional, for power users)
-7. **How It's Different** (comparison table if applicable)
-8. **Community**
-9. **License**
-
-### Structure
+Use this structure when the README is the primary documentation for the package. Based on `packages/store/README.md`.
 
 ```markdown
-# @videojs/{package}
+# @videojs/{name}
 
 [![package-badge]][package]
 
 > **⚠️ Alpha - SUBJECT TO CHANGE** Not recommended for production use.
 
-Brief description (2-3 sentences).
+{One-sentence description.}
 
-npm install @videojs/{package}
-
-import { mainExport } from '@videojs/{package}';
-
-// Minimal working example (5-10 lines)
+```bash
+npm install @videojs/{name}
+```
 
 ## Why?
 
-[Problem statement]
+{Motivation — what problem does this solve? Why not use X instead?}
 
-Traditional approach assumes X. But when working with Y, you need Z.
-
-`@videojs/{package}` embraces this model:
-
-- **Point one**: Description
-- **Point two**: Description
+```ts
+// Quick example showing the core value proposition
+```
 
 ## Core Concepts
 
-### Concept One
+### {Concept A}
 
-Explanation.
+{Explanation with code example.}
 
-// Code example
+### {Concept B}
 
-### Concept Two
+{Explanation with code example.}
 
-Explanation.
+## {Main API}
 
-// Code example
+{Primary API surface with examples.}
 
-## Advanced
+### {Sub-topic}
 
-[Optional section for power users]
-
-## How It's Different
-
-|            | Alternative A | Alternative B | @videojs/{package} |
-| ---------- | ------------- | ------------- | ------------------ |
-| **Aspect** | ...           | ...           | ...                |
+{Progressive detail.}
 
 ## Community
 
-- [Discord][discord]
-- [GitHub Discussions][discussions]
+If you need help with anything related to Video.js v10, or if you'd like to casually chat with other
+members:
+
+- [Join Discord Server][discord]
+- [See GitHub Discussions][gh-discussions]
 
 ## License
 
 [Apache-2.0](./LICENSE)
 
-[package]: https://www.npmjs.com/package/@videojs/{package}
-[package-badge]: https://img.shields.io/npm/v/@videojs/{package}/next
-[discord]: https://discord.gg/JBqHh485uF
-[discussions]: https://github.com/videojs/v10/discussions
-```
-
----
-
-## Package-Specific Sections
-
-### @videojs/store
-
-Core concepts:
-
-- Target
-- Features (defineFeature, state factory)
-- Feature Type Inference
-- Actions (task helper, sync mutations)
-- Action Metadata (store.meta())
-- Store (flat access, pending tasks)
-- Task Configuration (Keys, Modes, Cancels)
-- Error Handling
-
-### @videojs/store/html
-
-Core concepts:
-
-- Controllers (StoreController, SubscriptionController)
-- Mixins (StoreMixin, ProviderMixin, ContainerMixin)
-- createStore factory pattern
-- Context API
-
-### @videojs/core/dom
-
-Core concepts:
-
-- Media features: volumeFeature, playbackFeature, timeFeature, sourceFeature, bufferFeature
-- `media.all` array
-- Type exports (VolumeState, PlaybackRequests, etc.)
-
-### @videojs/html
-
-Core concepts:
-
-- FrostedSkinElement
-- `define()` pattern
-- Slot-based composition
-- Extending with custom features
-
-### @videojs/react
-
-Core concepts:
-
-- Components
-- Hooks
-- Context Providers
-
----
-
-## Patterns
-
-### Alpha Warning
-
-Always include at top:
-
-```markdown
-> **⚠️ Alpha - SUBJECT TO CHANGE** Not recommended for production use.
-```
-
-### Install → Example Progression
-
-1. Install command
-2. Imports
-3. Minimal working code (5-10 lines)
-4. [More complex examples in later sections]
-
-```markdown
-npm install @videojs/store
-
-import { createStore } from '@videojs/store';
-
-const store = createStore({
-features: [playbackFeature, volumeFeature],
-});
-
-store.attach(videoElement);
-await store.play();
-```
-
-### "How It's Different" Table
-
-Use when comparing to alternatives:
-
-```markdown
-|               | Redux/Zustand | React Query           | @videojs/store             |
-| ------------- | ------------- | --------------------- | -------------------------- |
-| **Authority** | You own state | Server owns state     | External system owns state |
-| **Mutations** | Sync reducers | Async server requests | Async requests to target   |
-```
-
-### Type Inference Export Pattern
-
-Always show type inference for TypeScript users:
-
-```ts
-import type { InferFeatureState } from '@videojs/store';
-
-type VolumeState = InferFeatureState<typeof volumeFeature>;
-// { volume: number; muted: boolean; changeVolume: ...; toggleMute: ... }
-```
-
-### Links Footer
-
-```markdown
 [package]: https://www.npmjs.com/package/@videojs/{name}
-[package-badge]: https://img.shields.io/npm/v/@videojs/{name}/next
+[package-badge]: https://img.shields.io/npm/v/@videojs/{name}/next?label=@videojs/{name}@next
 [discord]: https://discord.gg/JBqHh485uF
-[discussions]: https://github.com/videojs/v10/discussions
+[gh-discussions]: https://github.com/videojs/v10/discussions
 ```
 
----
+## Conventions
+
+- **Badge:** Always use the `/next` tag badge during alpha.
+- **Alpha warning:** Include the blockquote warning until stable release.
+- **Code examples:** Must be self-contained — include imports, use realistic values.
+- **Progressive disclosure:** Start simple, add complexity in later sections.
+- **No inline animation JS or framework code** — READMEs show the package API, not framework integration.
+- **Link definitions at bottom** — Keep URLs as reference-style links at the end.
 
 ## Checklist
 
-When writing READMEs:
-
-- [ ] Badge links to npm @next tag
-- [ ] Alpha warning present
-- [ ] Install command shown first
-- [ ] Working example within 30 seconds of reading
-- [ ] All code examples self-contained (include imports)
-- [ ] Type inference patterns shown for TS users
-- [ ] Community links (Discord, Discussions)
-- [ ] License stated
-- [ ] Follows package-specific section guidance
+- [ ] npm badge with `/next` tag
+- [ ] Alpha warning blockquote
+- [ ] Install command
+- [ ] Working quick example with imports
+- [ ] Self-contained code examples (copy-paste and run)
+- [ ] Community section with Discord + Discussions
+- [ ] License section
+- [ ] Reference-style links at bottom
diff --git a/.claude/skills/gh-issue/SKILL.md b/.claude/skills/gh-issue/SKILL.md
index 6fb032f1..6be68a99 100644
--- a/.claude/skills/gh-issue/SKILL.md
+++ b/.claude/skills/gh-issue/SKILL.md
@@ -77,7 +77,8 @@ Based on detected type, load the relevant skill for domain expertise:
 | ------------------------------- | ----------- | ------------------------------------------------------------- |
 | API proposal, RFC, architecture | `api`       | Extensibility, progressive disclosure, type safety principles |
 | DX, ergonomics, types           | `api`       | DX principles, TypeScript patterns, state/adapter patterns    |
-| Documentation                   | `docs`      | Tone, structure, code examples, doc types                     |
+| Documentation                   | `docs`          | Tone, structure, code examples, Diátaxis types            |
+| Component reference pages       | `api-reference` | API reference page structure, builder conventions         |
 | Accessibility                   | `aria`      | Keyboard, focus, ARIA patterns                                |
 | UI component implementation     | `component` | Compound components, polymorphism, styling patterns           |
 | Bug/Feature (general)           | `api`       | General principles apply                                      |
diff --git a/.claude/skills/review-branch/SKILL.md b/.claude/skills/review-branch/SKILL.md
index 5a572b32..7b187348 100644
--- a/.claude/skills/review-branch/SKILL.md
+++ b/.claude/skills/review-branch/SKILL.md
@@ -53,7 +53,8 @@ Categorize the changed files to determine which review criteria apply:
 | ---------------------------------------------- | ------------- | ------------------- |
 | `packages/*/src/**/*.ts` (non-test)            | API/Code      | `api`               |
 | `packages/html/**`, `packages/react/**` (UI)   | UI Components | `component`, `aria` |
-| `site/**/*.md`, `**/README.md`, `**/CLAUDE.md` | Documentation | `docs`              |
+| `site/**/*.md`, `**/README.md`, `**/CLAUDE.md` | Documentation | `docs`               |
+| `site/**/reference/*.mdx`                      | API Reference | `api-reference`      |
 | `packages/*/src/**/*.test.ts`                  | Tests         | General review      |
 | `.claude/**`                                   | Agent Config  | General review      |
 | Config files (`.json`, `.config.*`)            | Configuration | General review      |
@@ -71,7 +72,7 @@ For deeper domain-specific review, load the relevant skill:
 | API/Code      | `api`       | `api/review/workflow.md`       |
 | UI Components | `component` | `component/review/workflow.md` |
 | UI Components | `aria`      | `aria/review/workflow.md`      |
-| Documentation | `docs`      | `docs/review/workflow.md`      |
+| Documentation | `docs` | `docs/review/workflow.md` |
 
 Skip this step for quick reviews using the inline checklists below.
 
@@ -84,7 +85,7 @@ Based on detected categories, load the relevant skill's review checklist:
 | API/Code      | `api/review/checklist.md`          |
 | UI Components | `component/review/checklist.md`    |
 | Accessibility | `aria/review/checklist.md`         |
-| Documentation | `docs/review/workflow.md`          |
+| Documentation | `docs/review/workflow.md`    |
 
 For test changes, apply these checks:
 
diff --git a/.claude/skills/rfc/SKILL.md b/.claude/skills/rfc/SKILL.md
index 6634191b..b89239e8 100644
--- a/.claude/skills/rfc/SKILL.md
+++ b/.claude/skills/rfc/SKILL.md
@@ -78,4 +78,4 @@ For detailed writing guidance (progressive disclosure, conciseness, etc.), see t
 | Decisions you own          | `design` skill    |
 | API design principles      | `api` skill       |
 | Building UI components     | `component` skill |
-| Writing documentation      | `docs` skill      |
+| Writing documentation      | `docs` skill |
diff --git a/CLAUDE.md b/CLAUDE.md
index 45ab9ea6..f3424ea4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -508,13 +508,14 @@ export type FeatureAvailability = 'available' | 'unavailable' | 'unsupported';
 
 CLAUDE.md contains repo-wide conventions. Domain-specific patterns live in skills:
 
-| Domain                      | Location             |
-| --------------------------- | -------------------- |
-| Naming, testing, utilities  | CLAUDE.md Code Rules |
-| Component patterns and APIs | `component` skill    |
-| Accessibility               | `aria` skill         |
-| Documentation               | `docs` skill         |
-| API design and DX           | `api` skill          |
-| Updating AI docs            | `claude-update` skill |
+| Domain                      | Location                   |
+| --------------------------- | -------------------------- |
+| Naming, testing, utilities  | CLAUDE.md Code Rules       |
+| Component patterns and APIs | `component` skill          |
+| Accessibility               | `aria` skill               |
+| Documentation               | `docs` skill               |
+| Component reference pages   | `api-reference` skill      |
+| API design and DX           | `api` skill                |
+| Updating AI docs            | `claude-update` skill      |
 
 When adding a new rule, ask: "Who needs this?" If it's domain-specific, put it in the relevant skill.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0cc626e5..d28b3506 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -160,7 +160,7 @@ Domain-specific knowledge lives in `.claude/skills/`:
 | `api`       | Designing APIs, reviewing architecture  |
 | `component` | Building UI components                  |
 | `aria`      | Accessibility implementation and review |
-| `docs`      | Writing documentation                   |
+| `docs`       | Writing documentation                  |
 | `git`       | Commit messages, PR conventions         |
 
 See [`.claude/skills/README.md`](./.claude/skills/README.md) for workflow mappings.
diff --git a/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.css b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.css
index da2236a6..55048621 100644
--- a/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.css
+++ b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.css
@@ -1,11 +1,11 @@
-.buffering-indicator-basic {
+.html-buffering-indicator-basic {
   display: flex;
   width: 100%;
   height: 100%;
   position: relative;
 }
 
-.buffering-indicator-basic__overlay {
+.html-buffering-indicator-basic__overlay {
   position: absolute;
   inset: 0;
   display: flex;
@@ -15,15 +15,15 @@
   z-index: 30;
 }
 
-.buffering-indicator-basic__overlay .buffering-indicator-basic__spinner {
+.html-buffering-indicator-basic__overlay .html-buffering-indicator-basic__spinner {
   display: none;
 }
 
-.buffering-indicator-basic__overlay[data-visible] .buffering-indicator-basic__spinner {
+.html-buffering-indicator-basic__overlay[data-visible] .html-buffering-indicator-basic__spinner {
   display: block;
 }
 
-.buffering-indicator-basic__spinner {
+.html-buffering-indicator-basic__spinner {
   width: 48px;
   height: 48px;
   border: 4px solid rgba(255, 255, 255, 0.3);
diff --git a/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.html b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.html
index 3e8e7265..2572a7ff 100644
--- a/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.html
+++ b/site/src/components/docs/demos/buffering-indicator/html/css/BasicUsage.html
@@ -1,4 +1,4 @@
-<video-player class="buffering-indicator-basic">
+<video-player class="html-buffering-indicator-basic">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,7 +6,7 @@
         playsinline
         loop
     ></video>
-    <media-buffering-indicator class="buffering-indicator-basic__overlay">
-        <div class="buffering-indicator-basic__spinner"></div>
+    <media-buffering-indicator class="html-buffering-indicator-basic__overlay">
+        <div class="html-buffering-indicator-basic__spinner"></div>
     </media-buffering-indicator>
 </video-player>
diff --git a/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.css b/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.css
index da2236a6..89f9766b 100644
--- a/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.css
+++ b/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.css
@@ -1,11 +1,11 @@
-.buffering-indicator-basic {
+.react-buffering-indicator-basic {
   display: flex;
   width: 100%;
   height: 100%;
   position: relative;
 }
 
-.buffering-indicator-basic__overlay {
+.react-buffering-indicator-basic__overlay {
   position: absolute;
   inset: 0;
   display: flex;
@@ -15,15 +15,15 @@
   z-index: 30;
 }
 
-.buffering-indicator-basic__overlay .buffering-indicator-basic__spinner {
+.react-buffering-indicator-basic__overlay .react-buffering-indicator-basic__spinner {
   display: none;
 }
 
-.buffering-indicator-basic__overlay[data-visible] .buffering-indicator-basic__spinner {
+.react-buffering-indicator-basic__overlay[data-visible] .react-buffering-indicator-basic__spinner {
   display: block;
 }
 
-.buffering-indicator-basic__spinner {
+.react-buffering-indicator-basic__spinner {
   width: 48px;
   height: 48px;
   border: 4px solid rgba(255, 255, 255, 0.3);
diff --git a/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx b/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx
index bd0baba9..aa60ae56 100644
--- a/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/buffering-indicator/react/css/BasicUsage.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function BasicUsage() {
   return (
     <Player.Provider>
-      <Player.Container className="buffering-indicator-basic">
+      <Player.Container className="react-buffering-indicator-basic">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -16,9 +16,9 @@ export default function BasicUsage() {
           loop
         />
         <BufferingIndicator
-          className="buffering-indicator-basic__overlay"
+          className="react-buffering-indicator-basic__overlay"
           render={(props, state) => (
-            <div {...props}>{state.visible && <div className="buffering-indicator-basic__spinner" />}</div>
+            <div {...props}>{state.visible && <div className="react-buffering-indicator-basic__spinner" />}</div>
           )}
         />
       </Player.Container>
diff --git a/site/src/components/docs/demos/controls/html/css/BasicUsage.css b/site/src/components/docs/demos/controls/html/css/BasicUsage.css
index 05944d72..bafea709 100644
--- a/site/src/components/docs/demos/controls/html/css/BasicUsage.css
+++ b/site/src/components/docs/demos/controls/html/css/BasicUsage.css
@@ -1,13 +1,13 @@
-.controls-basic {
+.html-controls-basic {
   display: block;
   position: relative;
 }
 
-.controls-basic video {
+.html-controls-basic video {
   width: 100%;
 }
 
-.controls-basic__root {
+.html-controls-basic__root {
   position: absolute;
   inset: 0;
   display: flex;
@@ -18,15 +18,15 @@
   transition: opacity 0.25s;
 }
 
-.controls-basic__root:not([data-visible]) {
+.html-controls-basic__root:not([data-visible]) {
   opacity: 0;
 }
 
-.controls-basic__bottom {
+.html-controls-basic__bottom {
   pointer-events: auto;
 }
 
-.controls-basic__time {
+.html-controls-basic__time {
   display: inline-flex;
   align-items: center;
   gap: 4px;
@@ -40,14 +40,14 @@
   font-size: 14px;
 }
 
-.controls-basic__bottom {
+.html-controls-basic__bottom {
   display: flex;
   align-items: center;
   justify-content: space-between;
   width: 100%;
 }
 
-.controls-basic__button {
+.html-controls-basic__button {
   padding-block: 8px;
   background: rgba(255, 255, 255, 0.75);
   backdrop-filter: blur(10px);
@@ -59,15 +59,15 @@
   cursor: pointer;
 }
 
-.controls-basic__button .show-when-paused,
-.controls-basic__button .show-when-playing {
+.html-controls-basic__button .show-when-paused,
+.html-controls-basic__button .show-when-playing {
   display: none;
 }
 
-.controls-basic__play[data-paused] .show-when-paused {
+.html-controls-basic__play[data-paused] .show-when-paused {
   display: inline;
 }
 
-.controls-basic__play:not([data-paused]) .show-when-playing {
+.html-controls-basic__play:not([data-paused]) .show-when-playing {
   display: inline;
 }
diff --git a/site/src/components/docs/demos/controls/html/css/BasicUsage.html b/site/src/components/docs/demos/controls/html/css/BasicUsage.html
index f434bed5..d01832b4 100644
--- a/site/src/components/docs/demos/controls/html/css/BasicUsage.html
+++ b/site/src/components/docs/demos/controls/html/css/BasicUsage.html
@@ -1,4 +1,4 @@
-<video-player class="controls-basic">
+<video-player class="html-controls-basic">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -7,13 +7,13 @@
         loop
     ></video>
 
-    <media-controls class="controls-basic__root">
-        <media-controls-group class="controls-basic__bottom" aria-label="Playback controls">
-            <media-play-button class="controls-basic__button controls-basic__play">
+    <media-controls class="html-controls-basic__root">
+        <media-controls-group class="html-controls-basic__bottom" aria-label="Playback controls">
+            <media-play-button class="html-controls-basic__button html-controls-basic__play">
                 <span class="show-when-paused">Play</span>
                 <span class="show-when-playing">Pause</span>
             </media-play-button>
-            <media-time class="controls-basic__time" type="current"></media-time>
+            <media-time class="html-controls-basic__time" type="current"></media-time>
         </media-controls-group>
     </media-controls>
 </video-player>
diff --git a/site/src/components/docs/demos/controls/react/css/BasicUsage.css b/site/src/components/docs/demos/controls/react/css/BasicUsage.css
index 9f99bc9e..4e00d4ac 100644
--- a/site/src/components/docs/demos/controls/react/css/BasicUsage.css
+++ b/site/src/components/docs/demos/controls/react/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.controls-basic {
+.react-controls-basic {
   position: relative;
 }
 
-.controls-basic video {
+.react-controls-basic video {
   width: 100%;
 }
 
-.controls-basic__root {
+.react-controls-basic__root {
   position: absolute;
   inset: 0;
   display: flex;
@@ -17,15 +17,15 @@
   transition: opacity 0.25s;
 }
 
-.controls-basic__root:not([data-visible]) {
+.react-controls-basic__root:not([data-visible]) {
   opacity: 0;
 }
 
-.controls-basic__bottom {
+.react-controls-basic__bottom {
   pointer-events: auto;
 }
 
-.controls-basic__time {
+.react-controls-basic__time {
   display: inline-flex;
   align-items: center;
   gap: 4px;
@@ -39,14 +39,14 @@
   font-size: 14px;
 }
 
-.controls-basic__bottom {
+.react-controls-basic__bottom {
   display: flex;
   align-items: center;
   justify-content: space-between;
   width: 100%;
 }
 
-.controls-basic__button {
+.react-controls-basic__button {
   padding-block: 8px;
   background: rgba(255, 255, 255, 0.75);
   backdrop-filter: blur(10px);
diff --git a/site/src/components/docs/demos/controls/react/css/BasicUsage.tsx b/site/src/components/docs/demos/controls/react/css/BasicUsage.tsx
index b98e65e3..98be27fb 100644
--- a/site/src/components/docs/demos/controls/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/controls/react/css/BasicUsage.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function BasicUsage() {
   return (
     <Player.Provider>
-      <Player.Container className="controls-basic">
+      <Player.Container className="react-controls-basic">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -16,14 +16,14 @@ export default function BasicUsage() {
           loop
         />
 
-        <Controls.Root className="controls-basic__root">
-          <Controls.Group className="controls-basic__bottom" aria-label="Playback controls">
+        <Controls.Root className="react-controls-basic__root">
+          <Controls.Group className="react-controls-basic__bottom" aria-label="Playback controls">
             <PlayButton
-              className="controls-basic__button"
+              className="react-controls-basic__button"
               render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
             />
 
-            <Time.Value type="current" className="controls-basic__time" />
+            <Time.Value type="current" className="react-controls-basic__time" />
           </Controls.Group>
         </Controls.Root>
       </Player.Container>
diff --git a/site/src/components/docs/demos/fullscreen-button/html/css/BasicUsage.css b/site/src/components/docs/demos/fullscreen-button/html/css/BasicUsage.css
index 5ad0a6c7..59e108f6 100644
--- a/site/src/components/docs/demos/fullscreen-button/html/css/BasicUsage.css
+++ b/site/src/components/docs/demos/fullscreen-button/html/css/BasicUsage.css
@@ -1,13 +1,13 @@
-.fullscreen-button-basic {
+.html-fullscreen-button-basic {
   display: block;
   position: relative;
 }
 
-.fullscreen-button-basic video {
+.html-fullscreen-button-basic video {
   width: 100%;
 }
 
-.fullscreen-button-basic__button {
+.html-fullscreen-button-basic__button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
@@ -21,15 +21,15 @@
   cursor: pointer;
 }
 
-.fullscreen-button-basic__button .show-when-fullscreen {
+.html-fullscreen-button-basic__button .show-when-fullscreen {
   display: none;
 }
-.fullscreen-button-basic__button .show-when-not-fullscreen {
+.html-fullscreen-button-basic__button .show-when-not-fullscreen {
   display: none;
 }
-.fullscreen-button-basic__button[data-fullscreen] .show-when-fullscreen {
+.html-fullscreen-button-basic__button[data-fullscreen] .show-when-fullscreen {
   display: inline;
 }
-.fullscreen-button-basic__button:not([data-fullscreen]) .show-when-not-fullscreen {
+.html-fullscreen-button-basic__button:not([data-fullscreen]) .show-when-not-fullscreen {
   display: inline;
 }
diff --git a/site/src/components/docs/demos/fullscreen-button/html/css/BasicUsage.html b/site/src/components/docs/demos/fullscreen-button/html/css/BasicUsage.html
index ea873155..a81dae2c 100644
--- a/site/src/components/docs/demos/fullscreen-button/html/css/BasicUsage.html
+++ b/site/src/components/docs/demos/fullscreen-button/html/css/BasicUsage.html
@@ -1,4 +1,4 @@
-<video-player class="fullscreen-button-basic">
+<video-player class="html-fullscreen-button-basic">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,7 +6,7 @@
         playsinline
         loop
     ></video>
-    <media-fullscreen-button class="fullscreen-button-basic__button">
+    <media-fullscreen-button class="html-fullscreen-button-basic__button">
         <span class="show-when-fullscreen">Exit Fullscreen</span>
         <span class="show-when-not-fullscreen">Fullscreen</span>
     </media-fullscreen-button>
diff --git a/site/src/components/docs/demos/fullscreen-button/react/css/BasicUsage.css b/site/src/components/docs/demos/fullscreen-button/react/css/BasicUsage.css
index deab7dd1..b2460a95 100644
--- a/site/src/components/docs/demos/fullscreen-button/react/css/BasicUsage.css
+++ b/site/src/components/docs/demos/fullscreen-button/react/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.fullscreen-button-basic {
+.react-fullscreen-button-basic {
   position: relative;
 }
 
-.fullscreen-button-basic video {
+.react-fullscreen-button-basic video {
   width: 100%;
 }
 
-.fullscreen-button-basic__button {
+.react-fullscreen-button-basic__button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
diff --git a/site/src/components/docs/demos/fullscreen-button/react/css/BasicUsage.tsx b/site/src/components/docs/demos/fullscreen-button/react/css/BasicUsage.tsx
index 3e22c055..ac813524 100644
--- a/site/src/components/docs/demos/fullscreen-button/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/fullscreen-button/react/css/BasicUsage.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function BasicUsage() {
   return (
     <Player.Provider>
-      <Player.Container className="fullscreen-button-basic">
+      <Player.Container className="react-fullscreen-button-basic">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -16,7 +16,7 @@ export default function BasicUsage() {
           loop
         />
         <FullscreenButton
-          className="fullscreen-button-basic__button"
+          className="react-fullscreen-button-basic__button"
           render={(props, state) => <button {...props}>{state.fullscreen ? 'Exit Fullscreen' : 'Fullscreen'}</button>}
         />
       </Player.Container>
diff --git a/site/src/components/docs/demos/mute-button/html/css/BasicUsage.css b/site/src/components/docs/demos/mute-button/html/css/BasicUsage.css
index 5b8c34ed..41828464 100644
--- a/site/src/components/docs/demos/mute-button/html/css/BasicUsage.css
+++ b/site/src/components/docs/demos/mute-button/html/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.mute-button-basic {
+.html-mute-button-basic {
   position: relative;
 }
 
-.mute-button-basic video {
+.html-mute-button-basic video {
   width: 100%;
 }
 
-.mute-button-basic__button {
+.html-mute-button-basic__button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
@@ -20,15 +20,15 @@
   cursor: pointer;
 }
 
-.mute-button-basic__button .show-when-muted {
+.html-mute-button-basic__button .show-when-muted {
   display: none;
 }
-.mute-button-basic__button .show-when-unmuted {
+.html-mute-button-basic__button .show-when-unmuted {
   display: none;
 }
-.mute-button-basic__button[data-muted] .show-when-muted {
+.html-mute-button-basic__button[data-muted] .show-when-muted {
   display: inline;
 }
-.mute-button-basic__button:not([data-muted]) .show-when-unmuted {
+.html-mute-button-basic__button:not([data-muted]) .show-when-unmuted {
   display: inline;
 }
diff --git a/site/src/components/docs/demos/mute-button/html/css/BasicUsage.html b/site/src/components/docs/demos/mute-button/html/css/BasicUsage.html
index ab7edc81..cda6f540 100644
--- a/site/src/components/docs/demos/mute-button/html/css/BasicUsage.html
+++ b/site/src/components/docs/demos/mute-button/html/css/BasicUsage.html
@@ -1,4 +1,4 @@
-<video-player class="mute-button-basic">
+<video-player class="html-mute-button-basic">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,7 +6,7 @@
         playsinline
         loop
     ></video>
-    <media-mute-button class="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>
diff --git a/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.astro b/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.astro
new file mode 100644
index 00000000..ddba2960
--- /dev/null
+++ b/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.astro
@@ -0,0 +1,10 @@
+---
+import HtmlDemo from '@/components/docs/demos/HtmlDemo.astro';
+import html from './VolumeLevels.html?raw';
+import './VolumeLevels.css';
+---
+
+<HtmlDemo html={html} />
+<script>
+  import './VolumeLevels.ts';
+</script>
diff --git a/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.css b/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.css
new file mode 100644
index 00000000..89061ec4
--- /dev/null
+++ b/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.css
@@ -0,0 +1,41 @@
+.html-mute-button-volume-levels {
+  position: relative;
+}
+
+.html-mute-button-volume-levels video {
+  width: 100%;
+}
+
+.html-mute-button-volume-levels__button {
+  padding-block: 8px;
+  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-inline: 20px;
+  cursor: pointer;
+}
+
+.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="medium"] .level-medium {
+  display: inline;
+}
+.html-mute-button-volume-levels__button[data-volume-level="high"] .level-high {
+  display: inline;
+}
diff --git a/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.html b/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.html
new file mode 100644
index 00000000..0446f917
--- /dev/null
+++ b/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.html
@@ -0,0 +1,15 @@
+<video-player class="html-mute-button-volume-levels">
+    <video
+        src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
+        autoplay
+        muted
+        playsinline
+        loop
+    ></video>
+    <media-mute-button class="html-mute-button-volume-levels__button">
+        <span class="level-off">Off</span>
+        <span class="level-low">Low</span>
+        <span class="level-medium">Medium</span>
+        <span class="level-high">High</span>
+    </media-mute-button>
+</video-player>
diff --git a/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.ts b/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.ts
new file mode 100644
index 00000000..5c81c0a9
--- /dev/null
+++ b/site/src/components/docs/demos/mute-button/html/css/VolumeLevels.ts
@@ -0,0 +1,2 @@
+import '@videojs/html/video/player';
+import '@videojs/html/ui/mute-button';
diff --git a/site/src/components/docs/demos/mute-button/react/css/BasicUsage.css b/site/src/components/docs/demos/mute-button/react/css/BasicUsage.css
index 44bcd5bf..1015b3e5 100644
--- a/site/src/components/docs/demos/mute-button/react/css/BasicUsage.css
+++ b/site/src/components/docs/demos/mute-button/react/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.mute-button-basic {
+.react-mute-button-basic {
   position: relative;
 }
 
-.mute-button-basic video {
+.react-mute-button-basic video {
   width: 100%;
 }
 
-.mute-button-basic__button {
+.react-mute-button-basic__button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
diff --git a/site/src/components/docs/demos/mute-button/react/css/BasicUsage.tsx b/site/src/components/docs/demos/mute-button/react/css/BasicUsage.tsx
index cdd3150e..59ca479c 100644
--- a/site/src/components/docs/demos/mute-button/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/mute-button/react/css/BasicUsage.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function BasicUsage() {
   return (
     <Player.Provider>
-      <Player.Container className="mute-button-basic">
+      <Player.Container className="react-mute-button-basic">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -16,7 +16,7 @@ export default function BasicUsage() {
           loop
         />
         <MuteButton
-          className="mute-button-basic__button"
+          className="react-mute-button-basic__button"
           render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>}
         />
       </Player.Container>
diff --git a/site/src/components/docs/demos/mute-button/react/css/VolumeLevels.css b/site/src/components/docs/demos/mute-button/react/css/VolumeLevels.css
new file mode 100644
index 00000000..865f10f4
--- /dev/null
+++ b/site/src/components/docs/demos/mute-button/react/css/VolumeLevels.css
@@ -0,0 +1,21 @@
+.react-mute-button-volume-levels {
+  position: relative;
+}
+
+.react-mute-button-volume-levels video {
+  width: 100%;
+}
+
+.react-mute-button-volume-levels__button {
+  padding-block: 8px;
+  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-inline: 20px;
+  cursor: pointer;
+}
diff --git a/site/src/components/docs/demos/mute-button/react/css/VolumeLevels.tsx b/site/src/components/docs/demos/mute-button/react/css/VolumeLevels.tsx
new file mode 100644
index 00000000..75459dc7
--- /dev/null
+++ b/site/src/components/docs/demos/mute-button/react/css/VolumeLevels.tsx
@@ -0,0 +1,35 @@
+import { createPlayer, features, MuteButton, Video } from '@videojs/react';
+
+import './VolumeLevels.css';
+
+const Player = createPlayer({ features: [...features.video] });
+
+export default function VolumeLevels() {
+  return (
+    <Player.Provider>
+      <Player.Container className="react-mute-button-volume-levels">
+        <Video
+          src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <MuteButton
+          className="react-mute-button-volume-levels__button"
+          render={(props, state) => (
+            <button {...props}>
+              {state.volumeLevel === 'off'
+                ? 'Off'
+                : state.volumeLevel === 'low'
+                  ? 'Low'
+                  : state.volumeLevel === 'medium'
+                    ? 'Medium'
+                    : 'High'}
+            </button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
diff --git a/site/src/components/docs/demos/pip-button/html/css/BasicUsage.css b/site/src/components/docs/demos/pip-button/html/css/BasicUsage.css
index d4f8539d..a32fcbdb 100644
--- a/site/src/components/docs/demos/pip-button/html/css/BasicUsage.css
+++ b/site/src/components/docs/demos/pip-button/html/css/BasicUsage.css
@@ -1,13 +1,13 @@
-.pip-button-basic {
+.html-pip-button-basic {
   display: block;
   position: relative;
 }
 
-.pip-button-basic video {
+.html-pip-button-basic video {
   width: 100%;
 }
 
-.pip-button-basic__button {
+.html-pip-button-basic__button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
@@ -21,15 +21,15 @@
   cursor: pointer;
 }
 
-.pip-button-basic__button .show-when-pip {
+.html-pip-button-basic__button .show-when-pip {
   display: none;
 }
-.pip-button-basic__button .show-when-not-pip {
+.html-pip-button-basic__button .show-when-not-pip {
   display: none;
 }
-.pip-button-basic__button[data-pip] .show-when-pip {
+.html-pip-button-basic__button[data-pip] .show-when-pip {
   display: inline;
 }
-.pip-button-basic__button:not([data-pip]) .show-when-not-pip {
+.html-pip-button-basic__button:not([data-pip]) .show-when-not-pip {
   display: inline;
 }
diff --git a/site/src/components/docs/demos/pip-button/html/css/BasicUsage.html b/site/src/components/docs/demos/pip-button/html/css/BasicUsage.html
index f43a08de..5709d98b 100644
--- a/site/src/components/docs/demos/pip-button/html/css/BasicUsage.html
+++ b/site/src/components/docs/demos/pip-button/html/css/BasicUsage.html
@@ -1,4 +1,4 @@
-<video-player class="pip-button-basic">
+<video-player class="html-pip-button-basic">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,7 +6,7 @@
         playsinline
         loop
     ></video>
-    <media-pip-button class="pip-button-basic__button">
+    <media-pip-button class="html-pip-button-basic__button">
         <span class="show-when-pip">Exit PiP</span>
         <span class="show-when-not-pip">Enter PiP</span>
     </media-pip-button>
diff --git a/site/src/components/docs/demos/pip-button/react/css/BasicUsage.css b/site/src/components/docs/demos/pip-button/react/css/BasicUsage.css
index fd56f54f..8667bb39 100644
--- a/site/src/components/docs/demos/pip-button/react/css/BasicUsage.css
+++ b/site/src/components/docs/demos/pip-button/react/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.pip-button-basic {
+.react-pip-button-basic {
   position: relative;
 }
 
-.pip-button-basic video {
+.react-pip-button-basic video {
   width: 100%;
 }
 
-.pip-button-basic__button {
+.react-pip-button-basic__button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
diff --git a/site/src/components/docs/demos/pip-button/react/css/BasicUsage.tsx b/site/src/components/docs/demos/pip-button/react/css/BasicUsage.tsx
index cf85e187..5083e63c 100644
--- a/site/src/components/docs/demos/pip-button/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/pip-button/react/css/BasicUsage.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function BasicUsage() {
   return (
     <Player.Provider>
-      <Player.Container className="pip-button-basic">
+      <Player.Container className="react-pip-button-basic">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -16,7 +16,7 @@ export default function BasicUsage() {
           loop
         />
         <PiPButton
-          className="pip-button-basic__button"
+          className="react-pip-button-basic__button"
           render={(props, state) => <button {...props}>{state.pip ? 'Exit PiP' : 'Enter PiP'}</button>}
         />
       </Player.Container>
diff --git a/site/src/components/docs/demos/play-button/html/css/BasicUsage.css b/site/src/components/docs/demos/play-button/html/css/BasicUsage.css
index ec3a0ed7..d36d38c6 100644
--- a/site/src/components/docs/demos/play-button/html/css/BasicUsage.css
+++ b/site/src/components/docs/demos/play-button/html/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.play-button-basic {
+.html-play-button-basic {
   position: relative;
 }
 
-.play-button-basic video {
+.html-play-button-basic video {
   width: 100%;
 }
 
-.play-button-basic__button {
+.html-play-button-basic__button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
@@ -20,15 +20,27 @@
   cursor: pointer;
 }
 
-.play-button-basic__button .show-when-paused {
+.html-play-button-basic__button .show-when-paused {
   display: none;
 }
-.play-button-basic__button .show-when-playing {
+.html-play-button-basic__button .show-when-playing {
   display: none;
 }
-.play-button-basic__button[data-paused] .show-when-paused {
+.html-play-button-basic__button .show-when-ended {
+  display: none;
+}
+.html-play-button-basic__button[data-paused]:not([data-ended]) .show-when-paused {
   display: inline;
 }
-.play-button-basic__button:not([data-paused]) .show-when-playing {
+.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-ended] .show-when-paused {
+  display: none;
+}
+.html-play-button-basic__button[data-ended] .show-when-playing {
+  display: none;
+}
diff --git a/site/src/components/docs/demos/play-button/html/css/BasicUsage.html b/site/src/components/docs/demos/play-button/html/css/BasicUsage.html
index 09d1118a..9784d362 100644
--- a/site/src/components/docs/demos/play-button/html/css/BasicUsage.html
+++ b/site/src/components/docs/demos/play-button/html/css/BasicUsage.html
@@ -1,13 +1,13 @@
-<video-player class="play-button-basic">
+<video-player class="html-play-button-basic">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
         muted
         playsinline
-        loop
     ></video>
-    <media-play-button class="play-button-basic__button">
+    <media-play-button class="html-play-button-basic__button">
         <span class="show-when-paused">Play</span>
         <span class="show-when-playing">Pause</span>
+        <span class="show-when-ended">Replay</span>
     </media-play-button>
 </video-player>
diff --git a/site/src/components/docs/demos/play-button/react/css/BasicUsage.css b/site/src/components/docs/demos/play-button/react/css/BasicUsage.css
index b9441d75..f8fcabcb 100644
--- a/site/src/components/docs/demos/play-button/react/css/BasicUsage.css
+++ b/site/src/components/docs/demos/play-button/react/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.play-button-basic {
+.react-play-button-basic {
   position: relative;
 }
 
-.play-button-basic video {
+.react-play-button-basic video {
   width: 100%;
 }
 
-.play-button-basic__button {
+.react-play-button-basic__button {
   padding-block: 8px;
   position: absolute;
   bottom: 10px;
diff --git a/site/src/components/docs/demos/play-button/react/css/BasicUsage.tsx b/site/src/components/docs/demos/play-button/react/css/BasicUsage.tsx
index 0b70faa8..d2575072 100644
--- a/site/src/components/docs/demos/play-button/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/play-button/react/css/BasicUsage.tsx
@@ -7,17 +7,18 @@ const Player = createPlayer({ features: [...features.video] });
 export default function BasicUsage() {
   return (
     <Player.Provider>
-      <Player.Container className="play-button-basic">
+      <Player.Container className="react-play-button-basic">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
           muted
           playsInline
-          loop
         />
         <PlayButton
-          className="play-button-basic__button"
-          render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
+          className="react-play-button-basic__button"
+          render={(props, state) => (
+            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
+          )}
         />
       </Player.Container>
     </Player.Provider>
diff --git a/site/src/components/docs/demos/poster/html/css/BasicUsage.css b/site/src/components/docs/demos/poster/html/css/BasicUsage.css
index 8facdfae..6a685268 100644
--- a/site/src/components/docs/demos/poster/html/css/BasicUsage.css
+++ b/site/src/components/docs/demos/poster/html/css/BasicUsage.css
@@ -1,30 +1,30 @@
-.poster-basic {
+.html-poster-basic {
   display: block;
   position: relative;
 }
 
-.poster-basic video {
+.html-poster-basic video {
   width: 100%;
 }
 
-.poster-basic__poster {
+.html-poster-basic__poster {
   position: absolute;
   inset: 0;
   pointer-events: none;
   transition: opacity 0.25s;
 }
 
-.poster-basic__poster:not([data-visible]) {
+.html-poster-basic__poster:not([data-visible]) {
   opacity: 0;
 }
 
-.poster-basic__poster img {
+.html-poster-basic__poster img {
   width: 100%;
   height: 100%;
   object-fit: cover;
 }
 
-.poster-basic__button {
+.html-poster-basic__button {
   position: absolute;
   bottom: 10px;
   left: 10px;
@@ -38,15 +38,15 @@
   cursor: pointer;
 }
 
-.poster-basic__button .show-when-paused,
-.poster-basic__button .show-when-playing {
+.html-poster-basic__button .show-when-paused,
+.html-poster-basic__button .show-when-playing {
   display: none;
 }
 
-.poster-basic__button[data-paused] .show-when-paused {
+.html-poster-basic__button[data-paused] .show-when-paused {
   display: inline;
 }
 
-.poster-basic__button:not([data-paused]) .show-when-playing {
+.html-poster-basic__button:not([data-paused]) .show-when-playing {
   display: inline;
 }
diff --git a/site/src/components/docs/demos/poster/html/css/BasicUsage.html b/site/src/components/docs/demos/poster/html/css/BasicUsage.html
index da845464..34c4d4d6 100644
--- a/site/src/components/docs/demos/poster/html/css/BasicUsage.html
+++ b/site/src/components/docs/demos/poster/html/css/BasicUsage.html
@@ -1,16 +1,16 @@
-<video-player class="poster-basic">
+<video-player class="html-poster-basic">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         playsinline
     ></video>
 
-    <media-poster class="poster-basic__poster">
+    <media-poster class="html-poster-basic__poster">
         <img
             src="https://image.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/thumbnail.jpg"
         />
     </media-poster>
 
-    <media-play-button class="poster-basic__button">
+    <media-play-button class="html-poster-basic__button">
         <span class="show-when-paused">Play</span>
         <span class="show-when-playing">Pause</span>
     </media-play-button>
diff --git a/site/src/components/docs/demos/poster/react/css/BasicUsage.css b/site/src/components/docs/demos/poster/react/css/BasicUsage.css
index d0d94171..053a6078 100644
--- a/site/src/components/docs/demos/poster/react/css/BasicUsage.css
+++ b/site/src/components/docs/demos/poster/react/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.poster-basic {
+.react-poster-basic {
   position: relative;
 }
 
-.poster-basic video {
+.react-poster-basic video {
   width: 100%;
 }
 
-.poster-basic__poster {
+.react-poster-basic__poster {
   position: absolute;
   inset: 0;
   width: 100%;
@@ -16,11 +16,11 @@
   transition: opacity 0.25s;
 }
 
-.poster-basic__poster:not([data-visible]) {
+.react-poster-basic__poster:not([data-visible]) {
   opacity: 0;
 }
 
-.poster-basic__button {
+.react-poster-basic__button {
   position: absolute;
   bottom: 10px;
   left: 10px;
diff --git a/site/src/components/docs/demos/poster/react/css/BasicUsage.tsx b/site/src/components/docs/demos/poster/react/css/BasicUsage.tsx
index 4d75557a..c29c77b7 100644
--- a/site/src/components/docs/demos/poster/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/poster/react/css/BasicUsage.tsx
@@ -7,16 +7,16 @@ const Player = createPlayer({ features: [...features.video] });
 export default function BasicUsage() {
   return (
     <Player.Provider>
-      <Player.Container className="poster-basic">
+      <Player.Container className="react-poster-basic">
         <Video src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4" playsInline />
 
         <Poster
-          className="poster-basic__poster"
+          className="react-poster-basic__poster"
           src="https://image.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/thumbnail.jpg"
         />
 
         <PlayButton
-          className="poster-basic__button"
+          className="react-poster-basic__button"
           render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
         />
       </Player.Container>
diff --git a/site/src/components/docs/demos/seek-button/html/css/BasicUsage.css b/site/src/components/docs/demos/seek-button/html/css/BasicUsage.css
index c6b605d3..48f1fceb 100644
--- a/site/src/components/docs/demos/seek-button/html/css/BasicUsage.css
+++ b/site/src/components/docs/demos/seek-button/html/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.seek-button-basic {
+.html-seek-button-basic {
   position: relative;
 }
 
-.seek-button-basic video {
+.html-seek-button-basic video {
   width: 100%;
 }
 
-.seek-button-basic__buttons {
+.html-seek-button-basic__buttons {
   display: flex;
   gap: 8px;
   position: absolute;
@@ -14,7 +14,7 @@
   left: 10px;
 }
 
-.seek-button-basic__button {
+.html-seek-button-basic__button {
   padding-block: 8px;
   background: rgba(255, 255, 255, 0.7);
   backdrop-filter: blur(10px);
@@ -26,15 +26,15 @@
   cursor: pointer;
 }
 
-.seek-button-basic__button .show-when-backward {
+.html-seek-button-basic__button .show-when-backward {
   display: none;
 }
-.seek-button-basic__button .show-when-forward {
+.html-seek-button-basic__button .show-when-forward {
   display: none;
 }
-.seek-button-basic__button[data-direction="backward"] .show-when-backward {
+.html-seek-button-basic__button[data-direction="backward"] .show-when-backward {
   display: inline;
 }
-.seek-button-basic__button[data-direction="forward"] .show-when-forward {
+.html-seek-button-basic__button[data-direction="forward"] .show-when-forward {
   display: inline;
 }
diff --git a/site/src/components/docs/demos/seek-button/html/css/BasicUsage.html b/site/src/components/docs/demos/seek-button/html/css/BasicUsage.html
index e32f1e5d..896b1eda 100644
--- a/site/src/components/docs/demos/seek-button/html/css/BasicUsage.html
+++ b/site/src/components/docs/demos/seek-button/html/css/BasicUsage.html
@@ -1,4 +1,4 @@
-<video-player class="seek-button-basic">
+<video-player class="html-seek-button-basic">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,11 +6,11 @@
         playsinline
         loop
     ></video>
-    <div class="seek-button-basic__buttons">
-        <media-seek-button seconds="-5" class="seek-button-basic__button">
+    <div class="html-seek-button-basic__buttons">
+        <media-seek-button seconds="-5" class="html-seek-button-basic__button">
             <span class="show-when-backward">&#9194; 5s</span>
         </media-seek-button>
-        <media-seek-button seconds="10" class="seek-button-basic__button">
+        <media-seek-button seconds="10" class="html-seek-button-basic__button">
             <span class="show-when-forward">10s &#9193;</span>
         </media-seek-button>
     </div>
diff --git a/site/src/components/docs/demos/seek-button/react/css/BasicUsage.css b/site/src/components/docs/demos/seek-button/react/css/BasicUsage.css
index e75f8cdd..8f98b4c9 100644
--- a/site/src/components/docs/demos/seek-button/react/css/BasicUsage.css
+++ b/site/src/components/docs/demos/seek-button/react/css/BasicUsage.css
@@ -1,12 +1,12 @@
-.seek-button-basic {
+.react-seek-button-basic {
   position: relative;
 }
 
-.seek-button-basic video {
+.react-seek-button-basic video {
   width: 100%;
 }
 
-.seek-button-basic__buttons {
+.react-seek-button-basic__buttons {
   display: flex;
   gap: 8px;
   position: absolute;
@@ -14,7 +14,7 @@
   left: 10px;
 }
 
-.seek-button-basic__button {
+.react-seek-button-basic__button {
   padding-block: 8px;
   background: rgba(255, 255, 255, 0.7);
   backdrop-filter: blur(10px);
diff --git a/site/src/components/docs/demos/seek-button/react/css/BasicUsage.tsx b/site/src/components/docs/demos/seek-button/react/css/BasicUsage.tsx
index 4bdba1b0..326918f9 100644
--- a/site/src/components/docs/demos/seek-button/react/css/BasicUsage.tsx
+++ b/site/src/components/docs/demos/seek-button/react/css/BasicUsage.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function BasicUsage() {
   return (
     <Player.Provider>
-      <Player.Container className="seek-button-basic">
+      <Player.Container className="react-seek-button-basic">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -15,10 +15,10 @@ export default function BasicUsage() {
           playsInline
           loop
         />
-        <div className="seek-button-basic__buttons">
+        <div className="react-seek-button-basic__buttons">
           <SeekButton
             seconds={-5}
-            className="seek-button-basic__button"
+            className="react-seek-button-basic__button"
             render={(props, state) => (
               <button {...props}>
                 {state.direction === 'backward' ? '\u23EA' : '\u23E9'} {5}s
@@ -27,7 +27,7 @@ export default function BasicUsage() {
           />
           <SeekButton
             seconds={10}
-            className="seek-button-basic__button"
+            className="react-seek-button-basic__button"
             render={(props, state) => (
               <button {...props}>
                 {10}s {state.direction === 'forward' ? '\u23E9' : '\u23EA'}
diff --git a/site/src/components/docs/demos/time/html/css/CurrentDuration.css b/site/src/components/docs/demos/time/html/css/CurrentDuration.css
index d2eaa1bd..840554b9 100644
--- a/site/src/components/docs/demos/time/html/css/CurrentDuration.css
+++ b/site/src/components/docs/demos/time/html/css/CurrentDuration.css
@@ -1,12 +1,12 @@
-.time-current-duration {
+.html-time-current-duration {
   position: relative;
 }
 
-.time-current-duration video {
+.html-time-current-duration video {
   width: 100%;
 }
 
-.time-current-duration__group {
+.html-time-current-duration__group {
   display: flex;
   align-items: center;
   gap: 4px;
diff --git a/site/src/components/docs/demos/time/html/css/CurrentDuration.html b/site/src/components/docs/demos/time/html/css/CurrentDuration.html
index 80c800f8..843cceaf 100644
--- a/site/src/components/docs/demos/time/html/css/CurrentDuration.html
+++ b/site/src/components/docs/demos/time/html/css/CurrentDuration.html
@@ -1,4 +1,4 @@
-<video-player class="time-current-duration">
+<video-player class="html-time-current-duration">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,7 +6,7 @@
         playsinline
         loop
     ></video>
-    <media-time-group class="time-current-duration__group">
+    <media-time-group class="html-time-current-duration__group">
         <media-time type="current"></media-time>
         <media-time-separator></media-time-separator>
         <media-time type="duration"></media-time>
diff --git a/site/src/components/docs/demos/time/html/css/CurrentTime.css b/site/src/components/docs/demos/time/html/css/CurrentTime.css
index a01d8c06..685037db 100644
--- a/site/src/components/docs/demos/time/html/css/CurrentTime.css
+++ b/site/src/components/docs/demos/time/html/css/CurrentTime.css
@@ -1,12 +1,12 @@
-.time-current-time {
+.html-time-current-time {
   position: relative;
 }
 
-.time-current-time video {
+.html-time-current-time video {
   width: 100%;
 }
 
-.time-current-time__value {
+.html-time-current-time__value {
   position: absolute;
   bottom: 10px;
   left: 10px;
diff --git a/site/src/components/docs/demos/time/html/css/CurrentTime.html b/site/src/components/docs/demos/time/html/css/CurrentTime.html
index 7915542d..777247fc 100644
--- a/site/src/components/docs/demos/time/html/css/CurrentTime.html
+++ b/site/src/components/docs/demos/time/html/css/CurrentTime.html
@@ -1,4 +1,4 @@
-<video-player class="time-current-time">
+<video-player class="html-time-current-time">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,5 +6,5 @@
         playsinline
         loop
     ></video>
-    <media-time class="time-current-time__value" type="current"></media-time>
+    <media-time class="html-time-current-time__value" type="current"></media-time>
 </video-player>
diff --git a/site/src/components/docs/demos/time/html/css/CustomNegativeSign.css b/site/src/components/docs/demos/time/html/css/CustomNegativeSign.css
index 3f2c05cf..27b82ed2 100644
--- a/site/src/components/docs/demos/time/html/css/CustomNegativeSign.css
+++ b/site/src/components/docs/demos/time/html/css/CustomNegativeSign.css
@@ -1,12 +1,12 @@
-.time-custom-negative-sign {
+.html-time-custom-negative-sign {
   position: relative;
 }
 
-.time-custom-negative-sign video {
+.html-time-custom-negative-sign video {
   width: 100%;
 }
 
-.time-custom-negative-sign__value {
+.html-time-custom-negative-sign__value {
   position: absolute;
   bottom: 10px;
   left: 10px;
diff --git a/site/src/components/docs/demos/time/html/css/CustomNegativeSign.html b/site/src/components/docs/demos/time/html/css/CustomNegativeSign.html
index 72398ae0..b41d2084 100644
--- a/site/src/components/docs/demos/time/html/css/CustomNegativeSign.html
+++ b/site/src/components/docs/demos/time/html/css/CustomNegativeSign.html
@@ -1,4 +1,4 @@
-<video-player class="time-custom-negative-sign">
+<video-player class="html-time-custom-negative-sign">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -7,7 +7,7 @@
         loop
     ></video>
     <media-time
-        class="time-custom-negative-sign__value"
+        class="html-time-custom-negative-sign__value"
         type="remaining"
         negative-sign="~"
     ></media-time>
diff --git a/site/src/components/docs/demos/time/html/css/CustomSeparator.css b/site/src/components/docs/demos/time/html/css/CustomSeparator.css
index d6050440..6dfb9a23 100644
--- a/site/src/components/docs/demos/time/html/css/CustomSeparator.css
+++ b/site/src/components/docs/demos/time/html/css/CustomSeparator.css
@@ -1,12 +1,12 @@
-.time-custom-separator {
+.html-time-custom-separator {
   position: relative;
 }
 
-.time-custom-separator video {
+.html-time-custom-separator video {
   width: 100%;
 }
 
-.time-custom-separator__group {
+.html-time-custom-separator__group {
   display: flex;
   align-items: center;
   gap: 4px;
diff --git a/site/src/components/docs/demos/time/html/css/CustomSeparator.html b/site/src/components/docs/demos/time/html/css/CustomSeparator.html
index 70a2c5ff..29dea2b7 100644
--- a/site/src/components/docs/demos/time/html/css/CustomSeparator.html
+++ b/site/src/components/docs/demos/time/html/css/CustomSeparator.html
@@ -1,4 +1,4 @@
-<video-player class="time-custom-separator">
+<video-player class="html-time-custom-separator">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,7 +6,7 @@
         playsinline
         loop
     ></video>
-    <media-time-group class="time-custom-separator__group">
+    <media-time-group class="html-time-custom-separator__group">
         <media-time type="current"></media-time>
         <media-time-separator> of </media-time-separator>
         <media-time type="duration"></media-time>
diff --git a/site/src/components/docs/demos/time/html/css/Remaining.css b/site/src/components/docs/demos/time/html/css/Remaining.css
index aba8cd8a..1d8b075b 100644
--- a/site/src/components/docs/demos/time/html/css/Remaining.css
+++ b/site/src/components/docs/demos/time/html/css/Remaining.css
@@ -1,12 +1,12 @@
-.time-remaining {
+.html-time-remaining {
   position: relative;
 }
 
-.time-remaining video {
+.html-time-remaining video {
   width: 100%;
 }
 
-.time-remaining__value {
+.html-time-remaining__value {
   position: absolute;
   bottom: 10px;
   left: 10px;
diff --git a/site/src/components/docs/demos/time/html/css/Remaining.html b/site/src/components/docs/demos/time/html/css/Remaining.html
index 59ef9082..90d80f5c 100644
--- a/site/src/components/docs/demos/time/html/css/Remaining.html
+++ b/site/src/components/docs/demos/time/html/css/Remaining.html
@@ -1,4 +1,4 @@
-<video-player class="time-remaining">
+<video-player class="html-time-remaining">
     <video
         src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
         autoplay
@@ -6,5 +6,5 @@
         playsinline
         loop
     ></video>
-    <media-time class="time-remaining__value" type="remaining"></media-time>
+    <media-time class="html-time-remaining__value" type="remaining"></media-time>
 </video-player>
diff --git a/site/src/components/docs/demos/time/react/css/CurrentDuration.css b/site/src/components/docs/demos/time/react/css/CurrentDuration.css
index d2eaa1bd..510f4f39 100644
--- a/site/src/components/docs/demos/time/react/css/CurrentDuration.css
+++ b/site/src/components/docs/demos/time/react/css/CurrentDuration.css
@@ -1,12 +1,12 @@
-.time-current-duration {
+.react-time-current-duration {
   position: relative;
 }
 
-.time-current-duration video {
+.react-time-current-duration video {
   width: 100%;
 }
 
-.time-current-duration__group {
+.react-time-current-duration__group {
   display: flex;
   align-items: center;
   gap: 4px;
diff --git a/site/src/components/docs/demos/time/react/css/CurrentDuration.tsx b/site/src/components/docs/demos/time/react/css/CurrentDuration.tsx
index ea1557e0..c2af6f5c 100644
--- a/site/src/components/docs/demos/time/react/css/CurrentDuration.tsx
+++ b/site/src/components/docs/demos/time/react/css/CurrentDuration.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function CurrentDuration() {
   return (
     <Player.Provider>
-      <Player.Container className="time-current-duration">
+      <Player.Container className="react-time-current-duration">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -15,7 +15,7 @@ export default function CurrentDuration() {
           playsInline
           loop
         />
-        <Time.Group className="time-current-duration__group">
+        <Time.Group className="react-time-current-duration__group">
           <Time.Value type="current" />
           <Time.Separator />
           <Time.Value type="duration" />
diff --git a/site/src/components/docs/demos/time/react/css/CurrentTime.css b/site/src/components/docs/demos/time/react/css/CurrentTime.css
index a01d8c06..294b9f58 100644
--- a/site/src/components/docs/demos/time/react/css/CurrentTime.css
+++ b/site/src/components/docs/demos/time/react/css/CurrentTime.css
@@ -1,12 +1,12 @@
-.time-current-time {
+.react-time-current-time {
   position: relative;
 }
 
-.time-current-time video {
+.react-time-current-time video {
   width: 100%;
 }
 
-.time-current-time__value {
+.react-time-current-time__value {
   position: absolute;
   bottom: 10px;
   left: 10px;
diff --git a/site/src/components/docs/demos/time/react/css/CurrentTime.tsx b/site/src/components/docs/demos/time/react/css/CurrentTime.tsx
index 25c990d8..de72aee0 100644
--- a/site/src/components/docs/demos/time/react/css/CurrentTime.tsx
+++ b/site/src/components/docs/demos/time/react/css/CurrentTime.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function CurrentTime() {
   return (
     <Player.Provider>
-      <Player.Container className="time-current-time">
+      <Player.Container className="react-time-current-time">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -15,7 +15,7 @@ export default function CurrentTime() {
           playsInline
           loop
         />
-        <Time.Value type="current" className="time-current-time__value" />
+        <Time.Value type="current" className="react-time-current-time__value" />
       </Player.Container>
     </Player.Provider>
   );
diff --git a/site/src/components/docs/demos/time/react/css/CustomNegativeSign.css b/site/src/components/docs/demos/time/react/css/CustomNegativeSign.css
index 3f2c05cf..b5be1d0e 100644
--- a/site/src/components/docs/demos/time/react/css/CustomNegativeSign.css
+++ b/site/src/components/docs/demos/time/react/css/CustomNegativeSign.css
@@ -1,12 +1,12 @@
-.time-custom-negative-sign {
+.react-time-custom-negative-sign {
   position: relative;
 }
 
-.time-custom-negative-sign video {
+.react-time-custom-negative-sign video {
   width: 100%;
 }
 
-.time-custom-negative-sign__value {
+.react-time-custom-negative-sign__value {
   position: absolute;
   bottom: 10px;
   left: 10px;
diff --git a/site/src/components/docs/demos/time/react/css/CustomNegativeSign.tsx b/site/src/components/docs/demos/time/react/css/CustomNegativeSign.tsx
index 135d1d1a..7b00f6a9 100644
--- a/site/src/components/docs/demos/time/react/css/CustomNegativeSign.tsx
+++ b/site/src/components/docs/demos/time/react/css/CustomNegativeSign.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function CustomNegativeSign() {
   return (
     <Player.Provider>
-      <Player.Container className="time-custom-negative-sign">
+      <Player.Container className="react-time-custom-negative-sign">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -15,7 +15,7 @@ export default function CustomNegativeSign() {
           playsInline
           loop
         />
-        <Time.Value type="remaining" negativeSign="~" className="time-custom-negative-sign__value" />
+        <Time.Value type="remaining" negativeSign="~" className="react-time-custom-negative-sign__value" />
       </Player.Container>
     </Player.Provider>
   );
diff --git a/site/src/components/docs/demos/time/react/css/CustomSeparator.css b/site/src/components/docs/demos/time/react/css/CustomSeparator.css
index d6050440..840ae4f1 100644
--- a/site/src/components/docs/demos/time/react/css/CustomSeparator.css
+++ b/site/src/components/docs/demos/time/react/css/CustomSeparator.css
@@ -1,12 +1,12 @@
-.time-custom-separator {
+.react-time-custom-separator {
   position: relative;
 }
 
-.time-custom-separator video {
+.react-time-custom-separator video {
   width: 100%;
 }
 
-.time-custom-separator__group {
+.react-time-custom-separator__group {
   display: flex;
   align-items: center;
   gap: 4px;
diff --git a/site/src/components/docs/demos/time/react/css/CustomSeparator.tsx b/site/src/components/docs/demos/time/react/css/CustomSeparator.tsx
index 524ac64a..f9868bf2 100644
--- a/site/src/components/docs/demos/time/react/css/CustomSeparator.tsx
+++ b/site/src/components/docs/demos/time/react/css/CustomSeparator.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function CustomSeparator() {
   return (
     <Player.Provider>
-      <Player.Container className="time-custom-separator">
+      <Player.Container className="react-time-custom-separator">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -15,7 +15,7 @@ export default function CustomSeparator() {
           playsInline
           loop
         />
-        <Time.Group className="time-custom-separator__group">
+        <Time.Group className="react-time-custom-separator__group">
           <Time.Value type="current" />
           <Time.Separator> of </Time.Separator>
           <Time.Value type="duration" />
diff --git a/site/src/components/docs/demos/time/react/css/Remaining.css b/site/src/components/docs/demos/time/react/css/Remaining.css
index aba8cd8a..a65885aa 100644
--- a/site/src/components/docs/demos/time/react/css/Remaining.css
+++ b/site/src/components/docs/demos/time/react/css/Remaining.css
@@ -1,12 +1,12 @@
-.time-remaining {
+.react-time-remaining {
   position: relative;
 }
 
-.time-remaining video {
+.react-time-remaining video {
   width: 100%;
 }
 
-.time-remaining__value {
+.react-time-remaining__value {
   position: absolute;
   bottom: 10px;
   left: 10px;
diff --git a/site/src/components/docs/demos/time/react/css/Remaining.tsx b/site/src/components/docs/demos/time/react/css/Remaining.tsx
index 8389c16b..f2714ba1 100644
--- a/site/src/components/docs/demos/time/react/css/Remaining.tsx
+++ b/site/src/components/docs/demos/time/react/css/Remaining.tsx
@@ -7,7 +7,7 @@ const Player = createPlayer({ features: [...features.video] });
 export default function Remaining() {
   return (
     <Player.Provider>
-      <Player.Container className="time-remaining">
+      <Player.Container className="react-time-remaining">
         <Video
           src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
           autoPlay
@@ -15,7 +15,7 @@ export default function Remaining() {
           playsInline
           loop
         />
-        <Time.Value type="remaining" className="time-remaining__value" />
+        <Time.Value type="remaining" className="react-time-remaining__value" />
       </Player.Container>
     </Player.Provider>
   );
diff --git a/site/src/content/docs/how-to/write-guides.mdx b/site/src/content/docs/how-to/write-guides.mdx
index 01728268..160f41ee 100644
--- a/site/src/content/docs/how-to/write-guides.mdx
+++ b/site/src/content/docs/how-to/write-guides.mdx
@@ -1,5 +1,5 @@
 ---
-title: 'Writing guides for Video.js'
+title: 'Write guides for Video.js'
 description: 'A guide on writing documentation, and a test bed for all our MDX components'
 ---
 
@@ -11,17 +11,31 @@ import { TabsRoot, TabsList, TabsPanel, Tab } from '@/components/Tabs.tsx';
 import DocsLink from '@/components/docs/DocsLink.astro';
 import Aside from '@/components/Aside.astro';
 
-## 1. Create a guide in the correct content folder
+What is a guide? In this context, it's a document in the docs that's not an API reference. For API references, see <DocsLink slug="reference/write-references">Write reference pages</DocsLink>.
 
-First, read and understand [Diátaxis](https://diataxis.fr/).
+<Aside type="tip">
+Oh hey by the way. A lot of this knowledge is encoded in the `docs-guide` Claude skill. You should still read it, but, now your LLM can help you along the way, too.
+</Aside>
 
-Next, know that our [MDX](https://mdxjs.com) guides are separated into two categories:
-1. How-to guides: Focused on achieving a specific outcome. Place these in `src/content/docs/how-to/[slug].mdx`
-2. Concept guides: Focused on understanding a topic. Place these in `src/content/docs/concepts/[slug].mdx`
+## 1. Understand our documentation structure
 
-(You might also notice that we've written some `src/content/docs/reference` guides, but soon those will be auto-generated from source code.)
+First, read and understand [Diátaxis](https://diataxis.fr/). We organize documentation into three modes:
+
+1. **Concept pages** (`src/content/docs/concepts/`): Explain how and why things work. General understanding, spanning multiple APIs, can be applied to multiple outcomes. As we write guides, what are things we need people to understand in multiple places and don’t want to duplicate the content?
+2. **How-to guides** (`src/content/docs/how-to/`): Spans multiple concepts in order to achieve a specific outcome with step-by-step instructions. 
+3. **Reference pages** (`src/content/docs/reference/`): Component API documentation. These are scaffolded using the `api-reference` skill and the api-docs-builder. Again, see <DocsLink slug="reference/write-references">Write reference pages</DocsLink> for details.
+
+When in doubt, you probably want a concept page.
+
+## 2. Create a guide in the correct content folder
+
+Our guides are [MDX](https://mdxjs.com) files placed in the matching directory:
+
+- Concept pages go in `src/content/docs/concepts/[slug].mdx`
+- How-to guides go in `src/content/docs/how-to/[slug].mdx`
+
+## 3. Add that guide to the sidebar
 
-## 2. Add that guide to the sidebar
 Next, open `src/docs.config.ts` and add your guide to the appropriate section of the sidebar. For example, to add a how-to guide on "Writing guides", you would add:
 
 ```ts
@@ -42,7 +56,21 @@ If you want the guide to only apply to specific frameworks or styles, you can sp
 }
 ```
 
-## 3. Understand MDX and our components
+## 4. Follow our writing style
+
+Keep documentation clear, human, and useful. Here are the key rules:
+
+- **Sentence case for headings** — capitalize only the first word and proper nouns (e.g., "Choose your JS framework", not "Choose Your JS Framework")
+- **Active voice, second person** — speak directly to the reader with "you"
+- **Collaborative pronouns** — use "we," "us," and "our" when talking about the project or team
+- **Avoid gerunds in headings** — prefer "Write good headings" over "Writing good headings"
+- **Oxford comma** — always use the serial comma in lists of three or more
+- **Gender-neutral language** — use "they" or "their" instead of "his" or "her"
+- **Cut filler words** — remove "In order to," "basically," "simply," "might," "could," "perhaps"
+- **Be precise** — make claims as strong as possible without becoming false; avoid vague qualifiers like "somewhat" or "fairly"
+- **Read it out loud** — if it sounds awkward, rewrite it
+
+## 5. Understand MDX and our components
 
 ### `<FrameworkCase>` and `<StyleCase>`
 First, understand that the guide you write will be rendered for every framework / style combination (e.g., HTML + CSS, React + CSS) unless you restrict it in the sidebar config as shown above.
@@ -69,8 +97,8 @@ Use the `<StyleCase>` component to show content only for specific styling approa
 ```mdx
 <StyleCase styles={["css"]}>
   CSS-only content
-</StyleCase>  
-``` 
+</StyleCase>
+```
 
 
 <StyleCase styles={["css"]}>
@@ -299,7 +327,7 @@ The elements have a gross Tailwind class that manages their margins which makes
 
 ### Tabs
 
-Use `<TabsRoot>`, `<TabsList>`, `<Tab>`, and `<TabsPanel>` to show multiple items side-by-side. 
+Use `<TabsRoot>`, `<TabsList>`, `<Tab>`, and `<TabsPanel>` to show multiple items side-by-side.
 
 <Aside type="note">
 - Set `initial` on your first `<Tab>` and first `<TabsPanel>` to make them active by default
diff --git a/site/src/content/docs/reference/buffering-indicator.mdx b/site/src/content/docs/reference/buffering-indicator.mdx
index e36945c5..da96861a 100644
--- a/site/src/content/docs/reference/buffering-indicator.mdx
+++ b/site/src/content/docs/reference/buffering-indicator.mdx
@@ -35,6 +35,14 @@ import basicUsageHtmlTs from "@/components/docs/demos/buffering-indicator/html/c
 ```
 </FrameworkCase>
 
+## Behavior
+
+Shows a loading indicator when the media is waiting to buffer and not paused, but only after a configurable `delay` (default 500ms). This delay prevents the indicator from flickering during brief stalls. The indicator hides immediately when buffering ends.
+
+## Styling
+
+Hide and show the indicator based on the `data-visible` attribute.
+
 ## Examples
 
 ### Basic Usage
diff --git a/site/src/content/docs/reference/controls.mdx b/site/src/content/docs/reference/controls.mdx
index 32d7c827..097d9811 100644
--- a/site/src/content/docs/reference/controls.mdx
+++ b/site/src/content/docs/reference/controls.mdx
@@ -41,6 +41,39 @@ Import the component and assemble its parts:
   ```
 </FrameworkCase>
 
+## Behavior
+
+If the user is active, or if the video is paused, this component will show controls. Otherwise, it will hide them after a short delay.
+
+User activity is tracked via pointer movement, keyboard input, and focus events on the player container. On touch devices, a quick tap toggles visibility. `mouseleave` immediately sets the user as inactive.
+
+## Styling
+By default, controls have the following styles:
+
+```css
+/* Click-through: clicks pass through controls to video beneath */
+media-controls {
+  pointer-events: none;
+}
+
+media-controls-group {
+  pointer-events: auto;
+}
+
+/* Fade transition */
+media-controls {
+  transition: opacity 0.25s;
+}
+
+media-controls:not([data-visible]) {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+No ARIA role is applied to `<media-controls>` — it is a layout wrapper, not a landmark. `<media-controls-group>` automatically receives `role="group"` when an `aria-label` or `aria-labelledby` attribute is provided; otherwise no role is assigned.
+
 ## Examples
 
 ### Basic Usage
diff --git a/site/src/content/docs/reference/fullscreen-button.mdx b/site/src/content/docs/reference/fullscreen-button.mdx
index 793b4b66..5d742ac1 100644
--- a/site/src/content/docs/reference/fullscreen-button.mdx
+++ b/site/src/content/docs/reference/fullscreen-button.mdx
@@ -24,27 +24,56 @@ import basicUsageHtmlTs from "@/components/docs/demos/fullscreen-button/html/css
 ## Anatomy
 
 <FrameworkCase frameworks={["react"]}>
-```tsx
-<FullscreenButton />
-```
+  ```tsx
+  <FullscreenButton />
+  ```
 </FrameworkCase>
 
 <FrameworkCase frameworks={["html"]}>
-```html
-<media-fullscreen-button></media-fullscreen-button>
-```
+  ```html
+  <media-fullscreen-button></media-fullscreen-button>
+  ```
 </FrameworkCase>
 
+## Behavior
+
+Toggles fullscreen mode. Detects platform support through `availability` — when fullscreen is `"unsupported"`, the toggle does nothing.
+
+## Styling
+
+You can style the button based on fullscreen state:
+
+```css
+/* In fullscreen */
+media-fullscreen-button[data-fullscreen] {
+  background: red;
+}
+```
+
+Consider hiding the button when unsupported:
+
+```css
+media-fullscreen-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: "Enter fullscreen" or "Exit fullscreen". Override with the `label` prop. Keyboard activation: <kbd>Enter</kbd> / <kbd>Space</kbd>.
+
 ## Examples
 
 ### Basic Usage
 
 <FrameworkCase frameworks={["react"]}>
   <StyleCase styles={["css"]}>
-    <Demo files={[
-      { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
-      { title: "App.css", code: basicUsageReactCss, lang: "css" },
-    ]}>
+    <Demo
+      files={[
+        { title: "App.tsx", code: basicUsageReactTsx, lang: "tsx" },
+        { title: "App.css", code: basicUsageReactCss, lang: "css" },
+      ]}
+    >
       <BasicUsageDemoReact client:idle />
     </Demo>
   </StyleCase>
@@ -52,11 +81,13 @@ import basicUsageHtmlTs from "@/components/docs/demos/fullscreen-button/html/css
 
 <FrameworkCase frameworks={["html"]}>
   <StyleCase styles={["css"]}>
-    <Demo files={[
-      { title: "index.html", code: basicUsageHtml, lang: "html" },
-      { title: "index.css", code: basicUsageHtmlCss, lang: "css" },
-      { title: "index.ts", code: basicUsageHtmlTs, lang: "ts" },
-    ]}>
+    <Demo
+      files={[
+        { title: "index.html", code: basicUsageHtml, lang: "html" },
+        { title: "index.css", code: basicUsageHtmlCss, lang: "css" },
+        { title: "index.ts", code: basicUsageHtmlTs, lang: "ts" },
+      ]}
+    >
       <BasicUsageDemoHtml />
     </Demo>
   </StyleCase>
diff --git a/site/src/content/docs/reference/mute-button.mdx b/site/src/content/docs/reference/mute-button.mdx
index 6e8985dd..46cf64a5 100644
--- a/site/src/content/docs/reference/mute-button.mdx
+++ b/site/src/content/docs/reference/mute-button.mdx
@@ -21,6 +21,17 @@ import basicUsageHtml from "@/components/docs/demos/mute-button/html/css/BasicUs
 import basicUsageHtmlCss from "@/components/docs/demos/mute-button/html/css/BasicUsage.css?raw";
 import basicUsageHtmlTs from "@/components/docs/demos/mute-button/html/css/BasicUsage.ts?raw";
 
+{/* React demos — Volume Levels */}
+import VolumeLevelsDemoReact from "@/components/docs/demos/mute-button/react/css/VolumeLevels";
+import volumeLevelsReactTsx from "@/components/docs/demos/mute-button/react/css/VolumeLevels.tsx?raw";
+import volumeLevelsReactCss from "@/components/docs/demos/mute-button/react/css/VolumeLevels.css?raw";
+
+{/* HTML demos — Volume Levels */}
+import VolumeLevelsDemoHtml from "@/components/docs/demos/mute-button/html/css/VolumeLevels.astro";
+import volumeLevelsHtml from "@/components/docs/demos/mute-button/html/css/VolumeLevels.html?raw";
+import volumeLevelsHtmlCss from "@/components/docs/demos/mute-button/html/css/VolumeLevels.css?raw";
+import volumeLevelsHtmlTs from "@/components/docs/demos/mute-button/html/css/VolumeLevels.ts?raw";
+
 ## Anatomy
 
 <FrameworkCase frameworks={["react"]}>
@@ -35,6 +46,32 @@ import basicUsageHtmlTs from "@/components/docs/demos/mute-button/html/css/Basic
 ```
 </FrameworkCase>
 
+## Behavior
+
+Toggles mute on and off, and exposes a derived `volumeLevel` based on the current volume and mute state.
+
+## Styling
+
+Style the button based on muted state:
+
+```css
+media-mute-button[data-muted] .icon-muted { display: inline; }
+media-mute-button:not([data-muted]) .icon-unmuted { display: inline; }
+```
+
+Use `data-volume-level` for multi-level icon switching:
+
+```css
+media-mute-button[data-volume-level="off"] .icon-off { display: inline; }
+media-mute-button[data-volume-level="low"] .icon-low { display: inline; }
+media-mute-button[data-volume-level="medium"] .icon-medium { display: inline; }
+media-mute-button[data-volume-level="high"] .icon-high { display: inline; }
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: "Unmute" when muted, "Mute" when unmuted. Override with the `label` prop. Keyboard activation: <kbd>Enter</kbd> / <kbd>Space</kbd>.
+
 ## Examples
 
 ### Basic Usage
@@ -62,4 +99,29 @@ import basicUsageHtmlTs from "@/components/docs/demos/mute-button/html/css/Basic
   </StyleCase>
 </FrameworkCase>
 
+### Volume Levels
+
+<FrameworkCase frameworks={["react"]}>
+  <StyleCase styles={["css"]}>
+    <Demo files={[
+      { title: "App.tsx", code: volumeLevelsReactTsx, lang: "tsx" },
+      { title: "App.css", code: volumeLevelsReactCss, lang: "css" },
+    ]}>
+      <VolumeLevelsDemoReact client:idle />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
+
+<FrameworkCase frameworks={["html"]}>
+  <StyleCase styles={["css"]}>
+    <Demo files={[
+      { title: "index.html", code: volumeLevelsHtml, lang: "html" },
+      { title: "index.css", code: volumeLevelsHtmlCss, lang: "css" },
+      { title: "index.ts", code: volumeLevelsHtmlTs, lang: "ts" },
+    ]}>
+      <VolumeLevelsDemoHtml />
+    </Demo>
+  </StyleCase>
+</FrameworkCase>
+
 <ApiReference component="MuteButton" />
diff --git a/site/src/content/docs/reference/pip-button.mdx b/site/src/content/docs/reference/pip-button.mdx
index 74312531..cd44954f 100644
--- a/site/src/content/docs/reference/pip-button.mdx
+++ b/site/src/content/docs/reference/pip-button.mdx
@@ -35,6 +35,33 @@ import basicUsageHtmlTs from "@/components/docs/demos/pip-button/html/css/BasicU
 ```
 </FrameworkCase>
 
+## Behavior
+
+Toggles picture-in-picture (PiP) mode. Detects platform support through `availability` — when PiP is `"unsupported"`, the toggle does nothing.
+
+## Styling
+
+You can style the button based on PiP state:
+
+```css
+/* In PiP mode */
+media-pip-button[data-pip] {
+  background: red;
+}
+```
+
+Consider hiding the button when unsupported:
+
+```css
+media-pip-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: "Enter PiP" or "Exit PiP". Override with the `label` prop. Keyboard activation: <kbd>Enter</kbd> / <kbd>Space</kbd>.
+
 ## Examples
 
 ### Basic Usage
diff --git a/site/src/content/docs/reference/play-button.mdx b/site/src/content/docs/reference/play-button.mdx
index 1fb1ad72..c346e747 100644
--- a/site/src/content/docs/reference/play-button.mdx
+++ b/site/src/content/docs/reference/play-button.mdx
@@ -35,6 +35,36 @@ import basicUsageHtmlTs from "@/components/docs/demos/play-button/html/css/Basic
 ```
 </FrameworkCase>
 
+## Behavior
+
+PlayButton is a three-state button: **play**, **pause**, and **replay**. When media reaches the end (`ended` state), clicking restarts playback from the beginning.
+
+## Styling
+
+Style with the `[data-paused]` and `[data-ended]` attributes to show/hide play/pause/replay icons based on state. For example:
+
+```css
+/* Paused (but not ended) */
+media-play-button[data-paused]:not([data-ended]) .play-icon { display: inline; }
+
+/* Playing */
+media-play-button:not([data-paused]) .pause-icon { display: inline; }
+
+/* Ended */
+media-play-button[data-ended] .replay-icon { display: inline; }
+```
+
+After first play, the `data-started` attribute is added and remains present until a new source is loaded. Use this to hide the play button when media hasn't started yet:
+
+```css
+/* Hide play button before first play */
+media-play-button:not([data-started]) .play-icon { display: none; }
+```
+
+## Accessibility
+
+Renders a `<button>` element with an automatic `aria-label` that updates based on state: "Play", "Pause", or "Replay". Override with the `label` prop (accepts a string or function). Keyboard activation: <kbd>Enter</kbd> / <kbd>Space</kbd>.
+
 ## Examples
 
 ### Basic Usage
diff --git a/site/src/content/docs/reference/poster.mdx b/site/src/content/docs/reference/poster.mdx
index a1408b55..a391c798 100644
--- a/site/src/content/docs/reference/poster.mdx
+++ b/site/src/content/docs/reference/poster.mdx
@@ -39,6 +39,26 @@ Import the component:
   ```
 </FrameworkCase>
 
+## Behavior
+
+The poster is visible before playback starts. Once the user plays or seeks, the poster hides permanently — pausing does not bring it back. The poster reappears when a new source is loaded.
+
+## Styling
+
+Style the poster with the `[data-visible]` attribute:
+
+```css
+media-poster:not([data-visible]) {
+  display: none;
+}
+```
+
+You control the child `<img>` — this means `srcset`, `sizes`, `loading="lazy"`, and framework image components all work naturally.
+
+## Accessibility
+
+Unlike the native `<video poster>` attribute, this component allows you to provide accessible text alternatives for screen readers via the `alt` attribute on your child `<img>`. This means you can describe the poster image (e.g., `alt="Keynote speaker at a conference"`) or mark it as decorative with `alt=""` if it doesn't convey meaningful information. 
+
 ## Examples
 
 ### Basic Usage
diff --git a/site/src/content/docs/reference/seek-button.mdx b/site/src/content/docs/reference/seek-button.mdx
index e12e0798..c68d6aa0 100644
--- a/site/src/content/docs/reference/seek-button.mdx
+++ b/site/src/content/docs/reference/seek-button.mdx
@@ -35,6 +35,14 @@ import basicUsageHtmlTs from "@/components/docs/demos/seek-button/html/css/Basic
   ```
 </FrameworkCase>
 
+## Behavior
+
+Seeks media by a configurable number of `seconds` (default 30). Positive values seek forward, negative values seek backward. The seek is clamped to media bounds (0 to duration).
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label` describing the action, e.g. "Seek forward 30 seconds" or "Seek backward 10 seconds". Override with the `label` prop. Keyboard activation: <kbd>Enter</kbd> / <kbd>Space</kbd>.
+
 ## Examples
 
 ### Basic Usage
diff --git a/site/src/content/docs/reference/time.mdx b/site/src/content/docs/reference/time.mdx
index c36647fe..757b333d 100644
--- a/site/src/content/docs/reference/time.mdx
+++ b/site/src/content/docs/reference/time.mdx
@@ -75,6 +75,42 @@ import customNegativeSignHtmlTs from "@/components/docs/demos/time/html/css/Cust
 ```
 </FrameworkCase>
 
+## Behavior
+
+Three display types — `current`, `duration`, and `remaining` — in digital format with smart padding:
+
+- **Hours** are never padded (`1:05:30`, not `01:05:30`)
+- **Minutes** are padded when hours are shown (`1:05:30`, but `5:30`)
+- **Seconds** are always padded (`1:05`, not `1:5`)
+
+Hour display is triggered when either the current value or the duration exceeds 1 hour, ensuring consistency within a Group. Remaining time displays a negative sign (customizable via the `negativeSign` prop).
+
+## Styling
+
+The negative sign is rendered inside `<span aria-hidden="true">` and can be hidden with CSS:
+
+```css
+[data-type="remaining"] > span[aria-hidden] {
+  display: none;
+}
+```
+
+## Accessibility
+
+<FrameworkCase frameworks={["html"]}>
+Each `<media-time>` has:
+- `aria-label` for the static role label ("Current time", "Duration", "Remaining")
+- `aria-valuetext` for the dynamic human-readable time ("1 minute, 30 seconds")
+</FrameworkCase>
+
+<FrameworkCase frameworks={["react"]}>
+Each `<Time.Value>` has:
+- `aria-label` for the static role label ("Current time", "Duration", "Remaining")
+- `aria-valuetext` for the dynamic human-readable time ("1 minute, 30 seconds")
+</FrameworkCase>
+
+No `aria-live` region is used — time updates too frequently and might overwhelm screen readers. The separator is `aria-hidden="true"` since screen readers already hear each time value separately. The negative sign is also `aria-hidden` because `aria-valuetext` already conveys "remaining". In React, `<time datetime>` provides machine-readable time for parsers.
+
 ## Examples
 
 ### Current Time
diff --git a/site/src/content/docs/reference/write-references.mdx b/site/src/content/docs/reference/write-references.mdx
new file mode 100644
index 00000000..68cca08f
--- /dev/null
+++ b/site/src/content/docs/reference/write-references.mdx
@@ -0,0 +1,205 @@
+---
+title: Write reference pages
+description: How to create component API reference pages for the Video.js documentation site
+---
+
+import Aside from '@/components/Aside.astro';
+import DocsLink from '@/components/docs/DocsLink.astro';
+
+This guide covers how to create component reference pages — the API documentation under `reference/` in the docs sidebar.
+
+<Aside type="tip">
+Reference pages are scaffolded with the `api-reference` Claude skill. Run `/api-reference play-button` to generate a reference page interactively.
+</Aside>
+
+## Prerequisites
+
+Before creating a reference page, the component must exist in:
+
+- **Core**: `packages/core/src/core/ui/{name}/{name}-core.ts` (props, state, behavior)
+- **HTML**: `packages/html/src/ui/{name}/` (custom element)
+- **React**: `packages/react/src/ui/{name}/` (React component)
+
+The component should be feature-complete enough that its props, state, and data attributes are stable.
+
+## Generate the API reference JSON
+
+The api-docs-builder extracts type information from TypeScript sources and outputs JSON files that the `<ApiReference />` component renders as tables.
+
+```bash
+pnpm -F site api-docs
+```
+
+This generates JSON to `site/src/content/generated-api-reference/{name}.json`. These files are gitignored and regenerated automatically on `pnpm dev` and `pnpm build`.
+
+### Builder naming conventions
+
+The builder relies on file naming conventions to discover components:
+
+| Convention | Pattern | Example |
+|------------|---------|---------|
+| Core file | `{name}-core.ts` | `play-button-core.ts` |
+| Data attrs | `{name}-data-attrs.ts` | `play-button-data-attrs.ts` |
+| HTML element | `{name}-element.ts` | `play-button-element.ts` |
+| React component | `packages/react/src/ui/{name}/` | `packages/react/src/ui/play-button/` |
+| Multi-part detection | `index.parts.ts` | `packages/react/src/ui/slider/index.parts.ts` |
+
+If the builder output is missing or incomplete, check that your files match these conventions. See `.claude/skills/api-reference/references/builder-conventions.md` for the full list.
+
+## Create demo files
+
+Each reference page needs at least a BasicUsage demo in both HTML and React.
+
+### HTML demo (4 files)
+
+```
+src/components/docs/demos/{name}/html/css/
+├── BasicUsage.astro    # Wrapper: imports CSS, renders HTML, bundles script
+├── BasicUsage.html     # Markup only (no <style> or <script>)
+├── BasicUsage.css      # Styles
+└── BasicUsage.ts       # Side-effect imports for custom element registration
+```
+
+The `.astro` wrapper ties everything together:
+
+```astro
+---
+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>
+```
+
+### React demo (2 files)
+
+```
+src/components/docs/demos/{name}/react/css/
+├── BasicUsage.tsx      # React component
+└── BasicUsage.css      # Styles
+```
+
+### BEM naming
+
+Use BEM class names for CSS scoping. The block name follows the pattern `{framework}-{component}-{variant}`:
+
+```css
+/* HTML demo */
+.html-play-button-basic__button { /* ... */ }
+
+/* React demo */
+.react-play-button-basic__button { /* ... */ }
+```
+
+React and HTML demos for the same variant should use matching BEM structures.
+
+### Video and poster sources
+
+All demos use these URLs:
+
+```
+Video: https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4
+Poster: https://image.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/thumbnail.jpg
+```
+
+All demo videos use `autoplay muted playsinline loop` (React: `autoPlay muted playsInline loop`).
+
+## Create the MDX reference page
+
+Create `site/src/content/docs/reference/{name}.mdx` with this structure:
+
+### Frontmatter
+
+```yaml
+---
+title: PlayButton
+frameworkTitle:
+  html: media-play-button
+description: A button component for playing and pausing media playback
+---
+```
+
+Use `frameworkTitle` to show the HTML custom element tag name when the HTML framework is selected.
+
+### Imports
+
+```tsx
+import ApiReference from "@/components/docs/api-reference/ApiReference.astro";
+import FrameworkCase from "@/components/docs/FrameworkCase.astro";
+import Demo from "@/components/docs/demos/Demo.astro";
+
+{/* React demos */}
+import BasicUsageDemoReact from "@/components/docs/demos/{name}/react/css/BasicUsage";
+import basicUsageReactTsx from "@/components/docs/demos/{name}/react/css/BasicUsage.tsx?raw";
+import basicUsageReactCss from "@/components/docs/demos/{name}/react/css/BasicUsage.css?raw";
+
+{/* HTML demos */}
+import BasicUsageDemoHtml from "@/components/docs/demos/{name}/html/css/BasicUsage.astro";
+import basicUsageHtml from "@/components/docs/demos/{name}/html/css/BasicUsage.html?raw";
+import basicUsageHtmlCss from "@/components/docs/demos/{name}/html/css/BasicUsage.css?raw";
+import basicUsageHtmlTs from "@/components/docs/demos/{name}/html/css/BasicUsage.ts?raw";
+```
+
+#### Import naming conventions
+
+| What | Naming pattern | Example |
+|------|---------------|---------|
+| React demo component | `{Variant}DemoReact` | `BasicUsageDemoReact` |
+| React source (TSX) | `{variant}ReactTsx` | `basicUsageReactTsx` |
+| React source (CSS) | `{variant}ReactCss` | `basicUsageReactCss` |
+| HTML demo component | `{Variant}DemoHtml` | `BasicUsageDemoHtml` |
+| HTML source (HTML) | `{variant}Html` | `basicUsageHtml` |
+| HTML source (CSS) | `{variant}HtmlCss` | `basicUsageHtmlCss` |
+| HTML source (TS) | `{variant}HtmlTs` | `basicUsageHtmlTs` |
+
+### Page sections
+
+After imports, the page follows this order:
+
+1. **Anatomy** — show the component markup for each framework using `<FrameworkCase>`
+2. **Prose sections** (optional, as needed):
+   - **Behavior** — state transitions, timing, interaction logic
+   - **Styling** — data attribute CSS selectors
+   - **Accessibility** — ARIA attributes, keyboard interactions
+   - Other sections as appropriate
+3. **Examples** — at least BasicUsage, wrapped in `<Demo>` with `<FrameworkCase>`
+4. **`<ApiReference />`** — renders the generated JSON as props, state, and data attribute tables
+
+```mdx
+<ApiReference component="PlayButton" />
+```
+
+The component automatically handles single-part and multi-part layouts.
+
+## Add to the sidebar
+
+Open `site/src/docs.config.ts` and add your page alphabetically within the Components section:
+
+```ts
+{
+  sidebarLabel: 'Components',
+  contents: [
+    // sorted alphabetically
+    { slug: 'reference/play-button' },
+    { slug: 'reference/your-component' }, // add here
+  ],
+},
+```
+
+## Verify
+
+1. Run `pnpm dev` from the repo root
+2. Navigate to your reference page in both HTML and React framework modes
+3. Confirm the anatomy, demos, and API reference tables render correctly
+4. Check that the page appears in the sidebar
+
+## Examples
+
+For reference, look at existing pages:
+
+- <DocsLink slug="reference/play-button">PlayButton</DocsLink> — single-part, interactive
+- <DocsLink slug="reference/controls">Controls</DocsLink> — behavior-heavy (auto-hide)
+- <DocsLink slug="reference/time">Time</DocsLink> — multi-part, formatting
diff --git a/site/src/docs.config.ts b/site/src/docs.config.ts
index d69e2065..83721c04 100644
--- a/site/src/docs.config.ts
+++ b/site/src/docs.config.ts
@@ -9,6 +9,11 @@ export const sidebar: Sidebar = [
         sidebarLabel: 'Writing guides',
         devOnly: true,
       },
+      {
+        slug: 'reference/write-references',
+        sidebarLabel: 'Writing references',
+        devOnly: true,
+      },
       { slug: 'how-to/installation' },
       { slug: 'concepts/v10-roadmap', sidebarLabel: 'Roadmap' },
     ],