dynamic-archify

Dynami-carchify Skill

インライン SVG、テーマの切り替え機能、組み込みの画像／SVG エクスポートメニューを備えた、プロフェッショナルな技術図を自己完結型の HTML ファイルとして作成します。

すべての図に、ダーク／ライトテーマの切り替え機能（localStorage に保存され、prefers-color-scheme を尊重）、エクスポートメニュー（PNG をクリップボードにコピー、最大 4× 解像度でネイティブにラスタライズした PNG／JPEG／WebP をダウンロード、埋め込み先の prefers-color-scheme に従うデュアルテーマ SVGをダウンロード — GitHub の README に最適）、および両方のテーマで一貫性を保つCSS 変数によるカラーシステムが備わっています。

セットアップ（レンダラーモードのみ、初回のみ）

4 種類の型付きレンダラーは、ajv を使って JSON をスキーマに照らして検証します。このスキルのフォルダーから実行してください。

npm install

これがなくてもレンダラーは実行されますが、警告を表示してスキーマ検証をスキップし、独自のレイアウトチェックは行います。生成される HTML に依存関係はありません。依存関係があるのはレンダラーのみです。

シェルにまったくアクセスできない場合（たとえば、このスキルがプロジェクトナレッジとして追加された場合）は、すべてのリクエストでアーキテクチャモードを使用してください。以下のデザインシステムに従って assets/template.html に SVG を手作業で配置し、納品前にセルフレビューチェックリストを実行します。

図の種類を選ぶ

種類	用途	方法
architecture	システムコンポーネント、クラウドリソース、サービス、セキュリティ境界、インフラストラクチャ	renderers/architecture/render-architecture.mjs + JSON（またはレンダラーを実行できない場合は SVG を手作業で配置）
workflow	技術的なフロー、承認ゲート、ツール呼び出し、ランブック、CI/CD、インシデント対応	renderers/workflow/render-workflow.mjs + JSON
sequence	API 呼び出しチェーン、リクエストのライフサイクル、キャッシュのフォールバック、非同期トレース、戻り経路	renderers/sequence/render-sequence.mjs + JSON
dataflow	パイプライン、ETL/ELT、PII の分離、リネージ、データウェアハウスとの同期、コンシューマー	renderers/dataflow/render-dataflow.mjs + JSON
lifecycle	ステートマシン、ステータス遷移、待機状態、リトライ、終端状態	renderers/lifecycle/render-lifecycle.mjs + JSON

トリガーフレーズ：「architecture/system/cloud diagram」→ architecture（明らかにプロセス指向の場合を除く）。「workflow/flow/process/runbook/approval/CI-CD/incident」→ workflow。「sequence/interaction/call chain/who calls whom」→ sequence。「data flow/pipeline/ETL/lineage/PII/governance」→ dataflow。「state/status/lifecycle/state machine/retry/terminal」→ lifecycle。

入力方言としての Mermaid

ユーザーが Mermaid コードを貼り付けた場合、機械的にレンダリングしたり解析したりしないでください。構造を読み取り、対応する archify モードで最初からレイアウトを組み立ててください。

Mermaid	Archify モード	マッピング
flowchart / graph	workflow（コンポーネントマップの場合は architecture）	subgraph → レーンまたは領域の境界。ノード形状 {}（ひし形）→ 判断ノード／セキュリティノード。--> ラベル → エッジラベル（控えめに使用）。classDef／style → 最も近い意味タイプ
sequenceDiagram	sequence	participant → 参加者（名前から意味的な type を選択）。->> → メッセージ、-->> → return バリアント。Note → メッセージの note。rect ブロック → セグメント
stateDiagram	lifecycle	状態 → 状態（名前から start／active／waiting／success／failure を選択）。[*] の開始／終了 → start タイプ／terminal レーン。遷移ラベル → イベント形式のラベル

Mermaid のスタイル指定は破棄し、トポロジーと意味のみを残します。グループ分け、レーンの順序、強調する要素は自分で選んでください。その判断こそが成果物です。

レンダラーモード（workflow / sequence / dataflow / lifecycle）

4つのモードはすべて、同じ手順に従います。

