# Design System Document: Financial Decision-Making Framework

## 1. Overview & Creative North Star

### The Wealth Architect

The goal of this design system is to move beyond the "fintech template" and into
the realm of **The Wealth Architect**. We are not building a simple utility; we
are crafting a digital dossier that feels authoritative, transparent, and
sophisticated.

The "Wealth Architect" aesthetic is defined by **Editorial Precision**. We treat
financial data as high-value content, using aggressive typographic scales
(Manrope) to command attention and functional sans-serifs (Inter) to ensure
technical clarity. We break the rigid, boxed-in grid of traditional banking by
utilizing **Intentional Asymmetry** and **Tonal Layering**. Instead of a flat
interface, we create a sense of depth where information feels like it is resting
on sheets of fine, frosted glass and premium paper.

## 2. Colors: The Success Spectrum

The palette is engineered to evoke psychological stability and the momentum of
growth.

### Core Palette

- **The Growth Engine (Primary):** `#0c5316` (Primary) and `#2a6c2c` (Primary
  Container). These greens are deep and "money-backed," used for positive trends
  and final decision-making actions.
- **The Foundation (Secondary):** `#1860a4` (Secondary) and `#7ab3fd` (Secondary
  Container). These blues represent stability and historical data.
- **The Catalyst (Tertiary):** `#892000` (Tertiary) and `#b22d01` (Tertiary
  Container). Reserved strictly for 'Recommendations' and 'Break-even' points to
  demand immediate ocular attention against the cooler background.

### The "No-Line" Rule & Surface Hierarchy

To achieve a high-end editorial feel, we prohibit the use of 1px solid borders
for sectioning. Structural boundaries must be defined through background shifts
and nested containers:

- **Nesting Logic:** Place a `surface_container_lowest` (#ffffff) card on top of
  a `surface_container_low` (#e6f6ff) section to create a soft, natural lift.
- **The Glass & Gradient Rule:** For hero sections and primary CTAs, use a
  subtle linear gradient from `primary` to `primary_container`. For floating
  "Recommendation" overlays, use a Glassmorphism effect: `surface` color at 70%
  opacity with a `24px` backdrop-blur.

## 3. Typography: The Editorial Voice

We use a dual-typeface system to balance personality with extreme readability.

- **Display & Headlines (Manrope):** Use `display-lg` (3.5rem) and `headline-md`
  (1.75rem) to introduce major data sections. Manrope’s geometric nature feels
  modern and architectural.
- **The Technical Layer (Inter):** All interactive elements, labels, and dense
  data tables use Inter. `body-md` (0.875rem) is our workhorse for data-centric
  content.
- **Hierarchy Note:** Use `on_surface_variant` (#3e4948) for secondary metadata
  to ensure the eye settles first on the primary "Success" figures (rendered in
  `primary` green).

## 4. Elevation & Depth: Tonal Layering

Traditional drop shadows are too "software-generic." We define depth through
light and texture.

- **The Layering Principle:** Depth is achieved by stacking `surface_container`
  tiers.
  - _Base:_ `surface` (#f3faff)
  - _Section:_ `surface_container_low` (#e6f6ff)
  - _Card:_ `surface_container_lowest` (#ffffff)
- **Ambient Shadows:** When a card must float (e.g., a critical recommendation),
  use an extra-diffused shadow:
  `Y: 16px, Blur: 32px, Color: rgba(7, 30, 39, 0.06)`. Note the use of the
  `on_surface` color for the shadow tint to maintain naturalism.
- **The Ghost Border Fallback:** If a boundary is required for accessibility,
  use the `outline_variant` (#bec9c8) at **15% opacity**. Never use a 100%
  opaque border.

## 5. Components: Precision Primitives

### Cards & Data Modules

- **Styling:** No borders. Use `xl` (0.75rem) roundedness for outer containers
  and `md` (0.375rem) for inner elements.
- **Separation:** Forbid the use of divider lines. Use `spacing-6` (2rem) of
  vertical whitespace or a shift to `surface_container_high` (#d5ecf8) to
  separate content blocks.

### Buttons (Action Anchors)

- **Primary:** `primary` (#0c5316) background with `on_primary` text. Use `full`
  roundedness for a modern, pill-shaped silhouette.
- **Secondary:** `secondary_container` (#7ab3fd) with `on_secondary_container`
  (#00457c) text.
- **States:** On hover, shift the background color to the next tier of the color
  scale (e.g., `primary` to `primary_container`).

### Financial Specifics

- **Break-even Markers:** Use `tertiary_fixed` (#ffdbd1) as a background for
  "Break-even" tags to provide a high-contrast visual anchor that differs from
  standard "Success/Fail" patterns.
- **Data Inputs:** Use `surface_container_highest` (#cfe6f2) for the input field
  background with a `Ghost Border` on focus. This creates a "recessed" look that
  feels more premium than a white box.

### Chips & Tags

- **Selection Chips:** Use `secondary_fixed` (#d3e4ff) for inactive states and
  `primary_fixed` (#acf4a4) for active 'Success' states.

## 6. Do’s and Don’ts

### Do

- **Do** use `spacing-8` (2.75rem) or `spacing-10` (3.5rem) to let high-value
  financial figures "breathe."
- **Do** use `display-sm` for large monetary values to give them a "hero" feel.
- **Do** apply `backdrop-blur` to any element that overlaps data to maintain
  context.

### Don't

- **Don't** use pure black (#000000) for text. Always use `on_surface` (#071e27)
  to maintain the sophisticated blue-tinted editorial tone.
- **Don't** use 1px dividers. If you feel you need a line, use a 4px vertical
  block of `primary_fixed` to indicate a "Success" section instead.
- **Don't** use standard "Warning" yellows. In this system, tertiary
  oranges/reds represent critical decision points, not just errors.