From 61d345d80e39106f7bc4bc2c89a7059d8846834c Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Mon, 9 Nov 2026 20:53:43 +0900
Subject: [PATCH 1/7] feat(ds/skeleton): add a non-inverting 'Skeleton'
 primitive

---
 src/components/ds/ds-nav.ts    |  10 +++
 src/components/ds/ui/index.tsx |  53 +++++++++++++
 src/routeTree.gen.ts           |  25 +++++-
 src/routes/ds.index.tsx        |   2 +
 src/routes/ds.skeleton.tsx     | 138 +++++++++++++++++++++++++++++++++
 5 files changed, 224 insertions(+), 4 deletions(-)
 create mode 100644 src/routes/ds.skeleton.tsx

diff --git a/src/components/ds/ds-nav.ts b/src/components/ds/ds-nav.ts
index 027387d0b..d0e91ccfc 100644
--- a/src/components/ds/ds-nav.ts
+++ b/src/components/ds/ds-nav.ts
@@ -226,6 +226,16 @@ export const dsNav: Array<DsNavSection> = [
         to: '/ds/partner-rail',
         sections: ['Rail', 'Tiers', 'Per-logo scale'],
       },
+      {
+        label: 'Skeleton',
+        to: '/ds/skeleton',
+        sections: [
+          'Skeleton',
+          'On any surface',
+          'Grouping and accessibility',
+          'Match the real layout',
+        ],
+      },
       {
         label: 'Spinner',
         to: '/ds/spinner',
diff --git a/src/components/ds/ui/index.tsx b/src/components/ds/ui/index.tsx
index 7557cc96c..074851a67 100644
--- a/src/components/ds/ui/index.tsx
+++ b/src/components/ds/ui/index.tsx
@@ -628,6 +628,59 @@ export function Spinner({ className }: { className?: string }) {
   )
 }
 
+/* --------------------------------------------------------------- Skeleton -- */
+
+/**
+ * Placeholder block shown while content loads.
+ *
+ * The tint is an alpha overlay rather than an opaque surface token, so it keeps
+ * the same contrast on the page background and on an elevated card — an opaque
+ * `background-subtle` reads lighter than the page in dark mode but darker than
+ * a card, inverting as it moves between surfaces.
+ *
+ * The pulse is wrapped in `motion-safe:` so it holds still under
+ * `prefers-reduced-motion`.
+ */
+export function Skeleton({
+  className,
+  ...rest
+}: React.ComponentPropsWithoutRef<'div'>) {
+  return (
+    <div
+      aria-hidden="true"
+      className={twMerge(
+        'motion-safe:animate-pulse rounded bg-text-primary/10',
+        className,
+      )}
+      {...rest}
+    />
+  )
+}
+
+/**
+ * Wrapper that announces a loading region to assistive tech. Wrap a group of
+ * `Skeleton` blocks in this so screen readers hear one message instead of
+ * nothing — the blocks themselves are `aria-hidden`.
+ */
+export function SkeletonGroup({
+  label = 'Loading',
+  className,
+  children,
+  ...rest
+}: React.ComponentPropsWithoutRef<'div'> & { label?: string }) {
+  return (
+    <div
+      role="status"
+      aria-busy="true"
+      aria-label={label}
+      className={className}
+      {...rest}
+    >
+      {children}
+    </div>
+  )
+}
+
 /* ----------------------------------------------------------------- Avatar -- */
 
 type AvatarSize = '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
diff --git a/src/routeTree.gen.ts b/src/routeTree.gen.ts
index c09771b52..5c7fd6b95 100644
--- a/src/routeTree.gen.ts
+++ b/src/routeTree.gen.ts
@@ -105,6 +105,7 @@ import { Route as DsPanelRouteImport } from './routes/ds.panel'
 import { Route as DsPartnerRailRouteImport } from './routes/ds.partner-rail'
 import { Route as DsSemanticRouteImport } from './routes/ds.semantic'
 import { Route as DsShadowsRouteImport } from './routes/ds.shadows'
+import { Route as DsSkeletonRouteImport } from './routes/ds.skeleton'
 import { Route as DsSpinnerRouteImport } from './routes/ds.spinner'
 import { Route as DsStatsRouteImport } from './routes/ds.stats'
 import { Route as DsTabsRouteImport } from './routes/ds.tabs'
@@ -814,6 +815,11 @@ const DsShadowsRoute = DsShadowsRouteImport.update({
   path: '/shadows',
   getParentRoute: () => DsRoute,
 } as any)
