Tema Sistemi — Lvntr Starter Kit #

Bu belge şunları kapsar:

• AppShell / AdminLayout kompozisyon modeli ve yeni layout kurma
• İki katmanlı tema modeli: runtime kit temaları (main, aura) ve build-zamanı custom slot-override'ları
• Custom temalar için build-zamanı resolver ve tam-değiştirme + fallback modeli
• Custom temalar için VITE_SK_THEME ile aktivasyon
• Özel tema ekleme veya tek bir bileşenin stilini değiştirme adım adım reçetesi

Layout mimarisi #

AppShell — yapısal kabuk #

resources/js/layouts/AppShell.vue, admin panelinin yapısal iskeletidir. Şunları sahiplenir:

• .admin-layout kökü ve .admin-main / .admin-content bölgeleri
• useSidebar aracılığıyla sidebar collapse ve mobil-açık durumu (tek sahip — alt bileşenlerde useSidebar tekrar import etmeyin)
• .admin-main üzerindeki responsive sınıf değiştiricileri (admin-main--expanded, admin-main--collapsed, admin-main--mobile)

AppShell beş adlandırılmış slot sunar:

AppShell sayfa prop'u, flash-to-toast köprüsü ve <Head> taşımaz. Yalnızca yapısal sarmalayıcıdır.

AdminLayout — ince kompozisyon #

resources/js/layouts/AdminLayout.vue, AppShell'i sarar ve her bölgeyi standart admin bileşenleriyle doldurur:

• #sidebar → AdminSidebar
• #header → AdminHeader (karanlık mod toggle'ını iletir)
• default → AdminPageHeader + <slot /> (sayfa içeriği) + <slot name="page-actions" />
• #footer → AdminFooter
• #overlays → ConfirmDialogComponent, ToastComponent, AppDialog, ImageLightbox

Flash-to-toast köprüsünü (router.on('finish', …)) ve <Head :title="title" />'ı da yönetir.

Dış kontrat (değişmedi):

<AdminLayout title="Kullanıcılar" subtitle="Kullanıcı yönetimi" :back-url="route('admin.users.index')">
    <template #page-actions>
        <Button label="Yeni Kullanıcı" />
    </template>

    <!-- sayfa içeriği -->
</AdminLayout>

Prop'lar: title?: string, subtitle?: string, backUrl?: string | boolean. Slot'lar: default (sayfa gövdesi), page-actions (AdminPageHeader'ın #actions slot'una iletilir).

Mevcut tüm sayfalar @/layouts/AdminLayout.vue'yu import etmeye devam eder — public kontrat birebir aynıdır.

Yeni layout kurma #

Kabuk yapısını paylaşan ama bölgeleri farklı düzenleyen bir layout oluşturmak için AppShell'i doğrudan kompozisyon yapın:

<!-- resources/js/layouts/MinimalLayout.vue -->
<script setup lang="ts">
    import AppShell from '@/layouts/AppShell.vue';
    import MinimalSidebar from '@/layouts/components/MinimalSidebar.vue';
    import MinimalHeader from '@/layouts/components/MinimalHeader.vue';
</script>

<template>
    <AppShell>
        <template #sidebar="{ collapsed, mobileOpen, isMobile, closeMobile }">
            <MinimalSidebar
                :collapsed="collapsed"
                :mobile-open="mobileOpen"
                :is-mobile="isMobile"
                @close-mobile="closeMobile"
            />
        </template>
        <template #header="{ collapsed, isMobile, toggle }">
            <MinimalHeader :collapsed="collapsed" :is-mobile="isMobile" @toggle-sidebar="toggle" />
        </template>
        <slot />
    </AppShell>
</template>

Yeni layout'u kullanan sayfalar onu yoluna göre import eder — AdminLayout sayfaları etkilenmez.

İki stil katmanı #

Tema sistemi iki bağımsız, tamamlayıcı katmana sahiptir.

Ek olarak, PrimeVue preset katmanı build zamanında VITE_SK_THEME'e bağlıdır:

Runtime kit temaları — main ve aura #

