web-asset-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Web Asset Generator

网页资产生成工具

Generate professional web assets from logos or text slogans, including favicons, app icons, and social media meta images.

从logo或文字标语生成专业的网页资产，包括网站图标（favicon）、应用图标和社交媒体元图片。

Quick Start

快速开始

When a user requests web assets:

Use AskUserQuestion tool to clarify needs if not specified:
- What type of assets they need (favicons, app icons, social images, or everything)
- Whether they have source material (logo image vs text/slogan)
- For text-based images: color preferences
Check for source material:
- If user uploaded an image: use it as the source
- If user provides text/slogan: generate text-based images
Run the appropriate script(s):
- Favicons/icons:
```
scripts/generate_favicons.py
```
- Social media images:
```
scripts/generate_og_images.py
```
Provide the generated assets and HTML tags to the user

当用户请求生成网页资产时：

若需求未明确，使用AskUserQuestion工具澄清：
- 需要哪种类型的资产（网站图标、应用图标、社交图片，或全部）
- 是否有素材来源（logo图片 vs 文字/标语）
- 若为文本类图片：颜色偏好
检查素材来源：
- 若用户上传了图片：将其作为源素材
- 若用户提供文字/标语：生成基于文本的图片
运行对应的脚本：
- 网站图标/应用图标：
```
scripts/generate_favicons.py
```
- 社交媒体图片：
```
scripts/generate_og_images.py
```
向用户提供生成的资产和HTML元标签

Using Interactive Questions

使用交互式提问

IMPORTANT: Always use the AskUserQuestion tool to gather requirements instead of plain text questions. This provides a better user experience with visual selection UI.

重要提示：始终使用AskUserQuestion工具收集需求，而非纯文本提问。这能通过可视化选择界面提升用户体验。

Why Use AskUserQuestion?

为何使用AskUserQuestion？

✅ Visual UI: Users see options as clickable chips/tags instead of typing responses ✅ Faster: Click to select instead of typing out answers ✅ Clearer: Descriptions explain what each option means ✅ Fewer errors: No typos or misunderstandings from free-form text ✅ Professional: Consistent with modern Claude Code experience

✅ 可视化界面：用户可通过点击选项卡片/标签进行选择，无需输入文本 ✅ 更高效：点击选择替代手动输入 ✅ 更清晰：选项附带说明解释含义 ✅ 更少错误：避免自由文本输入导致的拼写错误或误解 ✅ 专业规范：与现代Claude Code体验保持一致

Example Flow

示例流程

User request: "I need web assets"

Claude uses AskUserQuestion (not plain text):

What type of web assets do you need?                    [Asset type]
○ Favicons only - Browser tab icons (16x16, 32x32, 96x96) and favicon.ico
○ App icons only - PWA icons for iOS/Android (180x180, 192x192, 512x512)
○ Social images only - Open Graph images for Facebook, Twitter, WhatsApp, LinkedIn
● Everything - Complete package: favicons + app icons + social images

User clicks → Claude immediately knows what to generate

用户请求："我需要网页资产"

Claude使用AskUserQuestion（而非纯文本）：

你需要哪种类型的网页资产？                    [资产类型]
○ 仅网站图标 - 浏览器标签页图标（16x16、32x32、96x96）和favicon.ico
○ 仅应用图标 - 适用于iOS/Android的PWA图标（180x180、192x192、512x512）
○ 仅社交图片 - 适用于Facebook、Twitter、WhatsApp、LinkedIn的Open Graph图片
● 全部 - 完整套餐：网站图标 + 应用图标 + 社交图片

用户点击后 → Claude立即明确要生成的内容

Question Patterns

提问模板

Below are the standard question patterns to use in various scenarios. Copy the structure and adapt as needed.

以下是适用于不同场景的标准提问模板，可复制结构并按需调整。

Question Pattern 1: Asset Type Selection

提问模板1：资产类型选择

When the user's request is vague (e.g., "create web assets", "I need icons"), use AskUserQuestion:

Question: "What type of web assets do you need?" Header: "Asset type" Options:

"Favicons only" - Description: "Browser tab icons (16x16, 32x32, 96x96) and favicon.ico"
"App icons only" - Description: "PWA icons for iOS/Android (180x180, 192x192, 512x512)"
"Social images only" - Description: "Open Graph images for Facebook, Twitter, WhatsApp, LinkedIn"
"Everything" - Description: "Complete package: favicons + app icons + social images"

当用户请求模糊时（例如："创建网页资产"、"我需要图标"），使用AskUserQuestion：

问题："你需要哪种类型的网页资产？" 标题："资产类型" 选项：

"仅网站图标" - 描述："浏览器标签页图标（16x16、32x32、96x96）和favicon.ico"
"仅应用图标" - 描述："适用于iOS/Android的PWA图标（180x180、192x192、512x512）"
"仅社交图片" - 描述："适用于Facebook、Twitter、WhatsApp、LinkedIn的Open Graph图片"
"全部" - 描述："完整套餐：网站图标 + 应用图标 + 社交图片"

Question Pattern 2: Source Material

提问模板2：素材来源

When the asset type is determined but source is unclear:

Question: "What source material will you provide?" Header: "Source" Options:

"Logo image" - Description: "I have or will upload a logo/image file"
"Emoji" - Description: "Generate favicon from an emoji character"
"Text/slogan" - Description: "Create images from text only"
"Logo + text" - Description: "Combine logo with text overlay (for social images)"

当资产类型已确定但素材来源不明确时：

问题："你将提供哪种素材来源？" 标题："素材来源" 选项：

"Logo图片" - 描述："我已有或将上传一张logo/图片文件"
"表情符号" - 描述："从表情符号生成网站图标"
"文字/标语" - 描述：仅从文字创建图片
"Logo + 文字" - 描述：将logo与文字叠加（用于社交图片）

Question Pattern 3: Platform Selection (for social images)

提问模板3：平台选择（针对社交图片）

When user requests social images but doesn't specify platforms:

Question: "Which social media platforms do you need images for?" Header: "Platforms" Multi-select: true Options:

"Facebook/WhatsApp/LinkedIn" - Description: "Standard 1200x630 Open Graph format"
"Twitter" - Description: "1200x675 (16:9 ratio) for large image cards"
"All platforms" - Description: "Generate all variants including square format"

当用户请求社交图片但未指定平台时：

问题："你需要为哪些社交媒体平台生成图片？" 标题："平台" 多选：true 选项：

"Facebook/WhatsApp/LinkedIn" - 描述："标准1200x630 Open Graph格式"
"Twitter" - 描述："1200x675（16:9比例）用于大图卡片"
"所有平台" - 描述："生成所有变体，包括方形格式"

Question Pattern 4: Color Preferences (for text-based images)

提问模板4：颜色偏好（针对文本类图片）

When generating text-based social images:

Question: "What colors should we use for your social images?" Header: "Colors" Options:

"I'll provide colors" - Description: "Let me specify exact hex codes for brand colors"
"Default theme" - Description: "Use default purple background (#4F46E5) with white text"
"Extract from logo" - Description: "Auto-detect brand colors from uploaded logo"
"Custom gradient" - Description: "Let me choose gradient colors"

生成基于文本的社交图片时：

问题："你的社交图片应使用什么颜色？" 标题："颜色" 选项：

"我将提供颜色" - 描述："让我指定品牌颜色的精确十六进制代码"
"默认主题" - 描述："使用默认紫色背景（#4F46E5）搭配白色文字"
"从logo提取" - 描述："从上传的logo中自动检测品牌颜色"
"自定义渐变" - 描述："让我选择渐变颜色"

Question Pattern 5: Icon Type Clarification

提问模板5：图标类型澄清

When user says "create icons" or "generate icons" (ambiguous):

Question: "What kind of icons do you need?" Header: "Icon type" Options:

"Website favicon" - Description: "Small browser tab icon"
"App icons (PWA)" - Description: "Mobile home screen icons"
"Both" - Description: "Favicon + app icons"

当用户说"创建图标"或"生成图标"（表述模糊）时：

问题："你需要哪种类型的图标？" 标题："图标类型" 选项：

"网站favicon" - 描述："小型浏览器标签页图标"
"应用图标（PWA）" - 描述："移动设备主屏幕图标"
"两者都要" - 描述："网站favicon + 应用图标"

Question Pattern 6: Emoji Selection

提问模板6：表情符号选择

When user selects "Emoji" as source material:

Step 1: Ask for project description (free text):

"What is your website/app about?"
Use this to generate emoji suggestions

Step 2: Use AskUserQuestion to present the 4 suggested emojis:

Question: "Which emoji best represents your project?" Header: "Emoji" Options: (Dynamically generated based on project description)

Example: "🚀 Rocket" - Description: "Rocket, launch, startup, space"
Example: "☕ Coffee" - Description: "Coffee, cafe, beverage, drink"
Example: "💻 Laptop" - Description: "Computer, laptop, code, dev"
Example: "🎨 Art" - Description: "Art, design, creative, paint"

Implementation:

bash

undefined

当用户选择"表情符号"作为素材来源时：

步骤1：询问项目描述（自由文本）：

"你的网站/应用是关于什么的？"
使用该描述生成表情符号建议

步骤2：使用AskUserQuestion展示4个推荐的表情符号：

问题："哪个表情符号最能代表你的项目？" 标题："表情符号" 选项：（根据项目描述动态生成）

示例："🚀 火箭" - 描述："火箭、启动、初创企业、太空"
示例："☕ 咖啡" - 描述："咖啡、咖啡馆、饮品、饮料"
示例："💻 笔记本电脑" - 描述："电脑、笔记本、代码、开发"
示例："🎨 艺术" - 描述："艺术、设计、创意、绘画"

实现方式：

bash

undefined

Get suggestions

获取建议

python scripts/generate_favicons.py --suggest "coffee shop" output/ all

Then generate with selected emoji

然后使用选中的表情符号生成

python scripts/generate_favicons.py --emoji "☕" output/ all


**Optional**: Ask about background color for app icons:

**Question**: "Do you want a background color for app icons?"
**Header**: "Background"
**Options**:
- **"Transparent"** - Description: "No background (favicons only)"
- **"White"** - Description: "White background (recommended for app icons)"
- **"Custom color"** - Description: "I'll provide a color"

python scripts/generate_favicons.py --emoji "☕" output/ all


**可选**：询问应用图标的背景颜色：

**问题**："你需要为应用图标添加背景色吗？"
**标题**："背景"
**选项**：
- **"透明"** - 描述："无背景（仅适用于网站图标）"
- **"白色"** - 描述："白色背景（推荐用于应用图标）"
- **"自定义颜色"** - 描述："我将提供颜色"

Question Pattern 7: Code Integration Offer

提问模板7：代码集成提议

When to use: After generating assets and showing HTML tags to the user

Question: "Would you like me to add these HTML tags to your codebase?" Header: "Integration" Options:

"Yes, auto-detect my setup" - Description: "Find and update my HTML/framework files automatically"
"Yes, I'll tell you where" - Description: "I'll specify which file to update"
"No, I'll do it manually" - Description: "Just show me the code, I'll add it myself"

If user selects "Yes, auto-detect":

Search for framework config files (next.config.js, astro.config.mjs, etc.)
Detect framework type
Find appropriate target file (layout.tsx, index.html, etc.)
Show detected file and ask for confirmation
Show diff of proposed changes
Insert tags if user confirms

If user selects "Yes, I'll tell you where":

Ask user for file path
Verify file exists
Show diff of proposed changes
Insert tags if user confirms

Framework Detection Priority:

Next.js: Look for

next.config.js

, update

app/layout.tsx

pages/_app.tsx

