GitHub README Dark Mode Design Tips (2026 Guide)

GitHub has supported system-preference-based dark mode since 2021, and the majority of developers now browse GitHub in dark mode. Your profile README is displayed against either a dark (#0D1117) or light (#FFFFFF) background depending on each visitor's preference — and you have no way of knowing which one they are using.

This creates a design challenge that most profile READMEs fail to address: images, colors, and visual elements optimized for one background often look poor or illegible against the other. A dark banner image that looks sleek in dark mode becomes a dark rectangle on a white background with no visual separation. A light-colored typing animation that pops against dark backgrounds becomes nearly invisible in light mode.

This guide covers the practical techniques for building a GitHub profile README that looks good in both modes.

How GitHub Handles Dark and Light Mode

Before solving the problem, understand the mechanics:

1. GitHub's renderer detects your system preference via CSS prefers-color-scheme. The GitHub interface switches; your README content does not automatically switch.

2. Plain text and markdown elements (headings, paragraphs, code blocks, tables) adapt automatically — GitHub's CSS handles text color changes. You do not need to worry about heading colors.

3. Images embedded with standard markdown (![alt](url)) do not adapt. The same image file renders against whichever background is active. A transparent PNG background appears as dark or light depending on the viewer.

4. HTML <picture> elements with prefers-color-scheme media queries — This is the correct solution for images that need to differ between modes.

5. Inline SVGs and SVG services — Some services (Capsule Render, readme-typing-svg) accept a theme parameter; others require you to provide two separate URLs.

Technique 1: The <picture> Element for Mode-Aware Images

The most reliable solution for any image that needs to look different in dark vs. light mode:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./assets/banner-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="./assets/banner-light.svg">
  <img alt="Profile Banner" src="./assets/banner-light.svg">
</picture>

GitHub's markdown renderer passes <picture> elements through, allowing the browser's native prefers-color-scheme detection to serve the appropriate image.

The fallback <img> at the bottom should point to whichever version looks acceptable in more contexts — typically the light version, since a light image on a white background blends rather than clashes.

Creating Dark and Light Variants

For SVG files, creating two variants is straightforward — change the background color and text/element colors:

Light version (banner-light.svg):

<svg>
  <rect fill="#FFFFFF" .../>
  <text fill="#24292F">Your Name</text>
</svg>

Dark version (banner-dark.svg):

<svg>
  <rect fill="#0D1117" .../>
  <text fill="#E6EDF3">Your Name</text>
</svg>

Commit both to your profile repository and reference them with the <picture> element.

Technique 2: Transparent Background Images

For images where the content (not the background) is what matters — icons, logos, diagrams — use PNG or SVG with a transparent background. The image content renders on whatever background GitHub displays:

![Logo](./assets/logo-transparent.png)

Caveat: Transparent backgrounds work well only if your image's colors have sufficient contrast against both dark and light backgrounds. A white logo on transparent background is invisible in light mode. A dark icon on transparent background is invisible in dark mode.

The solution: Use medium-contrast colors, or use two separate images with the <picture> element.

Technique 3: Dark-Mode-Aware Badge Colors

Shields.io badges use opaque background colors that render fine in any mode — the badge container has its own background regardless of the page background. However, your choice of badge color still matters for readability and visual coherence.

Colors that work well in both modes:

• Medium blues: #0075ca, #1DA1F2
• Medium greens: #3cb371, #28a745
• Medium purples: #6f42c1, #663399
• Technology-standard colors (Python yellow #3776AB, TypeScript blue #3178C6, etc.)

Colors to avoid:

• Very light colors (#EEEEEE, #F8F9FA) — washed out in light mode, invisible in dark
• Very dark colors (#111111, #0D0D0D) — invisible in dark mode
• Pure white text on light backgrounds

<!-- These color combinations work in both modes -->
![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)

Technique 4: Service-Specific Theme Parameters

Several popular README services accept a theme parameter that selects a dark or light variant. But since you cannot know the visitor's preference at request time, you have two options:

Option A: Pick One Theme

Choose the theme that the majority of your visitors will prefer (dark, for most developer audiences), and accept that light mode users will see a mismatched widget:

![GitHub Stats](https://github-readme-stats.vercel.app/api?username=you&theme=dark)

This is the simplest approach and acceptable for many profiles. The visual mismatch in light mode is noticeable but not a critical problem.

Option B: Use <picture> with Two Theme URLs

For services that generate different URLs per theme, combine with the <picture> element:

<picture>
  <source
    media="(prefers-color-scheme: dark)"
    srcset="https://github-readme-stats.vercel.app/api?username=you&theme=dark&bg_color=0D1117">
  <source
    media="(prefers-color-scheme: light)"
    srcset="https://github-readme-stats.vercel.app/api?username=you&theme=default">
  <img src="https://github-readme-stats.vercel.app/api?username=you&theme=default" alt="GitHub Stats">
</picture>

This is the cleanest approach — each visitor sees the appropriate theme. The downside is verbosity in your markdown.

Option C: The color_mode Parameter (Capsule Render)

Capsule Render supports a color_mode parameter that generates both light and dark CSS within a single SVG:

![Header](https://capsule-render.vercel.app/api?type=waving&color=gradient&height=200&section=header&text=Name&animation=twinkling)

When color is set to gradient or auto, Capsule Render generates gradients that look reasonable in both modes without requiring separate images.

Technique 5: GitHub's Native Dark Mode SVG Support

GitHub uses a CSS variable system for its UI colors. SVGs that reference these CSS variables via currentColor or GitHub's color tokens adapt automatically:

<svg>
  <!-- This adapts to dark/light mode automatically -->
  <text fill="currentColor">Adapts automatically</text>
</svg>

The currentColor keyword inherits the parent element's color property, which GitHub sets appropriately for each mode. Use fill="currentColor" for text and icon elements in custom SVGs.

Important: This only works for SVGs embedded inline via HTML <img> tags with the SVG hosted on raw.githubusercontent.com. External SVG services that generate SVGs with hardcoded colors will not inherit currentColor.

Practical Color Palette for Mode-Adaptive READMEs

These color combinations have good contrast against both GitHub's dark (#0D1117) and light (#FFFFFF) backgrounds:

Text and Accent Colors

| Color Name | Hex | Works On | |------------|-----|----------| | GitHub Blue | #58A6FF | Dark mode backgrounds | | Primary Blue | #0075CA | Light mode backgrounds | | Adaptive Blue | #1565C0 | Both (medium contrast) | | Adaptive Green | #2DA44E | Both | | Adaptive Purple | #8957E5 | Both (good for both) | | Adaptive Orange | #F78166 | Dark primarily |

Background Colors (for SVG shapes)

| Color | Hex | Notes | |-------|-----|-------| | GitHub Dark | #0D1117 | Native dark mode background | | GitHub Card Dark | #161B22 | Dark mode card/panel background | | GitHub Light | #FFFFFF | Native light mode background | | GitHub Light Border | #D0D7DE | Light mode borders |

Testing Your README in Both Modes

Before publishing, test your profile in both modes:

1. GitHub's built-in preview: Commit your README and view your profile. Toggle dark/light mode in your system or browser preferences and reload.

2. Browser developer tools: In Chrome DevTools, open the Rendering panel (three dots → More tools → Rendering) and set "Emulate CSS media feature prefers-color-scheme" to dark or light without changing your system setting.

3. Private browser window: Some browsers remember theme per window. Open an incognito window and change the theme there for isolated testing.

Check these elements specifically:

• Are all images visible and legible in both modes?
• Do badge colors look correct in both modes?
• Are there any elements where the text becomes unreadable in either mode?
• Do animated SVGs from external services look reasonable in both modes?

What You Do Not Need to Worry About

Plain markdown content — Headings, paragraphs, bold/italic text, code blocks, tables, and bullet points all adapt automatically. GitHub handles text color in dark and light modes.

GitHub's pinned repository cards — These render with GitHub's native UI, which adapts automatically to the active theme.

Code blocks — GitHub renders code blocks with syntax highlighting adapted to the current theme. Your code examples look fine in both modes without any special handling.

Frequently Asked Questions

How do I know if my GitHub profile uses dark mode by default?

GitHub follows your system preference. You can force-override it in GitHub's settings under Appearance → Theme preferences. Most developers have dark mode enabled at the system level, meaning most of your profile visitors will see your dark mode design.

Do I need to support both modes if my target audience is mostly developers?

Developers predominantly use dark mode, but not exclusively. If your profile is targeting enterprise hiring managers or a general audience, light mode matters more. For developer-to-developer profiles, a single dark-mode-optimized design is acceptable.

Does prefers-color-scheme in <picture> elements work on GitHub Mobile?

Yes. GitHub's mobile app respects the device's color scheme preference, and the <picture> element's media queries work correctly in the mobile web view.

What happens to my README when GitHub adds new themes?

GitHub has added additional themes beyond just dark/light (dark dimmed, dark high contrast). The prefers-color-scheme media query only distinguishes between dark and light preference — your images will not automatically adapt to GitHub's additional theme variants. For most profiles, this is an acceptable limitation.

---

A mode-adaptive GitHub profile README is a polish detail that the majority of developers overlook. Getting it right signals design thinking and attention to detail that extends beyond code. Our AI README Generator creates README content with dark mode in mind — you add the mode-specific image variants on top.