Personal Loan AppFlow — Master Plan & Implementation Status

Last reviewed: June 2026
Audience: Designers, product managers, engineers, AI agents
Purpose: Single source of truth for the gallery implementation of the Personal Loan application flow — what exists today, how tokens and components propagate, what remains, and how to complete a live end-to-end prototype without backend work.

---

Table of contents

1. How this document relates to other docs
2. Executive summary
3. Project scope
4. Environment and architecture
5. Investigated items
6. Step inventory (full audit)
7. Design tokens — how changes apply
8. Components — state and token coverage
9. End-to-end connectivity today
10. Risks and concerns
11. Implementation plan (step-by-step)
12. Validation and maintenance
13. Appendix

---

1. How this document relates to other docs

When production routing changes, update personal-loans-flow.md first, then the registry, then this master plan.

---

2. Executive summary

The Spring Design Library already contains a strong visual prototype of the Personal Loan AppFlow: 22 of 24 steps have authored screen bodies, shared chrome (AppFlowShell), token-backed components from @spring/ds-react, and a flow map with live iframe previews.

Feasibility

Top three gaps blocking a demo narrative

1. Analyzing → outcomes — step 20 has no forward navigation or demo controls.
2. Step 1 landing (start) — no real UI; PlaceholderStep only.
3. Step 21 recovery (complete-skipped-steps) — not built.

---

3. Project scope

In scope

• Live, clickable Personal Loan flow in the design library from landing through terminal outcomes
• Consistent mobile shell: floating bottom CTA, scrollable content, hidden scrollbar
• Token-driven visual consistency across all steps and components
• Demo routing for branches and outcomes without backend APIs
• Flow map + PageMapPopup as visual source-of-truth preview
• Documentation for non-technical stakeholders (token change workflow)

Out of scope

• Production APIs, database, session persistence, analytics
• Real Flinks bank connection, Twilio SMS, or eligibility polling
• Returning customer paths (welcome-back, verify-otp, deeper prepop)
• Full Foundation cross-sell flow (PL declined screen links out only)
• Plan selection step (exists as a component screen but is not in the Personal Loan registry)

---

4. Environment and architecture

Monorepo layout

How a step renders

flowchart LR
  registry[personalLoanFlow.ts] --> route["/library/page/appflow/personal-loan/slug"]
  route --> layout["[slug]/layout.tsx"]
  layout --> shell[AppFlowShell]
  shell --> body[Step Body or PlaceholderStep]
  ds["@spring/ds-react"] --> shell
  ds --> body

Route entry: apps/design-library/src/app/library/page/appflow/personal-loan/[slug]/page.tsx

• If step.Body exists → render screen component
• Else → render PlaceholderStep.tsx (shell CTA advances to next registry step)

URL modes

Gallery root: /library/page/appflow/personal-loan
Step URL pattern: /library/page/appflow/personal-loan/<slug>

Navigation model (prototype)

• Each screen calls router.push() to the next gallery slug on Continue
• No shared application state — data entered on one step is not available on later steps (intentional for design-library prototype)
• Branching is implemented locally via *Options.ts helper files

---

5. Investigated items

Audit performed against the codebase in June 2026. Items reviewed:

Key findings

• Registry and screens are aligned for all steps except start and complete-skipped-steps.
• Linear happy path (name → verify-income → analyzing) is wired with router.push.
• Employment branching matches the UX doc for the common cases.
• Analyzing is a dead end in the gallery — no CTA, no auto-advance, no outcome simulator.
• Verify bank is a dead end — static Flinks mockup by design; no prototype Continue.
• Mobile body layouts are only refined on name and purpose-of-loan; shell provides floating CTA globally.
• Token sync updates all --spring-* consumers; documented literals still bypass sync (see §7).

---

6. Step inventory (full audit)

Gallery URL base: /library/page/appflow/personal-loan/

* Footnote *: when purposeOfLoanVariant === 'false', production skips step 4; gallery always routes loan-amount → purpose-of-loan.

† Footnote † — employment branches (employmentStatusOptions.ts):

‡ Footnote ‡: production may skip verify-address when POA not required; gallery always shows the screen.

CTA pattern reference

---

7. Design tokens — how changes apply

Architecture

flowchart TB
  source[design-tokens.mjs]
  sync["npm run tokens:sync"]
  css[css-variables.css]
  layout["app/layout.tsx import"]
  components["DS components + AppFlow screens"]
  source --> sync --> css --> layout --> components

Global import in apps/design-library/src/app/layout.tsx:

import '@spring/ds-react/tokens/generated/css-variables.css'

