# BYLD Wealth — Design Master Index

**Date:** 2026-04-09
**Author:** Vivek Kumar, Head of Engineering
**Purpose:** single source of truth for every BYLD design artifact. If it is not in this index, it does not exist.

This doc is the entry point for the designer (Dharam) and for any engineer who needs to know "where does the visual for X live?". It catalogues everything across Waves 1-3, tokens, brand book, guidelines, demo prototype, deferred items, and open handoff notes.

---

## 1. Brand canon (source of truth for all design decisions)

| File | Purpose | Status |
|---|---|---|
| `.claude/rules/design-system.md` | Canonical brand tokens: gold `#C49A3C`, 5-dot logo, dark CRED-level glassmorphism, Montserrat + DM Sans + Playfair Display + JetBrains Mono | Live |
| `.claude/rules/pricing-partners.md` | Pricing tiers (BYLD One/Edge/Legacy) + partner names (9 total) | Live |
| `design-system/brand-book.html` | Pre-pivot brand book (222 KB, historical) | Preserved, not edited |
| `design-system/brand-book-v2.html` | **Post-pivot canonical brand book** (1,223 lines, 13 sections) | Canonical |
| `design-system/DESIGN-GUIDELINES.md` | Written design guidelines (voice, tone, accessibility, motion, layout) | Canonical |
| `design-system/page-1..9-*.html` | Brand book chapters (colors, typography, spacing, components, screens, theming, accessibility, component states) | Pre-pivot, still authoritative for atomic elements |

`brand-book-v2.html` adds: §0 Pivot Update, §10 Dharam's Three Rules, §11 Component Library Index, §12 State Visualization. This is what Dharam imports into Figma for the component library mirror.

---

## 2. Design tokens — Token Studio v2 (Dharam rule 1)

All token files at `design-system/tokens/`:

| File | Purpose |
|---|---|
| `core.json` | Atomic tokens: 9 color families (gold scale, neutral/dark scale, alpha, success/warning/error/info, lifecycle state, 16-leaf asset palette), 4 typography axes, 16 spacing steps, 8 radii, 9 shadows, 4 backdrop blurs, 6 durations, 5 easings, 8 z-indices |
| `semantic.json` | Semantic tokens that reference core (e.g., `color.brand.primary` → `{core.color.gold.500}`) |
| `component.json` | Component-level tokens (button, card, tab, chat-bubble, drawer, modal, table, badge, input) |
| `themes/dark.json` | Dark theme (default and only Phase 1 theme) |
| `$metadata.json` | Token Studio v2 metadata — defines set load order |
| `$themes.json` | Token Studio v2 themes config |
| `tokens.css` | Compiled CSS variables consumed by all Wave 1-3 HTML prototypes via `_prototype-base.css` |

**~220 token definitions total.** Dharam's workflow: install Figma Token Studio plugin → multi-file import pointing at `design-system/tokens/` → sync Figma Variables → every Figma frame uses the variables, never hardcoded values.

---

## 3. Wave 1 prototypes — Lane G (10 screens + index + shared CSS)

Location: `design-system/prototype-pivot/`

| # | File | Covers |
|---|---|---|
| 0 | `index.html` | Landing page with device-frame previews of all 10 screens |
| 0 | `_prototype-base.css` | Shared component CSS (inherited by Wave 2 + Wave 3 via @import) |
| 1 | `01-mia-landing.html` | Post-KYC first MIA greeting (Trial Day 1) |
| 2 | `02-home-5tab-nav.html` | Home tab + net worth hero + 5-tab bottom nav + MIA peek sheet (**gold-standard visual reference**) |
| 3 | `03-mia-floating-sheet-expanded.html` | MIA drawer 80% expanded, conversational capture in progress |
| 4 | `04-trial-nudge-day5.html` | Day 5 gentle trial nudge + AA revocation preview |
| 5 | `05-free-markets-post-trial.html` | Day 8 FREE_MARKETS state + "AA Access Revoked" notice + upgrade CTA |
| 6 | `06-cams-upload-flow.html` | CAMS CAS upload flow + parser progress + extracted holdings review |
| 7 | `07-investments-tab-taxonomy.html` | Investments tab with 11 asset leaves grouped Listed/Unlisted/Deposits |
| 8 | `08-liabilities-tab-taxonomy.html` | Liabilities tab (Secured + Unsecured) + Insurance Security panel |
| 9 | `09-milestone-tracker.html` | Activation funnel progress (4 of 6 complete, Trial Day 3) |
| 10 | `10-ips-deviation-inline.html` | IPS target-vs-actual per bucket with MIA commentary |

