ForgeFlow-ERP/docs/superpowers/specs/2026-06-12-forgeflow-erp-ui-optimization-design.md

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.