diorama

Diorama: 動く小さな世界

詳細な物語的なミニチュアやピクセル仕上げのシーンには、別の diorama-worlds スキルを使ってください。このスキルは、依存関係のない SVG イラストレーションワークフローを維持します。

あなたは1つのジオラマを作ります。丸みを帯びた土台の上にブロックで組み立てられ、等角投影カメラで見下ろし、いくつかのものが自律的に動き、ポインターに応答し、テーマに沿って描かれたシーンです。デフォルトのテーマ toy は、パステルカラーのブロック、温かい太陽、柔らかな影で、すべてのオブジェクトは数個の箱と円筒で構成され、テクスチャはなく、一目で楽しく読めます。同じシーンファイルが soft（クリーム色、より優しい）、mono（1つのアクセント、残りはインクの濃淡）、line（極細線の描画：白い塗りつぶし、インクの輪郭、影なし）、print（面ごとにフラットな色調とインクの線、印刷されたイラスト）、night（夕暮れ、ランプ点灯）でも描画され、すべてのテーマフィールドは上書き可能です。wobble はインクを手描き風にし、halo はベースがページに落とす柔らかな影で、accent はすべてのテーマにおける被写体の色です。examples/ にある18の例が基準であり、あなたが書くフォーマットもこれに従います。

あなたが書くのは1つのこと、すなわちフィギュア（.js ファイル）だけです。カーネル（kit/diorama.js）とページ（bench.html）は固定されています。これらを編集したり、変更したコピーを貼り付けたり、カーネルがすでに提供しているもの（カメラ、ライト、影、オフスクリーンでスリープするループ、ポインター、スプリング、パス、プロパティ）を再度書いたりしないでください。

以下に記載されるすべてのファイルは、このスキルのフォルダ内にあります。フィギュアとページは作業ディレクトリに書き込まれ、scripts/build.mjs、scripts/validate.mjs、scripts/look.mjs はそのディレクトリから、このフォルダ内のパスを指定して実行します。

1. サイズとコンセプト

まずサイズを決めます。予算が決まるからです。

サイズ	配置場所	ステージ	パーツ数	行数	動作
hero	ランディングページ上部、README、プロダクトツアー	3:2、全幅	150–400 プリミティブ	≤ 420	3つまたは4つの独立したループ、常に何かが動いている
card	ドキュメントページ、ブログ記事、機能セクション	4:3、約500px	60–150	≤ 240	1つまたは2つのループとポインター応答
mini	空の状態、機能リスト、404、設定セクションなどの小さな場所	1:1、160–240px	15–40	≤ 150	1つの静かな環境動作

次に references/concepts.md を読み、コンセプトを1行で書き、最後にテーマを付けます。

名前. 場所とそこにあるもの。自律的に動くもの。ポインターがすること。（ミニの場合：何が欠けているか。）テーマ。

場所は例ではなく、プロダクト自身の世界から選びます。港、台所、屋上、机、温室、プラットホーム、発射台、街角などはすべてジオラマです。次にテーマは好みではなく、フィギュアが配置される場所から選びます。toy は暖かさと色彩を求めるプロダクトページに、soft はエディトリアルまたはクリーム色のページに、mono は独自のアクセントカラーを持つプロダクトUI（accent として渡す）、ドキュメント、または密集したテキストの横に、line はミニマルまたは技術的なページ、白地に黒文字のブランド、またはささやくべき空の状態に、night は暗いページに適しています。人物がブランドカラーを持っている場合は accent として入力し、すべてのテーマで被写体の色を変更します。2つ目の色は palette を通して指定します。references/craft.md には各テーマが追加するルールがあります。

次に、パーツリストをコードの前に書きます。グループごとに5行で、すべてのオブジェクトと、それを特徴付ける2つまたは3つの機能に名前を付けます。地面（スラブ、ゾーン、道路、水）、構造物（立っているもの：建物、ラック、木）、動くもの（乗る、歩く、回転する、持ち上げるもの）、家具（端を埋めるもの：ランプ、コーン、木箱、ベンチ、フェンス）、光（光るもの：窓、ランプ、ビーコン）。すべてのパーツは他のパーツの上にあり、浮いているものはありません。ヒーローリストは30オブジェクト、カードは10、ミニは3までです。リストがシーンです。リストが薄ければ、フィギュアも薄くなります。

