VisualSpec

VisualSpec

AI エージェント向けの決定論的なビジュアル生成。
画像は AI が生成します。VisualSpec がタイポグラフィとレイアウトを保証します。

# Instant workspace setup (no clone required)
npx @utkarshx27/visualspec init

# Launch local MCP Server for Cursor, Claude Desktop, or Antigravity
npx @utkarshx27/visualspec mcp

---

中核となる課題

ソーシャルメディアやマーケティング向けのグラフィックでは、1つの自然言語プロンプトに多くの要件を一度に処理させるため、ほとんどの画像生成ワークフローがうまくいきません。

• 被写体と背景
• 正確なタイポグラフィと文言
• プラットフォームの寸法とセーフマージン
• 視覚的な階層とネガティブスペース
• ブランドカラーのルールと制約

画像モデルは、意味不明なテキストをでっち上げたり、単語を途中で切ったり、構図のルールを無視したりすることがよくあります。

解決策：レイヤーの分離

VisualSpec は、生成に関する要素と決定論的な要素を分離します。

1. 生成レイヤー（AI モデル）：写真、3D の被写体、雰囲気のある背景、テクスチャ、ライティング。
2. 決定論的レイヤー（コードと SVG エンジン）：正確な見出し、サブタイトル、バッジ、ロゴ、指標、セーフマージン、レイアウトルール。
3. 構造化されたビジュアル仕様：唯一の基準となる、機械可読な YAML 仕様。
4. ビジュアル QA と対象を絞った修復：ジオメトリ、マージン、文言の完全一致条件を検証し、シーン全体を再生成せずに局所的な修復を合成します。

User Brief / Intent
       │
       ▼
   Visual Spec (spec.yaml)
       │
   ┌───┴──────────────┐
   ▼                  ▼
Platform Pack    Template Pack
   │                  │
   └───┬──────────────┘
       ▼
   Spec Resolver
       │
   ┌───┴───────────────────────┐
   ▼                           ▼
Model Adapter           Deterministic Layout
(Generative Base)       (SVG Typography / Overlay)
   │                           │
   └───┬───────────────────────┘
       ▼
  Compositor (Sharp)
       │
       ▼
   Visual QA (Constraints, Safe Margins, Exact Copy)
       │
       ├── PASS ──► Final Asset Bundle
       │
       └── FAIL ──► Targeted Repair Planner

---

ドキュメント

• アーキテクチャと設計原則
• VisualSpec のスキーマと仕様
• MCP サーバーのセットアップ（Cursor、Claude、Antigravity）
• 新しい画像モデルプロバイダーの追加
• コントリビューションガイドライン

---

クイックスタート

インストール不要ですぐに実行

# Initialize a new VisualSpec workspace
npx @utkarshx27/visualspec init

# Launch local MCP Server for Cursor, Claude, or Antigravity IDE
npx @utkarshx27/visualspec mcp

またはグローバルにインストール

npm install -g @utkarshx27/visualspec

# Use CLI commands directly
visual init
visual mcp

またはソースからビルド

git clone https://github.com/utkarshx27/visualspec.git
cd visualspec
npm install
npm run build

1. プロジェクトを初期化

npx @utkarshx27/visualspec init

2. ビジュアル仕様を検証

npx @utkarshx27/visualspec validate examples/product-launch/spec.yaml

3. コンパイル済みの生成プロンプトを確認

npx @utkarshx27/visualspec compile examples/product-launch/spec.yaml --provider openai

4. 決定論的レンダリング（API キー不要）

レイアウト、タイポグラフィ、背景のスタイルをローカルでレンダリングします。

npx @utkarshx27/visualspec render examples/product-launch/spec.yaml --output ./output/demo-launch

5. 生成パイプライン全体を実行

npx @utkarshx27/visualspec generate examples/product-launch/spec.yaml --provider mock --output ./output/demo-launch

6. ビジュアル QA でアセットの品質を検証

npx @utkarshx27/visualspec check ./output/demo-launch/final.png --spec examples/product-launch/spec.yaml

---

Model Context Protocol（MCP）サーバー

