---
id: alecs5am/ralphy/tailwind
version: "83408c86"
license: Apache-2.0
install: manual
updated: 2026-07-27
---

# tailwind — This skill covers Tailwind v4 browser-runtime styling for HyperFrames compositions scaffolded with `hyperframes init --tailwind`. It explains CSS-first theme tokens, utility classes, dynamic class safety, and when to compile to CSS instead of relying on the runtime. Use it to debug missing styles, migrate from v3 syntax, and ensure deterministic frame rendering.

Publisher: alecs5am · Stars: 112 · Updated: 2026-07-27

Install (manual): `git clone https://github.com/alecs5am/ralphy`

## 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:

```html
<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:

```css
/* 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.

```html
<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:

```html
<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:

```js
// 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:

```html
<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:

```bash
npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect
```

For a render proof:

```bash
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

1. Confirm the project was scaffolded with `hyperframes 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 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.


[View on SkillFed](https://skillfed.io/alecs5am/ralphy/tailwind) · [View on GitHub](https://github.com/alecs5am/ralphy)