# Vue UX Reference Sprint Pattern

Use this reference when improving the JARVIS Finance Vue User Mode from external UX examples without expanding scope or creating license risk.

## Trigger

The user provides external finance/dashboard app references and asks to use them as inspiration only, while preserving the current Vue vertical slice as read-only.

## Required sequence

1. Analyze references first, before coding.
   - Extract UI/UX patterns only: layout, navigation, cards, tables, detail panels, dashboard structure, budgeting/cashflow concepts.
   - Do not copy code, assets, branding, screenshots, text, or implementation specifics.
2. Create a concise reference analysis document under `docs/`.
3. Create a design matrix with:
   - reference
   - useful pattern
   - why relevant
   - MVP yes/no
   - later yes/no
   - concrete JARVIS implementation
4. Derive a small UI design system before component changes:
   - navigation
   - summary cards
   - allocation charts/bars
   - position tables
   - detail drawer
   - load/action bar
   - data-quality badge
   - empty state
   - toast/status pattern if needed
5. Write a text layout sketch and component hierarchy before changing Vue files.
6. Keep v0 strictly read-only:
   - no write actions
   - no admin/raw technical language in User Mode
   - no real data, raw IDs, or secrets in Git/frontend
   - no provider/API calls on normal render
   - Streamlit remains Admin/Fallback if that is the current architecture decision
7. Implement only controlled UX improvements in the current vertical slice:
   - Command Center: KPI cards, allocation, top positions, compact data quality
   - Crypto: position table, row click, detail drawer, wallet split, external CoinGecko link, clear status badges
   - Portfolio/Equity/Wallets/Cash surfaces: read-only grouped overviews, no fake or unfinished controls
8. Park later modules explicitly in the roadmap, not in code:
   - budgeting
   - cashflow planner
   - FIRE/projections
   - goals
   - scenario planning
   - recurring income/expenses
   - watchlist scoring
   - decision journal UI

## Testing and verification pattern

Add/adjust frontend tests to prove:

- normal render does not call backend/provider APIs;
- explicit load button triggers local FastAPI read-model calls;
- Command Center shows allocation and top-position context;
- Crypto row click opens a detail drawer with wallet allocation and read-only copy;
- User Mode pages avoid technical IDs/admin phrasing where practical.

For browser sanity, use the running FastAPI + Vite dev servers and verify:

- after clearing resource timings and reloading, no `/api/` calls happen before explicit user action;
- explicit load renders the expected KPI/allocation/table/drawer content;
- console has no JavaScript errors.

## Final report checklist

Report the following explicitly:

- references analyzed: yes/no
- design matrix created: yes/no
- UI design system derived: yes/no
- patterns directly adopted
- patterns deferred to roadmap
- Vue vertical slice adjusted: yes/no
- Command Center improved: yes/no
- Crypto detail drawer improved: yes/no
- tables/charts improved: yes/no
- no new write actions: confirmed
- no copied external code/assets: confirmed
- tests/build/git-safety results
- commit hash
- push status and remote-hash verification

## Pitfalls

- Do not let UX-reference work become a feature sprint.
- Do not add budgeting/FIRE/forecast features just because reference apps showcase them.
- Do not create a polished-looking but misleading UI with fake buttons or non-working actions.
- Do not expose real portfolio values in chat summaries; report aggregate verification only when possible.
- Do not scan built minified bundles with broad terms such as `TOKEN` without excluding framework/runtime internals; prefer targeted source scans plus build artifact scans for concrete secret patterns.