tailwind

FrameVideo 向け Tailwind CSS

FrameVideo の init --tailwind は、@tailwindcss/[email protected] に固定された Tailwind のブラウザーランタイムを使用します。Tailwind v3 ではなく、Tailwind v4 として扱ってください。

このスキルは CLI が生成するコンポジション HTML 向けです。内部で引き続き Tailwind v3、tailwind.config.js、PostCSS、@tailwind ディレクティブを使用する packages/studio 向けではありません。

使用する場合

次の場合にこのスキルを使用してください。

• プロジェクトが 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 border-white/20 のほうが安全です。
• 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
• v4 の注意点とスキルの形式を確認するために、コミュニティの Tailwind スキルを参照しました。ただし、このスキルでは、長期にわたって維持できる仕様をリポジトリ内に置き、FrameVideo 固有のものにしています。