Hyvä'da Tailwind: tasarım token'ları ve derleme süreci

Luma temaları LESS dosyaları, değişkenler ve uzun bir geçersiz kılma zinciriyle biçimlendirilir. Hyvä bunun yerine, stillerin doğrudan şablondaki HTML'de sınıflar olarak yer aldığı, yardımcı sınıf odaklı (utility-first) bir framework olan Tailwind CSS'i kullanır.

Bu değişiklik ilk başta bazı ekiplerin kafasını karıştırır. Her öğe kendi sınıflarını taşıyorsa marka nerede duruyor? Yanıt: tasarım token'ları ve bunları küçük bir stil dosyasına dönüştüren bir derleme süreci. Bu yazıda ikisini de anlatıyoruz. Örneklerin hepsi kendi Hyvä mağazalarımızdan.

Tasarım token'ı nedir?

Tasarım token'ı, temanın tamamının ortak kullandığı, adı olan bir değerdir. Yirmi şablona tek tek hex renk kodu yazmak yerine primary rengini bir kez tanımlar ve her yerde bg-primary ve text-primary gibi sınıfları kullanırsınız.

Bir Hyvä temasındaki tipik token grupları şunlardır:

• Renkler: ana renk, ikincil renk, arka plan, metin, kenarlıklar, indirim ve stok durumları.
• Tipografi: başlıklar ve gövde metni için yazı tipi aileleri, boyutları ve kalınlıkları.
• Boşluk ve boyutlar: iç boşluklar, dış boşluklar ve kapsayıcı genişlikleri için kullanılan ölçek.
• Kırılım noktaları: yerleşimin değiştiği ekran genişlikleri.
• Köşe yuvarlaklıkları ve gölgeler: bir tasarımı tutarlı hissettiren küçük detaylar.

Bir marka rengi değiştiğinde tek bir token'ı değiştirip yeniden derlersiniz. Tüm butonlar, bağlantılar ve rozetler buna uyar.

Hyvä'da token'lar nerede durur?

Hyvä’nın varsayılan teması, Tailwind yapılandırmasında zaten bir dizi token tanımlar. Alt temanızda bu temadan kopyalanan web/tailwind klasörü bulunur ve bu değerleri genişletir. Ayrıntılar: Hyvä alt tema rehberimiz.

Renk token'larını genişletmenin basit bir örneği şöyle:

theme: {
    extend: {
        colors: {
            primary: {
                lighter: 'var(--color-primary-lighter)',
                DEFAULT: 'var(--color-primary)',
                darker: 'var(--color-primary-darker)'
            }
        }
    }
}

Yukarıdaki gibi bir token'ı bir CSS özel değişkenine (custom property) bağlamak işe yarayan bir yöntemdir. Sınıf adı aynı kalır, ancak asıl renk başka bir yerde, örneğin mağaza görünümü bazında ya da yönetim panelinden ayarlanabilir.

Dosya yapısının tam hali Hyvä sürümünüze bağlıdır; çünkü yeni Tailwind sürümleri yapılandırmanın daha büyük kısmını CSS'e taşıyor. İlke ise aynı kalır: token'ları bir kez tanımlayın, her yerde kullanın.

Ekibin renkleri kod yazmadan değiştirmesine olanak tanıyın

Mağazalarımızda header ve marka renklerini Stores > Configuration altında sunuyoruz. Pazarlama ekibi, destek talebi açmadan yönetim panelinden bir rengi değiştirebiliyor.

Bu ayarın arkasında, Tailwind token'ları dağıtım sırasında yapılandırma ve tema dosyalarından yeniden oluşturulur. Değerleri yönetim paneli, adları token'lar tutar; derleme ise ikisini birbirine bağlar.

Bunu bilerek birkaç değerle sınırlıyoruz. Her öğe için bir renk seçici, temiz bir tasarımı kısa sürede yamalı bohçaya çevirir. Bu yüzden yönetim paneli marka kararlarını sunar, tema da geri kalan her şeyi tutarlı tutar. Konuyu şu yazımızda daha ayrıntılı anlatıyoruz: Hyvä tema renklerini yönetim panelinden değiştirmek.

Derleme süreci nasıl işler?

Tailwind, olası tüm yardımcı sınıfları tarayıcıya göndermez. Derleme sırasında şablonlarınızı tarar, kullandığınız sınıfları bulur ve yalnızca bunları son stil dosyasına yazar.

Bir Hyvä mağazasında derlemenin, bir sınıfın gelebileceği her yeri görmesi gerekir:

