The wiseinvest-ux-ui-designs repository is organized so design intent mirrors the production DOM tree. Designers work in Markdown and HTML wireframes that line up with real components and routes in the financial-insights app.
High-level layout:
design-system/ — brand, tokens, typography, spacing, components, motionshared/ — global chrome (header, footer, scrollbars, ticker)pages/ — route-aligned surfaces such as home, wealth-dashboard, stock-page, stock, payment, payments, checkout-pro, contactEach designed surface is represented by two primary files:
.md): human-readable documentation of goals, UX flows, visual hierarchy, states, copy, accessibility, and production mappings..html): Tailwind CDN prototype that stacks four variants on one canvas:
Wireframes use semantic HTML and <aside> annotation blocks to capture intent without polluting the visual layout.
pages/home/home.md — explains / goals, section order, vertical rhythm, scroll behavior, and cross-cutting rules.pages/home/ (00-brand-hero, 01-hero, 02-heatmaps, 03-features, 04-testimonials, 05-pricing, 06-faq, 07-wealth-dashboard) each with its own .md and .html.financial-insights/src/pages/Homepage.jsx and src/components/Homepage/* for the live implementation.Two related structures capture stock detail UX:
pages/stock-page/Design.md — high-level stock page system with 12 modular components (header, price chart, WiseInvest score, key statistics, shareholding, analyst ratings, 52-week range, financials, peer comparison, revenue segments, dividends history, ESG scores).pages/stock/ — a more granular UX spec set with separate folders for each major analytical slice:
01-stock-header/02-price-chart/03a-valuation/03b-trading-risk/03c-about/04-financials/05-fundamentals/06-revenue-segments/07-market-sentiment/08-latest-news/09-holdings/10-wiseinvest-score/11-earnings/12-shareholding/13-analyst-ratings/14-dividends-splits/15-technical-analysis/16-index-membership/Each folder contains a spec and wireframe describing how that slice behaves across themes and breakpoints, with changes tracked in the Git history (for example, chart label alignment and watchlist affordances in 01-stock-header and 02-price-chart).
Payment-related UX is captured in multiple, related specs:
pages/payment/payment.md — payment entry surface(s) from marketing or in-app.pages/payments/payments.md — broader payments area design, plans, billing states.pages/payments/checkout/checkout.md — Stripe-inspired checkout and card entry flow.pages/checkout-pro/checkout.md — advanced or alternative checkout variant.These designs map to subscription and billing components in the production app and are expected to consume tokens from design-system/.
00-, 01-, 02-, etc.) to encode vertical order and make it obvious where new sections slot in.wealth-dashboard, stock-header, price-chart, dividends-splits) mirroring route or component semantics..md spec and one .html wireframe. Any imagery or screenshots are additives rather than separate spec files.The mapping between this design repo and product behavior follows a few rules:
pages/ directories (home, wealth-dashboard, stock-page, stock, payment, payments, checkout-pro, contact) correspond to high-level routes in the financial-insights app.01-hero, 02-heatmaps, 07-wealth-dashboard, 01-stock-header, 02-price-chart map to named React components under src/components/, as documented in specs such as pages/home/home.md.shared/ (header, footer, scrollbars, ticker) map to components imported by many screens to keep the chrome synchronized.Specs frequently include explicit Production file map tables so engineers can jump from spec to implementation and back.
When designing a new feature or screen:
pages/. Create pages/<route>/ with a top-level <route>.md composition file describing goals, section order, and cross-cutting rules.NN-section-name/ with <section>.md and <section>.html.design-system/. Use tokens and component guidelines from design-system/Design.md, tokens.md, and components-library.md. If you need new tokens, add them there first.financial-insights.shared/ where possible. If a header, footer, or chrome pattern already exists, reference the existing shared design instead of duplicating it.Following these rules keeps designs, implementation, and future documentation aligned as the product grows.