fix(docsite): stop mobile hero page-jump and polish the theme collage (#3401)

The home hero's theme reel re-skins the page on each swap. On mobile the card
collage sits in normal flow, so a theme with different fonts/spacing changed the
collage's height and reflowed the whole page every ~4.5s while autoplaying.

- Reserve a stable, theme-independent height for the collage so a theme swap
  can't reflow the page, and move its top gap to a non-themed wrapper (page.tsx)
  so --hero-gap/--spacing resolve in the docsite scale rather than the active
  theme's.
- Drop the earlier --spacing-* force-cast on the collage so every theme renders
  in its own authentic spacing again; the fixed height + bounded rows + flexible
  image cells absorb the per-theme size differences.
- Keep auto-advance desktop-only; mobile stays manual (swipe + dots).
- 2-col: the product/reward cards grow to fill the row (side row is
  content-sized) so the collage never leaves dead space.
- 3-col: size the row to fit the tallest theme's side column and distribute the
  side items with space-between so it fills without spilling past the cards;
  hoist the radio + badge pills into that distribution so their gap matches the
  rest.
- Pin the collage layout gaps (16px) and inner padding (24px) to constants so
  the column widths and gaps are identical across the 2-col/3-col breakpoints
  and across themes.
- Round the collage images with --radius-container (was --radius-element) so
  they match the card corners (most visible on Matcha: 18px vs 12px).
- Shorten the overly descriptive reel product names so the card titles fit on
  one line in the narrow 2-col cards without truncating (e.g. "Iced matcha
  latte" -> "Matcha", "Dried sea holly" -> "Sea holly", "Holo flip phone" ->
  "Phone").
- Use one consistent label ("Points") for the reward/progress card across all
  themes (was "Setup progress", "Loyalty perks", "Sparkle points", etc.).
- Apply the same shortened names in the /themes showcase preview so the hero and
  the theme gallery stay consistent.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: rubyycheung

apps/docsite/src/app/(site)/_landing/hero/HeroFloatingCards.tsx

@@ -51,9 +51,8 @@ const styles = stylex.create({
       '@media (min-width: 1024px)': 'block',
     },
   },
-  // Narrow-screen collage grid. <768px: 2 columns (product|reward, side below).
-  // 768–1024px: 3 columns (product | reward | side group). In flow inside the
-  // fixed hero content, so it's pinned and sits --hero-gap below the text.
+  // Narrow-screen collage grid. <768px: 2 cols (product|reward, side below);
+  // 768–1023px: 3 cols. Fixed-size box (see height) so a swap can't reflow the page.
   collage: {
     display: {
       default: 'grid',
@@ -68,7 +67,7 @@ const styles = stylex.create({
     },
     gridTemplateColumns: {
       default: '1fr 1fr',
-      '@media (min-width: 768px)': '1fr 1fr minmax(0, 240px)',
+      '@media (min-width: 768px)': '1fr 1fr 1fr',
     },
     gridTemplateAreas: {
       default: '"product reward" "side side"',
@@ -78,33 +77,46 @@ const styles = stylex.create({
     alignItems: 'stretch',
     justifyContent: 'center',
     textAlign: 'start',
-    columnGap: 'var(--spacing-4)',
-    rowGap: 'var(--spacing-4)',
+    // Literal, not var(--spacing-4): the collage renders inside <Theme> where
+    // Matcha/Y2K scale --spacing ~1.5×, so a token would differ per theme.
+    columnGap: 16,
+    rowGap: 16,
+    // Fixed height so a swap can't reflow the page (image cells absorb per-theme
+    // differences). 420px at 768-1023px fits the tallest theme's side column.
+    height: {
+      default: '665px',
+      '@media (min-width: 768px)': '420px',
+      '@media (min-width: 1024px)': 'auto',
+    },
+    // 2-col: side row is content-sized (`auto`), top cards take the rest (`1fr`);
+    // the fixed height means `auto` can't grow the box. 3-col: one row.
+    gridTemplateRows: {
+      default: 'minmax(0, 1fr) auto',
+      '@media (min-width: 768px)': 'minmax(0, 1fr)',
+      '@media (min-width: 1024px)': 'none',
+    },
     width: '100%',
     maxWidth: {
       default: 520,
       '@media (min-width: 768px)': 1200,
     },
     marginInline: 'auto',
-    paddingInline: 'var(--spacing-6)',
+    // Literal, like the gaps above — a themed value would make column widths
+    // differ per theme.
+    paddingInline: 24,
     boxSizing: 'border-box',
     zIndex: 0,
     pointerEvents: 'none',
   },
-  // Breaks the collage out of the 800px hero text column to span the viewport so
-  // the inner grid can center at the shared 1200px content width.
+  // Full-bleed wrapper so the inner grid can center at 1200px. Its top gap is
+  // set on a non-themed wrapper in page.tsx (heroCollageGap).
   collageBleed: {
     display: {
       default: 'block',
       '@media (min-width: 1024px)': 'none',
     },
     width: '100vw',
     marginInline: 'calc(50% - 50vw)',
-    // --hero-gap (96px) is too cavernous on phones; full gap returns at ≥768px.
-    marginBlockStart: {
-      default: 'var(--spacing-10)',
-      '@media (min-width: 768px)': 'var(--hero-gap)',
-    },
   },
   gaProduct: {
     gridArea: 'product',
@@ -120,26 +132,40 @@ const styles = stylex.create({
     minHeight: 0,
     textAlign: 'start',
   },
-  // Side group: flex column of the small items with a uniform gap. alignSelf
-  // start so it keeps its natural height (it's the row-height ruler).
+  // Side column (buy card, composer, pills). 3-col: stretch + space-between so it
+  // fills the fixed-height row. 2-col: content-sized row, so it keeps the 16px gap.
   gaSide: {
     gridArea: 'side',
     display: 'flex',
     flexDirection: 'column',
-    alignSelf: 'start',
-    gap: 'var(--spacing-3)',
+    alignSelf: 'stretch',
+    justifyContent: 'space-between',
+    gap: 16,
     minWidth: 0,
+    minHeight: 0,
     textAlign: 'start',
   },
-  // Radio + badge on one row, shrink to content.
+  // Radio + badge pills. 3-col: display:contents hoists them into the side
+  // column's space-between distribution so their gap matches the cards. 2-col:
+  // one centered row.
   collagePillRow: {
-    display: 'flex',
+    display: {
+      default: 'flex',
+      '@media (min-width: 768px)': 'contents',
+    },
     flexDirection: 'row',
     alignItems: 'center',
-    justifyContent: 'flex-start',
+    justifyContent: 'center',
     flexWrap: 'wrap',
     gap: 'var(--spacing-2)',
   },
+  // Left-align the pills when hoisted in 3-col (see collagePillRow); centered in 2-col.
+  pillSelf: {
+    alignSelf: {
+      default: 'center',
+      '@media (min-width: 768px)': 'flex-start',
+    },
+  },
   // Per-card reset in the collage: drop the overlap positioning + scaled pose.
   stackCard: {
     position: 'static',
@@ -150,19 +176,15 @@ const styles = stylex.create({
   collageProductBody: {
     height: '100%',
   },
-  // Image fills the card height without adding intrinsic height (flexBasis:0 +
-  // absolutely-filled img), so the side group stays the row-height ruler. minH
-  // gives a real height in 2-col (own row, nothing to stretch it); 0 in 3-col.
+  // Image fills the card height (flexBasis:0 + absolutely-filled img, minHeight:0)
+  // so it's the flexible element that absorbs each theme's text-height differences.
   collageImageFill: {
     position: 'relative',
     flexGrow: 1,
     flexBasis: 0,
-    minHeight: {
-      default: 180,
-      '@media (min-width: 768px)': 0,
-    },
+    minHeight: 0,
     overflow: 'hidden',
-    borderRadius: 'var(--radius-element)',
+    borderRadius: 'var(--radius-container)',
   },
   collageImageAbs: {
     position: 'absolute',
@@ -181,10 +203,7 @@ const styles = stylex.create({
     position: 'relative',
     flexGrow: 1,
     flexBasis: 0,
-    minHeight: {
-      default: 180,
-      '@media (min-width: 768px)': 0,
-    },
+    minHeight: 0,
     overflow: 'hidden',
   },
   // Shared base for the overlap-layout floating cards.
@@ -212,7 +231,7 @@ const styles = stylex.create({
   // Shared image helpers.
   imageFrame: {
     overflow: 'hidden',
-    borderRadius: 'var(--radius-element)',
+    borderRadius: 'var(--radius-container)',
   },
   image: {
     width: '100%',
@@ -287,6 +306,10 @@ const styles = stylex.create({
     borderWidth: 0,
     boxShadow: 'none',
     whiteSpace: 'nowrap',
+    alignSelf: {
+      default: 'center',
+      '@media (min-width: 768px)': 'flex-start',
+    },
   },
   buyCard: {
     left: '80%',
@@ -300,7 +323,7 @@ const styles = stylex.create({
     height: 'var(--spacing-12)',
     flexShrink: 0,
     overflow: 'hidden',
-    borderRadius: 'var(--radius-element)',
+    borderRadius: 'var(--radius-container)',
   },
   fullWidth: {
     width: '100%',
@@ -337,6 +360,7 @@ export function HeroFloatingCards({
       variant="green"
       label={content.pills.leading}
       icon={<Sparkles size={12} />}
+      xstyle={styles.pillSelf}
     />
   );
 

apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsx

@@ -229,6 +229,9 @@ export function HeroReelProvider({children}: {children: ReactNode}) {
   const [index, setIndex] = useState(0);
   const [paused, setPaused] = useState(false);
   const reduceMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+  // Auto-advance is desktop-only; on mobile the reel stays manual (swipe + dots)
+  // so the cards don't move on their own while the user reads/scrolls.
+  const isNarrow = useMediaQuery('(max-width: 1023px)');
   const {themeMode: userMode} = useThemeMode();
 
   const goTo = useCallback(
@@ -282,14 +285,20 @@ export function HeroReelProvider({children}: {children: ReactNode}) {
   );
 
   useEffect(() => {
-    if (!AUTOPLAY_ENABLED || reduceMotion || paused || slides.length <= 1) {
+    if (
+      !AUTOPLAY_ENABLED ||
+      reduceMotion ||
+      isNarrow ||
+      paused ||
+      slides.length <= 1
+    ) {
       return;
     }
     const id = window.setInterval(() => {
       setIndex(i => (i + 1) % slides.length);
     }, ADVANCE_INTERVAL_MS);
     return () => window.clearInterval(id);
-  }, [reduceMotion, paused, slides.length]);
+  }, [reduceMotion, isNarrow, paused, slides.length]);
 
   useEffect(() => {
     const onVisibility = () => setPaused(document.hidden);

apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.ts

@@ -124,7 +124,7 @@ const CONTENT_BY_THEME: Record<string, HeroThemeContent> = {
     pills: {leading: 'Limited time', trailing: 'Free shipping'},
     chatPrompt: 'How can I help?',
     reward: {
-      label: 'Setup progress',
+      label: 'Points',
       value: 7,
       total: 8,
       member: 'Astryx team',
@@ -150,7 +150,7 @@ const CONTENT_BY_THEME: Record<string, HeroThemeContent> = {
     pills: {leading: 'Limited time', trailing: 'Free shipping'},
     chatPrompt: 'How can I help?',
     reward: {
-      label: 'Member rewards',
+      label: 'Points',
       value: 6,
       total: 10,
       member: 'Alex Rivera',
@@ -170,17 +170,17 @@ const CONTENT_BY_THEME: Record<string, HeroThemeContent> = {
     },
     mini: {
       image: `${IMAGE_CDN}/Butter-Pancake.png`,
-      title: 'Buttermilk pancakes',
+      title: 'Pancakes',
       description: 'Stacked tall with melting butter.',
     },
     pills: {leading: 'Limited time', trailing: 'Free shipping'},
     chatPrompt: 'How can I help?',
-    reward: {label: 'Loyalty perks', value: 5, total: 9, member: 'Noa Bright'},
+    reward: {label: 'Points', value: 5, total: 9, member: 'Noa Bright'},
   },
   '@astryxdesign/theme-matcha': {
     product: {
       image: `${IMAGE_CDN}/matcha-product-1.png`,
-      title: 'Iced matcha latte',
+      title: 'Matcha',
       description: 'Stone-ground ceremonial matcha over cold milk.',
       price: '$6',
     },
@@ -197,7 +197,7 @@ const CONTENT_BY_THEME: Record<string, HeroThemeContent> = {
     pills: {leading: 'Limited time', trailing: 'Free shipping'},
     chatPrompt: 'How can I help?',
     reward: {
-      label: 'Reward progress',
+      label: 'Points',
       value: 7,
       total: 8,
       member: 'Lottie Wang',
@@ -206,7 +206,7 @@ const CONTENT_BY_THEME: Record<string, HeroThemeContent> = {
   '@astryxdesign/theme-gothic': {
     product: {
       image: `${IMAGE_CDN}/Gothic-1.png`,
-      title: 'Dried sea holly',
+      title: 'Sea holly',
       description: 'A single preserved thistle stem with a steely bloom.',
       price: '$24',
     },
@@ -217,17 +217,17 @@ const CONTENT_BY_THEME: Record<string, HeroThemeContent> = {
     },
     mini: {
       image: `${IMAGE_CDN}/Gothic-3.png`,
-      title: 'Lilac ranunculus',
+      title: 'Ranunculus',
       description: 'Layered petals in a soft mauve.',
     },
     pills: {leading: 'Limited time', trailing: 'Free shipping'},
     chatPrompt: 'How can I help?',
-    reward: {label: 'Member rewards', value: 7, total: 8, member: 'Mara Vale'},
+    reward: {label: 'Points', value: 7, total: 8, member: 'Mara Vale'},
   },
   '@astryxdesign/theme-y2k': {
     product: {
       image: `${IMAGE_CDN}/Y2K-Phone.png`,
-      title: 'Holo flip phone',
+      title: 'Phone',
       description: 'Iridescent clamshell with a rainbow screen.',
       price: '$18',
     },
@@ -238,12 +238,12 @@ const CONTENT_BY_THEME: Record<string, HeroThemeContent> = {
     },
     mini: {
       image: `${IMAGE_CDN}/Y2K-Butterfly.png`,
-      title: 'Glitter butterfly',
+      title: 'Butterfly',
       description: 'Sparkly stick-on in pastel chrome.',
     },
     pills: {leading: 'Limited time', trailing: 'Free shipping'},
     chatPrompt: 'How can I help?',
-    reward: {label: 'Sparkle points', value: 6, total: 8, member: 'Bella Cruz'},
+    reward: {label: 'Points', value: 6, total: 8, member: 'Bella Cruz'},
   },
 };
 
@@ -262,7 +262,7 @@ function fallbackContent(name: string): HeroThemeContent {
     mini: {image, title: 'Featured', description: 'In stock now.'},
     pills: {leading: 'Limited time', trailing: 'Free shipping'},
     chatPrompt: 'How can I help?',
-    reward: {label: 'Member rewards', value: 6, total: 10, member: 'Sam Lee'},
+    reward: {label: 'Points', value: 6, total: 10, member: 'Sam Lee'},
   };
 }
 

apps/docsite/src/app/(site)/page.tsx

@@ -98,6 +98,14 @@ const styles = stylex.create({
     maxWidth: 420,
     marginInline: 'auto',
   },
+  // Top gap for the narrow-screen collage, set outside the reel's <Theme> so
+  // --hero-gap/--spacing resolve in the docsite scale (constant across swaps).
+  heroCollageGap: {
+    marginBlockStart: {
+      default: spacingVars['--spacing-10'],
+      '@media (min-width: 768px)': 'var(--hero-gap)',
+    },
+  },
   // On dark slides the hero text switches to a light ink (headline/links inherit).
   heroTextDark: {
     color: 'var(--hero-on-dark)',
@@ -238,11 +246,12 @@ function HeroContent({contentRef}: {contentRef: Ref<HTMLElement>}) {
           </Link>
         </Text>
       </VStack>
-      {/* Narrow-screen collage — rendered inside the (fixed) hero content so it's
-          pinned with the text and sits a consistent --hero-gap below it. The
-          desktop overlap layer (HeroReelCards) hides below 1024px; this
-          self-hides at ≥1024px. */}
-      <HeroReelStack />
+      {/* Narrow-screen collage. The wrapper's gap is non-themed so it stays
+          constant across theme swaps. Overlap layer (HeroReelCards) takes over
+          ≥1024px; this self-hides there. */}
+      <div {...stylex.props(styles.heroCollageGap)}>
+        <HeroReelStack />
+      </div>
       {/* DarkScope flips the dot ink to the active slide's light/dark mode. */}
       <DarkScope isDark={isDark}>
         <div data-home-page="true" {...stylex.props(styles.heroDots)}>