プリアンブル(最初に実行)
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRY: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"page-load-animations","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"page-load-animations","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi
TEL_PROMPTED が no の場合:スキルワークフローを開始する前に、テレメトリについてユーザーに確認してください。
AskUserQuestion を使用します:
superstack の改善にご協力ください!どのスキルがどのくらいの時間使われているかを追跡しています — コード、ファイルパス、個人情報は収集しません。
~/.superstack/config.jsonでいつでも変更できます。
オプション:
- A) はい、superstack の改善に協力します(匿名)
- B) いいえ
A の場合:次の bash を実行します:
echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted
B の場合:次の bash を実行します:
echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted
これは一度だけ発生します。TEL_PROMPTED が yes の場合、これを完全にスキップしてスキルワークフローに進みます。
スキルが違いますか? 利用可能なすべてのスキルについては SKILL_ROUTER.md を参照してください。
ページ読み込みアニメーション
バトルテスト済みの framer-motion レシピから適応したパターン。元のインスピレーション:suzi-ux-motions。
ページ読み込みを混沌ではなく意図的に見せるための、本番対応の framer-motion レシピ集。このスキルが存在する理由は、暗号 UI における最も一般的なアニメーションの問題がアニメーションの欠如ではなく、コレオグラフィ、スタッガー、スプリング物理がない状態ですべてが一度に表示されることだからです。コードが正しくても、結果として壊れているように感じられます。
このスキルは実装レシピを提供します。アニメーション理論(いつアニメーションするか、期間ティア、イージングカーブ、動作軽減)については、frontend-design-guidelines/references/animation.md を参照してください。このスキルは、これらすべてのベースライン制約を継承します。
権限モデル
animation.md= ベースライン制約(期間ティア、イージング、動作軽減、GPU プロパティ)- このスキル = それらの制約内で実装する本番レシピ
frontend-design-guidelinesは、framer-motion パターンに関してはこのスキルに委譲し、その逆はありません
セットアップ
npm install framer-motion
シンプルな状態変更には、CSS トランジションがデフォルトです(animation.md に従う)。スプリング物理、オーケストレーションされたシーケンス、AnimatePresence 終了アニメーション、ジェスチャー/ドラッグ、共有レイアウトトランジションが必要な場合は、framer-motion を使用します。
このスキルを適用するタイミング
以下の場合にこれらのレシピを適用します:
- 複数のセクションを読み込むページを構築している(ダッシュボード、詳細画面、ランディングページ)
- マウント時にリスト、カードグリッド、テーブルをスタッガーする
- モーダル、ドロップダウン、ポップオーバーをアニメーションする
- コンテンツが変更され高さが変わるタブやフィルターを切り替える
- リアルタイム更新される数字、チャート、ドーナツグラフを表示する
- ホバーフィードバック、シェブロン回転、ツールチップの出現を追加する
- 既存の framer-motion コードをアンチパターンについてレビューする
- ユーザーが「ページがカクカクする」または「すべてが一度に表示される」と言った場合
ページレベルのコンポーネントを構築していて、このスキルがトリガーされていない場合は、自分でトリガーしてください。
ワークフロー
アニメーションコードを書く前に、該当するリファレンスファイルを特定して読みます:
- ページ読み込みのエントランスをオーケストレーションする → references/page-choreography.md
- リストやカードグリッドをスタッガーする → references/list-stagger.md
- モーダル、ドロップダウン、ポップオーバーをアニメーションする → references/popups-modals.md
- 高さが変わるタブ/フィルターを切り替える → references/filter-transitions.md
- 数字のローリング、チャート変形、ドーナツ表示 → references/live-data.md
- ボタンフィードバック、シェブロン回転、ツールチップ → references/hover-micro.md
- スプリングプリセットやイージングカーブを調べる → references/spring-presets.md
必要なものだけを読み込みます。すべてのリファレンスを一度に読む必要はありません。
モード 1: 新しいアニメーションの構築
- 必要なパターンに対応するリファレンスファイルを読みます。
- ASCII ストーリーボードコメントから始めます — コードを書く前に完全なシーケンスを計画します。
- すべての遅延に対して名前付き定数を持つ TIMING オブジェクトを定義します。
- リファレンスのパターンを使用して実装します。デフォルトでスプリング物理を使用します。
- 完了を報告する前に、以下の非妥協ルールに対して確認します。
モード 2: 既存のアニメーションコードのレビュー
- 一般的なアンチパターンをスキャンします:
# 親と子の両方に layout プロパティ(ジッターの原因) grep -rn "layout" --include="*.tsx" --include="*.jsx" | head -20 # AnimatePresence での staggerChildren(信頼性が低い) grep -rn "staggerChildren" --include="*.tsx" --include="*.jsx" | head -10 # transition-all(意図しないプロパティをアニメーション) grep -rn "transition-all\|transition: all" --include="*.tsx" --include="*.css" | head -10 # 動作軽減処理の欠如 grep -rn "motion\.\|animate=" --include="*.tsx" -l | while read f; do grep -L "reduced-motion\|useReducedMotion\|motion-safe" "$f"; done | head -10 - 見つかった問題ごとに、該当するリファレンスファイルから特定のアンチパターンルールを参照します。
- 正確なコードパッチを提供します。
モード 3: クイックルックアップ
ユーザーが「X のスプリング設定は?」や「Y をアニメーションするには?」と尋ねた場合、完全なワークフローを実行せずに、リファレンスファイルとスプリングプリセットから直接回答します。
非妥協ルール
- ASCII ストーリーボードコメント。 すべてのアニメーションページは、完全なシーケンスを一目で示すタイムラインコメントで始まります。時間はマウントからの絶対時間で、右揃え。
- 名前付きタイミング定数。 すべての遅延はファイルの先頭にある TIMING オブジェクトに入れます。
setTimeoutやdelayプロパティにマジックナンバーは使用しません。 - スプリング優先。 自然で割り込み可能なモーションには、duration ベースのイージングよりもスプリング物理を優先します。フェードとツールチップにのみ duration を使用します。
- ステージ駆動のシーケンス。 単一の整数状態が複数セクションのシーケンスを駆動します。散在するブール値フラグは使用しません。
stage >= Nパターン。 セクションは一度表示されると表示されたままになります。stage === Nは使用しません。- 親と子の両方に
layoutを決して使用しない。 これはフィルターアニメーションにおけるジッターの最大の原因です。代わりにResizeObserverを使用したAnimatedHeightを使用します。 AnimatePresenceでstaggerChildrenを決して使用しない。 信頼性が低いです。代わりに手動のdelay: i * staggerを使用します。prefers-reduced-motionを尊重する。animation.mdから継承。すべてのアニメーションは適切に動作を軽減できなければなりません。- マウントと更新の区別。 マウントアニメーションは劇的(600ms、表現的なイージング)です。更新アニメーションは控えめ(150ms、スムーズなイージング)です。異なるフェーズ、異なる設定。
設計原則
- ストーリーボードファースト — コードを書く前にシーケンスを計画する
- スプリングファースト — duration ベースのイージングよりもスプリング物理を優先
- 名前付き定数 — すべてのタイミング値は宣言され、インラインではない
- ステージ駆動 — 単一の整数状態が複雑なシーケンスをオーケストレーション
- データ駆動 — 繰り返し要素はコピーペーストされたブロックではなく、インデックスベースの遅延を持つ
.map()を使用 - 推測ではなく測定 — 動的な高さには
ResizeObserverを使用し、ハードコードされたピクセル高さは使わない
他のスキルとの統合
frontend-design-guidelines— 一般的な UI スキル。framer-motion の作業をこのスキルに委譲します。両方が発動した場合、animation.mdのベースラインルールが制約に関して権威を持ち、このスキルが実装レシピに関して権威を持ちます。number-formatting— リアルタイム更新される数字表示には、書式指定にnumber-formattingを、数字ローリングアニメーションパターンにこのスキルを使用します。brand-design— ブランドカラーはアニメーションの色の選択(ポジティブ/ネガティブインジケーター、アクセントハイライト)に影響を与える可能性があります。
リソース
references/
- references/page-choreography.md — ASCII ストーリーボード、TIMING オブジェクト、セクション設定、スプリングプリセット、
stage >= Nパターンを使用したステージ駆動のページエントランス - references/list-stagger.md — インデックスベースのスタッガー遅延、StaggerItem ラッパー、タイミング/オフセットガイドライン、アンチパターン
- references/popups-modals.md — 3層モーダルアニメーション(背景、パネル、コンテンツスタッガー)、ドロップダウンパターン、閉じる動作
- references/filter-transitions.md — ResizeObserver を使用した AnimatedHeight、キー付きラッパーを使用したクロスフェード、重要な
layoutアンチパターン - references/live-data.md — 数字のローリング(スロットマシン)、SVG ドーナツ表示、チャート変形、マウント vs 更新フェーズ管理
- references/hover-micro.md — CSS vs framer-motion 判断マトリックス、ボタンフィードバック、シェブロン回転、ツールチップ出現、コピーフィードバック
- references/spring-presets.md — すべてのプリセットを表 + JSON で:スプリング設定、イージングカーブ、スタッガー値、期間プリセット
スキル間リファレンス
frontend-design-guidelines/references/animation.md— このスキルが継承するベースライン制約(期間ティア、イージング、動作軽減、GPU プロパティ)number-formatting— 数字表示ルール用(書式指定、アニメーションではない)
クイックスタート
# トリガー例:
# 「ページ読み込みを修正して — すべてが一度に表示される」
# 「このダッシュボードにエントランスアニメーションを追加して」
# 「モーダルアニメーションがカクカクする」
# 「これらのカードをスタッガーするには?」
# 「ドロップダウンにはどのスプリング設定を使うべき?」
# 「残高表示に数字ローリングアニメーションを追加して」
# ページレベルのコンポーネントを構築するときに自動的に発動
テレメトリ(最後に実行)
スキルワークフローが完了した後(成功、エラー、中断のいずれか)、テレメトリイベントを記録します。
ワークフローの結果から結果を判定します:通常完了時は success、失敗時は error、ユーザーが中断した場合は abort。
次の bash を実行します:
_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - ${_TEL_START:-$_TEL_END} ))
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
if [ "$_TEL_TIER" != "off" ]; then
echo '{"skill":"page-load-animations","phase":"build","event":"completed","outcome":"OUTCOME","duration_s":"'"$_TEL_DUR"'","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","platform":"'$(uname -s)-$(uname -m)'"}' >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
true
fi
OUTCOME をワークフローの結果に基づいて success/error/abort に置き換えます。