+const DsSkeletonRoute = DsSkeletonRouteImport.update({
+  id: '/skeleton',
+  path: '/skeleton',
+  getParentRoute: () => DsRoute,
+} as any)
 const DsSpinnerRoute = DsSpinnerRouteImport.update({
   id: '/spinner',
   path: '/spinner',
@@ -2139,6 +2145,7 @@ export interface FileRoutesByFullPath {
   '/ds/partner-rail': typeof DsPartnerRailRoute
   '/ds/semantic': typeof DsSemanticRoute
   '/ds/shadows': typeof DsShadowsRoute
+  '/ds/skeleton': typeof DsSkeletonRoute
   '/ds/spinner': typeof DsSpinnerRoute
   '/ds/stats': typeof DsStatsRoute
   '/ds/tabs': typeof DsTabsRoute
@@ -2453,6 +2460,7 @@ export interface FileRoutesByTo {
   '/ds/partner-rail': typeof DsPartnerRailRoute
   '/ds/semantic': typeof DsSemanticRoute
   '/ds/shadows': typeof DsShadowsRoute
+  '/ds/skeleton': typeof DsSkeletonRoute
   '/ds/spinner': typeof DsSpinnerRoute
   '/ds/stats': typeof DsStatsRoute
   '/ds/tabs': typeof DsTabsRoute
@@ -2774,6 +2782,7 @@ export interface FileRoutesById {
   '/ds/partner-rail': typeof DsPartnerRailRoute
   '/ds/semantic': typeof DsSemanticRoute
   '/ds/shadows': typeof DsShadowsRoute
+  '/ds/skeleton': typeof DsSkeletonRoute
   '/ds/spinner': typeof DsSpinnerRoute
   '/ds/stats': typeof DsStatsRoute
   '/ds/tabs': typeof DsTabsRoute
@@ -3099,6 +3108,7 @@ export interface FileRouteTypes {
     | '/ds/partner-rail'
     | '/ds/semantic'
     | '/ds/shadows'
+    | '/ds/skeleton'
     | '/ds/spinner'
     | '/ds/stats'
     | '/ds/tabs'
@@ -3413,6 +3423,7 @@ export interface FileRouteTypes {
     | '/ds/partner-rail'
     | '/ds/semantic'
     | '/ds/shadows'
+    | '/ds/skeleton'
     | '/ds/spinner'
     | '/ds/stats'
     | '/ds/tabs'
@@ -3733,6 +3744,7 @@ export interface FileRouteTypes {
     | '/ds/partner-rail'
     | '/ds/semantic'
     | '/ds/shadows'
+    | '/ds/skeleton'
     | '/ds/spinner'
     | '/ds/stats'
     | '/ds/tabs'
@@ -4796,6 +4808,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof DsShadowsRouteImport
       parentRoute: typeof DsRoute
     }
+    '/ds/skeleton': {
+      id: '/ds/skeleton'
+      path: '/skeleton'
+      fullPath: '/ds/skeleton'
+      preLoaderRoute: typeof DsSkeletonRouteImport
+      parentRoute: typeof DsRoute
+    }
     '/ds/spinner': {
       id: '/ds/spinner'
       path: '/spinner'
@@ -6716,6 +6735,7 @@ interface DsRouteChildren {
   DsPartnerRailRoute: typeof DsPartnerRailRoute
   DsSemanticRoute: typeof DsSemanticRoute
   DsShadowsRoute: typeof DsShadowsRoute
+  DsSkeletonRoute: typeof DsSkeletonRoute
   DsSpinnerRoute: typeof DsSpinnerRoute
   DsStatsRoute: typeof DsStatsRoute
   DsTabsRoute: typeof DsTabsRoute
@@ -6748,6 +6768,7 @@ const DsRouteChildren: DsRouteChildren = {
   DsPartnerRailRoute: DsPartnerRailRoute,
   DsSemanticRoute: DsSemanticRoute,
   DsShadowsRoute: DsShadowsRoute,
+  DsSkeletonRoute: DsSkeletonRoute,
   DsSpinnerRoute: DsSpinnerRoute,
   DsStatsRoute: DsStatsRoute,
   DsTabsRoute: DsTabsRoute,
@@ -7396,15 +7417,11 @@ export const routeTree = rootRouteImport
   ._addFileTypes<FileRouteTypes>()
 
 import type { getRouter } from './router.tsx'
-
 import type { startInstance } from './start.ts'
-
 declare module '@tanstack/react-start' {
   interface Register {
     ssr: true
-
     router: Awaited<ReturnType<typeof getRouter>>
-
     config: Awaited<ReturnType<typeof startInstance.getOptions>>
   }
 }
diff --git a/src/routes/ds.index.tsx b/src/routes/ds.index.tsx
index 7891a6a9a..03579b5d5 100644
--- a/src/routes/ds.index.tsx
+++ b/src/routes/ds.index.tsx
@@ -8,6 +8,7 @@ import {
   DropIcon,
   StackIcon,
   CircleNotchIcon,
+  PlaceholderIcon,
   MapPinLineIcon,
   CursorClickIcon,
   PaletteIcon,
@@ -36,6 +37,7 @@ const SECTION_ICONS: Record<string, Icon> = {
   '/ds/inputs': TextTIcon,
   '/ds/dropdown': CaretDownIcon,
   '/ds/avatar': UserCircleIcon,
+  '/ds/skeleton': PlaceholderIcon,
   '/ds/spinner': CircleNotchIcon,
   '/ds/panel': CaretUpDownIcon,
   '/ds/breadcrumbs': MapPinLineIcon,
diff --git a/src/routes/ds.skeleton.tsx b/src/routes/ds.skeleton.tsx
new file mode 100644
index 000000000..4c1abc5af
--- /dev/null
+++ b/src/routes/ds.skeleton.tsx
@@ -0,0 +1,138 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { seo } from '~/utils/seo'
+import { Card, Skeleton, SkeletonGroup } from '~/components/ds/ui'
+import { ComponentPreview, DsPage, DsSection } from '~/components/ds/DsKit'
+
+export const Route = createFileRoute('/ds/skeleton')({
+  component: SkeletonPage,
+  head: () => ({
+    meta: seo({
+      title: 'Skeletons | TanStack Design System',
+      description:
+        'Skeleton placeholder blocks, surface behavior, grouping, and accessibility.',
+    }),
+  }),
+})
+
+function SkeletonPage() {
+  return (
+    <DsPage
+      title="Skeletons"
+      description="Placeholder blocks shown while content loads. Mirror the shape of what is coming so the layout does not shift when the real content arrives."
+    >
+      <DsSection
+        id="shapes"
+        title="Skeleton"
+        description={
+          <>
+            Size it with w-/h- utilities and change the corner with rounded-*.
+            The tint comes from the component, so pass only layout classes.
+            <br />
+            Source:{' '}
+            <a
+              href="https://github.com/TanStack/tanstack.com/blob/main/src/components/ds/ui/index.tsx"
+              target="_blank"
+              rel="noreferrer"
+              className="underline underline-offset-2 hover:text-text-primary"
+            >
+              src/components/ds/ui/index.tsx
+            </a>
+            .
+          </>
+        }
+      >
+        <ComponentPreview
+          code={`<Skeleton className="h-4 w-32" />
+<Skeleton className="h-10 w-10 rounded-full" />
+<Skeleton className="h-20 w-32 rounded-lg" />`}
+        >
+          <Skeleton className="h-4 w-32" />
+          <Skeleton className="h-10 w-10 rounded-full" />
+          <Skeleton className="h-20 w-32 rounded-lg" />
+        </ComponentPreview>
+      </DsSection>
+
+      <DsSection
+        id="surfaces"
+        title="On any surface"
+        description="The tint is an alpha overlay, not an opaque color, so it keeps the same contrast on the page background and on a raised card. An opaque surface token reads lighter than the page in dark mode but darker than a card, inverting as it moves between surfaces."
+      >
+        <ComponentPreview
+          code={`<Skeleton className="h-16 w-full" />
+
+<Card className="p-4">
+  <Skeleton className="h-16 w-full" />
+</Card>`}
+        >
+          <div className="w-full space-y-4">
+            <Skeleton className="h-16 w-full" />
+            <Card className="p-4">
+              <Skeleton className="h-16 w-full" />
+            </Card>
+          </div>
+        </ComponentPreview>
+      </DsSection>
+
+      <DsSection
+        id="grouping"
+        title="Grouping and accessibility"
+        description="Each block is aria-hidden, so a lone skeleton announces nothing. Wrap a loading region in SkeletonGroup to give screen readers one message for the whole area. The pulse is wrapped in motion-safe:, so it holds still under prefers-reduced-motion."
+      >
+        <ComponentPreview
+          code={`<SkeletonGroup label="Loading maintainers" className="space-y-3">
+  <Skeleton className="h-6 w-40" />
+  <div className="grid grid-cols-3 gap-3">
+    <Skeleton className="h-24" />
+    <Skeleton className="h-24" />
+    <Skeleton className="h-24" />
+  </div>
+</SkeletonGroup>`}
+        >
+          <SkeletonGroup
+            label="Loading maintainers"
+            className="w-full space-y-3"
+          >
+            <Skeleton className="h-6 w-40" />
+            <div className="grid grid-cols-3 gap-3">
+              <Skeleton className="h-24" />
+              <Skeleton className="h-24" />
+              <Skeleton className="h-24" />
+            </div>
+          </SkeletonGroup>
+        </ComponentPreview>
+      </DsSection>
+
+      <DsSection
+        id="matching"
+        title="Match the real layout"
+        description="Reuse the same grid, gap, and block heights as the content it stands in for. A skeleton that does not match the loaded UI trades a blank screen for a layout shift."
+      >
+        <ComponentPreview
+          code={`<SkeletonGroup label="Loading posts" className="space-y-4">
+  {Array.from({ length: 3 }).map((_, index) => (
+    <div key={index} className="flex gap-3">
+      <Skeleton className="h-12 w-12 shrink-0 rounded-lg" />
+      <div className="flex-1 space-y-2">
+        <Skeleton className="h-4 w-3/4" />
+        <Skeleton className="h-3 w-1/2" />
+      </div>
+    </div>
+  ))}
+</SkeletonGroup>`}
+        >
+          <SkeletonGroup label="Loading posts" className="w-full space-y-4">
+            {Array.from({ length: 3 }).map((_, index) => (
+              <div key={`post-skeleton-${index}`} className="flex gap-3">
+                <Skeleton className="h-12 w-12 shrink-0 rounded-lg" />
+                <div className="flex-1 space-y-2">
+                  <Skeleton className="h-4 w-3/4" />
+                  <Skeleton className="h-3 w-1/2" />
+                </div>
+              </div>
+            ))}
+          </SkeletonGroup>
+        </ComponentPreview>
+      </DsSection>
+    </DsPage>
+  )
+}

From 59e175315c90a27d5a2c69fafcd0333321286537 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Mon, 9 Nov 2026 20:56:35 +0900
Subject: [PATCH 2/7] refactor(components): use the design system 'Skeleton' in
 public loading states

---
 src/components/LandingCommunitySection.tsx    | 11 ++++---
 src/components/PartnersSponsorsSection.tsx    | 18 +++++------
 src/components/home/HomeCommunitySection.tsx  | 12 +++----
 .../home/HomeSocialProofSection.tsx           | 32 +++++++++----------
 src/components/npm-stats/NPMSummary.tsx       | 13 ++++----
 5 files changed, 44 insertions(+), 42 deletions(-)

diff --git a/src/components/LandingCommunitySection.tsx b/src/components/LandingCommunitySection.tsx
index 7fbd364c2..0e32e526a 100644
--- a/src/components/LandingCommunitySection.tsx
+++ b/src/components/LandingCommunitySection.tsx
@@ -2,6 +2,7 @@ import { Hydrate } from '@tanstack/react-start'
 import { visible } from '@tanstack/react-start/hydration'
 import type { LibraryId } from '~/libraries'
 import { MaintainersSection } from './MaintainersSection'
+import { Skeleton, SkeletonGroup } from '~/components/ds/ui'
 
 interface LandingCommunitySectionProps {
   libraryId: LibraryId
@@ -10,17 +11,17 @@ interface LandingCommunitySectionProps {
 function SectionSkeleton({ title }: { title: string }) {
   return (
     <div className="px-4 w-full lg:max-w-(--breakpoint-lg) md:mx-auto">
-      <div className="space-y-8">
-        <div className="h-10 w-48 rounded bg-gray-200/70 dark:bg-gray-800/70 animate-pulse" />
+      <SkeletonGroup label={`Loading ${title}`} className="space-y-8">
+        <Skeleton className="h-10 w-48" />
         <div className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 gap-6">
           {Array.from({ length: 4 }).map((_, index) => (
-            <div
+            <Skeleton
               key={`${title}-${index}`}
-              className="aspect-square rounded-lg bg-gray-200/70 dark:bg-gray-800/70 animate-pulse"
+              className="aspect-square rounded-lg"
             />
           ))}
         </div>
-      </div>
+      </SkeletonGroup>
     </div>
   )
 }
diff --git a/src/components/PartnersSponsorsSection.tsx b/src/components/PartnersSponsorsSection.tsx
index 34dbae7ce..4477137b7 100644
--- a/src/components/PartnersSponsorsSection.tsx
+++ b/src/components/PartnersSponsorsSection.tsx
@@ -2,7 +2,7 @@ import { Link } from '@tanstack/react-router'
 import { Hydrate } from '@tanstack/react-start'
 import { visible } from '@tanstack/react-start/hydration'
 import { ArrowRightIcon } from '@phosphor-icons/react/ArrowRight'
-import { Button } from '~/components/ds/ui'
+import { Button, Skeleton } from '~/components/ds/ui'
 import { OssSponsorsWithQuery } from '~/components/OssSponsorsSection'
 import { PartnersGrid, TierBand } from '~/components/PartnersGrid'
 import type { PartnerPlacement } from '~/utils/analytics'
@@ -78,28 +78,28 @@ function PartnersSponsorsSkeleton() {
       aria-hidden="true"
       className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto"
     >
-      <div className="mb-6 h-10 w-40 animate-pulse rounded bg-gray-200/70 dark:bg-gray-800/70" />
-      <div className="overflow-hidden rounded-2xl border border-gray-200 dark:border-gray-800">
+      <Skeleton className="mb-6 h-10 w-40" />
+      <div className="overflow-hidden rounded-2xl border border-border-default">
         {[2, 3].map((columns, band) => (
           <div key={`partner-band-${band}`}>
-            <div className="h-12 animate-pulse bg-gray-200/70 dark:bg-gray-800/70" />
+            <Skeleton className="h-12 rounded-none" />
             <div
-              className="grid gap-px bg-gray-200/70 dark:bg-gray-800/70"
+              className="grid gap-px bg-border-default"
               style={{
                 gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
               }}
             >
               {Array.from({ length: columns * 2 }).map((_, index) => (
-                <div
+                <Skeleton
                   key={`partner-skeleton-${band}-${index}`}
-                  className="min-h-[130px] animate-pulse bg-white/70 dark:bg-gray-950/60"
+                  className="min-h-[130px] rounded-none"
                 />
               ))}
             </div>
           </div>
         ))}
-        <div className="h-12 animate-pulse bg-gray-200/70 dark:bg-gray-800/70" />
-        <div className="h-[420px] animate-pulse bg-white/70 sm:h-[480px] lg:h-[540px] dark:bg-gray-950/60" />
+        <Skeleton className="h-12 rounded-none" />
+        <Skeleton className="h-[420px] rounded-none sm:h-[480px] lg:h-[540px]" />
       </div>
     </div>
   )
diff --git a/src/components/home/HomeCommunitySection.tsx b/src/components/home/HomeCommunitySection.tsx
index 16d7589c7..b91f10c48 100644
--- a/src/components/home/HomeCommunitySection.tsx
+++ b/src/components/home/HomeCommunitySection.tsx
@@ -4,7 +4,7 @@ import { visible } from '@tanstack/react-start/hydration'
 import { ArrowRightIcon } from '@phosphor-icons/react'
 import { MaintainerCard } from '~/components/MaintainerCard'
 import { coreMaintainers } from '~/libraries/maintainers'
-import { Button } from '~/components/ds/ui'
+import { Button, Skeleton, SkeletonGroup } from '~/components/ds/ui'
 
 export function HomeCommunitySection() {
   return (
@@ -19,19 +19,19 @@ export function HomeCommunitySection() {
 
 function CommunitySkeleton() {
   return (
-    <div className="space-y-24">
+    <SkeletonGroup label="Loading maintainers" className="space-y-24">
       <div className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto">
-        <div className="mb-6 h-10 w-52 animate-pulse rounded corner-squircle bg-gray-200/70 dark:bg-gray-800/70" />
+        <Skeleton className="mb-6 h-10 w-52 corner-squircle" />
         <div className="grid grid-cols-2 gap-6 sm:grid-cols-3 lg:grid-cols-5">
           {Array.from({ length: 10 }).map((_, index) => (
-            <div
+            <Skeleton
               key={`maintainer-skeleton-${index}`}
-              className="h-52 animate-pulse rounded-lg corner-squircle bg-gray-100/70 dark:bg-gray-900/60"
+              className="h-52 rounded-lg corner-squircle"
             />
           ))}
         </div>
       </div>
-    </div>
+    </SkeletonGroup>
   )
 }
 
diff --git a/src/components/home/HomeSocialProofSection.tsx b/src/components/home/HomeSocialProofSection.tsx
index 47e9370d2..935e41b25 100644
--- a/src/components/home/HomeSocialProofSection.tsx
+++ b/src/components/home/HomeSocialProofSection.tsx
@@ -3,7 +3,7 @@ import { Hydrate } from '@tanstack/react-start'
 import { visible } from '@tanstack/react-start/hydration'
 import { ArrowRightIcon } from '@phosphor-icons/react'
 import { BlogPostCard } from '~/components/ds/ui/BlogPostCard'
-import { Button } from '~/components/ds/ui'
+import { Button, Skeleton, SkeletonGroup } from '~/components/ds/ui'
 import { PartnersSponsorsContent } from '~/components/PartnersSponsorsSection'
 import type { RecentPost } from '~/utils/blog.functions'
 
@@ -26,23 +26,23 @@ export function HomeSocialProofSection({
 
 function SocialProofSkeleton() {
   return (
-    <div className="space-y-24">
+    <SkeletonGroup label="Loading partners and posts" className="space-y-24">
       <div className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto">
-        <div className="h-10 w-40 rounded bg-gray-200/70 dark:bg-gray-800/70 animate-pulse mb-6" />
-        <div className="overflow-hidden rounded-2xl corner-squircle border border-gray-200 dark:border-gray-800">
+        <Skeleton className="h-10 w-40 mb-6" />
+        <div className="overflow-hidden rounded-2xl corner-squircle border border-border-default">
           {[2, 3].map((cols, band) => (
             <div key={`partner-band-${band}`}>
-              <div className="h-12 bg-gray-200/70 dark:bg-gray-800/70 animate-pulse" />
+              <Skeleton className="h-12 rounded-none" />
               <div
-                className="grid gap-px bg-gray-200/70 dark:bg-gray-800/70"
+                className="grid gap-px bg-border-default"
                 style={{
                   gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`,
                 }}
               >
                 {Array.from({ length: cols * 2 }).map((_, index) => (
-                  <div
+                  <Skeleton
                     key={`partner-skeleton-${band}-${index}`}
-                    className="min-h-[130px] bg-white/70 dark:bg-gray-950/60 animate-pulse"
+                    className="min-h-[130px] rounded-none"
                   />
                 ))}
               </div>
@@ -51,27 +51,27 @@ function SocialProofSkeleton() {
         </div>
       </div>
       <div className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto">
-        <div className="h-10 w-56 rounded bg-gray-200/70 dark:bg-gray-800/70 animate-pulse mb-6" />
+        <Skeleton className="h-10 w-56 mb-6" />
         <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
           {Array.from({ length: 3 }).map((_, index) => (
             <div
               key={`post-skeleton-${index}`}
-              className="animate-pulse rounded-xl corner-squircle p-2"
+              className="rounded-xl corner-squircle p-2"
             >
-              <div className="aspect-video rounded-lg corner-squircle bg-gray-100 dark:bg-gray-800" />
+              <Skeleton className="aspect-video rounded-lg corner-squircle" />
               <div className="px-0.5 pt-2.5">
-                <div className="h-5 w-5/6 rounded bg-gray-200 dark:bg-gray-700" />
-                <div className="mt-3 h-3 w-2/3 rounded bg-gray-200 dark:bg-gray-700" />
+                <Skeleton className="h-5 w-5/6" />
+                <Skeleton className="mt-3 h-3 w-2/3" />
                 <div className="mt-4 space-y-2">
-                  <div className="h-3 rounded bg-gray-100 dark:bg-gray-800" />
-                  <div className="h-3 rounded bg-gray-100 dark:bg-gray-800" />
+                  <Skeleton className="h-3" />
+                  <Skeleton className="h-3" />
                 </div>
               </div>
             </div>
           ))}
         </div>
       </div>
-    </div>
+    </SkeletonGroup>
   )
 }
 
diff --git a/src/components/npm-stats/NPMSummary.tsx b/src/components/npm-stats/NPMSummary.tsx
index cbde3e3e5..f9b40f6b1 100644
--- a/src/components/npm-stats/NPMSummary.tsx
+++ b/src/components/npm-stats/NPMSummary.tsx
@@ -2,6 +2,7 @@ import * as React from 'react'
 import { Suspense } from 'react'
 import { useSuspenseQuery } from '@tanstack/react-query'
 import { BlankErrorBoundary } from '~/components/BlankErrorBoundary'
+import { Skeleton, SkeletonGroup } from '~/components/ds/ui'
 import { ossStatsQuery, recentDownloadsQuery } from '~/queries/stats'
 import { useNpmDownloadCounter } from '~/hooks/useNpmDownloadCounter'
 import type { Library } from '~/libraries'
@@ -125,19 +126,19 @@ function NPMSummaryContent({ library }: { library: Library }) {
  */
 function NPMSummarySkeleton() {
   return (
-    <div className="mb-6">
-      <div className="h-7 w-64 bg-gray-200 dark:bg-gray-700 rounded animate-pulse mb-2" />
-      <div className="h-5 w-96 max-w-full bg-gray-200 dark:bg-gray-700 rounded animate-pulse mb-4" />
+    <SkeletonGroup label="Loading download stats" className="mb-6">
+      <Skeleton className="h-7 w-64 mb-2" />
+      <Skeleton className="h-5 w-96 max-w-full mb-4" />
 
       <div className="grid grid-cols-2 md:grid-cols-4 gap-4 sm:gap-6">
         {[...Array(4)].map((_, i) => (
           <div key={i} className="flex flex-col items-center">
-            <div className="h-9 w-24 bg-gray-200 dark:bg-gray-700 rounded animate-pulse" />
-            <div className="h-4 w-20 bg-gray-200 dark:bg-gray-700 rounded animate-pulse mt-2" />
+            <Skeleton className="h-9 w-24" />
+            <Skeleton className="h-4 w-20 mt-2" />
           </div>
         ))}
       </div>
-    </div>
+    </SkeletonGroup>
   )
 }
 

From 9fbdb1ff6b362b8ec6dfb39eb787c8b4b0dea962 Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Mon, 9 Nov 2026 22:14:33 +0900
Subject: [PATCH 3/7] fix(components): match skeleton layout to loaded content
 and correct surface claims

---
 src/components/PartnersSponsorsSection.tsx     |  8 ++++----
 src/components/ds/ui/index.tsx                 |  9 +++++----
 src/components/home/HomeSocialProofSection.tsx |  4 ++--
 src/components/npm-stats/NPMSummary.tsx        | 12 ++++++------
 src/routes/ds.skeleton.tsx                     |  2 +-
 5 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/src/components/PartnersSponsorsSection.tsx b/src/components/PartnersSponsorsSection.tsx
index 4477137b7..a8f921887 100644
--- a/src/components/PartnersSponsorsSection.tsx
+++ b/src/components/PartnersSponsorsSection.tsx
@@ -2,7 +2,7 @@ import { Link } from '@tanstack/react-router'
 import { Hydrate } from '@tanstack/react-start'
 import { visible } from '@tanstack/react-start/hydration'
 import { ArrowRightIcon } from '@phosphor-icons/react/ArrowRight'
-import { Button, Skeleton } from '~/components/ds/ui'
+import { Button, Skeleton, SkeletonGroup } from '~/components/ds/ui'
 import { OssSponsorsWithQuery } from '~/components/OssSponsorsSection'
 import { PartnersGrid, TierBand } from '~/components/PartnersGrid'
 import type { PartnerPlacement } from '~/utils/analytics'
@@ -74,8 +74,8 @@ export function PartnersSponsorsContent({
 
 function PartnersSponsorsSkeleton() {
   return (
-    <div
-      aria-hidden="true"
+    <SkeletonGroup
+      label="Loading partners"
       className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto"
     >
       <Skeleton className="mb-6 h-10 w-40" />
@@ -101,7 +101,7 @@ function PartnersSponsorsSkeleton() {
         <Skeleton className="h-12 rounded-none" />
         <Skeleton className="h-[420px] rounded-none sm:h-[480px] lg:h-[540px]" />
       </div>
-    </div>
+    </SkeletonGroup>
   )
 }
 
diff --git a/src/components/ds/ui/index.tsx b/src/components/ds/ui/index.tsx
index 074851a67..2b7f416cc 100644
--- a/src/components/ds/ui/index.tsx
+++ b/src/components/ds/ui/index.tsx
@@ -633,10 +633,11 @@ export function Spinner({ className }: { className?: string }) {
 /**
  * Placeholder block shown while content loads.
  *
- * The tint is an alpha overlay rather than an opaque surface token, so it keeps
- * the same contrast on the page background and on an elevated card — an opaque
- * `background-subtle` reads lighter than the page in dark mode but darker than
- * a card, inverting as it moves between surfaces.
+ * The tint is an alpha overlay rather than an opaque surface token, so it always
+ * reads lighter than whatever sits behind it in dark mode and darker in light.
+ * An opaque `background-subtle` cannot do that: in dark mode it is lighter than
+ * the page but darker than an elevated card, so it inverts as it moves between
+ * surfaces.
  *
  * The pulse is wrapped in `motion-safe:` so it holds still under
  * `prefers-reduced-motion`.
diff --git a/src/components/home/HomeSocialProofSection.tsx b/src/components/home/HomeSocialProofSection.tsx
index 935e41b25..ebdbbe554 100644
--- a/src/components/home/HomeSocialProofSection.tsx
+++ b/src/components/home/HomeSocialProofSection.tsx
@@ -51,8 +51,8 @@ function SocialProofSkeleton() {
         </div>
       </div>
       <div className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto">
-        <Skeleton className="h-10 w-56 mb-6" />
-        <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+        <Skeleton className="mb-3 ml-1 h-4 w-48" />
+        <div className="grid grid-cols-1 gap-4 md:grid-cols-3">
           {Array.from({ length: 3 }).map((_, index) => (
             <div
               key={`post-skeleton-${index}`}
diff --git a/src/components/npm-stats/NPMSummary.tsx b/src/components/npm-stats/NPMSummary.tsx
index f9b40f6b1..4de8e269a 100644
--- a/src/components/npm-stats/NPMSummary.tsx
+++ b/src/components/npm-stats/NPMSummary.tsx
@@ -126,15 +126,15 @@ function NPMSummaryContent({ library }: { library: Library }) {
  */
 function NPMSummarySkeleton() {
   return (
-    <SkeletonGroup label="Loading download stats" className="mb-6">
-      <Skeleton className="h-7 w-64 mb-2" />
-      <Skeleton className="h-5 w-96 max-w-full mb-4" />
+    <SkeletonGroup label="Loading download stats" className="my-6">
+      <Skeleton className="h-5 w-full max-w-prose mb-4" />
+      <Skeleton className="h-4 w-80 max-w-full my-3" />
 
-      <div className="grid grid-cols-2 md:grid-cols-4 gap-4 sm:gap-6">
+      <div className="grid grid-cols-2 gap-4 sm:gap-6 md:grid-cols-2 xl:grid-cols-4 py-6">
         {[...Array(4)].map((_, i) => (
           <div key={i} className="flex flex-col items-center">
-            <Skeleton className="h-9 w-24" />
-            <Skeleton className="h-4 w-20 mt-2" />
+            <Skeleton className="h-8 w-24" />
+            <Skeleton className="h-5 w-20 mt-1" />
           </div>
         ))}
       </div>
diff --git a/src/routes/ds.skeleton.tsx b/src/routes/ds.skeleton.tsx
index 4c1abc5af..e2a6990b0 100644
--- a/src/routes/ds.skeleton.tsx
+++ b/src/routes/ds.skeleton.tsx
@@ -55,7 +55,7 @@ function SkeletonPage() {
       <DsSection
         id="surfaces"
         title="On any surface"
-        description="The tint is an alpha overlay, not an opaque color, so it keeps the same contrast on the page background and on a raised card. An opaque surface token reads lighter than the page in dark mode but darker than a card, inverting as it moves between surfaces."
+        description="The tint is an alpha overlay, not an opaque color, so it always reads lighter than whatever is behind it in dark mode and darker in light. An opaque surface token cannot do that: in dark mode it is lighter than the page but darker than a raised card, so it inverts as it moves between surfaces."
       >
         <ComponentPreview
           code={`<Skeleton className="h-16 w-full" />

From 5c4f8e62df1527b2ea7ea31a48b627040305efce Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Mon, 9 Nov 2026 22:23:33 +0900
Subject: [PATCH 4/7] refactor(components): use the design system 'Skeleton' in
 the remaining public loading states

---
 src/components/RecentPostsWidget.tsx          | 12 +++++---
 src/components/ShowcaseCard.tsx               | 27 ++++++++++++------
 src/components/ShowcaseGallery.tsx            | 20 ++++++++++---
 src/components/ShowcaseSection.tsx            |  8 ++++--
 src/components/home/HomeSectionFallbacks.tsx  | 26 ++++++++---------
 .../home/HomeSocialProofSection.tsx           |  2 ++
 src/routes/intent/registry/$packageName.tsx   | 28 +++++++++----------
 7 files changed, 77 insertions(+), 46 deletions(-)

diff --git a/src/components/RecentPostsWidget.tsx b/src/components/RecentPostsWidget.tsx
index 9380fb323..f149e785c 100644
--- a/src/components/RecentPostsWidget.tsx
+++ b/src/components/RecentPostsWidget.tsx
@@ -2,6 +2,7 @@ import { Link } from '@tanstack/react-router'
 import { useQuery } from '@tanstack/react-query'
 import { fetchRecentPosts, type RecentPost } from '~/utils/blog.functions'
 import { formatPublishedDate } from '~/utils/blog-format'
+import { Skeleton, SkeletonGroup } from '~/components/ds/ui'
 
 type RecentPostsWidgetProps = {
   posts?: ReadonlyArray<RecentPost>
@@ -76,14 +77,17 @@ function RecentPostsSkeleton() {
           Latest Posts
         </Link>
       </div>
-      <div className="flex flex-col divide-y divide-gray-500/10">
+      <SkeletonGroup
+        label="Loading latest posts"
+        className="flex flex-col divide-y divide-gray-500/10"
+      >
         {Array.from({ length: 3 }).map((_, index) => (
           <div key={`recent-post-skeleton-${index}`} className="px-3 py-2.5">
-            <div className="h-3.5 w-full rounded bg-gray-200/70 dark:bg-gray-800/70" />
-            <div className="mt-2 h-2.5 w-20 rounded bg-gray-100 dark:bg-gray-900" />
+            <Skeleton className="h-3.5 w-full" />
+            <Skeleton className="mt-2 h-2.5 w-20" />
           </div>
         ))}
-      </div>
+      </SkeletonGroup>
     </div>
   )
 }
diff --git a/src/components/ShowcaseCard.tsx b/src/components/ShowcaseCard.tsx
index a1c62cd36..49e81cfca 100644
--- a/src/components/ShowcaseCard.tsx
+++ b/src/components/ShowcaseCard.tsx
@@ -7,6 +7,7 @@ import {
   ThumbsDownIcon,
   CodeIcon,
 } from '@phosphor-icons/react'
+import { Skeleton } from '~/components/ds/ui'
 import { libraries, type LibraryId } from '~/libraries'
 import type { PublicShowcase } from '~/db/types'
 
@@ -193,14 +194,24 @@ export function ShowcaseCard({
 
 export function ShowcaseCardSkeleton() {
   return (
-    <div className="rounded-xl corner-squircle overflow-hidden bg-white dark:bg-gray-800 shadow-lg border border-gray-200 dark:border-gray-700 animate-pulse">
-      <div className="aspect-video bg-gray-200 dark:bg-gray-700" />
-      <div className="p-4">
-        <div className="h-6 bg-gray-200 dark:bg-gray-700 rounded w-3/4" />
-        <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-full mt-2" />
-        <div className="flex gap-1.5 mt-3">
-          <div className="h-5 w-16 bg-gray-200 dark:bg-gray-700 rounded-full" />
-          <div className="h-5 w-14 bg-gray-200 dark:bg-gray-700 rounded-full" />
+    <div className="group relative flex h-full flex-col overflow-hidden rounded-xl corner-squircle border border-gray-200 bg-white shadow-lg dark:border-gray-700 dark:bg-gray-800">
+      <Skeleton className="aspect-video rounded-none" />
+      <div className="flex-1 p-4">
+        <Skeleton className="h-7 w-3/4" />
+        <Skeleton className="mt-1 h-5 w-full" />
+        <Skeleton className="mt-1 h-5 w-2/3" />
+      </div>
+      <div className="mt-auto px-4 pb-4">
+        <div className="flex items-end justify-between gap-2">
+          <div className="flex min-w-0 flex-wrap gap-1.5">
+            <Skeleton className="h-5 w-16 rounded-full" />
+            <Skeleton className="h-5 w-14 rounded-full" />
+          </div>
+          <div className="flex shrink-0 items-center gap-1">
+            <Skeleton className="h-8 w-8 rounded-full" />
+            <Skeleton className="h-4 w-6" />
+            <Skeleton className="h-8 w-8 rounded-full" />
+          </div>
         </div>
       </div>
     </div>
diff --git a/src/components/ShowcaseGallery.tsx b/src/components/ShowcaseGallery.tsx
index c6d588b29..f91b1d9ca 100644
--- a/src/components/ShowcaseGallery.tsx
+++ b/src/components/ShowcaseGallery.tsx
@@ -6,6 +6,7 @@ import {
   getMyShowcaseVotesQueryOptions,
 } from '~/queries/showcases'
 import { voteShowcase } from '~/utils/showcase.functions'
+import { Skeleton, SkeletonGroup } from '~/components/ds/ui'
 import { ShowcaseCard, ShowcaseCardSkeleton } from './ShowcaseCard'
 import { CommunityProjectCard } from './CommunityProjectCard'
 import { SubmitShowcasePlaceholder } from './ShowcaseSection'
@@ -380,18 +381,29 @@ export function ShowcaseGallery({
       {/* Grid */}
       <div className="max-w-7xl mx-auto px-4 py-8">
         {isLoading ? (
-          <div className={gridClassName}>
+          <SkeletonGroup
+            label="Loading projects"
+            className={gridClassName}
+          >
             {Array.from({ length: 6 }).map((_, i) =>
               community ? (
                 <div
                   key={i}
-                  className="h-32 animate-pulse border-b border-gray-200 dark:border-gray-800"
-                />
+                  className="flex items-start gap-3 border-b border-gray-200 py-5 dark:border-gray-800"
+                >
+                  <Skeleton className="size-10 shrink-0 rounded-lg" />
+                  <div className="min-w-0 flex-1">
+                    <Skeleton className="h-6 w-48 max-w-full" />
+                    <Skeleton className="mt-1 h-5 w-full" />
+                    <Skeleton className="mt-1 h-5 w-4/5" />
+                    <Skeleton className="mt-2 h-4 w-32" />
+                  </div>
+                </div>
               ) : (
                 <ShowcaseCardSkeleton key={i} />
               ),
             )}
-          </div>
+          </SkeletonGroup>
         ) : data?.showcases && data.showcases.length > 0 ? (
           <>
             <div className={gridClassName}>
diff --git a/src/components/ShowcaseSection.tsx b/src/components/ShowcaseSection.tsx
index 6c7d6b9f4..89607231c 100644
--- a/src/components/ShowcaseSection.tsx
+++ b/src/components/ShowcaseSection.tsx
@@ -7,6 +7,7 @@ import {
   getMyShowcaseVotesQueryOptions,
 } from '~/queries/showcases'
 import { voteShowcase } from '~/utils/showcase.functions'
+import { SkeletonGroup } from '~/components/ds/ui'
 import { ShowcaseCard, ShowcaseCardSkeleton } from './ShowcaseCard'
 import { Button } from '~/ui'
 import { ArrowRightIcon, PlusIcon } from '@phosphor-icons/react'
@@ -205,11 +206,14 @@ export function ShowcaseSection({
       </div>
 
       {isLoading ? (
-        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
+        <SkeletonGroup
+          label="Loading showcases"
+          className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6"
+        >
           {Array.from({ length: Math.max(limit, minItems) }).map((_, i) => (
             <ShowcaseCardSkeleton key={i} />
           ))}
-        </div>
+        </SkeletonGroup>
       ) : (
         <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
           {showcases.map(({ showcase, user }) => (
diff --git a/src/components/home/HomeSectionFallbacks.tsx b/src/components/home/HomeSectionFallbacks.tsx
index ef5913500..ec1f762f2 100644
--- a/src/components/home/HomeSectionFallbacks.tsx
+++ b/src/components/home/HomeSectionFallbacks.tsx
@@ -1,4 +1,4 @@
-import { Card } from '~/components/ds/ui'
+import { Card, Skeleton, SkeletonGroup } from '~/components/ds/ui'
 
 function SectionTitle({ id, title }: { id: string; title: string }) {
   return (
@@ -88,35 +88,35 @@ export function HomeNewsletterFallback() {
 
 export function HomeApplicationStarterFallback() {
   return (
-    <div
-      aria-hidden="true"
-      className="min-h-[320px] overflow-hidden rounded-[1rem] border border-gray-200 bg-white dark:border-gray-800 dark:bg-gray-950 md:min-h-[360px]"
+    <SkeletonGroup
+      label="Loading the app starter"
+      className="relative min-h-[320px] overflow-hidden rounded-[1rem] border border-gray-200 bg-white dark:border-gray-800 dark:bg-gray-950 md:min-h-[360px]"
     >
       <div className="border-b border-gray-200 bg-gray-50/70 px-5 py-4 dark:border-gray-800 dark:bg-gray-900/50">
-        <div className="h-7 w-64 max-w-full rounded bg-gray-200 dark:bg-gray-800" />
+        <Skeleton className="h-7 w-64 max-w-full" />
         <div className="mt-4 flex flex-wrap gap-2">
-          <div className="h-9 w-28 rounded-lg bg-gray-200 dark:bg-gray-800" />
-          <div className="h-9 w-32 rounded-lg bg-gray-200 dark:bg-gray-800" />
-          <div className="h-9 w-24 rounded-lg bg-gray-200 dark:bg-gray-800" />
+          <Skeleton className="h-9 w-28 rounded-lg" />
+          <Skeleton className="h-9 w-32 rounded-lg" />
+          <Skeleton className="h-9 w-24 rounded-lg" />
         </div>
       </div>
 
       <div className="relative border-b border-gray-200 dark:border-gray-800">
         <div className="px-5 pt-4">
-          <div className="h-3 w-12 rounded bg-gray-200 dark:bg-gray-800" />
+          <Skeleton className="h-3 w-12" />
         </div>
         <div className="px-5 pb-4 pt-3">
-          <div className="h-28 rounded-xl bg-gray-100 dark:bg-gray-900" />
+          <Skeleton className="h-28 rounded-xl" />
         </div>
 
         <div className="border-t border-gray-200 px-5 py-4 dark:border-gray-800">
           <div className="flex flex-wrap gap-3">
-            <div className="h-10 w-28 rounded-lg bg-gray-200 dark:bg-gray-800" />
-            <div className="h-10 w-36 rounded-lg bg-gray-200 dark:bg-gray-800" />
+            <Skeleton className="h-10 w-28 rounded-lg" />
+            <Skeleton className="h-10 w-36 rounded-lg" />
           </div>
         </div>
       </div>
-    </div>
+    </SkeletonGroup>
   )
 }
 
diff --git a/src/components/home/HomeSocialProofSection.tsx b/src/components/home/HomeSocialProofSection.tsx
index ebdbbe554..6ed74dd2b 100644
--- a/src/components/home/HomeSocialProofSection.tsx
+++ b/src/components/home/HomeSocialProofSection.tsx
@@ -48,6 +48,8 @@ function SocialProofSkeleton() {
               </div>
             </div>
           ))}
+          <Skeleton className="h-12 rounded-none" />
+          <Skeleton className="h-[420px] rounded-none sm:h-[480px] lg:h-[540px]" />
         </div>
       </div>
       <div className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto">
diff --git a/src/routes/intent/registry/$packageName.tsx b/src/routes/intent/registry/$packageName.tsx
index 1e88adcf3..b10f83d86 100644
--- a/src/routes/intent/registry/$packageName.tsx
+++ b/src/routes/intent/registry/$packageName.tsx
@@ -9,6 +9,7 @@ import {
 import { useSuspenseQuery, useQuery } from '@tanstack/react-query'
 import * as v from 'valibot'
 import { CopyIcon, CheckIcon } from '@phosphor-icons/react'
+import { Skeleton, SkeletonGroup } from '~/components/ds/ui'
 import { Panel, PanelContent } from '~/components/Panel'
 import { seo } from '~/utils/seo'
 import {
@@ -526,7 +527,7 @@ function MobileSkillsDrawer({
 
 export function PackageDetailSkeleton({ name }: { readonly name: string }) {
   return (
-    <>
+    <SkeletonGroup label={`Loading ${name}`}>
       <div className="border-b border-gray-200 dark:border-gray-800">
         <div className="max-w-6xl mx-auto px-4 sm:px-6 py-6">
           <div className="flex items-center gap-2 text-sm text-gray-500 dark:text-gray-400 mb-4">
@@ -549,36 +550,33 @@ export function PackageDetailSkeleton({ name }: { readonly name: string }) {
               {name}
             </span>
           </div>
-          <div className="animate-pulse space-y-3">
-            <div className="h-8 w-48 bg-gray-200 dark:bg-gray-800 rounded" />
-            <div className="h-4 w-72 bg-gray-100 dark:bg-gray-800/60 rounded" />
+          <div className="space-y-3">
+            <Skeleton className="h-8 w-48" />
+            <Skeleton className="h-4 w-72" />
           </div>
         </div>
       </div>
       <div className="max-w-6xl mx-auto px-4 sm:px-6 flex gap-0 min-h-[calc(100vh-200px)]">
         <aside className="hidden md:block w-56 shrink-0 border-r border-gray-200 dark:border-gray-800 py-6 pr-4">
-          <div className="animate-pulse space-y-2">
-            <div className="h-3 w-12 bg-gray-200 dark:bg-gray-800 rounded mb-3" />
+          <div className="space-y-2">
+            <Skeleton className="mb-3 h-3 w-12" />
             {Array.from({ length: 4 }).map((_, i) => (
-              <div
-                key={i}
-                className="h-7 w-full bg-gray-100 dark:bg-gray-800/60 rounded-md"
-              />
+              <Skeleton key={i} className="h-7 w-full rounded-md" />
             ))}
           </div>
         </aside>
         <main className="flex-1 min-w-0 py-6 md:pl-6">
-          <div className="animate-pulse space-y-3">
-            <div className="h-6 w-40 bg-gray-200 dark:bg-gray-800 rounded" />
-            <div className="h-4 w-96 bg-gray-100 dark:bg-gray-800/60 rounded" />
-            <div className="mt-6 h-64 w-full bg-gray-100 dark:bg-gray-800/60 rounded-xl" />
+          <div className="space-y-3">
+            <Skeleton className="h-6 w-40" />
+            <Skeleton className="h-4 w-96 max-w-full" />
+            <Skeleton className="mt-6 h-64 w-full rounded-xl" />
           </div>
           <p className="mt-6 text-xs text-gray-400 dark:text-gray-500">
             Fetching package from npm...
           </p>
         </main>
       </div>
-    </>
+    </SkeletonGroup>
   )
 }
 

From 7dc1b0c4091bf3de11a98c5a2a71a7147580699a Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Mon, 9 Nov 2026 22:28:17 +0900
Subject: [PATCH 5/7] refactor(partners): share a tier-aware
 'PartnersGridSkeleton' between the grid callers

---
 src/components/PartnersGrid.tsx               | 62 +++++++++++++++++++
 src/components/PartnersSponsorsSection.tsx    | 29 ++-------
 .../home/HomeSocialProofSection.tsx           | 24 +------
 3 files changed, 70 insertions(+), 45 deletions(-)

diff --git a/src/components/PartnersGrid.tsx b/src/components/PartnersGrid.tsx
index 6bb7e8097..f6d318401 100644
--- a/src/components/PartnersGrid.tsx
+++ b/src/components/PartnersGrid.tsx
@@ -5,6 +5,7 @@ import {
   PartnerImage,
   partnerTierBandColor,
   partnerTierLabels,
+  partnerTiers,
   type PartnerTier,
 } from '~/utils/partners'
 import {
@@ -13,6 +14,7 @@ import {
   type PartnerPlacementContext,
 } from '~/utils/partner-placement'
 import { usePartnerPlacementContext } from '~/utils/usePartnerPlacementContext'
+import { Skeleton } from '~/components/ds/ui'
 import {
   trackEvent,
   useTrackedImpression,
@@ -155,6 +157,66 @@ function PartnerGridItem({
   )
 }
 
+/**
+ * Loading shape for `PartnersGrid`. It walks the same tier config as the real
+ * grid, so the band heights and cell sizes line up instead of collapsing to a
+ * uniform placeholder.
+ */
+export function PartnersGridSkeleton({
+  partnersList,
+  status = 'active',
+  withSponsorsBand = true,
+}: {
+  partnersList?: PartnersGridProps['partnersList']
+  status?: PartnersGridProps['status']
+  withSponsorsBand?: boolean
+}) {
+  const items = (partnersList ?? allPartners).filter(
+    (partner) => partner.status === status,
+  )
+
+  return (
+    <div className="overflow-hidden rounded-2xl corner-squircle border border-gray-200 dark:border-gray-800">
+      {partnerTiers.map((tier) => {
+        const count = items.filter((partner) => partner.tier === tier).length
+        if (count === 0) {
+          return null
+        }
+        const sizing = tierLayout[tier]
+        return (
+          <React.Fragment key={tier}>
+            <div className="h-[60px]" aria-hidden="true">
+              <Skeleton className="h-full rounded-none" />
+            </div>
+            <div className="flex flex-wrap items-stretch -mr-px -mb-px">
+              {Array.from({ length: count }).map((_, index) => (
+                <div
+                  key={`${tier}-${index}`}
+                  className={`${sizing.flexBasis} ${sizing.minHeight} border-r border-b border-gray-200 dark:border-gray-800`}
+                >
+                  <Skeleton className="h-full rounded-none" />
+                </div>
+              ))}
+            </div>
+          </React.Fragment>
+        )
+      })}
+      {withSponsorsBand ? (
+        <>
+          <div className="h-[60px]" aria-hidden="true">
+            <Skeleton className="h-full rounded-none" />
+          </div>
+          <div className="px-4 py-10">
+            <Skeleton className="h-[420px] rounded-lg sm:h-[480px] lg:h-[540px]" />
+            <Skeleton className="mx-auto mt-8 h-12 w-full max-w-(--breakpoint-sm)" />
+            <Skeleton className="mx-auto mt-6 h-10 w-48" />
+          </div>
+        </>
+      ) : null}
+    </div>
+  )
+}
+
 export function PartnersGrid({
   analyticsPlacement = 'grid',
   partnersList,
diff --git a/src/components/PartnersSponsorsSection.tsx b/src/components/PartnersSponsorsSection.tsx
index a8f921887..f9881d580 100644
--- a/src/components/PartnersSponsorsSection.tsx
+++ b/src/components/PartnersSponsorsSection.tsx
@@ -4,7 +4,11 @@ import { visible } from '@tanstack/react-start/hydration'
 import { ArrowRightIcon } from '@phosphor-icons/react/ArrowRight'
 import { Button, Skeleton, SkeletonGroup } from '~/components/ds/ui'
 import { OssSponsorsWithQuery } from '~/components/OssSponsorsSection'
-import { PartnersGrid, TierBand } from '~/components/PartnersGrid'
+import {
+  PartnersGrid,
+  PartnersGridSkeleton,
+  TierBand,
+} from '~/components/PartnersGrid'
 import type { PartnerPlacement } from '~/utils/analytics'
 
 type PartnersSponsorsContentProps = {
@@ -79,28 +83,7 @@ function PartnersSponsorsSkeleton() {
       className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto"
     >
       <Skeleton className="mb-6 h-10 w-40" />
-      <div className="overflow-hidden rounded-2xl border border-border-default">
-        {[2, 3].map((columns, band) => (
-          <div key={`partner-band-${band}`}>
-            <Skeleton className="h-12 rounded-none" />
-            <div
-              className="grid gap-px bg-border-default"
-              style={{
-                gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
-              }}
-            >
-              {Array.from({ length: columns * 2 }).map((_, index) => (
-                <Skeleton
-                  key={`partner-skeleton-${band}-${index}`}
-                  className="min-h-[130px] rounded-none"
-                />
-              ))}
-            </div>
-          </div>
-        ))}
-        <Skeleton className="h-12 rounded-none" />
-        <Skeleton className="h-[420px] rounded-none sm:h-[480px] lg:h-[540px]" />
-      </div>
+      <PartnersGridSkeleton />
     </SkeletonGroup>
   )
 }
diff --git a/src/components/home/HomeSocialProofSection.tsx b/src/components/home/HomeSocialProofSection.tsx
index 6ed74dd2b..5d983227b 100644
--- a/src/components/home/HomeSocialProofSection.tsx
+++ b/src/components/home/HomeSocialProofSection.tsx
@@ -5,6 +5,7 @@ import { ArrowRightIcon } from '@phosphor-icons/react'
 import { BlogPostCard } from '~/components/ds/ui/BlogPostCard'
 import { Button, Skeleton, SkeletonGroup } from '~/components/ds/ui'
 import { PartnersSponsorsContent } from '~/components/PartnersSponsorsSection'
+import { PartnersGridSkeleton } from '~/components/PartnersGrid'
 import type { RecentPost } from '~/utils/blog.functions'
 
 type HomeSocialProofSectionProps = {
@@ -29,28 +30,7 @@ function SocialProofSkeleton() {
     <SkeletonGroup label="Loading partners and posts" className="space-y-24">
       <div className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto">
         <Skeleton className="h-10 w-40 mb-6" />
-        <div className="overflow-hidden rounded-2xl corner-squircle border border-border-default">
-          {[2, 3].map((cols, band) => (
-            <div key={`partner-band-${band}`}>
-              <Skeleton className="h-12 rounded-none" />
-              <div
-                className="grid gap-px bg-border-default"
-                style={{
-                  gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`,
-                }}
-              >
-                {Array.from({ length: cols * 2 }).map((_, index) => (
-                  <Skeleton
-                    key={`partner-skeleton-${band}-${index}`}
-                    className="min-h-[130px] rounded-none"
-                  />
-                ))}
-              </div>
-            </div>
-          ))}
-          <Skeleton className="h-12 rounded-none" />
-          <Skeleton className="h-[420px] rounded-none sm:h-[480px] lg:h-[540px]" />
-        </div>
+        <PartnersGridSkeleton />
       </div>
       <div className="px-4 lg:max-w-(--breakpoint-lg) md:mx-auto">
         <Skeleton className="mb-3 ml-1 h-4 w-48" />

From cf83ed6e55963cc7e81850446653106e38bb50e5 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Mon, 9 Nov 2026 14:03:47 +0000
Subject: [PATCH 6/7] ci: apply automated fixes

---
 src/components/ShowcaseGallery.tsx | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/components/ShowcaseGallery.tsx b/src/components/ShowcaseGallery.tsx
index f91b1d9ca..15fda6098 100644
--- a/src/components/ShowcaseGallery.tsx
+++ b/src/components/ShowcaseGallery.tsx
@@ -381,10 +381,7 @@ export function ShowcaseGallery({
       {/* Grid */}
       <div className="max-w-7xl mx-auto px-4 py-8">
         {isLoading ? (
-          <SkeletonGroup
-            label="Loading projects"
-            className={gridClassName}
-          >
+          <SkeletonGroup label="Loading projects" className={gridClassName}>
             {Array.from({ length: 6 }).map((_, i) =>
               community ? (
                 <div

From 787241dd081573d0df15a3542099737d6f136c3d Mon Sep 17 00:00:00 2001
From: Wonsuk Choi <sukvvon@gmail.com>
Date: Tue, 10 Nov 2026 08:03:06 +0900
Subject: [PATCH 7/7] fix(ds/skeleton): derive section ids from titles so
 sidebar links resolve

---
 src/routes/ds.skeleton.tsx | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/src/routes/ds.skeleton.tsx b/src/routes/ds.skeleton.tsx
index e2a6990b0..bbb4e9c80 100644
--- a/src/routes/ds.skeleton.tsx
+++ b/src/routes/ds.skeleton.tsx
@@ -21,7 +21,6 @@ function SkeletonPage() {
       description="Placeholder blocks shown while content loads. Mirror the shape of what is coming so the layout does not shift when the real content arrives."
     >
       <DsSection
-        id="shapes"
         title="Skeleton"
         description={
           <>
@@ -53,7 +52,6 @@ function SkeletonPage() {
       </DsSection>
 
       <DsSection
-        id="surfaces"
         title="On any surface"
         description="The tint is an alpha overlay, not an opaque color, so it always reads lighter than whatever is behind it in dark mode and darker in light. An opaque surface token cannot do that: in dark mode it is lighter than the page but darker than a raised card, so it inverts as it moves between surfaces."
       >
@@ -74,7 +72,6 @@ function SkeletonPage() {
       </DsSection>
 
       <DsSection
-        id="grouping"
         title="Grouping and accessibility"
         description="Each block is aria-hidden, so a lone skeleton announces nothing. Wrap a loading region in SkeletonGroup to give screen readers one message for the whole area. The pulse is wrapped in motion-safe:, so it holds still under prefers-reduced-motion."
       >
@@ -103,7 +100,6 @@ function SkeletonPage() {
       </DsSection>
 
       <DsSection
-        id="matching"
         title="Match the real layout"
         description="Reuse the same grid, gap, and block heights as the content it stands in for. A skeleton that does not match the loaded UI trades a blank screen for a layout shift."
       >