Finance UI Customization Checklist (Framework-M Native)

Purpose: implement finance screens in a Framework-M/Tamagui-native way, using SVGs only as structure/skeleton references.

Scope and Principles

• Keep Framework-M visual language and theme tokens.
• Do not copy SVG CSS/styling literally.
• Use SVGs only for information architecture:
  • field grouping
  • columns
  • views
  • actions
  • summary blocks
• Build customizability for developers first (config + reusable components), not one-off pages.
• Keep metadata-driven fallback routes working for every DocType.

Definition of Done (Program Level)

• Every finance SVG has a mapped route/workspace in finance frontend.
• Core transaction flows are customizable by config, not hardcoded JSX edits.
• Screen blocks are composed from reusable Tamagui/Framework-M components.
• Existing generic list/form routes still work (/finance/:doctype/list, /finance/:doctype/new, /finance/:doctype/detail/:id).
• Tests validate routes, configs, and critical rendering contracts.
• Developer docs explain how to add/override screens.

Screen Inventory and Mapping

A. Priority (implement first)

• 07-finance-purchase-invoice.svg
  • Target route: /finance/workspace/purchase-invoice
  • Backing doctypes: PurchaseInvoice, InvoiceItem
• 07b-finance-sales-invoice.svg
  • Target route: /finance/workspace/sales-invoice
  • Backing doctypes: SalesInvoice, InvoiceItem
• 08-finance-payment-entry.svg
  • Target route: /finance/workspace/payment-entry
  • Backing doctypes: PaymentVoucher, PaymentReceipt (+ allocation child model if needed)

B. Secondary

• FNA-10-advanced-journal.svg
  • Target route: /finance/workspace/advanced-journal
  • Backing doctypes: JournalEntry, JournalEntryAccount
• 04-finance-gl-view.svg
  • Target route: /finance/workspace/gl-view
  • Backing doctypes: JournalEntry, JournalEntryAccount (report projection)
• FNA-07-bank-reconciliation.svg
  • Target route: /finance/workspace/bank-reconciliation
  • Backing doctypes: BankReconciliation, BankStatement, BankStatementEntry

C. Tertiary

• 09-finance-claims-management.svg
  • Target route: /finance/workspace/claims
  • Backing doctypes: ExpenseClaim, ExpenseClaimDetail
• FNA-06-fixed-asset-register.svg
  • Target route: /finance/workspace/fixed-asset-register
  • Backing doctypes: Asset, AssetMovement, DepreciationSchedule
• FNA-05-emd-register.svg
  • Target route: /finance/workspace/emd-register
  • Backing doctypes: EMDReceipt, EMDRefund
• 10-finance-imprest-requisition.svg
  • Target route: /finance/workspace/imprest-requisition
  • Backing doctypes: m_imprest integration
• 08a-finance-outgoing-payment.svg
  • Target route: /finance/workspace/outgoing-payment
  • Backing doctypes: PaymentVoucher
• 08b-finance-incoming-payment.svg
  • Target route: /finance/workspace/incoming-payment
  • Backing doctypes: PaymentReceipt
• FNA-09-stock-reconciliation.svg
  • Target route: /finance/workspace/stock-reconciliation
  • Backing doctypes: WMS + Finance integration
• 06-finance-dashboard.svg
  • Target route: /finance/dashboard
  • Backing: aggregated projections

Phase 0: Customization Foundation (must complete before screen work)

0.1 Config and Blueprint Contracts

• Create finance UI blueprint types:
  • header context
  • form sections
  • table column model
  • summary card model
  • action bar model
  • adapter badge/status model
• Create a registry for screen blueprints.
• Support per-screen override layering:
  • base framework config
  • finance base config
  • regional/adapter-specific overlay

0.2 Reusable Component Layer

• Create reusable workspace building blocks using @framework-m/ui primitives:
  • FinanceWorkspaceShell
  • FinanceHeaderContext
  • FinanceSectionedForm
  • FinanceGridPanel
  • FinanceSummaryPanel
  • FinanceActionBar
• Ensure all components are theme-token driven (no hardcoded visual style from SVGs).

0.3 Runtime Hooks and Config Glue

• Integrate with registerConfig for form/list overrides.
• Integrate with registerView and setDocTypeViews where custom views are needed.
• Add helper hooks for computed display fields and summary calculations.
• Keep generic FormView/ListView fallback routes untouched.

0.4 Quality Gates

