1. The Three Common Theme Failures
When developers create badges and widgets on their local machine, they usually test only in their own preferred GitHub theme. This causes three pervasive visual defects for visitors with opposite settings:
1. The Invisible Dark Logo Bug:
Brand logos like Next.js, GitHub, Apple, and AWS default to black SVGs. On dark badges or against GitHub's dark mode background (#0d1117), these logos disappear entirely into a dark void.
2. The Blinding White Flash:
Embedding default white-background GitHub stats cards creates an eye-straining white rectangle that breaks the immersion of a dark-themed profile.
3. Low-Contrast White Text on Light Badges:
Using white typography on bright yellow (JavaScript) or cyan (Tailwind) badges causes severe WCAG accessibility contrast failures in light mode.
2. Always Enforce Explicit `logoColor`
The simplest and most reliable fix for technology shields is explicitly setting logoColor in every Shields.io URL:
❌ Risky (Fails in dark mode):
https://img.shields.io/badge/Next.js-black?style=for-the-badge&logo=next.js
✅ Universal (Works in both modes):
https://img.shields.io/badge/Next.js-black?style=for-the-badge&logo=next.js&logoColor=white
3. GitHub's Native Theme-Aware Images
GitHub supports two official mechanisms for serving different image assets based on the viewer’s active theme:
Method A: HTML5 <picture> with prefers-color-scheme
This is the modern web standard supported directly by GitHub’s markdown rendering engine:
<picture> <source media="(prefers-color-scheme: dark)" srcset="https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE&show_icons=true&theme=tokyonight&cache_seconds=86400"> <source media="(prefers-color-scheme: light)" srcset="https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE&show_icons=true&theme=default&cache_seconds=86400"> <img alt="GitHub Stats" src="https://github-readme-stats.vercel.app/api?username=YOUR_HANDLE&show_icons=true&theme=tokyonight&cache_seconds=86400"> </picture>
Method B: GitHub URL Fragment Selectors (#gh-dark-mode-only)
GitHub also parses specific URL hash fragments to toggle CSS display on image elements:
<!-- Visible only in Dark Theme --> <img src="https://example.com/banner-dark.svg#gh-dark-mode-only" alt="Header Banner" /> <!-- Visible only in Light Theme --> <img src="https://example.com/banner-light.svg#gh-light-mode-only" alt="Header Banner" />
4. Verification Workflow Before Committing
Always verify your profile across themes before finalizing:
- Navigate to GitHub → Settings → Appearance.
- Switch to Single theme → Light default and inspect your README.
- Switch to Dark default and Dark dimmed to ensure all badge text and icons retain high contrast.
Generate Dual-Theme Badges in ProfileCrest
ProfileCrest automatically verifies logoColor parameters and high-contrast styling for every generated shield.