main ve aura temaları her build'de her zaman bundle'a dahil edilir. Aralarında geçiş yapmak için derleme gerekmez; useTheme composable'ı appearance.theme'i paylaşılan Inertia prop'larından okur ve mount'ta ve her prop değişiminde <html data-sk-theme="aura"> yazar (ya da main için attribute'u kaldırır).

• main — varsayılan. <html> üzerinde data-sk-theme attribute'u yoktur; tüm base kurallar geçerlidir.
• aura — <html> üzerinde data-sk-theme="aura" ayarlandığında etkinleşir. Aura'nın tüm kuralları html[data-sk-theme='aura']'ya scope'ludur; attribute yokken etkinsizdirler.

Admin panelindeki Ayarlar → Görünüm ekranından geçiş yapın; değişiklik anında geçerli olur ve admin genelinde kalıcıdır. Kullanıcı başına override yoktur.

Build-zamanı custom temalar #

Custom temalar resources/css/theme/<isim>/ dizinlerinde yaşar ve tam-değiştirme + fallback slot modelini kullanır — aşağıdaki CSS tema sistemi bölümüne bakın. Etkin olabilmeleri için .env'de VITE_SK_THEME=<isim> ve bir npm run build / npm run dev gereklidir. Ayarlar → Görünüm'de bir custom tema seçildiğinde arayüzde "derleme gerekir" notu gösterilir.

İki katman bağımsızdır: VITE_SK_THEME=custom (build-zamanı custom taban) kullanırken runtime attribute main ve aura görsel stilleri arasında geçiş yapabilir. Bir tokens.css override'ı genellikle preset'in emit ettiği --p-* token'larını okur — aşağıdaki Bağımlılık zinciri bölümüne bakın.

CSS tema sistemi #

Dizin yapısı #

resources/css/
├── theme/
│   ├── theme.css              # Giriş noktası: _active.css'i ardından theme-runtime/aura/aura.css'i import eder
│   ├── _active.css            # OLUŞTURULAN — elle düzenleme; gitignore'da
│   ├── main/                  # Dahili ana tema (tüm slot'lar için kaynak)
│   │   ├── tokens.css         # CSS custom property'leri: layout ölçüleri, renkler, gölgeler
│   │   ├── fonts.css          # Web font bildirimleri
│   │   ├── _base.scss         # Base reset / tipografi
│   │   ├── layout/
│   │   │   ├── shell.css        # .admin-layout, .admin-main, Vue geçişleri
│   │   │   ├── sidebar.css      # .admin-sidebar*, .admin-overlay
│   │   │   ├── header.css       # .admin-header*
│   │   │   ├── page-header.css  # .admin-page-header*
│   │   │   └── footer.css       # .admin-footer*
│   │   ├── components/
│   │   │   ├── card.css
│   │   │   ├── button.css
│   │   │   ├── confirm.css
│   │   │   ├── datatable.css
│   │   │   ├── dialog.css
│   │   │   ├── editor.css
│   │   │   ├── formbuilder.css
│   │   │   ├── menus.css
│   │   │   ├── message.css
│   │   │   ├── navigation.css
│   │   │   ├── primevue.css
│   │   │   ├── tabs.css
│   │   │   ├── tag.css
│   │   │   └── toast.css
│   │   ├── _auth.scss         # Auth layout stilleri
│   │   └── utilities.css      # Tailwind utility override'ları
│   └── custom/                # Override tema — kit ile gönderilmez; siz oluşturursunuz
│       └── (gerektiğinde oluşturun — aşağıdaki reçetelere bakın)
└── theme-runtime/
    └── aura/                  # Runtime kit teması — her zaman bundle'da, html[data-sk-theme='aura']'ya scope'lu
        ├── aura.css           # Index: aşağıdaki dört dosyayı sırayla import eder
        ├── tokens.css         # Çerçeve/panel/sidebar token'ları (scope'lu + koyu + sidebar varyantları)
        └── layout/
            ├── shell.css        # Marka renkli çerçeve + gömülü yuvarlatılmış panel
            ├── sidebar.css      # Çerçeve üzerinde statik sidebar, sürüm çipi, mobil drawer
            └── header.css       # 70px panel header'ı, solid dev/debug etiketleri

Kit artık boş bir custom/ dizini göndermez. Herhangi bir slot'u override etmek istiyorsanız dizini önce kendiniz oluşturun (aşağıdaki reçetelere bakın).

theme-runtime/aura/, build-zamanı slot dizini değildir. Resolver (sk-theme-build.mjs) tarafından okunmaz; VITE_SK_THEME=aura ayarının hiçbir etkisi yoktur — aura yalnızca data-sk-theme attribute'u üzerinden runtime'da etkinleşir.

Kit ile gelen aura teması #

aura, kit'in ikinci yerleşik temasıdır. Admin shell'i marka renkli bir çerçeve içine gömülü, yuvarlatılmış bir panel olarak yeniden biçimlendirir: sidebar doğrudan çerçevenin üzerinde durur (renkli stilde beyaz aktif pill), header/içerik/footer panel yüzeyini paylaşır. Yalnızca dört görsel alanı override eder — tokens.css, layout/shell.css, layout/sidebar.css, layout/header.css — geri kalan her şey (navigation, footer, page-header, tüm bileşenler) main'e düşer ve sadece token'lar üzerinden yeniden boyanır.

Çerçeve rengi aktif PrimeVue primary'sini izler (--p-primary-800); mevcut accent seçici tüm çerçeveyi yeniden renklendirir. Sidebar stil anahtarı (colored / light) ve koyu mod tam desteklidir.

aura'yı etkinleştirme: Admin Ayarlar → Görünüm ekranını açın ve Aura tema kartını seçin. Değişiklik anında uygulanır — derleme adımı gerekmez. Ayar admin genelinde geçerlidir (appearance.theme olarak DB'ye kaydedilir).

