stageshow

Stageshow

ミニチュアのプロダクト UI：空間の中に意図的に配置された、信頼感のあるインターフェースです。1枚の静止画、または1つの動きが起きる短いアニメーションとして表現します。見る人は画面を認識し、その動きを目にします。

伝えたいことは一つ

本物のプロダクトのように見え、見る人に必要な要素だけに絞られ、意図を持って配置され、すべての動きに理由があります。

うまくいかない例は5つあります。

• 盛り込みすぎ。 すべての行に実際のテキストがあり、至るところに数字があり、あらゆるものが詰め込まれています。細部が増えるほど、生成されたものに見えてしまいます。
• ワイヤーフレーム。 2つの灰色の塊とボタンだけです。小さく作りすぎているか、見分けがつく要素まで取り除いています。
• 枠に閉じ込める。 ウィンドウ全体を均等な余白のカードに縮めています。プロダクトのショットではなく、スクリーンショットを貼り付けただけです。
• 平坦。 すべてのオブジェクトが同じ境界線付きカードの中で、同じ重みになっています。視線を向ける場所がありません。
• 凡庸。 カーソルのある灰色のウィンドウで、ブリーフに書かれた内容をそのまま形にしています。ブリーフの見た目と雰囲気（設計図、色の上に重なるガラス、Dynamic Island、マスコット）が肝心です。求められているものを取り入れ、ルールに沿って作りましょう。examples/hero-demo では、入力中のポップアップと、端末やレシート、詳細カードなど、ヒーローの端にまたがる小さな2つ目のオブジェクトであるサテライトを使っています。

解決策は、落ち着いたグレーを基調に、構造のある画面を作ることです。実際の言葉を使うのはストーリーの中心となる部分だけにし、それ以外はプレースホルダーの線で表現します。余白を確保し、ストーリーに視線が向くように切り取ります。簡略化するのは言葉であって、文脈ではありません。空いた隅、リストの下の空白、ペインを埋めるためだけに広がった行、台座の上に浮かぶウィンドウ（その背後に置く背景や色付きの領域）は、落ち着きではなく未完成です。

これはブラウザーの自動操作ではなく、手作業で作るイラストです。a.click() はカーソルが押す動きを描き、a.set() はシーンを変化させます。

どこまで作り込むか

プロダクトデザイナーが評価されるローンチページを作るときと同じように作りましょう。examples/ の優れた例は目安ではなく、基準です。最も近い優れた例と並べて、こちらのほうが空っぽで、平坦で、小さく見えるなら、それを最初に直します。次に、知るかぎり最も妥協を許さないデザイナーの目でフレームを見直してください。1つでも間違いがあればスクリーンショットを撮り、「これは何？」と送り返すような人です。アバターからずれた点、単独の行に置かれた単位、Dynamic Islandの下にあるつかみ部分、カードに触れるテキスト。そんなスクリーンショットが思い浮かぶなら、それが次に直すところです。

ワークフロー

品質の大半は、コードを書く前に決まります。まず計画を書きましょう。どこに配置するか、焦点となるオブジェクトは何か、どんな動きがあるか、見せ場は何か、省けるものは何かを決めます。

