shadcn/ui tema rehberi: CSS değişkenleri, renkler ve temel paletler

İki yaklaşım: CSS değişkenleri ve yardımcı sınıflar

Tema belgesi iki seçenek sunar ve CSS değişkenlerini önerir. Değişken yaklaşımında bileşenler anlamsal sınıflar kullanır: bir kart bg-card, bir düğme bg-primary sınıfı taşır. Bu sınıfların gerçek rengi değişkenden gelir, bu yüzden tek bir değişkeni değiştirdiğinizde o rengi kullanan her bileşen güncellenir. Seçimi components.json içindeki tailwind.cssVariables alanı belirler:

{
  "style": "new-york",
  "rsc": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Değeri false yaparsanız CLI bileşenleri doğrudan Tailwind renk sınıflarıyla üretir. Belgedeki örnekte bir öğe bg-zinc-950 dark:bg-white gibi sınıflar taşır; koyu tema rengi her bileşende ayrıca yazılır. Bu yaklaşımda renk değiştirmek, ilgili sınıfları dosyalarda tek tek değiştirmek demektir.

Bu seçim sonradan kolayca değiştirilemez. components.json belgesi tailwind.cssVariables için açıkça "başlatmadan sonra değiştirilemez" uyarısı yapar ve iki yaklaşım arasında geçiş için bileşenleri silip yeniden kurmanız gerektiğini söyler. CLI tarafında aynı seçim init ve add komutlarındaki --css-variables (varsayılan true) ve --no-css-variables seçenekleriyle yapılır.

background ve foreground kuralı

Değişken adları basit bir kurala uyar: bir rengin kendisi bileşenin arka planı için, aynı adın -foreground ile biten eşi ise o arka planın üzerindeki metin için kullanılır. Arka plan için kullanılan değişkende background son eki yazılmaz. Yani --primary ana rengin arka planı, --primary-foreground ise o rengin üzerindeki yazıdır:

:root {
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

<div className="bg-primary text-primary-foreground">Merhaba</div>

Bu örnekte öğenin arka planı var(--primary), metin rengi var(--primary-foreground) olur. Kural tüm çiftlere uygulanır: card ve card-foreground, muted ve muted-foreground, sidebar-primary ve sidebar-primary-foreground gibi. Kendi renk çiftlerinizi eklerken aynı kurala uymak, bileşenleri okuyan herkesin rengin nerede kullanılacağını adından anlamasını sağlar.

Değişken listesi

Tema belgesindeki app/globals.css listesi, :root ve .dark için aynı adları içerir. Değişkenleri görevlerine göre şöyle gruplayabiliriz:

Varsayılan neutral temada açık mod değerlerinden bazıları şöyledir: --radius: 0.625rem, --background: oklch(1 0 0), --foreground: oklch(0.145 0 0), --primary: oklch(0.205 0 0), --destructive: oklch(0.577 0.245 27.325). Koyu modda --border ve --input değerleri saydamlık içerir: oklch(1 0 0 / 10%) ve oklch(1 0 0 / 15%). Kenar çubuğu değişkenleri sidebar menü ve gruplar, grafik renkleri ise shadcn chart yazısında ayrıca kullanılır.

--radius tek başına kullanılmaz; manuel kurulum sayfasındaki @theme inline bloğu ondan türetilen dört köşe değeri tanımlar. Böylece tek bir değeri değiştirerek tüm bileşenlerin köşe yuvarlaklığını orantılı olarak ayarlayabilirsiniz:

@theme inline {
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

Değişkenler Tailwind sınıflarına nasıl bağlanır?

:root içindeki --primary tek başına bir CSS değişkenidir; bg-primary sınıfının var olması için Tailwind'e bu rengin tanıtılması gerekir. Manuel kurulum sayfasındaki globals.css bunu @theme inline bloğunda yapar: her değişken --color- önekli bir tema değişkenine eşlenir. Aynı dosyanın sonundaki temel katman da tüm öğelere varsayılan kenarlık rengini ve body öğesine arka plan ile metin rengini verir.

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... diğer renkler aynı biçimde ... */
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

Tailwind v4 geçiş sayfası bu yapının nedenini de açıklar: değerler doğrudan değişkenlerde tam renk olarak durduğu için tema renklerine hem yardımcı sınıflardan hem de CSS dışından, örneğin JavaScript içinden erişmek kolaylaşır. @theme yönergesinin genel söz dizimi Tailwind'in konusudur; ayrıntı için Tailwind CSS v4 yenilikleri yazısına bakabilirsiniz.

Yeni bir renk eklemek

Kendi anlamsal renginizi, örneğin bir uyarı rengini eklemek üç adımdır: değişkeni :root içinde açık tema için, .dark içinde koyu tema için tanımlarsınız, ardından @theme inline içinde Tailwind'e tanıtırsınız. Tema belgesindeki örnek:

:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}

.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}

@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}

