transitions-ui-generation

トランジション UI の生成

ページ上の任意の要素に「エージェントが生成中」というアニメーションを表示し、その後、実際の UI に切り替えます。偽りはありません。描画は要素そのものを計測しているため、点線の輪郭、テキストの行、アイコンが、実際に表示される位置にぴったり重なります。

スキルを読み込むすべてのエージェント（Claude Code、Cursor、Codex など）で利用できます。npx skills add Jakubantalik/transitions.dev でインストールするか、このフォルダーをプロジェクトにコピーしてください。

描画内容

1 回のビルドで順番に表示します（デフォルトでは描画に 2400ms、全体で約 2.6s）。

1. ドットフィールド。 小さなドットのグリッドが中心から波紋状に広がり、各列をマトリックス風の雨が流れ落ち、プローブラインが横切ります。
2. 構築。 ガイドが要素の端に沿って角の先まで伸び、コーナーハンドルが現れ、サイズラベルがビルドタイマーとともに実際のサイズまでカウントアップします。
3. 輪郭。 輪郭は上部中央から両方向へ、小さな流れるドットで描かれます。その間、周囲のドットが飛んできて輪郭に着地します。
4. パーツ。 すべてのボックス、テキスト行、アイコンのパスをドキュメント順に描きます。主要な要素（ボタン、入力欄、最も大きなボックス）には、それぞれガイド、ハンドル、サイズラベルが表示され、ターゲティングレティクルが座標表示とともにパーツ間を移動します。
5. 表示。 スキャンラインの後ろから実際の UI が上から下へ表示され、--ease-smooth-out に従ってフェードしながら鮮明になります。その間に描画が消され、ドットが消去されます。

オプション

モード	表示内容	用途	参照
skeleton	ドットによる描画と表示演出。	多くの場面に適しています。エージェントが生成したカードやパネル、内容が埋まっていく空の状態、印象的な見せ場など。	01-skeleton.md
skeleton-texts	同じ演出に、生成テキストを追加します。エージェントのログ（パーツごとに 1 行、進捗バー付き）、書き込まれるモーション CSS（transitions.dev のトークンスケール上での要素固有の値）、ステップ表示（「レイアウトを計画中」…「準備完了」）が含まれます。	「エージェントが作業中」というストーリーが重要なショーケースやローンチ時に適しています。ランディングページ、デモ、オンボーディング、製品動画などに使えます。要素の横または下にスペースが必要です。ページの空いている場所にだけテキストを配置します。	02-skeleton-texts.md

判断ルール

• AI 機能が UI を返す場合（生成されたコンポーネント、チャート、要約カード、下書きなど）→ skeleton を使い、結果が届いたときに再生します。
• エージェントが構築したというストーリーを伝えるランディングページ、デモ、動画 → skeleton-texts を使い、画面内にスクロールして表示されたときに再生します。
• ユーザーが「テキスト」「ログ」「コードのストリーミング」「未来的なバージョン」を求めている場合 → skeleton-texts を使います。
• 複数の要素を一度に表示する場合（結果のグリッドなど）→ 各要素に skeleton を適用し、項目ごとに約 260ms の delay を設定します。テキストは一度に 1 つの要素の周囲にしか配置できません。
• 小さなインライン UI（バッジ、単一のボタン、約 120px 未満のもの）や、頻繁に表示される UI（ルートの切り替えごと、リストの各行など）には使わないでください。代わりに transitions-dev のスケルトン表示（14-skeleton-reveal.md）またはテキスト表示を使います。生成アニメーションは一瞬の演出であり、読み込み状態ではありません。
• どちらのモードを選ぶか迷う場合 → skeleton を使います。テキストを追加する前に確認してください。

コマンド

transitions generate

起動フレーズ： transitions generate、「生成アニメーションを追加して」、「AI が生成したように見せて」、「エージェントが構築するようにアニメーション化して」。

動作：

