fix(docsite): pin the hero with sticky rails, drop the overscroll suppression

[AKnassa]

Step 2 of #5392. Fixes #5470.

What this does

Keeps the home page hero pinned exactly as it is today, but without the CSS rule that switched off the browser's native overscroll. On a Mac trackpad the page rubber-bands again at the top and bottom, like every other page on the web. Nothing changes visually.

Why

The hero's three pinned layers (the aurora glow, the floating cards and the headline block) were position: fixed. A fixed layer is glued to the screen rather than to the page, so when the page rubber-bands past its own end the layer sits in the gap that opens up. #3032 hid that by turning overscroll off for the whole site, and #5415 narrowed the rule to desktop widths to give mobile its pull-to-refresh back. This finishes the job: the layers are now position: sticky inside full-height rails, so they lift with the page and physically cannot paint past its end. That is structural, which is why the rule can be deleted instead of narrowed further.

What changed

• Each pinned layer rides its own rail: a position: absolute; inset: 0 box that is a direct child of heroScope, spans the hero band and the showcase, and sits ahead of the showcase overlay so tree order still equals paint order (backdrop, cards, hero text, then the showcase covering them). A rail inside the 760px band alone releases its layer after about 48px, which is the trap the issue calls out.
• backdropGlow, the cards stage and heroContent go fixed -> sticky; top: var(--appshell-header-height) at 1024px and up. Narrow widths are untouched: the glow stays absolute and the hero text stays in flow.
• Centering moves from left: 50% + translateX(-50%) to auto margins in the full-width rail (on a sticky box left is an inset, not an offset). The 1200px box is capped to the rail's width rather than 100vw: with a classic scrollbar 100vw is wider than the rail, which zeroes the auto margins and shoves the box left.
• HeroReelProvider renders no DOM any more. Its hover / focus / touch surface is the new HeroReelSwipeArea, which page.tsx uses as the hero text's rail, so the band and its gutters still pause the reel and the phone collage still swipes. HeroReelCards is split into HeroReelBackdrop (fills + glow) and HeroReelCards (stage).
• The @media (min-width: 1024px) { html { overscroll-behavior-y: none } } block is deleted from globals.css.
• A comment on LayoutContent's overflow: clip records why it must stay clip: hidden or auto there would silently un-pin the landing page (the issue asked for this).
• New home-hero-overscroll.test.ts. The docsite suite is node-only with StyleX untransformed, so these are source invariants in the shape of component-preview-theme.test.ts: globals.css never suppresses overscroll at any width; none of the three layers is ever fixed in any media arm; the rails are bounded by heroScope and precede the showcase; the boxes are sized against the rail, not 100vw; and the AppShell / LayoutContent links that keep the main area a non-scroll container (overflow: clip, isScrollable={isFill}, the landing layout's height="auto") hold. It is red on main today, and 11 single-line mutations (a fixed behind a trailing comment, double quotes, a computed [BREAKPOINT] key, an overflowY longhand, isScrollable unconditional, height="fill", the width back to 100vw, heroScope static, a rail moved after the showcase, overscroll-behavior: contain, an uppercase rule) each turn it red again.

How to see it

Nothing should look different; that is the point. Run the docsite with the canary banner off so the header is the production 48px (NEXT_PUBLIC_DOCS_TARGET=latest pnpm -F @astryxdesign/docsite dev), open the home page on a Mac and rubber-band at the bottom: the page bounces and the footer stays clean. The Vercel preview on this PR shows the same page.

Measured against an untouched main checkout with Playwright + pixelmatch, both served with the banner hidden, prefers-reduced-motion: reduce so the reel holds its first slide, and transitions frozen, at ten scroll offsets per viewport (0, 100, 200, 400, 712, 760, 800, 1400, 2200, max):

viewport	pixels differing from main	overscroll-behavior-y	fixed layers reaching the viewport bottom at page end
1280 x 900	0	none -> auto	2 -> 0
1280 x 600	0	none -> auto	3 -> 0
1440 x 1400	0	none -> auto	0 -> 0
1024 x 768	0	none -> auto	2 -> 0
900 x 1200	0	auto -> auto	0 -> 0
390 x 844	0	auto -> auto	0 -> 0

Layer geometry matches fixed at every offset (hero text at y=48 and 712px tall, glow and stage at x=40 and 1200px wide at 1280) until max scroll, where sticky releases behind the opaque showcase. Document height is unchanged (3540px). elementFromPoint on the "Get started" button still returns the button.

Also checked on both trees: hover in the gutter, on the CTA and over the pinned hero while scrolled pauses the reel, hover on the showcase does not, keyboard focus on a dot pauses and blur resumes, a phone swipe steps the reel left and right and a vertical drag does not (11 checks, identical results before and after); resize while scrolled (1280 -> 1440 -> 1100 at scroll 400) and a theme swap mid-scroll with transitions running, 0 pixels differing; and a forced 15px classic scrollbar, where the old fixed box sat at x=-7.5 overflowing both sides and the new one sits centered inside the rail.

pnpm -F @astryxdesign/docsite test (27 files, 413 tests), tsc --noEmit, strict eslint and pnpm lint:strict (0 errors) are green.

Not verified here

Safari and WebKit, and a real rubber-band gesture, which cannot be driven headlessly. That is the careful visual pass the issue budgets for.

Related

• fix(docsite): bound the hero's pin so overscroll works everywhere #5431 takes the other route the issue mentions (a zero-height sticky pin with absolute children) and has been conflicting since fix(docsite): restore pull-to-refresh on mobile, scope the overscroll suppression to desktop #5415 landed; this follows the rails design written up in docsite: contain the desktop-pinned hero layers so overscroll suppression can be removed entirely #5470 instead.
• docs(docsite): correct two stale backdropGlow comments left by #5415 #5467 corrects the backdropGlow comment's causal chain; that comment is rewritten here with the same correction, so the two overlap if both land.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Error		Aug 25, 2026 4:51am

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Layout _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	1481	-
Complexity	N/A	Very High (84)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.8KB	1.2KB

Accessibility Audit

Status: 1 accessibility violation(s) found — 1 serious.

Layout - 1 issue(s)

• 🟠 serious: Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
  • Rule: color-contrast · Affects 1/18 stories · Learn more
  • WCAG: 1.4.3 (Level AA)

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}