UI overhaul: immersive chapter-based experience

- Rename tabs: Origins, Genetic Landscape, Gene Universe, Genome Explorer, Protein World, Your Report
- Load 3D UMAP embedding for true 3D scatter visualization
- Add country filter dropdown on Origins tab (replaces global filters accordion)
- Remove global filters accordion
- Update progress stepper labels
- Add new precomputed artifacts: 3D embedding, sunburst hierarchy, polar layout, radar axes
- Update UMAP callback to use 3D Scatter3d
- Upgrade Gradio SDK version to 6.5.1

README.md

@@ -4,7 +4,7 @@ emoji: "\U0001F331"
 colorFrom: green
 colorTo: yellow
 sdk: gradio
-sdk_version: 5.29.0
+sdk_version: 6.5.1
 app_file: app.py
 pinned: false
 short_description: Interactive pangenome exploration of 89 pigeon pea lines

app.py

@@ -23,6 +23,7 @@ from src.callbacks import (
     on_generate_report, build_data_health_html,
 )
 from ui.layout import build_app
+from ui.quest0 import build_globe_figure
 
 # ===========================================================
 # Load precomputed data
@@ -38,7 +39,14 @@ def load_data():
 
     DATA["gene_freq"] = pd.read_parquet(p / "pav_gene_frequency.parquet")
     DATA["line_stats"] = pd.read_parquet(p / "line_stats.parquet")
-    DATA["embedding"] = pd.read_parquet(p / "line_embedding.parquet")
+    # Prefer 3D embedding for the Genetic Landscape chapter
+    emb_3d = p / "line_embedding_3d.parquet"
+    if emb_3d.exists():
+        DATA["embedding"] = pd.read_parquet(emb_3d)
+        logger.info("Loaded 3D UMAP embedding")
+    else:
+        DATA["embedding"] = pd.read_parquet(p / "line_embedding.parquet")
+        logger.info("Loaded 2D UMAP embedding (3D not available)")
     DATA["similarity"] = pd.read_parquet(p / "line_similarity_topk.parquet")
     DATA["gff_index"] = pd.read_parquet(p / "gff_gene_index.parquet")
     DATA["protein"] = pd.read_parquet(p / "protein_index.parquet")
@@ -74,9 +82,6 @@ contig_choices = contig_gene_counts.head(30).index.tolist()
 # Gene choices (all genes with protein data)
 gene_choices = sorted(DATA["protein"]["gene_id"].tolist())
 
-# Country list for filters
-country_list = sorted(DATA["line_stats"]["country"].unique().tolist())
-
 # ===========================================================
 # Build UI
 # ===========================================================
@@ -87,9 +92,6 @@ demo, C = build_app(line_choices, contig_choices, gene_choices)
 # ===========================================================
 with demo:
 
