tailwind

Tailwind CSS for FrameVideo

FrameVideo init --tailwind uses the Tailwind browser runtime pinned to @tailwindcss/browser@4.2.4. Treat that as Tailwind v4, not v3.

This skill is for composition HTML generated by the CLI. It is not for packages/studio, which still uses Tailwind v3 internally with tailwind.config.js, PostCSS, and @tailwind directives.

When To Use

Use this skill when:

• Project uses Tailwind — created with framevideo init --tailwind
• Writing utility classes — styling composition HTML with Tailwind classes
• Custom theme tokens — defining colors, fonts, spacing with @theme
• v3 to v4 migration — converting old syntax to CSS-first v4
• Runtime debugging — styles missing or window.__tailwindReady issues

Do NOT Use

Avoid this skill for:

• Non-Tailwind projects — if project doesn't use Tailwind, write vanilla CSS
• Studio UI development — Studio uses v3 with PostCSS (different setup)
• Backend/CLI code — this is only for composition HTML
• When CSS compilation is preferred — compile Tailwind to CSS for production stability

---

Quick Start

Create Tailwind-enabled project:

npx framevideo init my-video --tailwind
cd my-video

Use utilities in composition HTML:

<div class="clip" data-start="0" data-duration="5">
  <div class="flex items-center justify-center h-screen">
    <h1 class="text-6xl font-bold text-white">Hello Tailwind</h1>
  </div>
</div>

Add custom theme:

<style type="text/tailwindcss">
  @theme {
    --color-brand: oklch(0.68 0.2 252);
    --font-display: "Inter", sans-serif;
  }
</style>

<!-- Use in HTML -->
<h1 class="text-brand font-display">Brand Title</h1>

---

Version Contract

• Pinned runtime: @tailwindcss/browser@4.2.4.
• Browser runtime script is injected by the CLI. Do not replace it with cdn.tailwindcss.com.
• FrameVideo waits for window.__tailwindReady before frame capture starts.
• The readiness shim must stay deterministic: no render-loop polling APIs, no clock-based retries, no runtime network fetches beyond the pinned Tailwind runtime script.
• For offline, locked-down, or production-stable renders, compile Tailwind to CSS and include the stylesheet directly instead of relying on the browser runtime.

v4 Rules

Tailwind v4 is CSS-first:

<style type="text/tailwindcss">
  @theme {
    --color-brand: oklch(0.68 0.2 252);
    --font-display: "Inter", sans-serif;
  }

  @utility headline-balance {
    text-wrap: balance;
    letter-spacing: 0;
  }
</style>

Avoid v3 setup patterns in browser-runtime compositions:

/* Do not use these in Tailwind v4 browser-runtime compositions. */
@tailwind base;
@tailwind components;
@tailwind utilities;

Do not add a tailwind.config.js just to define colors, fonts, spacing, or utilities for a v4 browser-runtime composition. Use @theme and @utility in a text/tailwindcss style block.

If you truly need an existing JavaScript config for a compiled v4 build, load it explicitly from CSS with @config, then validate in the browser. Do not assume v4 auto-detects v3 config files.

FrameVideo Composition Pattern

Keep Tailwind responsible for static layout and visual style. Keep motion timing in GSAP or another seekable adapter.

<section
  class="clip absolute inset-0 grid place-items-center bg-zinc-950 text-white"
  data-start="0"
  data-duration="5"
  data-track-index="1"
>
  <div class="w-[1280px] max-w-[82vw] text-center">
    <p class="mb-6 text-xl font-medium uppercase tracking-[0.18em] text-cyan-300">
      Render-ready Tailwind
    </p>
    <h1 class="text-7xl font-black leading-none text-balance">
      Utility classes, deterministic frames.
    </h1>
  </div>
</section>

For repeated items, prefer class lists plus CSS custom properties over generating class names dynamically:

<span class="inline-block translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 0"></span>
<span class="inline-block translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 1"></span>
<span class="inline-block translate-y-[calc(var(--i)*6px)] opacity-80" style="--i: 2"></span>

Dynamic Class Safety

Tailwind's browser runtime scans the current document and generates CSS for class names it can see. Do not build render-critical class names only at seek time:

// Risky: Tailwind may not see every generated class before capture.
element.className = `bg-${color}-500`;

Use complete class names in HTML, data attributes, or explicit CSS instead:

<div data-tone="blue" class="bg-blue-500 data-[tone=rose]:bg-rose-500"></div>

If a generated class is unavoidable, make sure the full class token appears in a text/tailwindcss block before validation.

Video-Specific Guardrails

• Use stable dimensions: w-[...], h-[...], aspect-video, grid, flex, and fixed padding for video layouts.
• Prefer transforms and opacity for animated properties.
• Keep Tailwind transitions out of render-critical timing unless a seekable runtime owns the state.
• Avoid hover, focus, scroll, viewport, or pointer variants for content that must render deterministically.
• Use explicit border colors. Tailwind v4 changed the default border behavior from v3, so border border-white/20 is safer than bare border.
• Use v4 utility names: shadow-xs, rounded-xs, outline-hidden, shrink-*, and grow-* where those replacements apply.
• Be careful with modern CSS utilities if the output needs older browser support. Tailwind v4 targets modern browsers.

Validation

After editing a Tailwind-enabled composition:

npx framevideo lint
npx framevideo validate
npx framevideo inspect

For a render proof:

npx framevideo render . --workers 1 --quality draft --output tailwind-proof.mp4

The validation path should show no missing-style flashes on frame 0. If styles appear in preview but not render, check that window.__tailwindReady exists and resolves before capture.

Quick Debug Checklist

1. Confirm the project was scaffolded with framevideo init --tailwind.
2. Confirm the script points to @tailwindcss/browser@4.2.4.
3. Confirm window.__tailwindReady is present.
4. Replace v3 @tailwind directives with v4 browser-runtime CSS.
5. Move custom tokens from tailwind.config.js to @theme.
6. Replace dynamically assembled classes with complete static tokens.
7. Run npx framevideo validate and render a short proof.

Credits And References

• Tailwind CSS official v4 installation, upgrade, and compatibility docs: https://tailwindcss.com/docs
• Tailwind CSS v4 release notes: https://tailwindcss.com/blog/tailwindcss-v4
• Community Tailwind skills were reviewed for v4 gotchas and skill shape, but this skill keeps the durable contract in-repo and FrameVideo-specific.