Tailwind CSS @theme Direktifi ile Özel Tema Oluşturma

@theme ile :root arasındaki fark

İkisi de CSS değişkeni tanımlar, ama amaçları farklıdır. Belgeye göre @theme, sınıf üretmesini istediğiniz tasarım değerleri içindir; :root ise sınıfa dönüşmesini istemediğiniz sıradan değişkenler içindir. :root içine --color-marka yazarsanız bg-marka diye bir sınıf oluşmaz; aynı satırı @theme içine taşıdığınızda oluşur.

İkinci önemli kural: tema değişkenleri en üst düzeyde olmalıdır, bir seçicinin ya da medya sorgusunun içine yerleştirilemez. Bunu denedik: @media (width >= 40rem) { @theme { --color-yok: red; } } yazan bir dosyayı v4.3.5 hata vermeden derledi, fakat çıktıda ne --color-yok değişkeni ne de o @media bloğu vardı. Sessiz kalan bu durum, hata ayıklarken en çok zaman kaybettiren noktalardan biridir.

Tema ad alanları ve ürettikleri sınıflar

Bir değişkenin hangi sınıfı oluşturacağını adının başı belirler. Belgedeki tablodan en sık kullanılanlar:

Tabloda olmayan bir ön ek (örneğin yanlış yazılmış --colour-marka) hiçbir sınıf üretmez. Bunu da denedik: --colour-marka: #5b21b6 tanımlayıp bg-marka kullandığımızda derleyici o sınıf için tek satır yazmadı. Kendi ad alanınızı yalnızca @utility ile fonksiyonel sınıf tanımlayıp --value(--ad-alani-*) ile okuduğunuzda kullanabilirsiniz.

Varsayılan temayı genişletmek ve ezmek

Yeni bir ad eklemek temayı genişletir, var olan bir adı yeniden tanımlamak onu ezer. Aşağıdaki dosyada bir marka rengi, bir başlık yazı tipi ve yeni bir 3xl kırılma noktası ekliyor, ayrıca sm kırılma noktasını varsayılan 40rem yerine 30rem yapıyoruz:

@import "tailwindcss" source(none);
@source inline("bg-marka-500 text-marka-500 font-baslik 3xl:grid-cols-6 sm:p-4");
@theme {
  --color-marka-500: oklch(0.62 0.19 259);
  --font-baslik: "Poppins", sans-serif;
  --breakpoint-3xl: 120rem;
  --breakpoint-sm: 30rem;
}

v4.3.5 ile derlenen CSS:

@layer theme {
  :root, :host {
    --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', 'Noto Sans', Arial,
    sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
    --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New',
    monospace;
    --spacing: 0.25rem;
    --default-font-family: var(--font-sans);
    --default-mono-font-family: var(--font-mono);
    --color-marka-500: oklch(0.62 0.19 259);
    --font-baslik: "Poppins", sans-serif;
  }
}
@layer utilities {
  .bg-marka-500 {
    background-color: var(--color-marka-500);
  }
  .font-baslik {
    font-family: var(--font-baslik);
  }
  .text-marka-500 {
    color: var(--color-marka-500);
  }
  @media (width >= 30rem) {
    .sm\:p-4 {
      padding: calc(var(--spacing) * 4);
    }
  }
  @media (width >= 120rem) {
    .\33 xl\:grid-cols-6 {
      grid-template-columns: repeat(6, minmax(0, 1fr));
    }
  }
}
/* (kısaltıldı: @layer base) */

Çıktıdan öğrenilecek birkaç şey var. Sınıflar beklendiği gibi var(--color-marka-500) ve var(--font-baslik) değişkenlerini okuyor. sm: artık @media (width >= 30rem) ile çalışıyor; yani ezme işlemi tüm sm: sınıflarını etkiler. Rakamla başlayan 3xl: sınıfının seçicisi CSS kuralı gereği .\33 xl\:grid-cols-6 biçiminde kaçışlanmış. Son olarak tema katmanında yalnızca kullanılan değişkenler var: binlerce varsayılan renk değişkeninin hiçbiri çıktıya girmedi, kırılma noktası değerleri de :root içinde değişken olarak yer almadı, doğrudan medya sorgusuna yazıldı. Kırılma noktalarıyla ilgili diğer seçenekler breakpoint özelleştirme yazısında, renk paleti renk paleti ve tonlar yazısında, yazı tipleri font size, weight ve family yazısında anlatılıyor.

Boşluk ölçeğini değiştirmek: --spacing ve --spacing-*

