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

Design

Source of Truth

• Status: Active
• Last refreshed: 2026-06-09
• Primary product surfaces: ERP 管理员工作台、领域管理页、实体查询页、表单录入页、记录详情抽屉、模块导航。
• Evidence reviewed:
  • src/components/erp/ErpAppShell.vue
  • src/components/erp/ErpPageHeader.vue
  • src/components/erp/ErpDomainAdminView.vue
  • src/components/erp/ErpTabbedDataPanel.vue
  • src/components/erp/ErpDataTable.vue
  • src/components/erp/ErpSearchForm.vue
  • src/components/erp/ErpEntityForm.vue
  • src/components/erp/ErpStatusTag.vue
  • src/components/erp/ErpActionBar.vue
  • src/components/erp/ErpDrawer.vue
  • src/components/erp/ErpUpload.vue
  • src/styles/erp-ui.css
  • src/styles/tokens.css
  • src/styles/base.css
  • src/styles/element-overrides.css
  • src/styles/erp-patterns.css
  • src/styles/modern.css
• Companion handbook: UI.md is the component and pattern usage guide for page authors.

Brand

• Personality: calm, operational, precise, trustworthy.
• Trust signals: compact density, visible filters, clear record counts, status labels, explicit disabled reasons, consistent detail entry points.
• Avoid: decorative-first layouts, oversized marketing treatment, one-off color palettes, nested card stacks, local CSS that duplicates wrapper behavior, copy that reads like an internal implementation report.

Product Goals

• Goals:
  • Make every business page feel like a usable ERP administrator workspace.
  • Surface search, tabular records, state, actions, and detail paths within the first screen.
  • Keep complex areas scan-friendly for repeated daily use.
  • Let wrappers and shared patterns carry layout, density, tokens, and interaction states.
• Non-goals:
  • Building separate visual systems per domain.
  • Recreating Element Plus primitives directly in each page when an ERP wrapper exists.
  • Adding decorative sections that do not help an administrator decide or act.
• Success signals:
  • A page can be understood by title, breadcrumb, filters, table, status, and actions without reading code.
  • Loading, empty, error, permission, and disabled states are visible and useful.
  • New pages need little or no local CSS beyond page-specific grid placement.

Personas and Jobs

• Primary personas:
  • ERP administrator managing orders, products, parties, accounting, facilities, operations, content, and HR records.
  • Domain operator who searches, filters, updates, and checks record status throughout the day.
  • Implementation maintainer who adds pages while preserving a shared product experience.
• User jobs:
  • Find records by identifier, name, state, date, or related entity.
  • Compare records in dense tables and open one record for details.
  • Understand whether an action can run, why it is disabled, and what result followed.
  • Move from global navigation to a domain workspace, then to a specific record or action.
• Key contexts of use:
  • Desktop administration with high information density.
  • Narrow screens where navigation collapses and forms become single-column.
  • Mixed data readiness where some records, actions, or permissions may be unavailable.

Information Architecture

• Primary navigation:
  • ErpAppShell owns the top-level shell, left menu, top actions, global search, and breadcrumb trail.
  • Business pages should not create independent shell navigation.
• Core routes and screens:
  • Domain landing views use ErpDomainAdminView or a domain-specific workspace wrapper.
  • State-split record areas use ErpTabbedDataPanel when one kind of work is divided by queue, status, facility, ownership, or approval step.
  • Entity record areas use ErpDataTable for listing and detail drawer entry.
  • Search and edit flows use ErpSearchForm and ErpEntityForm.
• Content hierarchy:
  • Page header: breadcrumb, domain title, short operational description, primary action.
  • Work controls: search form, status filters, quick actions.
  • Main work area: data table with pagination and row-level details.
  • Support area: metrics, queue cards, execution state, or governance notes when they help the workflow.

Design Principles

