Docs / web / PLATFORM-SPEC.md

#Substratal Hub for Web — Platform Spec

A modern, responsive web application and installable PWA that works equally well on phones, tablets and desktop browsers from one codebase. Its base design is the macOS app (sidebar · list · detail · inspector, toolbar with title/subtitle, sheets for forms, grouped settings rows), adapted to the web and to each device's size, input and system settings.

Read with: SCREENS.md (all 75 screens with web controls), shared/ (product spec, client architecture, components, copy, accessibility, flows), screens/ (reference renders at phone / tablet / desktop).

#1. Technology

Everything below is implementable with the platform APIs listed; each has a fallback (§11).

#2. Hosting & session security

• Served from https://dashboard.substratalapps.com (the host the API spec uses for billing returns) over HTTP/2+3, HSTS preload. The Web Hub also hosts the Phase 3 hosted sign-in page.
• Backend-for-frontend (BFF): a thin same-origin service holds the platform refresh token in an HttpOnly; Secure; SameSite=Strict cookie and exposes /bff/session/refresh and /bff/session/logout. The SPA keeps the 15-minute access token in memory only and calls the API directly with Authorization: Bearer. Never put refresh tokens in localStorage/IndexedDB. (If a BFF is ruled out, see OPEN-QUESTIONS #14 for the fallback and its risk.)
• CSP: default-src 'self'; script-src 'self' 'strict-dynamic' 'nonce-…'; connect-src 'self' https://api.substratalapps.com; frame-ancestors 'none'; require-trusted-types-for 'script'. No third-party scripts on any route.
• CSRF: BFF endpoints require SameSite=Strict cookie + custom header X-Substratal-CSRF.
• Logout: BFF responds with Clear-Site-Data: "cache", "storage"; the service worker also deletes its runtime caches.
• Tokens from emailed links (?token=) are exchanged immediately, then removed from the URL with history.replaceState.

#3. Responsive layout (based on the macOS design)

Breakpoints by viewport width for the shell; container queries for components (a table in a narrow pane reflows to cards even on desktop).

Shell anatomy (expanded), mirroring macOS:

┌ sidebar ────────┬ toolbar: title / subtitle ········ search · [actions] · bell · avatar ┐
│ Search  ⌘K      ├──────────────────────┬───────────────────────────────┬──────────────┤
│ PERSONAL        │ list pane            │ detail pane                   │ inspector    │
│  Home           │ (search, chips,      │ header: title, ID chip, badge │ (optional)   │
│  Organizations ●│  virtualized rows)   │ tabs                          │              │
│  Account        │                      │ content                       │              │
│  Settings       │                      │                               │              │
│ ADMINISTRATION  │                      │                               │              │
│ DEVELOPER       │                      │                               │              │
└─────────────────┴──────────────────────┴───────────────────────────────┴──────────────┘

Rules:

• Safe areas: env(safe-area-inset-*) on the bottom nav, sheets and toolbar (notches, home indicator); viewport-fit=cover.
• Dynamic viewport units (dvh) for full-height panes so mobile browser chrome doesn't hide the bottom nav.
• Content width capped at 760 px for forms/settings, tables use full pane width.
• 320 px minimum width with no horizontal scroll (WCAG reflow); browser zoom to 400 % keeps content usable (reflows to compact).
• On-screen keyboard: use visualViewport to keep the focused field and sheet buttons visible; interactive-widget=resizes-content.
• Orientation and window resizes (split-screen on iPad/Android, desktop window snapping) re-evaluate the class live without losing state; selection and scroll persist when panes collapse.

#4. Input adaptation

The app adapts to how the person is interacting, not only to screen size. Detect with media queries and Pointer Events; never with user-agent sniffing.

Tablets support touch, pencil, trackpad and keyboard at the same time. Handle every interaction with Pointer Events per event (pointerType) instead of a global "mode": a trackpad pointer gets hover previews and right-click menus, a finger gets long-press and swipe on the same screen, a pencil acts as a precise pointer (marquee selection, pen hover where supported, Scribble into text fields works natively), and a keyboard gets the full shortcut set.

#5. Interaction model

Every gesture and every shortcut accelerates an action that also has a visible button or menu item. Screen-reader and keyboard users reach every action without gestures.

#5.1 Desktop / pointer

#5.2 Touch

#5.3 Keyboard

macOS-style modifiers are shown as ⌘ on Apple platforms and Ctrl elsewhere (detect with navigator.userAgentData.platform / fallback). Shortcuts never override browser-reserved combos (⌘/Ctrl+1…9, N, T, W, R, L, D).

All shortcuts are listed in the ? dialog and in the palette next to their commands; single-key shortcuts are disabled while typing and can be turned off in SET-01 (WCAG 2.1.4).

#6. System preferences (live)

The UI follows the person's system settings automatically and updates live when they change — no reload.

The profile settings (SET-01) offer "Use device setting" as the default for language, time zone and appearance.

#7. Progressive Web App

#7a. Web Push (as app_hub)

#7b. Brand, icons & manifest

Assets: brand-assets/public/ mirrors the deployed web root (see shared/brand/BRAND.md).

#7c. Theming

theme/themes.css, theme/themes.ts, theme/head-snippet.html.

• All component colours are var(--sub-*) roles.
• applyTheme() sets data-scheme, data-light-theme and data-dark-theme on <html>, follows prefers-color-scheme in Match system, and updates <meta name="theme-color">.
• Put the inline head script first so there is no flash of the wrong theme.
• forced-colors: active hands colours to the OS.
• The PWA manifest keeps theme_color = Forest Floor background and background_color = Moss Paper background for the splash screen.
• SET-01: radiogroup swatch grid (5 columns desktop, 3 phone).

#8. Platform features used

#9. Accessibility (web specifics)

• WCAG 2.2 AA. Landmarks (nav, main, aside for inspector), one h1 per route, skip link to main, route-change focus to the heading + polite announcement of the page title.
• ARIA Authoring Practices for: grid (tables with row/cell navigation), listbox (lists with multi-select), tabs, menu/menubar, dialog/alertdialog, combobox (palette, selects), switch, treegrid not used.
• Target size ≥ 24 × 24 CSS px everywhere (2.5.8), ≥ 44 × 44 on coarse pointers.
• Dragging movements (2.5.7): every drag has a non-drag alternative (menu actions, move buttons).
• Focus not obscured (2.4.11): sticky toolbars/bottom nav use scroll-padding.
• Live regions: toasts role=status; errors role=alert; long operations announce completion.
• Test with VoiceOver (Safari macOS/iOS), NVDA + Firefox/Chrome, JAWS + Chrome, TalkBack + Chrome, Windows High Contrast (forced colors).

#10. Performance

Budgets from NON-FUNCTIONAL §1: LCP ≤ 2.5 s (4G mid-tier phone), INP ≤ 200 ms, CLS ≤ 0.1, ≤ 170 KB JS gzip for the initial route.

• Route-level code splitting; admin and developer sections never load for end users.
• Preload route data and code on intent (hover 100 ms, focus, touchstart, palette highlight).
• Skeletons sized like final content (no layout shift); images with explicit size; content-visibility: auto for long settings pages.
• Optimistic updates for toggles, role assignment, mark-read; everything else waits for the server.
• Web Workers for CSV parsing (bulk invites) and JSON diffing.
• fetchpriority=high on Home's first tiles; HTTP caching + SW for static assets with content hashes.
• Real-user monitoring of Core Web Vitals per route (no PII).

#11. Browser support & progressive enhancement

Build features as enhancements: detect ('share' in navigator, CSS.supports(...), 'startViewTransition' in document), never block a task when a feature is missing.

#12. Screens — web-specific construction

All screens, elements and API calls are in SCREENS.md (web controls column). Per-screen interaction extras:

#13. Testing checklist (web)

• Web Push in Chrome, Edge, Firefox, Safari (macOS) and installed PWA on iOS: subscribe, pushsubscriptionchange, click routing, badge, unsubscribe; polling fallback when permission is denied.
• Stripe Checkout/Portal round trip returning to /billing/return and the poll.
• Playwright projects: iPhone (WebKit, touch), Pixel (Chromium, touch), iPad (WebKit, touch + keyboard), desktop Chrome/Edge/Firefox/Safari.
• Every flow in UX-FLOWS with mouse only, keyboard only, touch only, and screen reader.
• Resize from 320 px to 2560 px on every archetype without losing state.
• Toggle each system preference (dark, reduced motion, forced colors, language, time zone) while the app is open — UI updates without reload.
• Install, go offline, reopen: Home renders read-only; writes disabled with explanation.
• Push, badge, share, share-target, file handlers on the browsers that support them; fallbacks on those that don't.
• Lighthouse/Web Vitals budgets on a throttled mid-tier phone; axe-core zero violations.