gemini-visual

Gemini Visual - フロントエンドおよびビジュアル開発アシスタント

概要

Google Gemini の高度なビジュアル推論機能を活用し、フロントエンド開発やデザイン関連の作業を支援する包括的なツールキットです。Gemini は、空間推論、ドキュメント理解、高解像度画像処理を備えた最先端のマルチモーダルな理解機能を提供します。

使用する場面

• UI/UX 分析：スクリーンショットを分析して、レイアウトの問題、視覚的階層、デザインパターンを確認します
• アクセシビリティ監査：コントラスト比、テキストの読みやすさ、WCAG 準拠を確認します
• デザイン比較：モックアップ、変更前後のスクリーンショット、または異なるデザイン案を比較します
• カラーパレットの抽出：画像から HEX、RGB、HSL 値を含む色を抽出します
• スクリーンショットからコードを生成：デザインのスクリーンショットから HTML/CSS を生成します
• UI アセットの生成：アイコン、背景、グラデーション、UI グラフィックを作成します
• レスポンシブデザインのレビュー：複数デバイスのスクリーンショットを分析し、一貫性を確認します
• ビジュアルデバッグ：レンダリングの問題、レイアウトの崩れ、視覚的なバグを特定します
• 要件からデザインを作成：テキストによる説明からデザイン、コード、コンポーネントを生成します
• インタラクティブなデザインセッション：複数ターンの会話を通じて、デザインを反復的に改善します

前提条件

• Python 3.9+
• google-genai パッケージ
• GEMINI_API_KEY 環境変数

インストール

pip install google-genai

API キーの取得

1. Google AI Studio にアクセスします
2. Google アカウントでサインインします
3. 「Create API Key」をクリックします
4. キーをコピーし、環境変数として設定します：

export GEMINI_API_KEY="your-api-key"

永続的に設定するには、シェルのプロファイル（~/.zshrc または ~/.bashrc）に追加します：

echo 'export GEMINI_API_KEY="your-api-key"' >> ~/.zshrc

スクリプトの概要

スクリプト	用途
analyze_ui.py	UI のスクリーンショットを分析し、問題、パターン、改善案を提示します
generate_ui_assets.py	アイコン、背景、UI グラフィックを生成します
compare_designs.py	2 つのデザインを比較し、相違点を強調表示します
extract_colors.py	画像からカラーパレットを抽出します
screenshot_to_code.py	スクリーンショットを HTML/CSS コードに変換します
design_from_brief.py	テキストによる要件からデザインとコードを生成します（画像は不要です）

利用可能なモデル

モデル	最適な用途	備考
gemini-2.5-flash	ビジュアル分析、コード生成、高速な推論	分析に最適なコストと品質のバランス
gemini-2.5-pro	複雑なビジュアル推論、コード生成	最高品質の分析
gemini-2.5-flash-image-preview	アセット生成、画像編集	ネイティブの画像出力
gemini-3.1-flash-image-preview	高品質な画像生成、4K 出力	最新の画像生成モデル
gemini-3-pro-image-preview	プロフェッショナルな画像生成	前世代の高品質モデル

注： 画像の分析タスク（analyze_ui、compare_designs、screenshot_to_code、extract_colors）には、テキストとビジョンに対応したモデル（gemini-2.5-flash または gemini-2.5-pro）を使用してください。画像の生成タスク（generate_ui_assets）には、画像出力モデルを使用してください。

メディア解像度のオプション

--resolution でトークン使用量と詳細度を調整します：

解像度	画像あたりのトークン数	最適な用途
low	70	手早い確認、サムネイル
medium	560	標準的なスクリーンショット、OCR
high	1120	詳細な UI 分析
ultra_high	2240+	細かなテキスト、複雑なレイアウト

---

スクリプトリファレンス

1. analyze_ui.py - UI 分析

UI のスクリーンショットを分析して、デザイン上の問題、アクセシビリティの問題、改善案を確認します。