1. Alt temanızdaki şablonlar.
2. Vendor klasöründeki Hyvä varsayılan temasından sunulmaya devam eden şablonlar.
3. Hyvä uyumlu modüllerden gelen şablonlar ve Tailwind kaynakları.
4. PHP, CMS içeriği ya da yönetim paneli üzerinden atanan tüm sınıflar.

Hyvä üçüncü maddeyi şu komutla çözer: bin/magento hyva:config:generate. Bu komut, kurulu Hyvä uyumlu modüllerin ve yollarının listesini oluşturur; Tailwind derlemesi de bu listeyi okur.

Dördüncü madde dikkat ister. Tailwind, yalnızca veritabanında bulunan bir sınıf adını göremez. Editörler CMS bloklarına sınıf adı yazıyorsa, derlemenin bunları koruması için bu sınıfları yapılandırmada açıkça listelemeniz gerekir; aksi halde geliştirme ortamında düzgün görünür, canlı ortamda bozulur.

Dağıtım sıramız

Derlenmiş stil dosyasını bir derleme çıktısı olarak görüyoruz; asla birinin düzenlediği ya da commit ettiği bir dosya olarak değil. Altyapımızda Magento 2.4.9 canlı modda ve statik içerik dağıtımıyla çalışıyor; dağıtım da sabit bir sırayla ilerliyor.

bin/magento hyva:config:generate
npm --prefix app/design/frontend/Vendor/default/web/tailwind ci
npm --prefix app/design/frontend/Vendor/default/web/tailwind run build-prod
bin/magento setup:static-content:deploy -f en_GB de_DE
bin/magento cache:flush

Derleme script’inin adını temanızın şu dosyasında kontrol edin: package.json; çünkü bu ad Hyvä sürümlerine göre değişir. npm ci komutunu npm install yerine kullanmak, her dağıtımda lock dosyasındaki paket sürümlerinin birebir kurulmasını sağlar.

Dağıtımdan sonra stil dosyası için CDN önbelleğini temizliyoruz; böylece ziyaretçiler eski CSS ile yeni HTML almaz.

Bu yaklaşım sayfaları neden hafif tutar?

Aynı sunucu ve katalogla yaptığımız karşılaştırmada temiz Hyvä sayfaları 195 ile 226 KB arasındaydı; aynı sayfalar Luma'da 756 ile 962 KB arasındaydı. Farkın büyük kısmı JavaScript'ten geliyor, ancak CSS'in de payı var.

Bir Luma stil dosyası, temanın gösterebileceği her widget'ın stillerini içerir. Bir Tailwind derlemesi ise şablonlarınızın kullandığı sınıfları ve çok az fazlasını içerir. Rakamların tamamını şu yazımızda bulabilirsiniz: Hyvä ve Luma karşılaştırması.

Derleme ancak disiplinli olursanız hafif kalır. Birkaç alışkanlık işinizi kolaylaştırır:

• Tek seferlik piksel genişlikleri gibi rastgele değerler yerine token'ları kullanın.
• PHP ya da JavaScript içinde sınıf adlarını metin parçalarından oluşturmaktan kaçının; Tailwind bunları algılayamaz.
• Eski bileşenleri değiştirdiğinizde kaldırın; böylece sınıfları da derlemeden çıkar.
• Özel CSS dosyalarını küçük tutun ve yalnızca Tailwind'in iyi ifade edemediği şeyler için kullanın.

Sık görülen sorunlar ve nedenleri

SSS

Tasarımcıların Tailwind öğrenmesi gerekir mi?

Derinlemesine değil. Tasarımcılar net bir renk, yazı boyutu ve boşluk değerleri seti sunmalı, geliştiriciler de bunları token'lara dönüştürmeli. Bu ortak liste, çoğu zaman tasarım aşamasının en faydalı çıktısıdır.

Hyvä'da normal CSS yazmaya devam edebilir miyiz?

Evet. Hyvä temaları özel CSS içerebilir; Tailwind de tekrarlanan kalıplar için bileşen sınıflarını destekler. Özel CSS'i minimumda tutuyoruz; böylece stillerin çoğu şablonlarda görünür kalır.

CSS'i her dağıtımda yeniden derlemek dağıtımı yavaşlatır mı?

Tailwind derlemesi, statik içerik dağıtımına göre küçük bir adımdır. Sürece kısa ve öngörülebilir bir aşama ekler, senkron dışı kalmaktan doğan hata türünü ise tümüyle ortadan kaldırır.

Ekibinizin güvenle düzenleyebileceği bir Hyvä teması mı istiyorsunuz? Yaklaşımımızı şu sayfada okuyabilirsiniz: Hyvä tema geliştirme sayfası, ya da mevcut ön yüzünüz için bir Magento 2 analizi talep edin.