• Wrapper-first: every business page starts from src/components/erp wrappers before direct Element Plus composition.
• Data before decoration: tables, filters, status, and actions are the primary visual weight.
• One clear action area: primary actions sit in the header or action bar; secondary actions group in overflow or a side panel.
• Stable density: use the 4px spacing rhythm, 28/32/36px controls, compact table rows, and small radius tokens.
• Concrete wrapper choice: page authors choose wrappers by business job, not by appearance. Use tabbed panels for one record family split by state, data tables for scan-and-open lists, search forms for structured filters, status tags for business state, and action bars for executable commands with permission or running state.
• Explicit state: loading, empty, error, no-access, disabled, and success states must tell the administrator what happened and what can be done next.
• Tradeoffs:
  • Prefer reusable wrapper behavior even when local markup could be shorter.
  • Prefer compact panels and grids over editorial storytelling.
  • Prefer neutral surfaces with state hues used only for state.

Visual Language

• Color:
  • Use tokens from src/styles/tokens.css.
  • Primary blue is for navigation focus and primary actions.
  • Success, warning, danger, and info hues are reserved for state labels, alerts, and risk lines.
  • Work surfaces stay neutral: white, muted, quiet, raised, or sunken token surfaces.
• Typography:
  • Use --erp-font-family and --erp-font-size-*.
  • Page titles may use larger sizes; panels, cards, controls, and tables stay compact.
  • Letter spacing stays 0.
• Spacing and layout rhythm:
  • Use --erp-space-*, --erp-work-area-padding, and --erp-work-area-gap.
  • Search forms and table toolbars align on the same compact rhythm.
  • Table density stays compact by default; row height should not grow to carry narrative text.
• Shape, border, and elevation:
  • Default radius is --erp-radius-xs or --erp-radius-sm.
  • Cards and panels use borders, not heavy shadow.
  • Avoid cards inside cards.
• Motion:
  • Keep motion functional: drawer opening, dropdowns, loading indicators, and focus states.
  • Do not add decorative motion to administrator workflows.
• Imagery and iconography:
  • Use Element Plus icons already available in the app for action affordances.
  • Do not rely on decorative imagery to explain operational screens.

Components

• Existing components to reuse:
  • Shell and navigation: ErpAppShell, ErpPageHeader.
  • Domain workspace: ErpDomainAdminView and domain-specific Erp*Workspace.vue wrappers.
  • Data: ErpTabbedDataPanel, ErpDataTable, ErpStatusTag.
  • Forms: ErpSearchForm, ErpEntityForm, ErpLookup, ErpUpload.
  • Actions and details: ErpActionBar, ErpDrawer.
• Wrapper decision rules:
  • ErpPageHeader: required for route-level admin pages. Breadcrumbs identify module and domain; the actions slot holds page-level commands such as create, refresh, export, or open global processing.
  • ErpTabbedDataPanel: use for a single operational list split by order state, inventory facility, accounting close state, approval queue, assignment, or publish state. Do not use it for unrelated datasets or route navigation.
  • ErpDataTable: use for record lists and entity rows that need scanning, pagination, status cells, source state, and a detail drawer. Keep visible columns focused; secondary facts belong in the drawer or support panel.
  • ErpSearchForm: use when filters come from metadata or when the page has three or more structured fields. Use lookups for related entities and keep reset/submit visible.
  • ErpStatusTag: use for business state in rows, queues, tabs, selected-record headers, and compact metrics. Pair state color with text and avoid local color mappings in pages.
  • ErpActionBar: use for executable action groups where enabled count, disabled reason, running state, overflow, and result feedback matter. Header actions are for one page-level command; action bars handle multi-action workflows.
• New or changed components:
  • Add a wrapper only when at least two business pages need the same behavior, state handling, or layout.
  • Do not add wrappers solely for naming convenience.
• Variants and states:
  • Tabbed panels include stable tab id, label, optional count, optional status, loading, disabled, panel actions, dense mode, and an empty state.
  • Tables include loading, empty, unavailable, error, pagination, row details, and status cells.
  • Forms include readonly, disabled, option loading, no-field, and submit feedback states.
  • Actions include enabled count, disabled reason, running state, success, warning, and error messaging.
  • Cards use density with intent: large for first-screen domain measures, medium for normal queue or record groups, small for side-panel rows and action candidates, mini for counters and KPI chips.
