Design on kenji.blog

Kustomisasi Tema Hugo: Cara Mengimplementasikan Tailwind CSS

Sun, 13 Sep 2026 03:00:00 +0900

Pengantar: Sinergi Kuat antara Hugo Static Site Generator dan Tailwind CSS

Dalam pengembangan frontend web modern, menyeimbangkan kinerja dan pengalaman pengembangan (DX: Developer Experience) adalah salah satu masalah paling penting dalam setiap proyek. Menggabungkan Hugo, yang membanggakan kecepatan build tercepat di dunia di antara Static Site Generators (SSG), dengan Tailwind CSS, yang membawa paradigma inovatif berupa utility-first, bisa dikatakan sebagai salah satu solusi utama untuk tantangan ini.

Hugo ditulis dalam bahasa Go dan memiliki performa luar biasa yang menyelesaikan proses build hanya dalam beberapa detik atau bahkan milidetik, bahkan untuk situs dengan ribuan halaman. Di sisi lain, Tailwind CSS memungkinkan Anda menulis kelas utilitas yang sudah ditentukan sebelumnya (seperti flex, text-center, mt-4) secara langsung di HTML, menghilangkan konteks switching antara file CSS dan HTML, serta mempercepat iterasi desain.

Dalam artikel ini, kami akan menjelaskan langkah-langkah untuk mengimplementasikan Tailwind CSS pada tema Hugo, dan selanjutnya membangun asset pipeline tingkat lanjut (Hugo Pipes) menggunakan PostCSS. Kami akan membahas ini secara detail, mulai dari fondasi arsitektur hingga optimasi performa matematis.

1. Evolusi CSS Utility-First dan Pendekatan Berorientasi Komponen

Sebelum masuk ke langkah-langkah implementasi Tailwind CSS, sangat bermanfaat untuk memahami secara mendalam sejarah dan evolusi filosofi desain CSS di balik mengapa kita harus menggunakan Tailwind CSS.

Keterbatasan Desain CSS Tradisional (BEM dan OOCSS)

Dalam pengembangan web di masa lalu, memberikan penamaan kelas semantik dianggap sebagai praktik terbaik. Misalnya, saat membuat komponen kartu, kita memisahkan HTML dan CSS seperti ini.

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">Judul</h2>
 <p class="card__description">Teks deskripsi ada di sini.</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* Kode gaya (style) lebih lanjut berikutnya */

Desain berbasis BEM (Block Element Modifier) seperti ini berfungsi baik saat ukuran proyek masih kecil, tetapi cenderung menimbulkan masalah berikut:

Penamaan yang Melelahkan dan Habis: Setiap kali kita membuat komponen serupa, kita harus memikirkan nama kelas baru (misalnya, card-news, card-featured).
Pembengkakan CSS: Setiap kali fitur baru ditambahkan, baris CSS terus bertambah. Karena rasa takut “tidak tahu di mana CSS tersebut digunakan”, kode jarang dihapus, dan dead code menumpuk.
Konteks Switching: Karena struktur HTML dan gaya CSS dikelola dalam file yang berbeda, jumlah pergantian tab di editor meningkat secara eksponensial.

Pergeseran Paradigma oleh Tailwind CSS

Tailwind CSS memecahkan masalah ini dengan pendekatan “kombinasi kelas utilitas”. Komponen kartu di atas akan terlihat seperti ini jika menggunakan Tailwind CSS.

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">Judul</h2>
 <p class="mt-2 text-gray-600">Teks deskripsi ada di sini.</p>
 </div>
</div>

Karena nama kelas itu sendiri mewakili nilai gaya spesifik (seperti p-6 berarti padding: 1.5rem;), Anda dapat memprediksi hasil akhir render hanya dengan melihat HTML-nya. Selain itu, kompiler JIT (Just-In-Time) Tailwind mengekstrak hanya kelas yang benar-benar digunakan ke dalam file CSS untuk production, yang membuat ukuran file CSS menjadi sangat kecil.

2. Arsitektur Hugo Pipes dan PostCSS

Untuk mengintegrasikan Tailwind CSS dengan Hugo, Anda perlu memahami asset processing pipeline yang disebut Hugo Pipes. Hugo Pipes adalah fitur yang kuat yang menangani seluruh proses yang berkaitan dengan aset di dalam Hugo, seperti mengkompilasi Sass/SCSS, mem-bundle dan mengecilkan (Minify) JavaScript, dan mengeksekusi PostCSS yang akan kita gunakan di sini.

PostCSS adalah alat untuk mengubah CSS menggunakan plugin JavaScript. Tailwind CSS itu sendiri juga beroperasi sebagai plugin untuk PostCSS.

Mekanisme Transformasi AST (Abstract Syntax Tree) dengan PostCSS

Memahami bagaimana PostCSS memproses CSS sangat membantu saat melakukan pemecahan masalah (troubleshooting). Diagram Mermaid berikut menunjukkan pipeline dari PostCSS membaca file CSS, mengubahnya melalui plugin, hingga output CSS final.

flowchart TD
A["CSS Mentah (styles.css)"] -->|Parser| B["AST (Abstract Syntax Tree)"]
B --> C["Plugin 1: Tailwind CSS"]
C --> D["Plugin 2: Autoprefixer"]
D --> E["Plugin N: cssnano"]
E -->|Stringifier| F["CSS Terkompilasi & Teroptimasi"]

Parser: Mengurai (parsing) string CSS mentah yang dimasukkan dan mengubahnya menjadi AST (Abstract Syntax Tree), struktur data yang dapat dimanipulasi oleh program.
Plugins (Kumpulan plugin):
- Tailwind CSS: Memindai file template (HTML atau Markdown) dan menambahkan kelas utilitas yang digunakan sebagai node pada AST. Ini juga mengekspansi arahan (directive) @tailwind.
- Autoprefixer: Merujuk ke database Can I Use dan menambahkan prefiks vendor (seperti -webkit-, -moz-) pada properti di AST jika diperlukan.
Stringifier: Mengubah kembali AST yang sudah diproses menjadi string CSS yang dapat dipahami oleh browser sebagai output.

3. Pengaturan Lingkungan dan Prasyarat

Sekarang, mari kita masuk ke langkah-langkah implementasi yang sebenarnya. Pertama, pastikan perangkat lunak yang diperlukan sudah terinstal.

Persyaratan Utama

Hugo Extended Version: Alih-alih versi Hugo biasa, versi Extended mutlak diperlukan karena mencakup pemrosesan Sass/SCSS dan dukungan PostCSS asli. Jalankan perintah berikut di terminal dan pastikan ada teks extended pada informasi versinya.
1 2 3

hugo version # Contoh output yang diharapkan: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js dan npm: Paket dependensi seperti Tailwind CSS dan PostCSS berjalan di Node.js. Pastikan Node.js (direkomendasikan versi LTS) sudah terinstal.
1 2

node -v npm -v

Instalasi Paket npm

Inisialisasi npm di direktori root proyek (di mana file konfigurasi Hugo hugo.toml berada) dan instal paket yang diperlukan.

1
2
3
4
5


# Menghasilkan package.json
npm init -y

# Menginstal Tailwind CSS, PostCSS, dan Autoprefixer sebagai dependensi pengembangan
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] Jika postcss-cli tidak diinstal, error dapat terjadi saat memanggil PostCSS dari dalam Hugo. Karena Hugo Pipes menggunakan postcss-cli secara internal, pastikan Anda menginstalnya.