Astro: Look for
```
astro.config.mjs
```
, update layout files in
```
src/layouts/
```
SvelteKit: Look for
```
svelte.config.js
```
, update
```
src/app.html
```
Vue/Nuxt: Look for
```
nuxt.config.js
```
, update
```
app.vue
```
or
```
nuxt.config.ts
```
Plain HTML: Look for
```
index.html
```
or
```
*.html
```
files
Gatsby: Look for
```
gatsby-config.js
```
, update
```
gatsby-ssr.js
```

使用时机：生成资产并展示HTML标签后

问题："你需要我将这些HTML标签添加到你的代码库中吗？" 标题："集成" 选项：

"是，自动检测我的配置" - 描述："自动查找并更新我的HTML/框架文件"
"是，我会告诉你位置" - 描述："我将指定要更新的文件"
"否，我手动添加" - 描述："只需展示代码，我自己添加"

若用户选择"是，自动检测我的配置"：

搜索框架配置文件（next.config.js、astro.config.mjs等）
检测框架类型
找到合适的目标文件（layout.tsx、index.html等）
展示检测到的文件并请求确认
展示拟修改内容的差异对比
若用户确认，插入标签

若用户选择"是，我会告诉你位置"：

询问用户文件路径
验证文件是否存在
展示拟修改内容的差异对比
若用户确认，插入标签

框架检测优先级：

Next.js：查找

next.config.js

，更新

app/layout.tsx

或

pages/_app.tsx

Astro：查找
```
astro.config.mjs
```
，更新
```
src/layouts/
```
下的布局文件
SvelteKit：查找
```
svelte.config.js
```
，更新
```
src/app.html
```
Vue/Nuxt：查找
```
nuxt.config.js
```
，更新
```
app.vue
```
或
```
nuxt.config.ts
```
纯HTML：查找
```
index.html
```
或
```
*.html
```
文件
Gatsby：查找
```
gatsby-config.js
```
，更新
```
gatsby-ssr.js
```

Question Pattern 8: Testing Links Offer

提问模板8：测试链接提议

When to use: After code integration (or if user declined integration)

Question: "Would you like to test your meta tags now?" Header: "Testing" Options:

"Facebook Debugger" - Description: "Test Open Graph tags on Facebook"
"Twitter Card Validator" - Description: "Test Twitter card appearance"
"LinkedIn Post Inspector" - Description: "Test LinkedIn sharing preview"
"All testing tools" - Description: "Get links to all validators"
"No, skip testing" - Description: "I'll test later myself"

Provide appropriate testing URLs:

Facebook: https://developers.facebook.com/tools/debug/
Twitter: https://cards-dev.twitter.com/validator
LinkedIn: https://www.linkedin.com/post-inspector/
Generic OG validator: https://www.opengraph.xyz/

使用时机：代码集成后（或用户拒绝集成时）

问题："你现在需要测试你的元标签吗？" 标题："测试" 选项：

"Facebook调试工具" - 描述："在Facebook上测试Open Graph标签"
"Twitter卡片验证工具" - 描述："测试Twitter卡片显示效果"
"LinkedIn帖子检查工具" - 描述："测试LinkedIn分享预览"
"所有测试工具" - 描述："获取所有验证工具的链接"
"否，跳过测试" - 描述："我稍后自己测试"

提供对应的测试URL：

Facebook：https://developers.facebook.com/tools/debug/
Twitter：https://cards-dev.twitter.com/validator
LinkedIn：https://www.linkedin.com/post-inspector/
通用OG验证工具：https://www.opengraph.xyz/

Workflows

工作流程

Generate Favicons and App Icons from Logo

从Logo生成网站图标和应用图标

When user has a logo image:

bash

python scripts/generate_favicons.py <source_image> <output_dir> [icon_type]

Arguments:

```
source_image
```
: Path to the logo/image file
```
output_dir
```
: Where to save generated icons
```
icon_type
```
: Optional - 'favicon', 'app', or 'all' (default: 'all')

Example:

bash

python scripts/generate_favicons.py /mnt/user-data/uploads/logo.png /home/claude/output all

Generates:

favicon-16x16.png

favicon-32x32.png

favicon-96x96.png

```
favicon.ico
```
(multi-resolution)
```
apple-touch-icon.png
```
(180x180)

android-chrome-192x192.png

android-chrome-512x512.png

当用户有logo图片时：

bash

python scripts/generate_favicons.py <source_image> <output_dir> [icon_type]

参数：

```
source_image
```
：logo/图片文件的路径
```
output_dir
```
：生成的图标保存目录
```
icon_type
```
：可选 - 'favicon'、'app'或'all'（默认：'all'）

示例：

bash

python scripts/generate_favicons.py /mnt/user-data/uploads/logo.png /home/claude/output all

生成的文件：

favicon-16x16.png

、

favicon-32x32.png

、

favicon-96x96.png

```
favicon.ico
```
（多分辨率）
```
apple-touch-icon.png
```
（180x180）

android-chrome-192x192.png

、

android-chrome-512x512.png

Generate Favicons and App Icons from Emoji

从表情符号生成网站图标和应用图标

NEW FEATURE: Create favicons from emoji characters with smart suggestions!

新功能：通过智能建议，从表情符号创建网站图标！

Step 1: Get Emoji Suggestions

步骤1：获取表情符号建议

When user wants emoji-based icons, first get suggestions:

bash

python scripts/generate_favicons.py --suggest "coffee shop" /home/claude/output all

This returns 4 emoji suggestions based on the description:

1. ☕  Coffee               - coffee, cafe, beverage
2. 🌐  Globe                - web, website, global
3. 🏪  Store                - shop, store, retail
4. 🛒  Cart                 - shopping, cart, ecommerce

当用户需要基于表情符号的图标时，先获取建议：

bash

python scripts/generate_favicons.py --suggest "coffee shop" /home/claude/output all

这会根据描述返回4个表情符号建议：

1. ☕  咖啡               - 咖啡、咖啡馆、饮品
2. 🌐  地球仪                - 网页、网站、全球
3. 🏪  商店                - 店铺、商店、零售
4. 🛒  购物车                 - 购物、购物车、电商

Step 2: Generate Icons from Selected Emoji

