# CHM ERP — Enterprise Design System ## Vision One unified, component-based design language across every module. The product should feel comparable in quality to Dynamics 365, OrangeHRM, SAP Fiori, and Linear — while remaining original to Celebrate Hope Ministries. **Constraints:** UI, UX, and performance only. No changes to business logic, accounting calculations, or workflows. --- ## Design Principles 1. **One product** — Every screen uses the same tokens, components, and patterns. 2. **Progressive enhancement** — Legacy Blade pages inherit global styles; new work uses `` components. 3. **Performance first** — Lazy-load heavy assets; one CSS stack; defer non-critical JS. 4. **Accessible by default** — Keyboard navigation, focus rings, ARIA labels, contrast-safe tokens. 5. **Preference-aware** — Theme, accent, density, and layout persist per user (local + server). --- ## Token Architecture | Layer | File | Purpose | |-------|------|---------| | Tokens | `chm-design-system.css` | Colors, spacing, typography, motion, density, accents | | Theme | `chm-theme.css` | Light/dark semantic mappings | | Components | `chm-ui.css` | Layout shell, sidebar, tables, forms, cards | HTML attributes on ``: - `data-chm-theme` — `light` | `dark` - `data-chm-theme-preference` — `light` | `dark` | `system` - `data-chm-accent` — `green` | `blue` | `navy` | `teal` - `data-chm-density` — `comfortable` | `compact` - `data-chm-sidebar` — `expanded` | `collapsed` --- ## Component Library (`resources/views/components/chm/`) | Component | Status | Use for | |-----------|--------|---------| | `layout/page` | ✅ | Standard page shell | | `page-header` | ✅ | Title, breadcrumb, actions | | `card` | ✅ | Content sections | | `stat-card` | ✅ | Dashboard KPIs | | `table-toolbar` | ✅ | Listing pages | | `filter-panel` | ✅ | Advanced filters | | `form-floating` | ✅ | Premium inputs | | `form-section` | 🆕 Phase 1 | Grouped form fields | | `table-empty` | 🆕 Phase 1 | Professional empty states | | `empty-state` | ✅ | Generic empty UI | | `button`, `modal`, `tabs`, `alert`, `status-badge` | ✅ | Actions & feedback | | `skeleton`, `loading` | ✅ | Loading states | --- ## JavaScript Modules | Module | Responsibility | |--------|----------------| | `chm-preferences.js` | Theme, accent, density, sidebar state; server sync | | `chm-sidebar.js` | Search, active route, **collapsible groups**, keyboard nav | | `chm-datatables.js` | Standard DataTables defaults + exports | | `chm-forms.js` | Select2, flatpickr, floating labels, validation UI | | `chm-nav.js` | Recent pages tracking | | `chm-favorites.js` | Pinned sidebar favorites | | `chm-global-search.js` | ⌘K module search | | `chm-ui.js` | Skeleton, toastr defaults | --- ## Sidebar (Flagship Feature) - Light/dark adaptive surface with accent stripe - Module search with instant filter - **Collapsible groups** with persisted open/closed state - Chevron indicators + smooth expand/collapse - Pinned favorites + recently visited - Collapsed mode with hover expansion - Keyboard: ↑↓ navigate, Enter activate, Escape clear search - Badge-ready menu items (`.chm-nav-badge`) --- ## Tables (Every Listing Page) Target pattern (CFDP Children is the pilot): ```blade ... {{-- when no data --}} ``` DataTables via `chm-datatable` + `chm-datatable-export` classes: - Search, pagination, column chooser - Copy, CSV, Excel, PDF, Print - Sticky headers, responsive scroll - Loading skeleton + empty state --- ## Forms - Section cards (``) - Floating labels (``) - Select2 + flatpickr via `chm-forms.js` - Inline validation errors - Responsive 12-column grid --- ## User Preferences Stored in `users.ui_preferences` (JSON) + `localStorage` for instant apply. | Preference | Values | |------------|--------| | Theme | light, dark, system | | Accent | green, blue, navy, teal | | Density | comfortable, compact | | Sidebar | expanded, collapsed | Access via header **Preferences** panel (gear icon). --- ## Implementation Phases ### Phase 1 — Foundation (current) - Design tokens + enhanced UI shell - Preferences engine + migration - Sidebar collapsibles + keyboard nav - Preferences panel - Form/table component upgrades - Login polish ### Phase 2 — Shell completion - Auth pages (forgot/reset password) - Notifications panel redesign - Profile & settings pages - Global search polish ### Phase 3 — Dashboard - Module dashboard templates (Accounting, CFDP, HR, Coffee, etc.) - Chart theming tied to accent colors ### Phase 4 — High-traffic modules - CFDP (Children, Sponsors, Letters) - Accounting (Journals, Invoices, Payments) - HR (Employees, Payroll) ### Phase 5 — Remaining modules - Transformation, Church, Health, Administration - Reports & print styles ### Phase 6 — Performance audit - Livewire component lazy loading - DataTables defer on tabbed pages - Blade partial caching review - Remove duplicate legacy CSS/JS --- ## Module Migration Order 1. CFDP Children ✅ (pilot) 2. CFDP Sponsors 3. Accounting Journals / Invoices 4. HR Employees 5. Coffee sales / inventory 6. User management 7. Reports 8. Remaining modules alphabetically --- ## Duplicated UI to Consolidate - `page-breadcrumb` → `` - Raw `.card` wrappers → `` - `#example` tables → unique IDs + `` - Inline DataTables init → `ChmDataTable.initAll()` - Multiple jQuery loads → single stack in `assets-scripts` - Legacy theme switcher in `app.js` → `ChmPreferences` --- ## Performance Checklist - [ ] One jQuery, one Bootstrap bundle - [ ] DataTables Buttons loaded only via `@push('vendor-scripts')` - [ ] Chart.js loaded only on dashboard/chart pages - [ ] CSS: tokens → theme → ui (3 files max) - [ ] JS: defer non-critical modules - [ ] Page skeleton removed on `DOMContentLoaded` - [ ] `deferRender: true` on all DataTables - [ ] Site settings cached (already in `AdminLayoutComposer`) --- ## Do Not Change - Controllers' business logic - Accounting calculations and GL posting - Database schema (except `ui_preferences`) - Spatie permission checks - Route names and workflow order