An open source design system that's fully customizable and agent ready
TypeScript
fix(docsite): preload hero reel theme fonts and images to remove first-visit jank (#3047)
Cindy Zhangfb3d85053784
diff --git a/apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsx b/apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsxindex 91e86fd0c2..f53dc5639f 100644--- a/apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsx+++ b/apps/docsite/src/app/(site)/_landing/hero/HeroThemeReel.tsx@@ -29,7 +29,12 @@ import {Text} from '@astryxdesign/core/Text';import {Pagination} from '@astryxdesign/core/Pagination';import {useMediaQuery} from '@astryxdesign/core/hooks';import {useThemeMode} from '../../../providers';-import {HERO_THEME_SLIDES, type HeroThemeSlide} from './heroThemeContent';+import {+ HERO_THEME_SLIDES,+ REEL_FONT_SPECIFIERS,+ REEL_IMAGE_SRCS,+ type HeroThemeSlide,+} from './heroThemeContent';import {AstryxLogo} from '../../../../components/logos';import {HeroFloatingCards} from './HeroFloatingCards';@@ -247,6 +252,47 @@ export function HeroReelProvider({children}: {children: ReactNode}) {return () => document.removeEventListener('visibilitychange', onVisibility);}, []);+ // Warm the reel's per-theme assets once, after first paint, so first-time+ // visitors don't see fonts flash (FOUT) and product photos pop in as the reel+ // auto-advances. The @font-face rules ship in the docsite's Google Fonts+ // <link>, but a family's woff2 is only fetched when a glyph using it first+ // paints — and the remote card photos aren't fetched until their slide+ // renders; both happen mid-swap on a cold cache. Kicking the fetches off here+ // (off the critical path, scoped to just the reel's ~9 fonts and photos) gets+ // them into cache before the first 4.5s advance without touching initial LCP.+ useEffect(() => {+ if (typeof window === 'undefined') {+ return;+ }+ // Defer to idle time so warming never competes with first paint / LCP.+ const schedule =+ window.requestIdleCallback?.bind(window) ??+ ((cb: () => void) => window.setTimeout(cb, 200));+ const cancel =+ window.cancelIdleCallback?.bind(window) ?? window.clearTimeout;++ const handle = schedule(() => {+ // Fonts: ask the CSS Font Loading API to load each reel family. This pulls+ // the woff2 the @font-face rule points at without us hardcoding gstatic's+ // hashed URLs (which rotate). Failures (e.g. a family not in the sheet)+ // are non-fatal — the slide just paints its fallback as it does today.+ if (typeof document !== 'undefined' && document.fonts?.load) {+ for (const spec of REEL_FONT_SPECIFIERS) {+ document.fonts.load(spec).catch(() => {});+ }+ }+ // Images: prime the browser cache with the reel's product photos so they+ // are decoded by the time their slide swaps in.+ for (const src of REEL_IMAGE_SRCS) {+ const img = new Image();+ img.decoding = 'async';+ img.src = src;+ }+ });++ return () => cancel(handle as never);+ }, []);+const value = useMemo<HeroReelState>(() => ({slides, index, goTo, animate: !reduceMotion, setPaused, userMode}),[slides, index, goTo, reduceMotion, userMode],diff --git a/apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.ts b/apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.tsindex 8847400dc3..193b1d8785 100644--- a/apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.ts+++ b/apps/docsite/src/app/(site)/_landing/hero/heroThemeContent.ts@@ -313,7 +313,9 @@ function wordmarkColorFor(name: string): string {}// Dark-first themes (rendered in dark mode; hero text/nav go light).-const DARK_THEMES: ReadonlySet<string> = new Set<string>(['@astryxdesign/theme-gothic']);+const DARK_THEMES: ReadonlySet<string> = new Set<string>([+ '@astryxdesign/theme-gothic',+]);// Per-theme aurora blob palettes (categorical background tokens, on-brand hues).const AURORA_BY_THEME: Record<string, HeroAuroraPalette> = {@@ -358,6 +360,45 @@ const DEFAULT_AURORA: HeroAuroraPalette = {right: 'var(--color-background-pink)',};+// The custom (web) font families each reel theme paints with — body, heading,+// and the marketing-scale display family. Listed here so the hero can warm them+// before the first auto-advance (the @font-face rules ship in the docsite's+// Google Fonts <link>, but the browser only fetches a family's woff2 once a+// glyph using it first paints — i.e. when the reel swaps to that slide, which+// is the visible FOUT first-time visitors hit). System/fallback stacks+// (-apple-system, Georgia, …) are intentionally omitted: they need no fetch.+//+// Keep in sync with the typography.{body,heading} families + display overrides+// in each theme package (packages/themes/<name>/src/<name>Theme.ts).+const REEL_FONT_FAMILIES: ReadonlyArray<string> = [+ // Astryx (docsite brand)+ 'Figtree',+ // Matcha (DM Sans body + Playwrite US Trad heading)+ 'DM Sans',+ 'Playwrite US Trad',+ // Butter (Outfit body/heading + Sarina display)+ 'Outfit',+ 'Sarina',+ // Gothic (Fustat body/heading + Manufacturing Consent display)+ 'Fustat',+ 'Manufacturing Consent',+ // Y2K (Poppins body/heading + Crimson Text display)+ 'Poppins',+ 'Crimson Text',+];++/**+ * `document.fonts.load()` specifiers for the reel's custom families. A short+ * representative string is enough to pull the right woff2 — the API loads the+ * whole face that would render those glyphs. We warm a normal and a bold-ish+ * weight since the cards mix body and heading weights.+ */+export const REEL_FONT_SPECIFIERS: ReadonlyArray<string> =+ REEL_FONT_FAMILIES.flatMap(family => [+ `400 1rem "${family}"`,+ `600 1rem "${family}"`,+ ]);+// Ordered slides from REEL_THEMES; unresolved (uninstalled) themes are skipped.export const HERO_THEME_SLIDES: ReadonlyArray<HeroThemeSlide> = REEL_THEMES.map(name => {@@ -376,3 +417,21 @@ export const HERO_THEME_SLIDES: ReadonlyArray<HeroThemeSlide> = REEL_THEMES.map(: null;},).filter((s): s is HeroThemeSlide => s !== null);++/**+ * Every product photo the reel cards reference, deduped and in slide order. The+ * cards use plain <img> (no next/image priority), so on a fresh visit a slide's+ * remote CDN photos aren't fetched until that slide renders — they pop in as+ * the reel advances. The hero warms this list on mount so the images are in the+ * browser cache before the first auto-advance. Scoped to just the reel's photos+ * (3 per slide) so it doesn't bloat the rest of the landing page's initial load.+ */+export const REEL_IMAGE_SRCS: ReadonlyArray<string> = Array.from(+ new Set(+ HERO_THEME_SLIDES.flatMap(slide => [+ slide.content.product.image,+ slide.content.feature.image,+ slide.content.mini.image,+ ]),+ ),+);