stack-diagram

stack-diagram は何をしますか？

エンジニアリング図面スタイルのアーキテクチャ図を生成します。実際のロゴを白いタイル上に配置し、ラベル付きのグループボックス（クラウドベンダーのVPC図のようなもの）、等幅フォントのラベルを持つ直交矢印、そしてクールなグラフ用紙風の背景を使用します。情報源は1つの自己完結型HTMLファイルであり、PNG / TSX / アーティファクトはそれから派生します。

必要条件

• Python 3.9+（fetch_icons.py、build.py、share.py には標準ライブラリのみ必要）
• アイコンソース（svgl.app、raw.githubusercontent.com、cdn.jsdelivr.net、aws.amazon.com と d1.awsstatic.com（AWSアイコン用）、services.google.com（Google Cloudアイコン用）、learn.microsoft.com と arch-center.azureedge.net（Azureアイコン用）、および name=URL で指定されたブランド自身のサイトやリポジトリ）へのネットワークアクセス（アイコン取得時）
• render_png.py 用の Playwright + Chromium：pip install playwright && python3 -m playwright install --with-deps chromium

ワークフロー

1. コンテンツ（ノード、グループ、エッジ）を確定する
2. アイコンを取得する — scripts/fetch_icons.py
3. 座標を計画する — references/geometry.md を参照
4. assets/template.html からHTMLをビルドする — scripts/build.py
5. PNGをレンダリングして確認する 提供前に必ず行う
6. 要求されたフォーマットで提供する
7. オプションでパブリックギャラリーに共有する

ステップ1 — コンテンツ

ユーザーが提供するテクノロジー/サービスのリストから、以下を決定します：

• ノード：各テクノロジー = 1つのノード（名前 + 小文字の短い役割、例：http server、sqlite db）
• グループ：実行環境、ベンダー、リポジトリを共有するものの周りにボックスを描画します（例：クラウドプロバイダーのボックス内にランタイムボックス、ツール用のモノレポボックス）。1レベルまでのネストは許容されますが、それ以上は見づらくなります。グループラベルはブランド自身の大文字小文字を使用します（GitHub、npm）。テンプレートは記述されたとおりに表示します。
• エッジ、3種類：
  • アクセント色の実線 = 主要なリクエスト/データフロー（1つの連続したパスが最適）
  • ニュートラル実線 = 二次的な内部接続
  • ニュートラル破線 = 開発時/デプロイ時の関係（CI、gitフック、IaCデプロイ）

ユーザーがフラットなツールリストのみを提供した場合、ツールの性質から妥当なグループとフローを推測します。ツールがあいまいで図が誤ったものになる場合にのみ質問します。

ステップ2 — アイコン

python3 scripts/fetch_icons.py <icons-dir> tanstack hono drizzle "betterauth:better-auth" "orpc=https://orpc.unnoq.com/logo.webp"
python3 scripts/fetch_icons.py <icons-dir> "aws:aws/AWS-Cloud-logo" "vpc:aws/vpc" "fargate:aws/fargate" "s3:aws/s3"
python3 scripts/fetch_icons.py <icons-dir> "gcp:google-cloud" "run:gcp/cloud-run" "lb:gcp/load-balancing" "sql:gcp/cloud-sql"
python3 scripts/fetch_icons.py <icons-dir> "azure:azure/Azure-A" "app:azure/app-service" "vnet:azure/vnet" "sql:azure/sql-database"
python3 scripts/fetch_icons.py <icons-dir> "k8s:kubernetes" "ing:k8s/ingress" "svc:k8s/service" "deploy:k8s/deployment" "pod:k8s/pod"

指定形式：name（名前をスラグとして使用）、name:slug（異なるスラグ）、name=URL（明示的なURL）、name:aws/<Name>（公式AWSアイコン）、name:gcp/<Product>（公式Google Cloudアイコン）、name:azure/<Name>（公式Azureアイコン）、name:k8s/<Resource>（公式Kubernetesアイコン）。スクリプトは、svgl → devicon → gilbarbara/logos の順に試行し、ファイルと manifest.json を書き込み、塗りつぶしが白のアイコンをフラグ付けします。svgl（svgl.app）が最初に試行されるのは、TanStack、Better Auth、Honoなどの最新のデベロッパーブランドの公式マークを提供しているからです。ロゴにライト/ダークバージョンがある場合、ライトバージョンが <name> になります（タイルは両方のテーマで白）、ダークバージョンはグループラベル用に <name>_dark として保存されます。svglは完全なタイトルでのみマッチするため、ミスがあればスキップされます。また、そのAPIは wordmark バリアントも公開しています。広いグループラベルには便利ですが、タイルには決して使用しません。

