ERP/ofbiz-framework/plugins/modern-ui/DESIGN.md

Design

Source of truth

• Status: Active
• Last refreshed: 2026-06-09
• Primary product surfaces: /modern/app/ admin shell, dashboard, domain admin pages, generated business pages, dedicated ERP workspaces, POS and commerce operator surfaces.
• Evidence reviewed: plugins/modern-ui/UI.md, plugins/modern-ui/app/src/styles/erp-ui.css, tokens.css, base.css, element-overrides.css, erp-patterns.css, modern.css, and ERP wrapper usage in plugins/modern-ui/app/src/components/erp.

Brand

• Personality: quiet, operational, trustworthy, dense enough for repeated back-office work.
• Trust signals: stable navigation, visible permissions, explicit unavailable/error states, audit context, predictable action hierarchy.
• Avoid: marketing composition, decorative dashboards, isolated style experiments, and operator-facing engineering status language.

Product goals

• Goals: make OFBiz administration usable as a production management site for orders, catalog, parties, finance, inventory, procurement, manufacturing, human resources, content, POS, commerce, reporting, security, and system operations.
• Non-goals: replacing business verification with structural coverage, adding a second design system, or turning Element Plus primitives into page-local bespoke styling.
• Success signals: business pages use ERP wrappers, work areas are compact and scan-friendly, actions are clearly ranked, and runtime/coverage/parity evidence is reported with precise scope.

Personas and jobs

• Primary personas: operations clerk, finance operator, catalog manager, inventory coordinator, procurement user, HR admin, content manager, system administrator.
• User jobs: find records, compare rows, submit service actions, inspect permissions, review audit context, run reports, process exceptions, and continue interrupted work.
• Key contexts of use: desktop-first back-office sessions, high data density, repeated scanning, partial backend availability, permission-gated operations.

Information architecture

• Primary navigation: ErpAppShell owns side navigation, top commands, session identity, module entry points, and support links.
• Core routes/screens: dashboard, domain admin pages, #/pages/:pageId generated pages, dedicated Erp*Workspace flows, report/POS/commerce surfaces.
• Content hierarchy: page header, tabs or local navigation, query/action band, primary work area, side context for audit, permissions, handoff, and receipts.

Design principles

• Wrapper first: business pages depend on ERP wrappers and ERP patterns, not scattered Element Plus styling.
• Text first, color second: state copy explains the business meaning; color reinforces priority or risk.
• Dense, not cramped: use 4px spacing rhythm, 28/32/36px controls, compact tables, and clear grouping.
• One next action: each work area has one primary action and clear secondary/danger/overflow handling.
• Tradeoffs: prefer operational consistency over visual novelty; prefer structural reuse over one-off page polish.

Visual language

• Color: primary blue for navigation, focus, and primary actions; success green for completed/healthy/connected; warning amber for pending/review/background processing; danger red for errors/rejection/cancel/delete; info gray for neutral metadata.
• Typography: 24px page titles, 18px large panel titles, 14px body and primary controls, 13px compact text, 12px status and metadata; letter spacing remains 0.
• Spacing/layout rhythm: 4px grid through --erp-space-*; desktop working width around 1180px; page sections are work areas, not nested decorative cards.
• Shape/radius/elevation: 4px/6px normal radius, 8px maximum; no decorative shadows on work surfaces; 1px borders and left state lines carry structure.
• Motion: Element Plus defaults only; avoid motion that delays data scanning or action completion.
• Imagery/iconography: icons support navigation/actions/status; back-office pages do not rely on ornamental imagery.

Components

• Existing components to reuse: ErpPageHeader, ErpSearchForm, ErpEntityForm, ErpDataTable, ErpActionBar, ErpStatusTag, ErpLookup, ErpUpload, ErpDrawer, ErpAuditTimeline, ErpPageRenderer, ErpAdapterBlock, and dedicated Erp*Workspace components.
• New/changed components: add wrapper or pattern only when a repeated business need is not covered by existing wrappers.
• Variants and states: forms use search/entity/one-column densities; tables use compact scan rows; actions use primary/default/link/danger/overflow; states use loading, empty, unavailable, error, success, disabled, and permission explanations.
• Token/component ownership: tokens.css owns variables; element-overrides.css maps Element Plus; erp-patterns.css owns reusable ERP patterns; modern.css owns shell and page-layout composition.

Accessibility

• Target standard: practical WCAG 2.1 AA for contrast, focus, keyboard access, and readable state copy.
• Keyboard/focus behavior: Element Plus focus rings must remain visible and use --erp-color-focus-ring.
• Contrast/readability: state colors must not carry meaning alone; pair with labels and descriptions.
• Screen-reader semantics: use tables for tabular data, descriptions for readonly facts, alerts for permission/error/unavailable states.
• Reduced motion and sensory considerations: avoid nonessential animation and color-only alerts.

Responsive behavior

• Supported breakpoints/devices: desktop-first admin workflows; narrower viewports collapse side context and multi-column grids without changing business order.
• Layout adaptations: search forms move from four columns to fewer columns; entity forms from two columns to one; workbench side panels stack below main work.
• Touch/hover differences: POS and commerce may use larger controls; back-office pages keep compact density while preserving tap targets where needed.

Interaction states

• Loading: skeleton or inline loading text stays inside the work area.
• Empty: explain whether no records match, permissions are missing, session is absent, service is unavailable, or data is flow-dependent.
• Error: keep the reason visible in the page; toast can supplement but not replace page feedback.
• Success: show action receipt or result context in the work area.
• Disabled: keep the disabled control visible when it teaches permission, session, or backend state.
• Offline/slow network: treat as unavailable/error with retry or next-step copy when the API contract supports it.

Content voice

• Tone: short, concrete, business-operational Chinese.
• Terminology: current document, business data, submit action, permission context, pending queue, exception handoff, action receipt, business flow, audit record.
• Microcopy rules: do not expose component paths, generated source, internal coverage states, or implementation labels as the main operator narrative.

Implementation constraints

• Framework/styling system: Vue 3, Element Plus, CSS tokens and patterns, ERP wrappers.
• Design-token constraints: pages do not define their own color, radius, spacing, shadow, button, table, or status systems.
• Performance constraints: generated pages and large admin routes must stay lightweight; prefer shared patterns over repeated page CSS.
• Compatibility constraints: original OFBiz metadata remains route, form, table, permission, action, and fallback source until business parity is signed off.
• Test/screenshot expectations: run build for changed UI code, runtime smoke for shell/pages, coverage for structural contracts, and parity checks only for scoped business behavior claims.

Open questions

• Owner: product/design. Impact: decide whether POS and commerce should receive a separate touch-density token set or continue sharing the admin density with local overrides.
• Owner: QA/business. Impact: define representative old-vs-new business E2E scenarios by module before claiming workflow completion.