scrollcraft

scrollcraft

スクロールは、訪問者がすでに使い方を知っている唯一の入力方法です。このスキルでは、スクロールをタイムラインとして扱います。ホイールはスクラバー、ページは実際のテキストが重なる映像となり、各セクションはそれぞれ十分に異なる動きをするため、訪問者は次に何が起こるのか確かめるために先へ進みます。

生成するもの： インタビューブリーフ、ページ文法、カスタマージャーニーマップ、意図的に設計したピークを1つ含む感情曲線、スクロールスコア、特徴的な動き1つ、生成アセット、トークン駆動のデザイン基盤上に構築した実際のHTMLページ、そしてあらゆるスクロール位置で適切に表示されることを証明するスクリーンショット一式。

これは何ではないか

「フライスルーを生成して、そこにテキストを載せる」ものではありません。この手法では、ページ全体に1つの仕掛けを適用することになり、そのように作られたサイトはどれも一目で見分けがつきます。同じクレイアニメ風のジオラマ、同じ中央揃えのコピー、同じ 01 / 06 カウンター、同じ「スクロールして探索」案内です。同じように振る舞う5つのセクションは、同じセクションを5回表示しているだけです。

このことから導かれる4つのルールが、このスキルの根幹です。

1. 多様性こそが価値です。 ページでは少なくとも4種類の仕掛けを使い、同じ仕掛けを連続して使ってはいけません。references/devices.mdをお読みください。
2. ブランドが本当にイラスト調でない限り、世界観は写真表現にします。 柔らかなマット仕上げのローポリクレイジオラマをデフォルトで使うことは禁止です。references/worlds.mdをお読みください。
3. 途切れのない連鎖は避けます。 1本の途切れないカメラ移動は、制作コストが最も高く、最も壊れやすい手法であり、シーン間のカットを隠すためだけに存在します。代わりに仕掛けに変化をつければ、訪問者は1本の映像を見ているわけではないため、カットは何もしなくても見えなくなります。連鎖させるのは、ブリーフが文字どおり「途切れのない1つの旅」である場合に限ります。
4. 世界観が違っても、ページが違うとは限りません。 仕掛けの組み合わせによってページの見た目は変わります。構造はそれとは別の軸であり、意識的に決めなければ、どの制作物も同じ骨組みを引き継いでしまいます。最初の4つの制作物は、まさにそうなっていました。references/uniqueness.mdをお読みください。

ステップ 0：インタビュー

何かを生成する前に、必ず人にインタビューしてください。 ブランド名から推測した簡単な概要でも、承認を得るために提示する計画でもありません。実際に質問し、回答をもらい、書き留めます。思い込みから作ったページは、思い込みから作られた前のページと同じような仕上がりになります。

このスキルは、ひとつのハウススタイルではなく、幅広い表現に対応するためのものです。人が意図や手持ちの素材を持ち寄り、インタビューを通じて、それが適切な種類のページへと形になります。ひと続きの世界、個別のシーン、印刷物のような章立て、動きのある画面。どの表現にも対応できます。どれを選ぶかは、インタビューで決めます。

短く済ませましょう。一度に尋ねる質問は8つです。

