# ForgeFlow ERP UI Optimization Design ## Background ForgeFlow ERP has moved beyond the initial skeleton stage. The frontend now contains 33 Vue views, 29 Vue components, a large global stylesheet, and many business-critical flows across sales, procurement, warehouse, production, quality, finance, returns, permissions, and system extension. The current UI has useful product foundations: workflow navigation, table controls, status badges, drawers, pagination, searchable selects, formal document flows, and PDF archive interactions. The main problem is not a lack of UI, but drift: multiple visual eras coexist, page-level styles override shared components, and high-value ERP workflows are hard to polish consistently. ## Confirmed Product Direction The product register is `product`. The desired brand personality is modern, clear, and easy to adopt. Routine ERP pages should feel calm, precise, and work-focused. They should avoid obvious AI-generated visual patterns, decorative SaaS tropes, heavy dark dashboard aesthetics, and paper styling outside formal business documents. Accessibility defaults to WCAG AA, keyboard-friendly interaction, readable Chinese text, reduced-motion support, and non-color-only status communication. ## Current Findings ### Design Governance - `PRODUCT.md` and `DESIGN.md` were missing and are now created. - The project now has `.impeccable/design.json` for tooling metadata. - Live mode is configured through `.impeccable/live/config.json`. ### Code And Styling Scale - `frontend/src/styles/main.css` has about 17,322 lines. - `frontend/src/views/InventoryLedgerView.vue` has about 7,119 lines. - Other large files include `PurchaseOrderView.vue`, `ProductWorkflowDrawer.vue`, `SalesPlanningView.vue`, and `SystemPermissionView.vue`. - The production build passes, but Vite reports a large JS chunk at about 797 kB and CSS at about 353 kB. ### Visual Drift - The codebase contains an older dark industrial theme and a newer light admin theme. - The light admin theme should become the default for routine ERP screens. - Dark industrial styling should be limited to login or intentionally staged surfaces. - Several pages still contain Element-like colors such as `#409eff`, `#606266`, and `#909399`; these are acceptable only if they are intentionally tokenized. ### Impeccable Detector Warnings The detector currently reports 9 warnings: - Side accent border in `frontend/src/styles/main.css`. - Layout property animation using `transition: width` in `frontend/src/styles/main.css`. - Side accent border in `frontend/src/views/PurchaseOrderView.vue`. - Side accent border in `frontend/src/views/SalesPlanningView.vue`. - Width/height transition in `frontend/src/components/OrgMindMap.vue`. These warnings match the product goal: remove obvious AI-generated tells and reduce janky layout animation. ## Optimization Goals 1. Establish a single routine ERP visual language. 2. Make high-frequency workflows faster to scan and safer to operate. 3. Standardize tables, drawers, forms, buttons, status badges, pagination, empty states, and error states. 4. Reduce global CSS drift and page-level one-off styling. 5. Improve bundle health with route-level code splitting. 6. Keep formal paper/document visuals scoped to business documents and archive flows. ## Phase 1: Design System Baseline ### Scope - `frontend/src/styles/main.css` - `frontend/src/components/ActionButton.vue` - `frontend/src/components/StatusBadge.vue` - `frontend/src/components/PaginationBar.vue` - `frontend/src/components/TableControls.vue` - `frontend/src/components/FormDrawer.vue` - `frontend/src/components/SmartDrawer.vue` - `frontend/src/components/DrawerDataTable.vue` - `frontend/src/components/GlobalSearchableSelect.vue` - `frontend/src/components/StockLotTagSelect.vue` ### Work - Create a small set of canonical CSS tokens for color, radius, shadow, focus, spacing, and z-index. - Keep the light admin theme as the default authenticated app theme. - Remove decorative gradients from routine buttons and cards. - Replace 24px+ routine card radii with 12-14px values. - Remove side accent borders greater than 1px except inside formal document grids where they have document semantics. - Add `prefers-reduced-motion` handling for remaining motion. - Replace width/height transition patterns with non-layout animation or no animation. ### Acceptance - `impeccable detect` warnings for side-tab and layout-transition are resolved or documented as intentional exceptions. - Buttons, form fields, cards, chips, and status badges share tokenized colors and radii. - `npm run build` passes. ## Phase 2: Core Workflow Shell ### Scope - `frontend/src/App.vue` - route navigation and tags view - topbar broadcast and assistant entry ### Work - Simplify topbar hierarchy: breadcrumb/current page first, secondary utilities second. - Make visited tags easier to scan, close, and recover from. - Keep assistant entry as a helper, not a competing primary action. - Improve collapsed sidebar behavior and tooltips. - Remove width animation from shell collapse where it causes layout work. ### Acceptance - Navigation remains clear at expanded, collapsed, and narrow widths. - Current route is visible without relying on a thick side stripe. - Keyboard focus states remain visible. ## Phase 3: Table And Data Interaction System ### Scope - `TableControls` - `DrawerDataTable` - all high-frequency table pages ### Work - Move table enhancement behavior toward declared component APIs rather than DOM patching where possible. - Standardize table density, sticky headers, sort behavior, tooltips, wide mode, and action columns. - Define empty states by page intent: no data, filtered out, no permission, sync pending, load failed. - Define loading skeletons for data regions instead of content-area spinners. - Ensure exported/PDF data never inherits frontend ellipsis behavior. ### Acceptance - Tables on master data, warehouse, purchase, sales, production, and finance pages share the same search, sort, pagination, tooltip, and empty-state vocabulary. - Long business identifiers remain accessible. - Action columns no longer resize unexpectedly. ## Phase 4: Inventory Ledger Refactor ### Scope - `frontend/src/views/InventoryLedgerView.vue` ### Work Split the large view into smaller units: - warehouse selector and summary - inbound/outbound operation launcher - stock lot list - transaction ledger drawer - stocktake dialog integration - document archive actions - operation-specific form sections - composables for warehouse state, filtering, and API calls ### Acceptance - The main view becomes understandable without reading thousands of lines at once. - Each warehouse operation form has consistent validation, loading, success, error, archive failed, and retry states. - Existing warehouse business behavior remains unchanged. ## Phase 5: Formal Document System ### Scope - sales order documents - purchase order documents - warehouse operation documents - quality and production archive flows ### Work - Keep formal document visuals scoped to real business documents. - Extract document paper/grid/signature/archive action components. - Avoid applying paper-like styling to dashboards and routine data tables. - Align list archive state, preview, download, retry, and batch download interactions. ### Acceptance - Document entry and archive screens feel formal and traceable. - Routine ERP pages remain light and product-like. - Archive failure never silently disappears. ## Phase 6: Performance And Build Health ### Scope - `frontend/src/router/index.js` - large views and route imports - global stylesheet ownership ### Work - Convert route components to dynamic imports. - Consider manual chunks only after route splitting. - Move page-specific CSS out of `main.css` where practical. - Keep global CSS for tokens, base layout, and shared components only. ### Acceptance - Initial JS chunk warning is reduced or eliminated. - CSS is easier to attribute to shared vs page-specific concerns. - Build continues to pass. ## First Implementation Slice Start with Phase 1 plus a narrow Phase 4 audit: 1. Fix side accent border and layout transition warnings. 2. Normalize buttons, status badges, and table container tokens. 3. Audit `InventoryLedgerView.vue` for component extraction boundaries without changing business behavior yet. 4. Run `npm run build` and `impeccable detect`. This creates a safer base before touching the largest workflow page. ## Verification - `cd frontend && npm run build` - `node /Users/souplearn/.codex/skills/impeccable/scripts/detect.mjs --json frontend/src/App.vue frontend/src/styles/main.css frontend/src/views frontend/src/components` - Manual browser checks at desktop and narrow widths when browser tooling is available. ## Notes This workspace is not currently a git repository, so this plan does not include commit steps. If the work later moves into a git worktree, commit after each phase.