HyperFramesレジストリへのコントリビュート
新しいレジストリブロックまたはコンポーネントについて、アイデアからマージされたPRまでユーザーを導きます。
ワークフロー
1. 明確化 → 2. スキャフォールディング → 3. ビルド → 4. バリデーション → 5. プレビュー → 6. 出荷
ステップ 1: 明確化
何を作成するのか尋ねます。レジストリには2種類のアイテムがあります。
- ブロック(
registry/blocks/、タイプhyperframes:block) — 固定の寸法と再生時間を持つ完全な独立した合成。キャプションスタイル、VFXエフェクト、タイトルカード、ローワーサード。 - コンポーネント(
registry/components/、タイプhyperframes:component) — 固定の寸法や再生時間がない再利用可能なスニペット。CSSエフェクト、テキスト処理、任意の合成サイズに適応するオーバーレイ。
次に以下を尋ねます。
- エフェクトの一文による説明
- ビジュアルリファレンス(URL、スクリーンショット、または説明)
- 誰がいつ使うのか?
ステップ 2: スキャフォールディング
レジストリ構造を作成します。
ブロックの場合:
registry/blocks/{block-name}/
{block-name}.html
registry-item.json
コンポーネントの場合:
registry/components/{component-name}/
{component-name}.html
registry-item.json
命名規則:
| アイテム名 | IDプレフィックス | IDの例 |
|---|---|---|
cap-hormozi | hz | hz-cg-0, hz-cw-3 |
cap-typewriter | tw | tw-cg-0, tw-ch-0-5 |
vfx-chrome | vc | vc-canvas |
2~3文字のプレフィックスを使用します。サブコンポジション内での衝突を避けるため、すべての要素IDにこのプレフィックスを使用する必要があります。
ブロック用のregistry-item.json:
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{block-name}",
"type": "hyperframes:block",
"title": "{人間が読めるタイトル}",
"description": "{一文の説明}",
"dimensions": { "width": 1920, "height": 1080 }, // 縦長/ソーシャル用は1080x1920に調整
"duration": 10, // コンポジションに合わせて調整
"tags": ["{カテゴリ}", "{サブカテゴリ}"],
"files": [
{
"path": "{block-name}.html",
"target": "compositions/{block-name}.html",
"type": "hyperframes:composition"
}
]
}
コンポーネント用のregistry-item.json(dimensionsやdurationはなし):
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{component-name}",
"type": "hyperframes:component",
"title": "{人間が読めるタイトル}",
"description": "{一文の説明}",
"tags": ["{カテゴリ}"],
"files": [
{
"path": "{component-name}.html",
"target": "compositions/components/{component-name}.html",
"type": "hyperframes:snippet"
}
]
}
ステップ 3: ビルド
タイプに応じて正しいテンプレートを適用します。コピーペースト用のスターターについてはtemplates.mdを参照してください。
キャプションブロック
絶対に守るべきキャプションのルール:
- フォント: プロポーショナルフォントは最小96px。等幅フォントは64~72pxで許容(文字幅が広いためサイズは小さくて済む)。
- 可読性:
-webkit-text-stroke: 2-3pxまたは多層text-shadow - オーバーフロー: すべてのグループで
window.__hyperframes.fitTextFontSize()を呼び出す - カラオケ:
tl.to(wordEl, { color/scale }, WORDS[wi].start)でアクティブな単語をハイライト - ハードキル: すべてのグループに対して
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end) tl.from(el, { opacity: 0 })をtl.set(el, { opacity: 1 })と同じ位置で使用しないこと — fromはsetを上書きします。代わりにtl.toを使用してください。
文字ごとのアニメーション(タイプライター、スクランブル):
- 各文字をID
{prefix}-ch-{group}-{char}の<span>でラップ - 単語のタイムスタンプから計算した間隔で
tl.setを使ってスタッガー - カーソル/装飾要素: 間隔を空けて
tl.setを使用 — CSSアニメーションは使用しない(シーク不可のため)
位置バリエーション:
- 中央揃え:
display: flex; align-items: center; justify-content: center; - ローワーサード:
position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center; - 左揃え:
position: absolute; bottom: 100px; left: 120px; text-align: left;
VFXブロック(Three.js)
- CDNから
[email protected]を使用(グローバルスクリプト) tl.eventCallback("onUpdate", renderScene); renderScene();—requestAnimationFrameは使用しない- ステートプロキシパターン: GSAPはプレーンなJavaScriptオブジェクトをアニメーションし、レンダリング関数がそれを読み取る
- シード付きPRNG(
mulberry32)でランダム性を確保
すべてのタイプ共通
data-composition-idはwindow.__timelines["id"]と一致させる必要がある- すべての要素IDはブロック略語をプレフィックスとする
gsap.timeline({ paused: true })— 常に一時停止状態Math.random()、Date.now()は使用しない
ステップ 4: バリデーション
hyperframes lint # エラー0必須
hyperframes validate --no-contrast # コンソールエラー0必須
ステップ 5: プレビュー
# プレビュー動画をレンダリング
hyperframes render -o preview.mp4
# ビジュアルQA用のスナップショット
hyperframes snapshot --at "1.0,3.0,5.0,7.0"
# レビュー用に hyperframes.dev に公開
npx hyperframes publish
カタログプレビュー画像 — カタログカードは docs/images/catalog/{kind}/{name}.png のPNG画像を使用します({kind} は blocks または components)。スナップショットから生成してください。その後:
- HeyGen社内コントリビューター:
scripts/upload-docs-images.shを実行(AWSプロファイルengineering-767398024897が必要) - 外部コントリビューター: プレビューMP4をPRの説明に添付してください。メンテナーがマージ前にカタログ画像を生成してアップロードします。
ステップ 6: 出荷
すべてのステップが必須です。1つでも欠けると、カタログエントリが壊れます。
{kind} はステップ1で作成したものに応じて blocks または components です。
# 1. ブランチを作成
git checkout -b feat/registry-{name}
# 2. HTMLをフォーマット
npx oxfmt registry/{kind}/{name}/*.html
# 3. registry/registry.json を更新 — "items"配列にエントリを追加:
# { "name": "{name}", "type": "hyperframes:block" } (または "hyperframes:component")
# 4. カタログドキュメントページを生成
npx tsx scripts/generate-catalog-pages.ts
# 5. レビューアーがプレビューできるように hyperframes.dev に公開
npx hyperframes publish
# 6. すべてをステージング
git add registry/{kind}/{name}/ registry/registry.json docs/catalog/
# 7. コミット
git commit -m "feat(registry): add {name} — {一文の説明}"
# 8. プッシュし、hyperframes.dev リンクを付けてPRを開く
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"
GitHubアカウントをお持ちでない場合: PRを開くにはアカウントが必要です。https://github.com/signup でサインアップし、gh auth login を実行してください。
品質ゲート
-
hyperframes lint→ エラー0 -
hyperframes validate→ コンソールエラー0 -
npx oxfmt --checkがパスする -
registry/registry.jsonが新しいエントリで更新されている -
scripts/generate-catalog-pages.tsが実行されている(ドキュメントページが生成されている) -
npx hyperframes publishが実行されている(プロジェクトURLを主張する) - プレビューMP4がPRに添付されている(外部)またはカタログPNGがアップロードされている(内部)
- すべてのIDが一意であり、プレフィックスが付いている