Tailwind CSS --spacing(), --alpha(), theme() ve @config

--spacing(): boşluk ölçeğinden değer

--spacing() içine yazdığınız sayıyı temel boşluk birimiyle çarpar. Varsayılan temada --spacing 0.25rem olduğu için --spacing(4) 1rem eder (kök yazı boyutu 16px ise 16px). Fonksiyonu hem kendi kurallarınızda hem keyfi değerlerin içinde kullanabilirsiniz:

@import "tailwindcss" source(none);
@source inline("py-[calc(--spacing(4)-1px)]");
.kutu {
  margin: --spacing(4);
  padding: --spacing(1.5) --spacing(6);
  gap: --spacing(-2);
}

v4.3.5 ile derlenen CSS:

@layer utilities {
  .py-\[calc\(--spacing\(4\)-1px\)\] {
    padding-block: calc(calc(var(--spacing) * 4) - 1px);
  }
}
.kutu {
  margin: calc(var(--spacing) * 4);
  padding: calc(var(--spacing) * 1.5) calc(var(--spacing) * 6);
  gap: calc(var(--spacing) * -2);
}

Çıktıdan üç sonuç çıkıyor. Birincisi, fonksiyon sabit bir sayı değil var(--spacing) içeren bir calc() yazıyor; temada --spacing değerini değiştirirseniz bu kurallar da kendiliğinden değişir. İkincisi, ondalık ve negatif sayılar kabul ediliyor: --spacing(1.5) ve --spacing(-2) doğrudan çarpana dönüştü. Üçüncüsü, keyfi değer içinde de çalışıyor; belgenin önerdiği py-[calc(--spacing(4)-1px)] kalıbı, bir kenarlık kalınlığını telafi etmek gibi durumlarda boşluğu ölçeğe bağlı tutarken bir piksel çıkarmanızı sağlar. Boşluk sınıflarının kendisi padding, margin ve spacing yazısında.

Hatalı argüman sessizce geçer

--spacing() argümanını doğrulamaz. margin: --spacing(abc); yazdığımızda derleme başarıyla bitti ve çıktıda margin: calc(var(--spacing) * abc); satırı vardı. Bu satır tarayıcıda geçersiz sayılıp yok sayılır, ama CLI sizi uyarmaz. Değişken adı yazım hatalarında da aynı durum yaşanabilir; bu yüzden fonksiyon çıktısını en az bir kez derlenmiş CSS'te kontrol etmek iyi bir alışkanlıktır.

Fonksiyonel utility içinde --spacing()

--spacing()'in en güçlü kullanımı, kendi @utility tanımlarınızdır. margin-inline-start: --spacing(--value(integer)); gibi bir satır, kaydir-4 sınıfını hazır boşluk sınıflarıyla aynı ölçeğe bağlar. Negatif aile için belge --spacing(--value(integer) * -1) biçimini gösterir. Bu kalıbın tam örneği @utility direktifi yazısında derlenmiş olarak var.

--alpha(): renk saydamlığı

--alpha() bir rengi ve bölü işaretinden sonra bir saydamlık değeri alır. Belge derlenmiş sonucu tek bir color-mix(in oklab, ...) satırı olarak gösterir. v4.3.5'in gerçek çıktısında ise ek bir ayrıntı var:

@import "tailwindcss" source(none);
@source inline("bg-[--alpha(var(--color-sky-500)/25%)]");
.kutu {
  color: --alpha(var(--color-lime-300) / 50%);
  border-color: --alpha(red / 10%);
}

@layer utilities {
  .bg-\[--alpha\(var\(--color-sky-500\)\/25\%\)\] {
    background-color: color-mix(in srgb, oklch(68.5% 0.169 237.323) 25%, transparent);
    @supports (color: color-mix(in lab, red, red)) {
      background-color: color-mix(in oklab, var(--color-sky-500) 25%, transparent);
    }
  }
}
.kutu {
  color: color-mix(in srgb, oklch(89.7% 0.196 126.665) 50%, transparent);
  @supports (color: color-mix(in lab, red, red)) {
    color: color-mix(in oklab, var(--color-lime-300) 50%, transparent);
  }
  border-color: color-mix(in oklab, red 10%, transparent);
}

Rengi bir tema değişkeniyle verdiğinizde derleyici iki satır yazıyor: önce değişkenin değeri gömülü, srgb uzayında karıştıran bir yedek satır, ardından @supports koşulu içinde belgedeki oklab satırı. Düz bir renk adı (red) verdiğimizde ise yalnızca tek oklab satırı üretildi. Bu, belgedeki kısa örneğin gerçek çıktının sadeleştirilmiş hâli olduğunu gösteriyor; tema değişkenli kullanımda @supports koşulunu karşılamayan ortamlar için gömülü değerli bir satır da bulunuyor. Sınıflardaki bg-black/50 gibi saydamlık yazımı da aynı color-mix() mekanizmasını kullanır; bunu renk opaklığı yazısı anlatıyor. oklch ve oklab renk uzaylarının kendisi CSS renk değerleri yazısında.