**Wave 1 total: 12 files.** All token-driven, Flexbox/Grid auto-layout, BEM-named.

---

## 4. Wave 2 prototypes — design-wave-2-builder (19 files)

Location: `design-system/prototype-pivot-wave2/`

Deferred items from the Lane G manifest, built in Wave 2:

| # | File | Covers |
|---|---|---|
| — | `index.html` | Wave 2 landing page |
| 1-5 | `pw2-01..05` | Pre-KYC onboarding: splash, permissions, phone entry, OTP verify, name entry |
| 6-9 | `pw2-06..09` | Subscription upgrade flow: tier comparison, payment confirm, success, failed |
| 10 | `pw2-10-risk-profiler-chat.html` | Risk profiler 8 questions as a MIA conversation |
| 11-12 | `pw2-11..12` | MIA Markets-mode drawer + refusal-with-upgrade-CTA |
| 13-15 | `pw2-13..15` | Services tab detail: overview, Ditto insurance booking, Blostem FD booking |
| 16 | `pw2-16-ips-pdf-mockup.html` | IPS PDF visual mockup (single fixed template per decision 7A) |
| 17 | `pw2-17-health-score-detail.html` | BYLD Health Score explainer (5 category breakdown) |
| 18 | `pw2-18-notification-templates.html` | Day 5/6/7 trial nudge email + SMS + push templates |

**Wave 2 total: 19 files.** Same token discipline as Wave 1.

---

## 5. Wave 3 prototypes — design-wave-3-builder (18 files)

Location: `design-system/prototype-pivot-wave3/`

Complete-app coverage screens:

| Tier | Files | Covers |
|---|---|---|
| — | `_wave3-shared.css` | Wave 3 shared component additions |
| Tier 1 — KYC + AA (10 screens) | `pw3-01..10` | KYC PAN entry → verify success/error → Aadhaar entry → OTP → DigiLocker → KYC review success → AA FIP selection → consent grant → fetching progress |
| Tier 2 — MIA conversation states (6 screens) | `pw3-11..16` | Empty conversation, Claude-down error, SEBI refusal, write confirmation card (decision 5A), asset capture flow, goal create flow |
| Tier 3 — Leaf drilldowns (1+ screens) | `pw3-17+` | Mutual Fund leaf drilldown (template for other leaves) |

**Wave 3 total: 18 files.** Inherits Wave 1's `_prototype-base.css` + Wave 3's `_wave3-shared.css`.

---

## 6. Single-file demo prototype — `byld-app-v2.html`

Location: `design-system/demo-app/byld-app-v2.html`

**3,004 lines**, 4 script blocks (matching the pre-pivot `byld-app.html` discipline per CLAUDE.md gotcha), single file, no external JS dependencies. Wires Wave 1 + Wave 2 + Wave 3 screens into a navigable end-to-end demo with:

- 5-tab bottom navigation (Home / Investments / MIA / Liabilities / Do More)
- MIA floating sheet overlay with peek/half/full states
- Demo controls panel (top-right) for switching user state (TRIAL Day 1/5/7 / WEALTH_PAID / FREE_MARKETS) and jumping between screens
- All 5 locked design decisions from PRD §9.5a baked in

**Pre-pivot `byld-app.html`** (22,942 lines, 17 screens) is preserved as historical at `design-system/demo-app/byld-app.html` — do NOT edit it.

---

## 7. Locked design decisions (PRD §9.5a, 2026-04-08)