メカニズムよりも重要なルール：

• ロゴの色を変更しないでください。 ユーザーは気づきます。ロゴが白すぎる、または明るすぎる場合は、塗りつぶしを変更する代わりに暗いタイル（tile dark クラス）に配置してください。マニフェストの white_fill フラグはヒューリスティックです。白い塗りつぶしはカラーマーク（tRPC、Ubuntu）の内部詳細である可能性があるため、暗いタイルを使用する前にSVGを確認してください。
• 公式マークのみを使用してください。 simple-iconsは意図的にソースに含まれていません。そのグリフは単色の再描画であり、ユーザーは一目で間違いだと指摘します。すべてのソースで見つからなかった場合（FAIL）、公式ファイルを見つけて name=URL として渡してください。プロジェクトのリポジトリ（ルート logo*.svg、docs/、assets/、public/）やそのサイト（/logo.svg、/favicon.svg、/images/logo.svg）を確認してください。一部のマークはリポジトリにのみ存在します（Lefthookのマークは evilmartians/lefthook のルートにある logo_sign.svg）。
• 抽象的な概念には絵文字ではなくピクトグラムを使用します。 「開発環境」、「cron」、「キュー」、「キャッシュ」、「webhookレシーバー」などのノードにはブランドがありません。Lucideラインアイコンを name:lucide/<icon> で使用してください（例：devenv:lucide/terminal、cron:lucide/clock；lucide.dev/icons で参照）。タイル内のテキストや絵文字は使用しないでください。
• ベンダーのサブプロダクト（Cloudflare D1/R2/KV...）には通常、個別のロゴはありません。タイルにベンダーロゴを再利用し、ノード名に区別を持たせてください（「Cloudflare D1」/「sqlite db」）。
• AWSはAWS独自のアイコンを使用します。 各サービスには1つあります。name:aws/<Name> で取得し、実行時にAWSの公式アイコンパッケージから読み取ります（例：lambda:aws/lambda、aws:aws/AWS-Cloud-logo、s3:aws/s3）。AWS- / Amazon- プレフィックスはオプションであり、一般的な略語は機能します（s3、sqs、sns、ses、ecs、eks、ecr、elb、alb、nlb、iam、kms、msk、vpc）。見つからない場合はすべての名前が表示されます。スラグ aws、amazonwebservices、aws-* は同じパッケージに解決され、パッケージにないものはサードパーティのコピーにフォールバックせずに FAIL になります。サービスの場合は常に aws/ プレフィックスを記述してください。dynamodb だけでもサードパーティのチェーンを通過します。パッケージと個別のアイコンファイルをリポジトリに含めないでください。AWSは図でのアイコン使用を許可していますが、再配布は確認されていません。
• AWSエリアはAWS自身の描画ルールに従います。 サービスアイコンは独自の四角形を持ち、明るい背景と暗い背景の両方で機能するため、tile bare を使用します。白いタイルはフレームを重複させるだけです。その内部の人物や汎用ノードは、AWSの汎用アイコン（user:aws/General-User；General-Users、General-Client、General-Internet、General-Server も同様）を tile bare res で使用し、テンプレートの lt/dk ペアを使用します。グループはテンプレートの group aws をAWS Cloudに使用し（ラベルに aws:aws/AWS-Cloud-logo）、region、az、vpc、private、public を残りの部分に使用します。角は四角、アウトラインのみ、ラベルはインク色、ベンダーの色合いはなし、コーナーに14pxではなく30pxのアイコンを配置します。VPC内では、パブリックサブネットとプライベートサブネットを、分割がわかっているか安全に推測できる場合に表示します（インターネットに面したロードバランサーはパブリック、アプリサーバーとデータベースはプライベート）。フラットなVPCはAWSの人々が最初に気づく点です。内部のエッジは1色と開いた矢印を使用します。<path class="aws" ... marker-end="url(#open)"/>、開発/デプロイには aws dash、ラベルにはプレーンな .el、凡例は不要です。ノード名は Amazon S3 / AWS Fargate とし、S3 / Fargate だけにしないでください。ALB のような短縮形は役割行に、完全な名前（Elastic Load Balancing）の下に配置します。名前は2行になる場合がありますが、Amazon / AWS は最初の単語の行に留めてください。プレフィックスの後で折り返す場合は、そのノードを広げてください（left:<centerX-76>px; width:152px）。
• Google CloudはGoogle独自のアイコンを使用します。 name:gcp/<Product> で取得し、実行時にGoogleの公式パッケージから読み取ります（例：run:gcp/cloud-run、lb:gcp/load-balancing、memorystore:gcp/memorystore）。コアプロダクトのみが独自のアイコンを持ちます（Cloud Run、Cloud SQL、Cloud Storage、BigQuery、GKE、Compute Engine、Vertex AIなど）。その他のプロダクトは、Googleのガイドに従ってカテゴリのアイコンを使用します。Cloud Load BalancingとCloud CDNはどちらもNetworkingを取得し、MemorystoreとFirestoreはどちらもDatabasesを取得します。プロダクト名を記述すると、スクリプトがアイコンを選択します。Cloud / Google プレフィックスはオプションであり、一部の短縮形は機能します（vpc、iam、kms、iap、gce、gcs）。見つからない場合はすべての名前が表示されます。gcp/storage はStorageカテゴリです。Cloud Storageは gcp/cloud-storage です。スラグ gcp-* と google-cloud-* は同じパッケージに解決され、パッケージにないものは、使用すべきでないとGoogleが述べている廃止された六角形アイコンであるサードパーティのコピーにフォールバックせずに FAIL になります。プロダクトの場合は常に gcp/ プレフィックスを記述してください。bigquery だけでもサードパーティのチェーンを通過します。gcp:google-cloud はグループラベル用のGoogle Cloudマークです。GeminiとFirebaseはパッケージに含まれていません。ベアの gemini と firebase を使用してください。パッケージと個別のアイコンファイルをリポジトリに含めないでください。Googleは図やドキュメントでのアイコン使用を許可していますが、再配布は確認されていません。
• Google Cloud図は通常のスタイルを維持し、Googleのグループを使用します。 Google自身の図（単色の青いパネル、水平方向のカード）は意図的にコピーしていません。アイコンは通常の白いタイルに配置され、エッジと凡例は通常通りです。グループはテンプレートの group gcp をGoogle Cloudに使用し（ラベルに gcp:google-cloud）、vpc、region、subnet、zone を使用します。VPCはグローバル、サブネットはリージョナルであるため、リージョンをVPC内に配置し、VPCをリージョン内に配置しないでください。外部ロードバランサー、Cloud Storage、Cloud RunなどのグローバルおよびサーバーレスサービスはVPCの外部に配置します。アイコンは共有されるため、プロダクトの完全な名前を常に記述し（LB ではなく Cloud Load Balancing）、名前が折り返されるノードを広げてください（left:<centerX-76>px; width:152px）。
• AzureはMicrosoft独自のアイコンを使用します。 各サービスには1つあります。name:azure/<Name> で取得し、実行時にMicrosoftの公式パッケージから読み取ります（例：app:azure/app-service、azure:azure/Azure-A、vault:azure/key-vault）。Azure- / Microsoft- プレフィックスと複数形の s はオプションであり、一般的な短縮形は機能します（aks、vm、vnet、nsg、waf、blob、cosmos、redis、postgres、functions、front-door、apim、ai-search）。見つからない場合はすべての名前が表示されます。スラグ azure、microsoft-azure、azure-* は同じパッケージに解決され、パッケージにないものはサードパーティのコピーにフォールバックせずに FAIL になります。サービスの場合は常に azure/ プレフィックスを記述してください。cosmos だけでもサードパーティのチェーンを通過します。Microsoft Entra IDは別のアイコンセットを持ちます。公式ファイルを name=URL として渡してください。Microsoftは、これらのアイコンをアーキテクチャ図、トレーニング資料、ドキュメントでのみ使用することを許可しています。アイコンを切り取ったり、反転、回転、変形したりしないでください。対応するMicrosoftサービスにのみ使用し、パッケージと個別のアイコンファイルをリポジトリに含めないでください。
• Azure図は通常のスタイルを維持し、Microsoftのグループ色を使用します。 Microsoft自身の図は意図的にコピーしていません。アイコンは通常の白いタイルに配置され、エッジと凡例は通常通りです。グループはテンプレートの group azure をAzureに使用し（ラベルに azure:azure/Azure-A）、rg、region、vnet、subnet、zone を使用し、vnet または subnet ラベルはそのアイコンを持ちます（vnet:azure/vnet、subnet:azure/subnet）。VNetは1つのリージョンに属するため、リージョン内に配置します。Front Doorのようなグローバルサービスはリージョンの外部に配置します。App ServiceはApp Service Environmentで実行されていない限りVNetの外部に配置され、プライベートエンドポイントを介して到達されるPaaSサービスは、役割を private endpoint として内部に配置できます。Microsoftは各アイコンの横にサービスの完全な名前を要求するため（SQL ではなく Azure SQL Database）、名前が折り返されるノードを広げてください（left:<centerX-76>px; width:152px）。
• Kubernetesは公式のコミュニティアイコンを使用します。 name:k8s/<Resource> で取得し、公式のkubernetes/communityアイコンセットから読み取ります（例：pod:k8s/pod、deploy:k8s/deployment、svc:k8s/service、ing:k8s/ingress、cm:k8s/configmap、secret:k8s/secret、node:k8s/node、api:k8s/kube-apiserver）。アイコンは、リソースとインフラストラクチャにはラベルのないバリアントを使用して、図のスケールでグリフをクリーンで整然とした状態に保ち、コントロールプレーンコンポーネントにはラベル付きバリアントを使用します。一般的な短縮名と複数形は機能します（svc/service/services、deploy/deployment/deployments、po/pod/pods、cm/configmap/configmaps、sts/statefulset、ds/daemonset、node/nodes など）。見つからない場合は使用可能な名前が表示されます。スラグ k8s、kubernetes、k8s/k8s は、チェーンを通じて公式のKubernetesホイールロゴを提供します。
• Kubernetes図はデフォルトで通常のスタイルを維持します。 アイコンは通常の白いタイル上に配置され、スタック内の他のテクノロジー（NGINX、cert-manager、外部データベース、クラウドロードバランサーなど）と統一され、グラフ用紙の背景に対して一貫した浮き上がりとコントラストを提供します。最小限のスタンドアロングリフには、tile bare もサポートされています。グループは標準のグループ（cluster、namespace、node、pod）を使用します。図のフッターでKubernetes Icons Setのクレジットを表示します。
• ベンダーのルールはそのベンダーのエリアにのみ適用されます。 AWS、Google Cloud、Azure、Kubernetesのルールは、図に他のものが表示されていなくても、そのベンダーのグループ内でのみ適用されます。その外部のもの（隣のユーザーやグループに入るエッジなど）は、通常のタイル、グループ、エッジ、凡例を維持します。
• ブランド以外のノード（ユーザー、ブラウザ、インターネット、デバイス、ベアメタルサーバー）：assets/generic/ からグリフをノード名のアイコンディレクトリにコピーするか、name:lucide/<icon> を使用してください。絵文字は使用しないでください。これらはブランドロゴではないため、図のインク色に色付けしても問題ありません（fetchスクリプトはLucideに対して自動的に行います）。
• グループラベルのアイコンは14pxでレンダリングされます — 正方形のグリフマークが必要です。ワードマークや幅の広いロックアップはこのサイズではつぶれます。メインアイコンがワードマークの場合は、別途ブランドの正方形アイコンをラベル用に取得してください（svglは通常持っています。それ以外の場合はプロジェクト自身のアイコンまたはファビコンファイル）。
• グループラベルはグループの色合いの上に配置され、白いタイルの上ではないため、ダークテーマでは黒い部分を持つマークがそこに表示されなくなります。fetch_icons.py が <name>_dark を保存した場合は、ラベルでテンプレートの lt/dk ペアを使用します。ダークバリアントがなく、マークに黒い部分がある場合は、ラベルにクラス plate を追加します。

…

(翻訳の都合上、元のSKILL.mdは途中まで表示されています。完全な翻訳が必要な場合は、全文を提供してください。)