09 — Web Experience¶

1. Design thesis¶

Baraka's lesson is that a financial app earns use through calm — few decisions per screen, plain language, no dashboard vomit. The temptation in an AI-heavy product is to display the intelligence: twelve agents, forty features, confidence distributions. That produces a tool that looks impressive in a screenshot and is exhausting to use daily.

The resolution is progressive disclosure with a hard rule: the top layer of every view answers one question in one sentence. Everything else is a click away, and the depth is genuinely deep — the analyst path leads all the way to the source filing.

The web target changes the shape of that disclosure but not the principle. A browser gives what a phone could not: a persistent sidebar, side-by-side panes, real tables, a command palette, and keyboard-driven navigation. Depth that would have been three taps down on a phone can sit in an adjacent pane. The discipline is to spend that space on more context, not more chrome.

Three commitments shape every view:

No number without provenance. Every figure links to its source and as-of date.
No recommendation without a falsifier. "What would change my mind" is displayed, not buried.
Uncertainty is shown, not smoothed. Stale data, low confidence, and pre-calibration status are visible on the card, because a system that hides its doubt is asking for trust it has not earned.

2. Delivery and platform¶

A single-page application served by the same FastAPI process that serves the API — one origin, one deployment unit, no CORS, no second server to run. Starting the stack gives you a URL and nothing else to configure. This is a real simplification over the mobile design, which needed a build pipeline and a device to install onto.

It is also a progressive web app. That is not an attempt to smuggle the mobile app back in; it buys three specific things:

Installability — a standalone window on the desktop, without browser chrome.
Web push notifications — so critical alerts (compliance breach, circuit breaker, thesis invalidation) reach you when the tab is closed.
Phone browser access — open the same URL on your phone over Wi-Fi and the responsive layout collapses to a single column. No app store, no build, no install. A genuinely useful secondary surface rather than a product to design for.

Breakpoints: three panes above 1400px, two panes 1000–1400px, single column below. The single-column layout is the phone-browser case, and it gets tested rather than merely tolerated.

Browser support: current Chrome, Firefox, Safari, and Edge. No legacy compatibility burden, so modern CSS (container queries, :has(), subgrid) is used freely.

3. Information architecture¶

A persistent left sidebar rather than a tab bar. The ten named surfaces group into five sections, and the sidebar shows all of them at once — the main structural advantage a browser has over a phone.

┌──────────────┬──────────────────────────────────────────────┐
│ HalalTrade   │                                              │
│              │                                              │
│ ▸ Today      │                                              │
│ ▸ Portfolio  │              content area                    │
│ ▸ Markets    │          (one, two, or three panes)          │
│ ▸ Ask        │                                              │
│ ▸ Settings   │                                              │
│              │                                              │
│ ──────────   │                                              │
│ ⏻ Stop all   │                                              │
│ ● Data OK    │                                              │
└──────────────┴──────────────────────────────────────────────┘

Section	Contains
Today	Dashboard, recommendations, news digest, alerts
Portfolio	Holdings, performance, risk, paper trading, order history, purification
Markets	Universe browser, watchlists, instrument detail, compliance screener
Ask	Conversational assistant with full portfolio and evidence grounding
Settings	Compliance methodology, backtesting, data sources, model routing, security, audit log

The sidebar footer carries two persistent elements: the emergency stop (07 §6) and a system health dot covering data freshness and model availability. Both need to be reachable from anywhere, and neither belongs in a menu.

Backtesting lives under Settings rather than in the primary navigation, deliberately: it is a periodic research activity, and giving it prime real estate encourages exactly the over-fitting behaviour 08 is designed to discourage.

Command palette (Cmd/Ctrl-K) — jump to any instrument, run a screen, open a recommendation, toggle a setting. For a data-dense tool used daily this is the fastest path to almost everything, and it is the feature that most benefits from being on a desktop.

4. Today¶

The landing view. It must be readable in ten seconds.

┌────────────────────────────────────────────────────────────────────┐
│  Good morning                                    3 Aug 2026, 08:14 │
│                                                                    │
│  £24,318.40      ▲ £182.30  +0.75%      Paper · since start +8.2%  │
│                                                                    │
│  ┌──────────────────────────┐  ┌────────────────────────────────┐  │
│  │ TODAY'S THINKING         │  │ ⚑ 2 new opportunities          │  │
│  │                          │  │ ⚠ 1 position needs attention   │  │
│  │ "Rate expectations       │  │ ● Data current · all feeds OK  │  │
│  │  shifted after the CPI   │  └────────────────────────────────┘  │
│  │  print. I've lowered     │                                      │
│  │  conviction on rate-     │  RECOMMENDATIONS                     │
│  │  sensitive holdings and  │  ┌────────────────────────────────┐  │
│  │  flagged two industrials │  │ BUY  ROK  Rockwell Automation  │  │
│  │  that screen well."      │  │ ●●●●○ 72%  ✓ Compliant         │  │
│  │                          │  │ ~3 months · Risk: Moderate     │  │
│  │              Read more → │  │ "Order backlog up 18% while    │  │
│  └──────────────────────────┘  │  trading below its 5-year avg" │  │
│                                │ [ Why? ] [ Paper trade ] [Skip]│  │
│                                └────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────────┘