1. 対象の要素を見つけます。ユーザーが指定したもの、開いているファイル内のコンポーネント、またはカーソルに最も近い要素を選びます。特定できない場合は、どれを指しているか確認します。
2. 判断ルールに従ってモード（デフォルトは skeleton）と、起動タイミング（マウント時、データ到着時、画面内にスクロールして表示されたとき、または要求時）を選びます。
3. たとえば、「<ResultCard> に、応答が届いたときに skeleton を再生する想定です。よろしいですか？」のように、1 行で提案します。
4. 確認を得たら、以下の ## Install と ## Wiring に従います。差分は小さく抑えてください。

transitions generate texts

mode: "skeleton-texts" を指定した transitions generate と同じです。テキストを表示するには要素の横または下に空きスペースが必要で、スペースがない場合は表示されないことを明記してください。

transitions generate preview

demo.html を開きます（このディレクトリで npx serve を実行するなどして、フォルダーを HTTP 経由で配信してください）。transitions.dev Community で公開されている 3 つのコンポーネント（Heart Rate Monitor、Chart card、Music Player Likes）を使い、サイドパネルが見える 1 カードレイアウトで、両方のモードを確認できます。各コンポーネントは独自のシャドウルートにマウントされるため、スタイルとスクリプトは公開時のまま保持されます。

インストール

1. ui-generation.js と ui-generation.css をプロジェクトにコピーします（例：src/lib/ または public/vendor/）。どちらのファイルも単独で動作し、依存関係はありません。
2. CSS をグローバルに一度だけインポートします（<link> を使うか、アプリのエントリーポイントで import "./ui-generation.css" を実行します）。
3. 要素がある場所で generate（属性 API を使う場合は auto も）をインポートします。

ランタイムやそのタイミングを書き換えないでください。描画フェーズ、ドットの間隔、動きの速度、表示カーブは一体となるよう調整されています。

接続方法

要素がレンダリングされ、最終的なサイズになり、フォントが読み込まれた後に generate を呼び出します。表示されるまで要素自体を非表示にし、その後、インラインの opacity、clip-path、filter を元に戻します。

Vanilla

import { generate } from "./ui-generation.js";
await document.fonts.ready;
const run = generate(document.querySelector("#result"), { mode: "skeleton" });
await run.finished; // the real UI is fully in

属性 API（要素がスクロールして表示範囲に入ると、それぞれ再生します）

<section data-t-generate="skeleton-texts" data-t-generate-delay="200">…</section>
<script type="module">
  import { auto } from "./ui-generation.js";
  auto();
</script>

React / Next.js（クライアントコンポーネント）

"use client";
import { useLayoutEffect, useRef } from "react";
import { generate } from "@/lib/ui-generation.js";

export function GeneratedCard({ data }) {
  const ref = useRef(null);
  useLayoutEffect(() => {
    if (!ref.current) return;
    const run = generate(ref.current, { mode: "skeleton" });
    return () => run.cancel();
  }, [data]); // replays when new data arrives
  return <div ref={ref} className="card">{/* … */}</div>;
}

Vue

import { onMounted, onBeforeUnmount, ref } from "vue";
import { generate } from "@/lib/ui-generation.js";
const el = ref(null); let run;
onMounted(() => { run = generate(el.value, { mode: "skeleton" }); });
onBeforeUnmount(() => run && run.cancel());

Svelte（アクション）

import { generate } from "$lib/ui-generation.js";
export function generating(node, mode = "skeleton") { const run = generate(node, { mode }); return { destroy: () => run.cancel() }; }
// <div use:generating={"skeleton-texts"}>…</div>

API

generate(element, options) は { finished, cancel, element } を返します。finished は実際の UI が完全に表示されると解決します。cancel() はその場で停止し、要素をそのまま表示します。同じ要素に対して再び generate を呼び出すと、前回の実行はキャンセルされます。

