tailwind

用途

该技能用于在 HyperFrames 作品（composition）中处理 Tailwind CSS，尤其是由 hyperframes init --tailwind 脚手架创建、依赖 Tailwind 浏览器运行时的项目。它覆盖脚手架搭建或编辑此类项目时的 Tailwind 使用方式。

适用信号包括：用户要求在 HyperFrames 作品中使用 Tailwind；项目由 hyperframes init --tailwind 创建；在 index.html 中看到 window.__tailwindReady；需要工具类、CSS-first 主题令牌、自定义工具类，或 v3 到 v4 的迁移指导；渲染缺少样式且项目依赖浏览器运行时。

该技能仅针对 CLI 生成的 composition HTML，不适用于 packages/studio——后者内部仍使用 Tailwind v3，配合 tailwind.config.js、PostCSS 和 @tailwind 指令。

版本契约

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

v4 规则

Tailwind v4 是 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>

在浏览器运行时作品中避免 v3 设置模式：

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

不要仅为定义颜色、字体、间距或工具类而添加 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。不要仅在 seek 时构建渲染关键类名：

// 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 及固定内边距。
动画属性优先使用 transform 与 opacity。
除非由可寻址运行时管理状态，否则不要让 Tailwind 过渡参与渲染关键计时。
对需要确定性渲染的内容避免 hover、focus、scroll、viewport 或指针变体。
显式指定边框颜色。Tailwind v4 改变了默认边框行为，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 是否存在并在捕获前完成。

快速调试清单：确认项目由 hyperframes init --tailwind 创建；确认脚本指向 @tailwindcss/browser@4.2.4；确认存在 window.__tailwindReady；将 v3 的 @tailwind 指令替换为 v4 浏览器运行时 CSS；将自定义令牌从 tailwind.config.js 移至 @theme；用完整静态令牌替换动态拼接类；运行 npx hyperframes validate 并渲染短验证。

参考

Tailwind CSS 官方 v4 安装、升级与兼容文档：https://tailwindcss.com/docs；Tailwind CSS v4 发布说明：https://tailwindcss.com/blog/tailwindcss-v4。

限制

资料未提供该技能的收费、价格、平台支持范围或具体效果数据；未提及 HyperFrames 的具体版本要求或除上述命令外的安装方式。