aura'nın CSS'i resources/css/theme-runtime/aura/ içinde yer alır ve main ile birlikte her zaman bundle'a dahil edilir. Tüm kuralları html[data-sk-theme='aura']'ya scope'ludur; attribute yokken tamamen etkisizdirler. useTheme composable'ı (AdminLayout içinde çağrılır), Inertia paylaşılan appearance.theme prop'una yanıt olarak bu attribute'u yazar ve kaldırır.

VITE_SK_THEME=aura kullanmayın — bu değişken yalnızca build-zamanı custom-tema resolver'ını denetler; aura slot tabanlı bir tema değildir. Bu ayarı yapmak aura'nın runtime davranışını etkilemez ve resolver'dan beklenmedik sonuçlara yol açabilir.

Resolver nasıl çalışır #

sk-theme-build.mjs, kit tarafından yönetilen ve paketin içinde gelen bir build scriptidir (vendor-resident; vendor/lvntr/laravel-starter-kit/resources/js/theme/sk-theme-build.mjs). Bu dosya sizin sahiplendiğiniz ya da düzenlediğiniz bir dosya değildir — yalnızca resources/ dizininizdeki tema/slot/preset dosyaları sizin özelleştirme alanınızdır. Script, dev ve build sırasında skTheme() Vite plugin'i tarafından otomatik çağrılır ve theme/_active.css'i üretir. Model tam-değiştirme + fallback'tir:

1. main/ slot listesi ve import sırası için kanoniktir.
2. Her slot için resolver, <aktif>/<slot> dosyası varsa onu yükler; yoksa main/<slot>'a döner.
3. Sonuç, doğru cascade sırasında her slot için bir @import içeren tek bir _active.css'tir.

custom/ dizini hiç yoksa bile build tamamlanır — her slot main'e düşer.

