YouTube / Public web reference / 2026.09
Implementation contracts
Use the local HTML, CSS and JavaScript as the reference API. The package runs as static files behind a small local HTTP server.
All entries shown
Source map
| Concern | File | Contract |
|---|---|---|
| Product layout and tokens | product.css | Base styles for recipe and component examples. Read exact selectors beside each specimen. |
| Product cascade corrections | control-overrides.css | Loaded after product.css. Includes measured layout corrections and state rules; retrieve both stylesheets. |
| Product behavior | product.js | Native controls and deterministic fixture state. No remote account writes. |
| Documentation shell | guide.css · guide.js | Guide-only navigation, page filtering and theme toggle. |
| Data fixtures | Download local component contracts | Local anatomy, inputs, outputs, states and source references. |
| Source measurements | Package: reference-data/component-geometry.json | Raw production geometry retained with source captures. |
| Verification | scripts/crawl-site.cjs and control-audit-contract.json | Four viewport crawl plus explicit before/after pointer and keyboard outcomes. |
Run and reproduce
cd designs/youtube python3 -m http.server 8765 --directory site # From the repository root, in a second terminal: .agents/skills/design-research/scripts/run-playwright.sh \ designs/youtube/scripts/crawl-site.cjs \ http://127.0.0.1:8765/ designs/youtube/evidence/local-crawl .agents/skills/design-research/scripts/run-playwright.sh \ .agents/skills/design-research/scripts/audit-controls.cjs \ http://127.0.0.1:8765/ --contract \ designs/youtube/reference-data/control-audit-contract.json
Machine-readable reference
component-api · local-component-contracts · local-governance · example-page-ledger · observed-tokens · operational-contract · premium-content-variants
Adding a variant
- Find the component row and its stable specimen.
- Keep public anatomy and semantic roles; add a named variant to the local CSS.
- Add fixture data, including long and missing content.
- Define the visible result, native or ARIA state and focus behavior.
- Add the specimen and coverage mapping. Never mark a local addition “observed”.
- Run the control audit and viewport comparison before changing the frozen package identity.
Integration boundaries
| Boundary | Rule | Verification |
|---|---|---|
| Routing | Use relative hrefs and encoded query parameters. No root-absolute asset paths. | Crawl beneath both localhost and the published base URL. |
| Safety | Use textContent for untrusted fixture text. Do not place user text into HTML. | Fixtures include angle brackets and long text; no inline executable content from inputs. |
| Persistence | Fixture actions stay in memory. The appearance preference alone uses localStorage key youtube-fixture-theme with light or dark values; it lasts until site storage is cleared. No accounts or remote writes. | Fresh browser contexts start from defaults. Reload preserves only the saved theme preference. |
| Privacy | No telemetry or identity collection. Audio and video do not autoplay. Premium illustrations are lazy-loaded; reduced motion uses still frames. | Browser resources remain local after page load except manually opened primary-source links. |
| Performance | Keep first-page local transfer under 5 MB, no external runtime or font dependency. | Retain resource sizes from crawl; use lazy loading for catalog images. |
| Versioning | Research date and source hashes identify a candidate. CSS/code or evidence edits require refreeze. | Both manifests and the composite package hash must match each judge’s review. |
| Ownership | Package maintainer owns source refresh, visual comparisons and regression repair. | Reinspect sources before using the package for a new product release. |
Accessibility target
The local reference targets WCAG 2.2 AA for implemented interactions. Use semantic landmarks, one page heading, visible keyboard focus, meaningful names, state announcements, 24 px minimum pointer targets and larger touch targets where space permits. Test Chromium keyboard behavior, 200% text resize, narrow reflow, reduced motion and forced colors. Automated checks do not establish a full assistive-technology or disabled-user usability study.
Local operational contract
These rules describe the static reference and its deterministic fixtures. Retrieve the operational contract.
| Contract | Rule and recovery |
|---|---|
| delivery-budgets | Initial page resource transfer must stay below 5,000,000 bytes. Load fonts, scripts, styles, images and original fixture media from this publication. Lazy-load long catalog images. Do not autoplay audio or video. Lazy-load Premium animated illustrations and use deterministic first-frame posters when reduced motion is requested. Keep page overflow within one CSS pixel at 390, 768, 1440 and 1920 pixels. Compress or defer the offending asset; retain its dimensions to prevent layout shifts. Recapture the affected page. |
| content-and-data | Treat video titles, query text and channel names as text. Encode query parameters with encodeURIComponent. Missing creator names use Channel unavailable; missing duration omits the duration badge. Keep object identity stable while filters change visibility. The local fixture contains a bounded collection; it does not promise production pagination, ranking or concurrency. Use textContent or native input.value. Do not interpret fixture strings as markup. Add the failing long, Unicode or missing case to the family specimen. |
| interruption-and-recovery | Loaded controls remain usable offline. A repeated menu or account-gate action leaves one current layer. Escape closes the active layer and returns focus to its trigger. The static site has no service-worker cache: navigating or reloading offline may show the browser's network error. The browser owns native media buffering and clipboard permission failures; show explicit failure copy and keep surrounding content available. Preserve query and object identity, cancel the current local layer, and expose a retry only when it can perform a real documented action. |
| account-and-authorization | Every account-dependent local action opens the signed-out boundary. The fixture never changes a subscription, saves a playlist, sends a comment, authenticates an account or collects payment data. Keep private completion states outside observed claims. A public action's visibility is not proof that the user has permission to complete it. Restore the gate and remove any false success state. Reverify both pointer and keyboard contracts. |
| privacy-and-storage | No cookies, telemetry, identity collection, watch-history persistence or runtime calls to third parties. Appearance alone may persist under youtube-fixture-theme with light or dark values. Ignore invalid stored values. If storage is disabled, retain the current in-memory appearance and keep controls usable. Users can reset appearance with Light or clear site storage. Remove unexpected collection or network calls. Guard storage access; a storage error must not abort control initialization. |
| browser-and-input-boundary | Verified runtime is Chromium 152 with native semantics, pointer and keyboard input, at four viewport widths. The guide retains reduced-motion, forced-color and 200% text-resize tests. Native browser accessibility snapshots support semantic inspection. Physical assistive-technology user testing and other browser engines remain unverified; do not claim universal compatibility. Record the failing environment and repair the local contract before adding it to the supported matrix. |
| diagnostics-and-changes | Retain page URL, viewport, control selector, expected result and before/after state in local test reports. Never collect a visitor's query or activity to monitor this guide. There are no runtime experiments or feature flags. To roll back a release, restore the prior frozen static package and publish it under the same private site name. Any evaluated content change requires a new package and dependency freeze and new independent review. Keep the failed release provisional, retain the failing report, restore the last verified package if necessary, and record the migration in CHANGELOG.md. |
Run scripts/verify-operational.cjs through the Playwright wrapper. Its report records transfer budgets, external requests, unsafe query handling, repeated input, offline controls, appearance persistence and storage denial. The current verification result is kept in the package. A physical screen-reader study and other browsers remain outside the verified matrix.
Component APIs
Use the fields below together with the runnable specimen. State belongs to the named control or component, and parent containers own layout gaps.
global-header
Anatomy and supported states
menu trigger, logo link, search input, clear-query control, search submit, voice search, settings, sign-in
empty query, populated query, signed-out
| Local API field | Contract |
|---|---|
| root | [data-denominator="global-header"] |
| selectors | .yt-header .searchbox .icon-button .signin |
| authority | reconstructed local contract |
| inputs | query string q |
| defaults | query: drawerExpanded: true on desktop fixture |
| events | submit search form click drawer click voice click sign in |
| outputs | search.html?q=<encoded query> native required-message for empty query local voice or sign-in boundary dialog |
| focus | The search input is tabbable. Boundary dialog receives focus and Escape restores the triggering control. |
| errors | empty query blocks navigation voice and sign-in stay within the public-evidence boundary |
| motion | Guide transform is 150ms except under reduced motion. |
| invariants | header is 56px high search uses a native form and named input buttons have accessible names |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
shell.header.search-combobox · 18 inventory-derived coverage rows
desktop-guide
Anatomy and supported states
guide trigger, primary route entries, explore grouping, more-from-YouTube grouping, sign-in prompt, collapse, show-more
expanded, collapsed, signed-out
| Local API field | Contract |
|---|---|
| root | [data-denominator="desktop-guide"] |
| selectors | .guide .guide a .guide h2 |
| authority | reconstructed local contract |
| inputs | drawer trigger |
| defaults | desktop: expanded narrow: off-canvas |
| events | click drawer |
| outputs | guide open or collapsed class and matching aria-expanded |
| focus | The trigger retains normal button focus. |
| errors | |
| motion | Narrow guide transform is 150ms except under reduced motion. |
| invariants | guide is 240px wide when open navigation links remain native anchors |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
shell.navigation.guide · 20 inventory-derived coverage rows
search-filter-tab-row
Anatomy and supported states
scroll previous, filter tabs, scroll next, Filters trigger
aria-selected=true, aria-selected=false, overflow controls
| Local API field | Contract |
|---|---|
| root | [data-denominator="search-filter-tab-row"] |
| selectors | .chip-row .chip .filters .filters-panel |
| authority | reconstructed local contract |
| inputs | selected filter tab Filters trigger |
| defaults | selected: All panel: closed |
| events | click filter tab click Filters |
| outputs | aria-selected moves to selected tab matching result cards hide status text announces filter filter panel hidden state changes |
| focus | Tabs are native buttons with role=tab. |
| errors | |
| motion | No scripted animation. |
| invariants | one filter tab has aria-selected=true chip order is fixture data, not a production claim |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
search.filters · 14 inventory-derived coverage rows
search-result-card
Anatomy and supported states
thumbnail, duration or live badge, title, channel identity, metadata, description, overflow action
standard, sponsored, live, mix, original long-title robustness fixture, original Arabic RTL robustness fixture, original missing-media robustness fixture
| Local API field | Contract |
|---|---|
| root | [data-denominator="search-result-card"] |
| selectors | .results .result .thumb .duration .overflow |
| authority | reconstructed local contract |
| inputs | overflow trigger menu choice |
| defaults | menu: closed result: visible |
| events | click More click Not interested click Save |
| outputs | menu role=menu opens Not interested hides local card Save opens public sign-in boundary |
| focus | Opened menu receives focus on its first menu item. |
| errors | authenticated save is intentionally blocked by the sign-in boundary |
| motion | No scripted animation. |
| invariants | thumbnail is a link overflow state is owned by its card |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
content.video-card · 20 inventory-derived coverage rows
video-player
Anatomy and supported states
play, next, mute, seek bar, live indicator, autoplay, CC, settings, theater, cast, fullscreen, like, dislike, share, save, download, more actions
paused, playing documented, unavailable observed, CC unavailable observed, settings collapsed, signed-out gated completion
| Local API field | Contract |
|---|---|
| root | [data-denominator="video-player"] |
| selectors | .player .unavailable .player-controls .seek |
| authority | reconstructed local contract |
| inputs | unavailable fixture: settings trigger local-media fixture: play or pause, mute, seek, settings, fullscreen |
| defaults | unavailableFixture: availability: unavailable settings: closed localMediaFixture: availability: original local media paused: true muted: true autoplay: false |
| events | click unavailable-fixture settings click local-media play or pause click local-media mute change local-media seek click local-media settings click local-media fullscreen |
| outputs | unavailable settings role=menu toggles local media play state and status update local mute state and status update local seek status updates local settings menu opens local fullscreen request updates aria-pressed |
| focus | Both settings triggers stay reachable; unavailable quality item is disabled. |
| errors | The unavailable fixture does not claim usable playback. The original local-media fixture does not claim YouTube stream playback, captions, quality, ads, or cast behavior. |
| motion | No scripted animation. |
| invariants | The unavailable fixture remains distinct from the public playable-player observation. The playable-local fixture uses original local media and never autoplays. The seek bar is functional only in the original local-media fixture. |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
watch.player · 32 inventory-derived coverage rows
playable-local-media
Anatomy and supported states
native video, play or pause, mute, seek, settings, full screen
no autoplay, paused, playing, muted, unmuted, reduced motion
| Local API field | Contract |
|---|---|
| root | [data-denominator="playable-local-media"] |
| selectors | .playable-player #local-video .player-controls [data-action="media-play"] [data-action="media-mute"] [data-action="media-seek"] [data-action="media-settings"] [data-action="media-fullscreen"] |
| authority | reconstructed local contract |
| inputs | play or pause mute seek value settings fullscreen |
| defaults | paused: true muted: true autoplay: false mediaAuthority: original local two-second clip |
| events | click play or pause click mute change seek click settings click fullscreen |
| outputs | native video play state changes mute state changes status announces seek value settings menu opens fullscreen request sets aria-pressed |
| focus | Every control has an accessible name. |
| errors | The clip is a local test fixture and makes no claim about YouTube playback content or production player behavior. |
| motion | No autoplay; native media progression begins only after an explicit play action. |
| invariants | Original local media only separate component from the public-derived video player the control test retains decoded dimensions and state transitions at 390px and 1440px |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
fixture.native-video · 16 inventory-derived coverage rows
metadata-description
Anatomy and supported states
summary copy, more trigger, less trigger
collapsed, expanded
| Local API field | Contract |
|---|---|
| root | [data-denominator="metadata-description"] |
| selectors | .description-toggle .watch-title .channel-line |
| authority | reconstructed local contract |
| inputs | READ MORE trigger |
| defaults | expanded: false |
| events | click expand |
| outputs | target hidden state toggles aria-expanded and label change |
| focus | The trigger keeps normal button focus. |
| errors | |
| motion | No scripted animation. |
| invariants | description only appears when expanded |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
watch.description · 9 inventory-derived coverage rows
channel-header
Anatomy and supported states
avatar or banner not measured, name, handle, counts, description, links disclosure, subscribe
public signed-out, description collapsed
| Local API field | Contract |
|---|---|
| root | [data-denominator="channel-header"] |
| selectors | .channel-hero .channel-cover .channel-head .subscribe |
| authority | reconstructed local contract |
| inputs | description disclosure Subscribe |
| defaults | description: collapsed signedIn: false |
| events | click description click Subscribe |
| outputs | description state toggles Subscribe opens sign-in boundary |
| focus | Disclosure and Subscribe are native buttons. |
| errors | channel editing and Studio behavior are outside scope |
| motion | No scripted animation. |
| invariants | local title and tab geometry retain mismatch evidence until repaired |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
channel.header · 15 inventory-derived coverage rows
channel-tabs
Anatomy and supported states
Home, Videos, Shorts, Live, Podcasts, Playlists, Posts
one selected, remaining unselected
| Local API field | Contract |
|---|---|
| root | [data-denominator="channel-tabs"] |
| selectors | .tabs .tabs button .tabs button[aria-selected=true] |
| authority | reconstructed local contract |
| inputs | selected channel tab |
| defaults | selected: Home |
| events | click tab |
| outputs | aria-selected moves local shelf heading and cards update status text changes |
| focus | Tabs are native buttons with role=tab. |
| errors | |
| motion | No scripted animation. |
| invariants | exactly one tab is selected tabs overflow horizontally rather than wrapping |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
channel.tabs · 20 inventory-derived coverage rows
history-gate
Anatomy and supported states
heading, explanatory copy, sign-in action, watch/search history controls
signed out
| Local API field | Contract |
|---|---|
| root | [data-denominator="history-gate"] |
| selectors | .history-gate .history-actions |
| authority | reconstructed local contract |
| inputs | Sign in action |
| defaults | signedIn: false |
| events | click sign in |
| outputs | public sign-in boundary dialog |
| focus | Sign-in action remains a native button. |
| errors | personal history rows are not fabricated |
| motion | No scripted animation. |
| invariants | signed-out gate has no private history data |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
access.signed-out-gate · 11 inventory-derived coverage rows
playlist-save-flow
Anatomy and supported states
playlist identity and cover, ordered playlist rows, type filters, more action, save account gate, public sign-in boundary
public signed-out viewing, account-gated save
| Local API field | Contract |
|---|---|
| root | [data-denominator="playlist-save-flow"] |
| selectors | .playlist .playlist-cover .playlist-row |
| authority | reconstructed local contract |
| inputs | playlist type filter More action Save action |
| defaults | signedIn: false filter: All |
| events | click filter click More click Save |
| outputs | public ordered rows filter Save opens the public sign-in boundary |
| focus | Filters and actions remain native buttons; the boundary dialog receives focus. |
| errors | Authenticated playlist creation, naming, privacy editing, and reordering are retained boundaries rather than fabricated public UI. |
| motion | No scripted animation. |
| invariants | The local contract covers public playlist identity, ordered rows, type filters, More, and account-gated Save only. The dynamic sign-in boundary proves the signed-out path without asserting an authenticated playlist editor. |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
collection.playlist-list · 14 inventory-derived coverage rows
shorts-player
Anatomy and supported states
vertical Short, continuous feed, overlay controls not captured
continuous advance documented, Clear Screen staged rollout
| Local API field | Contract |
|---|---|
| root | [data-denominator="shorts-player"] |
| selectors | .shorts-viewer .short-frame .short-overlay .short-actions |
| authority | reconstructed local contract |
| inputs | like dislike share next |
| defaults | selected: false currentItem: 1 |
| events | click toggle click Share click next |
| outputs | aria-pressed toggles Share dialog opens fixture title/image/status changes |
| focus | Every action has an accessible name. |
| errors | continuous feed runtime and playback controls remain unverified |
| motion | No scripted animation. |
| invariants | vertical frame remains distinct from normal video player |
| stateOwnership | data-action and ARIA state are owned by site/examples/product.js. CSS ownership is site/examples/product.css followed by site/examples/control-overrides.css. A state without an implemented matching denominator is explicitly unverified. |
| responsiveOwnership | @media (max-width:900px) and @media (max-width:560px) in site/examples/product.css |
| semantics | Use native button, input, form, link, dialog, tablist, and tab semantics when the part is interactive. Preserve the captured aria-* state on the control that owns the action. |
Production CSS trace
No source selector verified; consult the reconstruction boundary.
shorts.viewer · 12 inventory-derived coverage rows