tailwind

FrameVideo 的 Tailwind CSS

FrameVideo 的 init --tailwind 使用固定为 @tailwindcss/[email protected] 的 Tailwind 浏览器运行时。请将其视为 Tailwind v4，而非 v3。

此技能适用于 CLI 生成的合成 HTML。不适用于 packages/studio，它内部仍使用 Tailwind v3、tailwind.config.js、PostCSS 和 @tailwind 指令。

适用场景

在以下情况下使用此技能：

• 项目使用 Tailwind — 使用 framevideo init --tailwind 创建
• 编写实用类 — 使用 Tailwind 类为合成 HTML 设置样式
• 自定义主题令牌 — 使用 @theme 定义颜色、字体、间距
• 从 v3 迁移到 v4 — 将旧语法转换为以 CSS 为先的 v4 语法
• 运行时调试 — 样式缺失或出现 window.__tailwindReady 问题

不适用场景

以下情况请勿使用此技能：

• 非 Tailwind 项目 — 如果项目未使用 Tailwind，请编写原生 CSS
• Studio UI 开发 — Studio 使用带有 PostCSS 的 v3（设置方式不同）
• 后端/CLI 代码 — 此技能仅适用于合成 HTML
• 优先使用 CSS 编译的场景 — 将 Tailwind 编译为 CSS，以提高生产环境稳定性

---

快速入门

创建启用 Tailwind 的项目：

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

在合成 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>

添加自定义主题：

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


<h1 class="text-brand font-display">Brand Title</h1>

---

版本约定

• 固定的运行时：@tailwindcss/[email protected]。
• 浏览器运行时脚本由 CLI 注入。请勿将其替换为 cdn.tailwindcss.com。
• FrameVideo 会在开始捕获帧之前等待 window.__tailwindReady。
• 就绪状态垫片必须保持确定性：不得使用渲染循环轮询 API、基于时钟的重试机制，也不得发起固定 Tailwind 运行时脚本之外的运行时网络请求。
• 对于离线、受限或要求生产环境稳定性的渲染，请将 Tailwind 编译为 CSS，并直接引入样式表，而不是依赖浏览器运行时。

v4 规则

Tailwind v4 以 CSS 为先：

<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 设置模式：

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

对于 v4 浏览器运行时合成，不要仅为定义颜色、字体、间距或实用类而添加 tailwind.config.js。请在 text/tailwindcss 样式块中使用 @theme 和 @utility。

如果确实需要在已编译的 v4 构建中使用现有 JavaScript 配置，请在 CSS 中通过 @config 显式加载，然后在浏览器中验证。不要假定 v4 会自动检测 v3 配置文件。

FrameVideo 合成模式

让 Tailwind 负责静态布局和视觉样式。让 GSAP 或其他可定位的适配器负责运动时序。

<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 自定义属性，而不是动态生成类名：

<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 浏览器运行时会扫描当前文档，并为其能识别的类名生成 CSS。不要只在定位时构建渲染关键类名：

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

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

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

如果无法避免生成类，请确保完整类令牌在验证前出现在 text/tailwindcss 块中。

视频专用注意事项

• 使用稳定尺寸：视频布局采用 w-[...]、h-[...]、aspect-video、grid、flex 和固定内边距。
• 动画属性优先使用变换和不透明度。
• 除非可定位的运行时负责管理状态，否则不要让 Tailwind 过渡影响渲染关键时序。
• 对必须确定性渲染的内容，避免使用悬停、焦点、滚动、视口或指针变体。
• 使用显式边框颜色。Tailwind v4 更改了 v3 中的默认边框行为，因此 border border-white/20 比单独使用 border 更安全。
• 使用 v4 实用类名称：适用时使用 shadow-xs、rounded-xs、outline-hidden、shrink-* 和 grow-*。
• 如果输出需要支持较旧的浏览器，请谨慎使用现代 CSS 实用类。Tailwind v4 面向现代浏览器。

验证

编辑启用了 Tailwind 的合成后：

npx framevideo lint
npx framevideo validate
npx framevideo inspect

验证渲染效果：

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

验证路径应确保第 0 帧不会闪现缺失样式。如果预览中样式正常显示，但渲染结果中没有，请检查 window.__tailwindReady 是否存在，并且是否在捕获前完成解析。

快速调试清单

1. 确认项目是通过 framevideo init --tailwind 搭建的。
2. 确认脚本指向 @tailwindcss/[email protected]。
3. 确认 window.__tailwindReady 存在。
4. 将 v3 的 @tailwind 指令替换为 v4 浏览器运行时 CSS。
5. 将自定义令牌从 tailwind.config.js 移至 @theme。
6. 将动态拼接的类替换为完整的静态令牌。
7. 运行 npx framevideo validate 并渲染一段简短的验证片段。

致谢与参考资料

• Tailwind CSS 官方 v4 安装、升级和兼容性文档：https://tailwindcss.com/docs
• Tailwind CSS v4 发布说明：https://tailwindcss.com/blog/tailwindcss-v4
• 我们参考了社区的 Tailwind 技能，了解 v4 的注意事项和技能结构；不过，本技能将持久适用的约定保留在仓库中，并专门针对 FrameVideo。