diff --git a/apps/docsite/src/__tests__/static-shell.test.ts b/apps/docsite/src/__tests__/static-shell.test.ts
new file mode 100644
index 00000000000..d6ae12c7fbd
--- /dev/null
+++ b/apps/docsite/src/__tests__/static-shell.test.ts
@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards the docsite's query-driven PPR boundaries and global footer.
+ * @input Reads the relevant docsite source files
+ * @output Invariants for narrow Suspense boundaries, named fallbacks, and
+ *   CSS-driven footer responsiveness
+ * @position Cross-cutting meta-test; no runtime behavior of its own
+ *
+ * The docsite runs with `cacheComponents: true` (Partial Prerendering).
+ * Request state such as `searchParams` is valid, but everything up to its
+ * nearest Suspense boundary becomes a PPR hole. The component detail page and
+ * theme explorer deliberately keep their existing deep-link behavior; these
+ * tests make sure their boundaries stay narrow and never regress to an empty
+ * fallback. The global footer must be CSS-responsive because a JavaScript
+ * media query cannot know the viewport during prerendering.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+
+const SRC_DIR = join(__dirname, '..');
+
+function source(path: string): string {
+  return readFileSync(join(SRC_DIR, path), 'utf8');
+}
+
+describe('docsite static shell', () => {
+  it('keeps the component heading outside the query-dependent boundary', () => {
+    const detail = source(
+      'components/component-detail/ComponentDetailClient.tsx',
+    );
+
+    expect(detail).toContain('const searchParams = useSearchParams()');
+    expect(detail).toContain(
+      'fallback={<ComponentDetailFallback hasShowcase={hasShowcase} />}',
+    );
+    expect(detail).not.toMatch(/<Suspense[^>]*fallback=\{null\}[\s\S]*?>/);
+    expect(detail.indexOf('<Text type="display-1">')).toBeLessThan(
+      detail.indexOf('<Suspense'),
+    );
+  });
+
+  it('gives the query-dependent theme explorer a named fallback', () => {
+    const themes = source('app/(site)/themes/page.tsx');
+
+    expect(themes).toContain('const params = await searchParams');
+    expect(themes).toContain('fallback={<ThemeExplorerFallback />}');
+    expect(themes).not.toMatch(/<Suspense[^>]*fallback=\{null\}[\s\S]*?>/);
+  });
+
+  it('the site footer does not branch on a media query', () => {
+    // SiteFooter renders on every route, docs and marketing alike, so it is
+    // part of the static shell at every width. Its responsive layout has to be
+    // CSS (see the MOBILE media query in SiteFooter.tsx), because a JS branch
+    // can only ever prerender one of the two arms.
+    const footer = source('components/SiteFooter.tsx');
+    expect(footer).not.toMatch(
+      /import[^;]*(?:useAppShellMobile|useMediaQuery)[^;]*from/,
+    );
+  });
+});
diff --git a/apps/docsite/src/app/(site)/themes/page.tsx b/apps/docsite/src/app/(site)/themes/page.tsx
index 7258644a006..5fa707c29a1 100644
--- a/apps/docsite/src/app/(site)/themes/page.tsx
+++ b/apps/docsite/src/app/(site)/themes/page.tsx
@@ -1,102 +1,175 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
  * Themes page — /themes
  *
  * Single canonical surface for browsing every Astryx theme. Renders the
  * full live ThemePackagePage (sidebar picker + themed preview
  * mockup + card showcase), seeded with the Neutral theme as the
  * default selection.
  *
  * The legacy per-theme route at /themes/<name> still resolves —
  * it now redirects here with ?theme=<slug>, which this page reads
  * to preselect the right theme in the sidebar so deep links from
  * docs, search, and shared URLs land on the requested theme rather
  * than the default seed.
  */
 
 import type {Metadata} from 'next';
+import * as stylex from '@stylexjs/stylex';
 import {Suspense} from 'react';
 import {notFound} from 'next/navigation';
 import {Section} from '@astryxdesign/core/Section';
