# Panduan Desain eKoas

Ringkasan sistem desain agar tampilan tetap konsisten saat halaman baru ditambahkan. Berkas terkait:
[public/assets/app.css](../public/assets/app.css) (gaya), [public/assets/app.js](../public/assets/app.js) (interaksi), [app/layout.php](../app/layout.php) (kerangka & komponen PHP).

## Tema warna "Almamater FK" (dari foto gedung fakultas)
Warna diambil dengan menganalisis foto `docs/Gedung Fakutlas Kedokteran.jpg` (kelompok rona dominan), lalu disesuaikan agar kontras teks memenuhi AA:

| Unsur di gedung | Warna | Token | Dipakai untuk |
|---|---|---|---|
| Tiang & kaca hijau tua | `#1b6a53` (aksi) · `#0f4236 → #08221d` (sidebar) | `--brand`, `--side-a/b/c` | Tombol utama, tautan, sidebar, kartu sambutan |
| Panel & ornamen kuning emas | `#e8b020` | `--gold` (+ `--gold-ink`, `--gold-soft`) | Penanda menu aktif, lencana jumlah, tombol di atas kartu sambutan, peringatan/progres rendah, logo |
| Garis biru kobalt | `#2f6bd0` | `--blue`, `--info` | Status informasi, aksen strip |
| Tiang merah | `#c8322a` | `--red`, `--err` | Bahaya/penolakan |
| Strip hijau limau | `#a9c234` | `--lime` | Aksen strip |

**Tanda tangan visual**: strip empat warna (`--stripe`: emas · limau · biru · emas) meniru pita berwarna pada fasad — muncul di tepi atas sidebar, dasar kartu sambutan, dan dasar panel halaman masuk. Ornamen belah ketupat emas ([ornament.svg](../public/assets/ornament.svg), versi pudar untuk HP: [ornament-soft.svg](../public/assets/ornament-soft.svg)) terinspirasi ukiran pada fasad. Foto gedung ([gedung-fk.jpg](../public/assets/gedung-fk.jpg), salinan foto di `docs/`) menjadi latar samar panel halaman masuk.

Mengganti tema cukup mengubah blok token di awal `app.css` (light, dark, dan blok `prefers-color-scheme`); tidak ada warna tema yang ditulis langsung di halaman. Di mode gelap `--on-brand` (teks di atas tombol) menjadi hijau gelap agar tetap terbaca. Ikon PWA dibuat ulang dengan `php database/make_icons.php` (hijau + palang emas); bila ikon berubah, naikkan `CACHE` di `public/sw.js`.

## Prinsip
- **Tenang & klinis**: warna dasar teal (identitas), latar netral kebiruan, banyak ruang kosong, sudut membulat.
- **Mobile-first untuk pemakaian di bangsal**: menu bawah di HP, tombol cukup besar, tabel dapat digeser di dalam kartu.
- **Tanpa pustaka luar**: font sistem, ikon SVG sebaris, JS murni. Sesuai CSP (`default-src 'self'`) dan tetap cepat/offline-friendly.
- **Bisa diakses**: kontras teks, fokus terlihat (`:focus-visible`), `aria-label` pada tombol ikon, menghormati `prefers-reduced-motion`.

## Token (di `:root` pada app.css)
| Token | Kegunaan |
|---|---|
| `--brand`, `--brand-h`, `--brand-2`, `--brand-soft`, `--brand-ink`, `--on-brand` | Warna utama, hover, ujung gradasi, latar lembut, teks di atas latar lembut, teks di atas tombol |
| `--gold`, `--gold-h`, `--gold-ink`, `--gold-soft`, `--lime`, `--blue`, `--red` | Palet aksen dari gedung |
| `--side-a/b/c`, `--hero-a/b/c`, `--stripe` | Gradasi sidebar, kartu sambutan, dan pita empat warna |
| `--ok / --warn / --err / --info` (+ `-bg`) | Status sukses / peringatan / galat / informasi |
| `--bg`, `--surface`, `--surface-2`, `--line`, `--ink`, `--ink-2`, `--muted` | Latar halaman, kartu, garis, teks |
| `--radius`, `--radius-sm`, `--shadow-sm/--shadow/--shadow-lg` | Sudut & bayangan |

Mode gelap: token yang sama didefinisikan ulang di `:root[data-theme="dark"]` dan mengikuti preferensi sistem bila pengguna belum memilih. Pilihan pengguna disimpan di `localStorage` (`ekoas-theme`). **Jangan menulis warna heksadesimal langsung di halaman**; pakai `var(--…)` supaya mode gelap ikut bekerja.

## Kerangka halaman
```php
require BASE_PATH . '/app/layout.php';
layout_start('Judul Halaman', $user, 'Sub-judul opsional');   // sidebar, topbar, judul, pesan flash
...isi...
layout_end();                                                 // menu bawah (HP), skrip
```
`layout_start(..., $head = false)` menyembunyikan judul halaman (dipakai Beranda karena sudah ada hero). Menu dibangun oleh `nav_groups()` menurut peran; **menambah halaman baru = tambah satu baris di `nav_groups()`** (label, path, ikon, jumlah lencana opsional).

## Komponen (kelas CSS / helper PHP)
| Komponen | Pemakaian |
|---|---|
| Kartu form | `<form class="card">` — grid otomatis; `style="grid-column:1/-1"` untuk baris penuh |
| Tombol | `<button>` (utama), `class="ghost"` (sekunder), `class="danger"`, `.btn` untuk tautan, `.btn.sm` |
| Tabel | `<table>` biasa; JS membungkusnya otomatis dengan `.table-scroll` |
| Lencana status | `badge('menunggu')` → hijau/kuning/merah/biru/abu sesuai peta status; label kustom: `badge('lulus','Lulus')` |
| Bar progres | `progress_bar(66.7, $ambangKuning)` — hijau bila 100%, kuning bila di bawah ambang |
| Keadaan kosong | `empty_state('book', 'Judul', 'Keterangan')` |
| Ikon | `icon('nama')`; daftar nama ada di `icon()` pada layout.php |
| Tanggal | `tgl($tanggal)` / `tgl($tanggal, true)` → "25 Sep 2026" / "25 Sep 2026, 14:30" |
| Statistik / hero / tiles / feed | `.stats > .stat`, `.hero`, `.tiles > .tile`, `.feed > .feed-item`, `.rot-card` (lihat dashboard.php) |
| Tab filter | `<div class="tabs"><a class="active">…</a></div>`; bilah alat: `.toolbar` |
| Pesan | `flash('teks')` / `flash('teks','err')` → notifikasi kilat (tertutup sendiri untuk yang sukses). Kotak informasi permanen: `<p class="alert ok|err">` atau `.note` |
| Form filter sebaris | `<form method="get">` langsung di dalam konten otomatis ditata sebagai baris |

## Titik henti responsif
- `≥ 1024px`: sidebar tetap.
- `< 1024px`: sidebar menjadi laci (tombol hamburger / "Menu"), menu bawah 5 tombol muncul.
- `< 560px`: form satu kolom, kartu statistik dipadatkan.

## Catatan teknis
- Berkas CSS/JS diberi `?v=<waktu ubah berkas>` sehingga browser otomatis memuat versi terbaru setelah diedit.
- CSS memakai `color-mix()` dan `:focus-visible`: butuh browser modern (Chrome/Edge 111+, Safari 16.2+, Firefox 113+) — selaras target iOS 16.4+ pada README.
- Cetak (`Ctrl+P`): sidebar, topbar, dan menu bawah disembunyikan otomatis (dipakai laporan nilai).