# Video foundations
> What @sdxc/ui/video is for, the native-first rules its parts share, and every variable it reads.

One video player in parts: a screen, a chapter scrubber, chapters and a transcript beside it, and a control bar with a settings menu.

Chapters and lines are written once as data and feed the captions, the scrubber and the lists alike.

Import the components from `@sdxc/ui/video` and the theme once from `@sdxc/ui/theme.css`.

## When to reach for it

- A lesson, talk or demo video with chapters and a transcript.
- A product video on a landing or docs page that should play before script loads.
- A player whose settings menu needs the page's own toggles, such as ambient mode.

## Shared ideas

- **Native first.** The server renders `<video controls>`; the island hides them and reveals `.Controls`.
- **Links seek.** Every time is a `#t=` link into the first source, so it plays from there with no script.
- **Data once.** Chapters and the transcript become WebVTT tracks as `data:` URLs, so captions need no file.
- **Real controls.** Settings rows are checkboxes and radios; the page reads them by `name` from `change`.
- **Keyboard.** The menu walks with the arrows; → opens a submenu, ← leaves it, Enter picks.
- **On the picture.** The bar and the menu stay dark with light ink in either page scheme.

## CSS variables

Every custom property the namespace reads or declares. Reads the neutral role for text, hairlines and the plain surface, and brand for the current chapter, line and scrubber fill. The roles are documented on Theming.

### Shape

None is declared in `theme.css`; set any of them on the player or an ancestor.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-video-player-radius` | `var(--ui-landing-radius-frame, 0.75rem)` | Outer radius of the player; the screen nests a smaller one. |
| `--ui-video-player-transcript-height` | `11rem` | Height of the transcript's scroll region. |
| `--ui-video-player-progress-color` | `oklch(0.63 0.22 27)` | Fill of the seek slider, the captions mark, an on switch and the gear badge. |

### Set by the tone

`tone="plain"` follows the page; `tone="theater"` keeps a dark room in either scheme.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-video-player-bg` | `var(--ui-surface-raised, Canvas)` | The player's surface. |
| `--ui-video-player-accent` | `var(--ui-brand-fg)` | The current chapter, the current line's time and the scrubber's fill. |
| `--ui-video-player-line` | `var(--ui-landing-hairline, …)` | Hairlines and the scrubber's unplayed track. |