Today's Thinking is the product's signature. One short paragraph, written by the Supervisor, summarising what changed overnight and what the system did about it. It is what makes the platform feel like a team that worked while you slept rather than a page that refreshed.

Clicking a recommendation opens its detail in an adjacent pane on wide screens — list on the left, detail on the right — so you can work through the day's candidates without losing your place. On narrow screens it pushes to a full view.

5. The recommendation detail — "Why?"¶

The most important view in the product, and the one that most benefits from a browser. It renders the stored audit manifest, never a regenerated rationalisation (04 §9).

On a wide screen this is a two-column layout: thesis, compliance, and analyst breakdown on the left; the evidence panel pinned on the right, so citations stay visible while you read the claims they support. That adjacency is the thing a phone genuinely could not do, and it is where the extra space earns its keep.

1 · The thesis — three sentences. What, why, over what horizon.

2 · Shariah compliance — verdict, the full ratio table with every input, threshold, and result, each linked to its filing. Purification rate stated. Methodology named, with a link to change it. On desktop the whole table is visible at once rather than behind an accordion.

3 · What the analysts said — one row per agent: direction, a one-line summary, and a contribution bar from the SHAP attribution, so you see which view is carrying the recommendation.

Fundamental   ▲ Bullish   ████████░░  +0.24
Technical     ▲ Bullish   ████░░░░░░  +0.11
Macro         ▼ Bearish   ██░░░░░░░░  −0.07
News          ▲ Bullish   ███░░░░░░░  +0.09
Social        — Neutral   ░░░░░░░░░░   0.00
Market        ▲ Bullish   ██░░░░░░░░  +0.06

Clicking an agent expands its full reasoning inline and highlights the corresponding sources in the evidence panel.

4 · What would change my mind — the falsification conditions, each with its monitoring status. Displayed prominently, because it is the difference between a thesis and a tip.

5 · Risk and sizing — suggested size, why that size, stop level and its basis, target, expected downside in currency terms, and how the position would change portfolio concentration.

6 · The evidence — the pinned right-hand panel. Every source document with the excerpt actually read, its published and available-at times, and its trust tier.

7 · Confidence, in context — the calibration curve with this recommendation's bucket marked, and the historical hit rate in that bucket. Showing the scoreboard alongside the claim is the strongest available honesty signal.

Rejected candidates get the same treatment. A "Why not?" view explains what failed — a compliance ratio, a Supervisor veto, a risk limit — because refusals are as informative as recommendations and are where compliance trust is actually built.

6. Watching a run¶

A recommendation takes 20–45 seconds (04 §10). Rather than a spinner, the SSE stream from 13 §4 drives a live view of the agent graph: the compliance gate resolving, analysts reporting as they finish, the aggregator's score appearing, then the Supervisor's explanation streaming token by token.

This is not decoration. It is the same trace stored in the audit manifest, so what you watch happen is exactly what gets recorded — and seeing the compliance gate reject a candidate in real time does more for trust than any amount of copy about how seriously compliance is taken.

7. Portfolio¶

Tabbed within the section: Holdings · Performance · Risk · Activity.

Holdings — a real table, sortable and keyboard-navigable, with weight, P&L, and compliance status per row. Any non-compliant or at-risk holding sorts to the top with a persistent banner. Allocation charts by sector, geography, and correlation cluster — the cluster view usually being the one that surprises.

Performance — time-weighted and money-weighted returns both shown, with a one-line explanation of the difference. Benchmark overlay against the compliant benchmark and the naive compliant equal-weight portfolio. Cost drag decomposition. Net-of-purification return as the headline figure, with gross available beneath.

Risk — the 07 §9 translations: consequences in currency, precise metrics one click down. Stress tests as scenario cards. Risk contribution by position.

Activity — order history, fills with modelled spread and impact broken out so you see what execution cost, corporate actions applied, dividends received, purification accrued and settled. Exportable to CSV, which is trivial on the web and was awkward on mobile.

8. Paper trading flow¶

