Isometric SVG animation
1つのスクリプト(node build.mjs)がすべての形状を計画単位(plan units) で配置し、等角投影に変換し、自己完結型の diagram.svg(CSSキーフレームを内包し、通常の <img> として動作)と preview.html(同じSVGをインライン化してウィンドウにスケーリング)を出力します。手描きは一切不要です。すべての修正はコード変更とリビルドで行います。
スクリプトを作成する前に、references/generator.md をお読みください。このファイルには、セクションと、投影、カード、地面テキスト、ルート、キーフレーム、プラットフォーム、アセンブリに関するコアコードが含まれています。
手順
- ストーリー(Story)。 システムのドキュメントを読み、図のストーリーを1行で記述します。何が入力され、何が処理し、何が処理を駆動し、何が出力されるか。フローは左下から右上に読まれます。ラインの各段階が1~3語で名前を付けられるノードになり、ユーザーがそのラインに同意した時点で完了です。
- ブリーフ(Brief)。 雰囲気(線の太さ、密度、プラットフォームのスタイル)を決めるための参照画像を1枚入手します。ユーザーが持っていない場合は、references/examples.md の図を表示して選んでもらいます。テーマ、アスペクト比(1.6:1 はブラウザウィンドウ1つに収まる)、SVGの保存場所を決めます。これら4つがスクリプトのヘッダーコメントに記述された時点で完了です。
- 静的ビルド(Static build)。 プラットフォーム、ノード、ルート、ラベル。まだ動きは付けません。ビルドの監査(audit)で重なりや狭い角がないことが確認され、ユーザーがレイアウトのスクリーンショットに承認した時点で完了です。
- モーション(Motion)。 ループを追加します。1回のループでストーリーが順番に1回再生され、動きを減らした設定(reduced motion)で完成状態が表示された時点で完了です。
- エクスポート(Export)。 下記の「エクスポート」を参照。
各レビューラウンドでは、ユーザーの指摘を1つずつ取り上げ、何かを変更する前に質問に答え、現在のビルドを versions/ にコピーしてから大きな変更を行い、スクリーンショットを添えて返信します。ユーザーが名前やアイコンを選んでいる場合は、オプションを横に並べて表示します。
原則
コンテンツ
- 1つのフロー、最小限の詳細。各ノードは実際に行うことに基づいて名前が付けられます。名前について異論がある場合は、どちらが正確か、その理由を述べた上で、ユーザーに選んでもらいます。
- すべてのラベルは、第三者が見てもそれだけで理解できるものにします。説明が必要なラベルは書き直すか削除します。
- 積み重ねられたプレートは、本当に積み重ねられるもの(レポートのページなど)にのみ使用します。それ以外のノードはすべて単一のカードです。
- 正直な副経路(ある段階をスキップする入力など)は、たとえスペースを取っても描画し続けます。
- 外部システムは、内部のものと同じ塗りつぶしのプラットフォーム上に配置します。破線のエッジだけで外部であることを示します。
- 緩い入力は地面に直接置き、その下にプラットフォームは置きません。
幾何学
- 計画単位(Plan units) をすべての場所で使用します。
aはフロー方向(画面上右上)、bはフロー横方向(画面右下)、zは高さ方向です。位置、サイズ、間隔、ルートはすべて計画単位で指定します。画面ピクセルは投影内部にのみ存在します。 - カードは上面にサイドバンド(上面と下面の輪郭のハル(hull))を付けたもので、外側の輪郭には1本のストロークを設定し、面と厚みの境界には線を入れません。プラットフォームは、上面がグリッド上にあるため、代わりに上面にストロークを設定します。
- すべてのカードとモジュールピルで厚みは1つだけです。名前ピルは厚みのない平らな状態にします。
- レイヤー(地面、プラットフォーム、ワイヤー、オブジェクト、ラベル)ごとに、奥行き順に塗りつぶします。
テキスト
- すべてのラベルは地面平面上に配置し、ベースラインを
a方向に揃えます。グリフはビルド時にパスに変換されるため、SVGは<img>としてもどこでも同じようにレンダリングされ、フォントを読み込む必要がありません。 - サイズは1つの小さなテーブル(ピル、ラベル、小、キャプション、タイトル)から取得します。プラットフォームのタイトルは等幅の大文字でスペースを入れます。
レイアウト
- 地面グリッドは2単位間隔。プラットフォームのエッジは外側に向かってグリッド線にスナップします。プラットフォーム間および行間のギャップはセル全体の倍数です。共有のトランクラインは、ギャップの中央にあるグリッド線上を通ります。
- プラットフォームは自動的にサイズを決定します。すべてのノードとラベルがそのプラットフォームにフットプリントを登録し、プラットフォームはそのボックスに均一なパディングを加えたもので、グリッドにスナップします。同じ行のプラットフォームは、隣接するエッジを共有します。
- プラットフォームのタイトルは、左端からの距離と前端からの距離が等しくなる位置(キャピタル文字の基部から計測)に配置され、コンテンツに左揃えされます。
- グリッドはフレームのすべてのエッジを超えて広がり、フレームと同じアスペクトの楕円を通してフェードアウトするため、画像にハードエッジはありません。背景は透明です。
- ビルドごとに監査(audit) が出力されます。各プラットフォームの4つのマージン、プラットフォーム間のギャップ、ラベル×ラベルおよびラベル×カードの重なり、半径に対して狭すぎる角。何かを表示する前に必ず確認してください。
線
- すべての接続は1つの連続したパスで、直交し、角は一定半径の4分の1円とします。これにより、ルートが同じ区間を共有する場合は正確に共有し、分岐はトランクから接線方向に離れます。ルートを先に描き、その上にノードを描きます。結果には、スタブ、フォーク、ギャップは生じません。
- 線種はパターンで区別します。実線はフロー、破線は外部レール、丸点線は読み取り専用アクセスを表します。
トーン
- トーン(色調)は状態を表します。 ニュートラルカラーのみ(R = G = B)。薄い色=まだ到達していない、1段階濃い色=入力準備完了、最も濃い色=このラウンドで完了。アイコンと輪郭も同じルールに従うため、「なぜこれだけ濃いのか?」という質問には、状態が答えになります。最も濃いインクは中程度の濃いグレーで、純粋な黒や塗りつぶしの暗いブロックは使用しません。
- 線は非常に薄い色で始まり、光が通過した後にのみ濃くなります。
- 色は現在動作中 を意味します。カードは白のままで、ブランドグラデーションのかすかな色合いが下から透けて見え、周囲にかすかなグローが現れます。ライトは、全体像全体にフローに沿って配置された1つのグラデーションから色を取得します。
- あるフェーズ(たとえば、入力がピックアップされるなど)のアクセントカラーは、点灯中のみ表示され、その後は静止していたグレーに戻ります。
モーション
- SVGアニメーション:SVG内のCSSキーフレーム。スクリプトは使用せず、
<img>として再生します。動画のレンダリングは、要望があった場合のみ行います。 - 静止スタイルは完了したラウンドの状態です。キーフレームは、各ループを未実行の状態から開始します。そのため、動きを減らした設定と静的なエクスポートでは、完成した図が表示されます。
- 時間は幾何学から生まれます。 ライトは一定の画面速度(約400 px/s)で移動します。各到着時間は、開始時間 + ルート長 ÷ 速度 です。次のイベントはその到着時間にポーズを加えたものです。ノードを移動すると、タイムラインも追随します。キーフレームを書く前に、タイムライン全体とそれに伴うループ長を計算します。
- 1回のループでストーリーを1回表現します。入力が流れ込み、ドライバーが上から下に実行され、部品が集まり、出力が組み立てられ、エクスポート、ホールド、クリア、繰り返し。追跡できる程度に遅く(約20秒)。
- ライトは、よりソフトで広いハローを伴う短いダッシュをルートに沿って走らせたものです。ループがクリアされるまで、より暗いトレースが後ろに残ります。動作中のノードは数ピクセル持ち上がり、グローし、グラデーションの面をフラッシュします。
レンダリングコスト
<img> として表示される場合、実行中のアニメーションはブラウザにフレームごとに画像全体を再ラスタライズさせます。
- マスク、フィルター、グループは小さく保ちます。グリッドは独自のストロークグラデーションでフェードし、マスクは公開するパスにぴったりと沿います。
- 見えないものはすべて
visibility: hiddenにします(不透明度0やパスから外れたダッシュでも塗りつぶしは行われます)。 - 同一のキーフレームは1回だけ記述します。
エクスポート
- 静的PNG:動きを減らした設定(reduced motion)をエミュレートした状態でSVGドキュメント自体を開き、スクリーンショットを撮ります。
<img>内部ではエミュレーションはSVGに到達せず、代わりにループの最初のフレームがキャプチャされます。 - プレビューは、ユーザーがSVGを配置するまで、ユーザーのサイトの外部でローカルに提供されるスタンドアロンページに配置します。