Substratal Apps Substratal Apps Hub specs
GitHub

Docs web README.md

Substratal Hub for Web (PWA) — Team Handoff

Standard: Responsive PWA based on the macOS design; WCAG 2.2 · Stack: TypeScript, React, React Aria, TanStack, Workbox API: Substratal Apps Platform API v1.4.0 (openapi 1.0.0-draft.3) — https://compositecode.github.io/substratalapps.com/

Web-specific: the responsive layout classes, input adaptation, PWA, live system preferences and platform APIs are in PLATFORM-SPEC §3–§8; per-screen behavior at each size is in §12.

Reading order

  1. shared/CHANGES.md — what's new in this edition (push notifications, Free/Standard billing)
  2. shared/PRODUCT-SPEC.md — scope, personas, domains, phases, acceptance criteria
  3. PLATFORM-SPEC.md — how this app is built on Web (PWA)
  4. SCREENS.md — all 75 screens with native containers and controls (the build checklist)
  5. shared/CLIENT-ARCHITECTURE.md — sessions, request conventions, Capabilities, push and inbox (§6), billing hand-off (§9)
  6. shared/UX-FLOWS.md (+ shared/flows/*.svg) — the 16 end-to-end flows
  7. mockups/index.html / screens/ — reference renders in the default light (Moss Paper) and dark (Forest Floor) themes; ?mode=dark&light=<id>&dark=<id> previews any theme
  8. While building: shared/COMPONENTS.md, shared/COPY-AND-STATES.md, shared/ACCESSIBILITY.md, shared/NON-FUNCTIONAL.md, shared/OPEN-QUESTIONS.md, shared/API-SCREEN-MAP.csv

Themes: theme/ has this platform's implementation of the 5 light and 5 dark themes. Rules are in shared/THEMES.md; wiring is in PLATFORM-SPEC.md (Theming section).

Logo & app icon: brand-assets/ has every icon and logo file this app needs. Wiring is in PLATFORM-SPEC.md (Brand & app icon section) and rules in shared/brand/BRAND.md.

Definition of done (per screen)

  • Elements, data bindings and API calls match SCREENS.md
  • Reachable by its route / deep link; restores state from the route
  • Gated by Capabilities per shared/INFORMATION-ARCHITECTURE.md §2
  • Loading, empty, error (401/403/404/409/422/429/503) and offline states
  • Idempotency-Key on creates, If-Match on edits, conflict handling
  • Every gesture/shortcut has a visible equivalent; screen reader and largest text size pass
  • Copy matches shared/COPY-AND-STATES.md
  • Correct in both default themes and in every other theme (colours only from theme roles, no literals); high-contrast modes fall back to system colours
  • Logo and icons come only from brand-assets/ (no redraws), with accessible name "Substratal Apps"
  • Flag-gated features (notifications, push, billing) hide cleanly on 501

Reference screens