DESIGN_NOTES.md

# Design reference — Backtest Lab

Extracted from `Bit Trading Portal Dashboard/Backtest Lab.dc.html` plus the Bit
design system (`_ds/bit-design-system-b707c3d1…`). This file is the contract the
Gradio UI is built against; `assets/tokens/*.css` and `assets/fonts/*` are
vendored verbatim from that design system.

## Design system

Dark-first, terminal-flavoured. Tokens only — components never use raw colors.

| Role | Token | Value |
|---|---|---|
| Canvas | `--bg-canvas` | `#161512` (stone-950) |
| Panel | `--bg-panel` | `#1d1c18` (stone-900) |
| Raised | `--bg-raised` | `#24221d` (stone-850) |
| Border subtle / default | `--border-subtle` / `--border-default` | `#2c2a24` / `#3d3a32` |
| Text primary / secondary / tertiary | | `#f7f4ec` / `#b6b09a` / `#6f6a56` |
| Primary accent | `--accent-amber` / `-strong` | `#af9209` / `#cfab0a` |
| Secondary accent | `--accent-moss` / `-strong` | `#68781e` / `#7d901f` |
| Up / down | `--fin-up` / `--fin-down` | `oklch(66% .22 149)` / `oklch(62% .26 24)` |

Colorblind mode (`[data-colorblind=true]`) swaps up/down to blue/orange, and
direction is **also** marked with ▲/▼ glyphs — never color alone.

Fonts: headings `Styrene A` (400), body system sans (300), `JetBrains Mono` for
numbers, `Mac Minecraft` for the 8–10px pixel labels. Sizes are small:
`--text-2xs:8px … --text-base:12px … --text-4xl:62px`.

Radii are near-square (`--radius-sm:4px`, `--radius-md:8px`); panels are a 1px
border, no drop shadows (`--shadow-panel: 0 0 0 1px var(--border-default)`).

Section headings are ALL-CAPS Styrene with `--tracking-wide`; micro-labels are
uppercase Mac Minecraft with `--tracking-wider`.

## Layout

Three zones; left `286px`, right `306px` (collapses to `46px`), center fluid.

- **Top bar** — BIT mark, `BIT / Backtest Lab`, context chip
  (`BTC-USD · 1H · 2021-08-15 → 2026-08-15 · WALK-FORWARD`), run-status chip,
  elapsed (`~4S`), amber **▶ Run backtest**, Display menu (Dark mode /
  Colorblind-safe prices, footnote `UP/DOWN ALSO MARKED ▲ ▼`), `Portal ↗`.
- **Left — Strategy Builder** (`CFG #0142`), five numbered collapsible sections:
  1. Strategy — preset select + params
  2. Universe & Data — ticker chips (`+ ticker`), Asset class segmented
     (Crypto/Equities/Both), Timeframe chips, Date range (`1Y 3Y 5Y Max`),
     Regime filter (`Bull only / Bear only / Chop only`, `NEW` badge)
  3. Costs & Execution — Commission/side `0.10%`, Slippage `5 BPS`,
     slippage model (`Fixed bps / Volume-scaled / Spread-based`),
     fill (`Next bar open / Same bar close`), funding.
     Warning: **"Costs on. Turning these off is how strategies lie to you."**
  4. Sizing & Risk — sizing (`Fixed % / Kelly fraction / Vol-target 15% ann.`),
     leverage `1X…3X`, Max position `35%`, Max concurrent `2`
  5. Validation — `TRAIN 12MO · TEST 3MO · ROLL 3MO`, ■ TRAIN / ■ TEST bands,
     OOS holdout `LAST 6MO`
  Footer: `Save config`, `Share link`.
- **Center — Results Canvas**, tabs: `Overview · Trades · Comparison · Robustness · Report`
- **Right — Run Manager** — `RUNNING · {progress}`, Run history (`n/6 SELECTED`,
  star = favourite, Sharpe color-coded), Trending public configs, `Clone config`,
  `Metrics glossary`.
- **Footer** — always visible:
  "Simulated results with modeled costs. Backtests are hypotheses, not promises.
  Past performance does not predict future results. Not financial advice."
  Right: `BITTRADING SDK 0.9.3`.

