Design Guidelines

This document defines the shared component patterns and conventions for all pages on the Giles Finances site. All new pages and updates must follow these guidelines.

Colour Tokens

Token	Value	Usage
Primary	`#475569`	Headers, card borders, chart primary, links
Accent / Gold	`#b8860b`	Highlights, progress bars, hover states
Success	`#15803d`	✅ statuses, positive indicators
Warning	`#b45309`	⚠️ caution states
Danger	`#dc2626`	🔴 alerts, negative drift
Muted	`#94a3b8`	Secondary text, subtle chart lines
Card BG	`var(--md-code-bg-color, #f8f9fa)`	Card/panel backgrounds
Border	`#e2e8f0`	Card borders, dividers

Rule: Never use raw hex in inline styles. Use these tokens (or CSS variables defined in extra.css).

Shared Components

All components are defined in overrides/extra.css. Use the class names below — do not create page-specific CSS.

Stats Card (`.stat-card`)

A bordered card showing a single metric with label.

<div class="stat-card">
  <div class="stat-value">$5.5M</div>
  <div class="stat-label">Liquid Net Worth</div>
</div>

Variants:

.stat-card--success — green left border
.stat-card--warning — amber left border
.stat-card--danger — red left border

Stats Grid (`.stats-grid`)

Auto-flowing grid for multiple stat cards.

<div class="stats-grid">
  <div class="stat-card">...</div>
  <div class="stat-card">...</div>
</div>

Progress Bar (`.progress-track` + `.progress-bar`)

<div class="progress-track">
  <div class="progress-bar" style="width: 36%"></div>
</div>

Note/Callout (`.callout`)

Highlighted block with left border.

<div class="callout">Loading live market data…</div>

Goal Progress Row (`.goal-list` + `.goal-row`)

Horizontal row showing label, progress bar, numbers, and status. Used for FIRE targets on homepage, current-plan, and snapshots.

<div class="goal-list">
  <div class="goal-row">
    <div class="goal-label">Retirement<br><span class="goal-label-sub">$200K/yr at 4%</span></div>
    <div class="goal-bar-wrap"><div class="goal-bar goal-bar--success" style="width: 100%"></div></div>
    <div class="goal-numbers">$5.5M / $5M</div>
    <div class="goal-status">✅</div>
  </div>
</div>

Bar variants: --success (green, funded), --warning (amber gradient, on track), --danger (red, at risk).

Progress logic: - Retirement: current liquid / $5M target - University, Homes: "Funded" if drawdown timeline shows portfolio covers it at target year - Legacy / Grand: current liquid / $15.2M grand target (partial bar)

<div class="timeline">
  <div class="milestone">
    <div class="milestone-marker">✅</div>
    <div class="milestone-content">
      <p class="milestone-title">Financial Independence (2026)</p>
      <p class="milestone-sub">Jonathan 41 • Julia 40</p>
    </div>
  </div>
</div>

Task List (compact action items)

Single-line items with priority dots. Much more compact than info-cards — use for action-items.md and any task/checklist page.

<div class="task-list">
  <div class="task-item">
    <span class="task-dot task-dot--danger"></span>
    <div class="task-content">
      <p class="task-title">Task title here</p>
      <p class="task-detail">Brief detail or context. <a href="...">Link</a></p>
    </div>
    <span class="task-badge task-badge--danger">High</span>
  </div>
  <div class="task-item">
    <span class="task-dot task-dot--success"></span>
    <div class="task-content">
      <p class="task-title task-title--done">Completed task</p>
      <p class="task-detail">Date completed</p>
    </div>
    <span class="task-badge task-badge--success">Done</span>
  </div>
</div>

Variants:

Dots: task-dot--danger (red), task-dot--warning (amber), task-dot--success (green), task-dot--muted (grey)
Badges: task-badge--danger, task-badge--warning, task-badge--success, task-badge--muted
Completed titles: add task-title--done class for strikethrough

Chart Conventions (Chart.js)

CDN: https://cdn.jsdelivr.net/npm/chart.js@4
Primary line/bar colour: #475569 (slate)
Secondary line colour: #b8860b (gold)
Tertiary/muted line: #94a3b8
Line width: 2.5px for all primary lines
Point radius: 0 (no dots)
Tension: 0.3
Fill: subtle (opacity 0.08)
Tooltips: formatted as $X.XXM or $XK as appropriate
Container: <div style="width: 100%; height: 450px;"> wrapping a <canvas>
Responsive: responsive: true, maintainAspectRatio: false

Page Layout Rules

Max width: Let MkDocs Material handle it (content container is ~1220px)
No page-specific <style> blocks — all CSS goes in extra.css
Spacing: Blank line after every heading, before every table/list

Tables vs Cards — When to Use Which

Use cards when…	Use tables when…
Each row is a distinct "item" (goal, task, event)	Data is genuinely comparative (fund A vs B vs C)
Only 2-4 fields per item	5+ columns of numeric data
Items have a status/priority	Rows are meant to be scanned left-to-right
Content varies in length per row	Content is uniform and compact
The page is a dashboard	The page is reference/archival

Examples: - ✅ Cards: goals, action items, calendar events, milestones - ✅ Tables: vesting schedules, fund breakdowns, rebalance monitor, annual summaries

Info Card (`.info-card`)

A horizontal card for list items (tasks, events, goals) with status border and optional badge.

<div class="info-card info-card--danger">
  <p class="info-card-title">Task name <span class="badge badge--danger">High</span></p>
  <p class="info-card-meta">Owner: Jonathan · Notes here · Source link</p>
</div>

Variants: --success, --warning, --danger, --muted

Badge (`.badge`)

Inline status pill.

<span class="badge badge--success">Done</span>
<span class="badge badge--warning">Medium</span>
<span class="badge badge--danger">High</span>
<span class="badge badge--muted">TBD</span>

Status Indicators

Use emoji for inline status:

🟢 On track / <3% drift
🟡 Watch / 3-5% drift
🔴 Action needed / >5% drift
✅ Complete / met
⏳ Pending / future
❓ Unknown / TBD

Typography

Headings: Material default (don't override)
Body: 0.7rem (set in extra.css)
Labels/meta: 0.8em, colour #666
Big numbers: 1.6em, font-weight 700, colour primary

Nav Structure

Pages are grouped into logical sections:

- Home (dashboard — the "At a Glance" view)
- Strategy (current-plan, withdrawal, currency)
- Portfolio (net worth history, rebalance monitor, market dashboard)
- Tools (Monte Carlo, calendar)
- Planning (action items, topics, protection, expenses)
- Reference (family)
- Sessions (auto-generated)

Adding a New Page

Create page-name.md at repo root
Use shared component classes (no inline styles)
Add cp page-name.md docs/ to build.sh
Add to appropriate nav section in build.sh
Run ./build.sh — verify zero warnings
Follow markdown formatting rules from agents.md