Bundan sonra bg-warning ve text-warning-foreground sınıflarını herhangi bir bileşende kullanabilirsiniz. Bir adımı atlamak tipik bir hatadır: @theme inline eşlemesini unutursanız sınıf üretilmez; .dark değerini unutursanız koyu temada açık tema rengi görünür.

<div className="bg-warning text-warning-foreground">Diskiniz dolmak üzere.</div>

Yeni rengi bir bileşen varyantı haline getirmek isterseniz, örneğin Alert için warning varyantı, ilgili ui dosyasındaki cva tanımına bu sınıfları eklersiniz; yöntem cva ile varyant ekleme yazısında.

Renk biçimi: oklch

Güncel değişken değerleri oklch() biçimindedir. Tailwind v4 güncellemesinin değişiklik listesinde HSL renklerin OKLCH'ye dönüştürüldüğü yazar; eski projelerde 0 0% 100% gibi çıplak HSL değerleri görebilirsiniz. Bir değerdeki üç sayı sırasıyla açıklık, kroma ve ton açısıdır; nötr gri tonlarında kroma ve ton sıfırdır, bu yüzden neutral temadaki birçok değer oklch(x 0 0) biçimindedir. Biçimin kendisi için CSS renk değerleri ve oklch yazısına bakın. Tema belgesi başka renk biçimleri için Tailwind CSS'in renk belgesine yönlendirir.

Temel renkler: neutral, stone, zinc, gray, slate

Tema belgesi beş temel renk paletini tam değerleriyle verir. Temel renk, nötr tonların (arka plan, kenarlık, sönük yüzeyler) hangi renge kaydığını belirler. Seçim components.json içindeki tailwind.baseColor alanında tutulur ve belgeye göre başlatmadan sonra değiştirilemez. CLI'de bu seçim init komutunun -b, --base-color seçeneğiyle yapılabilir.

npx shadcn@latest init --base-color zinc

Palet değerlerine yakından bakınca farklar görülür. Neutral'de değerlerin kroması sıfırdır; stone'da ton açısı 50 civarında küçük bir sıcaklık vardır (--foreground: oklch(0.147 0.004 49.25)); zinc, gray ve slate ise mavi-mor tarafa kayar ve bu kayma sırayla artar (slate için --foreground: oklch(0.129 0.042 264.695)). Beş palette ortak kalan değerler de vardır: --destructive açık temada hepsinde oklch(0.577 0.245 27.325), grafik renkleri de beşinde aynıdır. Koyu temada --border ve --input beyazın saydam tonları olarak her palette aynı tanımlanır.

Uygulamalı örnek: marka rengini ana renk yapmak

Bir hosting paneli hazırladığınızı ve varsayılan siyah-beyaz ana renk yerine mavi bir marka rengi istediğinizi düşünün. Bileşen dosyalarına dokunmadan yalnızca --primary ve eşini değiştirmek yeterlidir. Aşağıdaki değerler, varsayılan paletin koyu temasında --sidebar-primary için kullanılan mavi tondan (oklch(0.488 0.243 264.376)) ve onun eşi olan oklch(0.985 0 0) değerinden alınmıştır:

:root {
  --primary: oklch(0.488 0.243 264.376);
  --primary-foreground: oklch(0.985 0 0);
  --ring: oklch(0.488 0.243 264.376);
}

