Co-authored-by: videojs-release[bot] <324600730+videojs-release[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
@videojs/skins
Internal package. Private and unpublished. The framework packages and the Shadcn registry consume its output.
Canonical VJSC skin sources and the generators that deliver them to @videojs/html, @videojs/react, and the Shadcn registry. Write a skin once here; the build lowers it to every framework and styling target.
How a skin comes together
Follow one skin from source to output.
- A skin is a component tree.
src/skins/default/video/skin.tsxcomposes preset parts fromsrc/skins/shared/video/with shared components such asContainerandPoster. Each<theme>/<preset>folder owns only what differs for that skin. - Components pair markup with styles.
src/components/holds the target-independent UI. Everyx.tsxsits beside anx.styles.tsthat lists Tailwind classes per rule, withdefault,neutral, orcompatvariants where the themes differ. Skin-only overrides live beside the skin, for examplesrc/skins/default/video/layout/controls.styles.ts. - Classes resolve through tokens. Style modules read
--media-*tokens through Tailwind theme keys such asduration-media-fast, never literal values that vary per theme. Tokens are declared insrc/styles/themes/and classified insrc/styles/vars.ts. - The build lowers everything per target. The vjsc compiler, configured in
build/, turns each module into React and HTML implementations, compiles class lists into scoped CSS for the CSS targets, and emits Shadcn registry items. The build tooling and the playground consume the builtvjscpackage, so after a compiler change runpnpm -F vjsc build(or keeppnpm -F vjsc devrunning) and restart the playground. - The sandbox shows the result.
pnpm dev:sandboxand pick Authored source under Skins from to render any skin straight from this source, on either platform and in either styling, at any width and color scheme. Compare puts CSS beside Tailwind (compare=styling) or the authored skin beside the one its framework package ships (compare=skins), Direction flips the text direction, and Report copies the environment details. The skin-parity suite inapps/e2edrives the same pages.
Where things live
| Path | Owns |
|---|---|
src/components/ |
Shared UI grouped as behaviors, buttons, dialogs, display, layout, menus, and sliders. |
src/skins/ |
Skin folders grouped by theme and preset (default/video, neutral/audio, compat/video, and so on), with reused parts under shared/. |
src/styles/ |
Base resets, themes, tokens, the shared Tailwind source, and style modules grouped like the components. |
src/presets/ |
The handwritten background preset, copied into both packages as is. |
src/meta.ts |
Skin and component metadata for the registry. Shared parts use defineRenderTarget from vjsc/components. |
src/gaps.md |
Deferred parity gaps. Maintain it with the maintain-vjsc-skin-gaps skill. |
src/tests/ |
Contract tests for tokens, the utility catalog, metadata, and poster behavior. |
build/ |
Pack config, transform resolvers, framework targets, package writers, and the Shadcn registry. |
Styles and tokens
base.css fixes the cascade: base.theme holds tokens and base.preferences overrides them, so a reduced motion, reduced transparency, or forced colors preference wins regardless of selector specificity.
themes/theme.cssdeclares every default token, grouped by colors, shadows, controls, motion, popups, sliders, and frame.themes/neutral.cssandthemes/compat.cssoverride tokens for their respective skins.video/theme.cssandaudio/theme.cssoverride tokens per media preset.themes/preferences.csscollapses durations and neutralizes hidden-state values under reduced motion, and switches backdrop filters off under reduced transparency.video/base.cssandaudio/base.cssare the default preset entries. Their adjacentneutral.cssandcompat.cssentries add the selected theme layer.vars.tsclassifies every token as public, runtime, or internal.utilities.tsdescribes every shared utility, variant, and computed theme key.
Tailwind entry files
Three files in src/styles/ chain together. Only the first ships to consumers.
| File | Purpose | Used by |
|---|---|---|
tailwind.css |
The design system: theme keys that alias --media-* tokens, shared @utility recipes, and media-* variants. No Tailwind import and no @source, so it works inside a consumer's own setup. |
Both entries below, the registry theme item, and the catalog tests. |
tailwind.compiler.css |
The build design system. Imports Tailwind, base, captions, presets, and the shared file, and aliases --spacing to the scaled media unit. No @source: the compiler applies class lists directly and never scans files. |
build/transform.ts and the registry theme test. |
Add a shared recipe to tailwind.css as a flat @utility, describe it in utilities.ts, and prefer a token plus theme key over a literal. The component skill has the full rules.
Build outputs
generate runs build/vite.config.ts and writes three things:
- Skin implementations into the ignored
packages/html/src/internal/skins/andpackages/react/src/internal/skins/folders, plus preset registrations and stylesheets underpackages/html/src/define/and the background preset underpackages/react/src/presets/, throughbuild/packages/. - Shadcn source registries for React with Tailwind, React with CSS, and HTML into
dist/registry/source/r/, from the items inbuild/registry/items/and the targets inbuild/registry/targets.ts. - The hosted registry in
dist/shadcn/throughbuild:shadcn, whichnetlify.tomlpublishes.
The normal registry E2E packs the current workspace packages so source and package changes can be tested before release. The Netlify production build additionally runs pnpm test:e2e:registry:published from the workspace root. That smoke test creates a fresh Next app, installs the video and audio skins through the stock Shadcn CLI, and builds them against the registry's exact npm package pins without local overrides. It is expected to pass only after those package versions have been published. To compare unreleased registry source with the newest package cut locally, run the same command with VIDEOJS_REGISTRY_PACKAGE_TAG=latest; production leaves that override unset.
Each framework and styling has default, /neutral, /compat, and /scaffold catalogs. All publish the same skin item names (video, audio, live-video, and live-audio) and install to the same preset paths under components/videojs/. A project chooses one theme by pointing its Shadcn namespace at one catalog; the default catalog keeps the shorter URL. Default and Neutral publish standalone shared UI under components/videojs/ui/. Compat and Scaffold publish complete skins with editable parts beside each preset.
Commands
Run these from packages/skins.
pnpm dev # package inputs regenerated on change; preview in the sandbox
pnpm exec vp run generate # regenerate package inputs and registries
pnpm exec vp run validate:shadcn # schema and policy checks on the hosted registry
pnpm test # type check plus unit, build, and registry tests