LMS-BGN/docs/admin-payroll-reward-brownfield-epic.md

# Admin Payroll Reward System — Brownfield Epic: UI Harmonization & Mock Data Seeding

## Executive Summary
Kita akan menyelaraskan (harmonize) UI modul Admin Payroll Reward System di lingkungan brownfield, agar konsisten dengan Sidebar/TopBar dan DashboardLayout yang sudah ada. Selain itu, kita akan menyediakan mock data representatif (empty/normal/high-activity) untuk memverifikasi UX tanpa bergantung penuh pada backend. Targetnya adalah meningkatkan keterbacaan, konsistensi visual, dan mempercepat siklus QA dengan risiko regresi minimal. Prioritas: tinggi. Horizon: 2 minggu.

## Goals
- Menyatukan gaya visual (warna, tipografi, spacing) komponen payroll-reward agar selaras dengan Sidebar/TopBar dan DashboardLayout.
- Meningkatkan aksesibilitas dan keterbacaan (kontras warna sesuai standar WCAG).
- Menyediakan mock data untuk state umum (empty, normal, high-activity) agar QA bisa menguji end-to-end tanpa backend.
- Menambahkan feature flags untuk rollout aman dan mitigasi regresi.

## Scope
Dalam cakupan:
- Harmonisasi warna dan tema komponen di `src/features/payroll-reward-system` (kartu, badge/status, angka/metrik).
- Mengganti background gradient pada kartu reward menjadi warna solid selaras tone Sidebar (brand gelap/primary-900).
- Penyesuaian warna teks: angka/metrik berkontras tinggi; label/deskripsi lebih soft tapi tetap terbaca.
- Pembungkusan route `/admin/payroll` dengan `src/layouts/DashboardLayout.tsx`, memastikan Sidebar dan TopBar tampil konsisten.
- Penyediaan mock data untuk user aktif (mapping `demo-user-123` → `user.id`) dan skenario variasi (empty/low/high).
- Penambahan feature flags di `src/config/featureFlags.ts` (mis. `enablePayrollUIHarmonization`, `useDemoRewardData`).

Di luar cakupan:
- Perubahan/penyempurnaan login page (ditangani epic/PRD terpisah).
- Integrasi penuh ke backend payroll/komputasi reward.
- Redesign navigasi global di luar kebutuhan harmonisasi.

## User Stories
- Sebagai Admin, saya ingin dashboard reward payroll tampil dengan gaya visual konsisten (warna, spacing, tipografi) agar mudah di-scan dan dipahami.
- Sebagai QA, saya ingin mengaktifkan mock data dan menguji berbagai state (empty/normal/high-activity) tanpa bergantung backend.
- Sebagai Developer, saya ingin feature flags untuk menyalakan/mematikan harmonisasi UI dengan aman saat rollout.
- Sebagai Desainer, saya ingin kontras warna dan tipografi mengikuti standar aksesibilitas sehingga teks dan angka tetap terbaca pada berbagai perangkat.

## Acceptance Criteria
- Konsistensi UI:
  - Semua kartu reward menggunakan background solid (bukan gradient) selaras tone Sidebar.
  - Teks metrik (angka) memiliki kontras minimal 4.5:1 terhadap background; label/deskripsi readable (≥3:1).
  - Spacing/padding antar kartu konsisten; tidak ada overlap/tumpang tindih.
- Integrasi layout:
  - Route `/admin/payroll` dibungkus `DashboardLayout`; Sidebar/TopBar tampil dan tidak mengganggu konten utama.
- Mock data:
  - Flag `useDemoRewardData` ON menampilkan data contoh untuk `user.id` saat login (map ke `demo-user-123`).
  - Tersedia 3 state mock: `empty` (0 reward), `normal` (nilai sedang), `high-activity` (nilai tinggi, beberapa badges).
- Feature flags:
  - `enablePayrollUIHarmonization` dapat ON/OFF tanpa error; saat OFF, UI kembali ke gaya lama secara aman.
  - Tersedia dokumentasi cara toggle dan fallback perilaku saat OFF.
- QA checklist:
  - Visual regression minimal (halaman lain tidak berubah signifikan).
  - Responsif di mobile/tablet/desktop tetap baik.

## Milestones
1) Audit & Design Tokens (Minggu 1, Hari 1–2)
   - Audit komponen di `src/features/payroll-reward-system` dan dependensi di `src/components/dashboard`.
   - Tentukan palet solid selaras Sidebar (brand gelap/primary-900) dan aturan tipografi (heading, label, angka).
2) Implementasi UI Harmonization (Minggu 1, Hari 3–4)
   - Ganti gradient → solid tone pada kartu/badge.
   - Atur warna teks (angka kontras tinggi; label lebih soft).
   - Sesuaikan spacing/padding antar kartu sesuai grid sistem.
3) Integrasi Layout & Flags (Minggu 1, Hari 5)
   - Bungkus `/admin/payroll` dengan `DashboardLayout`.
   - Tambah feature flags di `src/config/featureFlags.ts` (`enablePayrollUIHarmonization`, `useDemoRewardData`).
4) Mock Data Seeding (Minggu 2, Hari 1–2)
   - Buat provider/mock service untuk 3 state (empty/normal/high).
   - Mapping `demo-user-123` → `user.id` dari `AuthContext`.
5) QA & Hardening (Minggu 2, Hari 3–5)
   - Uji responsif, aksesibilitas, dan regression di halaman terkait.
   - Dokumentasi toggle flags dan panduan verifikasi state untuk QA.

## Dependencies
- `src/layouts/DashboardLayout.tsx`, `Sidebar.tsx`, `TopBar.tsx`
- `src/features/payroll-reward-system` (komponen kartu/badge/metrik)
- `tailwind.config.js` (warna/tema), `src/styles/globals.css`
- `src/config/featureFlags.ts` (penambahan flags)
- `src/contexts/AuthContext.tsx` (akses `user.id` untuk mapping mock data)

## Risks & Mitigations
- Regresi visual pada halaman lain akibat perubahan token/global style.
  - Mitigasi: Batasi perubahan pada payroll-reward dan komponen terkait; gunakan flags; lakukan QA regression checklist.
- Kontras warna kurang sesuai di beberapa display.
  - Mitigasi: Ikuti standar WCAG; uji di perangkat/brightness berbeda; sediakan varian palet jika perlu.
- Mock data mengganggu data real saat staging.
  - Mitigasi: Default flags OFF di staging/production; dokumentasi mode demo jelas; gating via env.
- Waktu implementasi melampaui target karena refactor komponen lama.
  - Mitigasi: Prioritaskan surface paling terlihat (dashboard reward); minor legacy dikerjakan iteratif.

## Next Actions
1) Konfirmasi fokus epic dan horizon: “UI harmonization + mock data seeding”, 2 minggu (boleh koreksi).
2) Setujui referensi konteks: gunakan `admin-brownfield-architecture.md` (default: ya).
3) Minta pembuatan story breakdown:
   - Story A: Harmonisasi warna/typography + spacing kartu reward.
   - Story B: Pembungkusan `/admin/payroll` dengan `DashboardLayout`.
   - Story C: Implement flags `enablePayrollUIHarmonization` & `useDemoRewardData`.
   - Story D: Mock data provider (empty/normal/high) + mapping `demo-user-123` → `user.id`.
   - Story E: QA suite, dokumentasi toggle, panduan verifikasi.
4) Setelah disetujui, keluarkan backlog terurut + estimasi + rencana rilis.