majiayu000/spellbook / skills/web-asset-generator
web-asset-generator
VerifiedGenerate web assets including favicons, app icons (PWA), and social media meta images (Open Graph) for Facebook, Twitter, WhatsApp, and LinkedIn. Use when users need icons, favicons, social sharing images, or Open Graph images from logos or text slogans. Handles image resizing, text-to-image generation, and provides proper HTML meta tags.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.7 KB |
| reference/extended.md | markdown | 13.9 KB |
| requirements.txt | manifest | 15 B |
| scripts/generate_favicons.pyexecutable | script | 11.4 KB |
| scripts/generate_og_images.pyexecutable | script | 8.7 KB |
reference/extended.md
View on GitHub# web-asset-generator Extended Reference
This file preserves detailed material moved out of `SKILL.md` for progressive disclosure. Load it only when the current task needs the specific examples, commands, templates, or checklists below.
Moved content starts at: `## Delivering Assets to User`.
## Delivering Assets to User
After generating assets, follow this workflow:
### 1. Move to Outputs Directory
```bash
cp /home/claude/output/* /mnt/user-data/outputs/
```
### 2. Show Generated HTML Tags
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">
```
### 3. Offer Code Integration (Use AskUserQuestion - Pattern 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"
#### If User Selects "Yes, auto-detect my setup":
**A. Detect Framework:**
```bash
# 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
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>
```
#### If User Selects "Yes, I'll tell you where":
1. Ask user for the file path
2. Verify file exists using Read tool
3. Show where tags will be inserted
4. Show diff
5. Insert if user confirms
#### 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)
### 4. Offer Testing Links (Use AskUserQuestion - Pattern 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
### 5. Final Instructions
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
## 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
### 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
### Color Choices
- Ensure sufficient contrast (4.5:1 minimum for readability)
- Use brand colors consistently
- Consider both light and dark mode contexts
## Validation and Quality Checks
Both `generate_og_images.py` and `generate_favicons.py` support automated validation with the `--validate` flag.
### 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
### What Gets Validated
#### For Social Media Images (OG Images)
**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
#### 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)
### 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
### 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!
```
### Integrating Validation into Workflows
**After generating assets**, if validation was NOT run:
1. Show the tip message: "💡 Tip: Use --validate to check file sizes, dimensions, and accessibility"
2. Optionally ask: "Would you like me to run validation on these files now?"
**If validation was run and issues found**:
1. Explain any errors or warnings
2. Offer to fix issues (e.g., resize, recompress, adjust colors)
3. Re-run generation with fixes if user agrees
**If validation passes**:
1. Confirm: "✅ All validation checks passed!"
2. Proceed with code integration and testing links
## Specifications and Platform Details
For detailed platform specifications, size requirements, and implementation guidelines, read:
- `references/specifications.md`: Comprehensive specs for all platforms
## Handling Common Requests
### "Create a favicon for my site"
**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
Text-based example:
```bash
python scripts/generate_favicons.py --text "AI" output/ all --text-bg white --validate
```
### "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
### "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
### User provides both logo and tagline
**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`
## Dependencies
The scripts require:
- Python 3.10+
- 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
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |