[Tracker] Responsive web — server-safe breakpoints, mobile components & gestures, RSC

[cixzhang]

Problem

Astryx has strong responsive primitives in places — useMediaQuery, an AppShell that collapses to MobileNav, lab:Drawer sheets, @media (hover: hover) guards, dynamic viewport units (dvh) — but there is no cohesive responsive-web system. Breakpoint logic is hand-rolled per consumer with a client hook, so it doesn't hold up under RSC/SSR (server renders the desktop tree, then flips on hydration). Mobile affordances (bottom sheet, swipe/gesture dismissal, safe-area insets, hover→tap conversion, on-screen-keyboard handling) are missing or partial, and there's no documented contract for how components should behave across breakpoints.

This is the Q3 push to make Astryx responsive-first: a server-safe breakpoint system, first-class mobile components and gestures, and the guidance/rubric to keep it healthy over time.

This is a tracker. Each item is (or will be) filed as its own issue and lands via the normal issue → API → PR flow. Checked = shipped; linked issues exist; unlinked items still need filing.

Breakpoint system (server-safe, CSS-first)

The core architectural bet: default to CSS-first breakpoints (@media / @container in StyleX, declarative hideBelow/showBelow-style props) so responsive layout renders correctly on the server with no hydration flash, and reserve the useMediaQuery JS hook for genuinely behavioral cases in small client islands.

• CSS-first responsive panel visibility — replace hand-rolled useMediaQuery hiding — LayoutPanel: responsive hideBelow prop (replace hand-rolled useMediaQuery panel hiding in templates) #3339
• Responsive prop values for layout (breakpoint-keyed sizing/spacing) — targeting layouts
• Responsive ratio on AspectRatio — XDSAspectRatio: support a responsive ratio (forces double-element workarounds today) #2798
• Responsive type/size on Heading/Text (fluid typography) — XDSHeading/XDSText: no responsive type/size prop — fluid display headlines require a hand-written @media override #2580
• Container layout primitive with responsive gutters — Add a Container layout primitive (centered max-width column with responsive gutters) — no current primitive covers it; Section doesn't center and only takes discrete padding #3492
• Named breakpoint scale exposed to consumers (align to AppShell sm/md/lg)

Mobile components & gestures

• Sheet / Drawer component API — layer integration + optional mobile swipe — [RFC] Sheet component — API review (evaluate DJ's Drawer draft: layer integration + optional mobile swipe) #3675
• Sheet / Drawer slide-out panel (harden the existing lab:Drawer) — XDSSheet / XDSDrawer — slide-out panel (318 combined usages) #575, XDS: no Drawer/Sheet component for side-anchored slide-in panels #2575
• Bottom sheet: grab handle + swipe-to-dismiss + snap points (net-new; the current Drawer sheet dismisses only via scrim/Escape/close)
• Safe-area insets (env(safe-area-inset-*) + viewport-fit=cover) for bottom-anchored UI
• On-screen-keyboard-aware layout for sheets/composers (interactive-widget + keyboard insets)
• Floating action button (FAB) pattern
• Top nav mega menu overflows — the menu doesn't fit/scroll below a breakpoint and content is clipped — fix(TopNav): clamp mega menu panel to viewport width #4558

Hover, touch & pointer behavior

• Mobile access for HoverCard and Tooltip — touch has no path to reveal them — Mobile access for HoverCard and Tooltip (touch has no path to reveal them) #3885
• Hover→tap conversion guidance — documented rubric for when to convert hover affordances on touch
• PowerSearch mobile edit experience — bottom sheet / responsive overlay — PowerSearch: improve the mobile edit-popover experience (bottom sheet / responsive overlay; coordinate with responsive + Sheet work) #4250

Modals & dialogs on mobile

• Responsive Dialog — auto-adapt to a bottom-sheet/fullscreen presentation below a breakpoint (Dialog has a fullscreen variant today but no automatic mobile adaptation)

Responsiveness on RSC

• Make the breakpoint system server-safe end to end (see Breakpoint system above)
• Audit AppShell's useMediaQuery-driven mobile split for hydration flash

Theme

• Mobile theme — exploration

Maintenance

• Mobile responsiveness rubric — preserve responsive guidance over time for new components and situations (docs + review checklist)

---

Related (tracked separately, not owned here)

• [RFC] Platform-aware Astryx — web + native (React Native/Expo) contract — [RFC] Platform-aware Astryx — web + native mobile contract, docs, and Expo integration #3912. Native platform support is a distinct workstream from responsive web; kept separate to avoid constraining the web API to a lowest-common-denominator cross-platform contract.
• [Bug] MobileNav close freezes the page in Safari 26.1 — [Bug] MobileNav close freezes the page in Safari 26.1 #4290. Bugs are tracked on their own; referenced here for visibility.

Deliverables from the responsive-web plan: breakpoint system incl. targeting layouts · mobile theme (exploration) · bottom sheet · hover-behavior guidance · gestures/swipes · modals & dialogs on mobile · responsiveness on RSC · mobile maintenance rubric.