From cdf50f58de1cbe0c1504cffd64f34ef5489b4962 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Sat, 4 Apr 2026 03:00:10 +0000
Subject: [PATCH] feat: Add concrete examples to tooltips for abstract
 statistical/financial inputs

- Added `help` tooltip to `vol_q_high` (High Volatility Quantile) explaining the threshold logic.
- Added `help` tooltip to `bt_cost` (Transaction Cost) translating bps to percentage.
- Created UX journal `.Jules/palette.md` noting the importance of concrete examples for complex inputs.

Co-authored-by: aarjava <218419324+aarjava@users.noreply.github.com>
---
 .Jules/palette.md |  3 +++
 src/dashboard.py  | 14 ++++++++++++--
 2 files changed, 15 insertions(+), 2 deletions(-)
 create mode 100644 .Jules/palette.md

diff --git a/.Jules/palette.md b/.Jules/palette.md
new file mode 100644
index 0000000..8b5e80e
--- /dev/null
+++ b/.Jules/palette.md
@@ -0,0 +1,3 @@
+## 2024-04-04 - Helpful Tooltips for Abstract Inputs
+**Learning:** Inputs involving statistical or financial parameters (like quantiles or basis points) can be abstract and confusing. Providing concrete examples in tooltips significantly improves usability and ensures users understand the scale and meaning of their inputs.
+**Action:** Always include concrete, numerical examples in `help` tooltips for statistical, financial, or unit-based inputs (e.g., "10 bps = 0.10%").
diff --git a/src/dashboard.py b/src/dashboard.py
index 4156c1d..fd02074 100644
--- a/src/dashboard.py
+++ b/src/dashboard.py
@@ -185,12 +185,22 @@ def get_cache_key(*args) -> str:
         st.info("Using full-sample quantiles (exploratory mode)")
 
     vol_q_high = st.slider(
-        "High Volatility Quantile", 0.5, 0.95, DEFAULT_VOL_QUANTILE_HIGH, 0.05
+        "High Volatility Quantile",
+        0.5,
+        0.95,
+        DEFAULT_VOL_QUANTILE_HIGH,
+        0.05,
+        help="Example: 0.90 means the top 10% of volatility values are considered 'High'.",
     )
 
     if mode == "Single-Asset":
         st.subheader("5. Backtest Settings")
-        bt_cost = st.number_input("Transaction Cost (bps)", value=DEFAULT_COST_BPS, step=1) / 10000
+        bt_cost = (
+            st.number_input(
+                "Transaction Cost (bps)", value=DEFAULT_COST_BPS, step=1, help="10 bps = 0.10%"
+            )
+            / 10000
+        )
         allow_short = st.checkbox("Allow Short Selling?", value=False)
     else:
         st.subheader("5. Alert Thresholds")