1. メディアと配置。 静止画またはアニメーション（ループ、表示時に1回再生、またはホバー時）。ページ、その背景、幅を考慮します。表示されるサイズでデザインします。コピーの横に置くヒーローなら約720 × 340（hero-demo）、全幅のヒーローなら幅900～1100（linear）、カードなら400 × 300で、1:1で表示します。デモの幅は約320未満にしません。ただし、Bentoのタイルやサテライトカードは小さくてもかまいません。スマートフォンの列に置けるデモはすべて、列幅（358）に合わせたcompactデザインを用意します。縮小するのではなく、デザインし直してください（references/framing.md、Small formats and the page）。タイルのグリッドはひとまとまりです。references/bento.mdを参考に計画してください。
2. 見た目。 製品のコードまたはサイトを参照できる場合は、そのトークンをキットのトークンに対応付けます（references/looks.md）。開発者から独自コンポーネントを使うよう依頼された場合は、キットの小さなパーツの代わりに、ステージ内でそのコンポーネントを使います。それ以外の場合は、テーマ（ライト、ダーク、ブループリント、ガラス）、パレット（アクセント、モノクロ）、忠実度を選びます。minimalはバーだけ、standardは意味を伝える箇所に言葉を使い、それ以外はバーを使い、realisticはすべてに実際のコンテンツを使います。デフォルトはライト、アクセント、標準です。ヒーローサイズ、実在する製品名を使う場合、またはリストやページを主題とする静止画では、リアルな表現にします。ダミーコンテンツはText fillerで一度だけ記述し、忠実度に応じて表示させます。製品独自のアイコン、本物のクローム、製品だと認識できるコンテンツを使います。概要にスタイル（Kawaii、紙、ポスターカラーなど）が指定されている場合は、このルールに沿って、そのスタイルを徹底して表現します。
3. ストーリー。 その形を決めます（references/motion.md、Story）。使い心地、流れ、またはシステムの動作を伝えます。3～5つのビートと見せ場を用意し、再生時間は10～16秒にします。理由を説明できないカーソル移動は避けます。画面上で、理由もなくデータが巻き戻ることがないようにします。ストーリー性の豊かさと落ち着いたフレームのどちらかを選ぶなら、フレームを選びます。
4. 例から始める。 最も近い優れた例（以下のGoldテーブル）を見つけて、撮影します（node scripts/film.mjs "<preview>/?capture=<gold>" --select '#example' --still --out gold.png。プレビューはnpm run devで配信されます）。そのフォルダーをプロジェクトにコピーして、出発点にします。見ただけで作り直してはいけません。最短の進め方は、ここにexamples/<yours>/としてコピーすることです。そうすればプレビューに取り込まれ、?capture=<yours>で撮影できます。合格したらホストに移し、キットのインポートパスを修正します。構造はそのまま保ちます。ステージのサイズ、トリミングと裁ち落とし、行と文字のサイズ、間隔、スクリプトのビート、キットのパーツを維持してください。次にreferences/craft.mdを最後まで読みます。短い文書ですが、優れた例だけでは分からない静止フレームのルールや、例にたまたま含まれていないケースが説明されています。その後、見た目とコンテンツを概要にある製品に置き換えます。手順2のトークン、製品独自のアイコン、クローム、言葉を使います。名前を変えただけでは完成ではありません。優れた例の製品ではなく、概要にある製品として伝わる必要があります。ストーリーに合う優れた例がない場合は、2段階で選びます。まずレイアウトを決めます（references/framing.mdのテーブルから選択します。各レイアウトには対応する例があります）。ストーリーが異なっていても、その例をコピーします。次に、ビートに合わせた動きを、ストーリーが最も近い例から取り入れます。どちらの例にもない部分は、同じスタイルで作ります。そしてフレームを決めます。ストーリーが起こるパネルに合わせてトリミングし、最終的に表示される範囲で判断します（ルールとレイアウトテーブルはreferences/framing.mdを参照）。要点は次のとおりです。ガターは1つにするか、全面にするか、かなり広く取ります。裁ち落とすのはダミーコンテンツだけにします。開いたものはそのまま表示します。ウィンドウの形状を維持します。ページが背景なので、白またはダークなページ上のヒーローの下にプレートを敷かず、四辺に余白のあるウィンドウ全体も見せません。開発者から依頼された場合に限りunframedを使います。空白のコーナーを作らないでください。両方の幅で静止画を撮影し、優れた例と並べて確認します。こちらのほうが空疎、平坦、または枠で囲みすぎている場合は、動きを加える前にフレームを修正します。
5. 画面。 実際に表示する文字列を数えます。通常は3～7個です（references/craft.md、Restraint）。これは要素数ではなく、言葉の予算です。キットのトークン、Bar、Text、Rowを使って構築します。動かす前に、すべてのコントロールのテキストが収まるようにします。カーソルが触れる箇所にはdata-targetとdata-cursorを指定し、計測にはrect()を使います。値をハードコードしてはいけません。
6. 動きを組み立てる。 Act APIを使います。表示する要素はマウントしたままにし、切り替えによって退出時もアニメーションさせます（BubbleとFlyは明示的に受け渡します）。単にオブジェクトを動かすのではなく、要素同士の関係をアニメーションさせます。新しい行が加わるときは、その下の行も動かします。サイズ変更されるサーフェスでは、テキストを伸縮させません。ビートを重ね、グループにはずらしを付け、見せ場はしばらく表示します。ループは最初と同じ状態で終えるか、目に見える理由を伴ってリセットします。
7. リハーサル。 まずposterを設定します。多くの人はそのフレームだけを見ます（サムネイル、モーション低減時、スクリーンショットなど）。それだけでストーリーを伝えられるビートを選び、途中で変化している瞬間は避けます。後片付けで消さず、結果を画面に残してください（references/motion.md、Story）。次に静止画だけでなく、ループを撮影します。表示幅と390幅でコンタクトシートを作り、すべてのプレス、メニュー、モーフ、ループの継ぎ目を確認します（references/rehearse.md）。静止画ではポップを確認できません。すべてのフレームを確認し、最も目立つ欠点から修正します（フレーミング、次に階層、次に動き、最後に仕上げ）。そして再撮影します。次に最も近い優れた例と並べ、references/teaching.mdの全体構成とスタイルに関する問いを、自分の静止画についての質問として確認します（最初に目が向かうのはどこか。それは結果か。1つのウィンドウ、タイル、またはデバイスが明確に主役になっているか）。「いいえ」となる項目があれば、それが最大の欠点です。film.mjs --gateの結果がrehearsal passedとなることは必要条件ですが、十分条件ではありません。最後にreferences/rehearse.mdの確認を実行します。新鮮な目でレビューし（references/review.md）、コンポーネントの横にREHEARSAL.mdを用意します（テンプレートはreferences/verify.mdのHand overを参照）。コピーした優れた例、変更した内容、確認していない内容を記載してください。 各ラウンドで繰り返し発生する不具合と、それぞれのルールを引き継ぎ前に確認してください。

