ERP/DESIGN.md

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.