4. Pembuatan File Konfigurasi (PostCSS & Tailwind CSS)

Setelah paket diinstal, kita akan membuat dua file konfigurasi penting yang mengontrol perilaku proyek. Tempatkan di direktori root proyek.

Membuat tailwind.config.js

Jalankan perintah berikut di terminal untuk menghasilkan file konfigurasi default.

1

npx tailwindcss init

Buka tailwind.config.js yang dihasilkan di editor Anda dan atur properti content. Ini sangat penting. Tailwind akan mengurai file pada path yang ditentukan di sini dan mengekstrak kelas yang digunakan. Sesuaikan dengan struktur proyek Hugo Anda dan spesifikasikan file tata letak (layout) dan konten secara akurat.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // Tentukan target yang akan dipindai berdasarkan struktur direktori Hugo
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // Jika Anda menggunakan tema, sertakan juga direktori temanya
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // Perluas custom color atau font di sini
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // Tambahkan plugin resmi jika diperlukan (contoh: plugin Typography)
 // require('@tailwindcss/typography'),
 ],
}

Membuat postcss.config.js

Selanjutnya, buat postcss.config.js di root proyek, yang menentukan plugin mana yang akan dieksekusi PostCSS dan dalam urutan apa.

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

Dengan konfigurasi ini, ketika Hugo memanggil PostCSS, proses Tailwind CSS akan dilakukan terlebih dahulu, dan kemudian penambahan prefiks vendor oleh Autoprefixer akan diterapkan.

5. Membangun Asset Pipeline CSS di Hugo

Setelah konfigurasi selesai, mari integrasikan Tailwind CSS ke sisi tema Hugo.

5-1. Membuat file CSS sebagai Entry Point

Buat file CSS sebagai entry point di direktori assets/css/ (buat direktorinya jika belum ada). Kita akan menyebutnya main.css.

Path file: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* Memuat gaya dasar Tailwind (reset CSS, dll.) */
@tailwind base;

/* Memuat kelas komponen */
@tailwind components;

/* Memuat kelas utilitas */
@tailwind utilities;

/* Jika Anda membutuhkan CSS kustom Anda sendiri, Anda dapat menambahkannya di sini,
 tetapi sangat disarankan untuk menggunakan extend di tailwind.config.js */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. Mengedit File Layout (head.html)

Selanjutnya, ambil file CSS di atas dari template Hugo dan tulis pipeline untuk memprosesnya menggunakan PostCSS. Umumnya, Anda mengedit sebagian template (partial template) yang mendefinisikan tag <head> (contoh: layouts/partials/head.html).

Path file: layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- Mengambil assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- Mendefinisikan opsi PostCSS -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- Pipeline optimasi aset untuk Production -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify (Kompresi) -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint (Penambahan hash untuk cache busting) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. Mencetak tag termasuk SRI (Subresource Integrity) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- Tanpa kompresi di lingkungan Development, output langsung (memprioritaskan kecepatan build) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

Penjelasan Pipeline dan Diagram Mermaid

Kami akan menggambarkan bagaimana kode template Go di atas memproses file CSS secara terstruktur melalui pipeline.

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Ruang Memori Hugo"]
B -->|resources.PostCSS| C["Proses PostCSS + Tailwind JIT"]
C --> D{"hugo.IsProduction ?"}
D -- Yes (Lingkungan Produksi) --> E["minify (Hapus spasi/baris baru)"]
E --> F["fingerprint (Hitung hash)"]
F --> G["public/css/main.[hash].css (Dengan SRI)"]
D -- No (Lingkungan Pengembangan) --> H["public/css/main.css"]

resources.Get: Mencari file yang ditentukan dalam direktori assets dan memuatnya sebagai objek sumber daya di memori.
resources.PostCSS: Merujuk ke postcss.config.js pada root proyek, dan menerapkan proses Tailwind CSS dan Autoprefixer ke source code CSS. Dalam mode pengembangan (hugo server), mode JIT diaktifkan dan secara cepat menghasilkan hanya kelas-kelas yang diperlukan saat file berubah.
minify: Selama build produksi (seperti hugo --environment production), menghapus spasi atau komentar yang tidak diperlukan untuk mengecilkan ukuran file.
fingerprint: Menghitung hash SHA berdasarkan konten file dan menambahkannya ke nama file (contoh: main.ab12cd...css). Hal ini mewujudkan “cache busting” yang memaksa browser untuk memuat ulang file baru ketika CSS diperbarui, meskipun tetap memanfaatkan caching yang kuat.
integrity: Menghasilkan atribut SRI untuk mencegah peretasan melalui CDN atau hal lainnya menggunakan nilai hash yang dihitung oleh Fingerprint.

6. Analisis Kinerja Matematis dalam Optimasi CSS

Salah satu manfaat terbesar menerapkan Tailwind CSS adalah meminimalkan ukuran file CSS yang dikirim. Mari kita analisis secara matematis menggunakan model tentang bagaimana hal ini memengaruhi kinerja web (terutama First Contentful Paint: FCP).

Model Pengurangan Ukuran File CSS

Dalam kerangka CSS tradisional (seperti Bootstrap), seluruh kode dimuat, termasuk style yang tidak digunakan, sehingga ukuran file $S_{original}$ cenderung besar (sekitar 150KB hingga 200KB). Misalkan ukuran setelah pembersihan (Purge) oleh kompiler JIT Tailwind CSS adalah $S_{purged}$, dengan menggunakan rasio pengurangan $R_{purge}$, kita dapat merumuskannya sebagai berikut:

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

Dalam proyek biasa, $R_{purge}$ dapat mencapai hampir $0.9$ (pengurangan 90%), membuat $S_{purged}$ hanya tersisa sekitar 10KB hingga 20KB.

Selain itu, ketika dilayani (served), server menggunakan kompresi Brotli atau Gzip. Jika rasio kompresi adalah $R_{compress}$ (biasanya sekitar 0.7 hingga 0.8), ukuran payload akhir $S_{final}$ yang berjalan di jaringan dihitung dengan rumus berikut:

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

Critical Rendering Path dan Keterlambatan Jaringan (Network Latency)

Waktu yang diperlukan peramban untuk menggambar konten pertama (FCP) dapat diperkirakan dari jumlah waktu pengunduhan HTML, waktu pengunduhan CSS, dan waktu perenderan (rendering).

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

Di mana:

$RTT$ : Round Trip Time (Waktu keterlambatan komunikasi bolak-balik dengan server)
$BW$ : Bandwidth jaringan

Dalam lingkungan dengan $BW$ sempit dan $RTT$ tinggi (seperti jaringan seluler), pendekatan Tailwind CSS yang dapat memangkas $S_{final}$ hingga tinggal beberapa kilobyte akan membuat nilai variabel $\frac{S_{final}}{BW}$ mendekati nol. Hal ini adalah kekuatan pendorong yang dapat menghasilkan skor mengagumkan (di Google PageSpeed Insights, dll.).

7. Menjalankan Server Pengembangan dan Memeriksa Hot Reload

Setelah semua pengaturan selesai, jalankan server pengembangan Hugo dan pastikan Tailwind CSS berfungsi dengan baik.

1

hugo server -D

