React'te Renk Teması: CSS Değişkenleri ve Context

Tema, ölçekte sürdürmek zorunda kalana kadar basit görünen sorunlardan biridir. Açık ve koyu mod arasındaki tek geçiş basittir. Birden fazla markaya hizmet eden, kullanıcı tarafından özelleştirilebilir paletler sunan veya sayfa yenilenmeden anında tema geçişi yapması gereken bir ürün, daha kasıtlı bir mimari gerektirir.

React'in bileşen modeli ve CSS özel özellikleri, tema için doğal bir eşleşmedir. CSS değişkenleri renk değerlerini bildirimsel olarak yönetir; React Context tema durumunu yönetir; ve Tailwind CSS (modern projelerde) her ikisini de köprüler. Bu kılavuz her katmanı kapsar — tema mimarisini nasıl yapılandırılacağını, CSS değişkeni temelini nasıl uygulayacağını, React state'ini nasıl bağlayacağını ve çok markalı senaryoları nasıl yöneteceğini.

Tema Mimarisi Desenleri

Desen 1: Yalnızca CSS Değişkenleri (JavaScript Durumu Yok)

Temel koyu mod desteği için en basit desen, hiç React state'i gerektirmez. Bir prefers-color-scheme medya sorgusu özel özellik değerlerini değiştirir ve her bileşen otomatik olarak güncellenir:

/* globals.css */
:root {
  --color-bg: #F8FAFC;
  --color-text: #1E293B;
  --color-brand: #2563EB;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #0F172A;
    --color-text: #F1F5F9;
    --color-brand: #60A5FA;
  }
}

Bileşenler var(--color-bg) kullanır ve mevcut tema hakkında hiçbir şey bilmesi gerekmez. Tarayıcı her şeyi yönetir.

Ne zaman kullanılır: İşletim sistemi düzeyindeki tercihe saygı göstermek ve kullanıcı tarafından kontrol edilen bir geçiş gerektirmeyen siteler.

Sınırlama: Kullanıcıların uygulama içinde işletim sistemi ayarını geçersiz kılma yolu yoktur.

Desen 2: Veri Özelliği Tema Geçişi

<html> öğesine bir data-theme özelliği eklemek, aktif temayı açık ve geçersiz kılınabilir hale getirir. Bu SSR ile uyumludur, yanlış tema flaşını önler ve localStorage kalıcılığıyla önemsiz şekilde birleştirilir:

/* Varsayılan: açık */
[data-theme="light"],
:root {
  --color-bg: #F8FAFC;
  --color-text: #1E293B;
  --color-brand: #2563EB;
  --color-surface: #FFFFFF;
  --color-border: #E2E8F0;
}

/* Koyu */
[data-theme="dark"] {
  --color-bg: #0F172A;
  --color-text: #F1F5F9;
  --color-brand: #60A5FA;
  --color-surface: #1E293B;
  --color-border: #334155;
}

// İlk boyamadan önce temayı uygula (satır içi script <head>'de)
const savedTheme = localStorage.getItem('theme') || 'light';
document.documentElement.setAttribute('data-theme', savedTheme);

Ne zaman kullanılır: Kullanıcı tarafından kontrol edilen geçiş gerektiren çoğu üretim uygulaması. Veri özelliği yaklaşımı mevcut endüstri standardıdır.

Desen 3: Sınıf Tabanlı Tema Geçişi

Veri özelliğine benzer, ancak CSS sınıfları kullanır. Tailwind'in darkMode: 'class' yapılandırması bu desene dayanır:

.dark {
  --color-bg: #0F172A;
  --color-text: #F1F5F9;
}

<html>'ye dark sınıfını eklemek koyu token değerlerini etkinleştirir.

Ne zaman kullanılır: class koyu mod stratejisiyle Tailwind CSS kullanan projeler.

Renkler İçin CSS Değişkenleri: Token Sistemi

Açıklayıcı Adlandırma Yerine Anlamsal Adlandırma

Token sistemindeki en önemli karar adlandırmadır. Renk değerine göre adlandırma (--blue-500, --gray-900), değişkeni izole olarak anlamayı kolaylaştırır ama temayı imkânsız kılar.

