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