SKILL.md

Tailwind CSS for HyperFrames

HyperFrames 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

The user asks for Tailwind in a HyperFrames composition.

A project was created with hyperframes init --tailwind.

You see window.__tailwindReady in index.html.

You need utility classes, CSS-first theme tokens, custom utilities, or v3-to-v4 migration guidance.

The render has missing styles and the project is relying on the browser runtime.

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.

HyperFrames 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.

HyperFrames 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 hyperframes lint

npx hyperframes validate

npx hyperframes inspect

For a render proof:

npx hyperframes 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

Confirm the project was scaffolded with hyperframes init --tailwind.

Confirm the script points to @tailwindcss/browser@4.2.4.

Confirm window.__tailwindReady is present.

Replace v3 @tailwind directives with v4 browser-runtime CSS.

Move custom tokens from tailwind.config.js to @theme.

Replace dynamically assembled classes with complete static tokens.

Run npx hyperframes 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 HyperFrames-specific.

tailwind