1. 最初に読む：スキーマ（schemas/<type>.schema.json）と、完成した作例（examples/*.{workflow,sequence,dataflow,lifecycle}.json）を読みます。フィールドの形式を推測するのではなく、作例のパターンをそのまま使ってください。
2. <name>.<type>.json を作成します。
3. レンダリングします：node renderers/<type>/render-<type>.mjs <input>.json <output>.html（パスはこのスキルのフォルダーからの相対パスです）。
4. 失敗した場合、エラーにはJSONのパスまたは修正方法（しきい値、有効な範囲、変更する設定）が示されます。JSONを修正して再実行してください。レンダラーは編集しないでください。

スキーマ違反があると、/nodes/3 (id/label: "router") must NOT have additional properties のように、パスを先頭に付けたメッセージが表示され、終了コードが0以外になります。レンダラーはさらに、レイアウト上の問題（ノード／状態の重なり（レーンをまたぐ場合を含む）、ノードや他のラベルと衝突するラベル、ノードより幅の広いラベル、範囲外の列／行、短すぎるエッジ、viewBoxの外側にある凡例）も即座に検出して失敗します。CJKテキストの幅は自動的に2倍として計測されます。

Workflow

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": { "title": "Release Workflow", "subtitle": "PR to production", "output": "release.html" },
  "lanes": [ { "id": "dev", "label": "Developer" }, { "id": "ci", "label": "CI" } ],
  "nodes": [
    { "id": "pr", "lane": "dev", "col": 0, "type": "frontend", "label": "Open PR", "sublabel": "feature branch" },
    { "id": "build", "lane": "ci", "col": 1, "type": "backend", "label": "Build", "sublabel": "lint + test", "tag": "blocking" }
  ],
  "edges": [
    { "from": "pr", "to": "build", "label": "webhook", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" }
  ],
  "cards": []
}

レイアウトの上限：列は6つ（col は0～5）で、x座標は固定です（[88, 220, 300, 430, 500, 625]）。列1↔2および3↔4の間隔はわずか70～80pxのため、同じレーンの隣接する列にデフォルト幅（92px）のノードを配置すると重なります。列を1つ飛ばすか、width を小さくしてください。レーンのコンテンツ幅は640pxです。レンダラーがレーン数に応じて高さを自動調整するため、meta.viewBox は省略してください。エッジの経路は、straight、drop（レーン間で曲げます。bias は0～1で曲げる位置を指定します）、outside-right、return-left、bottom-channel、up-channel、または明示的な via ポイントから選べます。隣接するステップ間のエッジにはラベルを付けず、レーン間の遷移、承認、非同期書き込み、戻りのラベルに限定してください。

Sequence

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Cache Miss Request", "subtitle": "auth and cache fallback", "output": "cache-miss.html" },
  "participants": [
    { "id": "web", "type": "frontend", "label": "Web App", "sublabel": "React UI" },
    { "id": "api", "type": "backend", "label": "API", "sublabel": "handler" }
  ],
  "segments": [ { "from": 160, "to": 320, "label": "01 / AUTH" } ],
  "messages": [
    { "from": "web", "to": "api", "y": 200, "label": "GET /data", "variant": "emphasis" },
    { "from": "api", "to": "web", "y": 290, "label": "200 JSON", "variant": "return" }
  ],
  "activations": [ { "participant": "api", "from": 190, "to": 300, "type": "backend" } ],
  "cards": []
}

レイアウトの上限：参加者は x = 62 + index×108 の位置に配置されるため、幅920のviewBoxに収まるのは最大8人です。メッセージの y は [160, viewBox_height − 83] の範囲内にしてください。水平方向のスペースを共有するメッセージには、垂直方向に28px以上の間隔が必要です。矢印の水平距離は60px以上必要です。segments[].from/to と activations[].from/to は、参加者IDではなく**y座標（ピクセル）**です。meta.viewBox を高くすると（デフォルトは [920, 760]）、タイムラインに余裕が生まれます。ラベルは短くしてください（「GET /path」、「verify JWT」、「cache miss」、「200 JSON」）。

Dataflow

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "meta": { "title": "Product Analytics", "subtitle": "events to consumers", "output": "analytics.html" },
  "stages": [ { "label": "Sources" }, { "label": "Ingest" }, { "label": "Store" } ],
  "nodes": [
    { "id": "web", "type": "frontend", "label": "Web App", "stage": 0, "row": 0, "sublabel": "clickstream" },
    { "id": "kafka", "type": "messagebus", "label": "Kafka", "stage": 1, "row": 0, "tag": "accepted events" }
  ],
  "flows": [
    { "from": "web", "to": "kafka", "label": "events", "classification": "PII touch", "variant": "emphasis" }
  ],
  "cards": []
}

レイアウトの上限：ステージは2～5個で、x = 100 + stage×215 の位置に配置されます。行は5つ（row は0～4）で、y座標は [128, 242, 356, 470, 584] です。ノードのデフォルトサイズは112×58です。デフォルトのviewBoxは [940, 720] です。フローには、アセット名のようなラベルが必須です（「clickstream」、「identity map」、「feature vectors」など）。機密性は classification に記載してください（「PII touch」、「approved only」、「non-PII」など）。バリエーションは、emphasis が主要経路、security がPII／ポリシー／同意、dashed が非同期／バッチを表します。

Lifecycle

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Agent Run Lifecycle", "subtitle": "states and terminal outcomes", "output": "agent-run.html" },
  "lanes": [
    { "id": "main", "label": "Lifecycle phases" },
    { "id": "waiting", "label": "Interruptions" },
    { "id": "terminal", "label": "Terminal exits" }
  ],
  "states": [
    { "id": "queued", "type": "start", "label": "Queued", "lane": "main", "col": 0, "step": "01" },
    { "id": "running", "type": "active", "label": "Executing", "lane": "main", "col": 2, "step": "02" },
    { "id": "approval", "type": "waiting", "label": "Needs Approval", "lane": "waiting", "col": 0 },
    { "id": "done", "type": "success", "label": "Completed", "lane": "terminal", "col": 2 }
  ],
  "transitions": [
    { "from": "queued", "to": "running", "variant": "emphasis" },
    { "from": "running", "to": "approval", "label": "needs approval", "variant": "security", "fromSide": "bottom", "toSide": "right" },
    { "from": "running", "to": "done", "label": "success", "variant": "emphasis", "fromSide": "bottom", "toSide": "top" }
  ],
  "cards": []
}

レイアウトの上限 — レーンIDは意味に基づいて予約されています：main は必須で、上部のフェーズ帯（列0～4）に対応します。terminal は下部の結果帯（列0～2）に対応します。それ以外のすべてのレーンIDは、中央のイベント帯（列0～2）を共有します。同じ帯の状態を分けるには、異なる col または yOffset を指定してください。帯のヘッダーには、レーンのラベルが表示されます。デフォルトのviewBoxは [980, 660] です。遷移ラベルはイベントを表す短いものにし、数を絞ってください（「retry」、「timeout」、「cancel」など）。ラベルの多い矢印よりも、状態の tag、step 番号、概要カードを使ってください。終了状態を明確にするため、terminal レーンに配置してください。

モードごとの詳しいガイダンス

各レンダラーには、デザインに関するガイド（経路プリセット、意味タイプ、ストーリー作成の指針）をすべて記載したREADMEがあります：renderers/workflow/README.md、renderers/sequence/README.md、renderers/dataflow/README.md、renderers/lifecycle/README.md。セッション中にそのモードで初めて図を作成する前に、該当するREADMEを読んでください。

アーキテクチャモード

アーキテクチャモードにも、ほかのモードと同じ「読み込み・スキーマ検証・描画」のループがあります。こちらを優先してください。レンダラーを実行できない場合は、SVG を手動で配置する方法が代替手段です。

{
  "schema_version": 1,
  "diagram_type": "architecture",
  "meta": { "title": "Sample Web App", "subtitle": "3-tier SaaS on AWS", "output": "web-app.html" },
  "components": [
    { "id": "users", "type": "external", "label": "Users", "sublabel": "Browser", "pos": [40, 300] },
    { "id": "api", "type": "backend", "label": "API Server", "sublabel": "FastAPI :8000", "pos": [460, 300] },
    { "id": "db", "type": "database", "label": "PostgreSQL", "sublabel": ":5432", "pos": [680, 300] }
  ],
  "boundaries": [
    { "kind": "region", "label": "AWS us-west-2", "wraps": ["api", "db"] }
  ],
  "connections": [
    { "from": "users", "to": "api", "label": "HTTPS", "variant": "emphasis" },
    { "from": "api", "to": "db", "label": "SQL" }
  ],
  "cards": []
}

描画するには、node renderers/architecture/render-architecture.mjs <input>.json <output>.html を実行します。

レンダラーが、以前は手作業で調整していた機械的な作業を行います。そのため、座標と意味を決めるだけで済みます。

• 自由な座標指定 — pos: [x, y] はコンポーネントの左上を示します。size: [w, h] のデフォルト値は [120, 60] です。型指定のあるモードと異なり、レーン／ステージのグリッドはありません。非対称な配置も自由に指定できます。meta.viewBox は省略可能です（コンポーネントと凡例の行に合わせて自動調整されます）。
• wraps による境界 — region（アンバーの破線）または security-group（ローズの破線）が囲むコンポーネント ID を列挙します。レンダラーが適切な 30／50 のパディングを含むボックスを自動計算します。境界の寸法を手計算する必要はもうありません。
• 接続はエッジと同じようにルーティングされます（variant、fromSide／toSide、route: straight|orthogonal-h|orthogonal-v|auto、via、labelDx/labelDy/labelAt）。ラベル付きの垂直接続では、labelDy を使ってラベルを隙間に配置してください（ボックスに重なる場合はバリデーターが知らせます）。
• レンダラーは、2 つの長方形を使う c-mask パターンを自動出力し、ボックスより先に矢印を描画して（z オーダー）、使用したコンポーネントの型から凡例を作成します。また、コンポーネントの重なり、キャンバス外のコンポーネント／境界、不明な wraps／接続 ID、ラベルとコンポーネントの衝突、有限でない座標がある場合は即座にエラーになります。これにより、ほかの 4 つのモードと同じ信頼性を実現します。

レンダラーが使えない場合の手動配置

Node／ajv を実行できない場合は、assets/template.html をコピーし、SVG を手動で配置してください。テンプレート内の完成済み図と examples/web-app.html を参考に座標指定の慣例を確認し、以下のデザインシステムに従って、納品前にセルフレビューチェックリストを実行してください。

最重要ルール：インラインカラーではなく CSS クラスを使う

テーマの切り替えは CSS カスタムプロパティを切り替えて行われます。fill="rgba(...)" や stroke="#22d3ee" のように色をハードコードすると、テーマを変更しても更新されません。必ずクラスシステムを使ってください。

<rect x="X" y="Y" width="W" height="H" rx="6" class="c-mask"/>
<rect x="X" y="Y" width="W" height="H" rx="6" class="c-backend" stroke-width="1.5"/>
<text x="CX" y="CY" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">API Server</text>
<text x="CX" y="CY+16" class="t-muted" font-size="9" text-anchor="middle">FastAPI :8000</text>

デザインシステム

コンポーネントの塗りつぶしには、c-frontend（クライアント／UI）、c-backend（サービス／API）、c-database（ストア／キャッシュ）、c-cloud（マネージドインフラ）、c-security（認証／シークレット）、c-messagebus（Kafka／キュー）、c-external（サードパーティ）を使います。テキストのアクセントには t-<same> と、ニュートラルカラーの t-primary／t-muted／t-dim を使います。矢印には a-default、a-emphasis（ホットパス）、a-security（破線）、a-dashed（非同期）を使います。必ず stroke-width を設定し、対応するクラスと marker-end="url(#arrowhead[-variant])" を組み合わせてください。境界には c-security-group（ローズの破線）、c-region（アンバーの破線）、c-lane（スイムレーン）を使います。

タイポグラフィは SVG ルートから JetBrains Mono を継承します。サイズは、コンポーネント名が 11～12px、補助ラベルが 9px、注釈が 8px、小さなラベルが 7px です。

レイアウトの必須ルール

• すべての箇所で 2 つの長方形パターンを使う：不透明な c-mask の長方形を先に配置し、その上にスタイル付きの c-<type> の長方形を重ねます。半透明の塗りつぶしでは、矢印が透けてしまいます。
• コンポーネントより先に矢印を配置する：ドキュメント内の順序どおりに SVG が描画されるため、矢印はボックスの背面に置く必要があります。
• 垂直方向の間隔：コンポーネント間には 40px 以上の間隔を設けます。インラインコネクター（メッセージバスなど、高さ 20px）は隙間に配置し、ボックスと重ならないようにします。
• 境界のパディング：境界の y = 内側の y − 30、境界の height = 内側の height + 50、ラベルのベースラインは境界上端から 18px 下にします。
• 凡例の配置：すべての境界ボックスの外側、最も低い境界ボックスから 20px 以上下に配置します。必要に応じて viewBox を広げてください。

セルフレビューチェックリスト（納品前に実行）

1. SVG 内で grep -E 'fill="(#|rgb)|stroke="(#|rgb)' out.html を実行し、テンプレート自体の defs 以外に何も返されないことを確認します（最重要ルール）。
2. すべての c-<type> の長方形の直前に、ジオメトリが同一の c-mask の長方形があることを確認します。
3. すべての <line>／<path> の矢印が、ドキュメント内の順序で、すべてのコンポーネントの長方形より前にあることを確認します。

エクスポートオプション

Archify は、静的図とアニメーション図の両方で複数のエクスポート形式に対応しています。

静的エクスポート

• PNG — 高解像度のラスター画像（元の解像度の4倍）
• JPEG — 背景付きの圧縮ラスター画像
• WebP — 透過に対応した最新の圧縮形式
• SVG — 自動テーマ対応のベクター形式
• クリップボードにコピー — 貼り付け用のPNGをすばやくコピー

アニメーション付きエクスポート（流れるアニメーションを含む図向け）

• GIF — 流れるアニメーションを記録したアニメーションGIF

  • クライアント側のエンコードにgif.jsライブラリを使用します
  • エクスポート前にユーザー設定可能な設定ダイアログが表示されます：
    • 解像度：1x / 2x（デフォルト） / 3x / 4x
    • フレームレート：10 / 15 / 20（デフォルト） / 24 / 30 / 60 fps
    • 長さ：2 / 3（デフォルト） / 5 / 8秒
  • フレーム数のライブプレビューが表示されます（例：「60 frames · 20 fps · 3s」）
  • ファイルサイズ：設定や複雑さに応じて通常1～10 MB

• WebM — 高品質な動画形式

  • ネイティブの動画キャプチャにMediaRecorder APIを使用します
  • GIFと同じユーザー設定可能な設定ダイアログを使用します
  • GIFより高画質で、ファイルサイズも小さくなります
  • Chrome、Firefox、Edgeでサポートされています

エクスポートのヒント

GIFの品質を高めるには：

1. ダークテーマを使用します（アニメーションのコントラストが高まります）
2. 図のサイズを適度に保ちます（図が大きいほどGIFファイルも大きくなります）
3. 「GIF exported successfully!」というトーストメッセージが表示されるまで待ちます

WebM動画の場合：

1. ChromeとFirefoxで最適に動作します
2. SafariではMediaRecorderのサポートが限定的です
3. WebMファイルの再生にはVLCまたはブラウザーを使用します

ファイルサイズの最適化：

• GIF：一般的な図で1～5 MB
• WebM：同じ内容で0.5～2 MB
• 共有する場合：WebMをおすすめします（画質とサイズのバランスに優れています）

流れるアニメーション効果

すべての図に、接続パス上の自動的に流れるアニメーション効果が含まれるようになりました。この機能はレンダラーとテンプレートに組み込まれているため、追加の設定は必要ありません。

アニメーションの動作

CSSアニメーション（stroke-dasharrayによるフロー）：

• a-emphasis：パルス効果付きの高速フロー（0.8秒周期）、3pxのグロー
• a-default：中速フロー（1.2秒周期）、2pxのグロー
• a-dashed：安定したフロー（1秒周期）
• a-security：安定したフロー（1秒周期）

SVGアニメーション（移動するドット）：

• 各接続パスに、パスに沿って流れるアニメーション付きのドットがあります
• ドットのプロパティはバリアントによって異なります：
  • emphasis：半径3px、高い不透明度（0.9）、継続時間2～3.5秒
  • default：半径2.5px、中程度の不透明度（0.8）、継続時間2.5～3.7秒
  • dashed：半径2px、低めの不透明度（0.7）、継続時間2.2～3.4秒
  • security：半径2px、低めの不透明度（0.7）、継続時間2.5～3.5秒

フロー方向のルール

重要な制約：流れるアニメーションは、始点（矢印なし）から終点（矢印あり）へ流れる必要があります。

レンダラーが自動的に処理します：

• すべてのパスで矢印の先端にmarker-endを使用します
• アニメーションの方向はパスの始点から終点へ向かいます
• ドットは矢印のないコンポーネントから、矢印のあるコンポーネントへ移動します

視覚効果

1. ストロークの破線アニメーション：パスに沿って破線が流れるように見せます
2. 移動するドット：アニメーション付きの円がパスの軌道に沿って移動します
3. グロー効果：強調パスには、より強いドロップシャドウフィルターが適用されます
4. パルス効果：強調パスの不透明度がわずかに脈動します

カスタマイズ

流れる効果は、接続／エッジ／フロー／遷移のvariantプロパティに基づいて自動的に適用されます：

{
  "from": "source",
  "to": "target",
  "variant": "emphasis",  // Fast flow with glow
  "label": "data flow"
}

利用可能なバリアント：

• emphasis — 主要なデータフロー。最速のアニメーションと最も強いグロー
• default — 標準的な接続。中速のアニメーション
• dashed — 非同期／バッチ処理。安定したフロー
• security — セキュリティ／ポリシーのパス。安定したフロー

技術的な実装

流れるようなエフェクトは、次の2つのレイヤーで実装されています。

1. CSS レイヤー（assets/template.html）：

   • @keyframes flowDash — stroke-dashoffset をアニメーションさせ、破線を流します
   • @keyframes flowPulse — 不透明度をアニメーションさせ、強調するように脈動させます
   • .a-emphasis、.a-default、.a-dashed、.a-security クラスを使用して適用します

2. SVG レイヤー（レンダラー）：

   • <circle> のドットに <animateMotion> 要素を使用します
   • 接続のルーティングからパスデータを取得します
   • 視覚的な変化を持たせるため、バリアントとインデックスに応じて時間を変えます

下位互換性

• アニメーションのない既存の図も引き続き動作します
• アニメーションは追加のみで、互換性を損なう変更はありません
• テーマ切り替えとエクスポート機能はすべて引き続き完全に機能します

4. すべての SVG 要素について y + height の最大値を計算します。viewBox の高さはこの値を 20px 以上上回る必要があります。x/width についても同様です。
5. 凡例の y は、すべての境界の y + height より下に配置します。
6. .toolbar、<script> ブロック、:root / [data-theme] CSS には手を加えません。これらはテーマ切り替えとエクスポートメニューそのものです。

出力

単一の自己完結型 .html ファイルです。CSS が埋め込まれています（Google Fonts は非同期で読み込まれ、オフライン時はシステムの等幅フォントにフォールバックします）。インライン SVG、アニメーション GIF のエクスポート用に埋め込まれた gif.js ライブラリとワーカー、テーマ・エクスポート・アニメーション用の約60KBの埋め込み JavaScript を含みます。最新のブラウザーであれば、どれでも直接レンダリングできます。ラスター画像へのエクスポートは、viewBox の最大4倍の解像度でネイティブにレンダリングされます（大きな図ではキャンバスの制限を超えないよう、3倍／2倍に下げます）。SVG のダウンロードは、ホストの prefers-color-scheme に従う、両テーマ対応の自己完結型です（svg[data-theme="..."] で手動指定できます）。アニメーション GIF/WebM へのエクスポートでは、ユーザーが解像度、フレームレート、再生時間を設定して、流れるアニメーションをキャプチャできます。