誰かに相談できる人がいる場合は、2つまたは3つの選択肢を提案して待ちます。相談できる人がいない場合は、最も静止画が強いものを選び、どれを選んだかを伝えます。1つのジオラマ、1つの場所、1つのストーリー。キャプションが必要なシーンはまだコンセプトではありません。

2. 構築

1. references/craft.md を読みます。10のルールが、ジオラマを立方体の山ではなく場所に見せるものです。これらのルールを破るフィギュアは完成していません。
2. kit/diorama.js の先頭にあるインデックス（var Diorama の上のコメント）を読みます。そこには呼び出せるすべてのものがリストされています。その下のコードは読まないでください。
3. サイズとテーマに最も近い例を読みます。examples/town.js（hero, toy: 小さなヘルパー関数で構築された町全体、複数の周回、点灯するライト）、examples/island.js（hero, toy: 水のある場所、停留所のある周回、カモメと雲）、examples/farm.js（hero, toy: 畑、動物、停留所のある周回）、examples/warehouse.js（hero, toy: シャトルとドックのあるヤード）、examples/harbour.js（hero, toy: 18秒周期でコンテナを持ち上げるクレーン、停留所と上がるバリアのあるトラクターの周回、タグボート、灯台、タップでリフトを開始、読み出し）、examples/cafe.js（card, soft: 人と小物）、examples/kitchen.js（card, toy: 背面壁とその上に設定された窓のある部屋、ホバーでドアが開くシェルとして構築された冷蔵庫、タップでポップアップするトースター、時計）、examples/launchpad.js（card, night: ランプ、まれなイベント、ポインターの下で分解するロケット、タップで発射、カウントダウンする読み出し）、examples/server.js（card, mono with accent: リズムのあるライト、グループ全体を照らすホバー）、examples/rack.js（card, mono with one accent: ポインター応答のある空の状態）、examples/assembly.js（card, mono with one accent: タップで保持されるゲートを通るジョブのベルト、スタンピングアーム、カウントする読み出し）、examples/mailbox.js（mini, toy）、examples/seedling.js（mini, line: インクで描かれた空の状態）、examples/observatory.js（mini, line with wobble: 回転するドームと見る望遠鏡）、examples/desk.js（mini, line with accent）、examples/vending.js（mini, print: フレームとくぼみの周りに構築された機械、むき出しのコイル、ファン）。これらはすべて意図的に工場ではありません。ジオラマはどんな場所でもあり得ます。
4. フィギュアを作業ディレクトリに <名前>.js として、例の形式で書きます。1つの Diorama.figure({ … }) 呼び出しです。
   • name: 小文字、1語またはハイフン区切り、size: hero | card | mini。
   • theme: 名前、または { base: 'mono', accent: '#f2c230', shadows: false, … } のように任意のフィールド（palette, accent, lights, shadows, finish, tone, tint, edges, outline, stroke, strokeWidth, round, glow, halo, wobble）を上書きします。1回構築すれば、テーマはカーネルによってすべてのプリミティブに適用されるため、フィギュアはテーマによって分岐しません。pal.accent で重要なものをペイントします。これはすべてのテーマにおける被写体の色であり、mono と line が保持する色であり、ブランドの16進数が置き換える色であり、ベンチのスウォッチがライブで再配色する色です。手描き風の line フィギュアには wobble: 1.4（震えのCSS px：1.2はペン、2.5はフェルトペン）を追加します。
   • means: 1文、140文字以下。ステージの下に表示され、シーンが何を示し、何が動くかを示します。
   • hint: 1行、90文字以下。ポインターがすることとタップがすること（「ロケットにホバーしてステージを表示、管制室をタップして今すぐ発射」）。ページは訪問者が操作できるようにこれを表示し、look.mjs は名前の付いたものを押します。
   • title: フィギュアの名前。ページはステージの上にこれを表示します。人物自身のUIがフィギュアの周りに配置する言葉（見出し、行、ボタン）は彼らが書くものであり、シーンは何も持ちません。
   • camera: { az, el, pad } 度単位。az 45 が等角投影のデフォルトです。30–40 は3:2のヒーローで広いベースを表示します。シーンが高い場合を除き、el は 35.264 のままにします。
   • still: 縮小モーションとサムネイルが表示するループの秒数。すべてが物語のある位置にある瞬間を選びます（トラックがドックに、フォークが上がっている）。
   • build({ D, pal }): ツールキットを使用してシーンを1回構築し、parts を返します。tick が動かすすべてのグループとメッシュ、さらに parts.hot（ポインターが選択できるグループ）です。各ホットグループには .name（boat.name = 'boat'）を付けます。ページはポインターが当たっている間、これを読み出しとして表示します。
   • tick(ctx): 毎フレーム、ctx.t から D.phase、D.pulse、D.wave、D.inOut、D.path、D.spring を使用してパーツをポーズします。ctx.hover と押下には ctx.pressed または ctx.active で応答します（タップはスマートフォンでの操作方法なので、ヒーローまたはカードには1つの押せるもの（スイッチ、呼び出し、またはホバーの双子）があります）。D.apart はポインターの下でものを分解し、元に戻します。ctx.read にシーンが現在何をしているかを示す短い行を設定します（'トラック · ドックにて'）。ページはこれを読み出しとして表示し、訪問者がシーンがループではなく動作するモデルであることを学ぶ方法です。references/motion.md にパターンがあります。
