BUMDes Design System & UI Guidelines

Dokumen ini adalah panduan resmi (Single Source of Truth) untuk pengembangan antarmuka pengguna (UI/UX) pada ekosistem aplikasi BUMDes. Tujuannya adalah memastikan konsistensi visual, aksesibilitas, dan rasa premium di seluruh halaman, terutama setelah migrasi ke tema OLED Black + Glassmorphism.

---

1. Filosofi Desain (The "Vibe")#

• Modern & Premium: Meninggalkan kesan "situs web instansi pemerintahan tradisional". Antarmuka harus terasa seperti aplikasi super-app finansial (Fintech) kelas atas.
• Mobile-First & Compact: Komponen harus dirancang seringkas mungkin di layar HP. Kurangi teks yang tidak perlu (contoh: deskripsi panjang) dan utamakan ikonografi visual.
• OLED Black (True Dark): Latar belakang utama pada mode gelap menggunakan #000000 (hitam pekat), bukan abu-abu gelap, untuk efisiensi daya layar OLED dan kontras yang dramatis.

---

2. Palet Warna (Color Palette)#

Mode Terang (Light Mode)

• Background Utama: bg-white atau bg-slate-50 untuk membedakan antar-seksi (sectioning).
• Teks Utama: text-slate-900
• Teks Pendukung: text-slate-600
• Border: border-slate-200

Mode Gelap (OLED Dark Mode)

• Background Utama: dark:bg-black (Sangat penting: Jangan gunakan bg-gray-900).
• Teks Utama: dark:text-white
• Teks Pendukung: dark:text-slate-400
• Border Lembut: dark:border-white/10 atau dark:border-white/5

Aksen (Accent Colors)

• Warna Identitas (Primary): Emerald (text-emerald-500 / bg-emerald-500). Sering dipadukan dengan gradasi untuk memberikan efek glowing.
• Warna Dukungan:
  • Blue (Portal/Admin)
  • Amber (Toko/E-commerce)
  • Purple (Transparansi/Data)

---

3. Komponen Inti (Core Components)#

A. Glassmorphism Card (Kartu Kaca Transparan)

Semua wadah elemen (kartu layanan, metrik, dll) wajib menggunakan gaya kaca jika berada di atas latar belakang kompleks atau untuk memberikan kedalaman (depth).

Resep Class Tailwind:

jsx
className="bg-white/80 dark:bg-white/5 backdrop-blur-xl border border-slate-200 dark:border-white/10 shadow-sm dark:shadow-inner"

Catatan: Gunakan dark:bg-white/5 (bukan hitam transparan) agar kartu sedikit lebih terang dan "mengambang" di atas latar belakang OLED Black.

B. Dynamic Glassmorphism Hover Glow

Kartu yang bisa diklik (Link/Tombol) atau menyajikan informasi kunci wajib memberikan respons visual saat disorot/disentuh. Standar terbaru menggunakan warna yang dinamis mengikuti "Identity Color" modul/kartu tersebut (misal: Amber untuk Gudang, Rose untuk Mortalitas, Emerald untuk Pemasukan).

Resep Class Tailwind untuk Pembungkus (Container):

jsx
className="group relative overflow-hidden bg-white/80 dark:bg-[color]-500/10 backdrop-blur-xl border border-transparent hover:border-[color]-300 dark:hover:border-[color]-500/50 hover:shadow-xl dark:hover:shadow-2xl transition-all duration-500 hover:-translate-y-0.5 cursor-pointer"

(Ganti [color] dengan emerald, amber, rose, indigo, atau blue)

C. Glowing Gradient (Efek Sorotan Lampu Tersembunyi)

Lapisan internal pada kartu untuk memberikan efek "ilusi lampu pijar" yang muncul perlahan (fade in) dari ujung sudut ruangan di dalam mode OLED Dark Mode maupun Light Mode.

Resep Background Glow Layer (Disisipkan di dalam Container):

jsx
<div className="absolute inset-0 bg-gradient-to-br from-[color]-500/10 dark:from-[color]-500/20 to-transparent opacity-0 group-hover:opacity-100 transition-opacity duration-500 pointer-events-none" />
<div className="relative z-10">
   {/* Konten Kartu */}
</div>

---

4. Tata Letak (Layouting & Grids)#

Asymmetrical Bento Grid

Untuk bagian dashboard atau daftar fitur (seperti Ekosistem), hindari penggunaan list vertikal biasa di versi mobile. Gunakan tata letak kotak bento asimetris.

Pola Mobile (HP): Gunakan grid-cols-2.

• Fitur Utama/Hero: col-span-2 (Lebar penuh, horizontal).
• Fitur Tambahan: col-span-1 (Berdampingan, berbentuk kubus aspect-square).

Aturan Konten Mobile: Gunakan utility class hidden sm:block untuk menyembunyikan elemen teks (seperti deskripsi atau subjudul) yang tidak absolut penting di layar < 640px. Biarkan ikon dan judul yang berbicara.

Galeri Mockup Referensi

Berikut adalah beberapa eksplorasi tata letak mobile yang disetujui:

Asymmetrical Bento Grid (Telah Diterapkan) Mockup Bento

Alternatif: Horizontal Carousel Mockup Carousel

Alternatif: Grid 2x2 Klasik Mockup 2x2 Grid

---

5. Tipografi#

• Heading: Selalu gunakan font-weight font-bold dengan tracking (spasi huruf) ketat tracking-tight pada judul besar (H1/H2).
• Keterbacaan (Readability): Untuk paragraf (p), gunakan leading-relaxed agar spasi antar baris nyaman dibaca.

---

Dibuat oleh AI Assistant untuk standarisasi proyek BUMDes - 2026.

C. Dashboard Metrics & KPI Cards (Sub Unit)

Untuk halaman operasional sub-unit (seperti Dashboard Ayam Petelur), kartu metrik (Suhu, Panen Telur, dll) yang tergabung dalam grid harus menghilangkan pembungkus (wrapper) panel solid besar, dan beralih ke format Bento Grid independen yang lebih luas.

Aturan Khusus Kartu Indikator:

• Glassmorphism Glow: Gunakan struktur hover glow (seperti kartu Ekosistem) pada masing-masing kartu metrik.
• Responsivitas: Di mode mobile, gunakan grid-cols-2 untuk menampilkan metrik bersebelahan. Di mode desktop, gunakan lg:grid-cols-3 agar kartu tidak meregang (stretch) secara berlebihan.
• Warna Dasar: Gunakan bg-[color]-50 dengan dark:bg-[color]-500/10 sebagai fondasi kartu (tanpa border statis di mode terang).
• Interaksi: Tambahkan efek gradient hover yang sesuai identitas metrik (misal: Emerald untuk Panen Telur, Sky untuk Suhu, Rose untuk Kematian).

Contoh Kelas:

jsx
className="group relative overflow-hidden space-y-1 p-4 bg-sky-50 dark:bg-sky-500/10 border border-transparent rounded-[24px] hover:border-sky-300 dark:hover:border-sky-500/50 hover:shadow-xl hover:-translate-y-1 transition-all duration-500 cursor-pointer flex flex-col justify-between"

D. Integrasi Komponen Pihak Ketiga (Third-Party UI)

Khusus untuk komponen eksternal (seperti Recharts):

1. Hindari hooks generik: Jangan gunakan useTheme bawaan next-themes. Sistem kita memakai Context mandiri. Selalu panggil const { theme } = usePublicTheme() dari @/contexts/ThemeContext.
2. Re-rendering Paksa (Key Forcing): Jika warna komponen SVG (seperti Tooltip atau CartesianGrid) tidak mau beradaptasi otomatis saat beralih ke Mode Gelap, berikan key={isDark ? "dark" : "light"} pada bungkus luarnya agar Next.js membongkar pasang (remount) kanvas grafik tersebut sepenuhnya.
3. Pewarnaan Eksplisit: Berikan definisi labelStyle dan itemStyle secara rinci, jangan bergantung pada abu-abu bawaan pihak ketiga yang rentan lenyap di latar belakang pekat OLED.

---

4. Backend & Pengolahan Metrik (Analitik)#

• Konsolidasi Hierarkis: Saat mengukur performa suatu unit bisnis yang berperan sebagai "Induk" (Holding/Unit Utama), selalu gunakan getIncomeStatement(unit.id, true) agar data dari seluruh sub-unit di bawahnya terkumpul (roll-up). Jika disetel false, unit Induk akan tampak bernilai 0 karena transaksinya menumpuk di akar (cabang), bukan di dahan (induk).

6. Desain Inklusif (Grassroots / Ekonomi Kerakyatan)#

Sistem juga mengakomodasi antarmuka untuk pengguna akar rumput (seperti petani dan pedagang kecil) yang mungkin tidak terbiasa dengan aplikasi yang rumit.

A. Filosofi Visual Khusus Inklusif

• Tombol Raksasa (Asymmetrical Bento): Gunakan tombol AkarRumputBentoButton yang memakan satu atau dua kolom secara penuh (col-span-2). Tidak ada formulir teks konvensional yang menyulitkan layar sentuh kecil.
• Warna Aman & Mengayomi: Gunakan Emerald (Pertanian/Panen) dan Amber (Kebutuhan/Toko). Warna yang digunakan harus ramah dan familiar.
• Kontras Tinggi: Hindari opacity terlalu tinggi pada lapisan kaca (glassmorphism) jika menyulitkan pembacaan.

B. Input Berbasis Suara (Voice-to-Action)

Selalu pertimbangkan opsi input suara untuk menggantikan ketikan panjang. Tombol rekaman (seperti komponen "Bicara Saja") harus mengambang (fixed) di bagian bawah layar (bottom-28, menghindari bottom navbar utama) agar mudah diakses dengan jempol.

C. Numpad Kustom (Bottom Number Pad)

Gunakan komponen BottomNumberPad untuk entri angka berat atau nominal uang, demi menghindari penggunaan keyboard sistem operasi bawaan yang kecil dan tidak ramah lansia. Papan ketik ini menyediakan tombol 000 untuk mempermudah nominal Rupiah.