Arsitektur SCSS dan Variabel Tema

Bundel CSS Mazer berakar pada satu entry, src/assets/scss/app.scss. Berkas itu hampir tidak menulis aturan style sendiri; isinya urutan @import: variabel lebih dulu, lalu Bootstrap dan Bootstrap Icons, lalu _mazer.scss src/assets/scss/app.scss:1-21¹. Urutan ini menentukan nilai akhir setiap variabel, karena Sass memakai nilai yang berlaku pada saat aturan ditulis.

Urutan import app.scss

app.scss mengimport ./variables di baris pertama, baru kemudian Bootstrap dan Bootstrap Icons src/assets/scss/app.scss:4-7². Setelah font dan perfect-scrollbar, berkas ditutup dengan ./mazer src/assets/scss/app.scss:20-21³.

graph TD
  app["app.scss"] --> vars["_variables.scss"]
  app --> bs["~bootstrap/scss/bootstrap"]
  app --> icons["~bootstrap-icons/font/bootstrap-icons"]
  app --> fonts["_fonts.scss"]
  app --> ps["~perfect-scrollbar/css/perfect-scrollbar.css"]
  app --> mazer["_mazer.scss"]
  mazer --> mixins["mixins/_navbar.scss"]
  mazer --> comps["components/*.scss (20 berkas)"]
  mazer --> layouts["layouts/main.scss"]
  mazer --> utils["_utilities.scss"]
  style vars fill:#f59e0b,color:#000
  style mazer fill:#f59e0b,color:#000
  style comps fill:#8b5cf6,color:#fff
  style utils fill:#8b5cf6,color:#fff
%% fig: Urutan import app.scss
%% desc: Variabel dimuat lebih dulu, lalu Bootstrap dan aset pihak ketiga, dan terakhir _mazer.scss yang memecah lapisan komponen.

_fonts.scss adalah kumpulan lima blok @font-face untuk keluarga Nunito pada bobot 300, 400, 600, 700, dan 800. Semuanya memakai font-display: swap dan menunjuk berkas .woff2/.woff di @/assets/static/fonts/ src/assets/scss/_fonts.scss:1-47⁶.

⚠️ _variables.scss mengimport ~bootstrap/scss/functions dua kali pada dua blok berurutan src/assets/scss/_variables.scss:8-16⁷. Import ganda itu tidak mengubah hasil, tetapi menandakan berkas ini disusun bertahap. Jangan menyimpulkan bahwa urutan import di berkas lain juga bebas.

Ada entry kedua, bootstrap.scss, yang memuat variabel Bootstrap lalu mengimport variables di tengah import-stack-nya src/assets/scss/bootstrap.scss:8-17⁸. Karena hampir semua variabel Mazer memakai !default, nilai akhir pada jalur ini bergantung pada siapa yang mendefinisikan lebih dulu, bukan pada berkas mana yang dianggap utama.

Lapisan di _mazer.scss

Komentar kepala _mazer.scss mencantumkan table of contents bernomor 1 sampai 5 src/assets/scss/_mazer.scss:9-42⁹. Import sebenarnya mengikuti urutan itu, dimulai dari mixin lalu komponen.

Setiap berkas komponen menimpa selector Bootstrap dengan variabel dari _variables.scss. Contohnya _card.scss membuang border kartu, memakai $card-cap-padding-y dan $card-cap-padding-x untuk .card-body, serta $card-title-font-size untuk judul src/assets/scss/components/_card.scss:1-68¹³. Berkas yang sama juga membaca map tema lewat map-get($theme-colors, 'success') src/assets/scss/components/_card.scss:96¹⁴.

_sidebar.scss memakai variabel khusus sidebar: .sidebar-wrapper berlebar 300px, position: fixed, dan background-color: $sidebar-bg src/assets/scss/components/_sidebar.scss:36-45¹⁵. Di sisi lain, layouts/main.scss menetapkan #main { margin-left: 300px } sebagai angka literal src/assets/scss/layouts/main.scss:1-19¹⁶.