python scripts/analyze_ui.py [options] IMAGE

Required:
  IMAGE                    Path to UI screenshot to analyze

Options:
  -m, --mode MODE          Analysis mode (default: comprehensive)
                           Modes: comprehensive, accessibility, layout, ux
  -r, --resolution RES     Media resolution (default: high)
  -o, --output FILE        Save analysis to file (JSON or text)
  -f, --format FORMAT      Output format: text, json, markdown (default: text)
  --thinking LEVEL         Thinking level: low, high (default: high)
  -v, --verbose            Show detailed progress

使用例：

# Comprehensive UI analysis
python scripts/analyze_ui.py screenshot.png

# Accessibility-focused analysis
python scripts/analyze_ui.py -m accessibility app_screen.png

# Layout analysis with JSON output
python scripts/analyze_ui.py -m layout -f json -o report.json mockup.png

# Quick UX review
python scripts/analyze_ui.py -m ux --thinking low mobile_app.png

分析モード：

• comprehensive：レイアウト、色、タイポグラフィ、アクセシビリティ、UX を含む包括的な分析
• accessibility：WCAG 準拠、コントラスト比、スクリーンリーダーへの対応、タッチターゲット
• layout：視覚的階層、余白、配置、レスポンシブ表示の問題
• ux：ユーザーフロー、アフォーダンス、認知負荷、インタラクションパターン

---

2. generate_ui_assets.py - アセット生成

アイコン、背景、パターン、グラフィックなどの UI アセットを生成します。

python scripts/generate_ui_assets.py [options]

Required:
  -p, --prompt TEXT        Description of asset to generate

Options:
  -t, --type TYPE          Asset type (default: icon)
                           Types: icon, background, pattern, illustration, badge
  -s, --style STYLE        Design style (default: modern)
                           Styles: modern, minimal, flat, gradient, glassmorphism,
                                   neumorphism, material, ios, outlined
  -c, --colors COLORS      Color palette (comma-separated HEX or names)
  -a, --aspect-ratio RATIO Aspect ratio (default: 1:1)
  --size SIZE              Resolution: 1K, 2K, 4K (default: 1K)
  -o, --output FILE        Output file path
  -r, --reference IMAGE    Reference image for style guidance
  -v, --verbose            Show detailed progress

例：

# Generate app icon
python scripts/generate_ui_assets.py -p "Weather app icon with sun and clouds" -t icon

# Create gradient background
python scripts/generate_ui_assets.py -p "Soft gradient for login screen" -t background \
  -c "#667eea,#764ba2" -a 9:16 -o login_bg.png

# Generate pattern for UI
python scripts/generate_ui_assets.py -p "Subtle geometric pattern for card backgrounds" \
  -t pattern -s minimal -o pattern.png

# Create illustration from reference
python scripts/generate_ui_assets.py -p "Onboarding illustration, person using phone" \
  -t illustration -r brand_style.png -o onboarding.png

# Generate badge/label
python scripts/generate_ui_assets.py -p "Premium badge with star" -t badge \
  -c "gold,white" -s gradient

---

3. compare_designs.py - デザイン比較

2 つのデザインスクリーンショットを比較し、違いを分析します。

python scripts/compare_designs.py [options] IMAGE1 IMAGE2

Required:
  IMAGE1                   First design image (before/version A)
  IMAGE2                   Second design image (after/version B)

Options:
  -m, --mode MODE          Comparison mode (default: full)
                           Modes: full, visual, content, accessibility
  -f, --format FORMAT      Output format: text, json, markdown (default: text)
  -o, --output FILE        Save comparison to file
  -r, --resolution RES     Media resolution (default: high)
  -v, --verbose            Show detailed progress

例：

# Full design comparison
python scripts/compare_designs.py before.png after.png

# Visual-only comparison
python scripts/compare_designs.py -m visual old_design.png new_design.png

