# 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.