These 5 decisions are baked into Wave 1/2/3 + byld-app-v2. CEO can override at the 2026-04-09 1:1, otherwise they are the shipping defaults:

| # | Decision | Default |
|---|---|---|
| 1 | Services (5th) tab name | **"Do More"** |
| 2 | Day 8 FREE_MARKETS transition UX | Pre-banner Day 7 (22:00 IST push) + post-modal Day 8 first-open + persistent slim gold bar on Home |
| 3 | MIA's first line on post-KYC landing | **"Hey. I'm MIA. Think of me as the financial analyst you always wished you had. Ready to figure out what you're worth?"** |
| 4 | MIA write-path pattern | **Confirm-before-write** (ProposedWrite → user taps Confirm → second POST commits) |
| 5 | IPS template | **Single fixed template Phase 1** (per-tier customization deferred to Phase 2) |

---

## 8. Deferred to Wave 4 (post-Sprint-1, not blocking)

These items were explicitly NOT built in Waves 1-3 and remain open for Dharam's Figma-first pass:

| # | Item | Priority | Sprint |
|---|---|---|---|
| 1 | Custom icon set for the 16 taxonomy leaves | Medium | Sprint 2 |
| 2 | Lottie / Rive motion files for MIA's 20 Bloom avatar states | Medium | Sprint 2-3 |
| 3 | Chart palette formalization (per asset class, per IPS bucket) | Low | Sprint 3-4 |
| 4 | RTL / Hindi scaffolding (X-PIV-017) | Medium | Sprint 4-6 |
| 5 | App Store + Play Store screenshots (5-10 for submission) | High | Sprint 7 |
| 6 | Marketing landing page at byldwealth.com | Medium | Parallel to Phase 1 |
| 7 | Email template final production HTML | Medium | Sprint 5 |
| 8 | Brand book §6 screens expansion beyond the 10 pivot flows | Low | Sprint 5+ |

---

## 9. Dharam handoff workflow (3 steps)

1. **Install Figma Token Studio plugin** (https://tokens.studio/)
2. **Multi-file import** pointing at `design-system/tokens/` — the plugin auto-loads sets in order via `$metadata.json`. Sync to Figma Variables. BYLD Dark is the default (and only) theme for Phase 1.
3. **Mirror the component library** from `brand-book-v2.html §11` (inspect elements in Chrome DevTools to see exact styles). Use Wave 1 + Wave 2 + Wave 3 HTMLs (open side-by-side with your Figma frames) as visual reference. `byld-app-v2.html` shows flows end-to-end.

---

## 10. File count summary

| Category | Files |
|---|---:|
| Brand canon (rules + brand book v1 + v2 + 9 brand book pages) | 13 |
| Design tokens (7 files in `tokens/`) | 7 |
| Wave 1 prototypes | 12 |
| Wave 2 prototypes | 19 |
| Wave 3 prototypes | 18 |
| Single-file demos (historical + v2) | 2 |
| Design guidelines + this index + deliverables manifest | 3 |
| **Total design surface** | **74 files** |

Plus ~47 production HTML prototype screens across 3 waves covering the full Phase 1 user-facing surface.

---

## 11. Cross-references

- **Engineering spec:** `docs/project-plan/markdown/PHASE1-PRD-v1.1.md` §9, §9.5a, §10, §11, §16
- **Architecture:** `design-system/docs/architecture/MOBILE-ARCHITECTURE.md`
- **Brand rules:** `.claude/rules/design-system.md`, `.claude/rules/pricing-partners.md`
- **Handover packet:** `docs/project-plan/handover/HANDOVER-PACKET-2026-04-09.md` Section A (designer)
- **Live dashboard:** `http://localhost:8766/design-system/byld-phase1-review-dashboard.html`

---

**Document version 1.0 | 2026-04-09 | CONFIDENTIAL**
**Prepared by Vivek Kumar, Head of Engineering | BYLD Wealth Management Pvt. Ltd.**
**SEBI RIA: INA000014252 | AMFI ARN: ARN-149832**