Anlamsal role göre adlandırma (--color-brand, --color-text-muted), temalar genelinde değerlerin tamamen değişmesine izin verirken bileşenlerin doğru kalmasını sağlar:

:root {
  /* ---- Renk İlkelleri (bileşenlerde doğrudan kullanılmaz) ---- */
  --blue-500: #3B82F6;
  --blue-700: #1D4ED8;
  --slate-50: #F8FAFC;
  --slate-800: #1E293B;
  --slate-900: #0F172A;

  /* ---- Anlamsal Tokenlar (bileşenlerde kullanılır) ---- */
  --text-primary: var(--slate-800);
  --text-secondary: #64748B;
  --text-disabled: #94A3B8;
  --text-inverse: var(--slate-50);

  --bg-base: var(--slate-50);
  --bg-elevated: #FFFFFF;
  --bg-sunken: #F1F5F9;

  --brand: var(--blue-700);
  --brand-hover: #1E40AF;
  --brand-subtle: #EFF6FF;
  --on-brand: #FFFFFF;

  --error: #DC2626;
  --error-bg: #FEF2F2;
  --success: #16A34A;
  --success-bg: #F0FDF4;
  --warning: #D97706;
  --warning-bg: #FFFBEB;
}

[data-theme="dark"] {
  --text-primary: #F1F5F9;
  --text-secondary: #94A3B8;
  --text-disabled: #475569;
  --text-inverse: #0F172A;

  --bg-base: #0F172A;
  --bg-elevated: #1E293B;
  --bg-sunken: #0D1426;

  --brand: #60A5FA;
  --brand-hover: #93C5FD;
  --brand-subtle: #172554;
  --on-brand: #0F172A;

  --error: #F87171;
  --error-bg: #1C0A0A;
  --success: #4ADE80;
  --success-bg: #052E16;
  --warning: #FCD34D;
  --warning-bg: #1C1000;
}

Renk Ölçeğinizi Oluşturma

Token sistemini oluşturmadan önce ham renk paletine ihtiyacınız var. Gölge Oluşturucu, tek bir marka renginden tam 50–950 ölçeği üretir. Marka hex kodunuzu girin ve Tailwind CSS tarafından kullanılan ölçek deseninin tam setini alın.

Tema Durumu İçin React Context

ThemeContext Deseni

Kullanıcı tarafından kontrol edilen tema geçişi olan uygulamalar için React Context durum yönetimi katmanını sağlar:

// contexts/ThemeContext.tsx
import { createContext, useContext, useEffect, useState } from 'react';

type Theme = 'light' | 'dark' | 'system';

interface ThemeContextValue {
  theme: Theme;
  resolvedTheme: 'light' | 'dark';
  setTheme: (theme: Theme) => void;
}

const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setThemeState] = useState<Theme>(() => {
    if (typeof window === 'undefined') return 'system';
    return (localStorage.getItem('theme') as Theme) || 'system';
  });

  const systemPrefersDark = typeof window !== 'undefined'
    ? window.matchMedia('(prefers-color-scheme: dark)').matches
    : false;

  const resolvedTheme: 'light' | 'dark' =
    theme === 'system'
      ? (systemPrefersDark ? 'dark' : 'light')
      : theme;

  useEffect(() => {
    const root = document.documentElement;
    root.setAttribute('data-theme', resolvedTheme);
    localStorage.setItem('theme', theme);
  }, [theme, resolvedTheme]);

  useEffect(() => {
    if (theme !== 'system') return;
    const media = window.matchMedia('(prefers-color-scheme: dark)');
    const handler = () => {
      document.documentElement.setAttribute(
        'data-theme',
        media.matches ? 'dark' : 'light'
      );
    };
    media.addEventListener('change', handler);
    return () => media.removeEventListener('change', handler);
  }, [theme]);

  const setTheme = (newTheme: Theme) => {
    setThemeState(newTheme);
  };

  return (
    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme(): ThemeContextValue {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error('useTheme must be used within ThemeProvider');
  return ctx;
}

Yanlış Tema Flaşını Önleme (FOTWT)

Sunucu tarafında render edilen uygulamalar, yanlış tema flaşı sorunuyla karşılaşır. Çözüm, localStorage'ı okuyan ve sayfa render edilmeden önce tema özelliğini uygulayan <head>'de engelleme satır içi script'tir:

<!-- <head>'inizde, CSS bağlantılarından önce -->
<script>
  (function() {
    try {
      var stored = localStorage.getItem('theme');
      var systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
      var theme = stored === 'dark' || stored === 'light'
        ? stored
        : (systemDark ? 'dark' : 'light');
      document.documentElement.setAttribute('data-theme', theme);
    } catch(e) {}
  })();
</script>

Tailwind CSS Temaları

Tailwind v3: Sınıf Tabanlı Koyu Mod

Tailwind v3'te koyu mod, tailwind.config.js'de darkMode: 'class' ayarını gerektirir:

// tailwind.config.js
module.exports = {
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#EFF6FF',
          500: '#3B82F6',
          600: '#2563EB',
          700: '#1D4ED8',
          950: '#172554',
        },
      },
    },
  },
};