Boşluk ölçeği diğer ad alanlarından biraz farklı çalışır. Tek bir --spacing değişkeni temel birimi belirler ve p-4, gap-0.5 gibi sayısal sınıflar bu birimin katı olarak hesaplanır. --spacing-128 gibi adlandırılmış bir değer eklerseniz o ada sahip sınıflar doğrudan o değişkeni okur. Skill notlarındaki --spacing-128: 32rem örneğini temel birimi değiştirerek birlikte derledik:

@import "tailwindcss" source(none);
@source inline("p-4 mt-128 w-128 gap-0.5");
@theme {
  --spacing: 0.3rem;
  --spacing-128: 32rem;
}

@layer utilities {
  .mt-128 {
    margin-top: var(--spacing-128);
  }
  .w-128 {
    width: var(--spacing-128);
  }
  .gap-0\.5 {
    gap: calc(var(--spacing) * 0.5);
  }
  .p-4 {
    padding: calc(var(--spacing) * 4);
  }
}

v4.3.5 çıktısı iki davranışı da gösteriyor: mt-128 ve w-128 adlandırılmış değişkeni okurken, p-4 ve gap-0.5 temel birimle çarpılıyor. Temel birimi 0.25rem'den 0.3rem'e çıkardığımız için p-4 artık 1.2rem demek. Bu tek satırlık değişiklik projedeki bütün padding, margin, gap, genişlik ve yükseklik sınıflarını aynı oranda etkiler; bu yüzden tasarım ölçeğini erken aşamada sabitlemek mantıklıdır. Sınıfların boşluk ölçeğiyle ilişkisi padding ve margin ve width ve height yazılarında.

Bir ad alanını boşaltmak: --color-*: initial

Varsayılan paleti tamamen kendi renklerinizle değiştirmek istiyorsanız ad alanını initial ile sıfırlayıp ardından kendi değerlerinizi yazarsınız. Aşağıdaki örnekte bg-red-500, bg-white ve text-black de kullanıldı:

@import "tailwindcss" source(none);
@source inline("bg-red-500 bg-white text-black bg-gece text-beyaz");
@theme {
  --color-*: initial;
  --color-beyaz: #fff;
  --color-gece: #121063;
}

@layer utilities {
  .bg-gece {
    background-color: var(--color-gece);
  }
  .text-beyaz {
    color: var(--color-beyaz);
  }
}

v4.3.5 çıktısında yalnızca kendi tanımladığımız iki renk sınıfı var. bg-red-500, bg-white ve text-black için hiçbir kural yok, çünkü beyaz ve siyah da --color-* ad alanının parçası. Paleti boşalttıysanız bu temel renkleri de kendiniz tanımlamalısınız. CLI bu sınıflar için uyarı vermez; sınıf sessizce üretilmez.

Tüm temayı sıfırlamak: --*: initial

Daha radikal seçenek, tüm tema değişkenlerini --*: initial ile silmektir. Bu durumda varsayılan temaya bağlı hiçbir sınıf kalmaz; boşluk ölçeği bile yeniden tanımlanmalıdır:

@import "tailwindcss" source(none);
@source inline("p-4 font-govde text-dalga bg-red-500 shadow-md");
@theme {
  --*: initial;
  --spacing: 4px;
  --font-govde: Inter, sans-serif;
  --color-dalga: oklch(0.72 0.11 221.19);
}

@layer theme {
  :root, :host {
    --spacing: 4px;
    --font-govde: Inter, sans-serif;
    --color-dalga: oklch(0.72 0.11 221.19);
  }
}
@layer utilities {
  .p-4 {
    padding: calc(var(--spacing) * 4);
  }
  .font-govde {
    font-family: var(--font-govde);
  }
  .text-dalga {
    color: var(--color-dalga);
  }
}

Çıktıda bg-red-500 ve shadow-md yok. p-4 ise hâlâ üretiliyor çünkü --spacing yeniden tanımlandı; yeni değerle p-4 16px'e eşit oluyor. flex ya da hidden gibi temaya bağlı olmayan sınıflar bu sıfırlamadan etkilenmez. Tema katmanının da ne kadar küçüldüğüne dikkat edin: varsayılan --font-sans ve --font-mono satırları bile gitti.

@theme inline: başka bir değişkene başvururken

Bir tema değişkeni başka bir değişkeni gösteriyorsa (--font-sans: var(--font-inter) gibi) inline seçeneğini kullanmanız önerilir. Farkı iki derlemeyle görelim. Önce seçeneksiz:

@import "tailwindcss" source(none);
@source inline("font-sans bg-birincil");
:root {
  --font-inter: "Inter", sans-serif;
}
@theme {
  --font-sans: var(--font-inter);
  --color-birincil: var(--color-red-500);
}

.bg-birincil {
  background-color: var(--color-birincil);
}
.font-sans {
  font-family: var(--font-sans);
}

Aynı dosyada yalnızca @theme satırını @theme inline yaptığımızda:

