static-web-artifacts-builder

静的 Web アーティファクトビルダー

高密度な静的インフォグラフィックアーティファクトを作成するには、次の手順に従います。

1. scripts/init-artifact.sh を使用してプロジェクトのひな形を初期化します
2. 生成された HTML ファイルを編集してアーティファクトを作成します
3. scripts/bundle-artifact.sh を使用して検証し、仕上げます
4. アーティファクトを表示します

技術スタック：Vanilla HTML5 + CSS3（Grid/Flexbox）+ インライン SVG — 実行時の依存関係はありません

デザインとスタイルのガイドライン

非常に重要：「AI slop」と呼ばれることの多いものを避けるため、過度に中央揃えされたレイアウト、紫のグラデーション、均一な角丸、Inter フォントは使用しないでください。

インフォグラフィック固有の制約

• 密度：コンテンツと余白の比率を 70:30 以上にします。ピクセルあたりの情報量を最大化します。
• 形状：レイヤー化／入れ子状のコンテナー、形状のある領域（clip-path、さまざまな border-radius）、グラデーション塗り、控えめな box-shadow を使います。平坦で均一なボックスは避けます。
• アイコン：主要な概念ごとにインライン SVG アイコンを使用します。テキストラベルだけの表示は避けます。
• 色：意味（カテゴリ、フローの方向、重大度）を表す、目的に沿ったパレット（3～4 色とニュートラルカラー）を使用します。CSS カスタムプロパティとして定義します。
• フロー：SVG の矢印、曲線、ラベル付きのエッジを使って方向性のある接続線を示します。アーキテクチャ図は、平坦なノードグラフではなく、双方向のデータフローを持つ階層レイヤーにします。
• レイアウト計算：列と行の比率を明示した grid-template-columns／grid-template-rows を CSS Grid で指定します。自動間隔設定のデフォルト値は使いません。すべての margin／padding を意図的に設定します。

クイックスタート

ステップ 1：プロジェクトを初期化する

初期化スクリプトを実行して、新しい静的プロジェクトを作成します。

bash scripts/init-artifact.sh <project-name>
cd <project-name>

これにより、次の内容を含む最小限のひな形が作成されます。

• ✅ CSS カスタムプロパティ（テーマ設定）を含む HTML テンプレート
• ✅ CSS Grid + Flexbox のレイアウトユーティリティ（インライン <style>）
• ✅ 印刷に対応した viewport meta 設定
• ✅ node_modules、package.json、ビルドツールチェーンなし

ステップ 2：アーティファクトを作成する

生成された index.html を直接編集します。各 HTML ファイルが 1 ページに対応し、明確なメッセージを 1 つ伝えます。

主なパターン：

• 名前付き領域のレイアウトには CSS Grid の grid-template-areas を使用します
• 空間を比例配分するには fr 単位を使用します
• SVG アイコンをインラインで埋め込みます（外部参照としてではなく）
• パレットの統一感を保つために、CSS カスタムプロパティ（--color-primary、--color-accent など）を使用します
• 視覚的な奥行きには clip-path、border-radius、グラデーション、box-shadow を使用します

ステップ 3：検証して仕上げる

bash scripts/bundle-artifact.sh

これにより、アーティファクトが完全に自己完結していることを検証します。

• 外部リソースへの参照がないことを確認します（CDN リンク、外部スタイルシート／スクリプトがないこと）
• インライン SVG が含まれていることを確認します
• ファイルサイズを報告します
• 検証済みの出力を bundle.html にコピーします

ステップ 4：アーティファクトをユーザーと共有する

ユーザーがアーティファクトとして表示できるよう、検証済みの HTML ファイルを会話内で共有します。

---

このスキルとほかのビジュアルスキルの使い分け

タスク	このスキルを使用	代わりに使用
複数のセクションと高いデータ密度を備えたリッチなインフォグラフィック	はい	—
インタラクティブなタブやトグルを備えた自己完結型ダッシュボード	はい	—
Figma/Illustratorで後から編集する静的なアーキテクチャ／トポロジー図	いいえ	architecture-diagram — このスキルのインタラクティブなHTMLではなく、本物のベクターSVGを生成します
シンプルなコンセプトイラストやアイコン風の画像	いいえ	concept-to-image
スライドデッキや複数ページのプレゼンテーション	いいえ	html-presentation
CSS Gridによるレイアウト制御が重要な単一ページのビジュアル	はい	—
Playwrightでスクリーンショットを撮れる状態にする必要があるアーティファクト	はい（ただし制限事項を参照）	—

---

エラー処理

エラー	原因	解決方法
bundle-artifact.shがCDNリンクを検出する	HTML内に外部スタイルシートまたはスクリプトへの参照がある	すべてのCSSとJSをインライン化します。出力に外部URLは使用できません
ブラウザーでコンテンツがはみ出す／切り取られる	ビューポートが小さすぎる、またはoverflow:hiddenを指定した固定高さ	heightの代わりにmin-heightを使用し、幅1440pxでテストします。スクロール領域ではoverflow: autoを使用します
Playwrightのスクリーンショットでコンテンツが切れる	ページの高さがスクリーンショットのビューポートを超えている	page.setViewportSizeをコンテンツの寸法に合わせて設定し、fullPage: trueを使用します
bundle-artifact.shがインラインSVGの欠落を報告する	SVGが<img src>または外部参照を介して読み込まれている	HTML内に直接インラインの<svg>ブロックを配置します
アーティファクトとして共有するにはファイルサイズが大きすぎる	base64画像の埋め込み、または冗長なSVG	SVGパスを最適化し、ラスター画像の埋め込みを避けます

---

制限事項

• スクリーンショットにはブラウザーが必要です：レンダリングとPlaywrightを使ったスクリーンショットの取得には、ブラウザーの実行環境が必要です。HTMLファイル自体はサーバー側の依存関係を持ちませんが、視覚的な検証にはブラウザーが必要です。
• サーバー側のレンダリングには対応していません：出力は純粋なクライアント側のものです。動的なデータ、API呼び出し、サーバー側で計算されるコンテンツには対応していません。
• 状態は保持されません：アーティファクトにバックエンドはありません。ユーザー操作（フォーム入力、トグル）はページの再読み込み時にリセットされ、保存できません。
• ファイルサイズの目安：500KB未満を目指してください。1MBを超えるアーティファクトは、一部のClaudeインターフェースでインラインの会話アーティファクトとしてレンダリングされない場合があります。
• フォントの利用可否：システムフォントのみ（またはbase64エンコードしたウェブフォントをインラインで使用）とします。Google Fontsやその他の外部フォントCDNを参照しないでください。
• 印刷時の再現性：CSSの印刷メディアクエリには対応していますが、ブラウザーによって印刷時のレンダリングは異なります。印刷出力が必要な場合は、@media printを明示的にテストしてください。