Import sırası (orijinal cascade'den korunur):

tokens → fonts → _base → layout/* → components/* → _auth → utilities

Her katman artık bir slot'tur. Yalnızca components/datatable.css gönderen bir custom tema yalnızca datatable'ı ezer. Diğer her şey main'e döner. custom/'da main/'deki hiçbir slot yoluna uymayan bir dosya yok sayılır — resolver main'in slot listesini dolaşır, custom dizini değil.

Not: _base.scss ve _auth.scss .scss dosyalarıdır — uzantıları korunur. Resolver uzantı-farkındadır; Sass derlemesi eskisiyle aynı pipeline ile yönetilir.

VITE_SK_THEME ile aktivasyon #

VITE_SK_THEME yalnızca build-zamanı custom tema resolver'ını denetler. Runtime kit temaları (main, aura) üzerinde hiçbir etkisi yoktur — bunlar her zaman bundle'da bulunur ve runtime'da data-sk-theme attribute'u aracılığıyla etkinleşir.

Aktif custom temayı .env'de belirtin:

VITE_SK_THEME=custom

Varsayılan main'dir. Değişken yoksa veya boşsa main kullanılır; yani tüm slot'lar main/'e çözümlenir ve hiçbir custom dosya yüklenmez. npm run dev veya npm run build çalıştırın — skTheme() Vite plugin'i, Vite herhangi bir asset'i işlemeden önce resolver'ı çalıştırarak _active.css'i yeniden üretir. Bu yaklaşım, npm lifecycle hook'larına dayanmadığı için ignore-scripts=true altında da güvenle çalışır.

Tam build yapmadan çözümlenen manifesti önizlemek için theme:build npm script'ini kullanın:

npm run theme:build
# [sk-theme-build] → resources/css/theme/_active.css (25 slot, 1 override)

Ya da vendor script'ini doğrudan çağırın:

node vendor/lvntr/laravel-starter-kit/resources/js/theme/sk-theme-build.mjs

resources/css/theme/_active.css'i açarak her slot'un hangi dosyaya çözümlendiğini görebilirsiniz. Override'lanan slot'lar /* override */ ile işaretlenir.

_active.css — üretilen artefakt #

_active.css bir build artefaktıdır:

• .gitignore'da listelenmiştir — asla commit etmeyin.
• sk:update tarafından hash-takip edilmez — her npm run dev / npm run build'de yeniden üretilir.
• skTheme() plugin'i resolver'ı Vite asset'leri işlemeden önce çalıştırdığı için Vite başlamadan önce her zaman mevcuttur.

Özel tema reçetesi #

Tek bir bileşeni override etme #

Datatable'ı başka hiçbir şeye dokunmadan yeniden stillemek için:

1. Custom dizinini oluşturun ve override etmek istediğiniz slot'u kopyalayın:

   mkdir -p resources/css/theme/custom/components
   cp resources/css/theme/main/components/datatable.css \
      resources/css/theme/custom/components/datatable.css
   

2. custom/components/datatable.css'i düzenleyin. Aynı class adlarını koruyun — Vue bileşenleri onları hedefler.

3. .env'de VITE_SK_THEME=custom olarak ayarlayın.

4. npm run dev çalıştırın. skTheme() plugin'i Vite başlamadan önce _active.css'i yeniden üretir; custom/components/datatable.css, import listesinde main/components/datatable.css'in yerini alır. Diğer tüm slot'lar main'den gelmeye devam eder.

Çözümlenen manifesti doğrulayın:

@import './main/tokens.css';
@import './main/fonts.css';
@import './main/_base.scss';
@import './main/layout/footer.css';
…
@import './custom/components/datatable.css'; /* override */
@import './main/components/dialog.css';
…
@import './main/_auth.scss';
@import './main/utilities.css';

Token setini override etme #

Layout ölçülerini, renkleri veya gölgeleri genel olarak değiştirmek için tokens.css'i override edin:

mkdir -p resources/css/theme/custom
cp resources/css/theme/main/tokens.css \
   resources/css/theme/custom/tokens.css

Custom property'leri düzenleyin. Tüm layout bölgeleri ve bileşenler bu token'ları okur; dolayısıyla bir token değişikliği bağımsız bileşen dosyalarına dokunmadan her yere yayılır.

Bir layout bölgesini override etme #

mkdir -p resources/css/theme/custom/layout
cp resources/css/theme/main/layout/sidebar.css \
   resources/css/theme/custom/layout/sidebar.css

İstediğiniz gibi düzenleyin. Yalnızca sidebar slot'u değiştirilir; layout'un geri kalanı main'den gelir.

Font veya utilities'i override etme #

Font bildirimleri ve Tailwind utility override'ları artık diğer her slot gibi birer slot'tur. Layout veya bileşenlere dokunmadan kendi fontlarınızı kullanmak için:

mkdir -p resources/css/theme/custom
cp resources/css/theme/main/fonts.css \
   resources/css/theme/custom/fonts.css

custom/fonts.css içindeki @font-face bildirimlerini düzenleyin. Sonraki build'de _active.css, main sürümü yerine sizin font dosyanızı kullanır; diğer tüm slot'lar main'den gelmeye devam eder.

Benzer şekilde Tailwind utility override'ları için:

mkdir -p resources/css/theme/custom
cp resources/css/theme/main/utilities.css \
   resources/css/theme/custom/utilities.css

utilities.css unlayered olup cascade'de en son emit edildiğinden her katmanlı kurala galip gelir — öncekiyle aynı öncelik davranışı. Serbestçe düzenleyebilirsiniz.

Auth stillerini override etme #

mkdir -p resources/css/theme/custom
cp resources/css/theme/main/_auth.scss \
   resources/css/theme/custom/_auth.scss

custom/_auth.scss'i düzenleyin. .scss uzantısı zorunludur — resolver ve Sass derleyicisi uzantı-farkındadır.

Tam slot referansı #

Notlar #

• Özel tema slot'ları dosya bütünüyle değiştirir — cascade diff yoktur. Başlangıç noktası olarak main dosyasını kopyalayın.
• Özel temalar yeni slot ekleyemez. custom/'daki main/'de eşleşen yolu olmayan bir dosya hiçbir zaman import edilmez.
• VITE_SK_THEME=main (varsayılan) stok panel ile byte-identical bir build üretir — hiçbir custom dosya yüklenmez.
• Kit custom/ dizini göndermez. Override eklemeden önce dizini kendiniz oluşturun; dizin yoksa her slot main'e çözümlenir.
• Artık ihtiyaç duymadığınız custom/ dosyalarını kaldırın; resolver otomatik olarak main'e döner.
• .scss uzantılı slot'lar (_base.scss, _auth.scss) custom/ içinde de aynı uzantıyı taşımalıdır.

PrimeVue preset katmanı #

Nasıl çalışır #

resources/js/theme/preset.ts, PrimeVue styled-mode preset'in tabanıdır — birincil palet, yüzey renkleri, border radius ve bileşen başına token'ları tanımlar. app.ts bunu @/theme/preset olarak import eder. Import yolu hiçbir zaman değişmez.

vite.config.ts'teki alias customResolver — kit'in vendor-resident vite-plugin-sk-theme.mjs'inden export edilen resolveActivePreset helper'ı — @/theme/preset specifier'ını build zamanında yakalar:

• VITE_SK_THEME değeri main değilse ve resources/js/theme/<aktif>/preset.ts mevcutsa → override dosyasına çözümlenir.
• Aksi takdirde → taban resources/js/theme/preset.ts'e çözümlenir.

Taban dosya daima yerinde kalır — kit onu asla taşımaz çünkü consumer projesinde en sık özelleştirilen dosyadır.

Dizin düzeni #

resources/js/theme/
├── preset.ts              # Taban preset (consumer tarafından özelleştirilebilir; yerinde kalır)
└── custom/                # Kit ile gönderilmez — gerektiğinde kendiniz oluşturun
    └── preset.ts          # (siz oluşturursunuz — aşağıdaki reçeteye bakın)

custom/ dizini kit tarafından gönderilmez. custom temasının preset'i varsayılan olarak yoktur; bu nedenle taban preset kullanılır ve PrimeVue görünümü stok panelle byte-identical kalır. Temaya özel preset override'ı ihtiyaç duyduğunuzda dizini kendiniz oluşturun.

Custom temaya kendi PrimeVue paletini verme #

1. resources/js/theme/custom/preset.ts oluşturun (custom/ dizini yoksa önce oluşturun). En basit yaklaşım, taban preset'i import edip yalnızca paleti override etmektir:

   mkdir -p resources/js/theme/custom
   

   import { definePreset } from '@primevue/themes';
   import Material from '@primevue/themes/material';
   import AppPreset from '../preset';
   
   export default definePreset(Material, {
       ...AppPreset,
       semantic: {
           ...AppPreset.semantic,
           primary: {
               50:  '{emerald.50}',
               100: '{emerald.100}',
               200: '{emerald.200}',
               300: '{emerald.300}',
               400: '{emerald.400}',
               500: '{emerald.500}',
               600: '{emerald.600}',
               700: '{emerald.700}',
               800: '{emerald.800}',
               900: '{emerald.900}',
               950: '{emerald.950}',
           },
       },
   });
   

2. .env'de VITE_SK_THEME=custom olarak ayarlayın.

3. npm run dev veya npm run build çalıştırın. Plugin, @/theme/preset'i override dosyanıza çözümler; override yoksa tabana döner.

Notlar #

• Preset nesnesini default export olarak dışa aktarın — app.ts bunu PrimeVue'nun preset seçeneğine geçirir.
• Override yalnızca VITE_SK_THEME=custom olduğunda ve resources/js/theme/custom/preset.ts mevcut olduğunda uygulanır. Diğer her değerde tabana döner.
• Kit resources/js/theme/ altında custom/ dizini göndermez. Temaya özel preset ihtiyacınızda kendiniz oluşturun.
• Üretilen artefakt yoktur. Bu saf modül çözümlemesidir — gitignore'a alınacak _active dosyası yok, bakılacak npm zinciri yok.

Bağımlılık zinciri — token'lar ve preset #

resources/css/theme/main/tokens.css (ve varsa custom/tokens.css override'ı), layout ve bileşenlerin kullandığı --admin-* custom property'lerini tanımlar. Bunlar, PrimeVue preset'inin çalışma-zamanında emit ettiği --p-* değişkenlerine canlı referanslardır:

/* tokens.css — admin rolleri PrimeVue preset çıktısına bağlanır */
--admin-sidebar-bg: var(--p-surface-900);
--admin-sidebar-item-active-bg: var(--p-primary-color);

Canlı var() referansı oldukları için, preset override'ınızda birincil/yüzey paletini değiştirmek otomatik olarak akar — --admin-* rolleri yeni --p-* değerlerine yeniden çözülür; "senkronize edilecek" bir şey yoktur.

tokens.css'i yalnızca bir admin rolünün hangi PrimeVue token'ına bağlandığını yeniden eşlemek isterseniz override edin (örn. sidebar'ı farklı bir surface adımından okutmak):

mkdir -p resources/css/theme/custom
cp resources/css/theme/main/tokens.css \
   resources/css/theme/custom/tokens.css

Ardından --admin-* property'lerini seçtiğiniz --p-* token'larına göre düzenleyin.

Accent renk sistemi #

Admin paneli, PrimeVue birincil paletini ve sidebar yüzeyini derleme gerektirmeden çalışma zamanında yeniden boyayan bir accent rengi destekler. Sistem iki katmana sahiptir: admin global varsayılanı (Ayarlar → Görünüm'den ayarlanır) ve isteğe bağlı kullanıcı başına override (header popover'dan ayarlanır). Kullanıcının kişisel bir seçimi yoksa admin global varsayılanı uygulanır; admin global varsayılanı da 'default' ise kit birincil rengi kullanılır (main altında mavi, aura altında indigo).

Nasıl çalışır #

useAccentColor (vendor-resident composable, resources/js/composables/useAccentColor.ts) accent rengini yönetir. onMounted'da ve watch içinde şunları çağırır:

1. updatePrimaryPalette(palette) — PrimeVue'nun çalışma zamanı palet değişimi. Aktif --p-primary-* CSS custom property'lerini seçilen Tailwind v4 oklch ölçeğiyle değiştirir; düğmeler, bağlantılar, odak halkaları, aktif durumlar ve her --p-primary-color referansı derleme gerektirmeden anında güncellenir.
2. <html> üzerinde data-sk-accent — tokens.css tarafından aydınlık modda sidebar yüzeyine derin accent tonunu uygulamak için kullanılan bir işaretçidir. Koyu modda sidebar her zaman nötr koyu yüzeyde kalır; yalnızca aktif öğeler ve düğmeler accent rengini taşır. Accent 'default' olduğunda işaretçi yoktur.

Sidebar yüzey işlemi accent'ten bağımsızdır: sidebarStyle değeri ('colored' | 'light'), <html> üzerindeki data-sk-sidebar işaretçisini denetler. data-sk-sidebar="light" mevcutsa sidebar koyu metinle beyaz/açık yüzey gösterir; yoksa (varsayılan 'colored'), derin accent tonu (koyu modda nötr koyu) uygulanır.

Mevcut renkler #

ACCENT_COLORS, seçilebilir 26 ismi listeler: 22 standart Tailwind v4 paleti (slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose) ve dört özel sönük ton (taupe, mauve, mist, olive). 'default' özel değeri "admin global varsayılanını kullan" (global da 'default' ise kit primary'sine dön) anlamına gelir.

Tüm palet değerleri composable içinde satır içi Tailwind v4 oklch ölçekleridir — Tailwind, kullanılmayan --color-* değişkenlerini tree-shake ettiğinden çalışma zamanında CSS değişkenlerinden okunmazlar.

Kalıcılık #

Hem accent seçimi hem de sidebar stili localStorage'a kaydedilir:

writeDefaults: false seçeneği, ilk kez giren kullanıcı için localStorage'ın boş kalmasını sağlar; böylece kullanıcı açıkça bir renk seçene kadar admin global varsayılanı her zaman geçerlidir. Tek seferlik eski storage temizliği (migrateLegacyAppearanceStorage), eski derlemelerdeki isteksiz writeDefaults: true tarafından yazılmış 'default' / false / 'colored' seed'leri kaldırır.

Admin global varsayılanı ve kullanıcı override'ı #

appearance paylaşılan prop'u (her Inertia yanıtında HandleInertiaRequests tarafından sağlanır) şunları taşır:

useAppearanceDefaults bu prop'u okur. useAccentColor, kullanıcının kişisel seçimi olmadığında başlangıç değerlerini oluşturmak için defaultAccent ve defaultSidebarStyle'ı ondan alır.

Global varsayılanı Ayarlar → Görünüm → Varsayılan Renk'ten yapılandırın. Admin tarafı seçici canlı önizleme gösterir: bir renk seçmek applyAccent(color, { followGlobal: false }) çağırır; bu, 'default''u kit primary olarak değerlendirir (admin varsayılanı tanımladığı için kit mavisinin nasıl göründüğünü görmelidir). Sekmeden kaydetmeden çıkıldığında kullanıcının kendi oturum accent'i geri yüklenir.

Her admin kullanıcısına açık header popover, aynı renk ızgarasını ve bir "Varsayılan" renk kutusu gösterir. Renk seçmek setAccent(color) çağırır ve localStorage'a kaydeder; accent üzerindeki watch otomatik olarak applyAccent'i tetikler. "Varsayılan"ı seçmek kişisel override'ı temizler ve admin global varsayılanı tekrar geçerli olur.

Tema etkileşimi #

• main varsayılan accent: mavi ({blue.x} token referansları, Material preset'e göre çözümlenir).
• aura varsayılan accent: indigo (Tailwind v4 oklch ölçeği). Runtime tema main ve aura arasında geçiş yaptığında, useAccentColor paleti otomatik olarak yeniden uygular (appearance.theme üzerindeki watch, applyAccent'i tetikler); böylece 'default' accent aktif tema için doğru imza rengini seçer.
• Aura çerçeve rengi (--p-primary-800) aktif primary'yi takip eder; aura altında accent seçici tüm çerçeveyi yeniden renklendirir.

Sayfa yükleyici ve accent #

SkPageLoader — Inertia sayfa geçişlerinde gösterilen tam ekran animasyonlu overlay — marka öğeleri için --p-primary-color kullanır (ışınlar, damlacıklar, sekme noktaları, dalga tepesi harf rengi). updatePrimaryPalette çalışma zamanında --p-primary-color'ı güncellediğinden, sayfa yükleyici otomatik olarak aktif accent rengini kullanır. Overlay arka planı tema-güdümlüdür:

• main: --admin-sidebar-bg (koyu sidebar yüzeyi).
• aura: --p-surface-900 (aydınlık) / --p-surface-950 (koyu) — aura'nın --admin-sidebar-bg'si şeffaf olduğundan nötr koyu yüzey kullanılır.

Stiller components/page-loader.css tema slotunda yaşar (custom tema ile override edilebilir). Overlay SSR-güvenlidir ve prefers-reduced-motion'ı destekler. Opt-in'dir — açmak için AdminLayout overlays slot'una <SkPageLoader/> ekleyin (bkz. ui-components.tr.md — SkPageLoader).

Karanlık mod #

Karanlık mod için CSS custom property'leri main/tokens.css içindeki .dark { … } bloklarında (ve layout-özel karanlık mod override'larının bulunduğu layout dosyalarında) tanımlanır. tokens.css'i override ederseniz, .dark bloklarını da kopyalayın.

Karanlık mod useDarkMode ile değiştirilir — <html> üzerine dark sınıfı ekler / kaldırır. Ayrı bir build adımı veya CSS dosyası gerekmez.

aura temasının karanlık mod kuralları theme-runtime/aura/tokens.css içindeki html.dark[data-sk-theme='aura'] { … } blokları olarak tanımlanır. Her iki attribute bağımsızdır — karanlık mod ve tema geçişi dört kombinasyonun tamamında doğru şekilde birleşir (aydınlık/koyu × main/aura).

İlgili belgeler #

• docs/install.md — ilk kurulum
• docs/update.md — sk:update ve hash-takipli stub'lar
• docs/UPGRADE.md — mevcut projeler için geçiş rehberi