Eksik argüman hatası

--spacing()'in aksine --alpha() argümanlarını denetler. Saydamlık değeri olmadan color: --alpha(var(--color-red-500)); yazdığımızda derleme şu mesajla durdu:

Error: The --alpha(…) function requires a color and an alpha value, e.g.: `--alpha(var(--color-red-500) / 50%)`

Uygulamalı örnek: iki fonksiyon bir bileşende

Kontrol etmediğiniz bir HTML'e (örneğin bir CMS'in ürettiği kartlara) stil verdiğinizi düşünün. Kartın iç boşluğu 1px'lik kenarlığı telafi edecek şekilde boşluk ölçeğine bağlı olsun, kenarlık rengi yarı saydam bir gri olsun ve üzerine gelindiğinde mavimsi bir tona dönsün. Bunu tek bir bileşen kuralıyla, hiç sınıf eklemeden yazabilirsiniz:

@import "tailwindcss" source(none);
@layer components {
  .kart {
    padding: calc(--spacing(6) - 1px);
    border: 1px solid --alpha(var(--color-gray-900) / 10%);
    border-radius: var(--radius-xl);
    @variant hover {
      border-color: --alpha(var(--color-sky-600) / 40%);
    }
  }
}

v4.3.5 ile derlenen CSS:

@layer theme {
  :root, :host {
    /* (kısaltıldı: --font-sans, --font-mono ve varsayılan font değişkenleri) */
    --color-sky-600: oklch(58.8% 0.158 241.966);
    --color-gray-900: oklch(21% 0.034 264.665);
    --spacing: 0.25rem;
    --radius-xl: 0.75rem;
  }
}
@layer components {
  .kart {
    padding: calc(calc(var(--spacing) * 6) - 1px);
    border: 1px solid color-mix(in srgb, oklch(21% 0.034 264.665) 10%, transparent);
    @supports (color: color-mix(in lab, red, red)) {
      border: 1px solid color-mix(in oklab, var(--color-gray-900) 10%, transparent);
    }
    border-radius: var(--radius-xl);
    &:hover {
      @media (hover: hover) {
        border-color: color-mix(in srgb, oklch(58.8% 0.158 241.966) 40%, transparent);
        @supports (color: color-mix(in lab, red, red)) {
          border-color: color-mix(in oklab, var(--color-sky-600) 40%, transparent);
        }
      }
    }
  }
}

Çıktıda fonksiyonların birbirine ve @variant'a nasıl uyduğu görülüyor. --spacing(6) bir calc() içine yerleşip 1px düşüldü. --alpha() kısa border özelliğinin içinde bile yedek ve @supports satırlarını üretti. @variant hover bloğu, sınıflardaki hover: gibi @media (hover: hover) sorgusuna sarıldı ve içindeki --alpha() da aynı yedek yapıyı aldı. Kullandığımız dört tema değişkeni tema katmanına eklendi; başka hiçbir renk ya da değer çıktıya girmedi. Kuralı @layer components içine koyduğumuz için, aynı öğeye sonradan bir utility sınıfı eklenebiliyorsa o sınıf bu kuralı ezebilir. Bileşen yazmanın diğer yolu olan @apply @apply ve bileşen sınıfları yazısında.

theme(): eski fonksiyon ve hâlâ işe yaradığı yer

theme(), v3'te tema değerlerine nokta gösterimiyle erişmek için kullanılırdı. Belge onu kullanımdan kalkmış olarak işaretler ve yerine CSS tema değişkenlerini önerir. v4.3.5 eski yazımı hâlâ derliyor:

@import "tailwindcss" source(none);
.eski {
  margin: theme(spacing.12);
  color: theme(colors.red.500);
  font-size: theme(--text-lg);
  width: theme(--spacing-yok, 3rem);
}

.eski {
  margin: 3rem;
  color: oklch(63.7% 0.237 25.331);
  font-size: 1.125rem;
  width: 3rem;
}

Çıktı, theme() ile var() arasındaki temel farkı gösteriyor: theme() değeri derleme sırasında sabit olarak yazar. margin: 3rem satırı artık --spacing değişkenine bağlı değil; değişkeni sayfada değiştirseniz bile bu kural değişmez. var(--color-red-500) ise çalışma anında çözülür. Ayrıca nokta gösterimi (colors.red.500) ve değişken adı gösterimi (--text-lg) birlikte çalıştı. Var olmayan bir anahtar için ikinci argüman yedek değer olarak kullanıldı. Yedek vermeseydik ne olacağını da denedik; theme(--spacing-4) yazınca derleme durdu:

