Broaden spec to app-wide rollout of design foundations

docs/superpowers/specs/2026-07-03-app-wide-desktop-design.md

@@ -1,33 +1,63 @@
-# Listing detail page — desktop/web design pass
+# Desktop/web design pass — global foundations + listing detail page
 
 ## Problem
 
-The listing detail screen (`app/src/app/listing/[id].tsx`) looks noticeably worse on
+The app looks noticeably worse on web/desktop than the HTML design prototype
-web/desktop than the HTML design prototype (`prototype/Volana.dc.html`, "LISTING
+(`prototype/Volana.dc.html`): content runs edge-to-edge with no max-width,
-DETAIL" section, lines 423-543): content runs edge-to-edge with no max-width, the
+typography doesn't scale up for desktop, secondary text has no visual hierarchy,
-hero is an oversized flat-color box with a tiny emoji, typography doesn't scale up
+addresses/fees aren't distinguished from regular text, and there's no shared,
-for desktop, the sidebar isn't visually a distinct card, and several shared
+theme-token-driven system for any of this — every screen does its own ad-hoc
-components it depends on (`TopNav`, `ListingCard`) have the same issues since they're
+centering and spacing.
-reused across other screens.
+
+The listing detail screen (`app/src/app/listing/[id].tsx`) is the worst offender
+(hero is an oversized flat-color box with a tiny emoji, sidebar isn't visually a
+distinct card) and gets a full page-specific redesign here. But the underlying
+problem — no shared container, no responsive typography/spacing scale, no
+consistent treatment of muted/subtle text and monospace data — is app-wide, so
+this spec has two layers:
+
+1. **Foundations** (theme, fonts, `PageContainer`, typography/spacing
+   conventions, hover pattern): built once, applied to every screen.
+2. **Listing detail page**: the one screen that also gets a full page-specific
+   redesign (hero, purchase sidebar, verified/about sections) to close the gap
+   with its prototype counterpart.
+
+Other screens (Home, Browse, Orders, Order Detail) get layer 1 applied to their
+*existing* layout and content — this spec does not redesign their structure or
+add new sections to them, only replaces ad-hoc containers/spacing/text-color
+choices with the shared foundations.
 
 ## Scope
 
-Primary target: `app/src/app/listing/[id].tsx`. Because two of the fixes (navbar,
+**Foundations (app-wide):**
-"customers also bought" cards) live in shared components also used by
+- `app/src/global.css` (theme tokens)
-`(tabs)/index.tsx`, `(tabs)/browse.tsx`, and `(tabs)/orders.tsx`, this spec also
-covers:
-- `app/src/components/TopNav.tsx`
-- `app/src/components/ListingCard.tsx`
-- `app/src/components/StatusChip.tsx`
-- `app/src/components/ResolverCard.tsx`
-- A new `app/src/components/PageContainer.tsx`
-- `app/src/global.css` (theme)
 - `app/src/app/_layout.tsx` (font loading)
+- A new `app/src/components/PageContainer.tsx`
+- `app/src/components/StatusChip.tsx`, `app/src/components/ResolverCard.tsx`,
+  `app/src/components/TopNav.tsx`, `app/src/components/ListingCard.tsx` (shared
+  components, used across screens)
+- `app/src/app/(tabs)/index.tsx` (Home) — wrap in `PageContainer`, adopt the
+  spacing scale
+- `app/src/app/(tabs)/browse.tsx` (Browse) — wrap in `PageContainer`, filter
+  captions ("Currency", "Sort") adopt the micro-label convention
+- `app/src/app/(tabs)/orders.tsx` (Orders list) — wrap in `PageContainer`
+  (replacing its current `md:mx-auto md:w-full md:max-w-2xl` ad-hoc centering)
+- `app/src/app/orders/[id].tsx` (Order detail) — wrap in `PageContainer` (same
+  ad-hoc centering to replace), "Order Progress" caption adopts the micro-label
+  convention
+- `app/src/components/OrderRow.tsx` — seller address adopts the monospace
+  convention
+- `app/src/components/CheckoutSheet.tsx` — `listing.seller` adopts the
+  monospace convention (no `PageContainer`; it's a bottom sheet, not a page)
 
-Out of scope: on-chain/wallet logic, `(tabs)/index.tsx` and `(tabs)/browse.tsx`
+**Listing detail page (full redesign):** `app/src/app/listing/[id].tsx`, covered
-layout beyond what `ListingCard` changes give them for free, `WalletConnectSheet`,
+in detail below.
-`CheckoutSheet`, the mobile/desktop nav breakpoint (768px) itself, nav
+
-blur/translucency.
+Out of scope: on-chain/wallet logic, redesigning the *content/structure* of
+Home/Browse/Orders/Order Detail (their current sections, copy, and interactions
+stay as they are — only containers/spacing/text treatment change),
+`WalletConnectSheet` (no addresses or long text needing the new conventions),
+the mobile/desktop nav breakpoint (768px) itself, nav blur/translucency.
 
 The prototype (`prototype/Volana.dc.html`) is the visual source of truth; it has
 **zero responsive/mobile CSS** — it's a desktop-only mockup, no `@media` queries
@@ -126,6 +156,45 @@ Used to wrap:
 - The entire `ListingDetailScreen` body (hero, two-column detail layout, and
   "Customers also bought" section all inside one container, mirroring the
   prototype's single wrapping div)
+- `(tabs)/index.tsx`, `(tabs)/browse.tsx`, `(tabs)/orders.tsx`, and
+  `orders/[id].tsx` — see "App-wide rollout" below
+
+## App-wide rollout
+
+The foundational pieces above (theme tokens, fonts, `PageContainer`, the
+typography/spacing conventions defined per-element in the Listing detail section
+below, the `onHoverIn`/`onHoverOut` web-hover pattern) apply to every screen once
+built — theme tokens and fonts are global by construction (`global.css` /
+root-layout font loading), and shared components (`StatusChip`, `ResolverCard`,
+`ListingCard`, `TopNav`) pick up the changes automatically wherever they're used.
+The remaining screens need explicit, mechanical updates to adopt the rest:
+
+- **Home (`(tabs)/index.tsx`):** replace the manual `px-5` / `md:items-center`
+  centering with `PageContainer`. Content and copy are unchanged.
+- **Browse (`(tabs)/browse.tsx`):** wrap the filter bar and list/grid in
+  `PageContainer`. The "Currency" and "Sort" filter captions adopt the
+  micro-label convention (`text-[11px] font-semibold uppercase tracking-wider
+  text-subtle`) in place of their current `type="body-xs" color="muted"`.
+  `ListingCard`'s grid-variant changes apply automatically. Add the
+  `onHoverIn`/`onHoverOut` hover pattern to `ListingCard`'s list variant too
+  (currently only specified for the grid variant).
+- **Orders list (`(tabs)/orders.tsx`):** replace `md:mx-auto md:w-full
+  md:max-w-2xl` with `PageContainer`. `OrderRow`'s `order.seller` address adopts
+  the monospace convention (`Typography type="code"` stripped of its background,
+  `DMMono_500Medium` via `style`, same as the listing detail page's addresses).
+  Add the hover pattern to `OrderRow` (it's a pressable row, currently no hover
+  feedback).
+- **Order detail (`orders/[id].tsx`):** replace the same `md:mx-auto
+  md:w-full md:max-w-2xl` pattern with `PageContainer`. `order.seller` adopts
+  the monospace convention. The "Order Progress" caption adopts the micro-label
+  convention.
+- **`CheckoutSheet`:** `listing.seller` adopts the monospace convention. No
+  `PageContainer` — it's a bottom sheet, not a full-width page, so there's no
+  max-width to enforce.
+
+None of these screens get new sections, restructured layout, or copy changes —
+only their container, spacing, and text-treatment building blocks change to the
+shared ones.
 
 ## Listing detail layout (`app/src/app/listing/[id].tsx`)
 
@@ -242,16 +311,22 @@ the grid view on the browse tab:
 
 ## Cross-cutting
 
-- Vertical spacing between major sections on the listing detail screen:
+- Vertical spacing between major sections: `gap-6 lg:gap-10` in place of flat,
-  `gap-6 lg:gap-10` (was flat `gap-5`/`gap-6` with no responsive scaling).
+  non-responsive gaps — applied on the listing detail screen and, where a
-- Web-only hover states (resolver cards, related-product cards) via the
+  screen has analogous major-section breaks, on Home/Browse/Orders/Order Detail
-  `onHoverIn`/`onHoverOut` local-state pattern described above — applied
+  too (their existing gap values step up responsively rather than changing which
-  consistently wherever this spec calls for hover feedback.
+  sections exist).
+- Web-only hover states (resolver cards, related-product cards in both
+  `ListingCard` variants, `OrderRow`) via the `onHoverIn`/`onHoverOut`
+  local-state pattern described above — applied consistently wherever this spec
+  calls for hover feedback, on every screen that uses these shared components.
 - Mobile regression check: since the two-column breakpoint moves from `md` (768px)
   to `lg` (1024px), mobile and tablet-portrait layouts stay single-column longer
   than today, which is a safe direction (less likely to cramp a mid-size viewport),
   not a regression risk in itself. Verify at implementation time on a phone-width
-  viewport that spacing/typography changes don't look oversized before `lg`.
+  viewport that spacing/typography changes don't look oversized before `lg` — on
+  the listing detail page and on every other screen touched by the app-wide
+  rollout.
 
 ## Testing
 
@@ -259,4 +334,6 @@ No test runner is configured in this repo (per `CLAUDE.md`). Verification is:
 `npm run typecheck`, `npm run lint`, and manual check in a running `expo start`
 web session at mobile (<768px), tablet (~900px), and desktop (>=1320px) widths,
 plus a native (iOS or Android simulator) pass to confirm nothing web-only leaked
-into native rendering.
+into native rendering. The manual pass covers every screen touched by this spec —
+Home, Browse, Orders list, Order Detail, and Listing Detail — not just the
+primary target.