ShadcnStore
back to the blog

Dark Mode Done Right: Advanced Theming Techniques with Shadcn UI

Dark Mode Done Right: Advanced Theming Techniques with Shadcn UI

Three months ago, I launched a product with what I thought was perfect dark mode support. Two weeks later, I had 47 support tickets about "broken dark mode" and a 1-star review that simply said "my eyes are bleeding."

The problem wasn't that dark mode didn't work—it did. The problem was that I treated dark mode like an afterthought, a simple color swap that would magically make everything better. I learned the hard way that good dark mode is about much more than inverting colors.

After rebuilding our entire theming system and studying how companies like Linear, Figma, and GitHub handle dark mode, I've developed a systematic approach that actually works. Not just technically, but visually and emotionally too.

Here's everything I wish I'd known from the start.

Why Most Dark Mode Implementations Fail

Before we dive into solutions, let's talk about why dark mode is so hard to get right. Most developers make the same mistakes I did:

Mistake #1: Thinking Dark = Light Inverted
You can't just flip #ffffff to #000000 and call it done. Pure black backgrounds cause eye strain, and high contrast can be jarring.

Mistake #2: Forgetting About Images and Graphics
Your logo might look great on white, but disappear completely on dark backgrounds. Those subtle drop shadows? They become harsh lines.

Mistake #3: Ignoring Color Psychology
Colors behave differently in dark mode. That friendly blue becomes aggressive. That subtle gray becomes invisible. The emotional impact changes completely.

Mistake #4: Not Testing in Real Conditions
Testing dark mode in a bright office at 2 PM is not the same as using it in a dark room at 11 PM, which is when most people actually prefer dark mode.

The good news? Shadcn UI gives us the tools to avoid all these mistakes. We just need to use them thoughtfully.

The Foundation: Understanding Shadcn's Theming Architecture

Shadcn UI's approach to theming is brilliant in its simplicity. Instead of managing hundreds of color variables, you work with a semantic color system based on HSL values:

/* Light mode */
:root {
  --background: 0 0% 100%;          /* Pure white */
  --foreground: 240 10% 3.9%;       /* Nearly black */
  --muted: 240 4.8% 95.9%;          /* Light gray */
  --muted-foreground: 240 3.8% 46.1%; /* Medium gray */
  --border: 240 5.9% 90%;           /* Border gray */
  --primary: 240 5.9% 10%;          /* Dark primary */
  --primary-foreground: 0 0% 98%;   /* Light text on primary */
}

/* Dark mode */
.dark {
  --background: 240 10% 3.9%;       /* Dark background */
  --foreground: 0 0% 98%;           /* Light text */
  --muted: 240 3.7% 15.9%;          /* Dark gray */
  --muted-foreground: 240 5% 64.9%; /* Light gray */
  --border: 240 3.7% 15.9%;         /* Dark border */
  --primary: 0 0% 98%;              /* Light primary */
  --primary-foreground: 240 5.9% 10%; /* Dark text on primary */
}

The beauty of this system is that every component automatically adapts when you switch the dark class. But to make it truly great, we need to go deeper.

Advanced Technique #1: Creating Nuanced Dark Backgrounds