# Compare for accessibility changes
python scripts/compare_designs.py -m accessibility v1.png v2.png -o report.md

# A/B test comparison as JSON
python scripts/compare_designs.py -m full variant_a.png variant_b.png -f json

比較モード：

• full：すべての視覚的および機能的な要素を包括的に比較します
• visual：色、タイポグラフィ、間隔、視覚的階層に注目します
• content：テキストの変更、レイアウトの移動、情報アーキテクチャを確認します
• accessibility：コントラスト、読みやすさ、タッチターゲット、WCAG 準拠状況の変更を確認します

---

4. extract_colors.py - カラーパレット抽出

複数の出力形式で画像からカラーパレットを抽出します。

python scripts/extract_colors.py [options] IMAGE

Required:
  IMAGE                    Image to extract colors from

Options:
  -n, --count COUNT        Number of colors to extract (default: 6)
  -f, --format FORMAT      Output format: text, json, css, tailwind, scss (default: text)
  -o, --output FILE        Save palette to file
  --named                  Include closest CSS color names
  --contrast               Calculate contrast ratios between colors
  -v, --verbose            Show detailed progress

例：

# Extract 6 main colors
python scripts/extract_colors.py screenshot.png

# Extract palette as CSS variables
python scripts/extract_colors.py -f css -o colors.css brand_image.png

# Get Tailwind config
python scripts/extract_colors.py -f tailwind -o tailwind.config.js design.png

# Detailed palette with contrast info
python scripts/extract_colors.py -n 8 --named --contrast hero_image.jpg

# SCSS variables output
python scripts/extract_colors.py -f scss -o _colors.scss mockup.png

---

5. screenshot_to_code.py - スクリーンショットからコードを生成

UI のスクリーンショットを HTML/CSS コードに変換します。

python scripts/screenshot_to_code.py [options] IMAGE

Required:
  IMAGE                    UI screenshot to convert

Options:
  -f, --framework FRAME    CSS framework (default: tailwind)
                           Frameworks: tailwind, css, bootstrap, vanilla
  -c, --components         Extract as reusable components
  --responsive             Generate responsive code
  -o, --output DIR         Output directory for files
  -r, --resolution RES     Media resolution (default: ultra_high)
  --thinking LEVEL         Thinking level: low, high (default: high)
  -v, --verbose            Show detailed progress

例：

# Convert to Tailwind HTML
python scripts/screenshot_to_code.py landing_page.png

# Generate vanilla CSS
python scripts/screenshot_to_code.py -f vanilla -o ./output mockup.png

# Create responsive Bootstrap components
python scripts/screenshot_to_code.py -f bootstrap -c --responsive card.png

# Full page conversion with components
python scripts/screenshot_to_code.py -f tailwind -c --responsive -o ./components page.png

---

6. design_from_brief.py - テキストベースのデザインアシスタント

画像を入力せずに、テキストの説明からフロントエンドのデザイン、コード、コンポーネントを生成します。

python scripts/design_from_brief.py [options]

Input (one required):
  -p, --prompt TEXT      Design brief or prompt text
  -b, --brief-file FILE  Read brief from a file
  --interactive          Start interactive design session

Options:
  -m, --mode MODE        Generation mode (default: code)
                         Modes: design, code, component, review, brainstorm
  -fw, --framework FW    Framework for code generation (default: tailwind)
                         Frameworks: tailwind, css, bootstrap, react, vue, svelte, vanilla
  -c, --context TEXT     Additional context (existing code, constraints)
  -f, --format FORMAT    Output format: text, json, markdown (default: text)
  -o, --output FILE      Save output to file
  -v, --verbose          Show detailed progress

例：

# Generate code from a brief
python scripts/design_from_brief.py -p "Create a pricing table with 3 tiers" -m code -fw tailwind

# Get design advice and guidance
python scripts/design_from_brief.py -p "Design a modern SaaS landing page" -m design