Akses http://localhost:1313/ pada browser dan pastikan situs ditampilkan. Buka file konten Markdown atau template Hugo (file di bawah layouts/), dan cobalah menambahkan beberapa kelas.

1
2
3
4
5


<!-- Contoh penerapan kelas Tailwind untuk pengujian -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo is Awesome!</h1>
 <p class="mt-4 text-lg font-medium">Pastikan hot reload langsung terefleksi dalam hitungan detik.</p>
</div>

Setelah Anda menyimpan file, watcher file dari Hugo dan kompiler JIT Tailwind akan berkolaborasi secara real-time. Anda akan merasakan pengalaman dari CSS yang dibuat ulang dalam hitungan milidetik dan browser dimuat ulang secara otomatis (hot reload).

Pemecahan Masalah (Troubleshooting): Jika Style Tidak Terefleksikan

Jika perubahan tidak terefleksikan, harap periksa poin-poin berikut:

Pengaturan path content di tailwind.config.js Jika path file target yang dipindai salah, Tailwind tidak dapat mendeteksi kelas yang digunakan di dalamnya dan tidak akan menampilkannya di CSS. Terutama jika Anda menggunakan tema, periksa apakah path direktori temanya terlewat.
Error PostCSS Jika log server Hugo di terminal menunjukkan error seperti Error: failed to transform resource: PostCSS not found, kemungkinan npm install tidak dijalankan dengan benar, atau postcss-cli mungkin kurang.
Membersihkan Cache Hugo Dalam kasus yang jarang terjadi, cache Hugo dapat menyisakan file CSS lama. Hentikan server, dan jalankan lagi dengan hugo server --ignoreCache, atau hapus direktori sementara OS (seperti /tmp/hugo_cache/).

8. Build Lingkungan Produksi dan Peningkatan Lebih Lanjut

Saat mendeploy situs web Anda ke server produksi (Netlify, Vercel, GitHub Pages, Cloudflare Pages, dll.), Anda harus mengatur variabel environment dan menjalankan pipeline optimasi produksi.

1
2


# Contoh perintah build untuk produksi
NODE_ENV=production hugo --minify --environment production

Dengan menyertakan flag --environment production, blok {{ if hugo.IsProduction }} pada head.html akan dieksekusi, lalu CSS Minify dan penambahan Fingerprint akan diterapkan.

Styling Markdown menggunakan Plugin Typography

Di blog atau situs dokumentasi seperti Hugo, Anda tidak dapat menambahkan kelas secara langsung ke elemen HTML murni (<h1>, <p>, <ul>, dll.) yang dihasilkan dari Markdown. Dalam kasus ini, Typography Plugin resmi dari Tailwind akan sangat membantu.

Menginstal Plugin

1

npm install -D @tailwindcss/typography

Menambahkannya ke tailwind.config.js

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

Menerapkannya di template Cukup dengan memberikan kelas prose (serta varian warna dan ukuran jika mau) ke elemen pembungkus (container) yang memuat konten tulisan, default styling yang indah akan diterapkan.
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

Ini sepenuhnya menghilangkan keharusan menulis selector CSS kompleks secara manual (.article-content h2 { ... }), dan modularitas komponen akan dipertahankan dengan sempurna.

9. Kesimpulan: Ekosistem Frontend yang Sangat Maintenable (Dapat Dipelihara)

Selamat! Anda kini telah menyelesaikan proses membangun pipeline aset pengembangan Web sempurna yang menggabungkan engine static-site generator Hugo yang sangat cepat dengan fitur styling modern Tailwind CSS serta ekstensibilitas PostCSS.

Kelebihan utama dari arsitektur ini adalah bahwa “pengaturan cukup dilakukan satu kali saja”. Setelah pipeline dibangun, developer dapat membangun UI kompleks dengan kecepatan fantastis hanya dengan menulis kelas-kelas utilitas intuitif dalam template HTML dan Markdown, tanpa harus membuka file CSS.

Selain itu, karena ukuran CSS akhir yang dihasilkan selalu minimal, hal ini secara langsung berdampak pada peningkatan skor Core Web Vitals dan sangat menguntungkan dari perspektif SEO.

Kombinasi Hugo dan Tailwind CSS akan selalu menjadi salah satu “pilihan terbaik” untuk proyek mana pun, dari blog teknologi perorangan hingga situs berskala korporat (enterprise). Gunakan kumpulan (toolchain) alat ini yang luar biasa untuk menikmati kehidupan pengembangan web (web development) yang nyaman!

Dasar-dasar Arsitektur Perangkat Lunak: Apa itu Clean Architecture?

Sat, 12 Sep 2026 12:00:00 +0900

Dalam pengembangan perangkat lunak modern, membangun “sistem yang tangguh terhadap perubahan” adalah tantangan abadi. Perubahan persyaratan bisnis, munculnya kerangka kerja baru, perombakan UI, dan migrasi basis data. Terhadap semua perubahan ini, diperlukan arsitektur yang dapat beradaptasi secara fleksibel tanpa harus membangun ulang seluruh sistem. Sebagai salah satu jawabannya, Clean Architecture (Arsitektur Bersih) diusulkan oleh Robert C. Martin (dikenal sebagai Uncle Bob).

Pada artikel ini, kita akan menyelami esensi dari Clean Architecture melalui sejarah, tujuan, rincian dari keempat lapisannya, aturan ketergantungan, serta contoh implementasi konkret. Kami akan memberikan penjelasan teknis yang sangat mendalam dan terperinci.

1. Masalah pada Arsitektur Konvensional dan Sejarah Clean Architecture

Secara historis, arsitektur perangkat lunak telah mengalami berbagai pergeseran paradigma. Pada sistem-sistem awal, kode untuk logika bisnis, UI, dan akses data tergabung erat (biasa disebut kode spageti). Setelah itu, arsitektur 3 lapisan (lapisan presentasi, lapisan logika bisnis, lapisan akses data) menjadi populer dengan tujuan Pemisahan Perhatian (Separation of Concerns).

Namun, arsitektur 3 lapisan konvensional memiliki masalah besar. Yaitu “domain (logika bisnis) menjadi bergantung pada basis data atau kerangka kerja (framework)”.

Sebagai contoh, jika lapisan logika bisnis memanggil lapisan akses data (seperti ORM) secara langsung, perubahan skema basis data atau perubahan ORM akan merembet ke logika bisnis. Dengan kata lain, timbul kontradiksi di mana “aturan bisnis” yang paling penting dan seharusnya tidak berubah, malah bergantung pada “infrastruktur” di mana perubahan teknis paling sering terjadi.

Sebagai solusi untuk masalah ini, arsitektur-arsitektur berikut telah dirancang:

Hexagonal Architecture (Ports and Adapters) - Alistair Cockburn
Onion Architecture - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

Semua arsitektur ini memiliki tujuan yang sama. Tujuannya adalah “Pemisahan Perhatian”. Yakni, membagi perangkat lunak ke dalam lapisan-lapisan, membuat masing-masing dapat diuji secara independen, dan menciptakan keadaan di mana perangkat lunak terlepas dari agen-agen eksternal (UI, DB, kerangka kerja).

Robert C. Martin mengintegrasikan konsep-konsep dari arsitektur-arsitektur luar biasa ini dan merangkumnya menjadi sebuah aturan praktis tunggal yang ia sebut “Clean Architecture”.

2. Tujuan dan Karakteristik Clean Architecture