5. 組み立て：node <スキル>/scripts/build.mjs <名前>.js を実行すると diorama-<名前>.html が書き込まれます。これにはベンチ、カーネル、フィギュアが含まれます。カーネルはイラストレーターが奥行きを偽装する方法（等角投影、面ごとに1つのフラットな色調、シーンの背面から前面へピースをペイント、地面に落ちる影を形状として描画）でSVGを描画するため、ページはレンダラーを必要とせず、WebGLも不要で、ネットワークリクエストも発生しません。描画はベクターであり、どのサイズでも鮮明で、ページはスタイルを設定できます。

3. 確認

1. node <スキル>/scripts/look.mjs <名前>.js を実行します。これによりページがビルドされ、検証され、ヘッドレスChromiumで開かれ、diorama-<名前>-look.png が書き込まれます。これには静止フレーム、ループの3つの瞬間、ポインターの応答、カメラの傾き、押下、サムネイル、ページ全体が含まれます。コンソール、塗りつぶし、動作、応答、押下が数値として出力されます。すべての FAIL を修正し、SMALL、STILL、FAINT、MUTE の行を質問として読み、終了コード0になるまで修正します。押下は、ヒントで「タップ」、「クリック」、「押す」と名付けられたホットグループに着地します（または --press name、--press x,y）。MUTE はヒントが押下を約束したのに何も変化しなかったことを意味します。--theme line（または任意の名前）を追加して、同じフィギュアを別のテーマで見ることができます。toy と line の両方で読めるフィギュアは正しく構築されています。また clash も出力されます。これは他のパーツを通過する動くパーツです。車両が木を通過する、車がバスを通過するは修正すべきバグですが、ラックの中のフォークやヒンジ上の旗は問題ありません。
2. references/look.md を読み、次にシートを読んでその質問に答えます。失敗するものを修正し、手順1に戻ります。

look.mjs はブラウザを必要とします。Playwright を見つけるか、このフォルダの外に playwright-core を一度インストールします。ブラウザがない場合は、ビルド後に node <スキル>/scripts/validate.mjs diorama-<名前>.html を実行し、look.md の「ブラウザなしの場合」の説明に従って look を行います。バリデーターが拒否するページを引き渡さないでください。確認していないのに確認が完了したと言わないでください。

4. 引き渡し

diorama-<名前>.html を、相手が希望する方法で引き渡します。ファイルを希望する場合はファイルを渡し、どこにあるかを伝えます。それ以外の場合は、可能であればアーティファクトとして公開します。その後、次の項目を1行ずつ伝えます。

