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

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:

# 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:

![Banner](assets/images/banner.png)

# Project Title

Description...

## Architecture

![Architecture Diagram](assets/diagrams/architecture.png)

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

<!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.