• 移動せずに入れ替わるコンテンツ（references/motion.md、テキストと値の変更）。
• **視線が集まる場所にあるグレーのバー。**余白要素は端に配置してください（references/craft.md、抑制）。
• **ウィンドウの背後にあるプレート、または四方に余白を残して浮いているウィンドウ。**ウィンドウまたはスマートフォンはステージの少なくとも3分の2を占め、端からはみ出すようにしてください（references/framing.md、ルール5および小さなフォーマットとページ）。
• 空の帯、切れたコントロール、影（references/craft.md、抑制、references/framing.md、ルール4）。
• **ありきたりなAI表現と架空のロゴ：**きらめき、紫、色付きの四角に入った文字（references/craft.md、アイコンとロゴ）。
• 要素が詰まった行と不揃いなインセット（references/craft.md、抑制、間隔と配置）。
• 長すぎる停止と、原因のないリセット（references/motion.md、ループ）。
• Iビームの位置と合っていない選択範囲（references/motion.md、ドラッグと選択）。
• **手描きのステータスバーやホームインジケーター。**どちらもPhoneが描画します（references/craft.md、クロームとデバイス）。
• 金額と通貨記号を中央揃えにした表示（references/craft.md、間隔と配置）。

例

始める前に、最も近い例を撮影してください（ステップ4）。Goldの例が品質基準です。プロダクトの事例は操作方法を参考にするためのものであり、他のプロダクトのアイデンティティを借用してはいけません。標本シートはカタログであり、構成例ではありません。すべてnpm installとnpm run devで実行してください。teaching/には問題の診断に使える悪い例／良い例のペア（references/teaching.md）があります。悪い例を出発点にしてはいけません。

Gold