⚠️ Lebar sidebar 300px muncul di dua tempat tanpa variabel bersama: $sidebar-* di _variables.scss dan angka 300px di _sidebar.scss serta layouts/main.scss. Mengubah lebar sidebar menuntut perubahan di kedua berkas itu.

_utilities.scss menunjukkan bagaimana satu variabel menyebar ke output: ia mengiterasi $theme-colors-light dengan @each, lalu memilih nilai background-color berbeda ketika $dark-mode bernilai benar src/assets/scss/_utilities.scss:24-44¹⁷. Cabang yang sama dipakai _alert.scss src/assets/scss/components/_alert.scss:25¹⁸. Nilai $dark-mode sendiri dideklarasikan false di berkas variabel src/assets/scss/_variables.scss:12¹⁹, dan mekanisme pengubahannya dibahas di Mode Gelap dan Persistensi Tema.

Variabel tema di _variables.scss

$font-family-base: "Nunito" sejalan dengan @font-face di _fonts.scss, sehingga mengganti keluarga font menuntut perubahan di dua berkas. Perhatikan juga bahwa $dark didefinisikan sebagai $body-bg src/assets/scss/_variables.scss:160-182²⁴, sementara kunci dark di $theme-colors bernilai #131313 src/assets/scss/_variables.scss:204-217²⁵. Keduanya bukan warna yang sama.

Lapisan pages dan widgets

Tidak semua SCSS masuk ke bundel inti. Berkas di pages/ dan widgets/ dimuat per halaman lewat tag <link> di HTML, dan masing-masing mengimport ulang variabel agar tetap mandiri.

graph LR
  authHtml["src/layouts/auth.html"] --> authScss["pages/auth.scss"]
  chatHtml["src/ui-widgets-chatbox.html"] --> chatScss["widgets/chat.scss"]
  dtHtml["src/table-datatable.html"] --> dtScss["pages/simple-datatables.scss"]
  authScss --> vars["_variables.scss"]
  chatScss --> vars
  style vars fill:#f59e0b,color:#000
  style authScss fill:#8b5cf6,color:#fff
  style chatScss fill:#8b5cf6,color:#fff
  style dtScss fill:#8b5cf6,color:#fff
%% fig: Stylesheet halaman dimuat di luar bundel inti
%% desc: Halaman tertentu menautkan berkas di pages/ atau widgets/ lewat tag link, dan berkas itu mengimport ulang _variables.scss sendiri.

pages/auth.scss membuka berkasnya dengan @import "../variables" src/assets/scss/pages/auth.scss:1-13³¹, jadi variabel Mazer tetap tersedia walau berkas itu tidak melewati app.scss. Berkas yang sama juga memuat blok html[data-bs-theme="dark"] yang mengimport ../themes/dark/variables-dark lalu menyusun ulang latar #auth-right src/assets/scss/pages/auth.scss:44-50³². Pola serupa dipakai widgets/chat.scss, yang mengimport ./../variables di baris pertama sebelum menata .chat-message src/assets/scss/widgets/chat.scss:1-26³³.

Mengubah tema tanpa merusak lapisan

Bundel gelap tidak menyalin komponen. app-dark.scss memuat variabel gelap, lalu mengimport ulang mazer dan menambahkan mazer-dark sebelum utilities Bootstrap src/assets/scss/themes/dark/app-dark.scss:53-57³⁴. Yang berubah hanyalah nilai variabel: _variables-dark.scss menetapkan $dark-mode: true src/assets/scss/themes/dark/_variables-dark.scss:3³⁵, dan cabang @if($dark-mode) di komponen menghasilkan output berbeda.

Untuk menambah komponen, letakkan berkas baru di src/assets/scss/components/ dan daftarkan import-nya pada blok komponen src/assets/scss/_mazer.scss:47-107¹¹. Untuk style yang hanya dipakai satu halaman, letakkan di pages/ atau widgets/ dan muat lewat <link> seperti tabel di atas. Alur build yang menggabungkan semuanya dijelaskan di Alur Build Vite dan Nunjucks, sedangkan build rtlcss dibahas di Layout RTL dan Build rtlcss.