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

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:

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

# Project Title

Description...

## Architecture

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

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

github-repo-visual-assets

How to add

Drop this on your repo README

Related skills

claude-api

skill-creator

oh-my-issues

claude-mem

Get new Desenvolvimento skills every Monday