• Token and component ownership:
  • src/styles/tokens.css owns product tokens.
  • src/styles/base.css owns global element defaults such as box sizing, body typography, and base surface color.
  • src/styles/element-overrides.css maps Element Plus variables to ERP tokens.
  • src/styles/erp-patterns.css owns reusable ERP layout classes.
  • src/styles/modern.css owns app shell and route-level layout patterns and is imported directly by src/main.ts.
  • src/styles/erp-ui.css is the ERP style entry that imports Element Plus CSS, tokens, base defaults, Element Plus overrides, and ERP patterns.

Accessibility

• Target standard: keyboard-operable admin workflows with readable contrast and visible focus.
• Keyboard and focus behavior:
  • Use Element Plus controls through wrappers to preserve focus management.
  • Drawers and dialogs must have clear titles and a predictable close path.
  • Row detail entry must be reachable through buttons or clickable rows with clear affordance.
• Contrast and readability:
  • State colors must use token pairs for text, background, and border.
  • Compact typography must remain legible at table density.
• Screen-reader semantics:
  • Keep native Element Plus form labels, table headers, breadcrumbs, alerts, and descriptions.
  • Avoid replacing text labels with icon-only controls unless the control has a label.
• Reduced motion and sensory considerations:
  • Keep animations short and functional.
  • Do not communicate state by color alone; pair color with labels.

Responsive Behavior

• Supported breakpoints and devices:
  • Desktop and laptop are primary.
  • Tablet and narrow browser widths must remain usable for search, table scanning, and record detail.
• Layout adaptations:
  • Search forms collapse from four columns to fewer columns, then one column.
  • Side support panels move below the main table when width is limited.
  • Drawers remain the preferred detail surface on desktop; narrow widths should keep content single-column.
• Touch and hover differences:
  • Hover may provide emphasis but cannot be required for core actions.
  • Buttons and menu items must keep stable hit areas from Element Plus sizing tokens.

Interaction States

• Loading:
  • Use table loading, form option loading, action button loading, or skeleton patterns.
  • Loading text should say what record area is loading.
• Empty:
  • Empty states should mention the current filter or missing selection and offer a next action when available.
• Error:
  • Errors should describe the affected area and keep the rest of the page usable.
• Success:
  • Success feedback should be brief and tied to the completed action.
• Disabled:
  • Disabled actions must expose a reason through ErpActionBar or button title/notice.
• Slow or unavailable data:
  • Show state tags or alerts near the affected table, not only at page top.

Content Voice

• Tone: direct, operational, administrator-facing.
• Terminology:
  • Use "工作台", "管理", "记录", "状态", "筛选", "详情", "执行", "授权", "处理".
  • Use domain nouns such as order, product, party, accounting, facility, operations when they match route context.
• Microcopy rules:
  • Page titles describe the domain and task.
  • Button labels use verbs.
  • Empty and error copy should give a next step or explain current limits.
  • Avoid implementation-layer wording in visible page copy.

Implementation Constraints

• Framework and styling system:
  • Vue pages use Element Plus through ERP wrappers and shared classes.
  • Direct Element Plus use is allowed for simple controls only when no ERP wrapper exists.
• Design-token constraints:
  • Use CSS custom properties from src/styles/tokens.css.
  • Do not hard-code colors, spacing, radius, or table density in business pages unless extending a documented pattern.
• Performance constraints:
  • Tables should display a focused set of columns, paginate records, and avoid rendering huge detail blocks inline.
  • ErpDataTable should stay the default for scan-heavy record work; hand-built tables must preserve compact row density, status handling, pagination, and nearby search.
  • Detail-heavy content belongs in drawers.
• Compatibility constraints:
  • Preserve existing route behavior and navigation targets.
  • Documentation changes do not alter runtime behavior.
• Test and screenshot expectations:
  • For UI code changes, run the smallest targeted check plus the app build when practical.
  • For documentation-only updates, run text checks for forbidden expressions and scope drift.

Open Questions

• Which domain workspaces should graduate additional repeated local layouts into new ERP wrappers?
• Should narrow-screen drawer width become tokenized for all detail surfaces?
• Should action severity mapping be centralized for all domain-specific action rows?