1. 3〜5語で表す雰囲気と、媒体を問わず最大3つの参考例。 映画、アルバムジャケット、ショップ、雑誌、ゲームなどです。「好きなサイト」ではありません。サイトを挙げると、既存のサイトに似たページになってしまいます。
2. スクロールの流れを、セクションごとに本人の言葉で。 訪問者に最初に見せたいもの、次に見せたいもの、最後に見せたいものは何でしょうか。あなたが提示したメニューではなく、本人が考える順序を聞きます。
3. エネルギーの変化。 どこで落ち着いた印象にし、どこで強い印象にするべきでしょうか。最初から最後までずっと騒がしいページも、ずっと静かなページと同じように平坦です。
4. スクロールの各段階で、どんな気持ちになってほしいですか。そして、覚えていてほしい瞬間はどれですか？ エネルギーは強さです。こちらは感情であり、両者は一致するとは限りません。騒がしいページでは、静かな演出が最も強く心に残ることもあります。各段階の回答が感情の変化を形づくり、ひとつの瞬間がピークになります。どちらも BRIEF.md に記載する必要があります。references/feel.md を参照してください。
5. これまでに見たどのサイトにもない、このサイトならではの要素をひとつ。 これがシグネチャームーブの種になります。納得できる回答を引き出してください。「印象に残ること」は答えになりません。
6. プレミアムミニマルからどのくらい離れたいか。 uniqueness.md §5 にある選択肢を提示します。ブルータリスト、マキシマリスト、遊び心のある表現、レトロ、情報密度の高い表現、エディトリアル、プレミアムミニマルです。回答は美的な方向性を決めるものであり、あなたの好みで決めるものではありません。
7. ひと続きの世界か、個別のシーンか？ ページ全体を、スクロールしながら通り抜けるひとつの連続した場所のように感じさせますか（ワールドフライト、references/worldflight.md を参照）、それとも別々のシーン、章、カットのように感じさせますか？ これは構造を決める最も大きな分岐であり、後からあなたが選ぶ演出手法ではなく、本人が決めることです。どちらもわかりやすく提示してください。どちらも標準ではありません。
8. すでに持っている素材は何ですか？ 映像、写真、商品写真、ブランドキット、本人が映ったクリップなどです。実際の素材は世界観の土台となり、生成コストを抑えます。回答によって、何を評価してエンコードし、何を生成するかが決まります。「何もありません」でも問題ありません。その場合は、世界全体を生成します。

演出計画を立てる前に、回答を本人の言葉のまま <workspace>/builds/<name>/BRIEF.md に書き留めてください。マーケティング向けの文章に言い換えないでください。以降の工程はすべて、このファイルを参照します。

BRIEF.md には、最低限、次の内容を記載する必要があります。

• 8つの質問への回答。逐語のまま記載します。
• 感情の変化。 各幕につき1行で、感情と、それを画面上で引き起こすものを記載します。幕ができる前に書き、スコアが固まるにつれて内容を追加します。
• ピーク。 訪問者が友人に話すとしたら、という文でその瞬間を記載し、どの幕にあるかを示します。
• 完成した「人に話したくなる」文。 「___な体験ができるサイトです」の空欄を、演出手法の名前ではなく体験で埋めます。
• 意図的に設けた沈黙。検証工程で、意味のないスクロールと区別できるように記載します。

4項目すべての仕様は references/feel.md にあります。

本人にどうしても連絡が取れず、実行を完全に自動化する場合は、自分で BRIEF.md を作成します。ブランドの語り口で8つの質問すべてに回答し、ファイルの先頭に Self-authored, not interviewed と記載して、最終レポートにもその旨を明記してください。自分で作成した概要は、あくまで代替策であり、基本方針ではありません。

ブートストラップ

作業のステージではなく、環境を整える段階です。ヒアリングへの回答を得たあと、Step 1 の前に一度だけ実施します。

手作業で確認するのではなく、事前チェックを実行してください。 あとで誤解を招くエラーとして表面化する失敗パターンを把握しています。主な例は、フィルターが見つからないという問題をコマンドの構文エラーとして報告する、機能が削られた ffmpeg です。

node <skill>/scripts/doctor.mjs

node、完全な ffmpeg ビルド、playwright と Chrome、API キー、解決済みのワークスペースを報告します。必須項目に問題がある場合は、ゼロ以外の終了コードで終了します。足りない項目は、黙って回避策を講じるのではなく、何が不足しているかを明確に伝えてください。

ワークスペース

ビルドとフィンガープリントレジストリは同じディレクトリに置きます。そのディレクトリは必ず解決し、決めつけてはいけません。

node <skill>/scripts/workspace.mjs --ensure     # prints it, creates it, seeds the registry

解決順序は次のとおりです。最初に見つかったものが使われます。

1. SCROLLCRAFT_HOME
2. cwd から上に向かって探した、最も近い .scrollcraft.json。{ "workspace": "..." } の形式です。
3. .git を含む最も近い祖先ディレクトリである、<project root>/scrollcraft