## States

- **Empty**: "No run loaded" / "Configure a strategy on the left, or start from a
  worked example and edit it." + `Load example: Sentiment-Gated Momentum · BTC 1h`
  + shortcut hints `⌘↵ RUN`, `⌘S SAVE CONFIG`, `⌘K COMMANDS`.
- **Loading**: staged labels — `Fetching data`, `Simulating N trades`,
  `Walk-forward window k/n`, `Computing robustness`.

## Tab contents

**Overview** — stat band (each stat shows `IS x · OOS y`); `EQUITY CURVE`
(`STRATEGY VS BUY & HOLD`, log-scale toggle, drawdown shading, hatched `HOLDOUT`
band, `REGIME` strip); `UNDERWATER · MAX −23.6%`; `ROLLING 90D SHARPE · MEDIAN 1.24`;
price+trades chart (`▲ ENTRY · ▼ EXIT · HOLLOW = SHORT · HOVER A FLAG FOR THE TRADE CARD`);
`NET P&L DISTRIBUTION`, `HOLDING PERIOD (HOURS)`, `MAE / MFE SCATTER`;
`COSTS PAID TOTAL: $1,842` with the note that the costed number is the real one.

**Trades** — `312 TOTAL · SHOWING 14`, `Export CSV →`, sortable columns:
id, entry/exit time, side, entry/exit px, size, gross, costs, net, R, duration,
MAE, trigger.

**Comparison** — `Time-scale matrix` (`CELL = OOS SHARPE · CLICK TO LOAD RUN`,
scale −0.5 → 2.0), `n/6 SELECTED`, small-multiples equity grid, overlaid
cumulative return (`SHARED SCALE · OOS PERIOD SHADED`), metrics table
(rows: Total return, CAGR, OOS Sharpe, Max drawdown, Win rate, Trades; best
value amber+bold), `RETURN CORRELATION · ARE THESE THE SAME BET?`,
`RETURN ACROSS REGIMES · BULL / BEAR / CHOP`.

**Robustness** — `Overfit verdict` with grade + checklist; `PARAMETER SENSITIVITY ·
FAST MA × SLOW MA · OOS SHARPE` heatmap with `□ CHOSEN` marker;
`MONTE CARLO · 1,000 TRADE RESHUFFLES` cone with `P5 / P50 / P95` and
`P(RUIN > 30% DD)`; `WALK-FORWARD WINDOWS · OOS RETURN` bars with
`CONSISTENCY 6/8 POSITIVE`; `SLIPPAGE STRESS · SHARPE VS BPS`.

**Report** — prose summary, `EQUITY CURVE · STRATEGY VS BUY & HOLD`,
`CONFIG SNAPSHOT`, verdict line, actions: `Export PDF`, `Publish to leaderboard`,
`Publish to graveyard`, `Copy share link`, `Export trades CSV`, `Open in Colab`.

## Presets (design list)

`SMA Crossover`, `RSI Mean Reversion`, `Bollinger Breakout`, `MACD Momentum`,
`Sentiment-Gated Momentum`, `Chronos Forecast Follower`, `Pairs Trading`,
`Buy & Hold (benchmark)`, `Custom (code)`.

`Custom (code)` is shown **disabled** — see DECISIONS.md (D-004). Executing
user-supplied strategy code is forbidden by the build spec, so the control is
present but inert with an explanation rather than silently removed.

## Glossary copy (verbatim, used in the Run Manager tray)

- **SHARPE** — Annualized mean excess return divided by return volatility. Above 1 is good; above 3 usually means a bug.
- **SORTINO** — Sharpe with only downside deviation in the denominator.
- **MAX DRAWDOWN** — Worst peak-to-trough decline of the equity curve.
- **PROFIT FACTOR** — Gross profit over gross loss. Below 1.2 rarely survives real costs.
- **R-MULTIPLE** — Trade P&L expressed in units of initial risk.
- **MAE / MFE** — Worst and best unrealized excursion while the trade was open.
- **WALK-FORWARD** — Train on a rolling window, test on the next unseen window, repeat.
- **OOS** — Out of sample: data the parameters never saw during fitting.