Pure black backgrounds (#000000) are harsh and cause eye strain. The secret is using very dark grays with subtle color temperatures:

/* Basic dark mode - too harsh */
.dark-basic {
  --background: 0 0% 0%;  /* Pure black - avoid this */
}

/* Better dark mode - warm dark */
.dark-warm {
  --background: 20 6% 4%;     /* Very dark brown */
  --card: 20 6% 6%;           /* Slightly lighter for cards */
  --muted: 20 6% 10%;         /* Muted elements */
}

/* Cool dark mode - for tech products */
.dark-cool {
  --background: 220 13% 4%;   /* Very dark blue */
  --card: 220 13% 6%;         /* Card background */
  --muted: 220 13% 10%;       /* Muted elements */
}

/* Neutral dark mode - most versatile */
.dark-neutral {
  --background: 240 5% 4%;    /* Neutral dark gray */
  --card: 240 5% 6%;          /* Card background */
  --muted: 240 5% 10%;        /* Muted elements */
}

I use warm dark for lifestyle products, cool dark for developer tools, and neutral for business applications. The temperature makes a huge difference in how the interface feels.

Advanced Technique #2: Smart Color Adaptation

Not all colors translate well to dark mode. Here's my system for adapting colors:

/* Color adaptation system */
:root {
  /* Light mode colors */
  --success: 142 76% 36%;     /* Forest green */
  --warning: 43 96% 56%;      /* Bright yellow */
  --error: 0 84% 60%;         /* Bright red */
  --info: 217 91% 60%;        /* Bright blue */
}

.dark {
  /* Dark mode - adjusted saturation and lightness */
  --success: 142 70% 45%;     /* Lighter, less saturated green */
  --warning: 43 86% 65%;      /* Less harsh yellow */
  --error: 0 75% 65%;         /* Softer red */
  --info: 217 80% 70%;        /* Gentler blue */
}

The key principles:

  • Increase lightness for better visibility on dark backgrounds
  • Decrease saturation to reduce eye strain
  • Adjust hue slightly to maintain color relationships

Advanced Technique #3: Multi-Theme Support

Sometimes you need more than just light and dark. Here's how to create a complete theming system:

/* Base theme variables */
:root {
  /* Neutral colors - stay consistent across themes */
  --radius: 0.5rem;
  --font-sans: ui-sans-serif, system-ui, sans-serif;

  /* Theme-specific colors will be overridden */
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
}

/* Light theme (default) */
.theme-light {
  --background: 0 0% 100%;
  --foreground: 240 10% 3.9%;
  --primary: 221 83% 53%;
  --primary-foreground: 0 0% 98%;
  --secondary: 210 40% 96%;
  --secondary-foreground: 222 47% 11%;
}

/* Dark theme */
.theme-dark {
  --background: 224 71% 4%;
  --foreground: 213 31% 91%;
  --primary: 217 91% 60%;
  --primary-foreground: 222 47% 11%;
  --secondary: 222 84% 5%;
  --secondary-foreground: 213 31% 91%;
}

/* High contrast theme - for accessibility */
.theme-high-contrast {
  --background: 0 0% 100%;
  --foreground: 0 0% 0%;
  --primary: 0 0% 0%;
  --primary-foreground: 0 0% 100%;
  --secondary: 0 0% 100%;
  --secondary-foreground: 0 0% 0%;
  --border: 0 0% 0%;
}

/* Soft theme - easier on the eyes */
.theme-soft {
  --background: 60 9% 98%;
  --foreground: 24 10% 10%;
  --primary: 25 95% 53%;
  --primary-foreground: 60 9% 98%;
  --secondary: 60 5% 96%;
  --secondary-foreground: 25 5% 45%;
}

Great dark mode isn't about inverting colors—it's about creating a cohesive experience that feels intentional and comfortable. The techniques I've shared here come from real projects and real user feedback.

Advanced Technique #4: Handling Images and Graphics in Dark Mode

This is where most implementations break down. Your beautiful hero image becomes an eyesore in dark mode. Here's my systematic approach:

Image Overlay Technique

// components/adaptive-image.tsx
"use client"

import { useState, useEffect } from "react"
import { cn } from "@/lib/utils"

interface AdaptiveImageProps {
  src: string
  alt: string
  darkOverlay?: boolean
  className?: string
}

export function AdaptiveImage({ src, alt, darkOverlay = false, className }: AdaptiveImageProps) {
  const [isDark, setIsDark] = useState(false)

  useEffect(() => {
    const checkDarkMode = () => {
      setIsDark(document.documentElement.classList.contains('dark'))
    }

    checkDarkMode()

    // Watch for theme changes
    const observer = new MutationObserver(checkDarkMode)
    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })

    return () => observer.disconnect()
  }, [])

  return (
    <div className={cn("relative overflow-hidden", className)}>
      <img src={src} alt={alt} className="w-full h-full object-cover" />
      {isDark && darkOverlay && (
        <div className="absolute inset-0 bg-background/20 backdrop-blur-[0.5px]" />
      )}
    </div>
  )
}