-    # Update country filter choices
-    C["country_filter"].choices = country_list
-
     # -- Data Health on load --
     try:
         report = {
@@ -103,7 +105,30 @@ with demo:
     except Exception as e:
         C["data_health_html"].value = f"<p>Error: {e}</p>"
 
-    # -- Quest 0 --
+    # -- Quest 0: Origins --
+
+    # Render globe on tab load
+    C["q0_tab"].select(
+        fn=lambda: build_globe_figure(DATA["line_stats"]),
+        inputs=[],
+        outputs=[C["q0_globe_plot"]],
+    )
+
+    # Country filter → update line dropdown choices
+    def on_country_filter(country):
+        ls = DATA["line_stats"]
+        if country and country != "All countries":
+            filtered = ls[ls["country"] == country]["line_id"].tolist()
+        else:
+            filtered = ls["line_id"].tolist()
+        return gr.Dropdown(choices=sorted(filtered), value=None)
+
+    C["q0_country_dropdown"].change(
+        fn=on_country_filter,
+        inputs=[C["q0_country_dropdown"]],
+        outputs=[C["q0_line_dropdown"]],
+    )
+
     C["q0_line_dropdown"].change(
         fn=lambda line_id, state: on_line_selected(line_id, state, DATA),
         inputs=[C["q0_line_dropdown"], C["state"]],

precomputed/line_embedding_3d.parquet

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:60b2c1a7744b55b613fb2f36d60668999d15d0b54355038b6a1a226a8528002f
+size 5680

precomputed/radar_axes.json

@@ -0,0 +1,26 @@
+{
+  "axes": [
+    "L",
+    "S",
+    "E",
+    "A",
+    "K",
+    "V",
+    "G",
+    "R",
+    "P",
+    "I"
+  ],
+  "global_mean": {
+    "L": 8.622,
+    "S": 6.65,
+    "E": 3.946,
+    "A": 3.843,
+    "K": 3.504,
+    "V": 3.448,
+    "G": 3.185,
+    "R": 2.93,
+    "P": 1.944,
+    "I": 1.828
+  }
+}

precomputed/sunburst_hierarchy.json

@@ -0,0 +1,26 @@
+{
+  "ids": [
+    "total",
+    "core",
+    "shell",
+    "cloud"
+  ],
+  "labels": [
+    "All Genes",
+    "Core",
+    "Shell",
+    "Cloud"
+  ],
+  "parents": [
+    "",
+    "total",
+    "total",
+    "total"
+  ],
+  "values": [
+    55512,
+    51990,
+    2526,
+    996
+  ]
+}

scripts/run_precompute.py

@@ -20,6 +20,8 @@ from src.precompute import (
     compute_gene_frequency, compute_line_stats, compute_line_embedding,
     compute_similarity_topk, build_gff_gene_parquet, build_protein_parquet,
     save_contig_index, compute_hotspot_bins, compute_cluster_markers,
+    compute_line_embedding_3d, build_sunburst_data, build_polar_contig_layout,
+    compute_radar_axes,
 )
 from src.utils import logger, find_file
 
@@ -98,6 +100,27 @@ def main():
     # Also save the PAV matrix as parquet for efficient loading
     pav.to_parquet(os.path.join(output_dir, "pav_matrix.parquet"))
 
+    # 3. New derived data for UI overhaul
+    logger.info("=== Phase 3: New UI overhaul artifacts ===")
+
+    t_step = time.time()
+    embedding_3d = compute_line_embedding_3d(pav, embedding)
+    embedding_3d.to_parquet(os.path.join(output_dir, "line_embedding_3d.parquet"), index=False)
+    logger.info(f"  -> line_embedding_3d.parquet ({time.time() - t_step:.1f}s)")
+
+    t_step = time.time()
+    build_sunburst_data(gene_freq, os.path.join(output_dir, "sunburst_hierarchy.json"))
+    logger.info(f"  -> sunburst_hierarchy.json ({time.time() - t_step:.1f}s)")
+
+    t_step = time.time()
+    build_polar_contig_layout(hotspots, contig_index,
+                              os.path.join(output_dir, "polar_contig_layout.json"))
+    logger.info(f"  -> polar_contig_layout.json ({time.time() - t_step:.1f}s)")
+
+    t_step = time.time()
+    compute_radar_axes(protein_index, os.path.join(output_dir, "radar_axes.json"))
+    logger.info(f"  -> radar_axes.json ({time.time() - t_step:.1f}s)")
+
     dt = time.time() - t_total
     logger.info(f"=== All precomputation done in {dt:.1f}s ===")
 

src/callbacks.py

@@ -61,43 +61,16 @@ def on_start_journey(state: AppState) -> tuple:
 # ============================================================
 
 def build_umap_plot(color_by: str, state: AppState, data: dict) -> go.Figure:
-    """Build Plotly UMAP scatter."""
-    embedding = data["embedding"]
-    line_stats = data["line_stats"]
-
-    df = embedding.merge(line_stats[["line_id", "country"]], on="line_id", how="left")
-    df["country"] = df["country"].fillna("Unknown")
-
-    color_col = "country" if color_by == "Country" else "cluster_id"
-    if color_col == "cluster_id":
-        df["cluster_id"] = df["cluster_id"].astype(str)
-
-    fig = px.scatter(
-        df, x="umap_x", y="umap_y", color=color_col,
-        hover_data=["line_id", "country"],
-        title="UMAP of 89 Pigeon Pea Lines",
-        labels={"umap_x": "UMAP 1", "umap_y": "UMAP 2"},
-        color_discrete_sequence=COUNTRY_COLORS if color_by == "Country" else px.colors.qualitative.Bold,
+    """Build 3D UMAP scatter (delegates to quest1.build_umap_3d)."""
+    from ui.quest1 import build_umap_3d
+
+    selected_line = state.selected_line if state else None
+    color_key = "country" if color_by == "Country" else "cluster"
+    return build_umap_3d(
+        data["embedding"], data["line_stats"],
+        color_by=color_key, selected_line=selected_line,
     )
 
-    # Highlight selected line
-    if state and state.selected_line:
-        sel = df[df["line_id"] == state.selected_line]
-        if len(sel) > 0:
-            fig.add_trace(go.Scatter(
-                x=sel["umap_x"], y=sel["umap_y"],
-                mode="markers",
-                marker=dict(symbol="star", size=18, color="red", line=dict(width=2, color="black")),
-                name=f"Your line: {state.selected_line}",
-                hovertext=state.selected_line,
-            ))
-
-    fig.update_layout(
-        plot_bgcolor="white",
-        legend=dict(orientation="h", yanchor="bottom", y=-0.3),
-    )
-    return fig
-
 
 def on_umap_select(selected_data, state: AppState) -> tuple:
     """Handle UMAP point selection."""

src/plot_config.py

@@ -0,0 +1,198 @@
+"""Shared Plotly chart configuration and color constants for the Pangenome Atlas.
+
+Every chart-building callback should import from this module to ensure
+visual consistency across all plots.
+
+Exports
+-------
+COLORS           – dict of semantic color tokens.
+COUNTRY_COLORS   – per-country color mapping (17 countries + Unknown).
+CLUSTER_COLORS   – ordered list for the 3 optimal clusters.
+PLOTLY_TEMPLATE  – light-background Plotly layout dict.
+PLOTLY_TEMPLATE_DARK – dark-background variant for globe / 3-D views.
+apply_template() – apply the atlas template to any ``plotly.graph_objects.Figure``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import plotly.graph_objects as go  # pragma: no cover
+
+# =====================================================================
+# Color Palette
+# =====================================================================
+
+COLORS: dict[str, str] = {
+    # Gene classification
+    "core": "#2E7D32",           # forest green
+    "shell": "#F9A825",          # warm amber
+    "cloud": "#C62828",          # warm red
+    # UI accents
+    "selected": "#D4A017",       # gold — user's selected line
+    "accent": "#1565C0",         # deep blue — links / actions
+    # Backgrounds
+    "bg_dark": "#1a2332",        # dark navy — globe / hero header
+    "bg_light": "#FAFAF5",       # warm white — page background
+    "bg_card": "#FFFFFF",        # card surface
+    # Text
+    "text_primary": "#1A1A1A",
+    "text_secondary": "#757575",
+    "text_muted": "#94a3b8",
+    # Structural
+    "border": "#E0E0E0",
+    "grid_faint": "#F0F0E8",
+}
+
+# Per-country colors used by the globe, UMAP, and any country legend.
+# 17 countries + Unknown.
+COUNTRY_COLORS: dict[str, str] = {
+    "India": "#2E7D32",
+    "Philippines": "#1565C0",
+    "Kenya": "#C62828",
+    "Nepal": "#D4A017",
+    "Myanmar": "#6A1B9A",
+    "Uganda": "#00838F",
+    "Zaire": "#E65100",
+    "Indonesia": "#455A64",
+    "Jamaica": "#AD1457",
+    "South_Africa": "#1B5E20",
+    "Puerto_Rico": "#0277BD",
+    "Sierra_Leone": "#BF360C",
+    "Nigeria": "#827717",
+    "Malawi": "#4E342E",
+    "Italy": "#283593",
+    "Sri_Lanka": "#00695C",
+    "Thailand": "#FF6F00",
+    "Unknown": "#9E9E9E",
+}
+
+# Cluster colors for the 3 optimal clusters (silhouette = 0.649).
+CLUSTER_COLORS: list[str] = ["#2E7D32", "#1565C0", "#C62828"]
+
+# =====================================================================
+# Shared font stack (matches the Gradio theme)
+# =====================================================================
+
+_FONT_STACK = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
+
+# =====================================================================
+# Plotly Layout Templates
+# =====================================================================
+
+PLOTLY_TEMPLATE: dict = dict(
+    layout=dict(
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)",
+        font=dict(
+            family=_FONT_STACK,
+            color=COLORS["text_primary"],
+            size=13,
+        ),
+        title=dict(
+            font=dict(size=18, color=COLORS["text_primary"]),
+            x=0.02,
+            xanchor="left",
+        ),
+        xaxis=dict(
+            showgrid=False,
+            zeroline=False,
+            showline=False,
+        ),
+        yaxis=dict(
+            showgrid=False,
+            zeroline=False,
+            showline=False,
+        ),
+        margin=dict(l=30, r=20, t=50, b=30),
+        hoverlabel=dict(
+            bgcolor="white",
+            font_size=13,
+            font_family=_FONT_STACK,
+            bordercolor=COLORS["border"],
+        ),
+        legend=dict(
+            bgcolor="rgba(255,255,255,0.85)",
+            bordercolor="rgba(0,0,0,0)",
+            font=dict(size=12),
+        ),
+    )
+)
+
+# Dark variant for 3-D plots, globe visualisations, and hero panels.
+PLOTLY_TEMPLATE_DARK: dict = dict(
+    layout=dict(
+        paper_bgcolor=COLORS["bg_dark"],
+        plot_bgcolor=COLORS["bg_dark"],
+        font=dict(
+            family=_FONT_STACK,
+            color="#E0E0E0",
+            size=13,
+        ),
+        title=dict(
+            font=dict(size=18, color="#E0E0E0"),
+            x=0.02,
+            xanchor="left",
+        ),
+        xaxis=dict(
+            showgrid=False,
+            zeroline=False,
+            showline=False,
+            color="#E0E0E0",
+        ),
+        yaxis=dict(
+            showgrid=False,
+            zeroline=False,
+            showline=False,
+            color="#E0E0E0",
+        ),
+        margin=dict(l=30, r=20, t=50, b=30),
+        hoverlabel=dict(
+            bgcolor="#263245",
+            font_size=13,
+            font_family=_FONT_STACK,
+            bordercolor="#3a4a60",
+        ),
+        legend=dict(
+            bgcolor="rgba(26,35,50,0.85)",
+            bordercolor="rgba(0,0,0,0)",
+            font=dict(size=12, color="#E0E0E0"),
+        ),
+    )
+)
+
+# Modebar buttons to hide for a cleaner look.
+_MODEBAR_REMOVE = [
+    "toImage",
+    "zoom2d",
+    "pan2d",
+    "select2d",
+    "lasso2d",
+    "autoScale2d",
+    "resetScale2d",
+    "zoomIn2d",
+    "zoomOut2d",
+]
+
+
+def apply_template(fig: "go.Figure", dark: bool = False) -> "go.Figure":
+    """Apply the Atlas Plotly template to *fig* and hide the modebar.
+
+    Parameters
+    ----------
+    fig : plotly.graph_objects.Figure
+        The figure to style in-place.
+    dark : bool, optional
+        If ``True``, use the dark-background variant suitable for globe
+        and 3-D scenes.  Defaults to ``False``.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+        The same figure, for chaining.
+    """
+    template = PLOTLY_TEMPLATE_DARK if dark else PLOTLY_TEMPLATE
+    fig.update_layout(**template["layout"])
+    fig.update_layout(modebar=dict(remove=_MODEBAR_REMOVE))
+    return fig

src/precompute.py

@@ -1,5 +1,9 @@
 """Offline precomputation for the Pigeon Pea Pangenome Atlas."""
 
+import json
+import re
+from collections import Counter, defaultdict
+
 import numpy as np
 import pandas as pd
 from scipy.spatial.distance import pdist, squareform
@@ -257,3 +261,180 @@ def compute_cluster_markers(pav: pd.DataFrame, embedding: pd.DataFrame,
     df = pd.DataFrame(records)
     logger.info(f"Cluster markers: {len(df)} total across {df['cluster_id'].nunique()} clusters")
     return df
+
+
+# ---------------------------------------------------------------------------
+# New precomputation functions for UI overhaul
+# ---------------------------------------------------------------------------
+
+
+@timer
+def compute_line_embedding_3d(pav: pd.DataFrame,
+                              embedding_2d: pd.DataFrame) -> pd.DataFrame:
+    """
+    3D UMAP embedding of lines, reusing cluster_id from the 2D embedding.
+    Output columns: line_id, umap_x, umap_y, umap_z, cluster_id
+    """
+    import umap
+
+    # Transpose: rows = lines, columns = genes
+    X = pav.T.values.astype(np.float32)
+    line_ids = list(pav.columns)
+
+    # UMAP with 3 components
+    reducer = umap.UMAP(n_components=3, metric="jaccard", n_neighbors=15,
+                        min_dist=0.1, random_state=42)
+    embedding = reducer.fit_transform(X)
+
+    # Reuse cluster_id from 2D embedding
+    cluster_map = dict(zip(embedding_2d["line_id"], embedding_2d["cluster_id"]))
+
+    df = pd.DataFrame({
+        "line_id": line_ids,
+        "umap_x": embedding[:, 0],
+        "umap_y": embedding[:, 1],
+        "umap_z": embedding[:, 2],
+        "cluster_id": [int(cluster_map.get(lid, -1)) for lid in line_ids],
+    })
+    logger.info(f"3D UMAP embedding computed for {len(df)} lines")
+    return df
+
+
+@timer
+def build_sunburst_data(gene_freq: pd.DataFrame, output_path: str) -> None:
+    """
+    Build Plotly go.Sunburst hierarchy arrays and save as JSON.
+    Structure: total -> core / shell / cloud
+    """
+    core_count = int((gene_freq["core_class"] == "core").sum())
+    shell_count = int((gene_freq["core_class"] == "shell").sum())
+    cloud_count = int((gene_freq["core_class"] == "cloud").sum())
+    total_count = core_count + shell_count + cloud_count
+
+    data = {
+        "ids": ["total", "core", "shell", "cloud"],
+        "labels": ["All Genes", "Core", "Shell", "Cloud"],
+        "parents": ["", "total", "total", "total"],
+        "values": [total_count, core_count, shell_count, cloud_count],
+    }
+
+    with open(output_path, "w") as f:
+        json.dump(data, f, indent=2)
+    logger.info(f"Sunburst hierarchy saved: {output_path} "
+                f"(total={total_count}, core={core_count}, "
+                f"shell={shell_count}, cloud={cloud_count})")
+
+
+@timer
+def build_polar_contig_layout(hotspots: pd.DataFrame,
+                              contig_index: dict,
+                              output_path: str,
+                              top_n: int = 20) -> None:
+    """
+    Assign the top contigs (by gene count) angular sectors for a polar layout.
+    Saves per-contig metadata and per-bin variability mapped to angular positions.
+    """
+    # Aggregate gene counts per contig from hotspot bins
+    contig_gene_counts = (
+        hotspots.groupby("contig_id")["total_genes"]
+        .sum()
+        .nlargest(top_n)
+    )
+    top_contigs = list(contig_gene_counts.index)
+
+    # Sum total length of selected contigs (use contig_index if available)
+    contig_lengths = {}
+    for cid in top_contigs:
+        contig_lengths[cid] = contig_index.get(cid, int(
+            hotspots[hotspots["contig_id"] == cid]["bin_end"].max()))
+
+    total_length = sum(contig_lengths.values())
+
+    # Assign angular sectors proportional to contig length
+    sectors = []
+    theta_cursor = 0.0
+    for cid in top_contigs:
+        length = contig_lengths[cid]
+        arc = (length / total_length) * 360.0 if total_length > 0 else 0
+        theta_start = round(theta_cursor, 4)
+        theta_end = round(theta_cursor + arc, 4)
+
+        # Map bins for this contig to angular positions
+        contig_bins = hotspots[hotspots["contig_id"] == cid].sort_values("bin_start")
+        bins_mapped = []
+        for _, row in contig_bins.iterrows():
+            # Map bin midpoint position to angular position within the sector
+            bin_mid = (row["bin_start"] + row["bin_end"]) / 2
+            frac = bin_mid / length if length > 0 else 0
+            theta_bin = theta_start + frac * arc
+            bins_mapped.append({
+                "theta": round(theta_bin, 4),
+                "total_genes": int(row["total_genes"]),
+                "variability_score": float(row["variability_score"]),
+                "core_genes": int(row["core_genes"]),
+                "shell_genes": int(row["shell_genes"]),
+                "cloud_genes": int(row["cloud_genes"]),
+            })
+
+        sectors.append({
+            "contig_id": cid,
+            "theta_start": theta_start,
+            "theta_end": theta_end,
+            "total_genes": int(contig_gene_counts[cid]),
+            "total_length": int(length),
+            "bins": bins_mapped,
+        })
+
+        theta_cursor += arc
+
+    with open(output_path, "w") as f:
+        json.dump(sectors, f, indent=2)
+    logger.info(f"Polar contig layout saved: {output_path} "
+                f"({len(sectors)} contigs, 360-degree arc)")
+
+
+@timer
+def compute_radar_axes(protein_index: pd.DataFrame,
+                       output_path: str,
+                       top_n: int = 10) -> None:
+    """
+    Find the top amino acids across all proteins and compute global mean percentages.
+    Parses composition_summary strings (e.g. 'L:9.8%, S:7.2%, A:6.5%, G:5.8%, V:5.5%').
+    Saves: { "axes": [...], "global_mean": {aa: mean_pct, ...} }
+    """
+    # Parse all composition summaries to accumulate per-protein AA percentages
+    aa_totals = defaultdict(list)  # aa -> list of pct values (one per protein)
+
+    for comp_str in protein_index["composition_summary"]:
+        if not comp_str or pd.isna(comp_str):
+            continue
+        # Parse tokens like "L:9.8%"
+        for token in comp_str.split(","):
+            token = token.strip()
+            match = re.match(r"([A-Z]):(\d+\.?\d*)%", token)
+            if match:
+                aa = match.group(1)
+                pct = float(match.group(2))
+                aa_totals[aa].append(pct)
+
+    # Compute mean percentage for each AA (proteins where AA was not in top-5
+    # are treated as 0 for ranking, but we report only the mean when present)
+    n_proteins = len(protein_index)
+    aa_mean = {}
+    for aa, pct_list in aa_totals.items():
+        # Mean across ALL proteins (assume 0 for those where it wasn't in top-5)
+        aa_mean[aa] = round(sum(pct_list) / n_proteins, 3)
+
+    # Select top-N by global mean
+    sorted_aas = sorted(aa_mean.items(), key=lambda x: -x[1])[:top_n]
+    axes = [aa for aa, _ in sorted_aas]
+    global_mean = {aa: pct for aa, pct in sorted_aas}
+
+    data = {
+        "axes": axes,
+        "global_mean": global_mean,
+    }
+
+    with open(output_path, "w") as f:
+        json.dump(data, f, indent=2)
+    logger.info(f"Radar axes saved: {output_path} (top {top_n} AAs: {axes})")

src/utils.py

@@ -40,6 +40,27 @@ KNOWN_COUNTRIES = {
     "Malawi", "Italy", "Kenya", "Sri_Lanka", "Thailand", "Nepal",
 }
 
+# Approximate centroid coordinates (lat, lon) for each country.
+COUNTRY_COORDS = {
+    "India":        (20.59,  78.96),
+    "Philippines":  (12.88, 121.77),
+    "Kenya":        (-1.29,  36.82),
+    "Nepal":        (28.39,  84.12),
+    "Myanmar":      (21.92,  95.96),
+    "Uganda":       (1.37,   32.29),
+    "Zaire":        (-4.04,  21.76),
+    "Indonesia":    (-0.79, 113.92),
+    "Jamaica":      (18.11, -77.30),
+    "South_Africa": (-30.56, 22.94),
+    "Puerto_Rico":  (18.22, -66.59),
+    "Sierra_Leone": (8.46,  -11.78),
+    "Nigeria":      (9.08,    7.49),
+    "Malawi":       (-13.25, 34.30),
+    "Italy":        (41.87,  12.57),
+    "Sri_Lanka":    (7.87,   80.77),
+    "Thailand":     (15.87, 100.99),
+}
+
 
 def parse_country(line_id: str) -> str:
     """Extract country from line ID (last token after underscore)."""
@@ -53,3 +74,128 @@ def parse_country(line_id: str) -> str:
         if two_word in KNOWN_COUNTRIES:
             return two_word
     return "Unknown"
+
+
+# =====================================================================
+# HTML builder helpers
+# =====================================================================
+
+def build_hero_header(
+    total_genes: int,
+    n_lines: int,
+    n_countries: int,
+    n_clusters: int,
+) -> str:
+    """Return an HTML string for the hero dashboard header.
+
+    Renders a dark (#1a2332) banner with large stat numbers and small
+    uppercase labels.  Uses the ``.hero-header``, ``.hero-stat``, and
+    ``.hero-subtitle`` CSS classes defined in ``ui/theme.py``.
+
+    Parameters
+    ----------
+    total_genes : int
+        Total number of genes in the pangenome.
+    n_lines : int
+        Number of accession lines (e.g. 89 + reference).
+    n_countries : int
+        Number of countries of origin.
+    n_clusters : int
+        Number of genomic clusters.
+    """
+    stats = [
+        (f"{total_genes:,}", "Total Genes"),
+        (str(n_lines), "Lines"),
+        (str(n_countries), "Countries"),
+        (str(n_clusters), "Clusters"),
+    ]
+    stat_html = "\n".join(
+        f'<span class="hero-stat">'
+        f'<span class="stat-number">{value}</span>'
+        f'<span class="stat-label">{label}</span>'
+        f"</span>"
+        for value, label in stats
+    )
+    return (
+        '<div class="hero-header">'
+        "<h1>Pigeon Pea Pangenome Atlas</h1>"
+        '<p class="hero-subtitle">'
+        "An interactive exploration of presence-absence variation across "
+        "pigeon pea accessions worldwide."
+        "</p>"
+        '<div class="hero-stats">'
+        f"{stat_html}"
+        "</div>"
+        "</div>"
+    )
+
+
+def build_metric_card(value: str, label: str, color: str = "green") -> str:
+    """Return an HTML string for a single metric card.
+
+    Parameters
+    ----------
+    value : str
+        The large number or text to display (e.g. ``"55,512"``).
+    label : str
+        Short uppercase caption below the number (e.g. ``"TOTAL GENES"``).
+    color : str, optional
+        Color accent for the top border.  One of ``"green"`` (default),
+        ``"amber"``, ``"red"``, or ``"blue"``.  Maps to CSS modifier
+        classes on ``.metric-card``.
+    """
+    color_class = ""
+    if color in ("amber", "red", "blue"):
+        color_class = f" {color}"
+    return (
+        f'<div class="metric-card{color_class}">'
+        f'<div class="metric-value">{value}</div>'
+        f'<div class="metric-label">{label}</div>'
+        "</div>"
+    )
+
+
+def build_progress_stepper(current_step: int = 0, total_steps: int = 6) -> str:
+    """Return an HTML string for a visual progress stepper.
+
+    Renders a horizontal row of numbered circles connected by lines.
+    Steps before *current_step* are marked complete (green filled),
+    *current_step* itself gets a green ring, and later steps are dimmed.
+
+    Uses ``.progress-stepper``, ``.step-complete``, ``.step-current``,
+    and ``.step-future`` CSS classes from ``ui/theme.py``.
+
+    Parameters
+    ----------
+    current_step : int
+        Zero-based index of the active step.
+    total_steps : int
+        Total number of steps (default 6, matching the quest count).
+    """
+    step_labels = [
+        "Explorer",
+        "Map the World",
+        "Core vs Accessory",
+        "Genome Landmarks",
+        "Protein Relics",
+        "Field Report",
+    ]
+    parts: list[str] = []
+    for i in range(total_steps):
+        label = step_labels[i] if i < len(step_labels) else f"Step {i + 1}"
+        if i < current_step:
+            cls = "step step-complete"
+            dot_content = "&#10003;"  # checkmark
+        elif i == current_step:
+            cls = "step step-current"
+            dot_content = str(i + 1)
+        else:
+            cls = "step step-future"
+            dot_content = str(i + 1)
+        parts.append(
+            f'<div class="{cls}">'
+            f'<span class="dot">{dot_content}</span>'
+            f"<span>{label}</span>"
+            f"</div>"
+        )
+    return '<div class="progress-stepper">' + "".join(parts) + "</div>"

ui/final.py

@@ -1,27 +1,354 @@
-"""Final tab: Field Report generation and export."""
+"""Final tab / Chapter 6: Your Report — field report generation and export."""
 
 import gradio as gr
 
+from src.plot_config import COLORS
+
+
+# =====================================================================
+# Module-level HTML builders (callable from callbacks)
+# =====================================================================
+
+def build_report_html(state, data: dict) -> str:
+    """Build a presentation-ready styled HTML field report.
+
+    Parameters
+    ----------
+    state : AppState
+        Current application state with selected_line, backpack, achievements.
+    data : dict
+        Loaded data dictionary with line_stats, embedding, similarity, etc.
+
+    Returns
+    -------
+    str
+        Self-contained HTML string with inline CSS for portability.
+    """
+    if state is None or not state.selected_line:
+        return (
+            '<div style="text-align:center;padding:40px;color:#757575;">'
+            '<p style="font-size:16px;">No line selected yet.</p>'
+            '<p style="font-size:13px;">Go back to Chapter 0 to choose a line first.</p>'
+            "</div>"
+        )
+
+    line_id = state.selected_line
+    line_stats = data["line_stats"]
+    embedding = data["embedding"]
+    similarity = data["similarity"]
+    gene_freq = data["gene_freq"]
+    pav = data.get("pav")
+
+    # -- Gather stats --
+    ls_row = line_stats[line_stats["line_id"] == line_id]
+    country = ls_row.iloc[0]["country"] if len(ls_row) > 0 else "Unknown"
+    genes_present = int(ls_row.iloc[0]["genes_present_count"]) if len(ls_row) > 0 else 0
+    unique_genes = int(ls_row.iloc[0]["unique_genes_count"]) if len(ls_row) > 0 else 0
+
+    emb_row = embedding[embedding["line_id"] == line_id]
+    cluster_id = int(emb_row.iloc[0]["cluster_id"]) if len(emb_row) > 0 else -1
+
+    # Nearest neighbors
+    sim_rows = similarity[similarity["line_id"] == line_id].nlargest(3, "jaccard_score")
+    neighbors = [
+        (r["neighbor_line_id"], f"{r['jaccard_score']:.3f}")
+        for _, r in sim_rows.iterrows()
+    ]
+
+    # Core/shell/cloud breakdown
+    core_count = shell_count = cloud_count = 0
+    if pav is not None and line_id in pav.columns:
+        my_genes = set(pav.index[pav[line_id] == 1])
+        my_freq = gene_freq[gene_freq["gene_id"].isin(my_genes)]
+        core_count = int((my_freq["core_class"] == "core").sum())
+        shell_count = int((my_freq["core_class"] == "shell").sum())
+        cloud_count = int((my_freq["core_class"] == "cloud").sum())
+
+    # Rare genes
+    rare_rows = []
+    if pav is not None and line_id in pav.columns:
+        my_genes_list = pav.index[pav[line_id] == 1].tolist()
+        rare = gene_freq[
+            (gene_freq["gene_id"].isin(my_genes_list))
+            & (gene_freq["freq_count"] <= 5)
+        ].nsmallest(5, "freq_count")
+        for _, r in rare.iterrows():
+            rare_rows.append((r["gene_id"], int(r["freq_count"]), r["core_class"]))
+
+    # Backpack
+    backpack_rows = []
+    for g in (state.backpack_genes or []):
+        gf = gene_freq[gene_freq["gene_id"] == g]
+        if len(gf) > 0:
+            backpack_rows.append((g, gf.iloc[0]["core_class"], int(gf.iloc[0]["freq_count"])))
+        else:
+            backpack_rows.append((g, "unknown", 0))
+
+    # -- Build HTML --
+    # Metric cards row
+    metrics = [
+        (f"{genes_present:,}", "Genes Present", COLORS["core"]),
+        (str(unique_genes), "Unique Genes", COLORS["accent"]),
+        (str(cluster_id), "Cluster", COLORS["selected"]),
+        (str(len(state.backpack_genes)), "Backpack Genes", COLORS["shell"]),
+    ]
+    metric_cards = ""
+    for val, label, color in metrics:
+        metric_cards += (
+            f'<div style="flex:1;min-width:120px;background:#FFFFFF;border-radius:12px;'
+            f"padding:20px;text-align:center;border-top:3px solid {color};"
+            f'box-shadow:0 2px 8px rgba(0,0,0,0.06);">'
+            f'<div style="font-size:28px;font-weight:700;color:#1A1A1A;">{val}</div>'
+            f'<div style="font-size:11px;font-weight:600;text-transform:uppercase;'
+            f'letter-spacing:1px;color:#757575;margin-top:4px;">{label}</div>'
+            f"</div>"
+        )
+
+    # Neighbor rows
+    neighbor_html = ""
+    for name, score in neighbors:
+        neighbor_html += (
+            f'<div style="display:flex;justify-content:space-between;padding:8px 0;'
+            f'border-bottom:1px solid #F0F0E8;">'
+            f'<span style="font-weight:500;">{name}</span>'
+            f'<span style="color:#757575;font-family:monospace;">{score}</span>'
+            f"</div>"
+        )
+
+    # Composition bar
+    total_csc = core_count + shell_count + cloud_count
+    if total_csc > 0:
+        core_pct = core_count / total_csc * 100
+        shell_pct = shell_count / total_csc * 100
+        cloud_pct = cloud_count / total_csc * 100
+    else:
+        core_pct = shell_pct = cloud_pct = 0
+
+    composition_bar = (
+        f'<div style="display:flex;height:24px;border-radius:6px;overflow:hidden;margin:12px 0;">'
+        f'<div style="width:{core_pct:.1f}%;background:{COLORS["core"]};"></div>'
+        f'<div style="width:{shell_pct:.1f}%;background:{COLORS["shell"]};"></div>'
+        f'<div style="width:{cloud_pct:.1f}%;background:{COLORS["cloud"]};"></div>'
+        f"</div>"
+        f'<div style="display:flex;justify-content:space-between;font-size:12px;color:#757575;">'
+        f'<span style="color:{COLORS["core"]};font-weight:600;">Core: {core_count:,}</span>'
+        f'<span style="color:{COLORS["shell"]};font-weight:600;">Shell: {shell_count:,}</span>'
+        f'<span style="color:{COLORS["cloud"]};font-weight:600;">Cloud: {cloud_count:,}</span>'
+        f"</div>"
+    )
+
+    # Rare genes table
+    rare_html = ""
+    if rare_rows:
+        rare_html += (
+            '<table style="width:100%;border-collapse:collapse;font-size:13px;">'
+            '<tr style="border-bottom:2px solid #E0E0E0;">'
+            '<th style="text-align:left;padding:8px 4px;color:#757575;">Gene</th>'
+            '<th style="text-align:center;padding:8px 4px;color:#757575;">Lines</th>'
+            '<th style="text-align:center;padding:8px 4px;color:#757575;">Class</th>'
+            "</tr>"
+        )
+        for gene, count, cls in rare_rows:
+            badge_color = {"core": COLORS["core"], "shell": COLORS["shell"], "cloud": COLORS["cloud"]}.get(cls, "#9E9E9E")
+            badge_text_color = "#FFFFFF" if cls != "shell" else "#333333"
+            rare_html += (
+                f'<tr style="border-bottom:1px solid #F0F0E8;">'
+                f'<td style="padding:6px 4px;font-family:monospace;font-weight:500;">{gene}</td>'
+                f'<td style="text-align:center;padding:6px 4px;">{count}</td>'
+                f'<td style="text-align:center;padding:6px 4px;">'
+                f'<span style="display:inline-block;padding:2px 10px;border-radius:12px;'
+                f"font-size:11px;font-weight:600;background:{badge_color};color:{badge_text_color};"
+                f'">{cls}</span></td></tr>'
+            )
+        rare_html += "</table>"
+    else:
+        rare_html = '<p style="color:#757575;font-size:13px;">No rare genes (&le;5 lines) found.</p>'
+
+    # Backpack table
+    backpack_html = ""
+    if backpack_rows:
+        backpack_html += (
+            '<table style="width:100%;border-collapse:collapse;font-size:13px;">'
+            '<tr style="border-bottom:2px solid #E0E0E0;">'
+            '<th style="text-align:left;padding:8px 4px;color:#757575;">Gene</th>'
+            '<th style="text-align:center;padding:8px 4px;color:#757575;">Class</th>'
+            '<th style="text-align:center;padding:8px 4px;color:#757575;">Lines</th>'
+            "</tr>"
+        )
+        for gene, cls, count in backpack_rows:
+            badge_color = {"core": COLORS["core"], "shell": COLORS["shell"], "cloud": COLORS["cloud"]}.get(cls, "#9E9E9E")
+            badge_text_color = "#FFFFFF" if cls != "shell" else "#333333"
+            backpack_html += (
+                f'<tr style="border-bottom:1px solid #F0F0E8;">'
+                f'<td style="padding:6px 4px;font-family:monospace;font-weight:500;">{gene}</td>'
+                f'<td style="text-align:center;padding:6px 4px;">'
+                f'<span style="display:inline-block;padding:2px 10px;border-radius:12px;'
+                f"font-size:11px;font-weight:600;background:{badge_color};color:{badge_text_color};"
+                f'">{cls}</span></td>'
+                f'<td style="text-align:center;padding:6px 4px;">{count}</td>'
+                f"</tr>"
+            )
+        backpack_html += "</table>"
+    else:
+        backpack_html = '<p style="color:#757575;font-size:13px;">No genes pinned to backpack.</p>'
+
+    # Achievement pills
+    achievements_pills = ""
+    for a in sorted(state.achievements):
+        achievements_pills += (
+            f'<span style="display:inline-block;padding:6px 16px;border-radius:20px;'
+            f"background:linear-gradient(135deg, #D4A017, #F9A825);color:#333;"
+            f'font-weight:600;font-size:12px;margin:4px;box-shadow:0 2px 4px rgba(0,0,0,0.1);">'
+            f"{a}</span>"
+        )
+    if not achievements_pills:
+        achievements_pills = '<span style="color:#757575;font-size:13px;">No achievements yet</span>'
+
+    # -- Assemble full report --
+    html = f'''
+    <div style="font-family:-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                max-width:720px;margin:0 auto;">
+
+        <!-- Header -->
+        <div style="background:{COLORS["bg_dark"]};color:white;padding:32px 36px;
+                    border-radius:16px;margin-bottom:24px;">
+            <div style="font-size:12px;font-weight:600;text-transform:uppercase;
+                        letter-spacing:1.5px;color:{COLORS["text_muted"]};margin-bottom:8px;">
+                Field Report</div>
+            <h2 style="margin:0 0 6px 0;font-size:26px;font-weight:700;">{line_id}</h2>
+            <p style="margin:0;font-size:14px;color:{COLORS["text_muted"]};">
+                Origin: {country} &middot; Cluster {cluster_id}</p>
+        </div>
+
+        <!-- Metric cards -->
+        <div style="display:flex;gap:12px;margin-bottom:24px;flex-wrap:wrap;">
+            {metric_cards}
+        </div>
+
+        <!-- Nearest Neighbors -->
+        <div style="background:#FFFFFF;border-radius:12px;padding:20px 24px;
+                    box-shadow:0 2px 8px rgba(0,0,0,0.06);margin-bottom:16px;">
+            <h3 style="margin:0 0 12px 0;font-size:15px;font-weight:600;
+                       color:{COLORS["text_primary"]};">Nearest Neighbors</h3>
+            {neighbor_html}
+        </div>
+
+        <!-- Gene Composition -->
+        <div style="background:#FFFFFF;border-radius:12px;padding:20px 24px;
+                    box-shadow:0 2px 8px rgba(0,0,0,0.06);margin-bottom:16px;">
+            <h3 style="margin:0 0 12px 0;font-size:15px;font-weight:600;
+                       color:{COLORS["text_primary"]};">Gene Composition</h3>
+            {composition_bar}
+        </div>
+
+        <!-- Top 5 Rare Genes -->
+        <div style="background:#FFFFFF;border-radius:12px;padding:20px 24px;
+                    box-shadow:0 2px 8px rgba(0,0,0,0.06);margin-bottom:16px;">
+            <h3 style="margin:0 0 12px 0;font-size:15px;font-weight:600;
+                       color:{COLORS["text_primary"]};">Top 5 Rare Genes</h3>
+            {rare_html}
+        </div>
+
+        <!-- Backpack Collection -->
+        <div style="background:#FFFFFF;border-radius:12px;padding:20px 24px;
+                    box-shadow:0 2px 8px rgba(0,0,0,0.06);margin-bottom:16px;">
+            <h3 style="margin:0 0 12px 0;font-size:15px;font-weight:600;
+                       color:{COLORS["text_primary"]};">Backpack Collection</h3>
+            {backpack_html}
+        </div>
+
+        <!-- Achievements -->
+        <div style="background:#FFFFFF;border-radius:12px;padding:20px 24px;
+                    box-shadow:0 2px 8px rgba(0,0,0,0.06);margin-bottom:16px;">
+            <h3 style="margin:0 0 12px 0;font-size:15px;font-weight:600;
+                       color:{COLORS["text_primary"]};">Achievements Earned</h3>
+            <div>{achievements_pills}</div>
+        </div>
+
+        <!-- Footer -->
+        <div style="text-align:center;padding:16px 0;font-size:11px;color:#757575;">
+            Generated by Pigeon Pea Pangenome Atlas
+        </div>
+    </div>
+    '''
+    return html
+
+
+def build_achievements_html(state) -> str:
+    """Build styled HTML for achievement badges.
+
+    Parameters
+    ----------
+    state : AppState
+        Current application state.
+
+    Returns
+    -------
+    str
+        HTML string with styled badge pills.
+    """
+    if state is None or not state.achievements:
+        return (
+            '<div style="padding:12px;text-align:center;color:#757575;">'
+            "Complete quests to earn badges!</div>"
+        )
+
+    pills = []
+    for a in sorted(state.achievements):
+        pills.append(
+            f'<span class="achievement-badge">{a}</span>'
+        )
+    return '<div style="display:flex;flex-wrap:wrap;gap:6px;">' + "".join(pills) + "</div>"
+
+
+# =====================================================================
+# Gradio UI builder
+# =====================================================================
 
 def build_final_tab():
-    """Build Final Report tab components. Returns dict of components."""
-    with gr.Tab("Field Report", id="final") as tab:
-        gr.Markdown("## Your Exploration Report")
-        gr.Markdown(
-            "Generate a summary of your pangenome exploration journey, "
+    """Build Final Report tab components. Returns dict of components.
+
+    Returned keys (prefixed with ``final_`` by layout.py):
+        tab, generate_btn, report_md, download_json, download_csv, achievements_html
+    """
+    with gr.Tab("Your Report", id="final") as tab:
+        # -- Header --
+        gr.HTML(
+            '<div style="padding:4px 0 12px 0;">'
+            '<h2 style="margin:0 0 4px 0;font-size:22px;font-weight:700;'
+            f'color:{COLORS["text_primary"]};">Chapter 6: Your Report</h2>'
+            '<p style="margin:0;font-size:14px;color:#757575;line-height:1.5;">'
+            "Generate a presentation-ready summary of your pangenome exploration, "
             "including your selected line, findings, and backpack collection."
+            "</p></div>"
         )
 
-        generate_btn = gr.Button("Generate Report", variant="primary")
+        generate_btn = gr.Button(
+            "Generate Report",
+            variant="primary",
+            size="lg",
+        )
 
-        report_md = gr.Markdown(value="*Click 'Generate Report' to create your field report.*")
+        report_md = gr.Markdown(
+            value="*Click 'Generate Report' to create your field report.*"
+        )
 
         with gr.Row():
             download_json = gr.File(label="Download JSON", visible=False)
             download_csv = gr.File(label="Download CSV", visible=False)
 
-        gr.Markdown("### Achievements Earned")
-        achievements_html = gr.HTML(value="<p>Complete quests to earn badges!</p>")
+        gr.HTML(
+            '<div style="margin-top:16px;padding:4px 0;">'
+            '<h3 style="margin:0 0 4px 0;font-size:17px;font-weight:600;'
+            f'color:{COLORS["text_primary"]};">Achievements Earned</h3>'
+            "</div>"
+        )
+        achievements_html = gr.HTML(
+            value=(
+                '<div style="padding:12px;text-align:center;color:#757575;">'
+                "Complete quests to earn badges!</div>"
+            ),
+        )
 
     return {
         "tab": tab,

ui/gene_card_ui.py

@@ -1,21 +1,185 @@
-"""Gene Card side panel UI."""
+"""Gene Card side panel UI with premium card styling."""
 
 import gradio as gr
 
+from src.plot_config import COLORS
+
+
+# =====================================================================
+# Module-level HTML builders (callable from callbacks / gene_card.py)
+# =====================================================================
+
+def render_gene_card_premium(card: dict) -> str:
+    """Render a premium-styled Gene Card HTML from a card data dict.
+
+    Parameters
+    ----------
+    card : dict
+        Gene card data dict as returned by ``src.gene_card.build_gene_card()``.
+        Expected keys: gene_id, core_class, freq_count, freq_pct,
+        presence_vector, contig, start, end, strand, protein_length,
+        composition_summary.
+
+    Returns
+    -------
+    str
+        Self-contained HTML string with inline CSS.
+    """
+    gene_id = card.get("gene_id", "unknown")
+
+    # -- Core/shell/cloud pill badge --
+    cc = card.get("core_class", "unknown")
+    badge_styles = {
+        "core": (COLORS["core"], "#FFFFFF", "Core"),
+        "shell": (COLORS["shell"], "#333333", "Shell"),
+        "cloud": (COLORS["cloud"], "#FFFFFF", "Cloud"),
+    }
+    bg, fg, label = badge_styles.get(cc, ("#9E9E9E", "#FFFFFF", "Unknown"))
+    badge_html = (
+        f'<span style="display:inline-block;padding:3px 12px;border-radius:16px;'
+        f"font-size:11px;font-weight:700;background:{bg};color:{fg};"
+        f'letter-spacing:0.5px;vertical-align:middle;">{label}</span>'
+    )
+
+    # -- Gene ID header --
+    header_html = (
+        f'<div style="display:flex;align-items:center;gap:10px;margin-bottom:12px;">'
+        f'<span style="font-family:\'SF Mono\',SFMono-Regular,ui-monospace,Menlo,monospace;'
+        f"font-size:18px;font-weight:700;color:{COLORS['text_primary']};"
+        f'">{gene_id}</span>'
+        f"{badge_html}"
+        f"</div>"
+    )
+
+    # -- Frequency line --
+    freq_html = ""
+    if card.get("freq_count") is not None:
+        freq_html = (
+            f'<div style="font-size:13px;color:{COLORS["text_secondary"]};margin-bottom:14px;">'
+            f'Present in <span style="font-weight:600;color:{COLORS["text_primary"]};">'
+            f'{card["freq_count"]}</span> lines '
+            f'(<span style="font-weight:600;">{card["freq_pct"]:.1f}%</span>)'
+            f"</div>"
+        )
+
+    # -- Presence barcode (thicker 4px bars) --
+    barcode_html = ""
+    if card.get("presence_vector") is not None:
+        bars = []
+        for val in card["presence_vector"]:
+            color = COLORS["core"] if val == 1 else "#EEEEEE"
+            bars.append(
+                f'<span style="display:inline-block;width:4px;height:24px;'
+                f'background:{color};margin:0;border-radius:1px;"></span>'
+            )
+        barcode_html = (
+            f'<div style="margin-bottom:14px;">'
+            f'<div style="font-size:11px;font-weight:600;text-transform:uppercase;'
+            f'letter-spacing:1px;color:{COLORS["text_secondary"]};margin-bottom:6px;">'
+            f"Presence Barcode</div>"
+            f'<div style="display:flex;gap:1px;flex-wrap:wrap;">{"".join(bars)}</div>'
+            f"</div>"
+        )
+
+    # -- Location info --
+    if card.get("contig"):
+        contig_short = card["contig"]
+        if "|" in contig_short:
+            contig_short = contig_short.split("|")[-1]
+        location_html = (
+            f'<div style="margin-bottom:14px;">'
+            f'<div style="font-size:11px;font-weight:600;text-transform:uppercase;'
+            f'letter-spacing:1px;color:{COLORS["text_secondary"]};margin-bottom:6px;">'
+            f"Genomic Location</div>"
+            f'<div style="font-size:13px;line-height:1.6;">'
+            f'<div><span style="color:{COLORS["text_secondary"]};width:60px;display:inline-block;">'
+            f'Contig</span> <code style="background:#F5F5F0;padding:2px 6px;border-radius:4px;'
+            f'font-size:12px;">{contig_short}</code></div>'
+            f'<div><span style="color:{COLORS["text_secondary"]};width:60px;display:inline-block;">'
+            f'Position</span> <span style="font-weight:500;">{card["start"]:,} &ndash; '
+            f'{card["end"]:,}</span> '
+            f'<span style="color:{COLORS["text_secondary"]};">({card["strand"]})</span></div>'
+            f"</div></div>"
+        )
+    else:
+        location_html = (
+            f'<div style="margin-bottom:14px;font-size:13px;color:{COLORS["text_secondary"]};">'
+            f"<em>No coordinate annotation available</em></div>"
+        )
+
+    # -- Protein length --
+    protein_html = ""
+    if card.get("protein_length"):
+        protein_html = (
+            f'<div style="margin-bottom:14px;">'
+            f'<div style="font-size:11px;font-weight:600;text-transform:uppercase;'
+            f'letter-spacing:1px;color:{COLORS["text_secondary"]};margin-bottom:6px;">'
+            f"Protein</div>"
+            f'<div style="font-size:13px;">'
+            f'<span style="font-weight:600;font-size:20px;color:{COLORS["text_primary"]};">'
+            f'{card["protein_length"]}</span>'
+            f'<span style="color:{COLORS["text_secondary"]};margin-left:4px;">amino acids</span>'
+            f"</div></div>"
+        )
+    else:
+        protein_html = (
+            f'<div style="margin-bottom:14px;font-size:13px;color:{COLORS["text_secondary"]};">'
+            f"<em>No protein data available</em></div>"
+        )
+
+    # -- Assemble card --
+    return f'''
+    <div class="gene-card-panel" style="padding:20px;">
+        {header_html}
+        {freq_html}
+        {barcode_html}
+        {location_html}
+        {protein_html}
+    </div>
+    '''
+
+
+# =====================================================================
+# Gradio UI builder
+# =====================================================================
 
 def build_gene_card_panel():
-    """Build Gene Card side panel. Returns dict of components."""
+    """Build Gene Card side panel. Returns dict of components.
+
+    Returned keys (prefixed with ``gc_`` by layout.py):
+        column, gene_card_html, show_genome_btn, show_protein_btn,
+        pin_card_btn, download_gene_btn, gene_report_file
+    """
     with gr.Column(visible=False, scale=1) as gene_card_col:
-        gr.Markdown("### Gene Card")
+        gr.HTML(
+            '<div style="font-size:15px;font-weight:700;margin-bottom:4px;'
+            f'color:{COLORS["text_primary"]};">Gene Card</div>'
+        )
+
         gene_card_html = gr.HTML(value="")
 
         with gr.Row():
-            show_genome_btn = gr.Button("Show on Genome", size="sm")
-            show_protein_btn = gr.Button("Show Protein", size="sm")
+            show_genome_btn = gr.Button(
+                "Show on Genome",
+                size="sm",
+                variant="secondary",
+            )
+            show_protein_btn = gr.Button(
+                "Show Protein",
+                size="sm",
+                variant="secondary",
+            )
 
         with gr.Row():
-            pin_card_btn = gr.Button("Pin to Backpack", size="sm", variant="secondary")
-            download_gene_btn = gr.Button("Download Report", size="sm")
+            pin_card_btn = gr.Button(
+                "Pin to Backpack",
+                size="sm",
+                variant="secondary",
+            )
+            download_gene_btn = gr.Button(
+                "Download Report",
+                size="sm",
+            )
 
         gene_report_file = gr.File(label="Gene Report", visible=False)
 

ui/layout.py

@@ -34,25 +34,6 @@ def build_app(line_choices: list[str], contig_choices: list[str],
             elem_classes=["progress-tracker"],
         )
 
-        # Global filters
-        with gr.Accordion("Global Filters", open=False):
-            with gr.Row():
-                country_filter = gr.CheckboxGroup(
-                    choices=[],
-                    label="Filter by country",
-                    info="Leave empty to show all",
-                )
-                annotated_toggle = gr.Checkbox(
-                    label="Only annotated genes (with GFF entry)",
-                    value=False,
-                )
-            with gr.Accordion("What is PAV?", open=False):
-                gr.Markdown(
-                    "**Presence-Absence Variation (PAV)** describes genes that are present "
-                    "in some lines but absent from others. The pangenome captures all genes "
-                    "across the species, not just those in a single reference genome."
-                )
-
         # Main content area
         with gr.Row():
             # Main tabs (left ~75%)
@@ -76,8 +57,6 @@ def build_app(line_choices: list[str], contig_choices: list[str],
         "state": state,
         "progress_html": progress_html,
         "tabs": tabs,
-        "country_filter": country_filter,
-        "annotated_toggle": annotated_toggle,
         "data_health_html": data_health_html,
         **{f"q0_{k}": v for k, v in q0.items()},
         **{f"q1_{k}": v for k, v in q1.items()},
@@ -94,12 +73,12 @@ def build_app(line_choices: list[str], contig_choices: list[str],
 def _build_progress_html(active_quest: int) -> str:
     """Build progress tracker HTML."""
     steps = [
-        ("Explorer", 0),
-        ("Map the World", 1),
-        ("Core vs Accessory", 2),
-        ("Genome Landmarks", 3),
-        ("Protein Relics", 4),
-        ("Field Report", 5),
+        ("Origins", 0),
+        ("Genetic Landscape", 1),
+        ("Gene Universe", 2),
+        ("Genome Explorer", 3),
+        ("Protein World", 4),
+        ("Your Report", 5),
     ]
     parts = []
     for label, idx in steps:

ui/quest0.py

@@ -1,54 +1,194 @@
-"""Quest 0: Choose Your Explorer — line selection and overview."""
+"""Quest 0 — Chapter 1: Origins.
+
+Hero header, interactive 3D globe of line origins, line selection
+with metric cards, and a 'Begin Exploration' call to action.
+"""
 
 import gradio as gr
+import plotly.graph_objects as go
+
+from src.plot_config import COLORS, COUNTRY_COLORS, apply_template
+from src.utils import COUNTRY_COORDS, build_hero_header, build_metric_card
+
+
+# =====================================================================
+# Standalone figure builder — importable by callbacks.py
+# =====================================================================
+
+def build_globe_figure(line_stats_df):
+    """Build a 3D orthographic globe showing pigeon pea line origins.
+
+    Parameters
+    ----------
+    line_stats_df : pandas.DataFrame
+        Must contain at least a ``country`` column.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    country_counts = line_stats_df.groupby("country").size().reset_index(name="count")
+
+    fig = go.Figure()
+    for _, row in country_counts.iterrows():
+        country = row["country"]
+        count = row["count"]
+        if country in COUNTRY_COORDS:
+            lat, lon = COUNTRY_COORDS[country]
+            fig.add_trace(go.Scattergeo(
+                lat=[lat],
+                lon=[lon],
+                text=f"{country}: {count} lines",
+                hoverinfo="text",
+                marker=dict(
+                    size=max(8, count ** 0.5 * 5),
+                    color=COUNTRY_COLORS.get(country, "#9E9E9E"),
+                    opacity=0.9,
+                    line=dict(width=1.5, color="white"),
+                ),
+                name=country,
+                showlegend=True,
+            ))
+
+    fig.update_geos(
+        projection_type="orthographic",
+        showocean=True, oceancolor=COLORS["bg_dark"],
+        showland=True, landcolor="#2a3a4a",
+        showcoastlines=True, coastlinecolor="#4a5a6a",
+        showcountries=True, countrycolor="#3a4a5a",
+        showlakes=False,
+        bgcolor=COLORS["bg_dark"],
+        projection_rotation=dict(lon=78, lat=20),  # Centre on India
+    )
+
+    fig.update_layout(
+        height=500,
+        margin=dict(l=0, r=0, t=0, b=0),
+        paper_bgcolor=COLORS["bg_dark"],
+        geo=dict(bgcolor=COLORS["bg_dark"]),
+        legend=dict(
+            bgcolor="rgba(26,35,50,0.85)",
+            font=dict(color="#E0E0E0", size=11),
+            bordercolor="rgba(0,0,0,0)",
+            x=0.02,
+            y=0.98,
+        ),
+        showlegend=True,
+    )
+    return fig
+
 
+def _empty_globe():
+    """Return a minimal placeholder globe before data is loaded."""
+    fig = go.Figure(go.Scattergeo())
+    fig.update_geos(
+        projection_type="orthographic",
+        showocean=True, oceancolor=COLORS["bg_dark"],
+        showland=True, landcolor="#2a3a4a",
+        showcoastlines=True, coastlinecolor="#4a5a6a",
+        showcountries=True, countrycolor="#3a4a5a",
+        showlakes=False,
+        bgcolor=COLORS["bg_dark"],
+        projection_rotation=dict(lon=78, lat=20),
+    )
+    fig.update_layout(
+        height=500,
+        margin=dict(l=0, r=0, t=0, b=0),
+        paper_bgcolor=COLORS["bg_dark"],
+        geo=dict(bgcolor=COLORS["bg_dark"]),
+    )
+    return fig
+
+
+# =====================================================================
+# Build the Gradio tab
+# =====================================================================
 
 def build_quest0(line_choices: list[str]):
-    """Build Quest 0 tab components. Returns dict of components."""
-    with gr.Tab("Choose Your Explorer", id="quest0") as tab:
-        gr.Markdown("## Choose your line to explore")
-        gr.Markdown(
-            "Select one of the 89 pigeon pea lines to begin your pangenome journey. "
-            "Each line has a unique gene repertoire shaped by geography and breeding history."
+    """Build Quest 0 tab components. Returns dict of components.
+
+    The returned dictionary keys **must** match the original contract so
+    that ``layout.py`` can prefix them with ``q0_`` and ``app.py`` can
+    wire callbacks without changes.
+
+    Keys: tab, line_dropdown, total_genes, unique_genes,
+          nearest_neighbor, start_btn
+    """
+    with gr.Tab("Origins", id="quest0") as tab:
+
+        # -- A) Hero header --------------------------------------------------
+        hero_html = gr.HTML(
+            value=build_hero_header(
+                total_genes=55_512,
+                n_lines=90,
+                n_countries=17,
+                n_clusters=3,
+            ),
         )
 
-        line_dropdown = gr.Dropdown(
-            choices=line_choices,
-            label="Select a pigeon pea line",
-            info="89 lines from across the world",
-            interactive=True,
+        # -- B) Interactive 3D globe -----------------------------------------
+        globe_plot = gr.Plot(
+            value=_empty_globe(),
+            label="Origins Globe",
         )
 
+        gr.HTML(
+            '<p style="text-align:center; color:#757575; font-size:13px; '
+            'margin-top:-8px; margin-bottom:16px;">'
+            "Drag to rotate the globe. Click a country in the legend to filter lines."
+            "</p>"
+        )
+
+        # -- C) Country filter + Line selection --------------------------------
         with gr.Row():
-            total_genes_box = gr.Textbox(
+            country_dropdown = gr.Dropdown(
+                choices=["All countries"] + sorted(COUNTRY_COORDS.keys()),
+                value="All countries",
+                label="Filter by country",
+                interactive=True,
+                scale=1,
+            )
+            line_dropdown = gr.Dropdown(
+                choices=line_choices,
+                label="Select a pigeon pea line",
+                info="90 lines from 17 countries",
+                interactive=True,
+                scale=2,
+            )
+
+        with gr.Row(equal_height=True):
+            total_genes_html = gr.Textbox(
                 label="Total Genes Present",
                 interactive=False,
                 value="--",
             )
-            unique_genes_box = gr.Textbox(
+            unique_genes_html = gr.Textbox(
                 label="Unique Genes",
                 interactive=False,
                 value="--",
                 info="Genes found only in this line",
             )
-            nearest_neighbor_box = gr.Textbox(
+            nearest_neighbor_html = gr.Textbox(
                 label="Nearest Neighbor",
                 interactive=False,
                 value="--",
                 info="Most similar line by gene content",
             )
 
+        # -- "Begin Exploration" button ---------------------------------------
         start_btn = gr.Button(
-            "Start the Journey",
+            "Begin Exploration",
             variant="primary",
             size="lg",
         )
 
     return {
         "tab": tab,
+        "globe_plot": globe_plot,
+        "country_dropdown": country_dropdown,
         "line_dropdown": line_dropdown,
-        "total_genes": total_genes_box,
-        "unique_genes": unique_genes_box,
-        "nearest_neighbor": nearest_neighbor_box,
+        "total_genes": total_genes_html,
+        "unique_genes": unique_genes_html,
+        "nearest_neighbor": nearest_neighbor_html,
         "start_btn": start_btn,
     }

ui/quest1.py

@@ -1,17 +1,188 @@
-"""Quest 1: Map the World — UMAP scatter of lines."""
+"""Quest 1 — Chapter 2: Genetic Landscape.
+
+3D UMAP constellation of 90 pigeon pea lines, colored by country or
+cluster, with comparison tools and neighbor list.
+"""
 
 import gradio as gr
+import plotly.graph_objects as go
+
+from src.plot_config import (
+    COLORS, COUNTRY_COLORS, CLUSTER_COLORS, apply_template,
+)
+
+
+# =====================================================================
+# Standalone figure builder — importable by callbacks.py
+# =====================================================================
+
+def build_umap_3d(embedding_df, line_stats_df,
+                  color_by="country", selected_line=None):
+    """Build a 3D UMAP scatter with constellation effect.
+
+    If the embedding only contains 2D coordinates (``umap_x``, ``umap_y``),
+    the third axis is set to zero so the visualisation still renders
+    correctly (it will appear flat until a 3D embedding is computed).
+
+    Parameters
+    ----------
+    embedding_df : pandas.DataFrame
+        Must contain ``line_id``, ``umap_x``, ``umap_y``, and optionally
+        ``umap_z`` and ``cluster_id``.
+    line_stats_df : pandas.DataFrame
+        Must contain ``line_id`` and ``country``.
+    color_by : str
+        ``'country'`` or ``'cluster'``.
+    selected_line : str or None
+        Line to highlight with a gold diamond.
+
+    Returns
+    -------
+    plotly.graph_objects.Figure
+    """
+    df = embedding_df.merge(
+        line_stats_df[["line_id", "country"]], on="line_id", how="left",
+    )
+    df["country"] = df["country"].fillna("Unknown")
+
+    # Gracefully handle missing umap_z
+    if "umap_z" not in df.columns:
+        df["umap_z"] = 0.0
+
+    fig = go.Figure()
+
+    if color_by == "country":
+        for country in sorted(df["country"].unique()):
+            mask = df["country"] == country
+            subset = df[mask]
+            fig.add_trace(go.Scatter3d(
+                x=subset["umap_x"],
+                y=subset["umap_y"],
+                z=subset["umap_z"],
+                mode="markers",
+                marker=dict(
+                    size=5,
+                    color=COUNTRY_COLORS.get(country, "#9E9E9E"),
+                    opacity=0.85,
+                    line=dict(width=1, color="white"),
+                ),
+                name=country,
+                text=subset["line_id"],
+                hovertemplate="%{text}<br>Country: " + country + "<extra></extra>",
+            ))
+    else:  # cluster
+        if "cluster_id" not in df.columns:
+            df["cluster_id"] = 0
+        for cid in sorted(df["cluster_id"].unique()):
+            mask = df["cluster_id"] == cid
+            subset = df[mask]
+            color = CLUSTER_COLORS[int(cid)] if int(cid) < len(CLUSTER_COLORS) else "#9E9E9E"
+            fig.add_trace(go.Scatter3d(
+                x=subset["umap_x"],
+                y=subset["umap_y"],
+                z=subset["umap_z"],
+                mode="markers",
+                marker=dict(
+                    size=5,
+                    color=color,
+                    opacity=0.85,
+                    line=dict(width=1, color="white"),
+                ),
+                name=f"Cluster {cid}",
+                text=subset["line_id"],
+                hovertemplate="%{text}<br>Cluster: " + str(cid) + "<extra></extra>",
+            ))
+
+    # Highlight selected line
+    if selected_line and selected_line in df["line_id"].values:
+        sel = df[df["line_id"] == selected_line].iloc[0]
+        fig.add_trace(go.Scatter3d(
+            x=[sel["umap_x"]],
+            y=[sel["umap_y"]],
+            z=[sel["umap_z"]],
+            mode="markers+text",
+            marker=dict(
+                size=12,
+                color=COLORS["selected"],
+                symbol="diamond",
+                line=dict(width=2, color="white"),
+            ),
+            text=[selected_line],
+            textposition="top center",
+            name="Your Line",
+            hovertemplate=selected_line + "<extra></extra>",
+        ))
 
+    fig.update_layout(
+        scene=dict(
+            xaxis=dict(showgrid=False, showticklabels=False, title="",
+                       showbackground=False),
+            yaxis=dict(showgrid=False, showticklabels=False, title="",
+                       showbackground=False),
+            zaxis=dict(showgrid=False, showticklabels=False, title="",
+                       showbackground=False),
+            bgcolor=COLORS["bg_dark"],
+        ),
+        paper_bgcolor=COLORS["bg_dark"],
+        height=550,
+        margin=dict(l=0, r=0, t=30, b=0),
+        legend=dict(
+            bgcolor="rgba(26,35,50,0.85)",
+            font=dict(color="#E0E0E0"),
+        ),
+    )
+    return fig
+
+
+def _empty_umap_3d():
+    """Return a minimal placeholder 3D scatter before data is loaded."""
+    fig = go.Figure(go.Scatter3d(x=[0], y=[0], z=[0], mode="markers",
+                                  marker=dict(size=1, opacity=0)))
+    fig.update_layout(
+        scene=dict(
+            xaxis=dict(showgrid=False, showticklabels=False, title="",
+                       showbackground=False),
+            yaxis=dict(showgrid=False, showticklabels=False, title="",
+                       showbackground=False),
+            zaxis=dict(showgrid=False, showticklabels=False, title="",
+                       showbackground=False),
+            bgcolor=COLORS["bg_dark"],
+        ),
+        paper_bgcolor=COLORS["bg_dark"],
+        height=550,
+        margin=dict(l=0, r=0, t=30, b=0),
+    )
+    return fig
+
+
+# =====================================================================
+# Build the Gradio tab
+# =====================================================================
 
 def build_quest1():
-    """Build Quest 1 tab components. Returns dict of components."""
-    with gr.Tab("Map the World", id="quest1") as tab:
-        gr.Markdown("## How do 89 lines relate by gene content?")
-        gr.Markdown(
-            "This UMAP projection arranges lines by their gene presence/absence profiles. "
-            "Lines closer together share more genes."
+    """Build Quest 1 tab components. Returns dict of components.
+
+    The returned dictionary keys **must** match the original contract so
+    that ``layout.py`` can prefix them with ``q1_`` and ``app.py`` can
+    wire callbacks without changes.
+
+    Keys: tab, color_radio, umap_plot, party_display,
+          compare_btn, comparison_plot
+    """
+    with gr.Tab("Genetic Landscape", id="quest1") as tab:
+
+        gr.HTML(
+            '<h2 style="margin:0 0 4px 0; font-size:22px; font-weight:700; '
+            'color:#1A1A1A;">'
+            "Genetic Landscape"
+            "</h2>"
+            '<p style="color:#757575; font-size:14px; margin:0 0 16px 0;">'
+            "Each point is a breeding line. Lines closer together share "
+            "more genes."
+            "</p>"
         )
 
+        # -- A) Color-by control ---------------------------------------------
         color_radio = gr.Radio(
             choices=["Country", "Cluster"],
             value="Country",
@@ -19,8 +190,21 @@ def build_quest1():
             interactive=True,
         )
 
-        umap_plot = gr.Plot(label="UMAP of 89 pigeon pea lines")
+        # -- B) 3D UMAP constellation ----------------------------------------
+        umap_plot = gr.Plot(
+            value=_empty_umap_3d(),
+            label="UMAP of 90 pigeon pea lines",
+        )
 
+        gr.HTML(
+            '<p style="text-align:center; color:#757575; font-size:13px; '
+            'margin-top:-8px; margin-bottom:16px;">'
+            "Drag to rotate. Hover for line details. "
+            "Switch coloring above to explore country or cluster groupings."
+            "</p>"
+        )
+
+        # -- C) Neighbor list + comparison ------------------------------------
         with gr.Row():
             party_display = gr.Textbox(
                 label="Selected party (lasso/click to select)",
@@ -28,19 +212,28 @@ def build_quest1():
                 value="None selected",
                 lines=2,
             )
-            compare_btn = gr.Button("Compare my line to party", variant="secondary")
+            compare_btn = gr.Button(
+                "Compare my line to party",
+                variant="secondary",
+            )
 
         comparison_plot = gr.Plot(label="Comparison", visible=False)
 
         with gr.Accordion("What does this mean?", open=False):
-            gr.Markdown(
-                "**UMAP** reduces the high-dimensional PAV matrix to 2D.\n\n"
-                "- **Country coloring** shows geographic origins.\n"
-                "- **Cluster coloring** shows groups identified by KMeans.\n"
-                "- **Click** a point to see its stats.\n"
-                "- **Lasso select** multiple points to compare with your chosen line."
+            gr.HTML(
+                '<div style="padding:8px 12px; line-height:1.7; '
+                'color:#1A1A1A; font-size:14px;">'
+                "<b>UMAP</b> reduces the high-dimensional PAV matrix so "
+                "that similar lines appear close together.<br>"
+                "<b>Country coloring</b> reveals geographic origins.<br>"
+                "<b>Cluster coloring</b> shows groups identified by "
+                "KMeans (k=3, silhouette=0.649).<br>"
+                "Click a point to see its stats; lasso-select multiple "
+                "points to compare with your chosen line."
+                "</div>"
             )
 
+    # Return same keys as original for backward compatibility
     return {
         "tab": tab,
         "color_radio": color_radio,

ui/quest2.py

@@ -1,17 +1,151 @@
-"""Quest 2: Core vs Accessory — gene classification explorer."""
+"""Quest 2: Gene Universe — Core / Shell / Cloud classification explorer.
 
+Features a Sunburst hero chart with adjustable thresholds, frequency
+histogram, and a gene treasure table with pin-to-backpack support.
+"""
+
+import json
 import gradio as gr
+import plotly.graph_objects as go
+
+from src.utils import PRECOMPUTED_DIR
+from src.plot_config import COLORS, apply_template
+
+# ---------------------------------------------------------------------------
+# Load sunburst hierarchy once at import time
+# ---------------------------------------------------------------------------
+_SUNBURST_PATH = PRECOMPUTED_DIR / "sunburst_hierarchy.json"
+_SUNBURST_DATA: dict | None = None
+if _SUNBURST_PATH.exists():
+    with open(_SUNBURST_PATH) as _f:
+        _SUNBURST_DATA = json.load(_f)
+
+
+# ---------------------------------------------------------------------------
+# Standalone chart builders (callable from callbacks / app.py)
+# ---------------------------------------------------------------------------
+
+def build_sunburst_figure(sunburst_data=None, gene_freq_df=None, state=None,
+                          core_thresh=95, cloud_thresh=15):
+    """Build the gene-universe sunburst chart.
+
+    Parameters
+    ----------
+    sunburst_data : dict or None
+        Pre-loaded hierarchy dict with keys ``ids``, ``labels``, ``parents``,
+        ``values``.  Falls back to the module-level ``_SUNBURST_DATA``.
+    gene_freq_df : DataFrame or None
+        If provided the counts are recomputed live from the frequency column
+        using the given thresholds.
+    core_thresh, cloud_thresh : float
+        Percentage thresholds for core (>=) and cloud (<).
+    """
+    if sunburst_data is None:
+        sunburst_data = _SUNBURST_DATA
+
+    # Recompute counts based on thresholds when live data is available
+    if gene_freq_df is not None:
+        core_count = int((gene_freq_df["freq_pct"] >= core_thresh).sum())
+        cloud_count = int((gene_freq_df["freq_pct"] < cloud_thresh).sum())
+        shell_count = len(gene_freq_df) - core_count - cloud_count
+        total = len(gene_freq_df)
+        ids = ["total", "core", "shell", "cloud"]
+        labels = [
+            "All Genes",
+            f"Core ({core_count:,})",
+            f"Shell ({shell_count:,})",
+            f"Cloud ({cloud_count:,})",
+        ]
+        parents = ["", "total", "total", "total"]
+        values = [total, core_count, shell_count, cloud_count]
+    elif sunburst_data is not None:
+        ids = sunburst_data["ids"]
+        labels = sunburst_data["labels"]
+        parents = sunburst_data["parents"]
+        values = sunburst_data["values"]
+    else:
+        # Fallback — empty figure
+        fig = go.Figure()
+        fig.add_annotation(text="Sunburst data not available", showarrow=False)
+        return fig
 
+    fig = go.Figure(go.Sunburst(
+        ids=ids,
+        labels=labels,
+        parents=parents,
+        values=values,
+        branchvalues="total",
+        marker=dict(colors=[
+            COLORS["bg_light"],  # root ring
+            COLORS["core"],
+            COLORS["shell"],
+            COLORS["cloud"],
+        ]),
+        textinfo="label+percent parent",
+        hovertemplate=(
+            "<b>%{label}</b><br>"
+            "%{value:,} genes<br>"
+            "%{percentParent:.1%} of total"
+            "<extra></extra>"
+        ),
+        insidetextorientation="radial",
+    ))
+    fig.update_layout(
+        height=450,
+        margin=dict(l=10, r=10, t=10, b=10),
+        paper_bgcolor="rgba(0,0,0,0)",
+    )
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Infographic header HTML
+# ---------------------------------------------------------------------------
+
+_INFOGRAPHIC_HTML = """
+<div style="display:flex;gap:24px;justify-content:center;padding:20px;">
+  <div style="text-align:center;">
+    <span style="color:#2E7D32;font-size:28px;">\u25cf</span>
+    <div style="font-weight:700;">Core (\u226595%)</div>
+    <div style="color:#757575;font-size:13px;">Essential genes shared by nearly all lines</div>
+  </div>
+  <div style="text-align:center;">
+    <span style="color:#F9A825;font-size:28px;">\u25cf</span>
+    <div style="font-weight:700;">Shell (15\u201395%)</div>
+    <div style="color:#757575;font-size:13px;">Group-specific genes found in subsets</div>
+  </div>
+  <div style="text-align:center;">
+    <span style="color:#C62828;font-size:28px;">\u25cf</span>
+    <div style="font-weight:700;">Cloud (&lt;15%)</div>
+    <div style="color:#757575;font-size:13px;">Rare genes unique to few lines</div>
+  </div>
+</div>
+""".strip()
+
+
+# ---------------------------------------------------------------------------
+# Tab builder
+# ---------------------------------------------------------------------------
 
 def build_quest2():
-    """Build Quest 2 tab components. Returns dict of components."""
-    with gr.Tab("Core vs Accessory", id="quest2") as tab:
-        gr.Markdown("## Explore the Core, Shell, and Cloud genome")
-        gr.Markdown(
-            "Genes are classified by how many of the 89 lines carry them. "
-            "Adjust the thresholds to explore different definitions."
+    """Build Quest 2 tab components.
+
+    Returns a dict whose keys match the original wiring contract:
+        tab, core_slider, cloud_slider, donut_plot, histogram_plot,
+        filter_radio, treasure_table, selected_gene_text, pin_btn,
+        backpack_display
+    """
+    with gr.Tab("Gene Universe", id="quest2") as tab:
+        # --- A) Infographic header ---
+        gr.HTML(value=_INFOGRAPHIC_HTML)
+
+        # --- B) Sunburst hero chart ---
+        donut_plot = gr.Plot(
+            label="Gene Universe Sunburst",
+            value=build_sunburst_figure(),
         )
 
+        # --- C) Threshold sliders ---
         with gr.Row():
             core_slider = gr.Slider(
                 minimum=50, maximum=100, value=95, step=1,
@@ -24,10 +158,10 @@ def build_quest2():
                 info="Genes present in fewer than this % of lines",
             )
 
-        with gr.Row():
-            donut_plot = gr.Plot(label="Core / Shell / Cloud distribution")
-            histogram_plot = gr.Plot(label="Gene frequency distribution")
+        # --- D) Frequency histogram ---
+        histogram_plot = gr.Plot(label="Gene frequency distribution")
 
+        # --- E) Treasure table + gene selection + backpack ---
         gr.Markdown("### Gene Treasure List")
         filter_radio = gr.Radio(
             choices=["All", "Unique to my line", "Rare (<5 lines)", "Cluster markers"],

ui/quest3.py

@@ -1,26 +1,171 @@
-"""Quest 3: Genome Landmarks — hotspot exploration."""
+"""Quest 3: Genome Explorer — Circos-style polar ring chart and contig drill-down.
 
+Features a circular genome overview showing variability hotspots across
+contigs, plus a linear gene-track view when drilling into a single contig.
+"""
+
+import json
 import gradio as gr
+import plotly.graph_objects as go
+
+from src.utils import PRECOMPUTED_DIR
+from src.plot_config import COLORS, apply_template
+
+# ---------------------------------------------------------------------------
+# Load polar contig layout once at import time
+# ---------------------------------------------------------------------------
+_POLAR_PATH = PRECOMPUTED_DIR / "polar_contig_layout.json"
+_POLAR_DATA: list | None = None
+if _POLAR_PATH.exists():
+    with open(_POLAR_PATH) as _f:
+        _POLAR_DATA = json.load(_f)
+
+
+# ---------------------------------------------------------------------------
+# Standalone chart builder (callable from callbacks / app.py)
+# ---------------------------------------------------------------------------
+
+def build_circos_figure(polar_layout=None):
+    """Build a Circos-style circular genome plot.
+
+    Parameters
+    ----------
+    polar_layout : list or None
+        List of contig dicts from ``polar_contig_layout.json``.  Falls back
+        to the module-level ``_POLAR_DATA`` when *None*.
+    """
+    if polar_layout is None:
+        polar_layout = _POLAR_DATA
+
+    if not polar_layout:
+        fig = go.Figure()
+        fig.add_annotation(text="Polar layout data not available", showarrow=False)
+        return fig
+
+    fig = go.Figure()
+
+    for contig in polar_layout:
+        contig_id = contig["contig_id"]
+        # Truncate contig name for readability
+        short_name = (
+            contig_id.split("|")[-2]
+            if "|" in contig_id
+            else contig_id[-15:]
+        )
+
+        n_bins = max(len(contig["bins"]), 1)
+        bin_width = (contig["theta_end"] - contig["theta_start"]) / n_bins
+
+        # Add bins as polar bars
+        for b in contig["bins"]:
+            score = b.get("variability_score", 0)
+            # Color by variability: green -> amber -> red
+            if score == 0:
+                color = COLORS["core"]
+            elif score < 2:
+                color = COLORS["shell"]
+            else:
+                color = COLORS["cloud"]
 
+            fig.add_trace(go.Barpolar(
+                r=[b["total_genes"]],
+                theta=[b["theta"]],
+                width=[bin_width],
+                marker_color=color,
+                marker_line_color="rgba(255,255,255,0.3)",
+                marker_line_width=0.5,
+                opacity=0.85,
+                hovertemplate=(
+                    f"{short_name}<br>"
+                    f"Genes: %{{r}}<br>"
+                    f"Score: {score:.1f}"
+                    "<extra></extra>"
+                ),
+                showlegend=False,
+            ))
+
+        # Add a contig label at the midpoint
+        mid_theta = (contig["theta_start"] + contig["theta_end"]) / 2
+        max_r = (
+            max(b["total_genes"] for b in contig["bins"]) + 3
+            if contig["bins"]
+            else 5
+        )
+        fig.add_trace(go.Scatterpolar(
+            r=[max_r],
+            theta=[mid_theta],
+            mode="text",
+            text=[short_name],
+            textfont=dict(size=8, color=COLORS["text_secondary"]),
+            showlegend=False,
+            hoverinfo="skip",
+        ))
+
+    fig.update_layout(
+        polar=dict(
+            bgcolor="rgba(0,0,0,0)",
+            radialaxis=dict(showticklabels=False, showline=False, showgrid=False),
+            angularaxis=dict(
+                showticklabels=False,
+                showline=False,
+                showgrid=False,
+                direction="clockwise",
+            ),
+        ),
+        height=500,
+        margin=dict(l=20, r=20, t=20, b=20),
+        paper_bgcolor="rgba(0,0,0,0)",
+        showlegend=False,
+    )
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Explanation header HTML
+# ---------------------------------------------------------------------------
+
+_EXPLANATION_HTML = (
+    '<div style="padding:12px 20px;color:#424242;font-size:14px;line-height:1.6;">'
+    "Where in the genome does genetic diversity concentrate? "
+    "The outer ring shows variability &mdash; "
+    '<span style="color:#C62828;font-weight:600;">red</span> regions are hotspots '
+    "with rare or variable genes, "
+    '<span style="color:#F9A825;font-weight:600;">amber</span> marks moderate variation, '
+    "and "
+    '<span style="color:#2E7D32;font-weight:600;">green</span> regions are conserved.'
+    "</div>"
+)
+
+
+# ---------------------------------------------------------------------------
+# Tab builder
+# ---------------------------------------------------------------------------
 
 def build_quest3(contig_choices: list[str]):
-    """Build Quest 3 tab components. Returns dict of components."""
-    with gr.Tab("Genome Landmarks", id="quest3") as tab:
-        gr.Markdown("## Explore genomic hotspots of variation")
-        gr.Markdown(
-            "The genome is divided into 100 kb bins. Hotter bins contain more "
-            "variable (shell/cloud) genes — potential regions of adaptation."
+    """Build Quest 3 tab components.
+
+    Returns a dict whose keys match the original wiring contract:
+        tab, contig_dropdown, heatmap_plot, track_plot, region_table,
+        region_gene_text
+    """
+    with gr.Tab("Genome Explorer", id="quest3") as tab:
+        # --- A) Explanation header ---
+        gr.HTML(value=_EXPLANATION_HTML)
+
+        # --- B) Circos-style polar ring chart (replaces old heatmap hero) ---
+        heatmap_plot = gr.Plot(
+            label="Circular Genome Overview",
+            value=build_circos_figure(),
         )
 
+        # --- C) Contig drill-down ---
+        gr.Markdown("### Contig Detail")
         contig_dropdown = gr.Dropdown(
             choices=contig_choices,
             label="Select contig (top contigs by gene count)",
             interactive=True,
         )
 
-        heatmap_plot = gr.Plot(label="Variability heatmap (contigs x bins)")
-
-        gr.Markdown("### Contig Detail")
         track_plot = gr.Plot(label="Gene track (colored by class)", visible=False)
 
         region_table = gr.Dataframe(

ui/quest4.py

@@ -1,34 +1,218 @@
-"""Quest 4: Protein Relics — protein analysis."""
+"""Quest 4 / Chapter 5: Protein World — protein analysis with radar charts."""
+
+import json
+from pathlib import Path
 
 import gradio as gr
+import plotly.graph_objects as go
+
+from src.plot_config import COLORS, apply_template
+from src.utils import PRECOMPUTED_DIR
+
+
+# =====================================================================
+# Module-level helpers (callable from callbacks)
+# =====================================================================
+
+def _load_radar_axes() -> dict:
+    """Load radar axes configuration from precomputed JSON."""
+    path = PRECOMPUTED_DIR / "radar_axes.json"
+    if path.exists():
+        with open(path) as f:
+            return json.load(f)
+    # Fallback: top 10 common amino acids with reasonable defaults
+    return {
+        "axes": ["L", "S", "E", "A", "K", "V", "G", "R", "P", "I"],
+        "global_mean": {
+            "L": 8.6, "S": 6.7, "E": 3.9, "A": 3.8, "K": 3.5,
+            "V": 3.4, "G": 3.2, "R": 2.9, "P": 1.9, "I": 1.8,
+        },
+    }
+
+
+# Cache at module level so it is loaded once
+_RADAR_AXES = _load_radar_axes()
+
+
+def parse_composition(comp_summary: str) -> dict[str, float]:
+    """Parse composition_summary string like 'A:15.1%, S:9.2%, ...' into dict."""
+    result: dict[str, float] = {}
+    if not comp_summary or comp_summary == "N/A":
+        return result
+    for part in comp_summary.split(","):
+        part = part.strip()
+        if ":" in part:
+            aa, pct = part.split(":", 1)
+            try:
+                result[aa.strip()] = float(pct.strip().rstrip("%"))
+            except ValueError:
+                pass
+    return result
+
+
+def hex_to_rgb(hex_color: str) -> str:
+    """Convert hex color '#RRGGBB' to 'r,g,b' string for rgba()."""
+    h = hex_color.lstrip("#")
+    return ",".join(str(int(h[i : i + 2], 16)) for i in (0, 2, 4))
+
+
+def build_radar_figure(gene_ids: list[str], protein_df, radar_axes_data: dict | None = None) -> go.Figure:
+    """Build radar/spider chart comparing amino acid composition of proteins.
+
+    Parameters
+    ----------
+    gene_ids : list[str]
+        Gene IDs to plot (max 5).
+    protein_df : pd.DataFrame
+        The protein index dataframe with columns gene_id, protein_length, composition_summary.
+    radar_axes_data : dict, optional
+        Dict with 'axes' and 'global_mean' keys. Falls back to module cache.
+    """
+    if radar_axes_data is None:
+        radar_axes_data = _RADAR_AXES
 
+    axes = radar_axes_data["axes"]
+    global_mean = radar_axes_data["global_mean"]
+
+    fig = go.Figure()
+
+    # Add global mean as a dashed reference polygon
+    mean_values = [global_mean.get(aa, 0) for aa in axes]
+    fig.add_trace(go.Scatterpolar(
+        r=mean_values + [mean_values[0]],
+        theta=axes + [axes[0]],
+        fill="none",
+        line=dict(color="#757575", dash="dash", width=1),
+        name="Global Average",
+        opacity=0.6,
+    ))
+
+    # Palette for up to 5 genes
+    palette = [COLORS["core"], COLORS["accent"], COLORS["cloud"], COLORS["selected"], "#6A1B9A"]
+
+    for i, gene_id in enumerate(gene_ids[:5]):
+        row = protein_df[protein_df["gene_id"] == gene_id]
+        if row.empty:
+            continue
+        comp = parse_composition(row.iloc[0]["composition_summary"])
+        values = [comp.get(aa, 0) for aa in axes]
+
+        fig.add_trace(go.Scatterpolar(
+            r=values + [values[0]],
+            theta=axes + [axes[0]],
+            fill="toself",
+            fillcolor=f"rgba({hex_to_rgb(palette[i % len(palette)])},0.15)",
+            line=dict(color=palette[i % len(palette)], width=2),
+            name=gene_id,
+        ))
+
+    fig.update_layout(
+        polar=dict(
+            bgcolor="rgba(0,0,0,0)",
+            radialaxis=dict(
+                showticklabels=True,
+                tickfont=dict(size=10, color="#757575"),
+                gridcolor="#E0E0E0",
+                showline=False,
+            ),
+            angularaxis=dict(
+                tickfont=dict(size=12, color=COLORS["text_primary"]),
+                gridcolor="#E0E0E0",
+            ),
+        ),
+        height=450,
+        margin=dict(l=60, r=60, t=40, b=40),
+        paper_bgcolor="rgba(0,0,0,0)",
+        legend=dict(bgcolor="rgba(255,255,255,0.85)"),
+    )
+    return fig
+
+
+def build_protein_length_bar(gene_id: str, protein_df) -> str:
+    """Build HTML for protein length percentile visualization.
+
+    Returns an inline-styled metric card with a position indicator on a
+    min-max bar showing where the selected protein falls.
+    """
+    row = protein_df[protein_df["gene_id"] == gene_id]
+    if row.empty:
+        return '<div style="color:#757575;padding:16px;">No protein data available</div>'
+
+    length = int(row.iloc[0]["protein_length"])
+    min_len = int(protein_df["protein_length"].min())
+    max_len = int(protein_df["protein_length"].max())
+    pct = (length - min_len) / (max_len - min_len) * 100 if max_len > min_len else 50
+
+    return f'''
+    <div class="metric-card">
+        <div class="metric-value">{length:,} aa</div>
+        <div class="metric-label">Protein Length</div>
+        <div style="margin-top:12px;position:relative;height:8px;background:#E0E0E0;border-radius:4px;">
+            <div style="position:absolute;left:{pct:.1f}%;top:-4px;width:16px;height:16px;
+                        background:{COLORS['core']};border-radius:50%;border:2px solid white;
+                        box-shadow:0 1px 3px rgba(0,0,0,0.3);transform:translateX(-50%);"></div>
+        </div>
+        <div style="display:flex;justify-content:space-between;margin-top:4px;font-size:11px;color:#757575;">
+            <span>{min_len:,} aa</span><span>{max_len:,} aa</span>
+        </div>
+    </div>
+    '''
+
+
+# =====================================================================
+# Gradio UI builder
+# =====================================================================
 
 def build_quest4(gene_choices: list[str]):
-    """Build Quest 4 tab components. Returns dict of components."""
-    with gr.Tab("Protein Relics", id="quest4") as tab:
-        gr.Markdown("## Examine protein properties")
-        gr.Markdown(
+    """Build Quest 4 tab components. Returns dict of components.
+
+    Returned keys (prefixed with ``q4_`` by layout.py):
+        tab, gene_dropdown, protein_stats_html,
+        comparison_bar_plot, composition_heatmap
+    """
+    with gr.Tab("Protein World", id="quest4") as tab:
+        # -- Header --
+        gr.HTML(
+            '<div style="padding:4px 0 12px 0;">'
+            '<h2 style="margin:0 0 4px 0;font-size:22px;font-weight:700;'
+            f'color:{COLORS["text_primary"]};">Chapter 5: Protein World</h2>'
+            '<p style="margin:0;font-size:14px;color:#757575;line-height:1.5;">'
             "Explore the protein products of pangenome genes. Compare amino acid "
-            "compositions and lengths across your backpack collection."
+            "compositions with radar charts and examine length distributions."
+            "</p></div>"
         )
 
-        gene_dropdown = gr.Dropdown(
-            choices=gene_choices,
-            label="Select a gene (or pick from backpack)",
-            interactive=True,
-            allow_custom_value=True,
-        )
+        # -- Single-gene selector --
+        with gr.Row():
+            with gr.Column(scale=2):
+                gene_dropdown = gr.Dropdown(
+                    choices=gene_choices,
+                    label="Select a gene (or pick from backpack)",
+                    interactive=True,
+                    allow_custom_value=True,
+                )
+            with gr.Column(scale=3):
+                protein_stats_html = gr.HTML(
+                    value=(
+                        '<div style="padding:16px;color:#757575;text-align:center;">'
+                        "Select a gene to see protein statistics</div>"
+                    ),
+                    label="Protein Statistics",
+                )
 
-        protein_stats_html = gr.HTML(
-            value="<p>Select a gene to see protein stats</p>",
-            label="Protein Statistics",
+        # -- Backpack comparison section --
+        gr.HTML(
+            '<div style="margin-top:16px;padding:4px 0;">'
+            '<h3 style="margin:0 0 4px 0;font-size:17px;font-weight:600;'
+            f'color:{COLORS["text_primary"]};">Backpack Comparison</h3>'
+            '<p style="margin:0;font-size:13px;color:#757575;">'
+            "Pin at least 2 genes to your backpack to see radar and heatmap comparisons."
+            "</p></div>"
         )
 
-        gr.Markdown("### Backpack Comparison")
-        gr.Markdown("Pin at least 2 genes to your backpack to see comparisons.")
-
-        comparison_bar_plot = gr.Plot(label="Protein lengths comparison")
-        composition_heatmap = gr.Plot(label="Amino acid composition heatmap")
+        with gr.Row():
+            comparison_bar_plot = gr.Plot(label="Amino Acid Radar")
+            composition_heatmap = gr.Plot(label="Composition Heatmap")
 
     return {
         "tab": tab,

ui/theme.py

@@ -1,8 +1,440 @@
-"""Custom Gradio theme for the Pigeon Pea Pangenome Atlas."""
+"""Custom Gradio theme and CSS for the Pigeon Pea Pangenome Atlas.
+
+Provides a premium botanical/academic visual identity with forest-green
+primary color, gold accents, and clean card-based layouts.
+
+Exports
+-------
+get_theme()   – returns the configured ``gr.themes.Base`` instance.
+build_theme() – alias kept for backward compatibility.
+CUSTOM_CSS    – CSS string injected into ``gr.Blocks(css=...)``.
+"""
 
 import gradio as gr
 
+# =====================================================================
+# Gradio theme
+# =====================================================================
+
+def get_theme() -> gr.themes.Base:
+    """Return a Gradio theme object with the Atlas visual identity.
+
+    * Primary hue  : forest green (#2E7D32)
+    * Secondary hue: gold (#D4A017)
+    * Neutral hue  : warm gray
+    * Border radius: 12px containers, 8px buttons
+    * Font         : system sans-serif stack
+    """
+    theme = gr.themes.Base(
+        primary_hue=gr.themes.colors.green,
+        secondary_hue=gr.themes.colors.amber,
+        neutral_hue=gr.themes.Color(
+            name="warmgray",
+            c50="#FAFAF5",
+            c100="#F5F5F0",
+            c200="#E8E8E0",
+            c300="#D4D4CC",
+            c400="#A8A8A0",
+            c500="#787870",
+            c600="#5C5C55",
+            c700="#45453F",
+            c800="#2E2E28",
+            c900="#1A1A15",
+            c950="#0D0D0A",
+        ),
+        font=[
+            "-apple-system",
+            "BlinkMacSystemFont",
+            "Segoe UI",
+            "Roboto",
+            "Helvetica Neue",
+            "Arial",
+            "sans-serif",
+        ],
+        font_mono=[
+            "SF Mono",
+            "SFMono-Regular",
+            "ui-monospace",
+            "Menlo",
+            "monospace",
+        ],
+    ).set(
+        # Page
+        body_background_fill="#FAFAF5",
+        body_text_color="#1A1A1A",
+
+        # Containers / blocks
+        block_background_fill="#FFFFFF",
+        block_border_width="0px",
+        block_border_color="transparent",
+        block_radius="12px",
+        block_shadow="0 2px 8px rgba(0,0,0,0.06)",
+
+        # Buttons
+        button_primary_background_fill="linear-gradient(135deg, #2E7D32, #43A047)",
+        button_primary_background_fill_hover="linear-gradient(135deg, #256b29, #388E3C)",
+        button_primary_text_color="white",
+        button_primary_border_color="transparent",
+        button_secondary_background_fill="transparent",
+        button_secondary_border_color="#2E7D32",
+        button_secondary_text_color="#2E7D32",
+        button_large_radius="8px",
+        button_small_radius="8px",
+
+        # Inputs
+        input_radius="8px",
+        input_border_color="#E0E0E0",
+        input_background_fill="#FFFFFF",
+
+        # Spacing
+        layout_gap="16px",
+
+        # Shadows
+        shadow_spread="0px",
+    )
+    return theme
+
+
+# Backward-compatible alias so existing ``from ui.theme import build_theme``
+# continues to work without changes.
+build_theme = get_theme
+
+
+# =====================================================================
+# Custom CSS
+# =====================================================================
+
 CUSTOM_CSS = """
+/* =================================================================
+   Pigeon Pea Pangenome Atlas — Custom CSS
+   =================================================================
+   Class reference (keep in sync with Python HTML builders):
+     Page        : body overrides
+     Cards       : .metric-card, .gene-card-panel
+     Hero        : .hero-header, .hero-stat, .hero-subtitle
+     Badges      : .gene-badge-core, .gene-badge-shell, .gene-badge-cloud
+     Backpack    : .backpack-chip, .backpack-chip-core/shell/cloud
+     Stepper     : .progress-stepper, .step-complete, .step-current, .step-future
+     Buttons     : .btn-primary, .btn-secondary
+     Legacy      : .quest-badge, .badge-core/shell/cloud, .gene-card,
+                   .presence-barcode, .progress-tracker, .progress-step,
+                   .stat-card, .achievement-badge
+   ================================================================= */
+
+/* ---- Page-level overrides ---- */
+body,
+.gradio-container {
+    background: #FAFAF5 !important;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+                 'Helvetica Neue', Arial, sans-serif;
+}
+
+/* Remove default Gradio container borders */
+.gradio-container .gr-box,
+.gradio-container .gr-panel {
+    border: none !important;
+}
+
+/* ---- Card styling ---- */
+.gr-block,
+.gr-panel,
+.gr-group {
+    background: #FFFFFF;
+    border-radius: 16px !important;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+}
+
+/* ---- Tabs — underline style ---- */
+.tabs > .tab-nav {
+    border-bottom: 2px solid #E0E0E0 !important;
+    background: transparent !important;
+}
+.tabs > .tab-nav > button {
+    border: none !important;
+    border-radius: 0 !important;
+    background: transparent !important;
+    padding: 10px 20px !important;
+    font-size: 14px;
+    font-weight: 500;
+    color: #757575;
+    transition: color 0.2s, border-color 0.2s;
+    position: relative;
+}
+.tabs > .tab-nav > button.selected {
+    color: #2E7D32 !important;
+    font-weight: 600;
+    border-bottom: 3px solid #2E7D32 !important;
+}
+.tabs > .tab-nav > button:hover {
+    color: #2E7D32;
+}
+
+/* ---- Hero header ---- */
+.hero-header {
+    background: #1a2332;
+    color: #FFFFFF;
+    padding: 40px 48px;
+    border-radius: 16px;
+    margin-bottom: 24px;
+}
+.hero-header h1 {
+    margin: 0 0 8px 0;
+    font-size: 28px;
+    font-weight: 700;
+    letter-spacing: -0.5px;
+}
+.hero-subtitle {
+    font-size: 16px;
+    color: #94a3b8;
+    margin-bottom: 28px;
+    line-height: 1.5;
+}
+.hero-stat {
+    display: inline-block;
+    text-align: center;
+    margin-right: 48px;
+    vertical-align: top;
+}
+.hero-stat .stat-number {
+    display: block;
+    font-size: 48px;
+    font-weight: 700;
+    color: #FFFFFF;
+    line-height: 1.1;
+}
+.hero-stat .stat-label {
+    display: block;
+    font-size: 12px;
+    font-weight: 400;
+    color: #94a3b8;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    margin-top: 6px;
+}
+
+/* ---- Metric cards ---- */
+.metric-card {
+    background: #FFFFFF;
+    border-radius: 16px;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+    padding: 24px;
+    border-top: 3px solid #2E7D32;
+    text-align: center;
+    transition: box-shadow 0.2s;
+}
+.metric-card:hover {
+    box-shadow: 0 4px 16px rgba(0,0,0,0.10);
+}
+.metric-card.amber {
+    border-top-color: #F9A825;
+}
+.metric-card.red {
+    border-top-color: #C62828;
+}
+.metric-card.blue {
+    border-top-color: #1565C0;
+}
+.metric-value {
+    font-size: 36px;
+    font-weight: 700;
+    color: #1A1A1A;
+    line-height: 1.1;
+    margin-bottom: 4px;
+}
+.metric-label {
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 1.2px;
+    color: #757575;
+}
+
+/* ---- Gene card side panel ---- */
+.gene-card-panel {
+    background: #FFFFFF;
+    border-radius: 16px;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+    padding: 20px;
+    border-left: 3px solid #2E7D32;
+}
+
+/* Gene classification badges */
+.gene-badge-core {
+    display: inline-block;
+    padding: 4px 14px;
+    border-radius: 20px;
+    font-size: 12px;
+    font-weight: 600;
+    background: #2E7D32;
+    color: #FFFFFF;
+}
+.gene-badge-shell {
+    display: inline-block;
+    padding: 4px 14px;
+    border-radius: 20px;
+    font-size: 12px;
+    font-weight: 600;
+    background: #F9A825;
+    color: #333333;
+}
+.gene-badge-cloud {
+    display: inline-block;
+    padding: 4px 14px;
+    border-radius: 20px;
+    font-size: 12px;
+    font-weight: 600;
+    background: #C62828;
+    color: #FFFFFF;
+}
+
+/* ---- Backpack chips ---- */
+.backpack-chip {
+    display: inline-block;
+    padding: 4px 12px;
+    border-radius: 16px;
+    font-size: 12px;
+    font-weight: 600;
+    margin: 2px 4px;
+    vertical-align: middle;
+}
+.backpack-chip-core {
+    background: #E8F5E9;
+    color: #2E7D32;
+    border: 1px solid #C8E6C9;
+}
+.backpack-chip-shell {
+    background: #FFF8E1;
+    color: #F9A825;
+    border: 1px solid #FFECB3;
+}
+.backpack-chip-cloud {
+    background: #FFEBEE;
+    color: #C62828;
+    border: 1px solid #FFCDD2;
+}
+
+/* ---- Progress stepper ---- */
+.progress-stepper {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: center;
+    gap: 0;
+    padding: 16px 0;
+}
+.progress-stepper .step {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 13px;
+    color: #757575;
+    padding: 0 16px;
+    position: relative;
+}
+.progress-stepper .step::after {
+    content: "";
+    position: absolute;
+    right: -2px;
+    width: 24px;
+    height: 2px;
+    background: #E0E0E0;
+}
+.progress-stepper .step:last-child::after {
+    display: none;
+}
+.progress-stepper .step .dot {
+    width: 24px;
+    height: 24px;
+    border-radius: 50%;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 12px;
+    font-weight: 700;
+    flex-shrink: 0;
+}
+/* Completed step: filled green circle with checkmark */
+.step-complete .dot {
+    background: #2E7D32;
+    color: #FFFFFF;
+}
+.step-complete {
+    color: #2E7D32;
+    font-weight: 500;
+}
+/* Current step: green ring, bold label */
+.step-current .dot {
+    background: transparent;
+    border: 2.5px solid #2E7D32;
+    color: #2E7D32;
+}
+.step-current {
+    color: #2E7D32;
+    font-weight: 700;
+}
+/* Future step: gray dimmed circle */
+.step-future .dot {
+    background: #E0E0E0;
+    color: #9E9E9E;
+}
+.step-future {
+    color: #9E9E9E;
+}
+
+/* ---- Buttons ---- */
+.btn-primary {
+    display: inline-block;
+    padding: 10px 24px;
+    background: linear-gradient(135deg, #2E7D32, #43A047);
+    color: #FFFFFF !important;
+    border: none;
+    border-radius: 8px;
+    font-size: 14px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: opacity 0.2s, box-shadow 0.2s;
+    text-decoration: none;
+}
+.btn-primary:hover {
+    opacity: 0.92;
+    box-shadow: 0 4px 12px rgba(46,125,50,0.25);
+}
+.btn-secondary {
+    display: inline-block;
+    padding: 10px 24px;
+    background: transparent;
+    color: #2E7D32 !important;
+    border: 2px solid #2E7D32;
+    border-radius: 8px;
+    font-size: 14px;
+    font-weight: 600;
+    cursor: pointer;
+    transition: background 0.2s;
+    text-decoration: none;
+}
+.btn-secondary:hover {
+    background: #E8F5E9;
+}
+
+/* ---- Hide Gradio footer / reduce noise ---- */
+footer {
+    display: none !important;
+}
+.gradio-container .gr-padded {
+    padding: 12px !important;
+}
+
+/* Clean accordion styling */
+.gr-accordion {
+    border: 1px solid #E0E0E0 !important;
+    border-radius: 12px !important;
+    box-shadow: none !important;
+}
+.gr-accordion > .label-wrap {
+    padding: 12px 16px !important;
+}
+
+/* ---- Legacy classes (backward compat) ---- */
 .quest-badge {
     display: inline-block;
     padding: 4px 12px;
@@ -12,14 +444,15 @@ CUSTOM_CSS = """
     margin: 2px 4px;
 }
 .badge-core { background: #2E7D32; color: white; }
-.badge-shell { background: #FFC107; color: #333; }
-.badge-cloud { background: #F44336; color: white; }
+.badge-shell { background: #F9A825; color: #333; }
+.badge-cloud { background: #C62828; color: white; }
 
 .gene-card {
     border: 2px solid #2E7D32;
-    border-radius: 8px;
+    border-radius: 12px;
     padding: 16px;
-    background: #F1F8E9;
+    background: #FFFFFF;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.06);
 }
 
 .presence-barcode span {
@@ -28,7 +461,7 @@ CUSTOM_CSS = """
     height: 20px;
     margin: 0;
 }
-.presence-barcode .present { background: #4CAF50; }
+.presence-barcode .present { background: #2E7D32; }
 .presence-barcode .absent { background: #E0E0E0; }
 
 .progress-tracker {
@@ -55,10 +488,11 @@ CUSTOM_CSS = """
 
 .stat-card {
     text-align: center;
-    padding: 16px;
-    border-radius: 8px;
-    background: #F1F8E9;
-    border: 1px solid #C8E6C9;
+    padding: 20px;
+    border-radius: 12px;
+    background: #FFFFFF;
+    border-top: 3px solid #2E7D32;
+    box-shadow: 0 2px 8px rgba(0,0,0,0.06);
 }
 .stat-card .stat-value {
     font-size: 1.8em;
@@ -67,35 +501,17 @@ CUSTOM_CSS = """
 }
 .stat-card .stat-label {
     font-size: 0.85em;
-    color: #666;
+    color: #757575;
 }
 
 .achievement-badge {
     display: inline-block;
     padding: 6px 14px;
     border-radius: 20px;
-    background: linear-gradient(135deg, #FFC107, #FF9800);
+    background: linear-gradient(135deg, #D4A017, #F9A825);
     color: #333;
     font-weight: 600;
     margin: 4px;
     box-shadow: 0 2px 4px rgba(0,0,0,0.1);
 }
 """
-
-
-def build_theme():
-    """Build custom Gradio theme."""
-    theme = gr.themes.Soft(
-        primary_hue=gr.themes.colors.green,
-        secondary_hue=gr.themes.colors.amber,
-        neutral_hue=gr.themes.colors.gray,
-        font=gr.themes.GoogleFont("Inter"),
-    ).set(
-        body_background_fill="#FAFAF5",
-        block_border_width="1px",
-        block_border_color="#C8E6C9",
-        block_radius="8px",
-        button_primary_background_fill="#2E7D32",
-        button_primary_text_color="white",
-    )
-    return theme