Sistem yang mengadopsi Clean Architecture memiliki karakteristik sebagai berikut:

Independen dari Kerangka Kerja (Independent of Frameworks): Arsitektur tidak bergantung pada keberadaan pustaka perangkat lunak yang kaya fitur. Hal ini memungkinkan kerangka kerja digunakan sebagai “alat”, dan menghilangkan kebutuhan untuk menekan sistem ke dalam batasan-batasan kerangka kerja.
Dapat Diuji (Testable): Aturan bisnis dapat diuji tanpa UI, basis data, server web, atau elemen eksternal lainnya.
Independen dari UI (Independent of UI): UI dapat diubah dengan mudah tanpa mengubah bagian sistem lainnya. Misalnya, UI Web dapat diganti dengan UI Konsol tanpa mengubah aturan bisnis.
Independen dari Basis Data (Independent of Database): Anda dapat mengganti Oracle atau SQL Server dengan Mongo, BigTable, CouchDB, dan lainnya. Aturan bisnis tidak terikat pada basis data.
Independen dari Agen Eksternal Apa Pun (Independent of any external agency): Kenyataannya, aturan bisnis tidak mengetahui apa pun tentang dunia luar.

3. 4 Lapisan (Layers) dari Clean Architecture

Clean Architecture umumnya digambarkan dengan diagram lingkaran konsentris. Semakin dekat ke pusat, perangkat lunak menjadi kebijakan tingkat yang lebih tinggi (aturan bisnis dengan tingkat abstraksi yang tinggi). Semakin ke luar, menjadi mekanisme (detail konkret).

