Skip to content

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.tsx
index 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.ts
index 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,
+ ]),
+ ),
+);