# UI/UX dan Design System

## Arah visual
Antarmuka ringan bergaya aplikasi SaaS: bersih, mudah dipindai, konsisten, responsif, dan berfokus pada tugas. Terapkan satu sistem desain lintas halaman dan peran.

## Arah visual yang diputuskan
- Warna utama: biru. Palet terang, warna status, permukaan, fokus, dan warna netral didefinisikan dalam token `:root` pada `resources/css/global.css`; aturan komponen memakai token, bukan nilai warna langsung.
- Font: Plus Jakarta Sans. Keluarga font, fallback, font monospace, dan seluruh ukuran tipografi dikelola melalui token global; font utama dimuat secara lokal agar tampilan konsisten dan tidak bergantung pada layanan font eksternal.
- Kepadatan: layout desktop ringkas dengan padding dan margin minimal yang tetap nyaman dibaca, khususnya tabel dan formulir akademik. Gunakan skala spacing global.
- Pada layar kecil, sesuaikan ruang dan target sentuh melalui token/breakpoint global; keputusan desktop ringkas tidak boleh membuat tampilan mobile sesak.

## Navigasi sidebar
- Sidebar desktop memiliki dua mode global: **lebar** (ikon dan label) dan **ikon saja** (ringkas).
- Sediakan tombol trigger yang jelas untuk berpindah mode; tombol memiliki label aksesibel, tooltip saat sidebar ikon saja, dan state fokus keyboard.
- Perubahan mode tidak boleh menutupi konten atau menyebabkan layout bergeser berat; gunakan transisi sederhana tanpa blur.
- Item navigasi aktif memiliki indikator visual yang jelas (`.is-active::before` bar aksen biru), dan grup menu mengikuti izin/peran pengguna.
- Struktur menu dikelompokkan secara hierarkis ke dalam 5 bagian semantik:
  1. **UTAMA**: Dashboard, Portal Mahasiswa, Portal Dosen.
  2. **DATA MASTER**: Menu grup Akademik (Unit, Program Studi, Mata Kuliah, Kurikulum, Penawaran Kelas, Ruang, Kalender Akademik), Mahasiswa, dan Dosen.
  3. **PERKULIAHAN**: Presensi, Nilai Perkuliahan, Tugas Akhir, Yudisium, dan Wisuda.
  4. **LAYANAN & PMB**: PMB, Kemahasiswaan, Keuangan Mahasiswa, dan Laporan Operasional.
  5. **INTEGRASI & SISTEM**: Menu grup Integrasi (Neo Feeder) dan Pengaturan (Pengguna, Peran & Izin, Aturan Akademik, Skala Nilai, Periode Akademik, Profil Kampus, Log Audit).
- Ikon dropdown (`.nav-chevron`) diletakkan langsung berdampingan dengan label menu teks (`margin-left: 0.4rem`) agar tetap intim dan mudah dikenali, bukan terdorong ke tepi kanan layar.
- Pada mode ringkas (ikon saja), scrollbar menu vertikal disembunyikan secara visual (`scrollbar-width: none`) untuk kerapian estetika tanpa mematikan kemampuan scroll roda mouse/touch. Mode lebar menggunakan scrollbar ramping 5px semi-transparan.
- Klik pada konten halaman dalam mode desktop lebar tidak menutup menu grup akordeon yang sedang aktif, menjaga kontinuitas konteks kerja pengguna.
- Identitas pengguna dan tombol keluar berada pada satu menu akun di topbar, bukan di sidebar.

## Dashboard dan Grid Panel
- Dashboard awal menggunakan layout umum yang konsisten untuk semua pengguna. Isi kartu, tautan cepat, dan ringkasan data mengikuti izin pengguna.
- Kartu statistik ikhtisar (`.stats-grid`) menggunakan grid dinamis `repeat(auto-fit, minmax(13.5rem, 1fr))` sehingga beradaptasi dengan jumlah metrik yang tersedia tanpa menyisakan ruang kosong yang timpang.
- Penataan `.content-grid` mengatur ulang margin adjacent sibling `.panel + .panel` sehingga panel yang berdampingan (seperti alur persiapan awal dan kartu status Neo Feeder) memiliki garis atas (*top baseline*) yang sejajar rata.
- Banner informasi aksi (`.period-banner`) menempatkan tombol tindakan di ujung kanan container dengan `margin-left: auto; flex-shrink: 0;`.