graph TD
subgraph "Antarmuka Eksternal (Kerangka Kerja & Penggerak)"
A["Web"]
B["UI"]
C["Basis Data"]
D["API Eksternal"]
end
subgraph "Adaptor Antarmuka"
E["Pengontrol"]
F["Gerbang (Gateways)"]
G["Penyaji (Presenters)"]
end
subgraph "Aturan Bisnis Aplikasi (Kasus Penggunaan)"
H["Interaktor Kasus Penggunaan"]
end
subgraph "Aturan Bisnis Perusahaan (Entitas)"
I["Entitas"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. Entitas (Entities)

Entitas mengenkapsulasi aturan bisnis berskala perusahaan (Enterprise Business Rules). Entitas bisa berupa objek dengan metode, atau bisa juga berupa sekumpulan struktur data dan fungsi. Ini adalah aturan tingkat tinggi yang paling umum dan dapat digunakan kembali oleh beberapa aplikasi berbeda di dalam perusahaan. Bahkan jika Anda hanya membuat satu aplikasi tunggal, entitas adalah objek bisnis dari aplikasi tersebut. Entitas tidak boleh terpengaruh oleh perubahan eksternal (seperti perubahan navigasi halaman atau perubahan keamanan).

3.2. Kasus Penggunaan (Use Cases)

Lapisan kasus penggunaan berisi aturan bisnis spesifik aplikasi (Application Business Rules). Di sinilah seluruh kasus penggunaan sistem dienkapsulasi dan diimplementasikan. Kasus penggunaan mengatur aliran data dari dan ke entitas, dan menginstruksikan entitas untuk mencapai tujuan sistem. Perubahan pada lapisan ini tidak boleh memengaruhi entitas. Juga, perubahan eksternal seperti basis data, UI, atau kerangka kerja tidak memengaruhi lapisan ini. Kasus penggunaan sepenuhnya terpisah dari perhatian-perhatian tersebut.

3.3. Adaptor Antarmuka (Interface Adapters)

Lapisan adaptor antarmuka adalah sekumpulan adaptor yang mengonversi data dari format yang nyaman bagi kasus penggunaan dan entitas, ke format yang nyaman bagi agen eksternal seperti basis data atau Web. Misalnya, elemen-elemen dari arsitektur MVC (Model-View-Controller) untuk GUI di dunia Web berada di sini. Pengontrol menerima input dari pengguna dan meneruskannya ke kasus penggunaan, kemudian penyaji menerima output dari kasus penggunaan dan memformatnya untuk tampilan (UI). Peran lapisan ini juga untuk mengonversi data ke dalam format yang dapat dipahami oleh basis data (seperti SQL). Kode di sebelah dalam lapisan ini tidak boleh mengetahui apa pun tentang basis data.

3.4. Kerangka Kerja dan Penggerak (Frameworks & Drivers)

Lapisan terluar terdiri dari alat-alat seperti basis data, kerangka kerja Web, dll. Di sini biasanya Anda tidak banyak menulis kode selain “kode perekat (glue code)” untuk berkomunikasi dengan lingkaran-lingkaran di bagian dalam. Lapisan ini menyimpan semua detail. Web adalah sebuah detail. Basis data adalah sebuah detail. Kita menempatkan detail-detail ini di luar agar dampak kerusakannya dapat diminimalkan.

4. Aturan Ketergantungan (The Dependency Rule)

Ada aturan yang paling penting dan mutlak tidak boleh dilanggar agar Clean Architecture dapat terbentuk. Itu adalah “Aturan Ketergantungan (The Dependency Rule)”.

Ketergantungan kode sumber (source code) hanya boleh mengarah ke dalam, menuju kebijakan tingkat yang lebih tinggi.

Kode yang berada di lingkaran dalam tidak boleh mengetahui apa pun tentang kode yang berada di lingkaran luar. Nama-nama (fungsi, kelas, variabel, dll.) yang dideklarasikan di lingkaran luar tidak boleh disebutkan di lingkaran dalam. Demikian pula, format data yang digunakan di lingkaran luar tidak boleh digunakan di lingkaran dalam. Terutama jika format tersebut dihasilkan oleh kerangka kerja dari lingkaran luar.

graph LR
A["Kerangka Kerja & Penggerak"] -->| Bergantung pada | B["Adaptor Antarmuka"]
B -->| Bergantung pada | C["Kasus Penggunaan"]
C -->| Bergantung pada | D["Entitas"]
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#fff0f6,stroke:#333,stroke-width:2px
style D fill:#f6ffed,stroke:#333,stroke-width:2px

Dinyatakan secara matematis, jika indeks lapisan didefinisikan sebagai $L_i$, dengan $i=0$ sebagai entitas (lapisan paling dalam) dan $i=3$ sebagai kerangka kerja (lapisan paling luar), jika terdapat ketergantungan dari lapisan $L_m$ ke $L_n$, maka pertidaksamaan berikut harus selalu berlaku:

$$ m > n $$

Artinya, vektor ketergantungan $\vec{D}$ selalu mengarah ke pusat.

5. Melintasi Batas: Prinsip Pembalikan Ketergantungan (DIP)

Ketika mencoba mematuhi aturan ketergantungan, kita segera dihadapkan pada satu masalah besar: “Bagaimana jika kasus penggunaan perlu mengambil data dari basis data?”

Jika lapisan kasus penggunaan (dalam) memanggil lapisan adaptor antarmuka (implementasi Repository di luar) secara langsung, ketergantungan akan mengarah ke luar, yang melanggar aturan ketergantungan.

Yang menyelesaikan masalah ini adalah huruf “D” dalam prinsip SOLID (Dependency Inversion Principle: Prinsip Pembalikan Ketergantungan).

Definisi Prinsip Pembalikan Ketergantungan (DIP)

Modul tingkat tinggi tidak boleh bergantung pada modul tingkat rendah. Keduanya harus bergantung pada abstraksi.
Abstraksi tidak boleh bergantung pada detail. Detail harus bergantung pada abstraksi.

Untuk merealisasikannya, kita mendefinisikan antarmuka (abstraksi) di lapisan kasus penggunaan, dan lapisan luar (adaptor antarmuka) akan mengimplementasikan antarmuka tersebut. Lapisan kasus penggunaan hanya bergantung pada antarmuka yang didefinisikannya sendiri, dan tidak bergantung pada implementasi konkret di luar.

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Bergantung pada"
UserRepositoryImpl ..|> UserRepository : "Mengimplementasikan"
note for UseCaseInteractor "Lapisan Dalam (Kasus Penggunaan)"
note for UserRepository "Lapisan Dalam (Kasus Penggunaan)"
note for UserRepositoryImpl "Lapisan Luar (Adaptor Antarmuka)"

Pada gambar di atas, aliran kontrol (Control Flow) saat eksekusi adalah UseCaseInteractor $\rightarrow$ UserRepositoryImpl. Namun, ketergantungan kode sumber (Source Code Dependency) adalah UserRepositoryImpl $\rightarrow$ UserRepository (ke dalam). Dengan memanfaatkan polimorfisme, kita dapat mengarahkan ketergantungan kode sumber berlawanan dengan arah aliran kontrol. Inilah sebabnya disebut “pembalikan” ketergantungan.

6. Contoh Implementasi Konkret dengan TypeScript

Di sini, kami menunjukkan contoh implementasi sederhana dari Clean Architecture (fitur registrasi pengguna) menggunakan TypeScript.

6.1. Entitas (Entities)

Ini adalah aturan bisnis di pusat yang paling inti.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// src/domain/entities/User.ts
export class User {
 constructor(
 public readonly id: string,
 public readonly name: string,
 public readonly email: string,
 public readonly createdAt: Date
 ) {}

 // Aturan bisnis spesifik entitas (misal: cek panjang nama dll.)
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. Kasus Penggunaan (Use Cases)

Di lapisan kasus penggunaan, kita mendefinisikan struktur data input dan output (DTO) serta antarmuka repositori untuk membalikkan ketergantungan.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// Antarmuka yang didefinisikan oleh lapisan kasus penggunaan
export interface UserRepository {
 findByEmail(email: string): Promise<User | null>;
 save(user: User): Promise<void>;
}

// src/application/usecases/RegisterUser/RegisterUserDTO.ts
export interface RegisterUserInputDTO {
 name: string;
 email: string;
}

export interface RegisterUserOutputDTO {
 id: string;
 name: string;
 email: string;
 createdAt: Date;
}

// src/application/usecases/RegisterUser/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { UserRepository } from '../../repositories/UserRepository';
import { RegisterUserInputDTO, RegisterUserOutputDTO } from './RegisterUserDTO';

export class RegisterUserUseCase {
 // Bergantung pada abstraksi (antarmuka). Tidak bergantung pada hal yang konkret.
 constructor(private readonly userRepository: UserRepository) {}

 public async execute(input: RegisterUserInputDTO): Promise<RegisterUserOutputDTO> {
 const existingUser = await this.userRepository.findByEmail(input.email);
 if (existingUser) {
 throw new Error('User already exists');
 }

 const newUser = new User(
 crypto.randomUUID(),
 input.name,
 input.email,
 new Date()
 );

 if (!newUser.isValid()) {
 throw new Error('Invalid user data');
 }

 // Memanggil proses penyimpanan DB di luar, tapi ketergantungan mengarah ke dalam (antarmuka)
 await this.userRepository.save(newUser);

 return {
 id: newUser.id,
 name: newUser.name,
 email: newUser.email,
 createdAt: newUser.createdAt
 };
 }
}

6.3. Adaptor Antarmuka (Interface Adapters)

Kita membuat akses spesifik ke basis data (implementasi Repository) dan Controller yang memproses permintaan HTTP.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


// src/adapters/repositories/PostgresUserRepository.ts
import { UserRepository } from '../../application/repositories/UserRepository';
import { User } from '../../domain/entities/User';
// Asumsi klien DB yang merupakan lapisan luar (Driver)
import { DatabaseClient } from '../../infrastructure/database/DatabaseClient';

export class PostgresUserRepository implements UserRepository {
 constructor(private readonly dbClient: DatabaseClient) {}

 public async findByEmail(email: string): Promise<User | null> {
 const record = await this.dbClient.query('SELECT * FROM users WHERE email = $1', [email]);
 if (!record) return null;
 return new User(record.id, record.name, record.email, record.created_at);
 }

 public async save(user: User): Promise<void> {
 await this.dbClient.query(
 'INSERT INTO users (id, name, email, created_at) VALUES ($1, $2, $3, $4)',
 [user.id, user.name, user.email, user.createdAt]
 );
 }
}

// src/adapters/controllers/UserController.ts
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';

export class UserController {
 constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

 public async register(req: any, res: any): Promise<void> {
 try {
 const input = {
 name: req.body.name,
 email: req.body.email
 };
 const output = await this.registerUserUseCase.execute(input);
 res.status(201).json(output);
 } catch (error: any) {
 res.status(400).json({ message: error.message });
 }
 }
}

6.4. Komponen Utama (Injeksi Ketergantungan: DI)

Saat aplikasi dijalankan, kita membangun (merangkai) seluruh dependensi. Ini disebut Composition Root.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/infrastructure/web/server.ts
import express from 'express';
import { DatabaseClient } from '../database/DatabaseClient';
import { PostgresUserRepository } from '../../adapters/repositories/PostgresUserRepository';
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';
import { UserController } from '../../adapters/controllers/UserController';

const app = express();
app.use(express.json());

// 1. Inisialisasi penggerak (driver)
const dbClient = new DatabaseClient(/* Info koneksi */);

// 2. Inisialisasi adaptor (membuat instance kelas konkret)
const userRepository = new PostgresUserRepository(dbClient);

// 3. Inisialisasi kasus penggunaan (menyuntikkan kelas konkret ke antarmuka = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. Inisialisasi pengontrol
const userController = new UserController(registerUserUseCase);

// Routing
app.post('/users', (req, res) => userController.register(req, res));

app.listen(3000, () => {
 console.log('Server is running on port 3000');
});

Dengan cara ini, “skrip startup” yang berada paling luar mengambil alih detail-detail kotor (pembuatan instance kelas konkret) dan hanya mewariskan antarmuka bersih ke lapisan dalam, sehingga logika bisnis sepenuhnya terisolasi dari dunia luar.

7. Analisis Matematis tentang Coupling (Kopling) dan Cohesion (Kohesi)

Dalam rekayasa perangkat lunak, Coupling (Tingkat Keterkaitan) dan Cohesion (Tingkat Kepaduan) adalah metrik untuk mengevaluasi kualitas arsitektur.

Coupling $C$ merepresentasikan kekuatan ketergantungan antar modul. Jika Modul $A$ bergantung pada Modul $B$, dan jumlah total ketergantungan dalam sistem adalah $N_{dep}$, serta jumlah modul adalah $N_{mod}$, salah satu indikator kompleksitas dapat dinyatakan sebagai berikut:

$$ Complexity \propto \frac{N_{dep}}{N_{mod}} $$

Dalam Clean Architecture, dengan menerapkan DIP, kita mengarahkan panah ketergantungan fisik menuju abstraksi. Frekuensi perubahan (Instability: $I$) dari abstraksi (antarmuka) dirancang sangat rendah.

Instability $I$ dihitung menggunakan rumus berikut (didefinisikan oleh Robert C. Martin):

$C_e$ (Efferent Coupling): Kopling keluar (jumlah dependensi dari modul ini ke modul lain)
$C_a$ (Afferent Coupling): Kopling ke dalam (jumlah dependensi dari modul lain ke modul ini)

$$ I = \frac{C_e}{C_e + C_a} $$

Jika $I = 0$, komponen tersebut sepenuhnya stabil (tidak bergantung pada siapa pun, dan diandalkan oleh yang lain).
Jika $I = 1$, komponen tersebut sepenuhnya tidak stabil (tidak diandalkan oleh yang lain, dan bergantung pada yang lain).

Dalam “Lapisan Entitas” pada Clean Architecture, karena $C_e = 0$ (tidak bergantung pada bagian luar), maka $I = 0$. Artinya, ini adalah lapisan yang paling stabil. Sebaliknya, “Lapisan UI” dan “Lapisan DB” memiliki $C_a \approx 0$ dan $C_e > 0$, sehingga $I \approx 1$, menjadikannya lapisan yang mudah diubah (lapisan tidak stabil).

Prinsip penting dari arsitektur yaitu SDP (Stable Dependencies Principle: Prinsip Ketergantungan Stabil) menetapkan bahwa “Ketergantungan harus mengarah pada komponen yang lebih stabil (komponen dengan nilai $I$ yang lebih kecil)”. Lingkaran konsentris dari Clean Architecture adalah visualisasi dari SDP ini, dirancang sedemikian rupa agar ketergantungan mengarah dari luar ($I=1$) ke dalam ($I=0$).

8. Strategi Pengujian dan Clean Architecture

Salah satu keuntungan terbesar dari Clean Architecture adalah kemudahan pengujian. Karena lapisan-lapisannya terpisah, Anda dapat menulis tes untuk masing-masing lapisan secara independen.

8.1. Pengujian Entitas (Unit Test)

Karena ini adalah logika murni tanpa ada ketergantungan eksternal sama sekali, DB maupun Mock tidak diperlukan. Ini adalah tes yang paling andal dan dapat dieksekusi paling cepat.

8.2. Pengujian Kasus Penggunaan (Unit Test with Mocks)

Karena semua ketergantungan eksternal seperti repositori didefinisikan sebagai antarmuka, saat pengujian, kita hanya perlu menyuntikkan (DI) mock untuk pengujian atau implementasi dalam memori (Fake). Kita tidak perlu menjalankan basis data sungguhan. Hal ini memungkinkan percabangan yang kompleks dan penanganan pengecualian pada logika bisnis untuk diuji dengan cepat.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// Contoh pengujian kasus penggunaan (Berasumsi menggunakan Jest)
test('Akan terjadi error jika mencoba mendaftar dengan email yang sudah ada', async () => {
 // Membuat repositori Fake
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // Mengembalikan pengguna yang sudah ada
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // Eksekusi kasus penggunaan dan asersi error
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. Pengujian Adaptor (Integration Test)

Kelas implementasi repositori benar-benar terhubung ke basis data untuk menguji apakah kueri SQL-nya sudah benar. Pengujian pengontrol akan menguji penerimaan permintaan HTTP dan pengembalian bagian JSON-nya. Di sini, validasi rinci atas logika bisnis tidak dilakukan, tetapi hanya memastikan bahwa “konversi” dan “komunikasi” sudah benar.

9. Kekurangan Clean Architecture dan Kapan Harus Mengadopsinya

Meskipun terlihat seperti solusi untuk segala hal, Clean Architecture bukanlah peluru perak. Terdapat kekurangan (trade-off) sebagai berikut:

Peningkatan biaya pembelajaran awal dan biaya pengembangan: Jumlah file dan antarmuka (abstraksi) akan meningkat secara signifikan. Akan ada banyak “kode boilerplate (kode kerangka standar)” seperti pemindahan DTO.
Berlebihan untuk proyek skala kecil: Untuk prototipe yang dibuat dalam beberapa hari atau perkakas sekali pakai yang hampir tidak pernah diubah, mengadopsi arsitektur ini sering kali menjadi biaya yang sia-sia. Arsitektur ini juga tidak cocok untuk API sederhana yang hanya melakukan operasi CRUD.

Kapan harus mengadopsinya:

Produk yang diperkirakan akan dikelola dan dioperasikan untuk jangka waktu yang panjang (lebih dari beberapa tahun).
Sistem dengan aturan bisnis yang kompleks dan sering mengalami perubahan spesifikasi.
Jika Anda ingin memajukan pembagian kerja dalam tim pengembangan skala besar (front-end, back-end, infrastruktur, dll.).
Jika Anda ingin memodelkan area bisnis yang kompleks dengan mengombinasikannya dengan Domain-Driven Design (DDD).

10. Kesimpulan

Clean Architecture adalah sebuah filosofi desain yang bertujuan untuk melindungi inti dari sistem, yaitu “aturan bisnis”, dari “detail-detail” seperti UI, basis data, dan kerangka kerja.

Inti dari hal ini adalah Aturan Ketergantungan dan Prinsip Pembalikan Ketergantungan (DIP). Dengan menerapkan ini dengan benar, perangkat lunak menjadi fleksibel terhadap perubahan, mudah diuji, dan mampu mempertahankan nilainya untuk jangka waktu yang lama.

Yang terpenting bukanlah meniru struktur direktori Clean Architecture secara membabi buta, melainkan memahami esensi dari “mengapa dibagi seperti itu” dan “ke mana panah ketergantungan mengarah”, serta menerapkannya dengan tepat sesuai dengan skala dan kompleksitas proyek Anda sendiri.

Referensi: “Clean Architecture: A Craftsman’s Guide to Software Structure and Design” oleh Robert C. Martin

Poin-poin Desain CSS untuk Menerapkan Mode Gelap di Blog

Sat, 12 Sep 2026 12:00:00 +0900

Dalam pengembangan web modern, dukungan mode gelap (Dark Mode) telah berubah dari sekadar “fitur tambahan yang bagus (Nice to have)” menjadi “persyaratan wajib (Must have)” untuk meningkatkan pengalaman pengguna (UX). Khususnya untuk media yang membutuhkan waktu baca yang lama seperti blog dan situs dokumentasi, dukungan mode gelap sangatlah penting karena dapat mengurangi kelelahan mata pengguna dan menghemat konsumsi baterai perangkat.

Pada artikel ini, saya akan membahas secara mendalam dari sudut pandang seorang frontend engineer mengenai tantangan teknis yang tidak dapat dihindari saat mengimplementasikan mode gelap di blog, beserta poin-poin desain CSS dengan maintainability yang tinggi. Saya akan mencakup semuanya tentang implementasi mode gelap, mulai dari penggunaan CSS Custom Properties (Variabel CSS), kontrol JavaScript tingkat lanjut dan integrasi SSR untuk mencegah FOUC (Flash of Unstyled Content), desain warna (RGB, HSL, dan OKLCH terbaru) untuk memastikan aksesibilitas (WCAG 2.1 AAA), hingga contoh kode praktis menggunakan Tailwind CSS.

1. Dasar-dasar Desain Tema dengan CSS Custom Properties (Variabel CSS)

Dalam mengimplementasikan mode gelap, pendekatan yang paling standar dan kuat saat ini adalah memanfaatkan CSS Custom Properties (Variabel CSS). Berbeda dengan variabel preprocessor CSS seperti Sass ($color) yang diselesaikan secara statis saat kompilasi, variabel CSS dapat diselesaikan dan ditimpa secara dinamis pada runtime browser. Hal ini memungkinkan kita untuk mengubah warna keseluruhan halaman secara instan hanya dengan beralih kelas melalui JavaScript.

1.1 Mendefinisikan Tema Warna Dasar

Pertama, kita mendefinisikan palet warna untuk mode terang (default) menggunakan pseudo-class :root. Kemudian, pola desain utamanya adalah menimpa variabel-variabel tersebut ketika atribut seperti [data-theme='dark'] (atau kelas .dark) diterapkan.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* Definisi variabel mode terang (default) */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* Menimpa variabel saat mode gelap */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* Penerapan aktual */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

Dengan memisahkan secara sempurna antara spesifikasi tata letak atau tipografi dan spesifikasi warna (tema) seperti ini, kemudahan pemeliharaan (maintainability) CSS akan meningkat drastis.

1.2 Memanfaatkan @media (prefers-color-scheme: dark)

Jika mode gelap telah diatur di tingkat OS, maka secara otomatis menerapkan tema gelap sejak kunjungan pertama situs web sangat dianjurkan dari sudut pandang UX. Hal ini dapat dicapai melalui media query @media (prefers-color-scheme: dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* Fallback ketika pengaturan sistem OS adalah mode gelap */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

Dengan penulisan ini, variabel akan ditimpa untuk menghormati pengaturan mode gelap pada OS, kecuali jika pengguna secara eksplisit memilih mode terang (data-theme='light').

2. Memahami Ruang Warna dan Aksesibilitas (WCAG 2.1 AAA)

Dalam desain warna mode gelap, sekadar “membuat latar belakang hitam dan teks putih” tidaklah cukup. Jika kontras terlalu tinggi, dapat menyebabkan halation dan justru sulit dibaca; sedangkan jika kontras terlalu rendah, visibilitasnya akan berkurang. Web Content Accessibility Guidelines (WCAG) mendefinisikan rasio kontras secara ketat untuk memastikan visibilitas.

2.1 Rumus Perhitungan Rasio Kontras WCAG

Rasio Kontras (Contrast Ratio) $CR$ dalam WCAG didefinisikan sebagai berikut menggunakan Relative Luminance (Luminansi Relatif) dari warna latar belakang dan warna latar depan.

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

Di sini, $L_{lighter}$ adalah luminansi relatif dari warna yang lebih terang, dan $L_{darker}$ adalah luminansi relatif dari warna yang lebih gelap (rentang nilainya dari 0.0 hingga 1.0). Untuk mencapai WCAG 2.1 level AAA, rasio kontras yang diperlukan adalah minimal 7:1 untuk teks biasa, dan minimal 4.5:1 untuk teks berukuran besar.

Luminansi relatif $L$ dihitung dari nilai RGB pada ruang warna sRGB dengan rumus yang rumit berikut ini:

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

Setiap komponen ($R, G, B$) menggunakan nilai normalisasi yang didapat dengan membagi nilai 8-bit asli ($R_{sRGB}$) dengan 255, dan melakukan transformasi berikut untuk menyelesaikan koreksi gamma:

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{jika } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{lainnya} \end{cases} $$

Melakukan perhitungan ini secara manual sangatlah sulit, namun dengan memanfaatkan alat desain warna, kita dapat secara mekanis memilih warna yang memenuhi rasio kontras 7:1 ($CR \ge 7.0$).

2.2 HSL vs RGB vs OKLCH

Saat membuat palet warna, RGB dan HSL dulunya merupakan arus utama. Namun, keduanya memiliki kelemahan yang signifikan dalam hal “keseragaman persepsi” (perceptual uniformity).

RGB: Berdasarkan tiga warna primer cahaya mekanis, sehingga menyulitkan manusia untuk secara intuitif melakukan penyesuaian seperti “buat lebih terang” atau “buat lebih gelap”.
HSL: Menggunakan warna (Hue), saturasi (Saturation), dan kecerahan (Lightness). Namun, “Lightness (L)” dalam HSL tidak sesuai dengan persepsi kecerahan pada mata manusia. Misalnya, warna kuning murni dan biru murni dengan Lightness 50% di HSL secara numerik memiliki kecerahan yang sama, tetapi di mata manusia warna kuning terlihat jauh lebih terang.
OKLCH: Ruang warna terbaru yang diperkenalkan pada CSS Color Module Level 4. Terdiri dari Lightness (kecerahan perseptual), Chroma (saturasi warna), dan Hue (corak warna), serta sepenuhnya selaras dengan karakteristik visual manusia (keseragaman perseptual).

Dengan menggunakan OKLCH, meskipun kita mengubah corak warna (Hue), kecerahan perseptual (Lightness) akan tetap terjaga. Hal ini membuat pembuatan palet warna untuk mode gelap menjadi sangat dapat diprediksi dan aman.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* Contoh definisi variabel CSS menggunakan OKLCH */
:root {
 /* Kecerahan dasar mode terang tinggi, dengan saturasi yang direndahkan */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* Pada mode gelap, cukup balikkan kecerahan untuk menjaga kontras persepsi */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* Dibuat sedikit lebih terang untuk visibilitas mode gelap */
}

Dengan mengadopsi OKLCH seperti ini, kita dapat membangun logika sederhana untuk memastikan rasio kontras yang konsisten (standar WCAG AAA) pada beberapa tema.

3. Mencegah FOUC (Flash of Unstyled Content) dan SSR Hydration

Masalah yang paling merepotkan pengembang saat mendukung mode gelap adalah masalah kedipan layar yang disebut FOUC (Flash of Unstyled Content).

3.1 Jebakan Peralihan Tema dengan Client-side JS

Pada SPA seperti React atau Vue (atau situs statis yang menggunakan SSG), sangat umum untuk menyimpan pengaturan pengguna di localStorage, kemudian membacanya dan mengganti tema menggunakan JavaScript. Namun, jika ini dilakukan di dalam React useEffect misalnya, masalah berikut akan muncul:

Browser merender HTML/CSS mode terang.
Bundle JS dimuat dan dieksekusi.
Membaca pengaturan dark dari localStorage.
Kelas dark ditambahkan ke HTML, dan layar tiba-tiba menjadi gelap (berkedip).

Praktik terbaik untuk sepenuhnya mencegah FOUC dan kesalahan hidrasi (hydration error) adalah dengan menyimpan pengaturan tema pengguna di document.cookie, kemudian merender HTML yang sudah disertai kelas tema secara tepat pada tahap Server-side Rendering (SSR).

Diagram urutan berikut ini menunjukkan alur ideal inisialisasi tema menggunakan Cookie.

sequenceDiagram
participant User as "Pengguna"
participant Browser as "Browser OS"
participant Server as "Server SSR"
participant DOM as "Klien DOM"
User->>Browser: "Minta Halaman"
Browser->>Server: "Permintaan GET dengan Cookie (theme=dark)"
Server-->>Browser: "Kembalikan HTML dengan <html data-theme='dark'>"
Browser->>DOM: "Render HTML Awal (Tanpa FOUC)"
DOM->>DOM: "Eksekusi Skrip Hidrasi"
alt "Cookie tidak ada (Kunjungan Pertama)"
DOM->>Browser: "Periksa OS prefers-color-scheme"
Browser-->>DOM: "Hasil matchMedia (misalnya dark)"
DOM->>DOM: "Atur data-theme='dark' melalui skrip inline pemblokiran"
end

Untuk blog yang hanya menggunakan SSG (Static Site Generation) dan SSR tidak dimungkinkan (misalnya eksport statis pada Hugo, Gatsby, atau Astro), teknik menyisipkan skrip JavaScript inline yang bersifat memblokir (blocking) di dalam tag <head> menjadi hal yang wajib dilakukan untuk menambahkan kelas tepat sebelum DOM dirender.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- Tempatkan di bagian paling akhir dalam <head> -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

Skrip kecil ini akan memblokir rendering browser dan langsung dieksekusi, sehingga atribut data-theme sudah tersusun pada saat layar dirender, mencegah sepenuhnya kedipan layar (FOUC).

4. Pendekatan Implementasi pada Tailwind CSS dan Raw SCSS/CSS

Saat mengintegrasikan mode gelap ke dalam proyek nyata, kita perlu memahami pendekatan untuk setiap tools yang digunakan.

4.1 Mode Gelap pada Tailwind CSS

Tailwind CSS menyediakan varian dark: secara default, membuat implementasi mode gelap menjadi sangat mudah. Atur properti darkMode dalam file konfigurasi (tailwind.config.js).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (Bergantung pada pengaturan OS) atau 'class' (Bisa dialihkan secara manual)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* Memperluas palet warna Tailwind dengan variabel CSS */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

Di sisi HTML, kita hanya perlu menambahkan kelas seperti berikut.

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hello World</h1>
 <p class="mt-2">Tailwind makes dark mode incredibly easy.</p>
</div>

Akan tetapi, menulis dark:bg-xxx pada setiap elemen dapat menyebabkan komponen membengkak. Pada aplikasi atau blog berskala besar, disarankan menggunakan pendekatan hibrida (desain warna semantik), di mana basisnya menggunakan variabel CSS, dan Tailwind akan merujuk ke variabel CSS tersebut.

Berikut adalah diagram kelas yang menunjukkan pewarisan variabel CSS dan lapisan penerapannya.

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "Menerapkan Kelas Utilitas"

4.2 Implementasi pada Raw SCSS/CSS (Memanfaatkan Mixin)

Dalam proyek yang tidak menggunakan Tailwind dan menulis SCSS sendiri, gunakan @mixin untuk merangkum gaya (style) pada mode gelap.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* Definisi SCSS Mixin */
@mixin dark-mode {
 /* Mendukung atribut [data-theme='dark'] dan pengaturan OS */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* Contoh Penggunaan */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

Metode ini memang intuitif, tetapi rentan menyebabkan pembengkakan ukuran file CSS hasil kompilasi (karena media query disalin ke setiap selector). Karenanya, tren saat ini bergeser ke desain berbasis variabel CSS (Custom Properties).

5. Optimalisasi Gambar (Image) dan SVG pada Mode Gelap

Meskipun desain warna pada teks atau latar belakang sudah selesai, jika gambar atau ikon (SVG) yang ditempatkan sebagai konten tetap pada pengaturan mode terang, tampilannya akan terlihat sangat menyilaukan dan menonjol ketika dilihat dalam mode gelap. Oleh karena itu, optimalisasi bagian ini sangatlah penting.

5.1 Filter CSS untuk Menurunkan Kecerahan Gambar

Gambar bitmap seperti foto, jika ditampilkan apa adanya saat mode gelap, terkadang terlalu menyilaukan. Dengan menggunakan properti filter pada CSS untuk sedikit menurunkan kecerahan (brightness) dan menaikkan kontras (contrast) gambar, kita dapat membaurkan gambar secara alami ke dalam UI mode gelap.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* Turunkan kecerahan, tingkatkan kontras sedikit */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* Kembalikan ke kecerahan asli saat hover (ketika pengguna ingin melihat detailnya) */
 filter: brightness(1) contrast(1);
}

5.2 Menyajikan Gambar Berbeda dengan Tag `<picture>`

Gambar logo atau ilustrasi penjelasan (seperti JPEG dengan latar belakang putih pekat) tidak bisa hanya diandalkan dengan filter. Dalam kasus seperti ini, solusi tepat adalah menyajikan file gambar yang berbeda untuk mode gelap menggunakan elemen HTML <picture> beserta media query.

1
2
3
4
5
6


<picture>
 <!-- Tampilkan ini untuk pengguna dengan pengaturan OS mode gelap -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- Default (Mode terang) -->
 <img src="/img/logo-light.png" alt="Logo situs">
</picture>

Catatan: Metode ini hanya bergantung pada pengaturan OS, sehingga tidak tersinkronisasi jika perubahan mode dilakukan manual (seperti lewat localStorage). Jika fitur peralihan manual diterapkan, Anda perlu mengubah src gambar secara dinamis dengan JS atau beralih kelas CSS dengan display: none.

5.3 Dukungan `currentColor` untuk Ikon SVG

Untuk ikon SVG inline, cara paling cerdas adalah menautkan warna pengisian dengan warna teks dari elemen induknya. Cukup tentukan currentColor pada atribut fill atau stroke SVG.

1
2
3
4


<!-- Nilai dari properti color CSS (seperti var(--text-primary)) akan diterapkan secara otomatis -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

Dengan cara ini, saat beralih ke mode gelap dan warna font pada elemen induk berubah ke nuansa putih, ikon SVG juga akan otomatis berubah mengikuti warna putih tersebut.

6. Kesimpulan: Menuju Desain Mode Gelap yang Berkelanjutan

Untuk mengimplementasikan mode gelap berkualitas tinggi pada blog atau aplikasi web, desain CSS yang mencakup poin-poin berikut ini sangatlah esensial.

Memanfaatkan CSS Custom Properties: Hindari hardcode pengaturan warna, melainkan abstraksikan ke dalam penamaan variabel semantik (misal: --bg-primary).
Mengadopsi Ruang Warna OKLCH: Rancang secara logis pada ruang warna yang seragam secara perseptual untuk mencapai rasio kontras dengan aksesibilitas tinggi (minimal 7:1) yang memenuhi WCAG 2.1 AAA.
Mencegah FOUC Sepenuhnya: Hilangkan kedipan layar sepenuhnya saat pertama dimuat menggunakan integrasi SSR dan Cookie, atau melalui skrip inline pemblokiran di dalam <head>.
Optimalisasi Media dan Aset: Manfaatkan filter: brightness(), currentColor, dan tag <picture> agar elemen selain teks juga selaras dengan tema gelap.

Bukan sekadar “membalik warna”, melainkan penerapan dengan detail mendalam inilah yang menjadi syarat sebuah blog modern. Blog yang dicintai pengguna untuk waktu yang lama dan mampu menyuguhkan pengalaman membaca (reading experience) yang hebat serta tidak membuat mata cepat lelah. Bagi para pengembang yang ingin memperkenalkan mode gelap ke depannya, silakan jadikan pola desain dari artikel ini sebagai referensi yang andal.