Components consume tokens as CSS variables, e.g. var(--spring-semantic-color-text-text-primary, #242621).

---

Step-by-step: for designers and PMs (non-technical)

When a colour, font size, or spacing value changes in the design system:

1. Identify what changed — e.g. primary purple, body text size, card border colour.
2. Request an engineering update — token changes require approval and must be applied in design-tokens.mjs (not in individual screens).
3. Engineer runs sync — they run npm run tokens:sync and restart the preview server.
4. Verify visually — open any AppFlow step (e.g. Name, Loan Purpose) and any component doc page (e.g. TextField, SpringButton). The new values should appear everywhere that uses the token.
5. Understand limits — layout widths (e.g. 630px tile grid), screen copy, and routing are not controlled by tokens. A few error colours and bank tints are still hardcoded (see below).

What updates automatically after sync

• Button colours and sizes
• Input field borders, backgrounds, error states
• Progress bar gradient
• Page title typography (via AppFlowPageTitle token bindings)
• Shell wash and footer styling
• All component doc preview pages

What does not update automatically

• Fixed layout dimensions in screen files (400px form width, 630px grid)
• Screen text/copy
• Icons and illustration assets
• Hardcoded literals listed in the table below

---

Step-by-step: for engineers and AI agents (technical)

1. Get approval for token changes (workflow-contracts.md § Token Change Contract).
2. Edit packages/spring-ds-react/src/components/tokens/design-tokens.mjs.
3. Regenerate artifacts:

   npm run tokens:sync
   

4. Restart the dev server if running (npm run dev).
5. Before production build validation, clear the Next.js cache:

   rm -rf apps/design-library/.next
   npm run build
   

6. Lint:

   npm run lint
   

7. Optional Figma pull (requires .env with FIGMA_TOKEN, FIGMA_FILE_ID):

   npm run tokens:figma
   npm run tokens:sync
   

See also: CONTRIBUTING.md, Design Tokens hub in the running gallery.

Known non-token literals (will NOT auto-update)

Address these in Phase P2 if full token purity is required.

---

8. Components — state and token coverage

All Personal Loan screens import from @spring/ds-react (index.ts).

Component quality gaps

• Error states: not every screen surfaces validation in the UI during normal demo walkthrough (some only on submit).
• Mobile layouts: only name and purpose-of-loan bodies have dedicated max-md: spacing; others use desktop-centric widths inside the mobile shell.
• Disabled states: loan amount disables Continue when invalid; most other steps do not disable the CTA.

---

9. End-to-end connectivity today

What works (gallery demo)

What is incomplete for a full demo

Recommended demo path (today)

1. Open /library/page/appflow/personal-loan/name
2. Click Continue through each step through verify-income
3. Continue to analyzing-application
4. Manually open /library/page/appflow/personal-loan/application-success (or other outcome) from flow map popup or URL bar

---

10. Risks and concerns

---

11. Implementation plan (step-by-step)

Each task includes: owner role, files, acceptance criteria, validation.

---

Phase P0 — Demo-ready end-to-end (must have)

P0-1 — Build step 1 landing screen

P0-2 — Analyzing → outcome demo routing

P0-3 — Verify bank prototype Continue

P0-4 — Manual walkthrough checklist

P0-5 — Automated validation

npm run lint
npm run build

Optional: add one manual browser spec for name → loan-amount → purpose-of-loan chain.

---

Phase P1 — Spec completeness

P1-1 — Build complete-skipped-steps (step 21)

P1-2 — Wire skip/recovery paths

P1-3 — Purpose variant flag

P1-4 — Mobile layout pass (remaining 20 screens)

P1-5 — Promote registry status

---

Phase P2 — Quality and maintainability

P2-1 — Optional demo context

P2-2 — Token literal cleanup

P2-3 — Expand manual QA coverage

P2-4 — Flow map / registry sync

---

12. Validation and maintenance

Pre-PR checklist

Use review-checklist.md. Minimum for AppFlow changes:

• Screen registered in personalLoanFlow.ts with Body, sourcePath, status
• Route resolves at /library/page/appflow/personal-loan/<slug>
• Uses @spring/ds-react components (no raw hex in new code)
• CTA follows shell pattern (§6)
• npm run lint && npm run build pass
• Update this master plan if step status or connectivity changed

How to preview a step

When to update which doc

---

13. Appendix

A. Quick commands

npm install
npm run dev                    # local gallery → http://localhost:3000/library/...
npm run tokens:sync            # after token edits
npm run lint
npm run build

B. Glossary

C. Figma reference

• Application Flow 2026: Figma file
• Key mobile nodes: Name 106-995, Purpose 106-1115
• Key desktop nodes: Purpose 100-778, Credit 88-573, Analyzing 141-3664

D. Demo outcome URLs (after P0-2)

E. Manual walkthrough checklist (P0-4)

• Flow map loads without horizontal clip
• start or name → Continue works on mobile (floating CTA visible)
• Loan purpose: 10 tiles, validation error when empty submit
• Employment: employed → income frequency; no income → home address
• Contact code: OTP accepts 4 digits; phone shown from query
• Financial selector: bank required validation
• Verify bank → verify identity (after P0-3)
• Verify income → analyzing
• Analyzing → each outcome (after P0-2)
• PageMapPopup: mobile + desktop toggle per step
• Token spot-check: change one semantic colour, sync, confirm button updates

F. Investigated file index

apps/design-library/src/gallery/page/appflow/
├── personalLoanFlow.ts          # Registry
├── AppFlowShell.tsx             # Chrome + CTA
├── PersonalLoanFlowChart.tsx    # Flow map
├── PageMapPopup.tsx             # Live preview
├── screens/
│   ├── AppFlow*.tsx             # 22 step bodies
│   ├── PlaceholderStep.tsx      # Fallback
│   └── *Options.ts              # Routing + copy constants
apps/design-library/src/app/library/page/appflow/personal-loan/[slug]/
├── layout.tsx                   # Shell wrapper
└── page.tsx                     # Body vs placeholder
packages/spring-ds-react/src/
├── index.ts                     # Public exports
└── components/tokens/
    ├── design-tokens.mjs        # Token source
    └── generated/css-variables.css
docs/ux/personal-loans-flow.md   # Product spec

---

End of master plan. For questions about agent workflow, see operational-manifesto.md.