` or generic class (`.wrapper`, `.inner`, `.container`) is a review rejection --- ## 1. What the 2026-04-08 pivot changed in the design system The pivot to freemium + MIA-first + 16-leaf taxonomy introduced five new design patterns. Everything downstream (brand book, prototypes, guidelines) flows from these. 1. **Five lifecycle states.** The user now has a flag — `TRIAL`, `WEALTH_PAID`, `FREE_MARKETS`, `CHURNED`, `ERASED` — that changes which screens are visible, which MIA is on duty, and what copy appears where. Every state has a color cue (`tokens/core.json → color.state.*`), a badge variant, and a Home treatment. See `brand-book-v2.html` §12 and LLD-IDENTITY §0. 2. **5-tab bottom navigation.** Home · Investments · MIA (centre) · Liabilities · Services. The MIA tab is raised 16px above the rest so the Neural Bloom avatar floats over the tab bar edge. All 5 tabs are visible during trial; after trial, advisory tabs go read-only for FREE_MARKETS. Component: `.byld-tabbar`. 3. **MIA floating sheet pattern.** MIA is not a page. She is a drawer that peeks 92px from the bottom of every screen (`.mia-drawer--peek`) and expands to 80% viewport on tap (`.mia-drawer--expanded`). This is the single most important pattern in the pivot. 4. **Day 5 / 6 / 7 escalating trial nudges.** A gold-tinted card (`.trial-banner`) that explains the AA data-revocation consequence honestly. Escalates across three days. Not a dark pattern — the alternative is a surprise-charge feel. 5. **16-leaf asset/liability taxonomy visualization.** The canonical tree (Assets → Listed / Unlisted / Deposits; Security → Insurance; Liabilities → Secured / UnSecured) drives every holdings view. Each leaf has a dedicated accent color in `tokens/core.json → color.asset-leaf`. Component: `.byld-card--leaf` + `.leaf-swatch--*`. --- ## 2. Brand fundamentals - **Name:** BYLD Wealth (Advisory mode) / BYLD Markets (Distribution mode). Same app binary, mode depends on user state. - **Logo:** 5-dot grid, 2 columns × 3 rows. Top-right position empty. Bottom-left dot is gold (`var(--brand-primary)`). Never alter the construction. - **Mascot:** MIA — My Intelligent Analyst. Rendered in Neural Bloom style. Same character in both modes; her voice changes with the user's flag. - **Aesthetic:** CRED-level dark. Premium. Glassmorphism. Gold accent. Never playful, never chatbot-cute. --- ## 3. Voice and tone ### MIA — Wealth mode (TRIAL, WEALTH_PAID) Analyst. Direct. Numerate. Specific. Uses SEBI/AMFI terminology correctly. Never flatters, never over-celebrates. - **Do:** "Your equity is 58% of assets — that's 8 points above your IPS target of 50%. I'd suggest trimming HDFC Bank (12% single-name concentration, IPS limit 10%)." - **Do:** "You have ₹4.2L available in FD rollover this week. Do you want me to show you laddering options?" - **Don't:** "Great question!", "Hi there!", "Awesome!", "Let me help you with that." - **Don't:** Use emoji except as a status cue (online/offline dot). ### MIA — Markets mode (FREE_MARKETS) Analyst who does distribution, not advisory. She can help you buy an MF or book an FD, but she cannot recommend. Every reply that mentions an allocation must include: "This is transactional assistance, not advice. Consider subscribing to BYLD Wealth for fee-only advisory." ### System copy (buttons, toasts, errors) - Short. Command form or declarative fragment. - "Start 7-day trial" not "Click here to start your trial" - "Account Aggregator access ended" not "Oh no, we had to end your AA access" --- ## 4. Color principles - **Gold is the only brand hue.** Everything else is neutral, feedback, or a taxonomy accent. No secondary brand color exists in Phase 1. - **Dark neutrals are tuned, not generic.** `color.neutral.950` is the page base; `900` is card; `800` is raised; `700` is overlay. Do not invent intermediate values. - **Feedback colors are restrained.** Success is emerald, warning is amber, error is deep red, info is blue. All four are used at ~30% alpha for backgrounds and 100% for text/accents. - **Finance colors are semantic.** Gain = success; loss = error; neutral = muted. Never invert. - **Taxonomy colors are categorical.** Each of the 16 leaves has a dedicated accent. Use them for cards, chart segments, and MIA reply bullets — never for generic UI chrome. - **Alpha whites for glass.** `alpha.white-04` for card fill, `alpha.white-06` for border, `alpha.white-08` for raised. Pair with `blur-md` or `blur-lg`. **Do:** `background: var(--surface-glass); border: 1px solid var(--border-default); backdrop-filter: var(--blur-md);` **Don't:** `background: rgba(255,255,255,0.05); border: 1px solid rgba(255,255,255,0.1);` --- ## 5. Typography principles Four fonts, each with a clearly-defined job. From the Brand Evolution v2 decision (CEO 2026-03-17). | Role | Font | When | |------|------|------| | Display | Playfair Display | Onboarding hero, brand moments only | | Heading | Montserrat | All UI headings, labels, buttons | | Body | DM Sans | Paragraphs, list items, description text | | Data | JetBrains Mono | Every financial number in the product. No exceptions. | - **Size scale is the only allowed ladder.** `xs` → `7xl` from `tokens/core.json`. No invented sizes. - **Weight is semantic.** `regular` = body, `medium` = data + labels, `semibold` = headings, `bold` = H1/H2 + brand moments. - **Letter spacing matters on all-caps.** Use `letter-spacing.wider` (0.08em) on `overline` and all-caps tags. - **Line height is tied to size.** `tight` for display, `snug` for headings, `relaxed` for body, `loose` for long-form MIA chat. **Do:** `font-family: var(--font-mono); font-size: var(--font-size-6xl); font-weight: var(--font-weight-medium);` (net worth) **Don't:** Render financial numbers in DM Sans. Never. --- ## 6. Spacing rules (8px grid) - **Grid:** 8px base. Allowed values from the `spacing.*` scale: 0, 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96. Any other value is wrong. - **Component padding:** use semantic `padding.xs / sm / md / lg / xl`. Default card padding is `padding.md` (16px). - **Component gaps:** use semantic `gap.xs / sm / md / lg / xl`. Default is `gap.md` (12px). - **Page gutter:** 16px on mobile, 24px on tablet+. Use `--page-gutter`. - **Section gap:** 32px between major page sections. Use `--section-gap`. **Do:** ```css .home-dashboard { display: flex; flex-direction: column; gap: var(--section-gap); padding: var(--padding-md) var(--page-gutter); } ``` **Don't:** ```css .home-dashboard > *:not(:last-child) { margin-bottom: 28px; } ``` --- ## 7. Layout rules — auto-layout-first Rule 2 is absolute. The only cases where absolute positioning is allowed are: - **Sticky bars:** the 5-tab bottom nav (position: sticky) - **Drawers:** the MIA floating sheet at the bottom of the screen (position: absolute relative to the phone frame) - **Modals:** full-screen overlays (position: fixed) - **Scrims:** full-screen backdrops behind modals (position: fixed; inset: 0) - **The noise overlay:** the SVG texture that sits above all content (position: fixed; inset: 0; pointer-events: none) Everything else — every card, every row, every chat bubble, every button row — must be auto-layout. ### Responsive breakpoints Phase 1 is mobile-first. Breakpoints: | Breakpoint | Width | Notes | |------------|-------|-------| | Mobile | < 768px | Primary Phase 1 target — 360-414px viewport | | Tablet | 768-1279px | Graceful fallback; not designed for | | Desktop | ≥ 1280px | Not supported in Phase 1 (brand book is desktop-friendly but the app is mobile-only) | --- ## 8. Component library usage Every reusable piece is documented in `brand-book-v2.html §11` and tokenized in `tokens/component.json`. Before creating a new component: 1. Check the library — does it exist already? 2. If it exists but needs a variant, add a BEM modifier (`.byld-card--my-variant`). 3. If it doesn't exist, propose it in `component.json` with tokens referencing semantic values, then add it to `tokens.css`, then document it in `brand-book-v2.html §11`. In that order. 4. Never define a component inline in a page. Every screen references library components. --- ## 9. State visualization — freemium lifecycle The 5 states are the load-bearing structural innovation of the pivot. Every screen must make the current state legible. | State | Color | Badge | Home treatment | |-------|-------|-------|----------------| | **TRIAL** | `color.state.trial` (gold) | "Trial · Day N" | Full dashboard + trial countdown in app bar + Day 5/6/7 escalating banner | | **WEALTH_PAID** | `color.state.wealth-paid` (bright gold) | "BYLD One/Edge/Legacy" | Full dashboard, no banner | | **FREE_MARKETS** | `color.state.free-markets` (muted olive) | "Markets only" | Markets-only dashboard + "AA Access Revoked" notice + CAMS upload CTA | | **CHURNED** | `color.state.churned` (muted neutral) | "Churned" | Markets-only + re-engagement card | | **ERASED** | `color.state.erased` (deep muted) | "Erased" | Final-confirmation screen only | The badge appears in the app bar on every screen. The state color bar appears on Home under the net worth hero. --- ## 10. Accessibility (WCAG 2.1 AA — Phase 1 NFR) - **Contrast:** body text on surface ≥ 4.5:1; headings ≥ 3:1; icons ≥ 3:1. - **Touch targets:** minimum 44×44 (`size.control.md`). This is the default control height. - **Focus visible:** every interactive element has a focus ring. Gold at 3px with 2px offset. - **Motion:** respect `prefers-reduced-motion`. The MIA bloom breathe animation pauses. - **Text scaling:** layout must not break at 200% text zoom. Use `rem` where feasible (`tokens.css` uses `px` for tooling compatibility but every prototype sets a 16px root). - **Screen reader:** every icon has an `aria-label`; every button has a text accessible name; the MIA avatar carries `role="img"` with an aria-label of "MIA is online". - **Color is not the only signal:** gain/loss uses ▲ and ▼ arrows AND green/red; never green/red alone. **Do:** White text (`--text-default`) on neutral-900 (`--surface-card`) — 17.6:1 **Don't:** Muted text (`--text-subtle`, neutral-400) on glass (`--surface-glass`) — 3.1:1 fails AA body --- ## 11. Motion - **Durations:** `duration.fast` (150ms) for hover; `duration.base` (250ms) for default UI; `duration.slow` (400ms) for drawer/modal; `duration.slower` (600ms) for page transitions; `duration.ambient` (2500ms) for the MIA breathe loop. - **Easings:** `easing.ease-out` for exits; `easing.ease-in-out` for drawers/sheets; `easing.spring` sparingly for first-use delight moments (onboarding confirmation). - **Never:** jitter, bounce on every interaction, overshoot on common UI. Motion is confident, not busy. --- ## 12. Dark theme only — Phase 1 There is no light-mode toggle in Phase 1. The `tokens/themes/dark.json` file is the only theme. All prototypes, the brand book, and the design system are dark-first. This is a brand decision (CRED-level aesthetic as trust signal for HNI segment) and a scope decision (no duplicate work for a second theme in Phase 1). --- ## 13. Figma handoff rules Dharam's workflow for picking up from this design system: 1. **Install Token Studio** (Figma plugin, free tier). 2. **Import tokens** from `design-system/tokens/` — point at the folder; Token Studio will auto-load `core.json`, `semantic.json`, `component.json`, `themes/dark.json` using `$metadata.json` and `$themes.json`. 3. **Sync to Figma Variables** — in Token Studio, click "Sync". This creates Figma Variables in collections matching the token sets. 4. **Pick a screen** from `design-system/prototype-pivot/*.html` — open in a browser, inspect the layer structure, mirror it in Figma using the component library from brand-book-v2 §11. 5. **Name layers to match HTML classes** — `.mia-drawer` in HTML is a frame named `mia-drawer` in Figma. `.mia-drawer__header` is a nested frame named `mia-drawer__header`. This is non-negotiable. 6. **Use Figma Auto Layout** on every frame — never free-position children. 7. **Export back to code** by sharing the Figma URL in the PR; engineers replicate the frame in HTML using the same token references. --- ## 14. Next steps (what is NOT yet tokenized) Out of scope for the 2026-04-08 pivot pass: - **Illustrations and iconography.** The 16-leaf accent colors are defined but the icons themselves are placeholder. Dharam + illustrator to commission a custom 16-icon set in a later pass. - **Motion tokens for Lottie / Rive.** MIA Bloom states (20 defined in `mia-bloom-states.json`) are not yet tokenized as motion primitives. - **Charts.** The chart color palette (line, bar, donut, heatmap) inherits from the 16-leaf palette but has not been formalized. - **Email + SMS templates.** Transactional templates are Phase 1 scope but are not in this token pass. They come next. --- ## Appendix A — Token reference quick-card | Need | Token | CSS var | |------|-------|---------| | Primary gold | `semantic.color.brand.primary` | `--brand-primary` | | Page background | `semantic.color.surface.page` | `--surface-page` | | Card background | `semantic.color.surface.glass` | `--surface-glass` | | Default text | `semantic.color.text.default` | `--text-default` | | Muted text | `semantic.color.text.muted` | `--text-muted` | | Border | `semantic.color.border.default` | `--border-default` | | H1 | `semantic.typography.heading-h1` | `--font-heading` + `--font-size-5xl` | | Body | `semantic.typography.body-default` | `--font-body` + `--font-size-md` | | Data hero | `semantic.typography.data-hero` | `--font-mono` + `--font-size-6xl` | | Card padding | `semantic.spacing.component.padding.md` | `--padding-md` | | Section gap | `semantic.spacing.layout.section-gap` | `--section-gap` | | Card radius | `semantic.radius.card` | `--radius-card` | | CTA glow | `semantic.elevation.cta` | `--elevation-cta` | | Drawer blur | `core.backdrop-blur.lg` | `--blur-lg` | | UI motion | `semantic.motion.ui` | `--motion-ui` |