VisualSpec は stdio 経由でネイティブ MCP サーバーとして動作し、AI コーディングアシスタント（Cursor、Claude Code、Gemini CLI、Antigravity IDE）からビジュアルツールを直接呼び出せます。

# Launch MCP server over stdio
npx @utkarshx27/visualspec mcp

# Or if installed globally
visual mcp

利用可能な MCP ツール

• visual_brief_to_spec：自然言語のリクエストを有効な VisualSpec YAML に変換します。
• visual_validate_spec：仕様のスキーマを検証します。
• visual_render：決定論的なレイアウトとタイポグラフィのレンダリングを行います（API キー不要）。
• visual_generate：画像モデルアダプターと決定論的なテキストオーバーレイのパイプライン全体を実行します。
• visual_check_qa：セーフマージン、行数、寸法、不変条件を確認します。
• visual_repair：自動診断を行い、タイポグラフィやレイアウトを局所的に修復します。
• visual_list_resources：対応するプラットフォームパックとテンプレートを一覧表示します。

Cursor、Claude Desktop、Antigravity IDE の設定スニペットについては、MCP セットアップガイドを参照してください。

---

出力バンドル

生成のたびに、完全で再現可能なデバッグバンドルが作成されます。

output/demo-launch/
├── final.png                 # Platform-ready asset
├── visual-spec.yaml          # Original input specification
├── resolved-spec.yaml        # Full spec with platform & template rules applied
├── generation-request.json   # Exact prompt and negative parameters sent to model
├── qa-report.json            # Deterministic and constraint QA verification results
└── metadata.json             # Execution timestamps and file index

---

対応プラットフォームとテンプレート

プラットフォーム

• Instagram：フィード縦長（1080x1350、4:5）、正方形（1080x1080、1:1）、ストーリー（1080x1920、9:16）。
• LinkedIn：フィード縦長（1080x1350）、正方形（1080x1080）、バナー（1200x628）。
• 汎用ソーシャル：1:1、4:5、16:9 の汎用ソーシャル形式。

テンプレート

• 製品ローンチ：インパクトの強い見出し、機能を示すピル、製品ビジュアル領域、補足サブ見出し。
• 引用カード：中央に焦点を当てたエディトリアルな引用、著者のクレジット、控えめな雰囲気のグロー。
• 統計カード：大きく表示する数値指標、説明ラベル、データの背景情報。

---

エージェントスキル

このフレームワークには、./skills/ に配置された標準スキル定義が 10 個含まれています。

• using-visualspec：ワークフローの基本手順。
• visual-brief：ブリーフの抽出と分析。
• visual-spec：YAML の作成とスキーマのルール。
• composition：空間的な階層構造とネガティブスペースの割り当て。
• typography：フォントファミリーの分類と行数の調整。
• strict-constraints：不変条件の分類と禁止パラメーター。
• social-instagram：Instagram 固有のデザインに関する考察。
• social-linkedin：LinkedIn 固有のデザインに関する考察。
• visual-qa：自動検査と検証。
• visual-repair：問題の局所的な診断とパッチの生成。

---

ロードマップとオープンな貢献

皆さんからの貢献を歓迎します！一緒に取り組みたい主な分野は次のとおりです。

• 追加プラットフォーム：X/Twitter（ヘッダー、投稿）、YouTube サムネイル、Pinterest、TikTok カバー。
• 追加テンプレート：お客様の声、製品比較、イベント告知、機能一覧。
• 追加画像モデルアダプター：Flux、Stable Diffusion / ComfyUI、Midjourney API。
• ブランドパック：複数ブランドのパレット上書き、カスタムフォントの読み込み、ロゴのクリアスペース規則。
• ビジュアルスタジオ：仕様のリアルタイム確認と余白の切り替えができるローカルのウェブプレイグラウンド／ビューアー。

---

貢献

皆さんからの貢献を歓迎します！以下をご確認ください。

• 貢献ガイドライン
• 行動規範

---

テスト

自動テストスイートを実行します。

npm test

28 個のテストはすべて、サードパーティ製 API キーを必要とせず、オフラインで実行できます。

---

ライセンス

Apache License, Version 2.0 の下でライセンスされています。