+import {Skeleton} from '@astryxdesign/core/Skeleton';
 import {packages} from '../../../generated/packageRegistry';
 import {themeObjects} from '../../../generated/themeRegistry';
 import {ThemePackagePage} from '../../../components/ThemePackagePage';
 import {pageMetadata} from '../../../lib/pageMetadata';
 
 // Static canonical metadata for /themes. The page also accepts a `?theme=`
 // param to preselect the picker, but every variant is the same surface, so the
 // canonical stays the bare /themes path to avoid duplicate-URL dilution.
 export const metadata: Metadata = pageMetadata({
   title: 'Themes',
   description:
     'Browse and preview every Astryx theme and see how design tokens, type, and components restyle across the gallery.',
   path: '/themes',
 });
 
 // Default seed for the page — the picker opens with this theme
 // selected on first visit. Neutral is the most restrained / brand-
 // neutral theme in the gallery, so it sets a calm baseline before
 // users browse into the more expressive themes (Y2K, Butter, etc.).
 const DEFAULT_THEME_PACKAGE = '@astryxdesign/theme-neutral';
 
+const THEME_SIDEBAR_BREAKPOINT = '@media (max-width: 900px)';
+
+const styles = stylex.create({
+  loadingLayout: {
+    display: 'flex',
+    alignItems: 'flex-start',
+    gap: 'var(--spacing-6)',
+    minHeight: {default: 1000, [THEME_SIDEBAR_BREAKPOINT]: 760},
+    flexDirection: {
+      default: 'row',
+      [THEME_SIDEBAR_BREAKPOINT]: 'column',
+    },
+  },
+  loadingSidebar: {
+    flex: '0 0 auto',
+    width: 260,
+    display: {default: 'block', [THEME_SIDEBAR_BREAKPOINT]: 'none'},
+  },
+  loadingRight: {
+    flex: '1 1 0',
+    minWidth: 0,
+    width: '100%',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 'var(--spacing-6)',
+  },
+  loadingMobileContext: {
+    display: {default: 'none', [THEME_SIDEBAR_BREAKPOINT]: 'flex'},
+    flexDirection: 'column',
+    gap: 'var(--spacing-3)',
+  },
+  loadingMobileActions: {
+    display: 'flex',
+    gap: 'var(--spacing-2)',
+  },
+  loadingPreview: {
+    height: {default: 720, [THEME_SIDEBAR_BREAKPOINT]: 520},
+  },
+});
+
 function slugToPackageName(slug: string): string {
   return `@astryxdesign/theme-${slug}`;
 }
 
 export default function ThemesPage({
   searchParams,
 }: {
   searchParams: Promise<{theme?: string | string[]}>;
 }) {
   return (
     <Section maxWidth="lg" padding={6}>
-      <Suspense fallback={null}>
+      <Suspense fallback={<ThemeExplorerFallback />}>
         <SeededThemeExplorer searchParams={searchParams} />
       </Suspense>
     </Section>
   );
 }
 
 async function SeededThemeExplorer({
   searchParams,
 }: {
   searchParams: Promise<{theme?: string | string[]}>;
 }) {
   // ?theme=<slug> preselects the picker. Falls back to the Neutral
   // seed if the param is missing, malformed, or names a theme that
   // isn't in the registry (so a stale link doesn't 404 on us — the
   // user still lands on the explorer with a sensible default).
   const params = await searchParams;
   const rawSlug = params.theme;
   const slug = Array.isArray(rawSlug) ? rawSlug[0] : rawSlug;
 
   const requestedPkgName = slug ? slugToPackageName(slug) : null;
   const requestedPkg = requestedPkgName
     ? packages.find(p => p.name === requestedPkgName)
     : undefined;
   const requestedTheme = requestedPkgName
     ? themeObjects[requestedPkgName]
     : undefined;
 
   // Use the requested theme if it resolved to a real package + theme
   // object; otherwise fall back to the default seed so stale links
   // still land on a usable page rather than a 404.
   const seedPkg =
     requestedPkg && requestedTheme
       ? requestedPkg
       : packages.find(p => p.name === DEFAULT_THEME_PACKAGE);
   const seedTheme =
     requestedPkg && requestedTheme
       ? requestedTheme
       : themeObjects[DEFAULT_THEME_PACKAGE];
 
   if (!seedPkg || !seedTheme) {
     // Defensive: only fires if the @astryxdesign/theme-neutral package is
     // ever removed from the workspace, which would break the entire
     // themes section anyway.
     notFound();
   }
 
   return <ThemePackagePage packageName={seedPkg.name} theme={seedTheme} />;
 }