Error: Could not resolve value for theme function: `theme(--spacing-4)`. Consider checking if the path is correct or provide a fallback value to silence this error.

Bu hatanın nedeni, v4 temasında --spacing-4 diye bir değişkenin olmamasıdır; boşluk ölçeği tek bir --spacing değişkeninden hesaplanır.

Medya sorgularında theme()

Yükseltme rehberi, theme()'in hâlâ gerekli olduğu bir yer belirtir: CSS değişkenlerinin desteklenmediği medya sorguları. Bu durumda nokta gösterimi yerine değişken adını kullanmanız önerilir:

@import "tailwindcss" source(none);
@media (width >= theme(--breakpoint-md)) {
  .genis { display: grid; }
}
.kutu { color: theme(colors.red.500 / 50%); }

@media (width >= 48rem) {
  .genis {
    display: grid;
  }
}
.kutu {
  color: color-mix(in oklab, oklch(63.7% 0.237 25.331) 50%, transparent);
}

Kırılma noktası değeri derleme sırasında 48rem olarak medya sorgusuna yazıldı. Bölü işaretli kullanım da saydamlığı uygulayan bir color-mix() üretti, ama bu kez rengin değeri gömülü. Kendi CSS'inizde kırılma noktasına bağlı bir kural yazıyorsanız @variant md { ... } de aynı sonuca ulaşır; bu yöntem @variant ve özel varyantlar yazısında. Kırılma noktalarını değiştirme breakpoint özelleştirme yazısında.

CSS değişkeni yazarken v3 alışkanlığı

Fonksiyonlarla yakından ilgili bir hata, keyfi değer içinde CSS değişkenini v3 biçiminde yazmaktır. Yükseltme rehberine göre v4'te değişken kısaltması köşeli parantez yerine normal parantezle yazılır. İki yazımı birlikte derledik:

@import "tailwindcss" source(none);
@source inline("bg-[--marka] bg-(--marka) bg-(color:--marka)");

.bg-\(--marka\) {
  background-color: var(--marka);
}
.bg-\(color\:--marka\) {
  background-color: var(--marka);
}
.bg-\[--marka\] {
  background-color: --marka;
}

Parantezli biçim beklendiği gibi var(--marka) üretti. Köşeli parantezli eski biçim ise hata vermeden background-color: --marka; yazdı; bu geçersiz bir değerdir ve tarayıcı tarafından yok sayılır. tailwindcss canonicalize bg-[--marka] komutu da bu sınıfı değiştirmeden geri döndürdü, yani bu hatayı otomatik araçla yakalayamazsınız. Aynı komut bg-[var(--color-red-500)] için bg-red-500, p-[--spacing(4)] için p-4 önerdi: keyfi değer içinde tema değişkeni ya da fonksiyon kullanıyorsanız çoğu zaman hazır bir sınıf zaten vardır. Komutun kullanımı standalone CLI yazısında.

@config ve @plugin: eski uyumluluk direktifleri

Belge bu iki direktifi yalnızca v3 uyumluluğu için sunar ve CSS tabanlı özelliklerle birlikte kullanılabildiklerini, böylece geçişin adım adım yapılabildiğini söyler. Çakışma olursa CSS'te yapılan tanımlar öncelik kazanır. @config eski bir JavaScript yapılandırma dosyasını yükler; yükseltme rehberine göre v4 bu dosyayı artık kendiliğinden aramaz. Yapılandırma dosyasının içeriği v3 konusu olduğundan burada göstermiyoruz; yalnızca theme.extend.colors altında kurumsal: '#0f766e' rengini tanımlayan küçük bir dosyayla denedik:

@import "tailwindcss" source(none);
@config "./tailwind.config.js";
@source inline("bg-kurumsal");

.bg-kurumsal {
  background-color: #0f766e;
}

Standalone CLI, Node.js kurulu olmadan bu dosyayı okudu ve bg-kurumsal sınıfını üretti. Dikkat ederseniz değer bir tema değişkenine bağlanmadı, doğrudan #0f766e olarak yazıldı; @theme ile tanımlanan renklerde gördüğümüz var(--color-...) bağlantısı burada yok. Belge ayrıca yapılandırmadaki corePlugins, safelist ve separator seçeneklerinin desteklenmediğini belirtir; belirli sınıfları her zaman üretmek için @source inline() önerilir (@source direktifi).

@plugin ise eski bir JavaScript eklentisini paket adı ya da yerel yol ile yükler. Belgedeki örnek @plugin "@tailwindcss/typography"; satırıdır; bu satırı standalone CLI ile denediğimizde derleme hatasız tamamlandı. Eklentilerin kendisi bu serinin kapsamı dışında. v3 yapılandırmasından tam geçiş için Tailwind v4 yenilikleri yazısına bakın.