したがって、ビルドフォルダーは <workspace>/builds/<name>/、レジストリは <workspace>/FINGERPRINTS.md です。レジストリは空の状態で始まります。重複を防ぐための仕組みなので、最初のビルドで消すものはありません。

すでに別の場所にビルドを保存している場合は、プロジェクトルートに保存先を指定した .scrollcraft.json を置くだけで、ほかに変更はありません。

その他

1. KIE_AI_API_KEY は、アセットを生成する場合にのみ必要です。ユーザー自身の写真や映像を使ったビルドなら、キーも費用も必要ありません。これは代替策ではなく、正規の選択肢です。node <skill>/scripts/kie.mjs probe で残高を確認してください。静止画は数セント、5秒のクリップはそれ以上かかります。クリップを2本使った6幕構成のページなら、費用は大きくなく、少額です。
2. 既存のブランドキットがあれば用意してください（色、ロゴ、書体、既存の商品写真など）。このリポジトリにブランド用フォルダーがある場合は、何かを生成する前に読み、その厳格なルールに従ってください。ブランドが架空の数値を禁止しているなら、見栄えがどれほどよくても、統計カウンターは使いません。

engine/scrollcraft.js と engine/scrollcraft.css をビルドフォルダーにコピーします。エンジンは仕組みそのものなので、プロジェクトごとに編集してはいけません。トークンでテーマを設定し、マークアップは自分で作成してください。

Step 1: ブリーフ、まずはジャーニーから

テーマはユーザーに決めてもらいます。業界の選択肢をでっち上げたリストにせず、平易な文章で自由回答式に尋ねてください。作り物のメニューは相手の選択を偏らせ、相手のビジネスをこちらが決めているように受け取られます。

Step 0 では、雰囲気、順序、エネルギー、範囲についてすでに確認しています。これらを再度尋ねないでください。無理なく既定値を設定できないことだけを尋ねます。

1. これは何で、誰に向けたものですか？ 本人の言葉で1、2文にまとめてもらいます。
2. 最後に、訪問者に何を信じてもらう必要がありますか？ このページが伝えるべき、ただ一つのメッセージです。機能の一覧ではありません。3つ挙げられたら、1つを選んでもらいます。
3. 訪問者に次に何をしてもらいますか？ アクションは1つだけです。そのラベルを決め、ページ全体で統一して使います。
4. すでに何を持っていますか？ ロゴ、配色、写真、商品写真、映像、ブランド資料などです。実物のアセットは、どんなときも生成したものに勝ります。
5. アートディレクション：references/worlds.md にある世界観を、実際に選べる選択肢として提示し、独自の方向性を選んでもよいと伝えます。

そして、ほかの何よりも先にジャーニーを書きます。訪問者の知識や感情が変化する、4〜7つのビートで構成します。

1  Recognition   they see their own morning
2  Tension       the cost of it, named plainly
3  Turn          the thing that changes
4  Substance     why it holds up
5  Range         what they can choose
6  Commitment    the one action

ビートが背骨です。各セクションはビートに沿って作ります。どれほどよいショットでも、ビートに沿わないセクションは削除します。ジャーニーは、アセットを1つでも生成する前にユーザーに見せて、内容を固めてください。アセットには費用がかかり、ジャーニーによって必要なアセットがすべて決まるからです。

ステップ 2: 文法、ゲート、そしてスコア

順番に 3 つのこと、そして最初の 2 つはどのアクトの計画よりも先に来ます。詳細は references/uniqueness.md にあります。

文法を 1 つ選びます。 8 つあり、それぞれが他のものが要求することを禁じるため、互いに排他的です。フィルミック・ワンショットは最初の 4 つのビルドがすべて使ったものなので、再び選ぶということは、他の 7 つがなぜこのインタビューに合わなかったのかをレポートで説明することを意味します。ナビ、ヒーロー、クローズはすべて文法から導かれます。それらは個別に決めるものではありません。

シグネチャームーブを発明します。 このサイトだけに存在する、ページ内にコーディングされた一つだけのオーダーメイドのインタラクションであり、キットのデバイスに対するパラメーター変更ではありません。インタビューの質問 5 がその種です。エンジンには手を付けません。