必要なもの	例	学ぶこと
静止画または機能カード	static-card	静かな階層構造、大胆なトリミング、サテライトを1つ、選択中の顧客とその隣、合計以外には実際のテキストを使わないこと
ダークな静止画	dark-bento	1つのシグナルを1度だけ伝えること。アルバムアートで音楽アプリらしさを保つこと
アニメーション付きヒーロー、ジェスチャー	hero-demo	5つのビート、名前付きターゲット、注釈、手前に出てくるターミナル
カーソルなしの演出	payout-flow	ゆっくり重なりながら現れる要素、読むための時間、余韻を保つ見せ場
その場で変化するコンテンツ	choreography	残るトラック、柔らかなマスク、連動するタイミング
AI の回答	ai-chat	質問を送信し、「考えています」を表示し、高さに合わせて回答をストリーミング表示し、最後にソースを表示すること。キラキラや紫色は使わないこと
カードを使った AI	ai-cards	複数選択カードに回答して記録として残すこと、スレッド内で選択肢のカードを開くこと、カード上のボタンから予約すること
フォームの検証	form-error	原因となったフィールドにエラーを表示し、修正すると消え、その後ボタン自体で確認を示すこと
ドラッグによる並べ替え	reorder	行をつかみ部分で持ち上げ、ほかの行が場所を空け、所定の位置にドロップすること
グラフのスクラブ	chart-scrub	ポインターに追従する細い線と点、その日の値に合わせて変わる見出しの数値
テーブル内での編集	table-edit	セルをその場で編集し、そこから算出される合計が1拍遅れて変わること
読み込みからコンテンツへ	loading	コンテンツ本来の形状に合わせたスケルトン、上から下へ解決する行、常に表示される実際のクローム
ダークなヒーロー	dark-hero	黒地に重ねたサーフェスの段差で奥行きを出し、光る色を1色に絞り、ステータスを専用のピル上で変化させること
ライブコラボレーター	presence	すべての場所で各人に同じ色を使い、カーソルに名前を添え、ドキュメント本来のマークで作業を示すこと
システムのストーリー	subscriptions	チップが行に飛び込み、MRR が変わり、2つ目のシーンでリセットすること
クローズアップ	close-up	ウィンドウのクロームを含め、1つのコントロールを1.4倍で表示し、行全体を見せ、それに合わせて大きなカーソルを使うこと
1つの要素を多数表示	many-of-one	端からはみ出すほど1種類の要素をグリッド状に並べ、奥行きで1つに焦点を当て、テキストを持たせるのはその1つだけにすること
フェードするトリミング	fade-crop	ウィンドウの下端をフェードさせ、端からはみ出させるのではなく、埋め草の上に重ねること
プロダクト上のパネル	panel-annotation	プロダクトの余白に設定パネルを重ね、設定から変更箇所へリーダー線を1本引くこと
重なり合うウィンドウ	overlap	ウィンドウの前にカードを置き、その端をウィンドウのサイドバーの線に合わせること
積み重ねたカード	stacked-cards	同じ幅のコンポーネントを2つ、小さな隙間を空けて配置し、下のカードは画面下からはみ出させること
対角の隅	opposite-corners	Bento タイル：コピーを左下に、プロダクトを右上の隅から吊り下げること
傾けたスタック	tilted-stack	紙をゆるく積み、小さく交互に傾け、最上部のカードだけにテキストを載せること
隅のチップ	corner-chip	ウィンドウの隅に小さなチップを中央揃えで置き、半分を外にはみ出させること
モノクロ	monochrome	他社のプロダクトを横一列に並べ、グレースケールにし、下端をフェードさせること
ウィンドウの列	window-row	同じ高さでセッションを横に並べ、奥行きで焦点を合わせ、隣の要素はステージで切り、埋め草だけをトリミングすること
ウィンドウとスマートフォン	device-pair	ダッシュボードとロック画面で1つのイベントを伝えること。スマートフォンは余白にまたがらせ、図には決して重ねないこと
関連オブジェクト	story	請求書、プラン、コネクター、変化する合計
カレンダーのドラッグ	calendar	予定の入った1週間、焦点となるイベント1つ、計算されたピックアップ
自由なドラッグ	freeform-drag	つかむ位置のずれ、計算されたグリッド、スナップするドロップ枠
スマートフォンアプリ	phone-touch	カードが1つのオブジェクトとして画面に開き、ループで折り返すこと
Dynamic Island	dynamic-island	黒い形状を1つ、そのコンテンツを別レイヤーにすること
メッセージ	messages	入力欄、入力中表示、開封確認、吹き出しの表示時間
カーソル	cursors、cursor-morph、cursor-resize	5つのスタイル、要素に応じた種類、辺と隅のリサイズ、カーソルなしの状態
注釈	annotations	リーダー線、寸法、フロー、移動するターゲット。references/annotations.md
機能グリッド	bento	ヒーローを1つ、ウィンドウを1つ、統計、オブジェクト、図
ダークな罫線グリッド	ruled-bento	共通の罫線とテクニカルなイメージ
コンシューマー向けグリッド	staggered-bento	ずらしたタイル、グラフィックアート、物理的なオブジェクト
画像主導のヒーローグリッド	hero-grid	異なる背景と素材を、1枚の絵として構成すること
アップロード	upload	デスクトップからドラッグされたファイル、ファイル行として落ち着く進捗表示付きのアップロード行
共有	share	ドキュメント上の共有ポップオーバー：メールアドレスがチップになり、ロールメニューが開き、リストにユーザーが追加されること
スワイプ	swipe	スワイプしてアーカイブするスマートフォンの操作：押し、スワイプし、指の速度で投げ、隙間が閉じること

