Skip to main content

UX Design Document (UDD)

Product: BayanCore ERP Document Owner: Design & Product Team Status: Draft / Requesting Feedback

1. UX Strategy & Philosophy​

  • Operating System, Not a Dashboard: BayanCore ERP must feel like a native, immersive environment rather than a collection of static web forms. The UI should respond fluidly to user interactions.
  • Interaction Model (Task-Driven & Assistant-Driven):
    • Task-Driven: Focus on guiding users through structured, linear workflows (e.g., a wizard for creating invoices) rather than exposing giant grid-like forms immediately.
    • Assistant-Driven: Utilize the AI/Autonomic engine to preemptively suggest actions, flag anomalies, and guide the user.
  • Progressive Disclosure: Traditional ERPs fail due to cognitive overload. We will aggressively hide 80% of ERPNext’s native complexity. Users will only see the exact links, fields, and modules relevant to their specific Role-Based Access Control (RBAC) profile.
  • Zero-Touch Automation (Where Possible): While manual data entry is unavoidable in an ERP, the design should prioritize automated extraction (e.g., AI OCR) and background processing (e.g., ZATCA clearance) wherever possible, shifting the user's focus toward "Review & Approve" when applicable.

2. "Liquid Glass" UI Guidelines & Design System​

The core aesthetic of BayanCore is premium, translucent, and interaction-driven.

2.1. The "No-Line" Rule (Optional Consideration)​

  • Soften UI Borders: Consider avoiding harsh, solid 1px borders to separate UI elements where it enhances the Liquid Glass feel.
  • Tonal Stacking & Volumetrics: Explore creating hierarchy and separation using subtle background color differences, soft drop shadows, and backdrop-blur utilities to make elements feel like they are floating.