.bg-birincil {
  background-color: var(--color-red-500);
}
.font-sans {
  font-family: var(--font-inter);
}

İkinci çıktıda sınıflar ara değişkeni atlayıp doğrudan asıl değere başvuruyor; tema katmanında da artık --font-sans ve --color-birincil satırları yok. Bunun neden önemli olduğunu belge şöyle açıklar: CSS değişkenleri tanımlandıkları öğede çözülür. --font-sans kökte var(--font-inter) olarak tanımlanırsa, --font-inter değeri daha alttaki bir öğede verildiğinde kök onu göremez ve yedek yazı tipine düşer. inline ile sınıf, değişkeni kullanıldığı yerde çözer ve bu sorun ortadan kalkar.

@theme static: kullanılmayan değişkenleri de yazdırmak

Varsayılan davranışta derleyici yalnızca kullanılan tema değişkenlerini çıktıya koyar. JavaScript tarafında getComputedStyle ile okuyacağınız ya da satır içi stilde kullanacağınız değişkenler kaynak dosyalarda sınıf olarak geçmiyorsa çıktıda olmayabilir. @theme static bu durumda tüm değişkenleri yazdırır:

@import "tailwindcss" source(none);
@theme static {
  --color-birincil: var(--color-red-500);
  --color-ikincil: var(--color-blue-500);
}

@layer theme {
  :root, :host {
    /* (kısaltıldı: --font-sans ve --font-mono) */
    --color-red-500: oklch(63.7% 0.237 25.331);
    --color-blue-500: oklch(62.3% 0.214 259.815);
    --default-font-family: var(--font-sans);
    --default-mono-font-family: var(--font-mono);
    --color-birincil: var(--color-red-500);
    --color-ikincil: var(--color-blue-500);
  }
}

Hiçbir sınıf kullanılmadığı hâlde iki değişken ve başvurdukları --color-red-500 ile --color-blue-500 çıktıya girdi; @layer utilities ise boş kaldı. @theme içine --animate-* değişkeniyle birlikte @keyframes yazmak da mümkündür; bu, animasyon konusuna ait olduğu için animasyon sınıfları ve özel animasyon yazısında ayrıca anlatılıyor.

Tema değişkenlerini kendi CSS'inizde kullanmak

Tema değişkenleri sıradan CSS değişkeni olarak yazıldığı için onları kendi kurallarınızda var() ile okuyabilirsiniz. Bu, kontrol etmediğiniz HTML'i (örneğin bir API'den gelen Markdown çıktısını) biçimlendirmenin pratik bir yoludur:

@import "tailwindcss" source(none);
@layer components {
  .makale p {
    font-size: var(--text-base);
    color: var(--color-gray-700);
  }
}

@layer theme {
  :root, :host {
    /* (kısaltıldı: --font-sans ve --font-mono) */
    --color-gray-700: oklch(37.3% 0.034 259.733);
    --text-base: 1rem;
    --default-font-family: var(--font-sans);
    --default-mono-font-family: var(--font-mono);
  }
}
@layer components {
  .makale p {
    font-size: var(--text-base);
    color: var(--color-gray-700);
  }
}

Derleyici, kendi CSS'inizde var() ile andığınız değişkenleri de "kullanılmış" sayıp tema katmanına ekledi. Keyfi değerlerde de aynı yol açıktır; belgedeki örnekte iç içe kutunun köşesi rounded-[calc(var(--radius-xl)-1px)] ile dıştakinden 1px küçük tutulur ve derlenen kural border-radius: calc(var(--radius-xl) - 1px) olur. Boşluk ölçeği ve renk saydamlığı için hazır fonksiyonlar da var: --spacing() ve --alpha() fonksiyonları. Bileşen katmanının ne zaman tercih edileceğini katmanlar ve özel CSS yazısı anlatıyor.

Satır içi stilde tema değişkeni

Belge, tema değişkenlerinin sınıf dışında da kullanılabileceğini hatırlatır: style özelliğine background-color: var(--color-mint-500) yazmak geçerli bir kullanımdır. Burada dikkat etmeniz gereken nokta çıktıdır. Derleyici yalnızca kaynak dosyalarda karşılaştığı değişkenleri tema katmanına koyduğu için, değişken adı taranan bir dosyada geçmiyorsa ya da değer JavaScript tarafından üretiliyorsa :root içinde bulunmayabilir. Bu durumda değişkeni @theme static ile tanımlamak en güvenli yoldur. Hangi dosyaların tarandığını ve taramanın nasıl genişletileceğini @source direktifi yazısı anlatıyor.

