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 and works seamlessly with both Tailwind CSS v3 and the latest v4. Instead of managing hundreds of color variables, you work with a semantic color system based on OKLCH values that's fully compatible with Tailwind's CSS-first configuration:

/* Modern OKLCH-based theming for Shadcn UI with Tailwind v4 */
@import "tailwindcss";

:root {
  --background: oklch(1 0 0);                    /* Pure white */
  --foreground: oklch(0.13 0.028 261.692);       /* Nearly black */
  --card: oklch(1 0 0);                          /* White cards */
  --card-foreground: oklch(0.13 0.028 261.692);  /* Dark text on cards */
  --primary: oklch(0.21 0.034 264.665);          /* Dark primary */
  --primary-foreground: oklch(0.985 0.002 247.839); /* Light text on primary */
  --secondary: oklch(0.967 0.003 264.542);       /* Light gray */
  --secondary-foreground: oklch(0.21 0.034 264.665); /* Dark text on secondary */
  --muted: oklch(0.967 0.003 264.542);           /* Muted backgrounds */
  --muted-foreground: oklch(0.551 0.027 264.364); /* Muted text */
  --border: oklch(0.928 0.006 264.531);          /* Border color */
  --input: oklch(0.928 0.006 264.531);           /* Input borders */
  --ring: oklch(0.707 0.022 261.325);            /* Focus rings */
  --destructive: oklch(0.577 0.245 27.325);      /* Error/danger */
  --destructive-foreground: oklch(0.985 0.002 247.839); /* Error text */
}

.dark {
  --background: oklch(0.13 0.028 261.692);       /* Dark background */
  --foreground: oklch(0.985 0.002 247.839);      /* Light text */
  --card: oklch(0.21 0.034 264.665);             /* Dark cards */
  --card-foreground: oklch(0.985 0.002 247.839); /* Light text on cards */
  --primary: oklch(0.928 0.006 264.531);         /* Light primary */
  --primary-foreground: oklch(0.21 0.034 264.665); /* Dark text on primary */
  --secondary: oklch(0.278 0.033 256.848);       /* Dark gray */
  --secondary-foreground: oklch(0.985 0.002 247.839); /* Light text on secondary */
  --muted: oklch(0.278 0.033 256.848);           /* Dark muted */
  --muted-foreground: oklch(0.707 0.022 261.325); /* Light muted text */
  --border: oklch(1 0 0 / 10%);                  /* Semi-transparent border */
  --input: oklch(1 0 0 / 15%);                   /* Semi-transparent input */
  --ring: oklch(0.551 0.027 264.364);            /* Focus rings */
  --destructive: oklch(0.704 0.191 22.216);      /* Error/danger */
  --destructive-foreground: oklch(0.985 0.002 247.839); /* Error text */
}

/* Tailwind v4 @theme integration */
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
}

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 with OKLCH

Pure black backgrounds (#000000) are harsh and cause eye strain. The secret is using very dark grays with subtle color temperatures in OKLCH color space, which provides better perceptual uniformity:

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

/* Better dark mode - warm dark with OKLCH */
.dark-warm {
  --background: oklch(0.04 0.01 50);     /* Very dark warm brown */
  --card: oklch(0.06 0.01 50);           /* Slightly lighter for cards */
  --muted: oklch(0.10 0.01 50);          /* Muted elements */
}

/* Cool dark mode - for tech products */
.dark-cool {
  --background: oklch(0.04 0.02 250);    /* Very dark blue */
  --card: oklch(0.06 0.02 250);          /* Card background */
  --muted: oklch(0.10 0.02 250);         /* Muted elements */
}

/* Neutral dark mode - most versatile (shadcn/ui default) */
.dark-neutral {
  --background: oklch(0.13 0.028 261.692);    /* Neutral dark gray */
  --card: oklch(0.21 0.034 264.665);          /* Card background */
  --muted: oklch(0.278 0.033 256.848);        /* 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. OKLCH gives us precise control over perceived lightness and color temperature.

Advanced Technique #2: Smart Color Adaptation with OKLCH

Not all colors translate well to dark mode. Here's my system for adapting colors using OKLCH for better perceptual uniformity:

/* Color adaptation system with OKLCH */
:root {
  /* Light mode colors */
  --success: oklch(0.6 0.2 142);     /* Forest green */
  --warning: oklch(0.7 0.15 85);     /* Bright yellow */
  --error: oklch(0.62 0.23 25);      /* Bright red */
  --info: oklch(0.65 0.18 252);      /* Bright blue */
}

.dark {
  /* Dark mode - adjusted for better visibility and reduced eye strain */
  --success: oklch(0.7 0.17 142);    /* Lighter, less saturated green */
  --warning: oklch(0.75 0.12 85);    /* Less harsh yellow */
  --error: oklch(0.68 0.20 25);      /* Softer red */
  --info: oklch(0.72 0.15 252);      /* Gentler blue */
}

The key principles with OKLCH:

  • Increase lightness (L) for better visibility on dark backgrounds
  • Decrease chroma (C) to reduce eye strain while maintaining color identity
  • Keep hue (H) consistent to maintain semantic meaning
  • OKLCH provides perceptual uniformity - equal lightness values appear equally bright

Advanced Technique #3: Multi-Theme Support with OKLCH

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

/* Base theme variables with Tailwind v4 @theme */
@theme {
  --radius: 0.5rem;
  --font-sans: ui-sans-serif, system-ui, sans-serif;
}

/* Light theme (default) with OKLCH */
.theme-light {
  --background: oklch(1 0 0);
  --foreground: oklch(0.2 0.01 240);
  --primary: oklch(0.56 0.19 252);
  --primary-foreground: oklch(0.98 0 0);
  --secondary: oklch(0.96 0.005 240);
  --secondary-foreground: oklch(0.15 0.02 240);
}

/* Dark theme with OKLCH */
.theme-dark {
  --background: oklch(0.13 0.028 261.692);
  --foreground: oklch(0.91 0.01 240);
  --primary: oklch(0.65 0.18 252);
  --primary-foreground: oklch(0.15 0.02 240);
  --secondary: oklch(0.18 0.025 264);
  --secondary-foreground: oklch(0.91 0.01 240);
}

/* High contrast theme - for accessibility */
.theme-high-contrast {
  --background: oklch(1 0 0);
  --foreground: oklch(0 0 0);
  --primary: oklch(0 0 0);
  --primary-foreground: oklch(1 0 0);
  --secondary: oklch(1 0 0);
  --secondary-foreground: oklch(0 0 0);
  --border: oklch(0 0 0);
}

/* Soft theme - easier on the eyes with OKLCH */
.theme-soft {
  --background: oklch(0.98 0.005 60);
  --foreground: oklch(0.15 0.01 24);
  --primary: oklch(0.6 0.2 25);
  --primary-foreground: oklch(0.98 0.005 60);
  --secondary: oklch(0.96 0.003 60);
  --secondary-foreground: oklch(0.5 0.02 25);
}

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 oklch(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: var(--background);
  color: var(--foreground);
}

/* Good - uses CSS custom properties efficiently with OKLCH */
.dark {
  --background: oklch(0.13 0.028 261.692);
  --foreground: oklch(0.98 0 0);
}

/* Elements use the custom properties */
.component {
  background-color: oklch(var(--background));
  color: oklch(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—covering React 18+ concurrent features, server component patterns, and the latest bundle optimization techniques for modern React applications.

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.