オプション	デフォルト	説明
mode	"skeleton"	"skeleton" または "skeleton-texts"。
duration	2400	描画時間（ミリ秒）。全体の実行時間は約 duration × 1.09 です。1600～3600 の範囲にしてください。
delay	0	開始までの時間（ミリ秒）。複数の要素を順番に開始する場合に指定します。
steps	["Planning layout", "Drawing structure", "Writing styles", "Adding motion"]	ステップ行（skeleton-texts）。
done	"Ready"	最後のステップ。UI が表示されるときに表示されます。例として、コンポーネント名を使い、"Invite modal ready" のように指定します。
code	導出	モーション CSS パネルに表示する行。デフォルトでは、要素自身の角丸、書体、色と、transitions.dev のモーショントークンを使います。
title	導出	モーション CSS ヘッダーに表示する名前（指定がない場合は aria-label または最初の見出しを使用します）。
maxParts	60	トレースするパーツの最大数。大きいパーツが優先されます。
keys	5	ガイド、ハンドル、サイズラベルを表示する主要な要素の数。
onDone	null	実行終了時に要素を引数として呼び出されます。

描画から除外する子要素には data-t-generate-skip を指定します。

調整可能な変数

ui-generation.css にあります。以下はライトモードの値です。ダークモードの値は prefers-color-scheme または [data-theme="dark"] に応じて切り替わります。

変数	デフォルト	説明
--gen-line	#9a9a9a	アウトライン、パーツ、ガイドに使う点線。
--gen-strong	#6c6c6c	移動するドットの先端、ハンドル、照準、点灯するドット、ラベル。
--gen-ink	rgba(13, 13, 13, 0.32)	静止時のドットフィールド。
--gen-surface	#ffffff	コーナーハンドルの塗りつぶし（ページの背景色に合わせます）。
--gen-text / --gen-muted	#0d0d0d / #8b8b8b	パネルの見出しとテキスト（skeleton-texts）。
--gen-dot	2.1px	トレースされた線上のドットのサイズ。
--gen-font	Roboto Mono, monospace	ラベルとパネル。

描画はモノクロにしてください。グレーのドットは「エージェントの作業レイヤー」として見え、実際の UI が表示されると色が加わります。

アクセシビリティ

• prefers-reduced-motion: reduce の場合、描画を完全にスキップします。要素は 200ms かけてフェードインし、通常どおり finished が解決されます。これを削除しないでください。
• オーバーレイは aria-hidden であり、ポインター入力を受け付けません。要素は常にアクセシビリティツリーに含まれます。
• これを使って操作を制限しないでください。finished が解決したら（約 2.6 秒後）、要素を使用できます。ユーザーが繰り返し待つことになるものには、代わりにスケルトンローダーを使用してください。

よくある間違い

• レイアウトが安定する前に実行する。 フォントや画像の読み込み前に計測すると、テキスト行やボックスが誤った位置に描画されます。先に document.fonts.ready（およびレイアウトサイズに影響する画像）を待機してください。
• display: none の要素で実行する。 非表示の要素にはサイズがありません。先に表示してください。タブやアコーディオンでは、パネルを開いてから生成してください。
• 要素を同時に独自にアニメーションさせる。 要素に独自の開始時トランジションを追加しないでください。実行中の opacity、clip-path、filter はランタイムが制御します。
• 実行中にスクロールする、overflow: hidden が設定された親要素。 オーバーレイはスクロール領域の内部ではなく、ページ上に配置されます。2.6 秒の間に要素がスクロールすると、描画がずれてしまいます。要素が表示範囲内にあるときに再生してください（属性 API ではそのように動作します）。
• ローディング状態として使用する。 実際の UI 上で一度だけ再生されます。データの読み込み中はスケルトンを表示し、データが届いてから生成を再生してください。
• テキストを無理に狭いレイアウトに押し込む。 skeleton-texts は、ページ上に空きがある場合にのみパネルを描画します。要素が密集したグリッドでは、ステップ線にフォールバックするか、何も描画しません。これは正しい動作です。そのような場所では skeleton を使用してください。
• サーバー上でインポートする。 window と DOM が必要です。Next.js や Nuxt では、クライアントコンポーネント内またはエフェクト内でインポートしてください。

リファレンスファイル

• 01-skeleton.md：スケルトンモードをフェーズごとに説明します。
• 02-skeleton-texts.md：生成テキストとその配置場所を説明します。
• ui-generation.js：ランタイム（ES モジュール。window.UIGeneration としても利用できます）。
• ui-generation.css：オーバーレイのスタイルと変数です。
• demo.html：Community の 3 つのコンポーネントで両方のモードを表示します。