Tabloyu bir karar sırası olarak da okuyabilirsiniz. Bir değere CSS içinde ihtiyaç duyduğunuzda önce hazır bir utility sınıfı olup olmadığına bakın; varsa HTML'de onu kullanmak en kısa yoldur. Kendi kuralınızı yazmanız gerekiyorsa tema değerini var() ile okuyun. Boşluk ölçeğine bağlı bir hesap gerekiyorsa --spacing(), bir tema renginin saydam hâli gerekiyorsa --alpha() kullanın. theme()'i yalnızca değişkenin işlemediği medya sorgularına bırakın. @config ve @plugin ise yeni bir projede değil, eski bir projeyi kademeli taşırken anlamlıdır; tanımlarınızı zamanla @theme, @utility ve @custom-variant direktiflerine aktardıkça bu satırları silebilirsiniz.

Sık yapılan hatalar

• --spacing() argümanını yanlış yazmak: hata vermez, geçersiz bir calc() üretir.
• --alpha() içinde saydamlığı unutmak: derleme hata ile durur.
• theme() ile çalışma anında değişen değer beklemek: değer derleme sırasında gömülür.
• theme(--spacing-4) yazmak: böyle bir değişken yok; --spacing(4) kullanın.
• bg-[--degisken] yazmak: v4'te bg-(--degisken) doğrudur; eski biçim geçersiz değer üretir.
• Eski config'te safelist aramak: v4 bu seçeneği okumaz; @source inline() kullanın.

Sık Sorulan Sorular

--spacing() ile calc(var(--spacing) * 4) arasında fark var mı?

Çıktı birebir aynı: derleyici --spacing(4) ifadesini calc(var(--spacing) * 4) olarak yazıyor. Fonksiyon yalnızca daha kısa ve okunaklıdır.

Temada --spacing değerini değiştirirsem fonksiyon çıktısı değişir mi?

Derlenen satır değişmez, çünkü zaten calc(var(--spacing) * n) biçiminde değişkene bağlıdır; değişen, tema katmanındaki --spacing değeridir. @theme yazısında temel birimi 0.3rem yaptığımızda p-4 sınıfının aynı calc() ifadesini koruduğunu ve yalnızca değişkenin değiştiğini gösterdik. theme(spacing.12) ise derleme anında 3rem olarak gömüldüğü için bu değişiklikten etkilenmez.

--alpha() yerine opacity kullanabilir miyim?

opacity öğenin tamamını, içindeki metin ve çocuklarla birlikte saydamlaştırır; --alpha() yalnızca o tek renk değerini değiştirir. Bu ayrımın sınıf tarafındaki karşılığı renk opaklığı yazısında.

Çıktıdaki iç içe calc() bir sorun mu?

calc(--spacing(6) - 1px) ifadesi calc(calc(var(--spacing) * 6) - 1px) olarak derlendi; derleyici fonksiyonu yerinde açtığı için iç içe bir calc() oluşuyor. Bu yazımı elle sadeleştirmeniz gerekmez, belgedeki py-[calc(--spacing(4)-1px)] örneği de aynı biçimde açılıyor.

--alpha() hangi renk değerlerini kabul eder?

Bu yazıdaki denemelerde iki biçim de çalıştı: var(--color-lime-300) gibi bir tema değişkeni ve red gibi düz bir CSS renk adı. Fark çıktıdaydı; tema değişkeninde derleyici değeri bildiği için ek bir srgb yedek satırı yazdı, düz renk adında yalnızca oklab satırı üretildi. Saydamlığı belgedeki gibi yüzde olarak verin (50%) ve renk ile saydamlık arasına bölü işareti koymayı unutmayın.

Bu fonksiyonları HTML sınıflarında kullanabilir miyim?

Evet, keyfi değerlerin içinde. Yukarıdaki py-[calc(--spacing(4)-1px)] ve bg-[--alpha(var(--color-sky-500)/25%)] sınıfları bunun örneği; ikisi de kendi CSS'inizdeki kullanımla aynı ifadelere derlendi. Sınıf adında boşluk olamayacağı için fonksiyonun içini boşluksuz yazın.

theme() fonksiyonu kaldırıldı mı?

v4.3.5'te hâlâ derleniyor, ama belge kullanımdan kalkmış olarak işaretliyor. Yeni kodda var() ve --spacing() kullanın; theme()'i yalnızca medya sorgusu gibi değişkenin çalışmadığı yerlerde tutun.

Eski tailwind.config.js dosyamı silmem gerekir mi?

Hemen değil. @config ile yükleyip tanımları zamanla @theme'e taşıyabilirsiniz; ikisi aynı projede birlikte çalışır.

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 · @theme direktifi · @utility direktifi · Renk opaklığı · Arbitrary values · Tailwind v4 yenilikleri