フィンガープリントゲートを実行します。 <workspace>/FINGERPRINTS.md にある自分のレジストリを読んでください（Bootstrap の The workspace を参照。パスを出力するには node <skill>/scripts/workspace.mjs を実行してください）。計画中のビルドは、6 つの次元のうち少なくとも 4 つにおいて、すべての既存行と異なっていなければなりません: 文法、ナビの扱い、ヒーローデバイス、アクトシーケンスの形、クローズのパターン、シグネチャームーブ。それぞれの行に対して個別に 4 つです。失敗した場合は、ログではなく計画を変更してください。

スコア表の前にフィーリングカーブを書きます。 アクトごとに 1 行: 感情、そしてその原因となるもの。カーブが先、アクトが後です。なぜなら、感情より先に選ばれたデバイスは、理由を探しているデバイスだからです。隣り合う 2 つのアクトが同じ感情を持つなら、一方は埋め草であり、アセットが存在した後に削るよりもここで削るほうが安く済みます。同じパスでピークを名付け、ページ上で最大のスパンを与えてください。完全な方法は references/feel.md にあります。

次に、各ビートにデバイスを割り当てます。意図的に行い、表として書き留めてください:

ビート	デバイス	これを選ぶ理由
Recognition	scrub	読者自身の手の下でカメラが動くことは、可能な限り最強のオープニングである
Tension	pin + kinetic	フレームが静止したまま、コピーが行ごとに組み上がる
Turn	reveal	ワイプは状態の変化であり、それがこのビートの本質である
Substance	scrub (macro)	目では他の方法では得られないスケールのテクスチャ
Range	pan	横方向の移動は「選択肢」として読め、縦方向は「主張」として読める
Commitment	pin + pointer	ページが動くのをやめ、反応し始める

この表はフィルミックなスコアです。それは 1 つの文法にとって正しい形であり、他の 7 つにとっては間違った形です。ですから、行を埋める前に自分の文法の leans-on と bans のリストを読んでください。

ビルド前のチェック:

• 文法の禁止事項が守られている。pin を禁じる文法は、たとえそれがどんなにうまく機能したとしても、ここでもそれを禁じます。
• 4 つ以上の異なるデバイスファミリー。それより少ないと、ページが 1 つのアイデアしか持たないことになります。
• 同じデバイスファミリーを連続して使わない。
• scrub のアクトは最大 2 つ。ビデオはページ上で最も重いものであり、3 つ目はもはや驚きではなくなります。
• 隣り合う 2 つのアクトが同じ感情を持たない。もし持つなら、一方は埋め草です。
• 1 つのアクトがピークであり、目に見える差で最大のスパンを持っています。その前のアクトはそれより静かです。
• すべてのアクトがそのスクロールスパンを獲得している。ページ全体の長さは 8 ～ 14 ビューポート高。長いことはより没入的ではなく、より遅いということです。
• アクト数と全体の長さが、以前の 4 つのビルドすべてが当たった 6 ～ 7 アクト、13.6 ～ 13.8vh の帯に収まっていない。その帯は今やフィンガープリントの次元です。

ステップ 3：アセットを生成する

パイプライン全体、プロンプトのひな形、モデルに関する注意事項は、references/assets.md を参照してください。

簡易版：

node <skill>/scripts/kie.mjs still "<style preamble>\n\n<scene>" out/01-hero.png --ar 16:9 [--ref brand-can.png]
node <skill>/scripts/kie.mjs shot  "<camera move>" out/01-hero.png out/01.mp4 --dur 5
bash  <skill>/scripts/encode.sh out/01.mp4 assets/01.mp4
bash  <skill>/scripts/encode.sh out/01.mp4 assets/01-m.mp4 mobile

仕上がりを高品質に見せるか、生成画像らしく見せるかを左右するポイントは 3 つです。