• Type-safe config validation for blueprint objects.
• Route contract tests updated for new workspace routes.
• Story/demo page for shared components.

Phase 1: Purchase Invoice Workspace (first implementation slice)

1.1 Screen Skeleton Mapping

• Define sections from SVG skeleton:
  • vendor identity block
  • statutory/GST context block
  • line grid block
  • totals summary block
• Map each section to model fields.

1.2 Form and Grid Customization

• Configure field order/grouping for PurchaseInvoice.
• Configure child-grid columns for InvoiceItem relevant to purchase flow.
• Expose GST/TDS fields prominently.
• Add computed totals panel from document values.

1.3 UX Actions (Framework Style)

• Add action bar slots (example: verify/match/recompute) without changing framework theme.
• Add adapter status strip driven by real metadata/state.

1.4 Validation

• Add route-level render test.
• Add config contract test for required fields/columns.
• Manual walkthrough checklist completed.

Phase 2: Sales Invoice Workspace

• Build sales invoice workspace using same reusable shell.
• Place GST/e-invoice context in top summary section.
• Add SAC/IGST-centric grid defaults.
• Add totals and tax summary panel.
• Add tests and manual walkthrough.

Phase 3: Payment Entry Workspace

• Build settlement workspace for AP payment entry.
• Support outstanding vs settlement vs net disbursed columns.
• Add statutory deduction indicators (TDS context).
• Add action bar for matching/validation operations.
• Add tests and manual walkthrough.

Phase 4: Journal and GL Workspaces

• Advanced Journal workspace (JournalEntry, JournalEntryAccount).
• GL view workspace with filtering/sorting presets.
• Compare/export action integration (framework-native actions).
• Tests for critical columns and route availability.

Phase 5: Bank Reconciliation Workspace

• Build side-by-side bank-vs-ledger panel layout.
• Add matching actions and summary variance panel.
• Support unmatched queues and exception highlighting.
• Add tests for matching workflow entry points.

Phase 6: Claims, Assets, EMD

• Claims management workspace.
• Fixed asset register workspace with depreciation view.
• EMD register workspace with verification checklist block.
• Add route, config, and rendering tests.

Phase 7: Dashboard and Cross-Module Views

• Upgrade finance dashboard to KPI + compliance feed layout.
• Add plug-in slots for module widgets (claims, reconciliation, statutory alerts).
• Add stock reconciliation integration touchpoint with WMS data.

Phase 8: Developer Customizability Hardening

8.1 Public Extension API

• Publish registerFinanceScreenBlueprint(...) helper.
• Publish overrideFinanceScreenBlueprint(...) helper.
• Publish typed extension docs with examples.

8.2 Developer Experience

• Add one “new screen in 10 steps” guide.
• Add one “override existing screen without forking” guide.
• Add troubleshooting section for route/meta/config mismatches.

8.3 Backward Compatibility

• Validate existing metadata routes remain functional.
• Ensure no breaking changes for existing menu routes.

Phase 9: Data/Model Gap Backlog (track while implementing)

• Identify fields shown in screen skeleton but missing in doctypes.
• For each missing field, classify:
  • UI-only computed field
  • persisted field in existing doctype
  • child table requirement
  • projection/report requirement
• Implement minimal model changes with tests before enabling dependent UI blocks.

Test Checklist (Run on Every Slice)

• libs/finance tests pass.
• Route contract tests pass (m routes integration checks).
• New frontend routes compile.
• Blueprint/config unit tests pass.
• Manual smoke checks for modified workspaces pass.

Manual Smoke Template (copy per screen)

• Route opens without errors.
• Header context reflects screen intent.
• Form fields appear in expected groups/order.
• Grid columns match expected skeleton information.
• Summary panel totals are correct for test data.
• Action bar buttons reflect status and permissions.
• Save/submit flow still uses Framework-M behavior.

Implementation Order (Strict)

• Step 1: Phase 0 foundation
• Step 2: Phase 1 purchase invoice
• Step 3: Phase 2 sales invoice
• Step 4: Phase 3 payment entry
• Step 5: Phase 4 journal + GL
• Step 6: Phase 5 bank reconciliation
• Step 7: Phase 6 claims/assets/EMD
• Step 8: Phase 7 dashboard and integrations
• Step 9: Phase 8 developer hardening
• Step 10: Program-level DoD sign-off

Change Log

• v0.1 checklist created
• v0.2 routes and blueprint contracts finalized
• v0.3 first 3 workspaces completed
• v1.0 finance customization baseline complete