# Open source project branding: README to release notes [Canonical HTML page](https://gradiently.design/guide/open-source-project-branding) Most people meet an open source project through a link preview, a README and a release post. A little branding across those three makes a project look maintained, trusted and worth a star. ## 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. **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](https://gradiently.design/guide/svg-vs-png) explains which to use where, and [favicon design](https://gradiently.design/guide/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](https://gradiently.design/guide/logo-on-gradient-background) explains how. - Terminal blue: `linear-gradient(135deg, #0d1117 0%, #1f2a44 55%, #3b82f6 100%)` - Build green: `radial-gradient(circle at 25% 25%, #a7f3d0 0%, #10b981 45%, #064e3b 100%)` - Release violet: `linear-gradient(160deg, #1a1033 0%, #6d28d9 50%, #f0abfc 100%)` - Warm amber: `linear-gradient(120deg, #fff7ed 0%, #fdba74 50%, #c2410c 100%)` Four project grounds that sit well next to GitHub's dark and light themes. Copy one for avatars, headers and the social preview. ## 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 `` 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](https://gradiently.design/guide/dark-mode-design) covers the colour side. ```html

Tidepool: a tiny job queue for Postgres

``` Paste at the top of README.md. GitHub shows the dark image to readers in dark mode and the light one to everyone else. Export both at 1200×600 and display at 600 wide so they stay sharp on high density screens. 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](https://gradiently.design/guide/open-graph-image-size) explains the crops, and [Open Graph tags](https://gradiently.design/guide/open-graph-tags) covers the same image for your docs site. A landscape social preview image for an open source project called Tidepool, with its one line description 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 landscape release announcement for version 2.0 of an open source project, headlined Retries with backoff A release post for X or Bluesky at 1600×900: the feature leads, the version supports. A square release graphic listing the highlights of Tidepool 2.0 on the same gradient The square version for LinkedIn at 1200×1200, listing the highlights. | Graphic | Size | Where it appears | | --- | --- | --- | | README header | 1200×600 px | Top of the repository | | Social preview | Link preview master, 1200×630 px | Shared repository links | | Release post | 1600×900 px | X and Bluesky | | Release post, square | 1200×1200 px | LinkedIn | | Community banner | 960×540 px | Discord server banner | | Docs site preview | 1200×630 px | Shared docs links | The working set for a project. One master design covers all of them. 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](https://gradiently.design/developers/mcp) takes a few minutes. ## FAQ ### 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.