• すべてのプロンプトで、同じスタイルの前置きを一字一句変えずに使います。 これにより、別々に生成した 6 枚の画像が 1 回の撮影で作られたように見えます。一度だけ書き、決して言い換えないでください。
• 使う前に、すべてのアセットを確認します。 PNG を読み込みます。生成は低コストですし、質の悪いフレームをリリースするくらいなら、再生成する方がさらに低コストです。
• 再生ではなく、スクロール操作に合わせてエンコードします。 encode.sh では、前のキーフレームからシークするため、密な GOP を設定しています。通常の Web 用エンコードは再生には問題ありませんが、スクロール操作ではまともに動きません。

ステップ 4：ページを構築する

実際の HTML を書きます。実際の <h1>、実際の <p>、実際のリンク、実際の読み上げ順序を用意します。エンジンはマークアップから data-sc-* 属性を読み取って動作し、DOM を生成することはありません。設定オブジェクトからページを構築するランタイムを使うことこそ、それで構築されたサイトがどれも同じ見た目になる理由です。

references/template.html を出発点にしてください。デバイスのパターンは references/devices.md に、余白、書体、奥行き、色のルールは references/taste.md に記載されています。マークアップを書く前に taste.md を読み、チェックリストについて触れずに構築してください。

6 つの値と 2 つのフォントを使い、トークンを上書きしてテーマを設定します。

:root {
  --sc-canvas: #0A0806;  --sc-surface: #16110E;
  --sc-ink:    #F5EBDD;  --sc-ink-soft: #A2968A;
  --sc-accent: #FF5A3D;  --sc-accent-ink: #15110F;
  --sc-font-display: "Archivo", system-ui, sans-serif;
  --sc-font-text:    "Geist", system-ui, sans-serif;
}

ステップ 5：スクロールして検証する

これは必須です。「動くはず」では不十分です。スクロールページに単一の状態はありません。位置ごとに異なるフレームが表示され、問題はたまたま確認した 2 つの位置の間に潜んでいます。手順の全体は references/verify.md を参照してください。

cd <build project> && npm i playwright-core     # once
node <skill>/scripts/serve.mjs --root . --port 4500 &
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/shots
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/mobile --width 390 --height 844
node <skill>/scripts/shoot.mjs --url http://localhost:4500 --out lab/reduced --reduced-motion

ハーネスは各アクトを 6 つの位置で確認し、スクラブ動画が実際に落ち着くまで待機してから、スクロールしても動かない箇所、不透明度が最大にならないキュー、および各行の下で最も明るいフレームにおける、合成後のページで測定したコントラストを報告します。コンタクトシートも作成します。

次に、ハーネスではできないことを行います。sheet.png を読み込んでください。 クリップが進むことは確認できますが、構図が良いか、動きが滑らかか、ページに意味があるかは判断できません。また、Tab キーでフォーカス順序も確認してください。

続いて、印象を確かめます（references/feel.md §6）。先入観を持たずにページをスクロールし、各アクトで感じたことを 1 語ずつ書き出してから、BRIEF.md を開いて意図された曲線と照らし合わせます。両者が食い違う場合、間違っているのはページであり、ブリーフではありません。ピークが最も大きな視覚的変化であり、スクロール範囲を最も広く占めること、また最後の画面が何もないままフェードアウトせず、きちんと収束することをシートで確認してください。

そして、テストがすべて成功しても実機のスマートフォンで確認する必要があることを明記してください。 ヘッドレス Chrome では、iPhone の動画デコーダー、自動再生ポリシー、低電力モード、タッチスクロールを再現できません。あるビルドでは、実機でヒーロークリップが停止したままなのに、4 回のテストがすべて成功してリリースされました。モバイルは最後に確認するだけの対象ではなく、最初から重要なターゲットです。縦向きスマートフォン用クリップ、タッチ操作に合わせて調整した lerp、拡大したタップ領域はすべて制作段階で用意します（assets.md と verify.md を参照）。モバイルの不具合が報告されたら、再現できないマシンで理論を立てるのではなく、最初のラウンドでサイトの隣に references/device-diag.html を配置し、実機で原因を確認してください。iOS のクリップのライフサイクルに関する詳細は、verify.md の「The phone is a different machine」を参照してください。

