# UI Handbook

This handbook defines how business pages in the modern ERP app should use Element Plus through the local ERP wrapper layer. It is the practical companion to `DESIGN.md`.

## Wrapper-First Rule
- Start with `src/components/erp` before composing raw Element Plus controls.
- Use wrappers for shared behavior, state handling, density, labels, and administrator-facing copy.
- Use local page CSS only for page-specific grid placement or one-off domain composition.
- Do not scatter colors, spacing, radius, table density, or state styles across business pages.
- When two pages need the same arrangement, promote it into an ERP wrapper or a class in `src/styles/erp-patterns.css`.

## Style and Token Ownership
- `src/styles/erp-ui.css` is the style entry and imports the ERP design system files.
- `src/styles/tokens.css` owns color, spacing, radius, typography, control height, table height, card density, and shadows.
- `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 and base component styling to ERP tokens.
- `src/styles/erp-patterns.css` owns reusable ERP classes such as forms, panels, cards, metrics, tables, status lines, menus, breadcrumbs, drawers, upload, empty, skeleton, and detail descriptions.
- `src/styles/modern.css` owns the application shell, top menu, left menu, route layout, and existing domain-specific layout patterns, and is imported directly by `src/main.ts`.

Use tokens such as `--erp-space-3`, `--erp-control-height`, `--erp-table-row-height`, `--erp-radius-xs`, `--erp-color-border-soft`, and `--erp-color-surface-quiet` instead of hard-coded values.

## Page Structure
Use this order for business pages:

1. `ErpPageHeader` for module position, domain title, short operational description, and the one primary command for the page.
2. Search or filter area with `ErpSearchForm` when fields come from metadata, or wrapper-owned compact controls when the page only has one or two fixed filters.
3. State summary using metric cards, queue rows, alerts, or `ErpStatusTag` when the state changes what the administrator should inspect next.
4. Main data area with `ErpDataTable` for record lists, remote entity rows, or route-owned rows.
5. Detail entry through the table drawer or `ErpDrawer`; keep long record facts out of inline expanded rows.
6. Secondary executable actions through `ErpActionBar`; use a right-side panel only when actions need supporting context.

For common domain pages, prefer `ErpDomainAdminView` because it already combines header, search, metrics, queue, table, side panel, and detail drawers.

## Component Choice Matrix
| Need | Use | Notes |
| --- | --- | --- |
| Application shell, left menu, top menu | `ErpAppShell` | Do not duplicate global navigation inside pages. |
| Page title and breadcrumbs | `ErpPageHeader` | Use `crumbs` and the actions slot for page-level commands. |
| Domain management page | `ErpDomainAdminView` | Best default for order, product, party, accounting, facility, operations, content, marketing, HR, and similar workspaces. |
| Data listing | `ErpDataTable` | Includes loading, empty, unavailable, error, pagination, sorting, status cells, and detail drawer. |
| Search filters | `ErpSearchForm` | Metadata-driven fields, lookup, option loading, reset and submit. |
| Entity create or edit form | `ErpEntityForm` | Use for submit-oriented fields and disabled state handling. |
| Status label | `ErpStatusTag` | Use for row status, queue state, and record detail status. |
| Action group | `ErpActionBar` | Use for executable actions, disabled reasons, running state, and overflow. |
| Status-grouped data panel | `ErpTabbedDataPanel` | Use when one data panel needs stable tabs, header actions, and table or queue content. |
| Record detail | `ErpDrawer` or table drawer | Prefer drawer over expanding large inline detail blocks. |
| File selection | `ErpUpload` or upload field in `ErpEntityForm` | Keep upload copy and permission behavior consistent. |
| Lookup field | `ErpLookup` through form wrappers | Use for party, product, order, and related entity selection. |

## Tabbed Data Panels
- Use `ErpTabbedDataPanel` when one work area contains the same kind of records split by operational state, queue, or ownership.
- Good fits: sales orders by fulfillment state, procurement requirements by approval state, inventory exceptions by facility, accounting documents by close state, content items by publish state, and work requests by assignment state.
- Keep tabs stable across refreshes. Do not create tabs from every transient filter value; use filters inside the active tab for dates, owner, keyword, and related entity.
- Put `ErpDataTable`, a compact queue list, or a focused review panel in the default slot. Search, pagination, and row details stay owned by that inner content.
- Use `count` when each tab represents a queue size; use `status` when the tab needs a short state label such as Ready, Review, or Processing.
- Use `dense` for secondary panels inside a wider workspace. Leave normal density for the main record panel.
- Use the actions slot for panel-level refresh, assignment, export, create, or batch commands that apply to the active tab. If the action applies to a selected row, keep it in the table row or detail drawer instead.
- Do not use it for whole-page route navigation, decorative tab stacks, or unrelated datasets that do not share columns or workflow.

## Tables
- Use `ErpDataTable` for business records: orders, invoices, payments, requirements, shipments, inventory items, parties, work efforts, requests, content records, system jobs, and entity-backed rows.
- Use the `rows` prop when the page already owns a filtered list. Use `dataSource` when the table should load an entity list and keep the source tag, search, refresh, pagination, and unavailable state together.
- The wrapper displays up to 12 visible data columns and then the fixed action column. If a workflow needs more facts, move secondary facts into the drawer or a support panel instead of widening the table.
- Put status fields through `ErpStatusTag`; `ErpDataTable` already detects status-like column names for standard cells.
- Keep row details in the table drawer unless the page has a domain-specific drawer with stronger record context.
- Use pagination for remote, large, or repeatedly refreshed record sets. Default scan size is 20 rows; 10 is suitable for narrow panels, 50 or 100 for audit-heavy pages.
- Keep table search in the source toolbar for broad keyword search. Use `ErpSearchForm` above the table for structured filters such as party, product, facility, status, date range, and owner.
- Preserve built-in loading, empty, unavailable, and error states. Do not replace the whole page when only one table source fails.
- Use `.erp-table` and `.erp-dense-pagination` only when a wrapper cannot be used, such as a route renderer that supplies specialized table slots.

Table layout rules:
- Primary identifier or name comes first.
- Status and date columns stay visible when possible.
- Amount columns align right.
- Action columns stay narrow and predictable.
- Long secondary values use muted subtext and ellipsis.

Table density rules:
- Main work tables use compact small rows from `ErpDataTable`; this is the default ERP density.
- Dense side tables should show 5-8 rows and avoid multi-line cells.
- Audit or exception tables may show 20-50 rows, but must keep identifier, state, timestamp, owner, and action columns visible.
- Do not increase row height to carry descriptions. Put descriptions in the drawer, a tooltip, or muted subtext under the primary value.
- Keep toolbar, total count, and pagination visible near the table so operators can tell whether they are seeing a filtered subset.

## Search Forms
- Use `ErpSearchForm` when query fields come from screen metadata, entity definitions, adapter blocks, or an action contract.
- Use direct compact controls only for one or two page-local switches such as status, facility, or active tab. Once the page has three or more structured fields, use `ErpSearchForm`.
- Place search forms above the table or inside the domain wrapper's control area. Do not place a full search form inside a table body.
- The wrapper shows up to 16 visible fields. Put the most operational fields first: identifier, status, related party/product/facility, date range, owner, and free text.
- Use `ErpLookup` for related records rather than free text when the domain has a known entity.
- Keep top labels and compact controls. Avoid placeholder-only forms; labels must remain visible.
- Preserve reset and submit behavior. The action row also carries form status such as queryable, submittable, login required, readonly, or processing.
- Put rarely used filters behind a drawer or collapsible panel, but keep the current filter state visible near the table after applying it.

Search form layout:
- Desktop: four compact columns when space allows.
- Medium width: two columns.
- Narrow width and drawers: one column.
- Actions align to the end using `.erp-form-actions`.

## Entity Forms
- Use `ErpEntityForm` for create, edit, and submit-oriented flows.
- Use one column inside drawers and dialogs.
- Use two columns in wider page panels only when fields are short and related.
- Show readonly values with wrapper readonly display, not disabled inputs unless the value belongs in a form control.
- Show disabled reasons near the form or action area.
- Keep submit actions in a stable bottom action row.

## Navigation
- `ErpAppShell` owns top-level navigation and the left menu.
- Business pages should receive navigation context rather than rebuilding it.
- Use `ErpPageHeader` breadcrumbs for page-level location.
- Use `ErpPageHeader` on every route-level admin page, including domain workspaces, entity search pages, and operational consoles.
- Header actions are for page-level commands such as create, refresh, export, or open a global action. Row-specific commands stay in `ErpDataTable`, the drawer, or `ErpActionBar`.
- Keep the page description to one sentence that states the operator's job: which records are managed, which queue is handled, or which state is monitored.
- Use `.erp-side-menu` only for page-local secondary navigation.
- Use `.erp-horizontal-menu` for top-level tabs or route groups inside the shell.
- Top menu items should be short domain labels.
- Left menu groups should be stable and scan-friendly.

Breadcrumb rules:
- First item is the admin workspace or module root.
- Middle items are domain or sub-area.
- Last item is the current page or record label.
- Breadcrumb text should be business-facing and concise.

## Cards, Panels, and Metrics
- Use `.erp-panel` or `.erp-work-area` for framed work sections.
- Use `.erp-card` only for individual repeated items, not for whole page sections.
- Use `.erp-metric-card` for numeric summaries.
- Use density variants deliberately:
  - Large: first-screen domain summaries with a number, short label, and one operational hint, such as open orders, exceptions, value at risk, or jobs running.
  - Medium: normal panel item, queue card, or record group that carries a title, one secondary line, and one status or action.
  - Small: row summary, action candidate, handoff, warning, or compact queue item in a side panel.
  - Mini: numeric counters and short KPI chips inside a header or compact workspace.
- Avoid nested cards.
- Use neutral surfaces; state color belongs on a side border, tag, alert, or icon.
- A card must help an operator compare, choose, or act. If it only wraps text, use a heading, list row, or panel section instead.
- Large cards should be rare on record-heavy pages; use them for the top 3-4 domain measures, then return to tables.
- Medium and small cards may repeat in grids or side panels. Keep their internal text short enough that the grid height remains stable.
- Do not use cards as section containers around `ErpDataTable`, `ErpSearchForm`, or `ErpTabbedDataPanel`; those wrappers already provide the working surface.

## Status, Alerts, and Feedback
- Use `ErpStatusTag` for record, queue, tab, and drawer labels when the value is a business state such as Approved, Review, Created, Processing, Error, Cancelled, Ready, Packed, or equivalent domain wording.
- Use status tags in table cells, queue rows, selected record headers, and compact metric cards. Avoid placing multiple status tags in the page header unless they describe the whole page.
- Keep the source status from the data, then map display labels through the wrapper. Do not invent local color classes for every domain state.
- Use `.erp-state-line` for state rows that need short text plus a state color.
- Use Element Plus alerts with `.erp-status-alert` for warnings or errors that affect a whole panel.
- Pair every color with text.
- Place state messages near the affected control or table.

State expectations:
- Loading: indicate what is loading.
- Empty: explain the current filter or missing selection.
- Error: name the affected area and keep other controls usable.
- Disabled: explain why the action cannot run.
- Success: keep feedback brief and tied to the completed action.

## Dialogs and Drawers
- Use drawers for record details, edit forms, action setup, and side-by-side review.
- Use dialogs for short confirmations or focused blocking decisions.
- Drawer titles must identify the record or action.
- Drawer content should use one-column forms, descriptions, timelines, or action lists.
- Long detail content should be grouped with headings and descriptions.
- Keep primary and secondary actions at the bottom or in a stable action row.
- Use `.erp-drawer`, `.erp-dialog`, and `.erp-detail-descriptions` classes where applicable.

## Upload
- Use `ErpUpload` or the upload field support inside `ErpEntityForm`.
- Keep upload areas compact and connected to the form they affect.
- Show file selection state and any permission note close to the upload control.
- Do not create custom drag areas with local CSS when the shared upload wrapper is enough.
- Use `.erp-upload` for shared upload styling when direct Element Plus upload is unavoidable.

## Actions
- Use `ErpActionBar` for executable business actions returned by a route, adapter block, service contract, or selected record context.
- Use the page header for one page-level primary command. Use `ErpActionBar` when there are multiple executable choices, permission-dependent actions, batch commands, or a need to show why an action cannot run.
- Primary action appears first and uses primary styling. Destructive actions use danger styling and clear labels.
- Normal mode shows up to four primary buttons before overflow. Compact mode shows up to two; use compact mode in side panels, drawers, and secondary consoles.
- The wrapper shows enabled count, disabled reason, running state, success, warning, and error feedback. Do not duplicate that feedback with page-local banners unless the whole panel is affected.
- Disabled actions must expose a reason through the action definition. A disabled button without a reason is not acceptable for administrator workflows.
- Running actions show button loading and should not shift layout.
- Use `.erp-action-stack` and `.erp-action-button` for custom action groups that cannot use `ErpActionBar`.

## Top Menu and Left Menu
- Top menu:
  - Use shell-owned top navigation.
  - Keep labels short and domain-oriented.
  - Active state uses the ERP primary token and a restrained underline.
- Left menu:
  - Use shell-owned left navigation for modules and durable route groups.
  - Use `.erp-side-menu` only for local subnavigation.
  - Keep item height aligned with the 38px menu rhythm.
  - Active state uses primary color and a left border, not a filled pill.

## Empty, Loading, and Error States
- Empty states use Element Plus empty components or `.erp-empty-state`.
- Loading states use wrapper loading behavior, Element Plus loading, or `.erp-skeleton`.
- Error states should not replace the whole page unless the whole page is unusable.
- For tables, keep the toolbar and search visible during failures.
- For forms, preserve entered values when an option load or submit action fails.

## Responsive Layout
- Use CSS grid and wrappers that can collapse cleanly.
- Search forms should move from four columns to two and then one.
- Metrics should wrap instead of shrinking text below readable size.
- Side panels move below the main table on narrow widths.
- Drawers keep one-column content and readable labels.
- Do not scale font size with viewport width.

## Accessibility and Interaction
- Keep visible focus behavior from Element Plus and token overrides.
- Do not remove native labels from forms or headers from tables.
- Icon-only buttons require accessible labels or tooltips.
- Use buttons for actions and links for navigation.
- Keep hover states helpful but nonessential.
- Do not communicate status by color alone.

## Content Rules
- Write for administrators: short, operational, and specific.
- Use verbs for buttons: search, reset, refresh, create, save, assign, approve, cancel.
- Use nouns for sections: filters, records, details, actions, queue, status.
- Avoid visible implementation wording.
- Avoid promising behavior that the page cannot currently perform.

## Local CSS Rules
- Business pages may add local classes for layout only when no wrapper or pattern exists.
- Local CSS should reference ERP tokens and stay narrowly scoped.
- Do not redefine Element Plus button, input, table, tag, menu, or card styles inside a page.
- Do not add hard-coded state colors in pages.
- If a layout pattern appears in multiple pages, move it into `src/styles/erp-patterns.css` or an ERP wrapper.

## Review Checklist
- Does the page use the right ERP wrapper for shell, header, table, form, status, actions, detail, and upload?
- Are tokens used instead of hard-coded color, spacing, radius, and table density?
- Are search, data table, state labels, action area, detail entry, empty, loading, and error states visible?
- Does the page avoid decorative card stacks and local style drift?
- Is copy business-facing and useful to an administrator?
- Does the page work at desktop, medium, and narrow widths?