## Komponen Pencarian, Form, dan Modal
- Seluruh elemen input formulir (`.ui-input`, `select.ui-input`, `input[type="number"]`, `input[type="text"]`, `input[type="date"]`) dan tombol aksi standar (`.ui-button`, `.ui-button--primary`, `.ui-button--secondary`) distandarisasi dengan tinggi terkunci yang sama persis: `height: 2.625rem; min-height: 2.625rem; max-height: 2.625rem; box-sizing: border-box;`. Hal ini menjamin seluruh input dan tombol yang bersandingan pada baris pencarian, filter (seperti filter Log Audit), maupun formulir grid memiliki ketinggian piksel yang identik (42px) tanpa ada tombol yang lebih pendek atau mencuat.
- Kontainer field `.ui-field` menggunakan flex vertikal (`display: flex; flex-direction: column; gap: 0.35rem; align-items: stretch;`) dengan input yang konsisten, sehingga teks bantuan (*help text*) tidak mendistorsi ketinggian box input.
- Komponen `.table-search` dirancang lebar penuh (`width: 100%`) dengan input pencarian fleksibel yang mengisi ruang secara proporsional dan sejajar dengan tombol aksi.
- Untuk filter multi-kolom yang menyertakan label di atas input (seperti pada Log Audit, Yudisium, dan Keuangan), container filter menggunakan `align-items: flex-end; flex-wrap: wrap;` sehingga tombol aksi berada sejajar di garis bawah (*baseline*) bersama kotak input.
- Modal dan formulir ringkas menggunakan layout 2 kolom responsif (`settings-form-grid`). Field deskriptif yang membutuhkan ruang luas (judul/topik tugas akhir, nama acara, catatan multiline, kebijakan transkrip, status kelulusan) menggunakan utilitas `.settings-form-span` (merentang 2 kolom) agar susunan formulir selalu simetris dan seimbang.
- Manajemen hak akses peran (`settings/roles`) menggunakan struktur `.permission-groups-container` dan `.permission-grid` dengan komponen `.permission-checkbox-item`, menggantikan pola panel bersarang dan checkbox login.
- Komponen `.ui-empty-state` mendukung ikon ilustratif dan tombol aksi primer (`x-slot:action`) untuk memandu langkah pertama pengguna ketika daftar data masih kosong.

