CurrenciCombo/docs/ux-responsive-strategy.md

# Responsive UX/UI strategy

This document describes the responsive design system added to the
CurrenciCombo portal. It is intended to be the source of truth for
future responsive work.

## Goals

The portal ships to a mixed audience that includes treasury operators
at desks (≥ 1440 px displays), branch-office users on 13" laptops,
tablets in landscape, and mobile phones for on-call auditors. The
system has to adapt across all of those without:

- horizontal scroll at any viewport ≥ 320 px,
- layout shift on resize (no CLS),
- unusable tap targets on touch devices,
- losing keyboard navigation on desktop, or
- degrading desktop performance.

## Architecture

The responsive system is CSS-first and token-driven. There is **one**
runtime hook (`useBreakpoint`) used by the handful of components that
have to swap structure (nav, workspace gate) — everything else is
pure CSS.

### Layered stylesheet order

`src/main.tsx` imports styles in this order:

1. `src/styles/tokens.css` — design tokens (no visual side effects).
2. `src/index.css` — the original desktop baseline stylesheet.
3. `src/styles/responsive.css` — media-query overrides.
4. `src/styles/a11y.css` — focus ring, skip-to-content, sr-only,
   touch-target enforcement.

Order matters: overrides must appear after the baseline so that rules
at equal specificity win. Nothing in `responsive.css` or `a11y.css`
changes behavior at `≥ lg` — every rule is wrapped in a
`@media (max-width: …)` or `@media (pointer: coarse)` query.

### Tokens

All sizing values that change with viewport live in
`src/styles/tokens.css`:

| Category      | Tokens                                       |
| ------------- | -------------------------------------------- |
| Breakpoints   | `--bp-xs 0`, `--bp-sm 480`, `--bp-md 768`, `--bp-lg 1024`, `--bp-xl 1440` (px) |
| Fluid type    | `--fs-2xs` through `--fs-4xl`, all `clamp()` |
| Fluid spacing | `--space-0` through `--space-12`, all `clamp()` |
| Line height   | `--lh-tight`, `--lh-snug`, `--lh-normal`, `--lh-relaxed` |
| Motion        | `--motion-fast 120ms`, `--motion-base 200ms`, `--motion-slow 320ms`, `--motion-ease` |
| Z-index       | `--z-base`, `--z-sticky`, `--z-drawer-backdrop`, `--z-drawer`, `--z-dropdown`, `--z-modal`, `--z-toast`, `--z-tooltip`, `--z-focus` |
| Focus ring    | `--focus-ring-color #60a5fa`, `--focus-ring-offset 2px`, `--focus-ring-width 2px` |
| Safe area     | `--safe-top/right/bottom/left` via `env()`   |
| Tap target    | `--tap-min 44px`                             |

### Fluid scaling formula

Typography and spacing use `clamp(min, preferred, max)` where
`preferred` has a `vw` term so values interpolate continuously between
the smallest design viewport (320 px) and the largest (1440 px). This
is what the spec calls "avoid hard breakpoints where possible; prefer
fluid responsiveness" — between breakpoints, sizes grow continuously
rather than snapping.

Example, `--fs-base: clamp(0.8125rem, 0.77rem + 0.23vw, 1rem)`:

- at 320 px → 13 px (minimum),
- at 1024 px → ~15.1 px,
- at 1440 px → 16 px (maximum clamp).

### Breakpoints

| Name | CSS range               | Semantic               |
| ---- | ----------------------- | ---------------------- |
| xs   | 0 – 479 px              | Small phones, portrait |
| sm   | 480 – 767 px            | Larger phones          |
| md   | 768 – 1023 px           | Tablets                |
| lg   | 1024 – 1439 px          | Laptops                |
| xl   | ≥ 1440 px               | External displays      |

Semantic aliases exposed by `useBreakpoint()`:

- `isMobile`  = `< md` (phones)
- `isTablet`  = `md – lg` (tablets, portrait iPads)
- `isDesktop` = `≥ lg` (laptops, external monitors)

### Hooks

- **`useMediaQuery(query)`** — subscribes to a matchMedia `change`
  event via `useSyncExternalStore`. No resize listener — re-renders
  only when the query result actually flips.
- **`useBreakpoint()`** — returns `{ current, isXs/Sm/Md/Lg/Xl,
  isMobile/Tablet/Desktop }`. Composed of four `useMediaQuery` calls
  using the `--bp-*` values from the tokens.
- **`useReducedMotion()`** — wraps `(prefers-reduced-motion: reduce)`
  so components that animate in JS can disable animations.
- **`useOrientation()`** — returns `'portrait'` or `'landscape'`.

All four hooks are SSR-safe (return `false` / default in a non-DOM
environment).

## Component inventory and strategy

### Global primitives

- **Skip-to-content link** — rendered at the top of the tree via
  `<SkipToContent>`. Visually hidden until `:focus`, then slides in at
  top-left. Target is `<main id="main-content" tabIndex={-1}>` in
  `PortalLayout`.
- **VisuallyHidden** — `sr-only` wrapper, for adding accessible text
  without visual presence.

### Portal chrome

- **Topbar** (`.portal-topbar`): fixed 48 px height at all sizes.
  Below `md`, the "Production" environment badge and the "Solace Bank
  Group" logo text are hidden so the hamburger, logo mark and user
  avatar fit on a phone without wrapping.
- **Hamburger toggle** (`.portal-menu-toggle`): new `<button>` in the
  topbar, hidden by default (CSS `display: none`), shown below `lg`.
  44 × 44 tap area. `aria-expanded`, `aria-controls`, swappable
  label/icon between open and closed.
- **Sidebar / drawer** (`.portal-sidebar`):
  - `≥ lg` — behaves exactly as before (220 px wide, collapsible to
    56 px rail via the existing collapse button).
  - `md – lg` — forced into a 56 px icon-only rail (tablet treatment).
  - `< md` — becomes an off-canvas drawer slid out from the left at
    `min(320px, 84vw)` wide, over a backdrop at
    `var(--z-drawer-backdrop)`. Drawer closes on: Escape key, backdrop
    click, route change, window resize into `≥ md`. Body scroll is
    locked while the drawer is open.

### Dashboard (`/dashboard`)

- KPI row uses `grid-template-columns: repeat(auto-fit, minmax(min(100%, 180px), 1fr))`
  so six cards at xl collapse to four at lg, three at md, two at sm,
  one at xs — fluidly.
- Header (title + time-range + refresh) stacks vertically below md;
  the time-range chip row scrolls horizontally if needed.
- Two-column `.dashboard-grid` becomes single-column below `lg`.

### Tables (Transactions, Settlements, Accounts)

Two CSS patterns available:

1. **Scrolling wrapper (default).** Wrap the `<table>` in
   `<div class="portal-table-wrapper">`. Below `sm` the wrapper
   scrolls horizontally and the `table` holds a `min-width: 640px`
   floor so columns never collapse to useless widths.
2. **Stacked-card mode (opt-in).** Add `portal-table--stack` to the
   `<table>` and a `data-label="Column name"` attribute to each
   `<td>`. At xs the rows render as cards with label-value pairs;
   the `<thead>` is hidden off-screen but remains in the accessibility
   tree.

### Forms (Reporting, Compliance, Treasury, Settings)

These pages already use CSS grid via the `.settings-grid` /
`.treasury-summary` / etc. classes; the responsive layer just forces
single-column layout below `md` via `grid-template-columns: 1fr
!important` and reduces container padding to `var(--space-4)` on
phones.

### Login page

- Below `md` the two-column layout (brand left / card right) stacks.
  Both halves go to `max-width: 100%`.
- `min-height: 100vh; min-height: 100dvh` accommodates iOS Safari's
  bottom toolbar.
- `safe-area-inset-*` padding for notched phones.

### Workspace / IDE mode (`App.tsx`)

The multi-panel IDE (TitleBar + ActivityBar + LeftPanel + Canvas +
RightPanel + BottomPanel + react-flow) is not realistically usable
below ~768 px of width. Matching the pattern used by VS Code Web,
Figma, and Replit:

- **`< md`** — show `<WorkspaceMobileGate>` instead of the IDE shell.
  Explains what the user is seeing and deep-links to `/dashboard`,
  `/transactions`, `/accounts` so they can keep using the portal.
- **`≥ md`** — render the full workspace exactly as before.

The gate is a plain `<section>` with three buttons, all 44 px tall,
and a single `<h2>` for landmark navigation.

## Performance

- **No layout shift.** Fluid `clamp()` sizes and `auto-fit` grids
  scale continuously; no script-driven layout recalculation on
  resize. `img, video, svg, picture` default to
  `max-width: 100%; height: auto` so intrinsic aspect ratios are
  preserved.
- **No resize listeners.** `useMediaQuery` subscribes to matchMedia's
  native `change` event, not `window.resize`. React only re-renders
  when a query actually flips.
- **CSS-first.** The only JS structure swap is the mobile drawer and
  the workspace gate — both driven by `useBreakpoint()` which is one
  tiny subscription shared across the app.
- **Print.** The portal has a minimal print stylesheet so treasury
  reports print clean (no sidebar, no topbar, black-on-white).

## Accessibility

- **Skip-to-content link** at the top of the tree.
- **Focus ring** via `:focus-visible`, 2 px solid `#60a5fa` with
  2 px offset. Defined in `a11y.css`, tightens to 3 px in
  `prefers-contrast: more`.
- **Landmarks** — `<main id="main-content">`, `<nav aria-label="Primary">`,
  proper heading levels.
- **Tap targets** — `@media (pointer: coarse)` enforces 44 × 44 px
  minimum on `button`, `a`, `[role="button"]`, `[role="tab"]`.
- **Reduced motion** — `@media (prefers-reduced-motion: reduce)`
  drops animation durations to 0.001 ms; JS-driven animations read
  `useReducedMotion()`.
- **No content hidden from screen readers** by the table transform —
  `thead` is positioned off-screen in stacked-card mode but remains
  accessible. Data labels are injected via `::before` content so
  they're visible to sighted users but not announced twice to
  screen readers.

## Gotchas and non-obvious decisions

1. **`html, body { overflow-x: hidden }`** — intentional global guard
   against any descendant creating horizontal scroll. The IDE shell
   (`.app-shell`) and portal root (`.portal-layout`) both cap at
   `max-width: 100vw` so they contain the react-flow canvas
   correctly.
2. **Drawer width is `min(320px, 84vw)`** — on a narrow phone the
   drawer would otherwise cover the whole viewport; 84 vw leaves a
   visible strip of backdrop so users know they can tap to close.
3. **`.portal-topbar-center` hides below md** — at 320 px the "Production"
   badge pushes the user avatar off-screen. The identity/environment
   is still visible in the user menu dropdown, so nothing is lost.
4. **Tablet (md – lg) forces the sidebar into 56 px rail** — rather
   than respecting the `collapsed` state. Tablets in portrait don't
   have room for a labeled 220 px nav plus meaningful content area.
5. **`use-syncExternalStore` for matchMedia** — avoids tearing
   between the two `useState` + `useEffect` pattern most examples
   use; means the hook reports the correct value on the very first
   render after a layout change.
6. **`setDrawerOpen` from effects** — the
   `react-hooks/set-state-in-effect` rule is narrowly disabled on the
   "close drawer on route change" and "close drawer on resize-up"
   effects. These are synchronizing internal state with *external*
   inputs (router location, media query), which is one of the
   legitimate uses of an effect. The rule would require either
   refactoring the entire state into derived values (noisy) or
   moving the close logic into every nav-item onClick (error-prone).

## Testing matrix

| Category         | Viewports tested                                    |
| ---------------- | --------------------------------------------------- |
| Phones           | 320, 375, 414                                       |
| Tablets          | 768 (portrait), 1024 (landscape)                    |
| Laptops          | 1280, 1440                                          |
| Desktops         | 1920, 2560                                          |
| Orientation      | Portrait and landscape at 768, 414                  |
| DPR              | 1× and 2× (hairline borders at 2×)                  |
| Reduced motion   | `prefers-reduced-motion: reduce` honored            |
| Keyboard         | Tab order, skip-link, focus ring, drawer Escape     |

## File inventory

New files:

- `src/styles/tokens.css`
- `src/styles/responsive.css`
- `src/styles/a11y.css`
- `src/hooks/useMediaQuery.ts`
- `src/hooks/useBreakpoint.ts`
- `src/hooks/useReducedMotion.ts`
- `src/hooks/useOrientation.ts`
- `src/components/a11y/SkipToContent.tsx`
- `src/components/a11y/VisuallyHidden.tsx`
- `docs/ux-responsive-strategy.md` (this document)

Modified files:

- `index.html` — viewport meta with `viewport-fit=cover`, `theme-color`,
  `color-scheme`, mobile-web-app meta.
- `src/main.tsx` — import order for the four CSS layers.
- `src/App.tsx` — workspace mobile gate wrapping the IDE entrypoint.
- `src/Portal.tsx` — `<SkipToContent>` mounted once at the route root.
- `src/components/portal/PortalLayout.tsx` — mobile drawer state,
  hamburger toggle, backdrop, `<main id="main-content">` landmark,
  route/resize/Escape auto-close.