+
+/**
+ * The theme explorer depends on the request query, so it remains a PPR hole.
+ * This fallback mirrors its two-column geometry and keeps the footer below the
+ * viewport instead of collapsing the section to zero height while it streams.
+ */
+function ThemeExplorerFallback() {
+  return (
+    <div
+      role="status"
+      aria-label="Loading theme explorer"
+      {...stylex.props(styles.loadingLayout)}>
+      <aside {...stylex.props(styles.loadingSidebar)}>
+        <Skeleton width="100%" height={720} index={0} />
+      </aside>
+      <div {...stylex.props(styles.loadingRight)}>
+        <div {...stylex.props(styles.loadingMobileContext)}>
+          <Skeleton width={220} height={40} index={0} />
+          <Skeleton width="80%" height={18} index={1} />
+          <div {...stylex.props(styles.loadingMobileActions)}>
+            <Skeleton width={180} height={40} index={2} />
+            <Skeleton width={40} height={40} radius="rounded" index={3} />
+          </div>
+        </div>
+        <div {...stylex.props(styles.loadingPreview)}>
+          <Skeleton width="100%" height="100%" index={4} />
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/docsite/src/components/SiteFooter.tsx b/apps/docsite/src/components/SiteFooter.tsx
index 0948205c1a4..40aa6cd9fdf 100644
--- a/apps/docsite/src/components/SiteFooter.tsx
+++ b/apps/docsite/src/components/SiteFooter.tsx
@@ -1,251 +1,270 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 'use client';
 
 import * as stylex from '@stylexjs/stylex';
 import {Text} from '@astryxdesign/core/Text';
 import {Link} from '@astryxdesign/core/Link';
 import {Button} from '@astryxdesign/core/Button';
 import {HStack, VStack} from '@astryxdesign/core/Layout';
 import {Grid, GridSpan} from '@astryxdesign/core/Grid';
 import {Divider} from '@astryxdesign/core/Divider';
 import {Section} from '@astryxdesign/core/Section';
-import {useAppShellMobile} from '@astryxdesign/core/AppShell';
 import {DocsVersionFooterLink} from './DocsVersionFooterLink';
 import {
   GITHUB_REPO,
   DISCORD_URL,
   FACEBOOK_URL,
   INSTAGRAM_URL,
   THREADS_URL,
   X_URL,
 } from '../constants';
 import {
   AstryxLogo,
   GitHubLogo,
   ThreadsLogo,
   XLogo,
   InstagramLogo,
   FacebookLogo,
   MetaOpenSourceLogo,
   DiscordLogo,
 } from './logos';
 
+const MOBILE = '@media (max-width: 768px)';
+
 const styles = stylex.create({
   siteFooter: {
     // Match the section rhythm above (responsive); fall back off the home page.
     paddingTop:
       'var(--astryx-marketing-section-gap, calc(var(--spacing-12) * 2))',
   },
   astryxLogo: {
     height: 18,
     width: 'auto',
     display: 'block',
     color: 'var(--color-icon-secondary)',
   },
   socialIcon: {
     width: 16,
     height: 16,
     display: 'block',
   },
   metaOpenSourceLogo: {
     height: 14,
     width: 'auto',
     display: 'block',
     color: 'var(--color-icon-secondary)',
   },
+  // Keeps the wrapped link list to a readable measure once it stacks; on
+  // desktop the links sit in their own grid column and must not be clamped.
   mobileFooterLinks: {
-    maxWidth: 320,
+    maxWidth: {default: 'none', [MOBILE]: 320},
+  },
+  // The footer is one markup at every width — the layout swaps in CSS, not in
+  // JS. It used to branch on `useAppShellMobile().isMobile`, which is a
+  // `useMediaQuery` whose server snapshot is always `false`: the prerendered
+  // HTML therefore carried the DESKTOP grid at every width, so on a phone the
+  // wordmark, the link list and the social buttons all painted on top of each
+  // other in ~80px columns until hydration replaced them. A media query has
+  // the right answer on the very first paint.
+  //
+  // Every override below RESTATES its desktop value in `default` rather than
+  // leaving it `null`. `xstyle` merges after the component's own styles and a
+  // `null` there *unsets* the property, so `{default: null, …}` would strip
+  // VStack's gap and Grid's `display: grid` at desktop width.
+  stack: {
+    // VStack gap={4}
+    gap: {default: 'var(--spacing-4)', [MOBILE]: 'var(--spacing-6)'},
+  },
+  // `grid-template-columns` (from Grid) and `grid-column` (from GridSpan) are
+  // inert under `display: flex`, and `flex-direction` is inert under
+  // `display: grid`, so switching `display` alone turns the row into a
+  // centered column.
+  row: {
+    display: {default: 'grid', [MOBILE]: 'flex'},
+    flexDirection: 'column',
+    alignItems: 'center',
+  },
+  navRow: {
+    gap: {default: 'normal', [MOBILE]: 'var(--spacing-6)'},
+  },
+  legalRow: {
+    gap: {default: 'normal', [MOBILE]: 'var(--spacing-2)'},
+  },
+  navLinks: {
+    // HStack gap={4}
+    gap: {default: 'var(--spacing-4)', [MOBILE]: 'var(--spacing-3)'},
+  },
+  copyright: {
+    // Text justify="end"
+    textAlign: {default: 'end', [MOBILE]: 'center'},
+  },
+  social: {
+    // Must stay `nowrap` on desktop: the social buttons sit in a `1fr` grid
+    // track, and a track only grows past its share to fit its MIN-CONTENT — a
+    // wrappable row has a one-icon min-content, so the track would stay at
+    // 1/5 of the row and the icons would wrap onto a second line.
+    flexWrap: {default: 'nowrap', [MOBILE]: 'wrap'},
   },
 });
 
 const FOOTER_LINKS: ReadonlyArray<{
   label: string;
   href: string;
 }> = [
   {label: 'Docs', href: '/docs/getting-started'},
   {label: 'Components', href: '/components'},
   {label: 'Templates', href: '/templates'},
   {label: 'Themes', href: '/themes'},
   {label: 'Playground', href: '/playground'},
   {label: 'Blog', href: '/blog'},
   {label: 'Community', href: '/community'},
   {label: 'Changelog', href: '/changelog'},
 ];
 
 const SOCIAL_LINKS: ReadonlyArray<{
   label: string;
   href: string;
   Icon: (props: React.SVGProps<SVGSVGElement>) => React.ReactElement;
 }> = [
   {label: 'GitHub', href: GITHUB_REPO, Icon: GitHubLogo},
   {label: 'Discord', href: DISCORD_URL, Icon: DiscordLogo},
   {label: 'Facebook', href: FACEBOOK_URL, Icon: FacebookLogo},
   {label: 'Instagram', href: INSTAGRAM_URL, Icon: InstagramLogo},
   {label: 'Threads', href: THREADS_URL, Icon: ThreadsLogo},
   {label: 'X', href: X_URL, Icon: XLogo},
 ];
 
 const LEGAL_LINKS: ReadonlyArray<{label: string; href: string}> = [
   {label: 'Terms of use', href: 'https://opensource.fb.com/legal/terms'},
   {label: 'Privacy policy', href: 'https://opensource.fb.com/legal/privacy'},
 ];
 
 function NavLinks() {
   return (
     <>
       {FOOTER_LINKS.map(item => (
         <Link
           key={item.label}
           href={item.href}
           type="supporting"
           color="secondary"
           isStandalone>
           {item.label}
         </Link>
       ))}
       <DocsVersionFooterLink />
     </>
   );
 }
 
 function SocialButtons() {
   return (
     <>
       {SOCIAL_LINKS.map(social => (
         <Button
           key={social.label}
           label={social.label}
           tooltip={social.label}
           variant="secondary"
           isIconOnly
           icon={
             <social.Icon
               aria-hidden="true"
               {...stylex.props(styles.socialIcon)}
             />
           }
           href={social.href}
         />
       ))}
     </>
   );
 }
 
 function LegalLinks() {
   return (
     <>
       {LEGAL_LINKS.map(link => (
         <Link
           key={link.label}
           href={link.href}
           type="supporting"
           color="secondary"
           isStandalone
           target="_blank">
           {link.label}
         </Link>
       ))}
     </>
   );
 }
 
 export function SiteFooter({year}: {year: number}) {
-  const {isMobile} = useAppShellMobile();
-
   // The regex compliance check requires the year to immediately follow the
   // copyright mark — `©{year}`, no separating space. See PR description.
   const copyright = `\u00A9${year} Meta Platforms, Inc.`;
 
   const astryxLogo = (
     <Link href="/" label="Astryx">
       <AstryxLogo aria-hidden="true" {...stylex.props(styles.astryxLogo)} />
     </Link>
   );
 
   const metaOpenSourceLink = (
     <Link
       href="https://opensource.fb.com"
       label="Meta Open Source"
       target="_blank">
       <MetaOpenSourceLogo
         aria-hidden="true"
         {...stylex.props(styles.metaOpenSourceLogo)}
       />
     </Link>
   );
 
-  if (isMobile) {
-    // On narrow viewports the horizontal rows can't fit side by side, so we
-    // stack the three regions vertically and let the link lists wrap.
-    return (
-      <Section role="contentinfo" padding={6} xstyle={styles.siteFooter}>
-        <VStack gap={6}>
-          <VStack gap={6} hAlign="center">
-            {astryxLogo}
-            <HStack
-              gap={3}
-              wrap="wrap"
-              hAlign="center"
-              align="center"
-              xstyle={styles.mobileFooterLinks}>
-              <NavLinks />
-            </HStack>
-            <HStack gap={2} wrap="wrap" align="center">
-              <SocialButtons />
-            </HStack>
-          </VStack>
-
-          <Divider />
-
-          <VStack gap={2} hAlign="center">
-            {metaOpenSourceLink}
-            <HStack gap={4} hAlign="start" xstyle={styles.mobileFooterLinks}>
-              <LegalLinks />
-            </HStack>
-            <Text type="supporting" color="secondary">
-              {copyright}
-            </Text>
-          </VStack>
-        </VStack>
-      </Section>
-    );
-  }
-
   return (
     <Section role="contentinfo" padding={6} xstyle={styles.siteFooter}>
-      <VStack gap={4}>
-        <Grid columns={5} align="center">
+      <VStack gap={4} xstyle={styles.stack}>
+        <Grid columns={5} align="center" xstyle={[styles.row, styles.navRow]}>
           {astryxLogo}
           <GridSpan columns={3}>
-            <HStack gap={4} wrap="wrap" align="center" hAlign="center">
+            <HStack
+              gap={4}
+              wrap="wrap"
+              align="center"
+              hAlign="center"
+              xstyle={[styles.navLinks, styles.mobileFooterLinks]}>
               <NavLinks />
             </HStack>
           </GridSpan>
-          <HStack gap={2} align="center" justify="end">
+          <HStack gap={2} align="center" justify="end" xstyle={styles.social}>
             <SocialButtons />
           </HStack>
         </Grid>
 
         <Divider />
 
-        <Grid columns={4} align="center">
+        <Grid columns={4} align="center" xstyle={[styles.row, styles.legalRow]}>
           {metaOpenSourceLink}
           <GridSpan columns={2}>
             <HStack
               gap={4}
               wrap="wrap"
               align="center"
               hAlign="center"
               width="100%">
               <LegalLinks />
             </HStack>
           </GridSpan>
-          <Text type="supporting" color="secondary" justify="end">
+          <Text
+            type="supporting"
+            color="secondary"
+            justify="end"
+            xstyle={styles.copyright}>
             {copyright}
           </Text>
         </Grid>
       </VStack>
     </Section>
   );
 }
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index 300d283bbce..2df937b756e 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -1,301 +1,364 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 'use client';
 
 import * as stylex from '@stylexjs/stylex';
 import {Suspense} from 'react';
 import {useSearchParams, useRouter, usePathname} from 'next/navigation';
 import {Heading, Text} from '@astryxdesign/core/Text';
 import {VStack} from '@astryxdesign/core/Layout';
 import {Section} from '@astryxdesign/core/Section';
 import {Card} from '@astryxdesign/core/Card';
+import {Skeleton} from '@astryxdesign/core/Skeleton';
 import {Divider} from '@astryxdesign/core';
 import {typeScaleVars} from '@astryxdesign/core/theme/tokens.stylex';
 import {CodeExampleBlock} from '../CodeExampleBlock';
 import {TabList, Tab} from '@astryxdesign/core/TabList';
 import {ShowcasePreview} from './ShowcasePreview';
 import {ComponentPreviewTheme} from './ComponentPreviewTheme';
 import {Anatomy} from './Anatomy';
 import {BestPractices} from './BestPractices';
 import {Theming} from './Theming';
 import {HookSignature} from './HookSignature';
 import {ExampleBlock} from './ExampleBlock';
 import {MarkdownText} from '../MarkdownText';
 import {
   InteractivePreviewStage,
   useInteractiveState,
 } from './InteractivePreview';
 import {hasInteractivePlayground} from './interactiveState';
 import {hasThemingContent} from './themingHelpers';
 import {CURRENT_TARGET} from '../../lib/docsVersions';
 import {PlaygroundPropsTable} from './PlaygroundPropsTable';
 import {PropsTable} from './PropsTable';
 import type {ComponentEntry} from '../../generated/componentRegistry';
 import type {BlockEntry} from '../../generated/blockRegistry';
 import {showcaseRegistry} from '../../generated/showcaseRegistry';
 import {exampleRegistry} from '../../generated/exampleRegistry';
 import {trackNavigate} from '../../lib/analytics';
 
 const styles = stylex.create({
   section: {
     marginInline: 'auto',
   },
   // Match the docs article body treatment (16px / 1.75) from DocPageLayout,
   // scoped to the Overview prose only — the dense Properties props table keeps
   // its compact body size. Live previews in the Overview are isolated inside
   // ComponentPreviewTheme (a nested Theme that re-declares the type-scale
   // tokens), so this override never leaks into them. The Usage/Examples
   // descriptions (large) use different tokens and are unaffected.
   overviewProse: {
     [typeScaleVars['--text-body-size']]: '1rem', // 16px
     [typeScaleVars['--text-body-leading']]: '1.75', // 28px line box
   },
   previewStage: {
     position: 'sticky',
     top: 44,
     zIndex: 10,
     backgroundColor: 'var(--color-background-page)',
     backdropFilter: 'blur(16px)',
     maxHeight: {default: 400, '@media (max-width: 768px)': 250},
     overflow: 'auto',
     borderWidth: 'var(--border-width, 1px)',
     borderStyle: 'solid',
     borderColor: 'var(--color-border-emphasized)',
     borderRadius: 'var(--radius-container)',
   },
+  // Reserve enough of the article to keep the footer below the viewport while
+  // Next streams the query-dependent tab panel. The named skeleton shapes
+  // mirror the tab row, live preview, heading and prose rather than presenting
+  // the empty Suspense hole that previously caused the 0.23 CLS.
+  loadingContent: {
+    minHeight: {default: 900, '@media (max-width: 768px)': 680},
+  },
+  loadingPreview: {
+    height: {default: 320, '@media (max-width: 768px)': 220},
+  },
 });
 
 interface ComponentDetailClientProps {
   comp: ComponentEntry;
   pkg: string | undefined;
   pkgVersion: string | undefined;
   showcase: BlockEntry | undefined;
 }
 
 function OverviewContent({
   comp,
   pkg,
   showcase: _showcase,
   hasShowcase,
 }: ComponentDetailClientProps & {hasShowcase: boolean}) {
   const isHook = comp.params != null;
   const importFrom = comp.importPath ?? `${pkg}/${comp.directory}`;
   const importPath = `import {${comp.moduleName}} from '${importFrom}'`;
 
   return (
     <VStack gap={8} xstyle={styles.overviewProse}>
       {hasShowcase && (
         <ComponentPreviewTheme>
           <Card variant="muted" padding={0}>
             <ShowcasePreview name={comp.name} />
           </Card>
         </ComponentPreviewTheme>
       )}
 
       {comp.usage && (
         <VStack gap={4}>
           <Heading level={2} type="display-3">
             Usage
           </Heading>
           <MarkdownText type="large" weight="normal">
             {comp.usage.description}
           </MarkdownText>
 
           <CodeExampleBlock
             code={importPath}
             language="ts"
             width="100%"
             hasCopyButton
           />
 
           {/* Anatomy before best practices, matching the CLI's section order
               in clients/cli/lib/component-format.mjs. */}
           {comp.usage.anatomy && comp.usage.anatomy.length > 0 && (
             <Anatomy elements={comp.usage.anatomy} />
           )}
 
           {comp.usage.bestPractices && comp.usage.bestPractices.length > 0 && (
             <BestPractices practices={comp.usage.bestPractices} />
           )}
         </VStack>
       )}
 
       {isHook && comp.params && comp.returns && (
         <HookSignature
           params={comp.params}
           returns={comp.returns}
           typeDefs={comp.typeDefs}
         />
       )}
 
       {!isHook && !hasInteractivePlayground(comp) && comp.props.length > 0 && (
         <PropsTable props={comp.props} heading="Props" />
       )}
 
       {(exampleRegistry[comp.name] || []).length > 0 && (
         <>
           <VStack gap={4}>
             <Heading level={2} type="display-3">
               Examples
             </Heading>
             <Text type="large" weight="normal">
               Common configurations, variations, and states.
             </Text>
           </VStack>
           <VStack gap={10}>
             {(exampleRegistry[comp.name] || []).map((entry, i) => (
               <ExampleBlock key={i} entry={entry} componentName={comp.name} />
             ))}
           </VStack>
         </>
       )}
     </VStack>
   );
 }
 
-function ComponentDetailInner({
+interface ComponentDetailTabsProps extends ComponentDetailClientProps {
+  hasPlayground: boolean;
+  hasThemingTab: boolean;
+  hasShowcase: boolean;
+}
+
+/**
+ * Query-dependent portion of the page. Keeping this below the nearest
+ * Suspense boundary lets the page heading and every component with no tabs
+ * remain in the prerendered shell while preserving `useSearchParams()` as the
+ * source of truth for deep links and soft navigation.
+ */
+function ComponentDetailTabs({
   comp,
   pkg,
   pkgVersion,
   showcase,
-}: ComponentDetailClientProps) {
+  hasPlayground,
+  hasThemingTab,
+  hasShowcase,
+}: ComponentDetailTabsProps) {
   const searchParams = useSearchParams();
   const router = useRouter();
   const pathname = usePathname();
 
-  const hasShowcase = comp.name in showcaseRegistry;
-  const hasPlayground = hasInteractivePlayground(comp);
-  // Theming lives in its own tab, shown only on the canary line (where the
-  // experimental theming API is documented) and only when the component has
-  // themeable targets or CSS variables — never an empty tab.
-  const hasThemingTab =
-    CURRENT_TARGET === 'canary' && hasThemingContent(comp.theming);
-  const hasTabs = hasPlayground || hasThemingTab;
-
   const requestedTab = searchParams.get('tab') ?? 'overview';
   // Clamp to a tab that actually exists for this component so a stale or
   // hand-edited `?tab=` never lands on a blank panel.
   const tab =
     (requestedTab === 'properties' && hasPlayground) ||
     (requestedTab === 'theming' && hasThemingTab)
       ? requestedTab
       : 'overview';
   const setTab = (value: string) => {
     trackNavigate({
       page: 'components',
       target: 'tab',
       tab: value,
       item: comp.name,
     });
     const params = new URLSearchParams(searchParams.toString());
     if (value === 'overview') {
       params.delete('tab');
     } else {
       params.set('tab', value);
     }
     const qs = params.toString();
     router.replace(`${pathname}${qs ? `?${qs}` : ''}`, {scroll: false});
   };
 
   const {knobs, state, setProp, missingRequiredProps} = useInteractiveState(
     comp.name,
     comp.props,
     comp.playground,
   );
 
+  return (
+    <>
+      <TabList value={tab} onChange={setTab} hasDivider>
+        <Tab value="overview" label="Overview" />
+        {hasPlayground && <Tab value="properties" label="Properties" />}
+        {hasThemingTab && <Tab value="theming" label="Theming" />}
+      </TabList>
+
+      {tab === 'overview' && (
+        <OverviewContent
+          comp={comp}
+          pkg={pkg}
+          pkgVersion={pkgVersion}
+          showcase={showcase}
+          hasShowcase={hasShowcase}
+        />
+      )}
+
+      {tab === 'properties' && hasPlayground && (
+        <VStack gap={4}>
+          <div {...stylex.props(styles.previewStage)}>
+            <InteractivePreviewStage
+              name={comp.name}
+              state={state}
+              knobs={knobs}
+              playground={comp.playground}
+              missingRequiredProps={missingRequiredProps}
+              onPropChange={setProp}
+              embedded
+              canControlOpenState={
+                comp.props.some(prop => prop.name === 'isOpen') &&
+                comp.props.some(prop => prop.name === 'onOpenChange')
+              }
+            />
+          </div>
+
+          {comp.props.length > 0 && (
+            <Section>
+              <VStack gap={3}>
+                <Heading level={3}>Props</Heading>
+                <PlaygroundPropsTable
+                  props={comp.props}
+                  typeDefs={comp.typeDefs}
+                  knobs={knobs}
+                  state={state}
+                  onPropChange={setProp}
+                />
+              </VStack>
+            </Section>
+          )}
+        </VStack>
+      )}
+
+      {tab === 'theming' && comp.theming && (
+        <Theming theming={comp.theming} props={comp.props} />
+      )}
+    </>
+  );
+}
+
+function ComponentDetailFallback({hasShowcase}: {hasShowcase: boolean}) {
+  return (
+    <div
+      role="status"
+      aria-label="Loading component documentation"
+      {...stylex.props(styles.loadingContent)}>
+      <VStack gap={8}>
+        <Skeleton width="100%" height={40} radius={0} index={0} />
+        {hasShowcase && (
+          <div {...stylex.props(styles.loadingPreview)}>
+            <Skeleton width="100%" height="100%" index={1} />
+          </div>
+        )}
+        <VStack gap={3}>
+          <Skeleton width={180} height={32} index={2} />
+          <Skeleton width="92%" height={18} index={3} />
+          <Skeleton width="68%" height={18} index={4} />
+          <Skeleton width="100%" height={72} index={5} />
+        </VStack>
+      </VStack>
+    </div>
+  );
+}
+
+export function ComponentDetailClient({
+  comp,
+  pkg,
+  pkgVersion,
+  showcase,
+}: ComponentDetailClientProps) {
+  const hasShowcase = comp.name in showcaseRegistry;
+  const hasPlayground = hasInteractivePlayground(comp);
+  const hasThemingTab =
+    CURRENT_TARGET === 'canary' && hasThemingContent(comp.theming);
+  const hasTabs = hasPlayground || hasThemingTab;
+
   return (
     <Section
       maxWidth={960}
       padding={6}
       variant="transparent"
       xstyle={styles.section}>
       <VStack gap={4}>
+        {/* This heading is independent of the URL and belongs in the static
+            shell. Only the tab row and panel below need request state. */}
         <VStack gap={2}>
           <Text type="display-1">{comp.displayName}</Text>
           <Text type="supporting" color="secondary">
             {pkg}
             {pkgVersion ? ` v${pkgVersion}` : ''} · {comp.moduleName}
           </Text>
         </VStack>
 
         {hasTabs ? (
-          <>
-            <TabList value={tab} onChange={setTab} hasDivider>
-              <Tab value="overview" label="Overview" />
-              {hasPlayground && <Tab value="properties" label="Properties" />}
-              {hasThemingTab && <Tab value="theming" label="Theming" />}
-            </TabList>
-
-            {tab === 'overview' && (
-              <OverviewContent
-                comp={comp}
-                pkg={pkg}
-                pkgVersion={pkgVersion}
-                showcase={showcase}
-                hasShowcase={hasShowcase}
-              />
-            )}
-
-            {tab === 'properties' && hasPlayground && (
-              <VStack gap={4}>
-                <div {...stylex.props(styles.previewStage)}>
-                  <InteractivePreviewStage
-                    name={comp.name}
-                    state={state}
-                    knobs={knobs}
-                    playground={comp.playground}
-                    missingRequiredProps={missingRequiredProps}
-                    onPropChange={setProp}
-                    embedded
-                    canControlOpenState={
-                      comp.props.some(prop => prop.name === 'isOpen') &&
-                      comp.props.some(prop => prop.name === 'onOpenChange')
-                    }
-                  />
-                </div>
-
-                {comp.props.length > 0 && (
-                  <Section>
-                    <VStack gap={3}>
-                      <Heading level={3}>Props</Heading>
-                      <PlaygroundPropsTable
-                        props={comp.props}
-                        typeDefs={comp.typeDefs}
-                        knobs={knobs}
-                        state={state}
-                        onPropChange={setProp}
-                      />
-                    </VStack>
-                  </Section>
-                )}
-              </VStack>
-            )}
-
-            {tab === 'theming' && comp.theming && (
-              <Theming theming={comp.theming} props={comp.props} />
-            )}
-          </>
+          <Suspense
+            fallback={<ComponentDetailFallback hasShowcase={hasShowcase} />}>
+            <ComponentDetailTabs
+              comp={comp}
+              pkg={pkg}
+              pkgVersion={pkgVersion}
+              showcase={showcase}
+              hasPlayground={hasPlayground}
+              hasThemingTab={hasThemingTab}
+              hasShowcase={hasShowcase}
+            />
+          </Suspense>
         ) : (
           <>
             <Divider />
             <OverviewContent
               comp={comp}
               pkg={pkg}
               pkgVersion={pkgVersion}
               showcase={showcase}
               hasShowcase={hasShowcase}
             />
           </>
         )}
       </VStack>
     </Section>
   );
 }
-
-export function ComponentDetailClient(props: ComponentDetailClientProps) {
-  return (
-    <Suspense>
-      <ComponentDetailInner {...props} />
-    </Suspense>
-  );
-}