Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Mobile Surface System

​

Principles

• One surface pattern per job: list, detail, and form flows should not invent their own layout shells.
• Headers carry context: every screen uses a strong title and an optional subtitle that explains the operational purpose.
• Cards define sections: content lives in framed cards with consistent spacing, typography, and stacking.
• Status is explicit: progress, success, warning, and failure states use the same notice treatment.
• Actions stay predictable: primary actions live at the end of the flow and related quick actions group together.

​

Shared Primitives

​

Collection flows

• CollectionSurface.tsx
• CollectionScreen
• CollectionCard
• CollectionActionRow
• CollectionEmptyState
• CollectionLoadingState

• contacts, documents, expenses, grantors, journals tab screens
• any browse/select surface with repeated cards

​

Detail flows

• DetailSurface.tsx
• DetailScreen
• DetailCard
• DetailField
• DetailLoadingState

• contact, document, expense, and journal detail routes
• future project, grantor, and approval detail routes

• first card explains the record itself
• later cards capture history, attachments, or related actions
• labels use compact uppercase-style treatment through DetailField

​

Form flows

• FormSurface.tsx
• FormScreen
• FormCard
• FormStatusNotice
• OptionPills

• new contact
• log interaction
• upload document
• new expense
• new journal entry
• auth and account flows that should follow the same mobile operating language

• screen subtitle explains what the submission affects
• each FormCard groups one logical step
• async progress and analysis feedback use FormStatusNotice
• compact selections use OptionPills instead of hand-rolled chips

​

Auth flows

• AuthScreens.tsx
• LoginScreenSurface
• SignupScreenSurface
• ForgotPasswordScreenSurface

• login
• signup
• forgot-password

• auth remains on FormScreen and FormCard so it shares the same spacing, typography, and notice language as other mobile workflows
• secondary navigation uses lightweight text actions instead of inventing separate footer shells
• route files own the async auth logic and navigation, while the shared auth surfaces own presentation

​

Workflow shells

• WorkflowScreens.tsx
• ContactCreateScreenSurface
• ContactInteractionScreenSurface
• DocumentUploadScreenSurface
• ExpenseCaptureScreenSurface
• JournalEntryScreenSurface

• new contact
• log interaction
• upload document
• new expense
• new journal entry

• route files own capture, mutation, and navigation state
• shared workflow surfaces own titles, subtitles, notices, and section order
• regression coverage should target the shared workflow surfaces instead of brittle stateful route modules

​

Migration Rules

• Do not compose new mobile screens from raw Screen + SectionHeader + ad hoc cards when a shared surface exists.
• Prefer CollectionActionRow over local flex rows for clustered actions.
• Prefer DetailField over inline label/value text pairs.
• Prefer FormCard over raw cards for form sections.
• Prefer FormStatusNotice over one-off tinted text blocks.

​

Next Targets

• future edit flows should be built directly on FormScreen or extracted screen-surface components before route logic grows
• richer approval and review flows once they exist in mobile
• image-based mobile visual coverage on top of the current text snapshot lane

​

Verification

• shared surface snapshots live in mobileSurfaceSystem.test.tsx
• route-level snapshots live in mobileRouteScreens.test.tsx
• auth surface snapshots live in authSurfaceSystem.test.tsx
• workflow surface snapshots live in workflowSurfaceSystem.test.tsx
• run npm --workspace @grantmaster/mobile run test:surfaces to verify the shared surface and mobile route baselines
• run npm --workspace functions run generate:router-types whenever backend router contracts change