isometric-explainer

アイソメトリック解説図

このスキルでは、1 ページのインタラクティブな図を作成します。図には、作業台の上にある立体的なアイソメトリック機械を描きます。機械の各ステーションは、プロセスの 1 つのステップを表します。たとえば、リクエストカードがキャリッジ上を移動し、プローブが降下して、プレスがカードに刻印します。すべての動作は純粋な状態モデルで決まるため、図、数値、文章の内容が一致します。templates/ フォルダーには動作するスターターがあり、kit/ にはそのスターターが使用するジオメトリライブラリがあります。

使用する場合

• この概念が、ステーション、順序、障害モードを持つプロセスである場合。たとえば、ループ、パイプライン、キャッシュ、キュー、再試行ポリシーなどです。
• 読者が一部を壊し、何が失敗するかを確認できる場合。
• 図がページのメインコンテンツである場合。

使用しない場合

• 静的な図で概念を説明できる場合。代わりにフラットな SVG 図を作成してください。
• 概念に順序や状態変化がない場合。代わりに静的な図を作成してください。
• 図がレッスンや README の中の小さな図である場合。同じ階層のスキル blueprint-figure を使用してください。
• 動作の決定論的なモデルを書けない場合。推測でアニメーションを作成しないでください。
• 150 個を超えるパーツが必要で、ユーザーが規模を承認していない場合。

手順

1. 機械を考案します。次の形式で 1 文を書きます。「X が Y を通って移動し、その動きは Z を意味します。」書けない場合は、別の機械を選んでください。references/concept.md を参照してください。

2. 描画する前に紙の上でパーツ数を数え、規模を選びます。

   規模	パーツ数	承認
   図	40〜80	不要
   ヒーロー	80〜150	不要
   大規模	150 を超える	事前にユーザーの承認を得る

3. まず状態モデルを書きます。DOM も時計も使わず、model.mjs を純粋かつ決定論的にします。simulate(config) はイベントリストと合計値を返します。ジオメトリに取りかかる前にテストしてください。references/state-model.md を参照してください。

4. 各概念をステーションに対応付けます。ステーション、ラベルに使う概念を表す単語、ステーションの動作、ステーションがない場合に起きる失敗を表にまとめます。

5. パーツリストを書きます。各パーツについて、アセンブリ、ワールド単位でのサイズ、色調、移動するかどうかを記載します。ジオメトリの作成はリストの後です。

6. カメラを設定します。ワールド単位と単一のアイソメトリックカメラを使用します。仰角を 30 度に設定します。作業面が見る人の方を向くように方位角を選びます。組み立て後と分解後の両方の状態が投影範囲に収まるようにします。

7. 静的なジオメトリを一度だけ作成します。各パーツを深度キー付きの SVG グループにします。移動するパーツには data-live フックを付けます。references/geometry.md を参照してください。

8. 平行移動でアニメーションさせます。パーツを動かすときは transform のみを変更します。ロッドが長くなる場合など、形状が変わるときに限りパスを再構築します。

9. 奥から手前に描画します。深度キーに現在のオフセットの深度を加えた値でグループを並べ替えます。並び順が変わるときだけ DOM を並べ替えます。

10. 色とインクで描画します。各素材にはフラットな色調を 3 種類使い、主要な本体には太いインクのシルエットを付けます。また各本体は、作業台に短く平坦な暖色系グレーの影を落とします。アクティブなパーツとそのピル型ラベルには、アクセントカラーを 1 色だけ使います。references/colour-and-ink.md を参照してください。

11. モデルを変更するコントロールを追加します。実行、ステップ、破損、修理、リセット、設定スイッチはすべて、実際の simulate 実行に作用します。設定を URL に書き込みます。references/live.md を参照してください。

12. ヘッドレスブラウザーでページを検証します。デスクトップとスマートフォンの幅で、両方のテーマのスクリーンショットを撮影します。4 倍のクローズアップ、線端の確認、コンソールエラーがゼロのシナリオ全体の確認、コンタクトシートを追加します。references/verify.md を参照してください。

ルール

真実性：

• 状態モデルを唯一の信頼できる情報源とします。動き、数値表示、トレースライン、結果のテキストはすべて、状態モデルのイベントから生成します。
• 同じ設定で simulate を実行すると、同じイベントが返されます。すべての設定の組み合わせでこれを証明するテストを用意します。
• 実在するモデル、実在するサービス、実際の指標を装ってはいけません。スクリプト化された部分がある場合は、ページの文面に「固定スクリプト」と記載します。
• シミュレーションの所要時間を表示するページには、「これはシミュレーションです。」で始まり、時間は固定のコストであって測定値ではないと説明する文を表示します。
• モデルでは実際の算術演算を行います。テストでは、ページに表示される数値と完全に一致することを検証します。

ジオメトリ：

