tailwind

HyperFrames 的 Tailwind CSS

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

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

适用场景

• 用户要求在 HyperFrames 合成中使用 Tailwind。
• 项目是通过 hyperframes init --tailwind 创建的。
• 你在 index.html 中看到 window.__tailwindReady。
• 你需要使用实用类、CSS 优先的主题令牌、自定义实用类或 v3 到 v4 的迁移指南。
• 渲染时缺少样式，且项目依赖浏览器运行时。

版本约定

• 固定的运行时：@tailwindcss/[email protected]。
• 浏览器运行时脚本由 CLI 注入。请勿将其替换为 cdn.tailwindcss.com。
• HyperFrames 会等待 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 配置文件。

HyperFrames 合成模式

让 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 过渡。
• 对必须确定性渲染的内容，避免使用 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 面向现代浏览器。

验证

编辑启用 Tailwind 的合成后：

npx hyperframes lint
npx hyperframes validate
npx hyperframes inspect

如需验证渲染效果：

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

验证过程应显示第 0 帧没有样式缺失闪烁。如果样式在预览中出现、但在渲染中缺失，请检查 window.__tailwindReady 是否存在，以及它是否在捕获前完成解析。

快速调试清单

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

致谢与参考资料

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