# Design ## Source of truth - Status: Active - Last refreshed: 2026-06-06 - Primary product surfaces: OFBiz modern frontend replacement, Element Plus UI lab, component documentation, future page-by-page migration. - Evidence reviewed: `/Users/qiu/Desktop/ERP/element-plus-lab/UI.md`, `/Users/qiu/Desktop/ERP/element-plus-lab/src/components/ElementPlusShowcase.vue`, `/Users/qiu/Desktop/ERP/element-plus-lab/src/components/showcase/ComponentCatalogShowcase.vue`, `/Users/qiu/Desktop/ERP/element-plus-lab/src/data/erpComponentDocs.js`, `/Users/qiu/Desktop/ERP/element-plus-lab/src/styles/tokens.css`, `/Users/qiu/Desktop/ERP/element-plus-lab/src/styles/element-overrides.css`, `/Users/qiu/Desktop/ERP/element-plus-lab/src/styles/erp-patterns.css`, `/Users/qiu/Desktop/ERP/element-plus-lab/src/styles/app.css`. ## Brand - Personality: quiet, durable, operational, precise, and business-focused. - Trust signals: dense but readable tables, consistent status language, predictable actions, clear page paths, conservative color use. - Avoid: marketing-style hero pages, decorative card walls, thick color bars, flashy gradients, over-rounded active states, and UI that hides core workflow actions. ## Product goals - Goals: rebuild OFBiz screens page by page with a modern Vue 3 + Element Plus frontend while keeping backend behavior stable first. - Non-goals: redesign OFBiz business logic, optimize for old browsers, or create a generic consumer-facing design language. - Success signals: every page has a clear route, one primary action per work area, stable component usage rules, and screenshot-verifiable UI quality. ## Personas and jobs - Primary personas: ERP operators, sales operations, purchasing staff, warehouse users, finance users, administrators. - User jobs: scan business records, filter quickly, approve safely, edit structured data, inspect audit context, and recover from errors. - Key contexts of use: long daily sessions, high-density data, repeated workflows, permission-sensitive operations, and audit-heavy decisions. ## Information architecture - Primary navigation: left module menu for business domains, top page context for current object or workflow, local tabs for views inside the same object. - Core routes/screens: component catalog, single component detail pages, navigation patterns, tables, forms, status feedback, metric cards, future OFBiz list/detail/entry/process pages. - Content hierarchy: breadcrumb, page header, filters, toolbar, main data area, pagination, side drawer or local tabs for secondary detail. ## Design principles - Principle 1: choose the page skeleton before choosing controls. - Principle 2: use Element Plus as the primitive layer and ERP wrappers/patterns as the product layer. - Principle 3: optimize for scanning, repetition, and safety rather than visual novelty. - Principle 4: status must be readable in text; color only reinforces meaning. - Tradeoffs: prefer compact density for tables and query screens, but preserve breathing room in confirmations, dialogs, and destructive flows. ## Visual language - Color: low-saturation operational palette with clear primary, success, warning, danger, muted surfaces, and readable borders. - Typography: 12/13/14/18/24 scale; no viewport-scaled font sizes; letter spacing stays 0. - Spacing/layout rhythm: 4px-based token rhythm; 20-24px between major sections; tighter rhythm inside tables, filters, and toolbars. - Shape/radius/elevation: 6px controls, 8px panels, 1px borders, subtle shadows only when separation is needed. - Motion: restrained feedback only; avoid decorative motion. - Imagery/iconography: use Element Plus and lucide-style operational icons where useful; avoid illustrative decoration in ERP work surfaces. ## Components - Existing components to reuse: all 122 local Element Plus component directories documented in `erpComponentDocs.js`, plus Element Plus services and directives. - New/changed components: future `ErpTable`, `ErpSearchBar`, `ErpStatusTag`, `ErpMoneyCell`, `ErpEntityPicker`, `ErpAuditTimeline`, `ErpMetricCard`, and page wrappers. - Variants and states: metric cards use large/small/mini; buttons use one primary plus secondary/danger/link/dropdown; forms distinguish query/edit/advanced fields; tables handle empty/loading/error/selected rows. - Token/component ownership: primitives in `tokens.css`, global Element Plus mapping in `element-overrides.css`, reusable product patterns in `erp-patterns.css`, lab-only layout in `app.css`. ## Accessibility - Target standard: practical WCAG 2.2 AA direction for color contrast, keyboard access, focus visibility, and semantic structure. - Keyboard/focus behavior: Element Plus focus states remain visible; menus, dialogs, drawers, tabs, and form fields must be reachable by keyboard. - Contrast/readability: status colors cannot be the only signal; text labels are required for warning, danger, success, and progress. - Screen-reader semantics: page titles, form labels, table headers, dialog titles, and actionable controls need clear accessible names. - Reduced motion and sensory considerations: avoid nonessential animation and flashing loading states. ## Responsive behavior - Supported breakpoints/devices: desktop-first ERP workstations; tablet/narrow layouts may stack secondary rails, but old-browser support is not a constraint. - Layout adaptations: hide the right token rail below wide desktop, keep left navigation and main work area stable, stack catalog grids as space tightens. - Touch/hover differences: hover affordances are enhancements; actions must remain visible and clickable without relying on hover-only discovery. ## Interaction states - Loading: use `Skeleton` for page sections and `Loading` only for blocking actions. - Empty: use `Empty` with reason and next action. - Error: persistent error information uses `Alert`; recoverable field errors stay in form validation. - Success: short save confirmation uses `Message`; flow completion uses `Result`. - Disabled: disabled controls must still expose why the action is unavailable when business risk is high. - Offline/slow network, if applicable: show stable loading or retry states rather than layout jumps. ## Content voice - Tone: direct, operational, calm. - Terminology: use business nouns such as order, customer, supplier, warehouse, approval, inventory, receivable, audit. - Microcopy rules: action labels are verbs, statuses are nouns or short phrases, errors explain the next recoverable step. ## Implementation constraints - Framework/styling system: Vue 3, Element Plus, local CSS token files, hash routes for direct previews. - Design-token constraints: do not hardcode one-off colors or spacing in feature pages when a token or reusable class exists. - Performance constraints: use normal `Table` first; use `Table V2` when large row count and scroll performance justify it. - Compatibility constraints: no need to support old browsers for this modernization path. - Test/screenshot expectations: run `pnpm build`, verify inventory counts, and capture key route screenshots after meaningful UI changes. ## Open questions - [ ] Final OFBiz API integration shape / owner: backend integration pass / impact: wrapper props and loading/error states may need adjustment. - [ ] Exact brand naming and logo treatment / owner: product decision / impact: shell branding and document export visuals. - [ ] Accessibility target confirmation / owner: product and engineering / impact: formal QA checklist depth.