• すべての座標はワールド単位です。ピクセルを使うのは投影時のみです。
• 仰角は30度とします。方位角はページ全体で1つの固定値を使います。リファレンスページでは60度を使います。
• ソリッドには kit/ink.mjs の inkSolid を使います。素材ごとに3段階のフラットな色調、インクの輪郭線、各本体を囲む太めのシルエット線を付けます。
• すべての線は、ソリッドまたは別の線で終端させます。意図的に端を浮かせる線には、data-free="start"、"end" または "" を設定します。
• 各ステーションには、作業部分につながるリーダー線付きのピル型ラベルを付けます。CACHE や VERIFIER のように、概念を表す語は大文字にします。ページにはラベル切り替えスイッチを設け、?labels=0 に対応させます。
• ステータスライトは、モデルが各ステーションに割り当てた状態を示します。完了時は緑、失敗時または未完了箇所が残った場合は赤にします。
• ガラスカバーは、ステーション内部を見せます。薄い色を付け、1本または2本の筋を入れます。
• 別の部品に載っている部品には深度バイアスを設定し、支える部品より後に描画されるようにします。

動き：

• 移動する部品が変更するのは transform のみです。形状が変わるパスは、可能な場合はキャッシュ済みの結果から再構築します。
• 1拍の長さは0.1～1.3秒です。移動距離が長いほど、移動時間も長くします。
• 分解アニメーションには、剛性64、減衰14.2、アセンブリごとに0.04秒ずらすスプリングを使います。
• フレーム時間が長くても拍を飛ばさないよう、フレーム間隔を1/20秒に制限します。
• モーション低減が有効な場合、実行速度を40倍にし、分解アニメーションは終了位置に即座に移動します。
• ステージが画面外にある場合、および動いているものがない場合は、アニメーションループを停止します。

ページ：

• デスクトップ幅では、ツールバー、ステージ、数値表示を 100svh 内に収め、作業台が1画面に表示されるようにします。
• スマートフォン幅ではページを縦に並べ、横スクロールが発生しないようにします。
• ボタンの高さは44 px以上にします。ステージをフォーカス可能にし、実行、ステップ、分解、破損、修復に対応するキーを用意します。
• SVG に role="img" と、すべてのステーションの名前を示す aria-label を設定します。
• 実行終了時に結果を通知する aria-live="polite" 領域を設けます。

完了前の確認事項

• 1文で説明する装置の概要が、ページの文面またはビルドノートに記載されている。
• 部品数が承認済みの段階と一致している。
• すべての設定の組み合わせを網羅するテストを含め、モデルのテストが通る。
• ページがビルドスクリプトの出力になっている。再ビルドしても差分が発生しない。
• 各設定コントロールが simulate を呼び出し、URL を更新する。
• ? パラメーター付きの URL を開くと、同じ設定が復元される。
• どの時点でもアクセントカラーが1色だけ表示され、アクティブな部品に追従する。
• すべてのステーションに、ライトテーマとダークテーマの両方、およびスマートフォン幅で読みやすいピル型ラベルが表示される。ピルが移動する部品や別のピルに重ならない。
• 揺れのスライダー、カラースウォッチ、ラベル切り替えスイッチが機能し、?labels=0 ではラベルがオフの状態で始まる。
• 図の下に「大事なポイント」を簡潔に説明する一文がある。
• 線の終端チェックで、浮いた端がゼロと報告される。
• シナリオの一括テストで、すべての設定を最後まで実行でき、コンソールエラーがゼロである。
• ライトテーマとダークテーマのデスクトップおよびスマートフォンのスクリーンショットで、表示の欠けや横スクロールがない。
• 分解後の位置がステージ内に収まっている。
• シミュレーションについての説明文がページにある。

ファイル

• references/concept.md：機械の着想、1文テスト、コンセプトのマッピング、サイズ設定。
• references/state-model.md：モデルの契約、イベントの形式、テスト、URL の状態。
• references/geometry.md：単位、カメラ、パーツ一覧、キット関数、シェーディング、奥行きキー、ラベル。
• references/colour-and-ink.md：マテリアル、トーン、インクの太さ、キャストシャドウ、ガラス、ステータスライト、ピルラベル、揺れ、ダークテーマ。
• references/live.md：ビートのタイムライン、描画ループ、ソート、アクセント、コントロール、アクセシビリティ、レイアウト。
• references/verify.md：スクリプトを使ったヘッドレス検証ループ。
• templates/model.mjs、templates/model.test.mjs、templates/build.mjs、templates/live.js：動作するキャッシュマシン。node templates/build.mjs を実行すると、templates/out.html が書き出されます。モデルテストを実行するには、node --test templates/model.test.mjs を実行します。
• kit/iso-kit.mjs、kit/lathe.mjs、kit/tube.mjs：投影、ソリッド、旋盤加工ボディ、チューブ、ベース CSS。キットとともに kit/LICENSE を保持してください。
• kit/ink.mjs：カラーとインクのレイヤー。inkSolid、silhouetteSvg、castShadowSvg、glassSvg、pillSvg、wobbleFilter、PALETTES、INK_CSS が含まれています。

AI Engineering from Scratch リポジトリ内の scripts/decompiler-machine/ と site/test_decompiler_machine.js も参照してください。カラーとインクのスタイルによるヒーロービルド一式を確認できます。また、以前のグレーのスタイルについては scripts/agent-machine/ を参照してください。