2.2. Design Tokens (Tailwind CSS)​

  • Typography:
    • English: Modern, clean sans-serif (e.g., Inter, Outfit).
    • Arabic: Optimized, highly legible modern Arabic typeface (e.g., Cairo, Tajawal or IBM Plex Sans Arabic).
  • Color Palette: Colors must strictly align with the BayanCore brand guidelines:
    • Navy Core (#001f3f): Primary brand color, outer shell of logo, dark headings in light mode.
    • Brand Blue (#4A90E2): Inner logo "b" form, "CORE" wordmark, primary interactive elements (buttons, links).
    • Signal Red (#E63946): Central logo dot, notifications, critical CTAs, error states.
  • Shapes: Generous, consistent corner roundness (e.g., rounded-xl or rounded-2xl) for a soft, approachable feel.

2.3. Micro-Interactions & State Transitions​

  • All state changes (hover, focus, active) must feature smooth CSS transitions.
  • Use subtle scaling (e.g., scale-105) and glow effects for primary buttons.

3. RTL-First Design Rule​

Because the primary market is Saudi Arabia, the design cannot treat Arabic as an afterthought.

  • Native Bidirectionality: The entire shadcn/ui + Tailwind stack must dynamically flip based on the user's language preference.
  • Component Alignment: Icons, margins, padding, and text alignment must mirror flawlessly (e.g., a "Next" chevron points right in English, but left in Arabic).
  • Hijri Calendar: Date pickers must natively support Hijri/Gregorian toggling without breaking the layout.

4. Component Library Strategy (shadcn/ui)​

We will customize default shadcn/ui components to fit the Liquid Glass aesthetic:

  • Inputs & Forms: Replace standard bordered inputs with borderless, subtly shaded fields (e.g., soft inner shadows) and floating labels.
  • Data Tables: Implement borderless rows with distinct hover states. Table headers should use a glassmorphism effect (bg-white/50 backdrop-blur-md) so data scrolls beautifully underneath them.
  • Badges & Statuses: Utilize standard shadcn/ui Badge components customized with BayanCore's brand colors (e.g., Signal Red for errors, muted Brand Blue for processing states). Avoid inventing overly complex custom animated components to remain strictly aligned with the core shadcn/ui ecosystem.

5. Navigation Structure & User Flows​

  • Global Navigation (The Hubs): A collapsible, frosted-glass sidebar acts as the primary navigation. To prevent clutter, it does not list individual screens; instead, it routes users to their respective Department Hubs (e.g., Core Financials, Sales & ZATCA, Saudi HRMS).
  • The Command Palette (Cmd+K): A universally accessible search bar used for instantly navigating to deeply nested, hidden sub-modules (Progressive Disclosure) without requiring a bloated sidebar menu.
  • Primary Workflows (Task-Driven):
    1. The ZATCA Invoice Flow: Click Create Invoice (Surface Quick Action) -> Review Fields -> Submit (Trigger Autonomic Engine) -> Display Success Badge & PDF.
    2. The AI Payable Flow: Drag & Drop Vendor PDF -> System shows Skeleton Loader while local OCR runs -> Draft Invoice is presented in the CFO Dashboard's Pending Approvals queue.
    3. The HR Payroll Flow: Navigate to HR Hub -> Launch Monthly Payroll Wizard -> Review System-Calculated Deductions (GOSI/Absences) -> Click "Generate SIF".

6. Screen Inventory (Hubs & Progressive Spokes)​

To combat the overwhelming nature of the default ERPNext Desk, we will not restrict access to sub-modules, but rather reorganize them using a "Progressive Disclosure" architecture. Each module has a unified Dashboard (the Hub) with prominent "Quick Actions" for the most common tasks, while all other sub-modules are neatly tucked away in collapsible menus or accessed via search.

1. Global / System Screens:

  • Login & Authentication: Brand-aligned entry point with OTP/2FA support.
  • Global Command Palette: (Cmd+K interface) The primary method for users to access deeply nested sub-modules instantly without navigating complex menus.

2. Core Financials Hub (The CFO Dashboard):

  • Module Dashboard: Displays Cash Runway, Revenue Breakdowns (by Business Unit or Product Line), and Pending Approvals.
  • Primary Quick Actions (Surface Level): Purchase Invoice, Journal Entry, Bank Reconciliation.
  • Progressive Disclosure (Hidden by Default): Chart of Accounts, Cost Centers, Tax Rules, Currency Exchange, and all other core accounting sub-modules are accessible via an "Advanced Financials" dropdown or Cmd+K.

3. Sales & ZATCA Hub (The Revenue Dashboard):

  • Module Dashboard: Displays Pending Invoices, Unpaid Receivables, and ZATCA Clearance Status metrics.
  • Primary Quick Actions (Surface Level): Sales Invoice (ZATCA), Sales Order, Customer Profile.
  • Progressive Disclosure (Hidden by Default): Pricing Rules, Shipping Rules, Quotation Templates, and Item Groups are tucked under an "Advanced Sales & Settings" menu.

4. Saudi HRMS Hub (The People Dashboard):

  • Module Dashboard: Displays Headcount, Upcoming Iqama/Contract Expirations, and current Payroll Run Status.
  • Primary Quick Actions (Surface Level): Employee Profile, Monthly Payroll Wizard, Leave Request Approval.
  • Progressive Disclosure (Hidden by Default): Shift Types, Salary Structures, Expense Claim Types, and Appraisals are collapsed into an "HR Operations" menu.

7. Edge Cases & Accessibility​

  • Handling API Timeouts: If the ZATCA API is down or slow, the UI must gracefully show a "Queued for Clearance" state rather than locking the user's screen.
  • Missing AI Data: If the AI OCR fails to read a vendor's VAT number from a blurry receipt, the UI must highlight the missing field in red and prompt the user for manual entry.
  • Accessibility (a11y): Despite the heavy use of glassmorphism, text contrast ratios must remain WCAG compliant. All custom components must retain keyboard navigability (Tab/Enter/Space) and ARIA labels.