## Sistem Tabel Global (`.ui-table`)
- Komponen tabel `<x-ui.table>` menggunakan wrapper `.ui-table-wrap` dengan batas border ramping, sudut melengkung (`border-radius: var(--radius-md)`), dan scrollbar horizontal otomatis untuk layar sempit tanpa memotong tata letak halaman.
- Header tabel (`<thead> <th>`) memiliki latar warna netral soft (`var(--color-neutral-100)`), teks uppercase dengan letter-spacing 0.04em, padding konsisten (0.75rem 1rem), dan garis pemisah tegas (`1px solid var(--color-border)`).
- Setiap sel data (`<tbody> <td>`) memiliki padding vertikal 0.8rem dan horizontal 1rem, perataan vertikal tengah (`vertical-align: middle`), dan garis pemisah horizontal yang konsisten.
- Efek hover baris memberikan umpan balik visual yang halus (`background-color: var(--color-neutral-50)`).
- Caption tabel (`<caption>`) disembunyikan secara visual dengan class `.sr-only` agar tidak bertumpuk dengan judul seksi (`.section-heading`), namun tetap 100% terbaca oleh teknologi pembaca layar (screen reader).
- Tabel dengan data lebar tinggi/panjang (seperti pratinjau Neo Feeder) menggunakan wrapper `.feeder-data-table-wrap` dengan `white-space: nowrap` dan font monospace pada sel kode/UUID agar tidak terpotong atau wrap vertikal berantakan.
- Standarisasi tinggi elemen form: `.ui-input`, `select.ui-input`, dan `.ui-button` dikunci pada tinggi identik `2.625rem` (42px) dengan `box-sizing: border-box;` sehingga seluruh kolom input dan tombol aksi selalu rata tinggi secara visual di semua layar.
- Formulir pencarian daftar (`.table-search`): Pada desktop, tata letak menggunakan baris tunggal horizontal tanpa pembungkusan (`flex-wrap: nowrap; align-items: center`). Kolom pencarian (`.ui-input`) fleksibel memenuhi ruang sisa (`flex: 1 1 auto; width: auto; min-width: 0;`), sedangkan tombol "Cari" dan tombol reset berdampingan di sisi kanan (`flex: 0 0 auto;`). Pada layar ponsel (`<= 640px`), kolom dan tombol bertumpuk penuh (`width: 100%`).
- Toolbar filter periode (`.table-filter-bar`): Menggabungkan pemilihan periode akademik (`.filter-field-inline`) di sisi kiri dengan indikator badge status (`Periode Aktif Berjalan` / `Arsip Periode`) di sisi kanan secara horizontal dengan garis pemisah bawah (`border-bottom: 1px solid var(--color-border)`). Pada opsi dropdown, semester aktif diberi penanda eksplisit `(Aktif)`. Jika data periode belum dikonfigurasi, dropdown kosong dicegah muncul dan digantikan oleh empty-state panduan dengan tombol aksi pintasan `[ + Kelola periode akademik ]`.
- Spanduk periode akademik (`.period-banner`): Teks informasi (`.period-copy`) meregang (`flex: 1 1 auto`) mendorong tombol aksi langsung merapat ke sisi paling kanan kartu secara proporsional.
- Pada saat data kosong, antarmuka tidak menampilkan header kosong dengan empty-state terjepit di dalam `<td>`, melainkan langsung menampilkan komponen `.ui-empty-state` terpusat dengan ikon dan deskripsi jelas.

## Prinsip global
- Definisikan token global untuk tema, warna, tipografi/font, ukuran font, jarak, radius, bayangan, breakpoint, dan fokus.
- Gunakan layout global untuk navigasi, header, konten, breadcrumbs, notifikasi, dan area aksi.
- Gunakan komponen bersama untuk tombol, field, tabel, badge/status, dialog, empty/loading/error state, dan pagination.
- Pola utama untuk aksi tambah dan ubah data adalah modal agar pengguna tetap berada pada halaman daftar. Form panjang, proses bertahap, atau pekerjaan yang memerlukan konteks layar luas memakai halaman khusus; keputusan pengecualian mengikuti kompleksitas alur, bukan dibuat per halaman tanpa alasan.
- Pengecualian halaman khusus mencakup pengisian presensi seluruh roster kelas, penyusunan KRS, serta layar konfigurasi institusi/aturan akademik. Route CRUD halaman form lama yang sudah digantikan modal tidak dipertahankan agar satu tindakan hanya memiliki satu jalur UI.
- Modal mengikuti satu komponen dan perilaku global: judul yang jelas, ukuran sesuai isi, validasi dekat field, scroll internal bila perlu, fokus keyboard terjaga, dapat ditutup dengan Escape/tombol tutup, dan konfirmasi sebelum membuang perubahan yang belum disimpan. Modal diposisikan presisi di tengah layar (center-aligned secara horizontal dan vertikal) menggunakan `position: fixed; inset: 0; margin: auto;` agar tidak menempel di sudut kiri atas layar akibat reset bawaan CSS. Aksi berisiko seperti hapus/pengesahan tetap memakai konfirmasi yang jelas.
- Pagination memiliki satu tampilan dan perilaku global; ukuran halaman dan pola query ditetapkan konsisten.
- Semua halaman memakai komponen/token yang ada. Hindari duplikasi CSS, style inline, aturan CSS di PHP/Blade, serta `!important`. Aturan komponen tidak menanam nilai warna atau ukuran font; ubah tampilan melalui token tema global.
- Tema awal hanya terang. Semua warna dan permukaan memakai token semantik global agar tema gelap dapat ditambahkan kemudian tanpa mengubah styling tiap halaman/komponen.

