kevinnft 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:
- Architecture Diagram (1200x800px) — System architecture visualization
- Social Media Card (1200x630px) — Twitter/LinkedIn/GitHub social preview
- 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
#1e293blines
Workflow
Step 1: Create Assets Directory
mkdir -p assets/{diagrams,images,social}
Step 2: Generate HTML Assets
Create three HTML files with inline CSS/SVG:
Architecture Diagram (
assets/diagrams/architecture.html)- Size: 1200x800px
- Shows system flow with components
- Color-coded by type
- Includes legend and info cards
Social Media Card (
assets/social/social-card.html)- Size: 1200x630px (Twitter/LinkedIn standard)
- Logo + title + tagline
- Key features (4 items)
- Badges (version, license, status)
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:
- Generate HTML files
- Send files to user (via MEDIA: or file path)
- User opens in browser to review
- Wait for approval or change requests
- 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:
# 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:
# Project Title
Description...
## Architecture
Step 6: Upload Social Card to GitHub
- Go to repository settings
- Scroll to "Social preview"
- Upload
assets/social/social-card.png - Save
Now when shared on Twitter/LinkedIn, the card appears automatically.
Asset Templates
Architecture Diagram Structure
<!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
<!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
<!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.