/financial-ui-patterns

name: financial-ui-patterns
description: Use when building any UI that displays prices, P&L, holdings, orders, trades, charts, order books, watchlists, or streaming market data. Covers patterns from Kraken, Coinbase, TradingView, Bloomberg, Robinhood. Read before writing JSX for any financial surface.

Financial UI Patterns

Overview

Generic AI output for financial UIs fails in predictable ways: raw color values instead of design tokens, jittery non-tabular numbers, no decimal alignment, missing tick-flash on updates, hard-coded dark theme, broken Tailwind dynamic classes, no streaming/staleness states, no accessibility for color-blind users.

This skill codifies the patterns that production trading UIs (Kraken, Coinbase, TradingView, Bloomberg Terminal, Robinhood, Binance) actually ship.

**Core principle:** numbers must be legible, aligned, and trustworthy. Color is a signal, not decoration. Latency must be visible. Every digit shift is a failure.

When to Use

• Tables with prices, P&L, holdings, positions, orders, fills, trades
• Order books, depth charts, ladders
• Watchlists, tickers, market overviews
• Streaming/live data of any kind
• Portfolio screens, transaction history
• Charts with OHLC, candlesticks, sparklines
• Any UI showing money, percentages, basis points, or quantities

**Don't use for:** marketing pages, blog posts, generic product UI without numbers.

Quick Reference

| Concern | Rule | |---|---| | Number rendering | Always `tabular-nums`. Never let digits reflow. | | Number alignment | Right-align in tables. Decimal-align when precision varies. | | Ticker/ID display | Use `font-mono` (JetBrains Mono, Roboto Mono, IBM Plex Mono). | | Colors | Semantic tokens only (`text-positive`, `text-negative`). Never `text-green-500`. | | Theme | Light + dark via CSS variables. Never hard-code surface colors. | | Tick flash | 300-500ms tinted background on price update. CSS only, no JS animation. | | P&L sign | Always show `+` for positive returns. `-` is automatic on negatives. | | Tailwind dynamic | NEVER `bg-${color}-500/10`. Use static class maps. | | Streaming state | Show connecting / live / stale / disconnected explicitly. | | Accessibility | Pair color with icon, position, or shape. Never color alone. | | Decimals | Crypto: dynamic precision by price magnitude. Stocks: 2 dp. FX: 4-5 dp. | | Large numbers | Compact notation (`1.2B`, `847M`) for caps/volume, not for prices/balances. | | Density | Default to compact. 32-40px row height in tables. 24-28px in order books. |

Required Reading

| File | When to load | |---|---| | `references/typography-and-color.md` | Designing any financial surface from scratch | | `references/number-formatting.md` | Implementing any price/quantity/percentage display | | `references/components.md` | Building tables, order books, tickers, charts | | `references/streaming-and-state.md` | Live data, WebSocket UIs, tick-flash, staleness | | `references/accessibility.md` | Any production UI (always) | | `references/mobile-and-responsive.md` | Targeting phones/tablets, responsive tables, bottom sheets, touch interactions | | `references/industry-patterns.md` | Want specific references from Kraken/Coinbase/TradingView/Bloomberg | | `references/charts-and-candles.md` | Building any chart (candles, OHLC, line, volume, indicators) | | `references/loading-and-skeletons.md` | First-load and reconnect treatments for tables, order books, charts | | `references/empty-and-error-states.md` | Empty positions/orders, rejected orders, market closed, rate-limit copy | | `references/timestamps-and-timezones.md` | Trade times, "as of" stamps, multi-TZ status bar, ms precision rules | | `references/virtualization.md` | Tables over 100 streaming rows, trades tape, sticky headers, row memoization | | `references/chart-interactions.md` | Crosshair, zoom/pan, drawing tools, multi-pane stacks, number animations | | `references/order-entry-and-lifecycle.md` | Order forms, types (market/limit/stop/bracket/OCO), preview-then-submit, pending→filled states, time-and-sales | | `references/alerts-and-disclosures.md` | Price alerts, fill notifications, escalation rules, PDT/wash-sale/options/restricted-symbol disclosures | | `references/data-sources-and-freshness.md` | Real-time/delayed/stale/frozen/disconnected chain, source chips (CBOE, NBBO), multi-account context | | `references/heatmaps-and-density-viz.md` | Sector heatmaps, options chain color scales, IV surfaces, correlation grids |

Core Pattern: Numbers

The single most important fix vs. generic AI output:

// ❌ BAD: digits shift width on update, color is decorative, no sign on positive
<span className="text-green-500 font-medium">
  {value.toFixed(2)}%
</span>

// ✅ GOOD: tabular-nums locks width, semantic color, explicit sign, fixed width
<span
  className={`tabular-nums font-medium tracking-tight ${
    value >= 0 ? "text-positive" : "text-negative"
  }`}
  style={{ minWidth: 64, textAlign: "right" }}
>
  {value >= 0 ? "+" : ""}{value.toFixed(2)}%
</span>

Three failures the bad version causes: 1. Width changes when value goes from `9.99%` to `10.00%` — the entire row reflows 2. `text-green-500` breaks light theme and ignores any design system 3. No `+` prefix means positive and zero look identical at a glance

Core Pattern: Color Tokens

Define semantic colors via CSS variables, expose via Tailwind, never use raw color values in components.

/* globals.css */
:root {
  --positive: 34 197 94;   /* green for gains, buy, success */
  --negative: 239 68 68;   /* red for losses, sell, danger */
  --warning: 251 191 36;   /* amber for partial fills, stale data */
  --info: 0 143 250;       /* blue for working orders, neutral signals */
  --surface: 13 13 16;
  --surface-elevated: 22 22 26;
  --text-primary: 240 240 245;
  --text-secondary: 180 180 192;
  --text-muted: 110 110 125;
}

[data-theme="light"] {
  --positive: 22 163 74;
  --negative: 220 38 38;
  --surface: 248 249