Placing a trade is where an AI product can most easily overreach. The design keeps the human unambiguously in control.

Recommendation → [Paper trade] → Order ticket (pre-filled from risk sizing)
    ├─ editable quantity, order type, limit
    ├─ live preview: est. fill, spread cost, impact, total
    ├─ risk preview: post-trade concentration, sector weight, cash
    ├─ compliance re-check at submit
    └─ Confirm → order placed → toast + activity entry

The ticket is a modal over the recommendation, so the thesis stays visible while you size the position — you should not have to remember why you are buying something while deciding how much.

Three deliberate frictions: the risk preview shows the new portfolio state before you confirm; sizing above the risk engine's recommendation triggers an explicit warning naming the limit being exceeded; and a persistent PAPER marker sits in the header of every trading view. The marker is not decorative — the moment you forget you are simulating, the track record stops meaning anything.

9. Markets¶

Where the browser's density pays off most. The screener is a full data table — compliance status, sector, market cap, liquidity, valuation, quality, current signal — with compliance as a primary filter, not a buried toggle. Sortable columns, saved views, CSV export.

Instrument detail: price chart with signal annotations, compliance card, point-in-time fundamentals with as-of labels, recent news with materiality scoring, agent view if analysed, and the compliance ratio history chart — which shows an instrument drifting toward a threshold long before it breaches.

Watchlists support alerts on price, compliance status change, and thesis-invalidation conditions.

10. Ask¶

Conversational, streaming, grounded. Suggested prompts on entry rather than a blank box:

Why did you recommend Rockwell?
Show today's strongest halal opportunities
Explain this company's financial health
Compare these two companies
Summarise today's market
How can I reduce my portfolio risk?
What am I most exposed to without realising it?

Every response carries inline citation chips that open the source in a side panel. When the assistant lacks data it says so rather than generalising. It can prepare an order but never place one; the ticket always routes through the confirmation flow in §8.

When running against a cloud model with portfolio sharing disabled, a persistent banner states that holdings are not being transmitted and answers are based on aggregate characteristics — the privacy posture is visible in the moment it applies, not only in settings.

11. Design system¶

Dark-first. Financial data is read at length, often at night. Light theme fully supported, not an afterthought. Both respect the OS preference with a manual override.

Colour semantics — green/red are reserved exclusively for P&L direction and never used for compliance status, because conflating "up" with "permitted" is a category error. Compliance uses its own palette: teal for compliant, amber for uncertain, slate for non-compliant. Confidence uses a neutral ramp, not a traffic light, because 60% confidence is not "bad."

Density is a setting. Comfortable by default, compact for users who want more rows on screen. Data-dense tools should not force one answer to that question.

Accessibility — WCAG AA contrast minimum; never colour alone to convey state; full keyboard navigation including tables and the command palette; visible focus rings; screen-reader labelling on charts including a text summary of the underlying data; prefers-reduced-motion honoured. Keyboard access is not a checkbox here — it is the primary interaction mode for a daily-use data tool.

Number formatting — locale-aware currency, consistent precision, tabular figures so columns align, explicit as-of timestamps on anything that can go stale. Percentages always state what they are relative to.

Charts — every financial chart shows its adjustment basis (split/dividend adjusted or not), because unlabeled adjusted charts are a persistent source of confusion.

12. Onboarding¶

Five steps, none of which ask for money or credentials:

What this is — a research and simulation tool, not advice; paper trading only; the disclaimer stated plainly and once, well.
Choose your methodology — the Shariah standard, each explained in plain language, changeable later. Placing this first signals the priority order.
Risk profile — three or four plain questions that set exposure and loss limits, phrased as consequences ("a £10,000 portfolio falling to £8,500 would feel: fine / uncomfortable / unacceptable").
Privacy choices — local vs cloud models, and whether portfolio data may be sent to a cloud provider. Defaults are the private option; the trade-off is stated honestly rather than nudged.
Fund the paper account — a virtual starting balance, and the explicit statement that no real money is connected and no code path to real money exists.

13. Notifications¶

Sparse by default, because a tool that notifies constantly is muted, and a muted tool cannot warn you about the thing that matters.

Priority	Examples	Default
Critical	Compliance breach in a holding; circuit breaker fired; thesis invalidation triggered	Web push, breaks through
Important	New high-confidence recommendation; stop or target hit; loss limit approaching	Web push
Informational	Daily digest; fills; dividends and purification accrual	In-app, optional email digest
Quiet	Data quality events; model routing fallbacks	In-app only

Web push requires the PWA to be installed and permission granted; where it is not, critical alerts fall back to in-app banners and the optional email digest. Notification bodies never include balances or holdings.