見つかった問題を修正し、もう一度撮影してください。実際に検証したことと、検証していないことを報告してください。

厳守事項

好みではなく、リリースを阻む要件です。どれも、ページが機械で作られたように見えてしまう要因です。

禁止事項	代わりに
デフォルトの世界観として、粘土のジオラマ、ローポリ、クレイアニメーションを使うこと	写真のような表現にします。worlds.md を参照してください
スクロールを促す合図、矢印、アニメーションするマウスアイコン	何も置きません。ユーザーはヒーローを見ているので、分かっています
01 / 06 のセクションカウンター	削除します。ここでは順番は情報になりません
セクション見出しの上に毎回アイブロウを置くこと	3 セクションにつき最大 1 つです。見出しだけで十分です
表示される箇所でのダッシュ記号の使用	ピリオド、コンマ、コロン、または括弧を使います
すべての幕で中央揃えのコピーを使うこと	起点を変えます。冒頭、末尾、中央、分割などです
同じ演出を連続して使うこと	Step 2 でジャーニーを適切に設計します
人へのヒアリング前に何かを生成すること	Step 0 を実行します。BRIEF.md を作成するか、自分で作成したと明記します
意図的なピークがない、または競合するピークが 3 つあるページ	ピークは 1 つです。アセットの予算、その前の静寂、最も長いスクロール範囲を割り当てます。feel.md §2 を参照してください
余韻なく終わる、フェードアウトする、または単にフッターになるエンディング	終わりは解決感をもたらし、その印象を保ちます。最後に残る感情が、ユーザーの持ち帰る感情です
感情曲線ができる前に幕を計画すること	まず曲線、その次に演出です。feel.md §1 を参照してください
独自のシグネチャー演出なしでリリースすること	ひとつ考案します。スポットライトの色を変えただけ、または傾きを調整しただけでは該当しません。uniqueness.md §3 を参照してください
既存のいずれかの行に対して、6 つのフィンガープリント軸のうち 4 つ未満しか異ならないビルド	FINGERPRINTS.md ではなく、計画を変更します
独自の挙動を実現するためにエンジンを編集すること	--sc-p と独自の data-sc-* を使い、ページ内に独自の JS を記述します
前回のビルドで使ったという理由だけで、フィルム調のワンショットを選ぶこと	8 つすべての文法から選び、残りの 7 つを選ばなかった理由を述べます
コントラストを調整するために全画面の暗いオーバーレイを使うこと	テキストがある箇所だけにスクリーンを置きます
生成画像にテキストを埋め込むこと	常に実際のマークアップを使います。選択でき、翻訳でき、鮮明です
カウンターに架空の統計値を使うこと	実際の数値だけを使います。数値がなければ、カウンターもありません
transition: all の使用、または width／height／top／left のアニメーション	transform と opacity を使います。ワイプには clip-path を使います
グラデーションテキスト、ネオンの輝き、オフセットがゼロの色付きハローシャドウ	強調には太さとサイズを使います。シャドウにはオフセットとぼかしを加えます
自動再生する音声、またはスクラブクリップでのあらゆる音声	音声トラックを取り除きます。encode.sh がすでに処理します
Step 5 を実行せずにリリースすること	Step 5 を実行します

出力

BRIEF.md を含むビルドフォルダーに、簡潔なレポートを添えます。レポートには、使用した文法と残りの 7 つを選ばなかった理由、シグネチャー演出、既存の各行に対するフィンガープリントゲートの結果、ジャーニー、感情曲線とピーク、感情チェックの差分（意図した曲線と実際に感じられた曲線、および変更内容）、スコア表（ビートごとの演出）、生成したもの、スクリーンショットで検証した内容、検証できなかった内容を記載します。ヒアリングではなく、自分でブリーフを作成した場合は、その旨を明記します。ローカル URL も記載します。簡潔にまとめてください。納品物はページです。

その後、ビルドの行を <workspace>/FINGERPRINTS.md に追加します。

スキル自体への変更と、その変更のきっかけとなったビルドの知見は CHANGELOG.md に記録されています。