## Performa visual
- Jangan gunakan `filter: blur()`, backdrop blur, efek frosted glass, atau efek visual sejenis yang menambah beban rendering/scroll.
- Hindari animasi berat, shadow berlapis, dan perubahan layout saat scroll. Gunakan transisi sederhana dan hormati `prefers-reduced-motion`.
- Scrollbar memakai gaya kustom yang ringan dan konsisten, dengan fallback scrollbar native bila styling tidak didukung. Jangan menghilangkan indikator scroll atau mengurangi aksesibilitas.
- Uji scroll pada tabel panjang dan perangkat dengan kemampuan terbatas; hindari listener scroll yang melakukan pekerjaan berat.

## Ikon
- Gunakan komponen global `x-ui.icon` dengan daftar nama ikon yang diizinkan; jangan memakai karakter Unicode/emoji sebagai ikon atau menyebarkan class Font Awesome langsung di tiap halaman.
- Saat ini Font Awesome Solid 7.3.1 dimuat dari cdnjs dengan versi dipatok. Hanya stylesheet inti dan gaya Solid yang diminta, tanpa skrip ikon.
- Karena aset bergantung pada CDN, ikon dapat tidak tampil saat CDN tak terjangkau. Evaluasi penyimpanan lokal sebelum deployment bila kampus membutuhkan operasi tanpa akses internet. Rujukan: [cdnjs Font Awesome](https://cdnjs.com/libraries/font-awesome) dan [dokumentasi Font Awesome](https://docs.fontawesome.com/web/).

## Layout dan pengalaman
Layout desktop memakai navigasi samping yang dapat diringkas, header ringkas, serta konten dengan hierarki judul yang jelas. Pada layar kecil, navigasi berubah menjadi pola yang mudah dijangkau dan tabel menyediakan cara akses yang sesuai tanpa memaksa halaman melebar.

Form memiliki label, petunjuk, validasi dekat field, dan pesan kegagalan yang dapat dipahami. Tabel menyediakan pencarian/filter/sort yang konsisten bila diperlukan, pagination global, serta state kosong dan loading. Status selalu memiliki teks/ikon selain warna.

## Kriteria penerimaan
- Halaman baru dibangun dari layout dan komponen global tanpa menambah styling lokal berulang.
- Aksi tambah/ubah memakai modal global untuk formulir ringkas; halaman khusus hanya digunakan untuk alur panjang/bertahap dengan alasan yang terdokumentasi.
- Tidak ada CSS inline, CSS dalam file PHP/Blade, `!important`, blur/backdrop blur, atau efek berat.
- Tema, font, skala tipografi, warna, dan pagination dapat diperbarui terpusat.
- Scrollbar kustom tetap terlihat, dapat digunakan dengan mouse/touch/keyboard sesuai konteks, dan tidak mengunci scroll.
- Tampilan responsif dan navigasi keyboard diuji; status tidak dibedakan hanya dengan warna.
- Scroll daftar panjang tetap lancar pada perangkat dan browser target yang ditetapkan.
- Komponen modal global digunakan pada tambah/ubah unit, program studi, mata kuliah, periode, kalender, pengguna, peran dan izin, kurikulum, penawaran kelas, ruang, mahasiswa, PMB, aktivitas kemahasiswaan, skala nilai, data tugas akhir, wisuda, serta mapping Feeder; form terkait mempertahankan input dan membuka kembali dialog yang benar setelah validasi gagal. Tidak ada halaman CRUD duplikat untuk entitas tersebut.

## Keputusan yang masih terbuka
Nuansa biru dan palet pendamping, ukuran breakpoint, nilai skala spacing, kepadatan tiap tabel, persistensi mode sidebar, serta desain detail ditetapkan sebelum implementasi UI. Mode awal terang, warna utama biru, Plus Jakarta Sans, kepadatan desktop ringkas, dan dua mode sidebar sudah diputuskan. Tema gelap dapat ditambahkan kemudian melalui token semantik. Ikuti [standar coding](13-standar-coding.md) dan [kebutuhan](02-kebutuhan.md).