步骤2：使用选中的表情符号生成图标

bash

python scripts/generate_favicons.py --emoji "☕" <output_dir> [icon_type] [--emoji-bg COLOR]

Arguments:

```
--emoji
```
: Emoji character to use
```
output_dir
```
: Where to save generated icons
```
icon_type
```
: Optional - 'favicon', 'app', or 'all' (default: 'all')
```
--emoji-bg
```
: Optional background color (default: transparent for favicons, white for app icons)

Examples:

bash

undefined

bash

python scripts/generate_favicons.py --emoji "☕" <output_dir> [icon_type] [--emoji-bg COLOR]

参数：

```
--emoji
```
：要使用的表情符号
```
output_dir
```
：生成的图标保存目录
```
icon_type
```
：可选 - 'favicon'、'app'或'all'（默认：'all'）
```
--emoji-bg
```
：可选背景色（默认：网站图标为透明，应用图标为白色）

示例：

bash

undefined

Basic emoji favicon (transparent background)

基础表情符号网站图标（透明背景）

python scripts/generate_favicons.py --emoji "🚀" /home/claude/output favicon

Emoji with custom background for app icons

带自定义背景的表情符号应用图标

python scripts/generate_favicons.py --emoji "☕" --emoji-bg "#F5DEB3" /home/claude/output all

Complete set with white background

带白色背景的完整图标集

python scripts/generate_favicons.py --emoji "💻" --emoji-bg "white" /home/claude/output all


Generates same files as logo-based generation:
- All standard favicon sizes (16x16, 32x32, 96x96)
- favicon.ico
- App icon sizes (180x180, 192x192, 512x512)

**Note**: Requires `pilmoji` library: `pip install pilmoji`

python scripts/generate_favicons.py --emoji "💻" --emoji-bg "white" /home/claude/output all


生成的文件与基于logo的生成结果相同：
- 所有标准网站图标尺寸（16x16、32x32、96x96）
- favicon.ico
- 应用图标尺寸（180x180、192x192、512x512）

**注意**：需要`pilmoji`库：`pip install pilmoji`

Generate Social Media Meta Images from Logo

从Logo生成社交媒体元图片

When user has a logo and needs Open Graph images:

bash

python scripts/generate_og_images.py <output_dir> --image <source_image>

Example:

bash

python scripts/generate_og_images.py /home/claude/output --image /mnt/user-data/uploads/logo.png

Generates:

```
og-image.png
```
(1200x630 - Facebook, WhatsApp, LinkedIn)
```
twitter-image.png
```
(1200x675 - Twitter)
```
og-square.png
```
(1200x1200 - Square variant)

当用户有logo且需要Open Graph图片时：

bash

python scripts/generate_og_images.py <output_dir> --image <source_image>

示例：

bash

python scripts/generate_og_images.py /home/claude/output --image /mnt/user-data/uploads/logo.png

生成的文件：

```
og-image.png
```
（1200x630 - 适用于Facebook、WhatsApp、LinkedIn）
```
twitter-image.png
```
（1200x675 - 适用于Twitter）
```
og-square.png
```
（1200x1200 - 方形变体）

Generate Social Media Meta Images from Text

从文本生成社交媒体元图片

When user provides a text slogan or tagline:

bash

python scripts/generate_og_images.py <output_dir> --text "Your text here" [options]

Options:

```
--logo <path>
```
: Include a logo with the text
```
--bg-color <color>
```
: Background color (hex or name, default: '#4F46E5')
```
--text-color <color>
```
: Text color (default: 'white')

Example:

bash

python scripts/generate_og_images.py /home/claude/output \
  --text "Transform Your Business with AI" \
  --logo /mnt/user-data/uploads/logo.png \
  --bg-color "#4F46E5"

当用户提供文字标语或口号时：

bash

python scripts/generate_og_images.py <output_dir> --text "Your text here" [options]

选项：

```
--logo <path>
```
：在文本中包含logo
```
--bg-color <color>
```
：背景色（十六进制代码或颜色名称，默认：'#4F46E5'）
```
--text-color <color>
```
：文字颜色（默认：'white'）

示例：

bash

python scripts/generate_og_images.py /home/claude/output \
  --text "用AI变革你的业务" \
  --logo /mnt/user-data/uploads/logo.png \
  --bg-color "#4F46E5"

Generate Everything

生成全部资产

For users who want the complete package:

bash

undefined

对于需要完整套餐的用户：

bash

undefined

Generate favicons and icons

生成网站图标和应用图标

python scripts/generate_favicons.py /mnt/user-data/uploads/logo.png /home/claude/output all

Generate social media images

生成社交媒体图片

python scripts/generate_og_images.py /home/claude/output --image /mnt/user-data/uploads/logo.png


Or for text-based:
```bash

python scripts/generate_og_images.py /home/claude/output --image /mnt/user-data/uploads/logo.png


或针对基于文本的场景：
```bash

Generate favicons from logo

从logo生成网站图标

python scripts/generate_favicons.py /mnt/user-data/uploads/logo.png /home/claude/output all

Generate social media images with text + logo

生成带文字+logo的社交媒体图片

python scripts/generate_og_images.py /home/claude/output
--text "Your Tagline Here"
--logo /mnt/user-data/uploads/logo.png

undefined

python scripts/generate_og_images.py /home/claude/output
--text "你的标语"
--logo /mnt/user-data/uploads/logo.png

undefined

Delivering Assets to User

向用户交付资产

After generating assets, follow this workflow:

生成资产后，遵循以下工作流程：

1. Move to Outputs Directory

1. 移动到输出目录

bash