製品の調査

見覚えのある製品（Figma、Linear、Slack、Raycast、Finder、Spotify、Notion、Gmail、Google のアプリ、Office、Wikipedia、Telegram、iMessage）については、まず references/products.md を読んでください。他の製品のアイデンティティではなく、インタラクションを参考にしてください。

必要なもの	例	学ぶこと
デザインツール	figma	キャンバスの選択、カラーピッカー、2 つ目のカーソル
課題管理ツール	linear	コマンドメニューと担当者の割り当て
チャット	slack	メッセージ、リアクション、スレッドへの返信
ランチャー	raycast	ぼかしたデスクトップ上での検索とクリップボード履歴
ファイル	finder, finder-glass	ファイル一覧上でのクイックルック、ファイルをフォルダーに移動する操作、すりガラス調の同じウィンドウ
音楽、ダーク	spotify	アルバムアートを使ったダークなデスクトップアプリ
ドキュメントとエディター	notion, google-docs	スラッシュコマンド、コメントとその返信
メール	gmail	ホバー時のアクション、アーカイブ、取り消しのトースト
カレンダー、実際のアプリ	google-calendar	イベントをドラッグして作成する操作、クイック作成ポップアップ
Office	powerpoint, excel	スライドの編集、オートSUMとグラフ
ブラウザのページ	wikipedia	ブラウザーでの検索候補
電話での会話	telegram, imessage	iPhone のネイティブなチャットアプリ

標本とリファレンスシート

パーツと背景のカタログは references/kit.md（標本シート）に記載されています。パーツはこちらで調べ、完成度の高い例をもとに組み立ててください。

必要なもの	例	学ぶこと
キットの標本	chrome, phones, controls, parts, kit-extras	すべてのフレームとパーツ
ガラス	glass	色のある背景上のすりガラス面
背景	backgrounds	20 種類の背景上の 1 つのインターフェース、references/backgrounds.md
ロゴ	brand-marks	明るい背景と暗い背景に合わせて光学的にサイズ調整した実際のロゴ、references/brands.md
製品の外観	looks	タイポグラフィ、形状、色の組み合わせ

キット

kit/ をプロジェクトにコピーし、kit/index.ts からインポートしてください。React、react-dom、lucide-react（Field と Chip が使用する Icon 用）が必要です。各パーツには独自の CSS が含まれています。手作業では正確に仕上げるのが難しいパーツをキットが提供し、製品らしい外観はユーザーに委ねます。各パーツの props とルールは references/kit.md に記載されています。使用するパーツの項目を読んでください。

• ステージ。 Stage：デザインサイズとフィットするように拡大縮小する機能、compact、シーンの状態、再生、外観、カーソルを備えています。スクリプトは Act（set、wait、move、click、type など。references/kit.md の Act を参照）を受け取ります。
• フレーム。 Window、LockScreen と Notification を備えた Phone、Keyboard、Bubble を備えた Thread、Stamp、Receipt。実際のジオメトリを備えているため、ウィンドウ、デバイス、吹き出しを手作業で描く必要はありません。
• モーション。 Collapse、Roll、Swap、Count、Connector、Fly、Follow、States、Stream、Popover、Scroll、Camera、Expand。手慣れていない人が間違えやすいフレーム処理を担います。
• 小さなパーツ。 Bar、Text、Row（すべてのリストはこれで構成します）、Avatar、Pin、Icon、Menu、Field、Segmented、Toggle、Tabs、Badge、Chip、BrandMark、Code、Chart。控えめな出発点として使い、製品に合わせてスタイルを変更してください。キットのパーツのジオメトリを外側から変えてはいけません。
• stageshow.css：トークン、外観、エッジのフェード、ウィンドウのクローム、スマートフォン、キーキャップ。

リファレンス

references/framing.md：フレーミングのルールとレイアウト表。references/craft.md：静止フレーム（抑制、タイポグラフィ、間隔、アイコン、色、クローム）。references/motion.md：ストーリー、ループ、ペース、カーソル、ドラッグ。references/verify.md：見えるもの／行うことの表を含むチェックリスト。references/rehearse.md：撮影方法と、意図せず映り込む映像の要素。