Tüm örneklerde tema değişkenlerinin @layer theme katmanında, :root, :host seçicisi altında yazıldığını görüyorsunuz. Katman sırası çıktının ilk satırında @layer theme, base, components, utilities; olarak bildirilir. Bu düzen, kendi kurallarınızı hangi katmana yazmanız gerektiğini de belirler; ayrıntılar katmanlar ve saf CSS tarafı için CSS @layer yazısında.

Temayı projeler arasında paylaşmak

Tema tanımı düz CSS olduğundan ayrı bir dosyaya koyup birden çok projede içe aktarabilirsiniz. Belgedeki önerilen yapı, marka değişkenlerini theme.css içinde tutmak ve her uygulamanın giriş dosyasında @import "tailwindcss"; satırından sonra bu dosyayı içe aktarmaktır:

/* paketler/marka/theme.css */
@theme {
  --color-marka-500: oklch(0.62 0.19 259);
  --font-govde: Inter, sans-serif;
}

/* paketler/panel/app.css */
@import "tailwindcss";
@import "../marka/theme.css";

Sık yapılan hatalar

• @theme'i iç içe yazmak: medya sorgusu ya da seçici içindeki @theme sessizce yok sayılır. Kırılma noktasına göre değişen bir değer gerekiyorsa değişkeni :root üzerinde medya sorgusuyla değiştirin, sınıfı üreten tanım ise üst düzeyde kalsın.
• Ad alanını yanlış yazmak: --colour-*, --colors-* gibi adlar sınıf üretmez ve hata vermez. Tablodaki ön ekleri birebir kullanın.
• Paleti boşaltıp beyaz ve siyahı unutmak: --color-*: initial sonrası bg-white da üretilmez.
• Başka bir değişkene başvururken inline kullanmamak: değer beklenmedik biçimde yedeğe düşebilir.
• JavaScript ile okunacak değişkeni çıktıda aramak: kullanılmayan değişkenler yazılmaz; gerekiyorsa @theme static kullanın.
• Temel boşluk birimini proje ortasında değiştirmek: --spacing bütün sayısal boşluk ve boyut sınıflarını aynı anda etkiler; küçük bir değişiklik bile sayfa düzeninin tamamını kaydırabilir. Tek bir değere ihtiyacınız varsa --spacing-128 gibi adlandırılmış bir değer ekleyin.

Sık Sorulan Sorular

tailwind.config.js dosyasına hâlâ ihtiyacım var mı?

v4'te tema CSS'te @theme ile tanımlanır. Eski JavaScript yapılandırması @config ile yüklenebilir, ancak bu yalnızca uyumluluk içindir; ayrıntılar fonksiyonlar ve eski uyumluluk direktifleri yazısında.

Tema değişkenini sayfa çalışırken değiştirebilir miyim?

Evet. Sınıflar var(--color-marka-500) gibi değişkenleri okuduğu için değişkeni bir öğe üzerinde yeniden tanımlamak o öğe ve çocuklarındaki sınıfları da etkiler. @theme inline ile ise sınıflar ara değişkeni atladığından bu esneklik o değişken için azalır.

Kendi değerlerim varsayılanlarla birlikte mi çalışır?

Evet, yeni adlar eklemek temayı genişletir ve varsayılan sınıflar yerinde kalır. Yalnızca initial ile sıfırladığınız ad alanları ortadan kalkar.

Varsayılan tema değerlerinin tamamını nerede görebilirim?

Belgeye göre @import "tailwindcss" satırı arka planda üç dosya getirir: tema katmanına theme.css, temel katmana preflight.css, utility katmanına utilities.css. Varsayılan palet, yazı boyutu ölçeği, gölgeler ve yazı tipleri theme.css içindedir ve belge sayfasının sonunda tam liste olarak yer alır. Bu yazıdaki değerleri (--color-red-500, --text-lg, --perspective-normal gibi) v4.3.5 ile derlediğimiz çıktının tema katmanından aldık; projenizdeki sürümün listesine bakmayı unutmayın.

Tema tanımlarını ayrı bir dosyada tutmalı mıyım?

Küçük projelerde @theme bloğunu ana CSS dosyasında @import "tailwindcss"; satırının hemen altında tutmak yeterlidir. Birden çok uygulama aynı markayı paylaşıyorsa yukarıdaki gibi ayrı bir theme.css dosyası tutarlılığı korur; bu yapıyı CLI ile iki klasörde denedik ve marka renkleri ile yazı tipi beklendiği gibi üretildi.

Koyu tema için renkleri nasıl değiştiririm?

Koyu tema varyantlarının kurulumu dark mode kullanımı yazısında anlatılıyor; özel varyant tanımlamak için @custom-variant yazısına bakabilirsiniz.

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: Tailwind öğrenme rehberi · @utility direktifi · @apply ve bileşen sınıfları · --spacing() ve --alpha() · Renk paleti · CSS renk değerleri ve oklch