tailwind

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS for HyperFrames

适用于HyperFrames的Tailwind CSS

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.

HyperFrames的

init --tailwind

命令使用固定版本为

@tailwindcss/browser@4.2.4

的Tailwind浏览器运行时，请将其视为Tailwind v4而非v3。

本指南适用于CLI生成的合成HTML，不适用于

packages/studio

——后者内部仍使用Tailwind v3，搭配

tailwind.config.js

、PostCSS和

@tailwind

指令。

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.

用户在HyperFrames合成项目中需要使用Tailwind
项目是通过
```
hyperframes init --tailwind
```
创建的
在
```
index.html
```
中能看到
```
window.__tailwindReady
```
需要使用工具类、CSS优先的主题令牌、自定义工具类，或需要v3到v4的迁移指导
渲染时出现样式丢失，且项目依赖浏览器运行时

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.

固定运行时版本：
```
@tailwindcss/browser@4.2.4
```
浏览器运行时脚本由CLI注入，请勿替换为
```
cdn.tailwindcss.com
```
HyperFrames会等待
```
window.__tailwindReady
```
就绪后再开始帧捕获
就绪垫片必须保持确定性：禁止使用渲染循环轮询API、基于时钟的重试，除固定版本的Tailwind运行时脚本外，禁止运行时网络请求
对于离线、锁定环境或生产稳定的渲染场景，请将Tailwind编译为CSS并直接引入样式表，而非依赖浏览器运行时

v4 Rules

v4规则

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.

Tailwind v4采用CSS优先模式：

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>

在浏览器运行时合成项目中，避免使用v3的配置模式：

css

/* 请勿在Tailwind v4浏览器运行时合成项目中使用以下代码 */
@tailwind base;
@tailwind components;
@tailwind utilities;

请勿仅为了定义颜色、字体、间距或工具类而给v4浏览器运行时合成项目添加

tailwind.config.js

。请在

text/tailwindcss

样式块中使用

@theme

和

@utility

。

如果确实需要为编译后的v4构建使用现有JavaScript配置，请通过CSS中的

@config

显式加载，然后在浏览器中验证。请勿假设v4会自动检测v3配置文件。

HyperFrames Composition Pattern

HyperFrames合成模式

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>

让Tailwind负责静态布局和视觉样式，将动画时序交由GSAP或其他可寻帧的适配器处理。

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>

对于重复元素，优先使用类列表加CSS自定义属性，而非动态生成类名：

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:

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

Tailwind的浏览器运行时会扫描当前文档，为能识别的类名生成CSS。请勿仅在寻帧时构建对渲染至关重要的类名：

// 存在风险：Tailwind可能在捕获前无法识别所有生成的类名
element.className = `bg-${color}-500`;

请在HTML、数据属性或显式CSS中使用完整类名：

html

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

如果无法避免生成类名，请确保完整的类令牌在验证前出现在

text/tailwindcss

块中。

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.

使用稳定尺寸：为视频布局使用
```
w-[...]
```
、
```
h-[...]
```
、
```
aspect-video
```
、
```
grid
```
、
```
flex
```
和固定内边距
优先使用变换和透明度作为动画属性
除非由可寻帧运行时管理状态，否则请勿将Tailwind过渡效果用于对渲染时序至关重要的内容
对于必须确定性渲染的内容，避免使用hover、focus、scroll、viewport或pointer变体
使用明确的边框颜色：Tailwind v4改变了v3的默认边框行为，因此
```
border border-white/20
```
比单纯的
```
border
```
更安全
使用v4工具类名称：在适用场景下使用
```
shadow-xs
```
、
```
rounded-xs
```
、
```
outline-hidden
```
、
```
shrink-*
```
和
```
grow-*
```
如果输出需要兼容旧浏览器，请谨慎使用现代CSS工具类，因为Tailwind v4以现代浏览器为目标

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.

编辑启用Tailwind的合成项目后：

bash

npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect

如需渲染样片：

bash

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

验证流程应确保第0帧没有样式丢失的闪烁。如果预览中有样式但渲染中没有，请检查

window.__tailwindReady

是否存在并在捕获前完成加载。

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.

确认项目是通过
```
hyperframes init --tailwind
```
搭建的
确认脚本指向
```
@tailwindcss/browser@4.2.4
```
确认
```
window.__tailwindReady
```
存在
将v3的
```
@tailwind
```
指令替换为v4浏览器运行时CSS
将自定义令牌从
```
tailwind.config.js
```
迁移到
```
@theme
```
中
将动态拼接的类名替换为完整的静态令牌
运行
```
npx hyperframes validate
```
并渲染短样片

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 CSS官方v4安装、升级和兼容性文档：https://tailwindcss.com/docs
Tailwind CSS v4发布说明：https://tailwindcss.com/blog/tailwindcss-v4
参考了社区Tailwind相关指南中的v4注意事项，但本指南保持与仓库内HyperFrames专属的持久约定一致。