cp /home/claude/output/* /mnt/user-data/outputs/

bash

cp /home/claude/output/* /mnt/user-data/outputs/

2. Show Generated HTML Tags

2. 展示生成的HTML标签

Display the HTML tags that were automatically generated by the scripts.

Example output for favicons:

html

<!-- Favicons -->
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="96x96" href="/favicon-96x96.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="192x192" href="/android-chrome-192x192.png">
<link rel="icon" type="image/png" sizes="512x512" href="/android-chrome-512x512.png">

Example output for Open Graph images:

html

<!-- Open Graph / Facebook -->
<meta property="og:image" content="/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Your description here">

<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="/twitter-image.png">
<meta name="twitter:image:alt" content="Your description here">

显示由脚本自动生成的HTML标签。

网站图标示例输出：

html

<!-- 网站图标 -->
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="96x96" href="/favicon-96x96.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="192x192" href="/android-chrome-192x192.png">
<link rel="icon" type="image/png" sizes="512x512" href="/android-chrome-512x512.png">

Open Graph图片示例输出：

html

<!-- Open Graph / Facebook -->
<meta property="og:image" content="/og-image.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="你的描述">

<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="/twitter-image.png">
<meta name="twitter:image:alt" content="你的描述">

3. Offer Code Integration (Use AskUserQuestion - Pattern 7)

3. 提议代码集成（使用AskUserQuestion - 模板7）

IMPORTANT: Always ask if the user wants help adding the tags to their codebase.

Question: "Would you like me to add these HTML tags to your codebase?" Header: "Integration" Options:

"Yes, auto-detect my setup"
"Yes, I'll tell you where"
"No, I'll do it manually"

重要提示：始终询问用户是否需要帮助将标签添加到代码库中。

问题："你需要我将这些HTML标签添加到你的代码库中吗？" 标题："集成" 选项：

"是，自动检测我的配置"
"是，我会告诉你位置"
"否，我手动添加"

If User Selects "Yes, auto-detect my setup":

若用户选择"是，自动检测我的配置"：

A. Detect Framework:

bash

undefined

A. 检测框架：

bash

undefined

Search for framework config files

搜索框架配置文件

find . -maxdepth 2 -name "next.config.js" -o -name "astro.config.mjs" -o -name "svelte.config.js" -o -name "nuxt.config.js" -o -name "gatsby-config.js"

Or check package.json

或检查package.json

grep -E "next|astro|nuxt|svelte|gatsby" package.json


**B. Find Target Files Based on Framework:**

- **Next.js (App Router)**: `app/layout.tsx` or `app/layout.js`
- **Next.js (Pages Router)**: `pages/_app.tsx` or `pages/_document.tsx`
- **Astro**: `src/layouts/*.astro` (typically `BaseLayout.astro` or `Layout.astro`)
- **SvelteKit**: `src/app.html`
- **Vue/Nuxt**: `app.vue` or `nuxt.config.ts` (head section)
- **Gatsby**: `gatsby-ssr.js` or `src/components/seo.tsx`
- **Plain HTML**: `index.html`, `public/index.html`, or any `*.html` file

**C. Confirm with User:**

Use AskUserQuestion to confirm detected file:

Question: "I found [Framework Name]. Should I update [file_path]?" Header: "Confirm" Options:

"Yes, update this file"
"No, show me other options"
"Cancel, I'll do it manually"


**D. Show Diff and Insert:**

1. Read the target file
2. Prepare the insertion (find `<head>` or appropriate section)
3. Show the diff to the user
4. If user confirms, use Edit tool to insert tags

**Framework-Specific Insertion Examples:**

**For Plain HTML** (insert before `</head>`):
```html
<head>
  <meta charset="UTF-8">
  <!-- INSERT TAGS HERE -->
  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
  ...
</head>

For Next.js App Router (add to metadata export):

typescript

export const metadata = {
  icons: {
    icon: [
      { url: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' },
      { url: '/favicon-16x16.png', sizes: '16x16', type: 'image/png' },
    ],
    apple: [
      { url: '/apple-touch-icon.png', sizes: '180x180', type: 'image/png' },
    ],
  },
  openGraph: {
    images: ['/og-image.png'],
  },
  twitter: {
    card: 'summary_large_image',
    images: ['/twitter-image.png'],
  },
}

For Astro (insert in

<head>

of layout file):

astro

<head>
  <meta charset="UTF-8">
  <!-- Favicons -->
  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
  ...
</head>

grep -E "next|astro|nuxt|svelte|gatsby" package.json


**B. 根据框架查找目标文件**：

- **Next.js（App Router）**：`app/layout.tsx`或`app/layout.js`
- **Next.js（Pages Router）**：`pages/_app.tsx`或`pages/_document.tsx`
- **Astro**：`src/layouts/*.astro`（通常为`BaseLayout.astro`或`Layout.astro`）
- **SvelteKit**：`src/app.html`
- **Vue/Nuxt**：`app.vue`或`nuxt.config.ts`（head部分）
- **Gatsby**：`gatsby-ssr.js`或`src/components/seo.tsx`
- **纯HTML**：`index.html`、`public/index.html`或任何`*.html`文件

**C. 与用户确认**：

使用AskUserQuestion确认检测到的文件：

问题："我检测到[框架名称]。是否更新[file_path]？" 标题："确认" 选项：

"是，更新此文件"
"否，展示其他选项"
"取消，我手动添加"


**D. 展示差异并插入**：

1. 读取目标文件
2. 准备插入内容（找到`<head>`或合适的位置）
3. 向用户展示差异对比
4. 若用户确认，使用Edit工具插入标签

**框架特定插入示例**：

**纯HTML**（插入到`</head>`之前）：
```html
<head>
  <meta charset="UTF-8">
  <!-- 在此处插入标签 -->
  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
  ...
</head>

Next.js App Router（添加到metadata导出）：

typescript

export const metadata = {
  icons: {
    icon: [
      { url: '/favicon-32x32.png', sizes: '32x32', type: 'image/png' },
      { url: '/favicon-16x16.png', sizes: '16x16', type: 'image/png' },
    ],
    apple: [
      { url: '/apple-touch-icon.png', sizes: '180x180', type: 'image/png' },
    ],
  },
  openGraph: {
    images: ['/og-image.png'],
  },
  twitter: {
    card: 'summary_large_image',
    images: ['/twitter-image.png'],
  },
}

Astro（插入到布局文件的

<head>

中）：

astro

<head>
  <meta charset="UTF-8">
  <!-- 网站图标 -->
  <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
  ...
</head>

If User Selects "Yes, I'll tell you where":

若用户选择"是，我会告诉你位置"：

Ask user for the file path
Verify file exists using Read tool
Show where tags will be inserted
Show diff
Insert if user confirms

询问用户文件路径
使用Read工具验证文件是否存在
展示标签将插入的位置
展示差异对比
若用户确认，插入标签

If User Selects "No, I'll do it manually":

若用户选择"否，我手动添加"：

Provide brief instructions:

Place asset files in the public/static directory of your website
Add the HTML tags to the
```
<head>
```
section of your HTML
Update placeholder values (title, description, URL, alt text)

提供简要说明：

将资产文件放置在网站的public/static目录中
将HTML标签添加到HTML的
```
<head>
```
部分
更新占位符值（标题、描述、URL、替代文本）

4. Offer Testing Links (Use AskUserQuestion - Pattern 8)

4. 提议测试链接（使用AskUserQuestion - 模板8）

Question: "Would you like to test your meta tags now?" Header: "Testing" Options:

"Facebook Debugger"
"Twitter Card Validator"
"LinkedIn Post Inspector"
"All testing tools"
"No, skip testing"

Provide Testing URLs:

Facebook Sharing Debugger: https://developers.facebook.com/tools/debug/
- Paste your URL and click "Debug" to see preview
- Click "Scrape Again" to refresh cache
Twitter Card Validator: https://cards-dev.twitter.com/validator
- Paste your URL to see how Twitter card will appear
LinkedIn Post Inspector: https://www.linkedin.com/post-inspector/
- Check how links appear when shared on LinkedIn
OpenGraph.xyz: https://www.opengraph.xyz/
- Generic Open Graph validator for quick checks

问题："你现在需要测试你的元标签吗？" 标题："测试" 选项：

"Facebook调试工具"
"Twitter卡片验证工具"
"LinkedIn帖子检查工具"
"所有测试工具"
"否，跳过测试"

提供测试URL：

Facebook分享调试工具：https://developers.facebook.com/tools/debug/
- 粘贴你的URL并点击"调试"查看预览
- 点击"重新抓取"刷新缓存
Twitter卡片验证工具：https://cards-dev.twitter.com/validator
- 粘贴你的URL查看Twitter卡片的显示效果
LinkedIn帖子检查工具：https://www.linkedin.com/post-inspector/
- 检查链接在LinkedIn上的分享显示效果
OpenGraph.xyz：https://www.opengraph.xyz/
- 用于快速检查的通用Open Graph验证工具

5. Final Instructions

5. 最终说明

Remind user to:

✅ Copy asset files to their public/static directory
✅ Update dynamic values in meta tags (og:title, og:description, og:url)
✅ Test on actual platforms after deployment
✅ Update alt text to be descriptive and accessible

Important Notes:

OG images must be accessible via HTTPS URLs (not localhost)
URLs in meta tags should be absolute (https://yourdomain.com/og-image.png)
Test after deploying to production/staging environment

提醒用户：

✅ 将资产文件复制到他们的public/static目录
✅ 更新元标签中的动态值（og:title、og:description、og:url）
✅ 部署后在实际平台上测试
✅ 更新替代文本使其具有描述性且易于访问

重要注意事项：

OG图片必须可通过HTTPS URL访问（不能是localhost）
元标签中的URL应为绝对路径（https://yourdomain.com/og-image.png）
部署到生产/预发布环境后进行测试

Best Practices

最佳实践

Image Requirements

图片要求

Logos: Should be square or nearly square for best results
High resolution: Provide largest available version (scripts will downscale)
Transparent backgrounds: PNG with transparency works best for favicons
Solid backgrounds: Recommended for app icons and social images

Logo：应为方形或接近方形以获得最佳效果
高分辨率：提供最大可用版本（脚本会自动缩小尺寸）
透明背景：带透明通道的PNG格式最适合网站图标
纯色背景：推荐用于应用图标和社交图片

Text Content

文本内容

Text length affects font size automatically:
- Short text (≤20 chars): 144px font - Large and impactful
- Medium text (21-40 chars): 120px font - Standard readable size
- Long text (41-60 chars): 102px font - Reduced for fit
- Very long text (>60 chars): 84px font - Minimal size
Keep text concise for maximum impact
Use 2-3 lines of text maximum for social images
Avoid special characters that may not render well

文本长度会自动影响字体大小：
- 短文本（≤20字符）：144px字体 - 大且醒目
- 中等文本（21-40字符）：120px字体 - 标准可读尺寸
- 长文本（41-60字符）：102px字体 - 缩小以适应
- 极长文本（>60字符）：84px字体 - 最小尺寸
保持文本简洁以达到最大效果
社交图片最多使用2-3行文本
避免使用可能无法正常渲染的特殊字符

Color Choices

颜色选择

Ensure sufficient contrast (4.5:1 minimum for readability)
Use brand colors consistently
Consider both light and dark mode contexts

确保足够的对比度（可读性最低要求4.5:1）
保持品牌颜色的一致性
考虑浅色和深色模式场景

Validation and Quality Checks

验证和质量检查

Both

generate_og_images.py

and

generate_favicons.py

support automated validation with the

--validate

flag.

generate_og_images.py

和

generate_favicons.py

都支持使用

--validate

标志进行自动验证。

When to Use Validation

何时使用验证

Always recommend validation when:

User is generating for production/deployment
User asks about file sizes or quality
User mentions platform requirements (Facebook, Twitter, etc.)
User is new to web assets and may not know requirements

Validation is optional for:

Quick prototypes or testing
Users who explicitly decline
When time is a concern

始终建议进行验证的场景：

用户为生产/部署生成资产
用户询问文件大小或质量
用户提及平台要求（Facebook、Twitter等）
用户不熟悉网页资产，可能不了解相关要求

验证可选的场景：

快速原型或测试
用户明确拒绝验证
时间紧迫时

What Gets Validated

验证内容

For Social Media Images (OG Images)

社交媒体图片（OG图片）

File Size Validation:

Facebook/LinkedIn/WhatsApp: Must be <8MB
Twitter: Must be <5MB
Warning if within 80% of limit

Dimension Validation:

Checks against platform-specific recommended sizes:
- Facebook/LinkedIn: 1200x630 (1.91:1 ratio)
- Twitter: 1200x675 (16:9 ratio)
- Square: 1200x1200 (1:1 ratio)
Warns if aspect ratio is >10% off target
Errors if below minimum dimensions

Format Validation:

Facebook/LinkedIn: PNG, JPG, JPEG
Twitter: PNG, JPG, JPEG, WebP
Errors if unsupported format

Accessibility (Contrast Ratio):

Only for text-based images
Calculates WCAG 2.0 contrast ratio
Reports compliance level:
- WCAG AAA: 7.0:1 (normal text) or 4.5:1 (large text)
- WCAG AA: 4.5:1 (normal text) or 3.0:1 (large text)
- Fails if below AA minimum

文件大小验证：

Facebook/LinkedIn/WhatsApp：必须<8MB
Twitter：必须<5MB
若超过限制的80%则发出警告

尺寸验证：

检查是否符合平台推荐尺寸：
- Facebook/LinkedIn：1200x630（1.91:1比例）
- Twitter：1200x675（16:9比例）
- 方形：1200x1200（1:1比例）
若宽高比与目标偏差>10%则发出警告
若尺寸低于最小值则报错

格式验证：

Facebook/LinkedIn：PNG、JPG、JPEG
Twitter：PNG、JPG、JPEG、WebP
若为不支持的格式则报错

可访问性（对比度）：

仅针对文本类图片
计算WCAG 2.0对比度
报告合规等级：
- WCAG AAA：7.0:1（普通文本）或4.5:1（大文本）
- WCAG AA：4.5:1（普通文本）或3.0:1（大文本）
- 若低于AA最低要求则报错

For Favicons and App Icons

网站图标和应用图标

File Size Validation:

Favicons: Warns if >100KB (recommended for fast loading)
App icons: Warns if >500KB (recommended for mobile)
No hard limits, but warnings help optimize performance

Dimension Validation:

Verifies each icon matches expected size (16x16, 32x32, etc.)
Ensures square aspect ratio

Format Validation:

Checks all files are PNG (or ICO for favicon.ico)

文件大小验证：

网站图标：若>100KB则发出警告（推荐用于快速加载）
应用图标：若>500KB则发出警告（推荐用于移动设备）
无硬性限制，但警告有助于优化性能

尺寸验证：

验证每个图标是否符合预期尺寸（16x16、32x32等）
确保为方形宽高比

格式验证：

检查所有文件是否为PNG格式（favicon.ico除外）

How to Use Validation

如何使用验证

In generate_og_images.py:

bash

python scripts/generate_og_images.py output/ --text "My Site" --validate

In generate_favicons.py:

bash

python scripts/generate_favicons.py logo.png output/ all --validate

Output Format:

✓ Success (green): All checks passed
⚠ Warning (yellow): Issues to consider but not critical
❌ Error (red): Must be fixed before deployment

在generate_og_images.py中：

bash

python scripts/generate_og_images.py output/ --text "My Site" --validate

在generate_favicons.py中：

bash

python scripts/generate_favicons.py logo.png output/ all --validate

输出格式：

✓ 成功（绿色）：所有检查通过
⚠ 警告（黄色）：需要注意但不影响功能
❌ 错误（红色）：部署前必须修复

Example Validation Output

验证输出示例

======================================================================
Running validation checks...
======================================================================

og-image.png:

Facebook Validation:
======================================================================
  ✓ File size 0.3MB is within Facebook limits
  ✓ Dimensions 1200x630 match Facebook recommended size
  ✓ Format PNG is supported by Facebook

LinkedIn Validation:
======================================================================
  ✓ File size 0.3MB is within LinkedIn limits
  ✓ Dimensions 1200x630 match LinkedIn recommended size
  ✓ Format PNG is supported by LinkedIn

======================================================================
Accessibility Checks:
======================================================================
  ✓ Contrast ratio 8.6:1 meets WCAG AAA standards (4.5:1 required)

======================================================================
Summary: 9/9 checks passed
✓ All validations passed!

======================================================================
运行验证检查...
======================================================================

og-image.png:

Facebook验证：
======================================================================
  ✓ 文件大小0.3MB符合Facebook限制
  ✓ 尺寸1200x630符合Facebook推荐尺寸
  ✓ PNG格式受Facebook支持

LinkedIn验证：
======================================================================
  ✓ 文件大小0.3MB符合LinkedIn限制
  ✓ 尺寸1200x630符合LinkedIn推荐尺寸
  ✓ PNG格式受LinkedIn支持

======================================================================
可访问性检查：
======================================================================
  ✓ 对比度8.6:1达到WCAG AAA标准（要求4.5:1）

======================================================================
总结：9/9项检查通过
✓ 所有验证通过！

Integrating Validation into Workflows

将验证集成到工作流程

After generating assets, if validation was NOT run:

Show the tip message: "💡 Tip: Use --validate to check file sizes, dimensions, and accessibility"
Optionally ask: "Would you like me to run validation on these files now?"

If validation was run and issues found:

Explain any errors or warnings
Offer to fix issues (e.g., resize, recompress, adjust colors)
Re-run generation with fixes if user agrees

If validation passes:

Confirm: "✅ All validation checks passed!"
Proceed with code integration and testing links

生成资产后，若未运行验证：

显示提示信息："💡 提示：使用--validate检查文件大小、尺寸和可访问性"
可选询问："你现在需要我对这些文件运行验证吗？"

若运行验证后发现问题：

解释错误或警告
提议修复问题（例如：调整大小、重新压缩、调整颜色）
若用户同意，重新生成资产并修复问题

若验证通过：

确认："✅ 所有验证检查通过！"
继续进行代码集成和测试链接提议

Specifications and Platform Details

规范和平台详情

For detailed platform specifications, size requirements, and implementation guidelines, read:

```
references/specifications.md
```
: Comprehensive specs for all platforms

有关详细的平台规范、尺寸要求和实施指南，请阅读：

```
references/specifications.md
```
：所有平台的综合规范

Handling Common Requests

处理常见请求

"Create a favicon for my site"

"为我的网站创建一个favicon"

Use AskUserQuestion:

Question: "Do you have a logo image, or should I create a text-based favicon?"
Header: "Source"
Options:
- "Logo image" - Description: "I have/will upload a logo file"
- "Text-based" - Description: "Generate from text or initials"

Then ask:

Question: "Do you also need PWA app icons for mobile devices?"
Header: "Scope"
Options:
- "Favicon only" - Description: "Just browser tab icons (16x16, 32x32, 96x96)"
- "Include app icons" - Description: "Add iOS/Android icons for home screen (180x180, 192x192, 512x512)"

Generate: Use

generate_favicons.py

with appropriate parameters

使用AskUserQuestion：

问题："你有logo图片，还是需要我创建一个基于文本的网站图标？"
标题："素材来源"
选项：
- "Logo图片" - 描述："我已有/将上传一张logo文件"
- "基于文本" - 描述："从文字或首字母生成"

然后询问：

问题："你还需要用于移动设备的PWA应用图标吗？"
标题："范围"
选项：
- "仅网站图标" - 描述："仅浏览器标签页图标（16x16、32x32、96x96）"
- "包含应用图标" - 描述："添加用于主屏幕的iOS/Android图标（180x180、192x192、512x512）"

生成：使用

generate_favicons.py

并传入对应的参数

"Make social sharing images"

"制作社交分享图片"

Use AskUserQuestion:

Question: "Which social media platforms do you need images for?"
Header: "Platforms"
Multi-select: true
Options:
- "Facebook/WhatsApp/LinkedIn" - Description: "Standard 1200x630 format"
- "Twitter" - Description: "1200x675 (16:9 ratio)"
- "All platforms" - Description: "Generate all variants"

Then ask:

Question: "What should the images contain?"
Header: "Content"
Options:
- "Logo only" - Description: "Resize my logo for social sharing"
- "Text only" - Description: "Create images from text/slogan"
- "Logo + text" - Description: "Combine logo with text overlay"

Generate: Use

generate_og_images.py

with appropriate parameters

使用AskUserQuestion：

问题："你需要为哪些社交媒体平台生成图片？"
标题："平台"
多选：true
选项：
- "Facebook/WhatsApp/LinkedIn" - 描述："标准1200x630格式"
- "Twitter" - 描述："1200x675（16:9比例）"
- "所有平台" - 描述："生成所有变体"

然后询问：

问题："图片应包含什么内容？"
标题："内容"
选项：
- "仅Logo" - 描述："调整我的logo尺寸用于社交分享"
- "仅文字" - 描述："从文字/标语创建图片"
- "Logo + 文字" - 描述："将logo与文字叠加"

生成：使用

generate_og_images.py

并传入对应的参数

"I need everything for my website"

"我需要为我的网站生成所有资产"

Use AskUserQuestion:

Question: "What source material will you provide?"
Header: "Source"
Options:
- "Logo image" - Description: "I have a logo to use for all assets"
- "Logo + tagline" - Description: "Logo for icons, logo+text for social images"
- "Text only" - Description: "Generate all assets from text/initials"

Generate:

Both favicons and Open Graph images with complete HTML implementation
Provide instructions for file placement and testing

使用AskUserQuestion：

问题："你将提供哪种素材来源？"
标题："素材来源"
选项：
- "Logo图片" - 描述："我有一张logo可用于所有资产"
- "Logo + 标语" - 描述："Logo用于图标，Logo+文字用于社交图片"
- "仅文字" - 描述："从文字/首字母生成所有资产"

生成：

同时生成网站图标和Open Graph图片，以及完整的HTML实现代码
提供文件放置和测试说明

User provides both logo and tagline

用户同时提供logo和标语

Use AskUserQuestion:

Question: "How should I use your logo and tagline?"
Header: "Layout"
Options:
- "Logo above text" - Description: "Logo at top, tagline centered below"
- "Logo + text side-by-side" - Description: "Logo on left, text on right"
- "Text only on social images" - Description: "Use logo for icons, text-only for social sharing"
- "Logo background with text" - Description: "Subtle logo background with prominent text"

Generate: Use

--text

and

--logo

parameters together in

generate_og_images.py

使用AskUserQuestion：

问题："如何使用你的logo和标语？"
标题："布局"
选项：
- "Logo在文字上方" - 描述："Logo在顶部，标语居中在下方"
- "Logo + 文字并排" - 描述："Logo在左侧，文字在右侧"
- "社交图片仅用文字" - 描述："Logo用于图标，社交图片仅用文字"
- "Logo背景+文字" - 描述："淡色Logo背景搭配醒目文字"

生成：在

generate_og_images.py

中同时使用

--text

和

--logo

参数

Dependencies

依赖项

The scripts require:

Python 3.6+

Pillow (PIL):

pip install Pillow --break-system-packages

Pilmoji (for emoji support):
```
pip install pilmoji
```
(optional, only needed for emoji-based generation)
emoji (for emoji suggestions):
```
pip install emoji
```
(optional, only needed for emoji suggestions)

Install if needed before running scripts.

For emoji features, install both:

bash

pip install pilmoji emoji --break-system-packages

脚本需要：

Python 3.6+

Pillow (PIL)：

pip install Pillow --break-system-packages

Pilmoji（用于表情符号支持）：
```
pip install pilmoji
```
（可选，仅在基于表情符号生成时需要）
emoji（用于表情符号建议）：
```
pip install emoji
```
（可选，仅在表情符号建议时需要）

若需要，在运行脚本前安装：

对于表情符号功能，安装两者：

bash

pip install pilmoji emoji --break-system-packages