github-repo-visual-assets

# GitHub Repository Visual Assets Create professional visual assets for GitHub repositories to improve presentation, social sharing, and documentation quality. ## Scope **Best suited for:** - Open source projects needing professional branding - Repositories requiring architecture documentation - Projects optimized for social media sharing (Twitter, LinkedIn, Reddit) - README files needing visual headers **Assets covered:** 1. **Architecture Diagram** (1200x800px) — System architecture visualization 2. **Social Media Card** (1200x630px) — Twitter/LinkedIn/GitHub social preview 3. **README Banner** (1200x300px) — Repository header image ## Design System ### Color Palette Use semantic color mapping for technical components: | Component Type | Fill (rgba) | Stroke (Hex) | Use Case | |----------------|-------------|--------------|----------| | **Frontend/Agent** | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) | UI, client-side, agents | | **Backend/Storage** | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) | APIs, servers, storage | | **Database/Backup** | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) | Databases, backups | | **Cloud/External** | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) | Cloud services, external | ### Typography - **Font:** JetBrains Mono (monospace) — loaded from Google Fonts - **Sizes:** - Title: 48-56px - Subtitle: 20-24px - Body: 14-18px - Small: 9-13px ### Background - **Primary:** `#0f172a` (slate-950) - **Secondary:** `#1e293b` (slate-800) - **Border:** `#334155` (slate-700) - **Grid Pattern:** 40px grid with `#1e293b` lines ## Workflow ### Step 1: Create Assets Directory ```bash mkdir -p assets/{diagrams,images,social} ``` ### Step 2: Generate HTML Assets Create three HTML files with inline CSS/SVG: 1. **Architecture Diagram** (`assets/diagrams/architecture.html`) - Size: 1200x800px - Shows system flow with components - Color-coded by type - Includes legend and info cards 2. **Social Media Card** (`assets/social/social-card.html`) - Size: 1200x630px (Twitter/LinkedIn standard) - Logo + title + tagline - Key features (4 items) - Badges (version, license, status) 3. **README Banner** (`assets/images/banner.html`) - Size: 1200x300px - Wide banner format - Logo + title + subtitle + badges ### Step 3: Review Before Pushing **CRITICAL:** Always let user review visual assets before pushing to GitHub. **Review workflow:** 1. Generate HTML files 2. Send files to user (via MEDIA: or file path) 3. User opens in browser to review 4. Wait for approval or change requests 5. Only after approval: convert to PNG and push **Why:** Visual assets represent the project's brand. User must approve design before it goes public. ### Step 4: Convert to PNG (After Approval) Use headless browser to convert HTML to PNG: ```bash # Chrome (recommended) google-chrome --headless --screenshot=architecture.png --window-size=1200,800 assets/diagrams/architecture.html google-chrome --headless --screenshot=social-card.png --window-size=1200,630 assets/social/social-card.html google-chrome --headless --screenshot=banner.png --window-size=1200,300 assets/images/banner.html # Firefox (alternative) firefox --headless --screenshot architecture.png --window-size=1200,800 assets/diagrams/architecture.html firefox --headless --screenshot social-card.png --window-size=1200,630 assets/social/social-card.html firefox --headless --screenshot banner.png --window-size=1200,300 assets/images/banner.html # Move PNGs to assets mv architecture.png assets/diagrams/ mv social-card.png assets/social/ mv banner.png assets/images/ ``` ### Step 5: Update README Add visual assets to README.md: ```markdown  # Project Title Description... ## Architecture  ``` ### Step 6: Upload Social Card to GitHub 1. Go to repository settings 2. Scroll to "Social preview" 3. Upload `assets/social/social-card.png` 4. Save Now when shared on Twitter/LinkedIn, the card appears automatically. ## Asset Templates ### Architecture Diagram Structure ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>Architecture Diagram</title> <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet"> <style> /* Dark theme styles */ body { font-family: 'JetBrains Mono', monospace; background: #020617; } /* Component boxes, arrows, legend */ </style> </head> <body> <div class="container"> <div class="header"> <h1>System Architecture</h1> </div> <div class="diagram-card"> <svg viewBox="0 0 1200 800"> <!-- Grid, arrows, components --> </svg> </div> <div class="info-grid"> <!-- Info cards --> </div> </div> </body> </html> ``` ### Social Card Structure ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>Social Card</title> <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet"> <style> /* 1200x630 card with gradient background */ .card { width: 1200px; height: 630px; } </style> </head> <body> <div class="card"> <div class="content"> <div class="header"> <div class="icon">🧠</div> <h1>Project Title</h1> </div> <div class="tagline">Key value proposition</div> <div class="features"> <!-- 4 feature boxes --> </div> <div class="footer"> <!-- Badges + URL --> </div> </div> </div> </body> </html> ``` ### Banner Structure ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>Banner</title> <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet"> <style> /* 1200x300 banner */ .banner { width: 1200px; height: 300px; } </style> </head> <body> <div class="banner"> <div class="content"> <div class="logo-section"> <div class="logo">🧠</div> <h1>Project Title</h1> </div> <div class="tagline">Key features</div> <div class="badges"> <!-- Feature badges --> </div> </div> </div> </body> </html> ``` ## Pitfalls ### 1. Pushing Without Review **Problem:** User wants to review visual assets before they go public. **Solution:** Always send HTML files to user first, wait for approval, then convert and push. ### 2. Wrong Sizes **Problem:** Social media platforms have specific size requirements. **Solution:** Use standard sizes: - Architecture: 1200x800px - Social card: 1200x630px (Twitter/LinkedIn/GitHub standard) - Banner: 1200x300px ### 3. Missing Google Fonts **Problem:** HTML files don't load fonts offline. **Solution:** Include Google Fonts CDN link in `<head>`. Files work offline after first load (browser cache). ### 4. Inconsistent Branding **Problem:** Colors/fonts don't match across assets. **Solution:** Use the design system color palette and JetBrains Mono font consistently. ### 5. No Assets README **Problem:** User doesn't know how to use the HTML files. **Solution:** Always create `assets/README.md` with: - Directory structure - How to view (open in browser) - How to convert to PNG - How to add to README - Design system reference ## Related Skills - **architecture-diagram** — For detailed SVG architecture diagrams - **comprehensive-public-repo-setup** — For complete repo setup including visual assets - **github-repo-management** — For managing GitHub repositories ## Examples See `references/mnemosyne-obsidian-example.md` for a complete example from the mnemosyne-obsidian repository.