# Generate a React component
python scripts/design_from_brief.py -p "A toggle switch with smooth animation" -m component -fw react

# Review a design idea
python scripts/design_from_brief.py -p "Is a hamburger menu good for desktop navigation?" -m review

# Brainstorm creative ideas
python scripts/design_from_brief.py -p "Ideas for a fitness app dashboard" -m brainstorm

# Read brief from file
python scripts/design_from_brief.py -b project_brief.txt -m code -fw vue

# Interactive multi-turn session
python scripts/design_from_brief.py --interactive -m code -fw tailwind

生成モード：

• design：色、タイポグラフィ、レイアウト、UX に関する推奨事項など、デザインのガイダンスを取得します
• code：本番環境ですぐに使えるフロントエンドコードを生成します
• component：props とバリアントを備えた再利用可能な UI コンポーネントをデザインし、コードを生成します
• review：デザイン案やコードに関するフィードバックと推奨事項を取得します
• brainstorm：創造的なアイデアと複数のデザイン案を生成します

対応フレームワーク：

フレームワーク	説明
tailwind	Tailwind CSS のユーティリティクラス
css	変数と BEM を使用したカスタム CSS
bootstrap	Bootstrap 5 のコンポーネント
react	TypeScript を使用した React の関数コンポーネント
vue	TypeScript を使用した Vue 3 Composition API
svelte	Svelte コンポーネント
vanilla	通常の HTML/CSS/JavaScript

インタラクティブセッションのコマンド：

--interactive を使用すると、次のコマンドを利用できます。

コマンド	説明
/mode <mode>	生成モードを変更します
/framework <fw>	フレームワークを変更します
/save <file>	直前の応答をファイルに保存します
/clear	会話履歴を消去します
/quit	セッションを終了します

---

ユースケース

フロントエンド開発ワークフロー

# 1. Analyze a design mockup
python scripts/analyze_ui.py mockup.png -f markdown -o analysis.md

# 2. Extract brand colors
python scripts/extract_colors.py mockup.png -f tailwind -o colors.js

# 3. Generate code from screenshot
python scripts/screenshot_to_code.py mockup.png -f tailwind -c -o ./src

# 4. Generate placeholder icons
python scripts/generate_ui_assets.py -p "Settings gear icon" -t icon -s outlined

デザインレビューのプロセス

# Compare design iterations
python scripts/compare_designs.py v1.png v2.png -f markdown -o review.md

# Check accessibility
python scripts/analyze_ui.py final_design.png -m accessibility -o a11y_report.json

アセット制作パイプライン

# Generate icon set
for icon in "home" "search" "profile" "settings"; do
  python scripts/generate_ui_assets.py -p "${icon} icon" -t icon -s outlined -o icons/${icon}.png
done

# Generate backgrounds for different screens
python scripts/generate_ui_assets.py -p "Auth screen gradient" -t background -a 9:16 -o bg_auth.png
python scripts/generate_ui_assets.py -p "Dashboard header" -t background -a 21:9 -o bg_header.png

テキストの要件からデザインを作成

# Start with design exploration
python scripts/design_from_brief.py -p "E-commerce product page for sneakers" -m design -o design_spec.md

# Generate the code
python scripts/design_from_brief.py -p "E-commerce product page with image gallery,
size selector, add to cart button, and reviews section" -m code -fw react -o product_page.tsx

# Create reusable components
python scripts/design_from_brief.py -p "Star rating component, 1-5 stars,
supports half stars, shows count" -m component -fw react

# Interactive refinement session
python scripts/design_from_brief.py --interactive -m code -fw tailwind
# Then iterate: "Add a sticky header", "Make the CTA more prominent", etc.

プロジェクト全体のワークフロー（画像不要）

# 1. Brainstorm ideas
python scripts/design_from_brief.py -p "Modern dashboard for analytics SaaS" -m brainstorm

# 2. Get detailed design spec
python scripts/design_from_brief.py -p "Analytics dashboard with sidebar nav,
KPI cards, charts, and data tables" -m design -f markdown -o design.md

# 3. Generate components
python scripts/design_from_brief.py -p "KPI card showing metric, trend, and sparkline" \
  -m component -fw react -o components/KPICard.tsx

python scripts/design_from_brief.py -p "Data table with sorting, filtering, pagination" \
  -m component -fw react -o components/DataTable.tsx

# 4. Generate full page layout
python scripts/design_from_brief.py -p "Dashboard layout combining sidebar, header,
and main content area with the KPI cards and data table" -m code -fw react

---

API 機能の概要

Gemini 3 の視覚機能

• 空間推論：要素の配置、整列、相互関係を理解します
• ドキュメント理解：OCR、テキスト抽出、レイアウト解析
• 高解像度：細部や小さなテキストを確認できる超高解像度に対応します
• 複数画像の入力：1 回のリクエストにつき最大 3,600 枚の画像を比較します
• 思考シグネチャ：複数ターンにわたる編集で推論コンテキストを保持します

画像のサポート

• 入力形式：PNG、JPEG、WebP、HEIC、HEIF
• 最大ファイルサイズ：インラインでは 20MB、File API 経由ではそれ以上
• 出力形式：PNG（生成画像）
• 解像度：1K、2K、4K（生成）、入力解像度は設定可能

---

トラブルシューティング

「GEMINI_API_KEY environment variable not set」

API キーを設定します。

export GEMINI_API_KEY="your-api-key"

「Rate limit exceeded」

数分待ってから再試行してください。バッチ処理では、リクエスト間に待機時間を追加してください。

分析の品質が低い場合

より高い解像度を使用してください。

python scripts/analyze_ui.py -r ultra_high screenshot.png

細部が不足している場合

詳細な UI 分析には、ultra_high 解像度を使用してください。

python scripts/analyze_ui.py -r ultra_high -m comprehensive app.png

コード生成に問題がある場合

高い思考レベルと ultra_high 解像度を使用してください。

python scripts/screenshot_to_code.py --thinking high -r ultra_high mockup.png

コンテンツモデレーションによってアセットの生成がブロックされる場合

「No image content returned. The request may have been blocked by content moderation」と表示された場合は、次の方法を試してください。

• プロンプトを簡潔にする、または言い換える
• 特定のブランド名や著作権で保護された表現を削除する
• より一般的な説明を使用する

これは Gemini API の安全フィルターによるもので、すべてのプロンプトが受け付けられるわけではありません。

解像度はトークン使用量に影響します

--resolution パラメーターは、画像処理に使用するトークン数を制御します。

• low：画像あたり約 70 トークン。クイックスキャン、サムネイル向け
• medium：画像あたり約 560 トークン。一般的なスクリーンショット、OCR 向け
• high：画像あたり約 1120 トークン。詳細な UI 分析向け（デフォルト）

解像度を高くすると精度が向上しますが、使用するトークン数も増えます。

---

ベストプラクティス

1. 適切な解像度を使用する：解像度を高くするとトークン数は増えますが、精度も向上します
2. タスクに合ったモデルを選ぶ：分析には gemini-3-pro-preview、生成には gemini-3-pro-image-preview を使用します
3. コンテキストを提供する：より良い結果を得るため、プロンプトに関連する詳細を追加します
4. アセットを反復的に調整する：複数ターンの会話を使って改善します
5. スクリプトを組み合わせる：抽出と生成を組み合わせ、一貫性のあるデザインシステムを構築します
6. 出力を保存する：-o フラグを使ってレポートを保存し、ドキュメントに活用します
7. 類似したタスクをまとめて処理する：効率化のため、類似した複数の項目をまとめて処理します

参照元

• Gemini モデルのリファレンス
• 画像の理解
• 画像生成
• Google AI Studio