.dark {
  --primary: oklch(0.488 0.243 264.376);
  --primary-foreground: oklch(0.985 0 0);
}

Bu değişiklikten sonra varsayılan Button, bg-primary kullanan rozetler ve --ring değişkenini kullanan odak halkası yeni rengi alır. Burada iki tema için aynı değer kullanıldı; gerçek projede marka rehberinize göre koyu tema için ayrı bir ton seçebilirsiniz. Renk çiftinin yeterli kontrastı sağlayıp sağlamadığını kontrol etmek sizin sorumluluğunuzdadır; erişilebilirlik ilkeleri için WCAG temelleri yazısına bakın.

Hangi bileşen hangi değişkeni kullanır?

Bir değişkeni değiştirdiğinizde neyin etkileneceğini bilmek için bileşen kaynağına bakmak yeterlidir. button.tsx içindeki varyantlar iyi bir örnektir: default varyantı bg-primary text-primary-foreground, secondary varyantı bg-secondary text-secondary-foreground kullanır. destructive varyantı bg-destructive ile birlikte metin için sabit text-white yazar; yani bu varyantın metin rengi tema değişkeninden gelmez. outline varyantı bg-background üzerine kurulur ve üzerine gelindiğinde bg-accent rengine geçer; koyu temada ise dark:bg-input/30 ile --input değişkeninin saydam bir tonunu kullanır. Tüm varyantlardaki odak halkası ring-ring/50 biçimindedir. card.tsx ise bg-card text-card-foreground ile kendi çiftini kullanır. Bu yüzden örneğin yalnızca kartların rengini değiştirmek için --card değerini düzenlemek yeterlidir; sayfa arka planı (--background) etkilenmez.

Sık yapılan hatalar

• @theme inline eşlemesini unutmak: Değişken tanımlı olur ama bg-warning gibi bir sınıf oluşmaz.
• Sadece :root değerini değiştirmek: Koyu temada eski renk görünmeye devam eder; .dark bloğunu da güncelleyin.
• foreground eşini atlamak: Yeni arka plan renginin üzerindeki metin okunmaz hale gelebilir.
• cssVariables değerini sonradan değiştirmek: Var olan bileşenler değişmez; belgeye göre geçiş için bileşenleri silip yeniden kurmanız gerekir.
• Eski HSL biçimini yeni projeye taşımak: Güncel kurulumlar oklch() kullanır; eski çıplak HSL değerlerini hsl() sarmalamadan kullanırsanız renkler bozulur. Geçiş adımları Tailwind v4 geçişi yazısında.
• Renkleri sınıflarla tek tek ezmek: Değişken yaklaşımının amacı tek yerden değişikliktir; bkz. cn fonksiyonu.

Sık Sorulan Sorular

Tema değiştirmek için bileşen dosyalarını düzenlemem gerekir mi?

CSS değişkenleri yaklaşımında hayır. Bileşenler anlamsal sınıflar kullandığı için globals.css içindeki değerleri değiştirmeniz yeterlidir.

baseColor alanını sonradan değiştirebilir miyim?

Belgeye göre bu alan başlatmadan sonra değiştirilemez. Pratikte görünümü değiştirmek için istediğiniz paletin değerlerini tema belgesinden globals.css dosyanıza kopyalarsınız.

Kenar çubuğu neden ayrı değişkenler kullanıyor?

Sidebar kendi yüzey, vurgu, kenarlık ve halka değişkenlerine sahiptir; böylece kenar çubuğunu sayfanın geri kalanından farklı renklendirebilirsiniz. Ayrıntılar sidebar kurulumu yazısında.

Koyu tema için ayrı bir ayar dosyası var mı?

Hayır. Koyu tema değerleri aynı globals.css dosyasında .dark seçicisi altında durur. Bu sınıfı sayfaya ekleyip kaldırmak framework'e göre değişir.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: shadcn/ui öğrenme rehberi · dark mode kurulumu · Tailwind v4 geçişi · cn fonksiyonu · CSS değişkenleri · CSS renk değerleri