first

docs/06-ui-ux-plan.md

@@ -0,0 +1,229 @@
+# UI/UX Plan
+
+## Design Direction
+
+The application should feel like a practical Malaysian government/PBT administration system:
+
+- Clean.
+- Responsive.
+- Data-first.
+- Easy to scan.
+- Conservative use of color.
+- Clear status labels and actions.
+- Works well on PC/laptop, tablet, and mobile phone.
+
+The UI should prioritize operational speed over decorative presentation.
+
+## Frontend Stack
+
+- Blade templates.
+- Bootstrap 5.
+- Bootstrap Icons.
+- jQuery for progressive enhancement where suitable.
+- Vite for compiled CSS and JavaScript.
+- SweetAlert2 for confirmations.
+- Select2 or Tom Select for searchable dropdowns.
+- Flatpickr for date/time fields.
+- DataTables only where it adds value; otherwise use Laravel server-side pagination with filters.
+
+## Layout
+
+### Authenticated Layout
+
+Common elements:
+
+- Top navigation bar.
+- Collapsible sidebar or offcanvas menu on mobile.
+- Role-aware navigation items.
+- Breadcrumbs.
+- Page title and primary action area.
+- Flash messages.
+- Main content area.
+
+### Public Application Layout
+
+Common elements:
+
+- Simple header.
+- Pusat Mengundi context panel.
+- Step-friendly form sections.
+- Mobile-first form controls.
+- Clear closed-registration and duplicate-registration messages.
+
+## Responsive Requirements
+
+Desktop:
+
+- Use tables with filters for large data.
+- Summary cards at top of dashboard.
+- Side navigation can remain visible.
+
+Tablet:
+
+- Use two-column card grids where appropriate.
+- Keep filters collapsible if space is limited.
+
+Mobile:
+
+- Use offcanvas navigation.
+- Convert dense tables into stacked card rows where practical.
+- Keep primary actions sticky or clearly visible on long forms.
+- Avoid horizontal scrolling except for exports or unavoidable wide data.
+
+## Dashboard Plans
+
+### Admin Dashboard
+
+Cards:
+
+- Total Pusat Mengundi.
+- Total Saluran.
+- Total applicants.
+- Approved count.
+- Pending review count.
+- Missing IC/bank statement count.
+- Bank verification pending count.
+- Attendance summary on polling day.
+
+Primary views:
+
+- Election readiness summary.
+- Registration period status.
+- Pusat Mengundi list with setup completeness.
+- Attendance summary when active.
+
+### PPM Dashboard
+
+Cards:
+
+- Assigned Pusat Mengundi.
+- Pending applications.
+- Approved staff by role.
+- Saluran assignment status.
+- Attendance action button on polling day.
+
+Primary views:
+
+- Applications requiring review.
+- Saluran staffing completeness.
+- Police/KKM/JKM information.
+
+### KTM Dashboard
+
+Cards:
+
+- Assigned Saluran.
+- KP list count.
+- Remaining KP vacancy.
+- Registration period status.
+
+Primary actions:
+
+- Register KP if registration period is open.
+- Review KP under own team.
+
+### Admin Kewangan Dashboard
+
+Cards:
+
+- Bank verification pending.
+- Missing bank statement.
+- Rejected bank records.
+- Requires correction.
+
+Primary views:
+
+- Finance verification table.
+- Filters by Pusat Mengundi, role, finance status, missing document, and missing account number.
+- Export finance list.
+
+## UI Components
+
+Use reusable Blade components or partials for:
+
+- Status badges.
+- Role badges.
+- Breadcrumbs.
+- Summary cards.
+- Filter forms.
+- Empty states.
+- Confirmation modals.
+- File/document rows.
+- Sensitive data display with mask/reveal authorization.
+- Pagination wrapper.
+
+## Status Display
+
+Application statuses should use badges:
+
+- `submitted`: secondary/info.
+- `under_ppm_review`: warning.
+- `approved`: success.
+- `rejected`: danger.
+- `assigned`: primary/success.
+- `cancelled`: dark/secondary.
+- `deleted_by_ktm`: secondary.
+
+Finance statuses:
+
+- `pending`: warning.
+- `verified`: success.
+- `rejected`: danger.
+- `requires_correction`: info.
+
+Attendance statuses:
+
+- `present`: success.
+- `absent`: danger.
+- `not_recorded`: secondary.
+
+## Forms
+
+Guidelines:
+
+- Use server-side validation with clear inline errors.
+- Use required markers for mandatory fields.
+- Group long forms into sections.
+- Keep upload guidance short and precise.
+- Show current selected Pusat Mengundi on public QR form.
+- For KP/KPDP role, dynamically show KTM dropdown only when required.
+- Do not ask KTM applicants to select Saluran.
+
+## Tables and Lists
+
+Guidelines:
+
+- Use server-side pagination for large lists.
+- Add filters before data tables.
+- Use badges for status and role.
+- Show masked IC/account by default.
+- Keep actions in dropdown or grouped buttons.
+- Use mobile stacked cards for high-use mobile screens.
+
+## Confirmation and Destructive Actions
+
+- Use SweetAlert2 or Bootstrap modal for delete/cancel/reject confirmation.
+- Reject and post-closing changes must collect a reason/note.
+- Destructive actions should be rare and auditable.
+
+## Accessibility
+
+- Use semantic headings.
+- Use labels for all inputs.
+- Maintain adequate contrast.
+- Ensure keyboard focus is visible.
+- Avoid relying on color alone for status.
+- Provide meaningful button text or accessible labels.
+
+## Empty States
+
+Examples:
+
+- No applications pending review.
+- No KP vacancy available.
+- Registration is closed.
+- No bank records require correction.
+- No attendance records yet.
+
+Empty states should state the situation and provide the next valid action where applicable.
+