CSS Filter Technique

/* Automatic image adjustments for dark mode */
.dark img:not([data-theme-ignore]) {
  filter: brightness(0.8) contrast(1.1);
}

/* For logos and graphics that need inversion */
.dark .logo-invert {
  filter: invert(1) brightness(0.9);
}

/* For screenshots that need special handling */
.dark .screenshot {
  filter: brightness(0.85) contrast(1.05) saturate(0.9);
  border: 1px solid hsl(var(--border));
  border-radius: calc(var(--radius) - 2px);
}

Advanced Technique #5: Smooth Theme Transitions

Jarring theme switches feel broken. Here's how to make transitions smooth and delightful:

/* Smooth transitions for theme changes */
*,
*::before,
*::after {
  transition:
    background-color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
    border-color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
    color 0.3s cubic-bezier(0.4, 0, 0.2, 1),
    fill 0.3s cubic-bezier(0.4, 0, 0.2, 1),
    stroke 0.3s cubic-bezier(0.4, 0, 0.2, 1),
    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1),
    box-shadow 0.3s cubic-bezier(0.4, 0, 0.2, 1),
    transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

/* Disable transitions for reduced motion preference */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    transition: none !important;
    animation: none !important;
  }
}

/* Special handling for images to prevent flashing */
img {
  transition: filter 0.3s cubic-bezier(0.4, 0, 0.2, 1);
}

Real-World Testing and Implementation

Here's my testing checklist for dark mode:

Visual Testing

  • Bright office lighting
  • Dim room lighting
  • Complete darkness
  • Different devices (desktop, mobile, tablet)
  • Various screen types (LCD, OLED, etc.)

Accessibility Testing

  • Contrast ratios (minimum 4.5:1 for text)
  • Color blind testing (protanopia, deuteranopia, tritanopia)
  • Screen reader compatibility
  • Keyboard navigation in dark mode

Performance Considerations

Dark mode can impact performance if not implemented carefully:

/* Bad - causes repaints on every element */
.dark * {
  background-color: hsl(var(--background));
  color: hsl(var(--foreground));
}

/* Good - uses CSS custom properties efficiently */
.dark {
  --background: 240 10% 3.9%;
  --foreground: 0 0% 98%;
}

/* Elements use the custom properties */
.component {
  background-color: hsl(var(--background));
  color: hsl(var(--foreground));
}

Common Pitfalls and Solutions

  1. Forgetting About Form Elements - Input fields, selectors, and form controls need special dark mode styling
  2. Code Syntax Highlighting - Code blocks need theme-aware color schemes
  3. Third-Party Component Integration - External components may not support your theme system
  4. Image and Media Handling - Photos, videos, and graphics need careful consideration in dark mode
  5. Print Styles - Don't forget that users might print your dark-themed pages

The Bottom Line

Great dark mode isn't about inverting colors—it's about creating a cohesive experience that feels intentional and comfortable. The techniques I've shared here come from real projects and real user feedback.

Start with Shadcn's foundation, then layer on these advanced techniques as needed. Test extensively, especially in real usage conditions. And remember: the best dark mode is the one users don't notice because it just works.

Your users' eyes (and sleep schedules) will thank you.

Want to see all these techniques in action? Check out the ShadcnStore theme showcase where every component demonstrates proper dark mode implementation. You can also grab the complete theme system as a starter template.

Next week, I'll dive into performance optimization for Shadcn components—because beautiful components that load slowly aren't beautiful at all.

Using any of these techniques in your projects? I'd love to see how they work out. Share your dark mode wins (and challenges) in the comments.