<div className="bg-white dark:bg-slate-900 text-slate-800 dark:text-slate-100">
  <button className="bg-brand-600 dark:bg-brand-500 text-white">
    Birincil Eylem
  </button>
</div>

Tailwind v4: CSS-Önce Yapılandırma

Tailwind v4, yapılandırmayı tamamen CSS'e taşır:

/* styles.css */
@import "tailwindcss";

@theme {
  --color-brand-50: #EFF6FF;
  --color-brand-500: #3B82F6;
  --color-brand-600: #2563EB;
  --color-brand-700: #1D4ED8;
}

Çok Markalı Tema Stratejisi

Zorluk

Birden fazla istemciye hizmet eden bir SaaS platformu, yalnızca koyu/açık varyantları değil, tamamen farklı renk kimliklerini işlemesi gerekir.

CSS Değişken Geçersiz Kılmaları Olarak Marka Tokenları

/* Temel tema — tüm markalar için aynı token adları */
:root {
  --brand-primary-raw: 37 99 235; /* #2563EB RGB kanallarında */
  --brand-accent-raw: 99 102 241; /* #6366F1 RGB kanallarında */

  --brand-primary: rgb(var(--brand-primary-raw));
  --brand-primary-hover: color-mix(in srgb, rgb(var(--brand-primary-raw)) 80%, black);
  --brand-primary-subtle: color-mix(in srgb, rgb(var(--brand-primary-raw)) 10%, white);
}

/* Marka: Acme Corp (mavi) */
[data-brand="acme"] {
  --brand-primary-raw: 37 99 235;   /* #2563EB */
  --brand-accent-raw: 16 185 129;   /* #10B981 */
}

/* Marka: Globex Inc (mor) */
[data-brand="globex"] {
  --brand-primary-raw: 124 58 237;  /* #7C3AED */
  --brand-accent-raw: 245 158 11;   /* #F59E0B */
}

Gölge Oluşturucu ile Marka Ölçekleri Oluşturma

Her marka için yalnızca bir veya iki hex değeri değil, tam bir renk ölçeği gerekir. Her markanın birincil ve aksan renginden 50–950 ölçeği oluşturmak için Gölge Oluşturucu'yu kullanın.

Temel Çıkarımlar

CSS özel özellikleri temelin temelidir: Anlamsal tokenları (--text-primary, --brand-primary) tanımlayın ve değerlerini tema başına değiştirin.
Veri özelliği tema geçişi (data-theme="dark") en esnek desendir — JavaScript tarafından geçersiz kılınabilir, SSR ile uyumlu.
İki katmanlı token sistemi (ilkel renk ölçeği + anlamsal rol tokenları) bileşenleri temiz tutarken tam tema esnekliği sağlar.
Marka birincilinden tam 50–950 renk ölçeği oluşturmak için Gölge Oluşturucu'yu kullanın.
React Context tema durumunu yönetir; bileşenlerin doğru renkleri uygulamak için context okumalarına gerek yoktur.
Yanlış tema flaşını önlemek için <head>'de localStorage'ı okuyan engelleme satır içi script kullanın.
Çok markalı tema, tema sistemi üzerine başka bir veri özelliği (data-brand) yığar.