The short version
- Open source project branding mostly lives in four places: the logo, the README header, the repository's social preview image and release announcements.
- A good open source logo is simple enough to read at 16 pixels as a favicon and at small size in a dependency list.
- GitHub READMEs can switch a header image between light and dark versions using the HTML picture element and prefers-color-scheme.
- The social preview image is what appears when someone shares the repository link, so it should state the project name and what it does.
- Release posts in a consistent look help users notice new versions and connect them to the same project.
On this page
Open source project branding does not need a design agency. It needs four things done once and kept consistent: a simple logo, a README header that reads in light and dark mode, a social preview image for when the repository is shared, and a recognisable template for release announcements. Together they tell a visitor in a few seconds that the project is maintained and has a point of view, which is often what earns the first star or the first contributor.
Why branding matters for an open source project
Developers judge projects quickly, and they judge by signals of care: a clear README, recent releases, a name that is easy to find again. A consistent visual identity is one of those signals. It also helps people remember your project among several similar libraries, and it gives contributors and conference speakers something to put on a slide. None of it replaces good documentation; it makes good documentation easier to notice.
An open source logo that works at 16 pixels
Your logo will appear as a favicon, a GitHub avatar, a tiny badge on a docs site and occasionally a sticker. Design for the smallest case first. A single bold shape or one letter in a confident typeface beats a detailed illustration. Export an SVG for the web and transparent PNGs for everything else; SVG vs PNG explains which to use where, and favicon design covers the tiny sizes.
Hard to use
- A detailed mascot with thin lines
- Five colours that vanish at small size
- A wordmark too long to read in an avatar
- Only a PNG on a white background
Easy to use
- One shape or letter that reads at 16 px
- One or two colours plus a background
- A short mark for avatars, a wordmark for headers
- SVG plus transparent PNG, light and dark versions
Put the mark on a gradient ground for avatars and headers and it stops looking like a default icon. Keep the gradient behind the logo calm where the logo sits; logo on gradient background explains how.
A README header that works in dark mode
Plenty of developers read GitHub in dark mode, and a header made for white will glow like a torch. GitHub supports the HTML <picture> element in Markdown, so you can serve a light and a dark version of the same header. A 1200×600 banner, the size of a blog banner, is a comfortable width for a README. Dark mode design covers the colour side.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./.github/header-dark.png">
<img alt="Tidepool: a tiny job queue for Postgres" src="./.github/header-light.png" width="600">
</picture>
</p>Put three things on the header: the logo, the project name and a one line description. Badges, install commands and screenshots belong underneath it, in text, where they can be copied and kept up to date.
How to add a GitHub social preview image
When someone pastes your repository link into chat, a forum or a post, the platform shows its social preview image. Without one, GitHub generates a default card from the repository details. You can upload your own in the repository's Settings, under Social preview; GitHub gives its recommended dimensions on that page. Design it from your 1200×630 link preview master and keep words central, so small differences in shape don't crop anything. Open Graph image size explains the crops, and Open Graph tags covers the same image for your docs site.
A social preview at 1200×630: name, one line, nothing near the edges.
Release announcement graphics people notice
Many users hear about a new version from a post rather than the changelog. A consistent release graphic, the same background and layout with only the version number and headline changing, trains people to recognise your announcements. Lead with what users can now do, not the version number alone.
A release post for X or Bluesky at 1600×900: the feature leads, the version supports.
The square version for LinkedIn at 1200×1200, listing the highlights.
Size
Where it appears
Size
Where it appears
Size
Where it appears
Size
Where it appears
Size
Where it appears
Size
Where it appears
- 1
Make the mark
One shape or letter, tested at 16 px. Export SVG and transparent PNG.
- 2
Choose one ground
A gradient or colour that sits well in GitHub's dark and light themes.
- 3
Build the README header
Light and dark versions, logo, name and one line.
- 4
Upload the social preview
Repository Settings, Social preview. Test by pasting the link into a chat.
- 5
Template the release post
Keep the layout; change the version and headline each time.
Gradiently suits maintainers who would rather not open a design tool. It works inside ChatGPT, Claude and any assistant that supports remote MCP servers, so you can ask for a release graphic while writing the release notes, and the design opens in the Studio for a final check. Designs sit on a Mark, a gradient background nobody else can export with once you claim it, so your project's look is genuinely its own. The MCP setup guide takes a few minutes.
Questions people ask
How do I add a social preview image to a GitHub repository?
Open the repository's Settings, find Social preview and upload an image. GitHub shows its recommended dimensions there; keep text central so nothing important is cropped.
How do I make a README image change in dark mode?
Use the HTML picture element with a source for prefers-color-scheme: dark and an img fallback for light. GitHub renders it in Markdown files.
Does an open source project need a logo?
It is not required, but a simple logo makes the project easier to recognise in avatars, docs and talks. Design it to read at favicon size.
What should a release announcement graphic include?
The project name, the version, and the headline feature written as what users can now do. Keep the layout the same for every release.
Written by Gradiently
The team behind Gradiently, a design tool built around Marks: living gradients that make everything you design look like yours.
See our profile