• コンセプト：場所、動くもの、ポインターとタップがすること、テーマ（およびその切り替え方法：フィギュア内で theme:、ページ上で ?theme= と ?accent=、Diorama.mount で { theme }。ベンチのスウォッチは被写体をライブで再配色します）。
• 静止フレーム：何秒目か、なぜその瞬間か。
• 配置場所（hero、card、mini）と埋め込み方法（React または Next.js の場合は references/react.md、それ以外の場合はカーネルのプレーンな <script> とフィギュア、および Diorama.mount(fig, { el })）。
• 確認できなかったこと（Nodeなし、ブラウザなし）を明白に伝えます。

5. 調整

相手が変更を求めた場合、<名前>.js のみを編集し、再度 look.mjs を実行して新しいシートを読みます。10番目のバージョンも最初と同じ基準で評価されます。

よくある問題

もしあなたが次のことをしていることに気づいたら	代わりにこれを行ってください
three.js、ライト、カメラ、キャンバス、WebGL に手を伸ばしている	それらはありません。カーネルはSVGを描画します。D.box、D.cyl、D.props.*、o.M（ベクター用）、ctx を使用します
requestAnimationFrame、setInterval、CSSアニメーションを書いている	tick 内で ctx.t からすべてをポーズします（ルール07）
position.x += speed * dt でものを動かしている	それを D.path に置き、D.phase(t, period) から距離を読み取ります。ループがシームレスになり、静止フレームが再現可能になります（ルール08）
単語、数字、矢印をシーンに書いている	タイトルまたは means で伝えます。シーンには単語は一切含まれません。看板さえもありません（ルール10）
テクスチャ、グラデーション、グロー、15番目の色に手を伸ばしている	パレットカラーのブロックをもう1つ追加します。pal.* に必要なものがあります（ルール03と04）
フィギュア内で if (theme === 'line') と書いている	カーネルがテーマごとにすべてのプリミティブのトーン、ストローク、ライトを設定します。フィギュアは5つすべてで同じです
ブランドカラーを20のパーツに貼り付けている、または被写体をパレット名で塗っている	被写体を pal.accent で塗り、ブランドの16進数を宣言内の accent に1回だけ入れます。2番目の色には palette: { cobalt: … } を使用します
ホバー応答はあるが、指用の応答がない	1つのものに押下（ctx.pressed、ctx.active）を与えます。ホバーはプレビュー、タップは確定です（motion.mdの「押下」）
line フィギュアがCAD出力のように読める	テーマ内で wobble: 1.4 を設定します。インクが手書きのように曲がり、オーバーシュートします
「ベースが汚く見える」という理由で halo をオフにしている	ハローはジオラマをページに配置するものです。背景が込み入っている場合は下げます（.1）。維持してください
読み出しがタイトルと同じことを言っている	ctx.read は言葉で表した時計です。フェーズ、停止、カウントを、パーツをポーズするのと同じ T から取得します
シーンの後またはまったくベースを構築していない	D.slab を最初に実行します。影が着地する場所が必要です（ルール01）
シーンが同一の立方体のグリッドのように読める	すべてのオブジェクトに、それを特徴付ける2つまたは3つの機能を与えます（ルール05）
8つのものが入ったミニ	1つのオブジェクト、1つの環境動作（concepts.mdの「ミニ」）
すべてが同じテンポで動くヒーロー	3つのループを異なる周期で使用します（例の章を参照）
動くパーツが交差している（ルックシートの clash）	パスを調整するか、高さを追加します。フォークがラックの中にあるのは正しく、車両が木を通過するのはバグです
フィギュアが空っぽに見える、またはシーンがまばらである	craft.md のルール06を確認します。「すべての面は別の面に面している」
自分の書いたコードが提供された例とまったく異なる構造になっている	例の形式に従ってください。フィギュアは Diorama.figure({…}) 呼び出しであり、クラスや関数ではありません

look.mjs の出力に加えて、次のことを確認します。

• ビルドスクリプトがエラーなしで完了すること。
• 検証スクリプトが合格すること。
• 生成されたHTMLがブラウザで開くこと。
• すべてのテーマで一貫して見えること。
• ポインターとタップの応答が期待通りに動作すること。
• アニメーションがスムーズで、途切れやジャンプがないこと。
• 静止フレームが適切な瞬間であること。
• 読み出しが正確で有益であること。
• フィギュアのサイズが選択したサイズのガイドラインに合っていること。
• パーツリストが完全で、シーンが意図したストーリーを伝えていること。