From 45ab938d17349af66ad5a9b067f78f128b6c8c7a Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Sat, 27 Jun 2026 21:52:11 +0200
Subject: [PATCH 01/16] feat(registry): per-family landing pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a landing page per component family at /families/[category] — hero,
description, component count, and a card grid — generated from the existing
`category` enum (11 families; `ai` keeps its curated /ai landing via a new
`familyPath` helper). Wires internal links + SEO:

- /components family headings and the component-page family breadcrumb crumb
  now link to the family page.
- sitemap: 11 family routes (× locales).
- JSON-LD: new `collectionPageLd` (CollectionPage + ItemList) + BreadcrumbList.
- e2e: family landing renders, unknown family 404s, breadcrumb crumb navigates.

Closes #463

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 .../app/[locale]/components/[slug]/page.tsx   |  13 +-
 .../registry/app/[locale]/components/page.tsx |  10 +-
 .../app/[locale]/families/[category]/page.tsx | 189 ++++++++++++++++++
 apps/registry/app/sitemap.ts                  |  17 ++
 apps/registry/e2e/family-homepage.spec.ts     |  47 +++++
 apps/registry/lib/component-categories.ts     |  56 +++++-
 apps/registry/lib/jsonld.ts                   |  25 +++
 apps/registry/lib/sidebar-sections.ts         |   2 +
 8 files changed, 356 insertions(+), 3 deletions(-)
 create mode 100644 apps/registry/app/[locale]/families/[category]/page.tsx
 create mode 100644 apps/registry/e2e/family-homepage.spec.ts

diff --git a/apps/registry/app/[locale]/components/[slug]/page.tsx b/apps/registry/app/[locale]/components/[slug]/page.tsx
index bafd7017..2f834440 100644
--- a/apps/registry/app/[locale]/components/[slug]/page.tsx
+++ b/apps/registry/app/[locale]/components/[slug]/page.tsx
@@ -34,6 +34,7 @@ import { registry } from "@/lib/registry";
 import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
 import { oembedUrl, withRef } from "@/lib/share";
 import {
+  familyPath,
   getCategoryForComponent,
   getSidebarSections,
   groupedComponents,
@@ -242,7 +243,17 @@ export default async function ComponentPage(props: Props) {
                       href: localizePathname("/components", locale),
                       label: "Components",
                     },
-                    ...(familyGroup ? [{ label: familyGroup.label }] : []),
+                    ...(familyGroup
+                      ? [
+                          {
+                            href: localizePathname(
+                              familyPath(familyGroup.category),
+                              locale,
+                            ),
+                            label: familyGroup.label,
+                          },
+                        ]
+                      : []),
                     { label: displayTitle },
                   ]}
                 />
diff --git a/apps/registry/app/[locale]/components/page.tsx b/apps/registry/app/[locale]/components/page.tsx
index a309328b..80840c89 100644
--- a/apps/registry/app/[locale]/components/page.tsx
+++ b/apps/registry/app/[locale]/components/page.tsx
@@ -11,6 +11,7 @@ import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
 import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
 import {
   components,
+  familyPath,
   getSidebarSections,
   groupedComponents,
 } from "@/lib/sidebar-sections";
@@ -75,7 +76,14 @@ export default async function ComponentsPage({ params }: Props) {
 
           {groupedComponents.map((group) => (
             <section className="mb-12" key={group.category}>
-              <h2 className="text-2xl font-semibold mb-6">{group.label}</h2>
+              <h2 className="text-2xl font-semibold mb-6">
+                <Link
+                  className="hover:underline"
+                  href={localizePathname(familyPath(group.category), locale)}
+                >
+                  {group.label}
+                </Link>
+              </h2>
               <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
                 {group.items.map((component) => {
                   const meta = metadata_map[component.name];
diff --git a/apps/registry/app/[locale]/families/[category]/page.tsx b/apps/registry/app/[locale]/families/[category]/page.tsx
new file mode 100644
index 00000000..f1df0237
--- /dev/null
+++ b/apps/registry/app/[locale]/families/[category]/page.tsx
@@ -0,0 +1,189 @@
+import { Breadcrumb, Sidebar } from "@vllnt/ui";
+import type { Metadata } from "next";
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { setRequestLocale } from "next-intl/server";
+
+import { ComponentThumbnail } from "@/components/component-thumbnail";
+import { type Locale, routing } from "@/i18n/routing";
+import componentMetadata from "@/lib/component-metadata.json";
+import {
+  breadcrumbLd,
+  collectionPageLd,
+  jsonLdScriptAttributes,
+} from "@/lib/jsonld";
+import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
+import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
+import {
+  getCategoryDescription,
+  getSidebarSections,
+  groupedComponents,
+} from "@/lib/sidebar-sections";
+import type { ComponentCategory } from "@/types/registry";
+
+type Props = {
+  readonly params: Promise<{ category: string; locale: Locale }>;
+};
+
+const metadata_map = componentMetadata as Record<
+  string,
+  {
+    description: string;
+    stories: { id: string; name: string }[];
+    title: string;
+  }
+>;
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+
+/**
+ * Component families that get their own landing page. `ai` stays out — its
+ * curated landing lives at `/ai` (see `familyPath`).
+ */
+const familyGroups = groupedComponents.filter(
+  (group) => group.category !== "ai",
+);
+
+function findFamily(category: string) {
+  return familyGroups.find((group) => group.category === category);
+}
+
+export function generateStaticParams(): {
+  category: ComponentCategory;
+  locale: Locale;
+}[] {
+  return routing.locales.flatMap((locale) =>
+    familyGroups.map((group) => ({ category: group.category, locale })),
+  );
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { category, locale } = await params;
+  const group = findFamily(category);
+
+  if (!group) {
+    return {};
+  }
+
+  const pathname = `/families/${category}`;
+  const title = `${group.label} components`;
+  const description = getCategoryDescription(group.category);
+
+  return {
+    alternates: {
+      canonical: canonical(pathname, locale),
+      languages: languageAlternates(pathname),
+    },
+    description,
+    openGraph: generateOGMetadata(
+      { category: group.label, description, title, type: "page" },
+      { locale, pathname },
+    ),
+    title,
+    twitter: generateTwitterMetadata({
+      category: group.label,
+      description,
+      title,
+      type: "page",
+    }),
+  };
+}
+
+export default async function FamilyPage({ params }: Props) {
+  const { category, locale } = await params;
+  setRequestLocale(locale);
+
+  const group = findFamily(category);
+
+  if (!group) {
+    notFound();
+  }
+
+  const description = getCategoryDescription(group.category);
+  const pathname = `/families/${category}`;
+
+  return (
+    <>
+      <script
+        {...jsonLdScriptAttributes([
+          breadcrumbLd([
+            { name: "Home", url: SITE_URL },
+            { name: "Components", url: `${SITE_URL}/components` },
+            { name: group.label, url: `${SITE_URL}${pathname}` },
+          ]),
+          collectionPageLd({
+            description,
+            items: group.items.map((item) => ({
+              name: item.title,
+              url: `${SITE_URL}/components/${item.name}`,
+            })),
+            title: `${group.label} components`,
+            url: `${SITE_URL}${pathname}`,
+          }),
+        ])}
+      />
+      <Sidebar sections={getSidebarSections(group.category, locale)} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        <div className="container mx-auto px-4 py-16 lg:px-8">
+          <Breadcrumb
+            className="mb-4 text-muted-foreground"
+            items={[
+              { href: localizePathname("/", locale), label: "Home" },
+              {
+                href: localizePathname("/components", locale),
+                label: "Components",
+              },
+              { label: group.label },
+            ]}
+          />
+          <div className="mb-12">
+            <h1 className="text-4xl font-semibold mb-4">
+              {group.label} components
+            </h1>
+            {description ? (
+              <p className="text-muted-foreground text-lg">{description}</p>
+            ) : null}
+            <p className="text-muted-foreground text-sm mt-2">
+              {`${group.items.length} ${group.items.length === 1 ? "component" : "components"}`}
+            </p>
+          </div>
+
+          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+            {group.items.map((component) => {
+              const meta = metadata_map[component.name];
+              const storyCount = meta?.stories?.length ?? 0;
+
+              return (
+                <Link
+                  className="group flex flex-col rounded-lg border bg-card hover:border-foreground/20 transition-colors overflow-hidden"
+                  href={localizePathname(
+                    `/components/${component.name}`,
+                    locale,
+                  )}
+                  key={component.name}
+                >
+                  <ComponentThumbnail componentName={component.name} />
+                  <div className="flex flex-1 flex-col p-4">
+                    <h2 className="text-sm font-medium group-hover:text-foreground transition-colors">
+                      {component.title}
+                    </h2>
+                    {meta?.description ? (
+                      <p className="text-xs text-muted-foreground mt-1 line-clamp-2">
+                        {meta.description}
+                      </p>
+                    ) : null}
+                    {storyCount > 0 ? (
+                      <span className="mt-3 text-xs text-muted-foreground">
+                        {`${storyCount} ${storyCount === 1 ? "story" : "stories"}`}
+                      </span>
+                    ) : null}
+                  </div>
+                </Link>
+              );
+            })}
+          </div>
+        </div>
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/sitemap.ts b/apps/registry/app/sitemap.ts
index 8526e438..254eb022 100644
--- a/apps/registry/app/sitemap.ts
+++ b/apps/registry/app/sitemap.ts
@@ -5,6 +5,7 @@ import { registry, type RegistryComponent } from "@/lib/registry";
 import { canonical } from "@/lib/seo";
 
 import { getAiComponentSlugs } from "../lib/ai-seo";
+import { groupedComponents } from "../lib/component-categories";
 import { DOCS_PAGES, getDocsPath } from "../lib/docs-pages";
 import { getTemplatePath, TEMPLATES } from "../lib/templates";
 import { getUseCasePath, USE_CASES } from "../lib/use-cases";
@@ -78,6 +79,21 @@ function staticRoutes(lastModified: Date): MetadataRoute.Sitemap {
   return routes.flatMap((route) => localizedEntries(route, lastModified));
 }
 
+function familyRoutes(lastModified: Date): MetadataRoute.Sitemap {
+  return groupedComponents
+    .filter((group) => group.category !== "ai")
+    .flatMap((group) =>
+      localizedEntries(
+        {
+          changeFrequency: "weekly",
+          path: `/families/${group.category}`,
+          priority: 0.7,
+        },
+        lastModified,
+      ),
+    );
+}
+
 function docsRoutes(lastModified: Date): MetadataRoute.Sitemap {
   return DOCS_PAGES.flatMap((page) =>
     localizedEntries(
@@ -172,6 +188,7 @@ export default function sitemap(): MetadataRoute.Sitemap {
 
   return [
     ...staticRoutes(lastModified),
+    ...familyRoutes(lastModified),
     ...docsRoutes(lastModified),
     ...templateRoutes(lastModified),
     ...buildGuideRoutes(lastModified),
diff --git a/apps/registry/e2e/family-homepage.spec.ts b/apps/registry/e2e/family-homepage.spec.ts
new file mode 100644
index 00000000..1e73fe84
--- /dev/null
+++ b/apps/registry/e2e/family-homepage.spec.ts
@@ -0,0 +1,47 @@
+import { expect, test } from "@playwright/test";
+
+/**
+ * Component family homepages (component-family phase).
+ *
+ * Each non-AI category has a landing page at /families/[category] with a hero,
+ * a component grid, and a breadcrumb. The /components index family headings and
+ * the component-page family crumb both link here. The `ai` family is excluded —
+ * its curated landing lives at /ai.
+ */
+
+test.describe("component family homepage", () => {
+  test("renders a family landing with its components", async ({ page }) => {
+    await page.goto("/families/form");
+
+    await expect(
+      page.getByRole("heading", { level: 1, name: "Form components" }),
+    ).toBeVisible();
+
+    const breadcrumb = page.getByRole("navigation", { name: "Breadcrumb" });
+    await expect(breadcrumb.getByText("Form", { exact: true })).toBeVisible();
+
+    // The grid links into individual component pages.
+    await expect(
+      page.locator('main a[href*="/components/"]').first(),
+    ).toBeVisible();
+  });
+
+  test("an unknown family 404s", async ({ page }) => {
+    const response = await page.goto("/families/not-a-real-family");
+    expect(response?.status()).toBe(404);
+  });
+
+  test("the component-page family crumb links to the family page", async ({
+    page,
+  }) => {
+    await page.goto("/components/form");
+
+    const breadcrumb = page.getByRole("navigation", { name: "Breadcrumb" });
+    await breadcrumb.getByRole("link", { exact: true, name: "Form" }).click();
+
+    await expect(page).toHaveURL(/\/families\/form$/);
+    await expect(
+      page.getByRole("heading", { level: 1, name: "Form components" }),
+    ).toBeVisible();
+  });
+});
diff --git a/apps/registry/lib/component-categories.ts b/apps/registry/lib/component-categories.ts
index 95036d3c..569f5176 100644
--- a/apps/registry/lib/component-categories.ts
+++ b/apps/registry/lib/component-categories.ts
@@ -82,4 +82,58 @@ function getCategoryForComponent(
   return component?.category;
 }
 
-export { components, getCategoryForComponent, groupedComponents };
+const categoryDescriptions = new Map<ComponentCategory, string>([
+  [
+    "ai",
+    "Chat, agents, reasoning, and tool-call UI for building AI-native apps.",
+  ],
+  ["billing", "Pricing tables, plans, and transaction UI for billing flows."],
+  ["content", "Layout and content primitives for presenting rich information."],
+  ["core", "The foundational building blocks every interface starts from."],
+  ["data", "Tables, lists, and inputs for working with structured records."],
+  ["data-display", "Charts, metrics, and visualizations for surfacing data."],
+  [
+    "educational",
+    "Lesson, quiz, and knowledge-check UI for learning products.",
+  ],
+  ["form", "Inputs, controls, and validation for accessible forms."],
+  ["learning", "Tutorials, timelines, and progress UI for guided experiences."],
+  [
+    "navigation",
+    "Menus, breadcrumbs, and wayfinding for moving through an app.",
+  ],
+  ["overlay", "Dialogs, popovers, and sheets that layer above the page."],
+  [
+    "utility",
+    "Indicators, helpers, and small primitives that glue UIs together.",
+  ],
+]);
+
+/**
+ * Human-readable blurb for a component family, used on family landing pages.
+ *
+ * @param category - the component category
+ * @returns a one-line description, or an empty string when none exists
+ */
+function getCategoryDescription(category: ComponentCategory): string {
+  return categoryDescriptions.get(category) ?? "";
+}
+
+/**
+ * Canonical site path for a component family. The `ai` family resolves to the
+ * curated `/ai` landing; every other family resolves to `/families/<category>`.
+ *
+ * @param category - the component category
+ * @returns the locale-agnostic family path (pass through `localizePathname`)
+ */
+function familyPath(category: ComponentCategory): string {
+  return category === "ai" ? "/ai" : `/families/${category}`;
+}
+
+export {
+  components,
+  familyPath,
+  getCategoryDescription,
+  getCategoryForComponent,
+  groupedComponents,
+};
diff --git a/apps/registry/lib/jsonld.ts b/apps/registry/lib/jsonld.ts
index 9eda6de9..18bd593b 100644
--- a/apps/registry/lib/jsonld.ts
+++ b/apps/registry/lib/jsonld.ts
@@ -107,6 +107,31 @@ export function breadcrumbLd(
   };
 }
 
+export function collectionPageLd(page: {
+  readonly description: string;
+  readonly items: readonly { readonly name: string; readonly url: string }[];
+  readonly title: string;
+  readonly url: string;
+}): JsonLdNode {
+  return {
+    "@context": "https://schema.org",
+    "@type": "CollectionPage",
+    description: page.description,
+    mainEntity: {
+      "@type": "ItemList",
+      itemListElement: page.items.map((item, index) => ({
+        "@type": "ListItem",
+        name: item.name,
+        position: index + 1,
+        url: item.url,
+      })),
+      numberOfItems: page.items.length,
+    },
+    name: page.title,
+    url: page.url,
+  };
+}
+
 export function techArticleLd(article: {
   readonly description: string;
   readonly title: string;
diff --git a/apps/registry/lib/sidebar-sections.ts b/apps/registry/lib/sidebar-sections.ts
index dfba1002..71c2e1d1 100644
--- a/apps/registry/lib/sidebar-sections.ts
+++ b/apps/registry/lib/sidebar-sections.ts
@@ -53,6 +53,8 @@ export function getSidebarSections(
 
 export {
   components,
+  familyPath,
+  getCategoryDescription,
   getCategoryForComponent,
   groupedComponents,
 } from "@/lib/component-categories";

From 0db5dc95945a51208c752f2a443c8aad81792d80 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Sat, 27 Jun 2026 22:02:27 +0200
Subject: [PATCH 02/16] chore: re-trigger preview deploy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ntk preview check failed at the infra layer (deploy unrouted; all paths
404 including pre-existing routes) — not the diff. Empty commit to retry the
preview; all GitHub Actions checks were green.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF

From d40bd5c1bd9b7d44d0f1eadb17ee9d07adab7c82 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Sat, 27 Jun 2026 22:13:00 +0200
Subject: [PATCH 03/16] feat(ui,registry): link sidebar families to their
 homepage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clicking a family in the sidebar now navigates to its landing page instead
of only drilling in place. Family sections carry an optional `href`
(SidebarSection.href): FamilyList renders a link when present (button-drill
kept as a no-href fallback), the drilled family header links there too, and
auto-drill now matches the family route — so landing on /families/[category]
(or /ai) opens the sidebar straight into that family.

- @vllnt/ui Sidebar: SidebarSection.href + link rendering + family-route
  auto-drill (non-family sidebars unchanged).
- registry: getSidebarSections stamps each family's href via familyPath.
- e2e: family row navigates to the homepage and drills the sidebar.
- regenerate sidebar registry artifacts.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 apps/registry/e2e/sidebar-drilldown.spec.ts   | 16 ++--
 apps/registry/lib/sidebar-sections.ts         |  3 +-
 apps/registry/registry.json                   |  2 +-
 .../registry/default/sidebar/sidebar.tsx      | 87 +++++++++++++++----
 .../ui/src/components/sidebar/sidebar.tsx     | 87 +++++++++++++++----
 5 files changed, 147 insertions(+), 48 deletions(-)

diff --git a/apps/registry/e2e/sidebar-drilldown.spec.ts b/apps/registry/e2e/sidebar-drilldown.spec.ts
index 15af99a0..8bc92030 100644
--- a/apps/registry/e2e/sidebar-drilldown.spec.ts
+++ b/apps/registry/e2e/sidebar-drilldown.spec.ts
@@ -37,7 +37,7 @@ test.describe("component sidebar drill-down", () => {
     await expect(breadcrumb.getByText("Core", { exact: true })).toBeVisible();
   });
 
-  test("back returns to the family list; selecting a family drills in", async ({
+  test("selecting a family navigates to its homepage and drills the sidebar", async ({
     page,
   }) => {
     await page.goto("/components/button");
@@ -45,19 +45,19 @@ test.describe("component sidebar drill-down", () => {
 
     await sidebar.getByRole("button", { name: "All families" }).click();
 
-    // ROOT: families are listed; the previous family's items are gone.
-    await expect(sidebar.getByRole("button", { name: /^Form/ })).toBeVisible();
+    // ROOT: families are links now; the previous family's items are gone.
+    const formLink = sidebar.getByRole("link", { name: /^Form/ });
+    await expect(formLink).toBeVisible();
     await expect(
       sidebar.getByRole("link", { exact: true, name: "Button" }),
     ).toHaveCount(0);
 
-    // Drill into Form: the back control returns and the family's items render.
-    await sidebar.getByRole("button", { name: /^Form/ }).click();
+    // Clicking a family navigates to its homepage and auto-drills the sidebar.
+    await formLink.click();
+    await expect(page).toHaveURL(/\/families\/form$/);
     await expect(
       sidebar.getByRole("button", { name: "All families" }),
     ).toBeVisible();
-    await expect(
-      sidebar.locator('a[href$="/components/form"]'),
-    ).toBeVisible();
+    await expect(sidebar.locator('a[href$="/components/form"]')).toBeVisible();
   });
 });
diff --git a/apps/registry/lib/sidebar-sections.ts b/apps/registry/lib/sidebar-sections.ts
index 71c2e1d1..1f570e66 100644
--- a/apps/registry/lib/sidebar-sections.ts
+++ b/apps/registry/lib/sidebar-sections.ts
@@ -1,5 +1,5 @@
 import { type Locale, routing } from "@/i18n/routing";
-import { groupedComponents } from "@/lib/component-categories";
+import { familyPath, groupedComponents } from "@/lib/component-categories";
 import { DOCS_PAGES, getDocsPath } from "@/lib/docs-pages";
 import { localizePathname } from "@/lib/seo";
 import type { ComponentCategory } from "@/types/registry";
@@ -42,6 +42,7 @@ export function getSidebarSections(
     },
     ...groupedComponents.map((group) => ({
       family: true,
+      href: localizePathname(familyPath(group.category), locale),
       items: group.items.map((item) => ({
         href: localizePathname(`/components/${item.name}`, locale),
         title: item.title,
diff --git a/apps/registry/registry.json b/apps/registry/registry.json
index 0132e495..e3f9bf5e 100644
--- a/apps/registry/registry.json
+++ b/apps/registry/registry.json
@@ -6108,5 +6108,5 @@
     }
   ],
   "version": "0.3.0",
-  "generatedAt": "2026-06-27T19:33:13.346Z"
+  "generatedAt": "2026-06-27T20:12:37.143Z"
 }
diff --git a/apps/registry/registry/default/sidebar/sidebar.tsx b/apps/registry/registry/default/sidebar/sidebar.tsx
index ab46c24c..73f505b5 100644
--- a/apps/registry/registry/default/sidebar/sidebar.tsx
+++ b/apps/registry/registry/default/sidebar/sidebar.tsx
@@ -19,6 +19,7 @@ export type SidebarSection = {
   collapsible?: boolean;
   defaultOpen?: boolean;
   family?: boolean;
+  href?: string;
   items: SidebarItem[];
   title?: string;
 };
@@ -143,10 +144,29 @@ type FamilyNavProps = {
   sections: SidebarSection[];
 };
 
+const FAMILY_ROW_CLASS =
+  "flex w-full items-center justify-between px-3 py-1.5 rounded-md text-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground transition-colors";
+
+function FamilyRowLabel({ section }: { section: SidebarSection }) {
+  return (
+    <>
+      <span>{section.title}</span>
+      <span className="flex items-center gap-1 text-xs">
+        {section.items.length}
+        <ChevronRight className="size-3" />
+      </span>
+    </>
+  );
+}
+
 function FamilyList({
+  isMobile,
+  onNavigate,
   onOpen,
   sections,
 }: {
+  isMobile: boolean;
+  onNavigate: () => void;
   onOpen: (title: string) => void;
   sections: SidebarSection[];
 }) {
@@ -156,22 +176,33 @@ function FamilyList({
         Components
       </div>
       <div className="space-y-0.5">
-        {sections.map((section) => (
-          <button
-            className="flex w-full items-center justify-between px-3 py-1.5 rounded-md text-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground transition-colors"
-            key={section.title}
-            onClick={() => {
-              onOpen(section.title ?? "");
-            }}
-            type="button"
-          >
-            <span>{section.title}</span>
-            <span className="flex items-center gap-1 text-xs">
-              {section.items.length}
-              <ChevronRight className="size-3" />
-            </span>
-          </button>
-        ))}
+        {sections.map((section) =>
+          section.href ? (
+            <Link
+              className={FAMILY_ROW_CLASS}
+              href={section.href}
+              key={section.title}
+              onClick={() => {
+                if (isMobile) {
+                  onNavigate();
+                }
+              }}
+            >
+              <FamilyRowLabel section={section} />
+            </Link>
+          ) : (
+            <button
+              className={FAMILY_ROW_CLASS}
+              key={section.title}
+              onClick={() => {
+                onOpen(section.title ?? "");
+              }}
+              type="button"
+            >
+              <FamilyRowLabel section={section} />
+            </button>
+          ),
+        )}
       </div>
     </div>
   );
@@ -201,7 +232,21 @@ function FamilyItems({
         <span>All families</span>
       </button>
       <div className="flex items-center justify-between px-3 pb-1">
-        <span className="text-sm font-semibold">{section.title}</span>
+        {section.href ? (
+          <Link
+            className="text-sm font-semibold hover:underline"
+            href={section.href}
+            onClick={() => {
+              if (isMobile) {
+                onNavigate();
+              }
+            }}
+          >
+            {section.title}
+          </Link>
+        ) : (
+          <span className="text-sm font-semibold">{section.title}</span>
+        )}
         <span className="text-xs text-muted-foreground">
           {section.items.length}
         </span>
@@ -248,8 +293,10 @@ function FamilyNav({
   sections,
 }: FamilyNavProps) {
   const activeTitle =
-    sections.find((section) =>
-      section.items.some((item) => item.href === pathname),
+    sections.find(
+      (section) =>
+        section.href === pathname ||
+        section.items.some((item) => item.href === pathname),
     )?.title ?? null;
 
   const [routeKey, setRouteKey] = useState(pathname);
@@ -281,6 +328,8 @@ function FamilyNav({
 
   return (
     <FamilyList
+      isMobile={isMobile}
+      onNavigate={onNavigate}
       onOpen={(title) => {
         setOpenTitle(title);
       }}
diff --git a/packages/ui/src/components/sidebar/sidebar.tsx b/packages/ui/src/components/sidebar/sidebar.tsx
index ee32708c..eaae86f9 100644
--- a/packages/ui/src/components/sidebar/sidebar.tsx
+++ b/packages/ui/src/components/sidebar/sidebar.tsx
@@ -19,6 +19,7 @@ export type SidebarSection = {
   collapsible?: boolean;
   defaultOpen?: boolean;
   family?: boolean;
+  href?: string;
   items: SidebarItem[];
   title?: string;
 };
@@ -143,10 +144,29 @@ type FamilyNavProps = {
   sections: SidebarSection[];
 };
 
+const FAMILY_ROW_CLASS =
+  "flex w-full items-center justify-between px-3 py-1.5 rounded-md text-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground transition-colors";
+
+function FamilyRowLabel({ section }: { section: SidebarSection }) {
+  return (
+    <>
+      <span>{section.title}</span>
+      <span className="flex items-center gap-1 text-xs">
+        {section.items.length}
+        <ChevronRight className="size-3" />
+      </span>
+    </>
+  );
+}
+
 function FamilyList({
+  isMobile,
+  onNavigate,
   onOpen,
   sections,
 }: {
+  isMobile: boolean;
+  onNavigate: () => void;
   onOpen: (title: string) => void;
   sections: SidebarSection[];
 }) {
@@ -156,22 +176,33 @@ function FamilyList({
         Components
       </div>
       <div className="space-y-0.5">
-        {sections.map((section) => (
-          <button
-            className="flex w-full items-center justify-between px-3 py-1.5 rounded-md text-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground transition-colors"
-            key={section.title}
-            onClick={() => {
-              onOpen(section.title ?? "");
-            }}
-            type="button"
-          >
-            <span>{section.title}</span>
-            <span className="flex items-center gap-1 text-xs">
-              {section.items.length}
-              <ChevronRight className="size-3" />
-            </span>
-          </button>
-        ))}
+        {sections.map((section) =>
+          section.href ? (
+            <Link
+              className={FAMILY_ROW_CLASS}
+              href={section.href}
+              key={section.title}
+              onClick={() => {
+                if (isMobile) {
+                  onNavigate();
+                }
+              }}
+            >
+              <FamilyRowLabel section={section} />
+            </Link>
+          ) : (
+            <button
+              className={FAMILY_ROW_CLASS}
+              key={section.title}
+              onClick={() => {
+                onOpen(section.title ?? "");
+              }}
+              type="button"
+            >
+              <FamilyRowLabel section={section} />
+            </button>
+          ),
+        )}
       </div>
     </div>
   );
@@ -201,7 +232,21 @@ function FamilyItems({
         <span>All families</span>
       </button>
       <div className="flex items-center justify-between px-3 pb-1">
-        <span className="text-sm font-semibold">{section.title}</span>
+        {section.href ? (
+          <Link
+            className="text-sm font-semibold hover:underline"
+            href={section.href}
+            onClick={() => {
+              if (isMobile) {
+                onNavigate();
+              }
+            }}
+          >
+            {section.title}
+          </Link>
+        ) : (
+          <span className="text-sm font-semibold">{section.title}</span>
+        )}
         <span className="text-xs text-muted-foreground">
           {section.items.length}
         </span>
@@ -248,8 +293,10 @@ function FamilyNav({
   sections,
 }: FamilyNavProps) {
   const activeTitle =
-    sections.find((section) =>
-      section.items.some((item) => item.href === pathname),
+    sections.find(
+      (section) =>
+        section.href === pathname ||
+        section.items.some((item) => item.href === pathname),
     )?.title ?? null;
 
   const [routeKey, setRouteKey] = useState(pathname);
@@ -281,6 +328,8 @@ function FamilyNav({
 
   return (
     <FamilyList
+      isMobile={isMobile}
+      onNavigate={onNavigate}
       onOpen={(title) => {
         setOpenTitle(title);
       }}

From d179b5304d1b642af762913621f4cae9eebeaa90 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Sun, 28 Jun 2026 15:56:44 +0200
Subject: [PATCH 04/16] feat(registry): inline previews for the remaining 167
 components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The gallery ComponentPreview switch only covered 142 components; the other
167 (all of data-display, ai, billing, educational + most of the rest) fell
through to the text PlaceholderPreview — so family pages like /families/data-display
showed no real previews. Add a bespoke inline preview per component (same
pattern as the existing 142), authored against each component's real API.

- 307 components now render a live inline preview; 2 (scroll-progress,
  heat-overlay) use the existing SimplePreview fallback (viewport-fixed /
  TS children-typing quirk). 0 placeholders remain.
- Deterministic demo data only (no Math.random / Date.now / argless Date).
- App-internal component — no registry regeneration.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 .../component-preview/component-preview.tsx   | 4018 +++++++++++++++--
 1 file changed, 3764 insertions(+), 254 deletions(-)

diff --git a/apps/registry/components/component-preview/component-preview.tsx b/apps/registry/components/component-preview/component-preview.tsx
index 70dc212b..cae19841 100644
--- a/apps/registry/components/component-preview/component-preview.tsx
+++ b/apps/registry/components/component-preview/component-preview.tsx
@@ -9,6 +9,30 @@ import {
   AccordionTrigger,
   ActivityHeatmap,
   ActivityLog,
+  AgentActivity,
+  AgentStep,
+  AgentStepDetail,
+  AgentStepDuration,
+  AgentStepTitle,
+  AIArtifact,
+  AIArtifactContent,
+  AIArtifactCopyButton,
+  AIArtifactDownloadButton,
+  AIArtifactToolbar,
+  AIArtifactVersion,
+  AIArtifactVersions,
+  AIChatInput,
+  AIMessageBubble,
+  AISidebar,
+  AISidebarClose,
+  AISidebarContent,
+  AISidebarFooter,
+  AISidebarHeader,
+  AISidebarProvider,
+  AISidebarTitle,
+  AISourceCitation,
+  AIStreamingText,
+  AIToolCallDisplay,
   Alert,
   AlertDescription,
   AlertDialog,
@@ -20,23 +44,42 @@ import {
   AlertDialogHeader,
   AlertDialogTitle,
   AlertDialogTrigger,
+  AlertPulse,
   AlertTitle,
+  AnimatedBeam,
+  AnimatedGridPattern,
+  AnimatedList,
+  AnimatedTabs,
+  AnimatedTestimonials,
   AnimatedText,
+  AnimatedTooltip,
+  Annotation,
   AspectRatio,
+  AutoReload,
   Avatar,
   AvatarFallback,
   AvatarGroup,
   AvatarImage,
   Badge,
+  Banner,
+  BannerAction,
+  BentoCard,
+  BentoGrid,
+  BlurReveal,
   BorderBeam,
+  BottomActivityStrip,
+  BottomBar,
   Breadcrumb,
   Button,
+  ButtonGroup,
   Calendar,
   Callout,
+  CandlestickChart,
   CanvasView,
   Card,
   CardContent,
   CardDescription,
+  CardFlip,
   CardFooter,
   CardHeader,
   CardTitle,
@@ -46,13 +89,24 @@ import {
   CarouselNext,
   CarouselPrevious,
   CategoryFilter,
+  ChainOfThought,
+  ChatDockSection,
   Checkbox,
+  CheckboxGroup,
+  CheckboxGroupItem,
   Checklist,
+  ChoroplethLegend,
+  ChoroplethMap,
+  ChoroplethTooltip,
+  ChronoEvent,
+  ChronologicalTimeline,
+  CivilizationCard,
   CodeBlock,
   CodePlayground,
   Collapsible,
   CollapsibleContent,
   CollapsibleTrigger,
+  ColorPicker,
   Combobox,
   CommandDialog,
   CommandEmpty,
@@ -60,21 +114,36 @@ import {
   CommandInput,
   CommandItem,
   CommandList,
+  CommentPin,
   CommonMistake,
   Comparison,
   ContentCard,
+  ContextLens,
   ContextMenu,
   ContextMenuContent,
   ContextMenuItem,
   ContextMenuTrigger,
+  ContributionGraph,
+  ConversationHeader,
+  ConversationMessages,
+  ConversationThread,
+  ConversationTitle,
+  CookieConsent,
+  CopyButton,
   CountdownTimer,
   CreditBadge,
+  Curriculum,
+  CurriculumLesson,
+  CurriculumModule,
+  Cursor,
   DataList,
   DataListItem,
   DataListLabel,
   DataListValue,
   DataTable,
+  DateField,
   DatePicker,
+  DateRangePicker,
   Dialog,
   DialogContent,
   DialogDescription,
@@ -82,6 +151,10 @@ import {
   DialogHeader,
   DialogTitle,
   DialogTrigger,
+  Dock,
+  DockIcon,
+  DocumentSiblingNav,
+  DotPattern,
   Drawer,
   DrawerClose,
   DrawerContent,
@@ -94,33 +167,102 @@ import {
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuTrigger,
+  EmptyState,
+  EraColumn,
+  EraComparison,
+  EraDomain,
+  EraFigure,
+  EraHighlight,
   Exercise,
+  ExpandableCards,
   FAQ,
   FAQItem,
+  Field,
+  FieldControl,
+  FieldDescription,
+  FieldLabel,
+  Fieldset,
+  FieldsetContent,
+  FieldsetLegend,
   FileUpload,
   Flashcard,
   FloatingActionButton,
+  FloatingNavbar,
+  FloatingToolbar,
+  FlowDiagram,
+  FollowMode,
   Form,
   FormControl,
   FormDescription,
   FormItem,
   FormLabel,
   FormMessage,
+  GanttChart,
+  GaugeChart,
+  GeographyQuizMap,
+  GeographyQuizMapPrompt,
+  GeographyQuizMapScore,
+  GlassCard,
+  GlassPanel,
+  GlassProgress,
+  Globe3D,
+  GlobeMarker,
   Glossary,
+  Grid,
+  H3,
+  HandoffBeacon,
+  HeatMapOverlay,
+  Highlight,
+  HistoricalFigureCard,
+  HistoricTimeline,
   HorizontalScrollRow,
   HoverCard,
   HoverCardContent,
   HoverCardTrigger,
+  InfinitePlane,
+  InlineCode,
   InlineInput,
   Input,
+  InputGroup,
+  InputGroupAddon,
+  InputGroupInput,
   InputOTP,
   InputOTPGroup,
   InputOTPSlot,
+  InteractiveTimeline,
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemDescription,
+  ItemTitle,
+  JarvisDock,
+  Kbd,
   KeyboardShortcutsHelp,
   KeyConcept,
+  KnowledgeCheck,
+  Label,
   LangProvider,
   LearningObjectives,
+  Link,
+  LiquidGlass,
+  ListBox,
+  ListBoxItem,
+  LiveCursor,
   LiveFeed,
+  Magnetic,
+  MagneticButton,
+  Map2D,
+  MapControls,
+  MapLayer,
+  MapMarker,
+  MapTimeline,
+  MapTimelineControls,
+  MapTimelineEvent,
+  MapTimelineLayer,
+  MapTimelinePlayButton,
+  MapTimelineSlider,
+  MapZoomIn,
+  MapZoomOut,
   MarketTreemap,
   Marquee,
   Menubar,
@@ -129,44 +271,108 @@ import {
   MenubarMenu,
   MenubarSeparator,
   MenubarTrigger,
+  Meteors,
+  Meter,
+  MetricCluster,
   MetricGauge,
+  ModelComparison,
+  ModelComparisonColumn,
+  ModelComparisonMeta,
   MultiSelect,
+  MultiSelectLasso,
+  Muted,
+  NativeSelect,
   NavigationMenu,
   NavigationMenuContent,
   NavigationMenuItem,
   NavigationMenuLink,
   NavigationMenuList,
   NavigationMenuTrigger,
+  NewsletterSignup,
   NumberInput,
   NumberTicker,
+  ObjectInspector,
   OrderBook,
+  OverviewBoard,
+  P,
   Pagination,
+  Panel,
+  PanelBody,
+  PanelDescription,
+  PanelFooter,
+  PanelHeader,
+  PanelTitle,
+  ParallelTimeline,
+  Particles,
   PasswordInput,
+  PhoneInput,
+  PieChart,
+  PlanBadge,
+  PlaybackGhost,
+  PolicyDeliveryPanel,
   Popover,
   PopoverContent,
   PopoverTrigger,
   Prerequisites,
+  PresenceStack,
+  PresenceSyncIndicator,
+  PricingPlan,
+  PricingTable,
+  PrimarySourceAnnotation,
+  PrimarySourceAnnotations,
+  PrimarySourceToolbar,
+  PrimarySourceViewer,
+  PrimarySourceZoomIn,
+  PrimarySourceZoomOut,
   ProfileSection,
   ProgressBar,
+  ProgressiveBlur,
+  ProgressTracker,
+  ProgressTrackerModule,
+  ProgressTrackerModules,
+  ProgressTrackerOverview,
+  ProgressTrackerStat,
+  ProgressTrackerStats,
+  PromptInput,
+  PromptTemplates,
+  PropertySection,
   ProTip,
+  QrCode,
   Quiz,
+  RadarChart,
   RadioGroup,
   RadioGroupItem,
+  RangeCalendar,
+  Rating,
+  Reasoning,
+  RelationshipInspector,
   ResizableHandle,
   ResizablePanel,
   ResizablePanelGroup,
+  RevealText,
+  RoleBadge,
+  RouteMap,
+  RoutingAssignmentPanel,
+  RunTimeline,
+  RuntimeOverviewPanel,
+  SankeyChart,
   ScopeSelector,
+  ScrambleText,
   ScrollArea,
   SearchBar,
+  SearchField,
   SegmentedControl,
   SegmentedControlItem,
   Select,
   SelectContent,
+  SelectionHalo,
+  SelectionPresence,
   SelectItem,
   SelectTrigger,
   SelectValue,
   Separator,
   SeverityBadge,
+  ShareDialog,
   ShareSection,
   Sheet,
   SheetClose,
@@ -176,19 +382,35 @@ import {
   SheetHeader,
   SheetTitle,
   SheetTrigger,
+  ShimmerButton,
+  ShimmerText,
+  ShineBorder,
+  ShinyButton,
   Sidebar,
   SidebarProvider,
   SidebarToggle,
   Skeleton,
   Slider,
+  SnapGuides,
+  Sparkles,
+  SparklineGrid,
   Spinner,
+  SpinningText,
+  SpotlightCard,
   StatCard,
+  StateBadgeOverlay,
   StatusBoard,
   StatusIndicator,
   Step,
   StepByStep,
   StepNavigation,
+  Stepper,
+  StickyMetric,
+  StoryMap,
+  StoryMapChapter,
+  SubscriptionCard,
   Summary,
+  Switch,
   Table,
   TableBody,
   TableCell,
@@ -200,12 +422,29 @@ import {
   TabsContent,
   TabsList,
   TabsTrigger,
+  TagGroup,
+  TagGroupItem,
   TagsInput,
   Terminal,
+  TextAnimate,
   Textarea,
+  TextField,
+  TextReveal,
+  TextShimmer,
+  ThemePresetProvider,
   ThemeProvider,
+  ThemeSwitcher,
   ThemeToggle,
   ThinkingBlock,
+  ThreadBubble,
+  ThresholdRing,
+  TickerTape,
+  TiltCard,
+  TimeField,
+  Timeline,
+  TimelineItem,
+  TimelineScrubber,
+  TimePicker,
   TLDRSection,
   Toast,
   ToastDescription,
@@ -213,23 +452,37 @@ import {
   Toggle,
   ToggleGroup,
   ToggleGroupItem,
+  Toolbar,
+  ToolbarSeparator,
   Tooltip,
   TooltipContent,
   TooltipProvider,
   TooltipTrigger,
+  Tour,
+  TransactionList,
+  TransactionListPinned,
+  TransactionListSubscriptionRow,
+  TreeView,
+  TruncatedText,
   TutorialCard,
+  Typewriter,
   UsageBreakdown,
   VideoEmbed,
+  ViewportBookmarks,
   ViewSwitcher,
   WalletCard,
   Watchlist,
+  WorldBreadcrumbs,
   WorldClockBar,
 } from "@vllnt/ui";
 import {
+  AlertTriangle,
   Bold,
   ChevronsUpDown,
+  Inbox,
   Italic,
   Plus,
+  Search,
   Terminal as TerminalIcon,
   Underline,
 } from "lucide-react";
@@ -255,6 +508,10 @@ function SimplePreview({ description }: { description: string }) {
 
 // Graceful fallback for components without a dedicated preview: a muted wordmark
 // tile derived from the component slug, so gallery cards still look intentional.
+function noop() {
+  // no-op handler for static gallery previews
+}
+
 function PlaceholderPreview({ componentName }: { componentName: string }) {
   const label = componentName
     .split("-")
@@ -2177,260 +2434,3177 @@ function SpinnerPreview() {
   );
 }
 
-// eslint-disable-next-line max-lines-per-function -- Switch statement mapping all components
-export function ComponentPreview({ componentName }: ComponentPreviewProps) {
-  switch (componentName) {
-    case "accordion":
-      return <AccordionPreview />;
-    case "activity-heatmap":
-      return <ActivityHeatmapPreview />;
-    case "activity-log":
-      return <ActivityLogPreview />;
-    case "alert":
-      return <AlertPreview />;
-    case "alert-dialog":
-      return <AlertDialogPreview />;
-    case "animated-text":
-      return <AnimatedTextPreview />;
-    case "area-chart":
-      return <AreaChartPreview />;
-    case "aspect-ratio":
-      return <AspectRatioPreview />;
-    case "avatar":
-      return <AvatarPreview />;
-    case "avatar-group":
-      return <AvatarGroupPreview />;
-    case "border-beam":
-      return <BorderBeamPreview />;
-    case "badge":
-      return <BadgePreview />;
-    case "bar-chart":
-      return <BarChartPreview />;
-    case "blog-card":
-      return <BlogCardPreview />;
-    case "breadcrumb":
-      return <BreadcrumbPreview />;
-    case "button":
-      return <ButtonPreview />;
-    case "anchor-port":
-      return (
-        <SimplePreview description="Connection port primitive for object graph cards and edges." />
-      );
-    case "callout":
-      return <CalloutPreview />;
-    case "calendar":
-      return <CalendarPreview />;
-    case "combobox":
-      return <ComboboxPreview />;
-    case "card":
-      return <CardPreview />;
-    case "data-list":
-      return <DataListPreview />;
-    case "data-table":
-      return <DataTablePreview />;
-    case "carousel":
-      return <CarouselPreview />;
-    case "canvas-shell":
-      return (
-        <SimplePreview description="Overlay shell for infinite-canvas workspaces with floating chrome regions." />
-      );
-    case "canvas-view":
-      return <CanvasViewPreview />;
-    case "connector-edge":
-      return (
-        <SimplePreview description="Curved connector edge for linking spatial objects on the canvas." />
-      );
-    case "category-filter":
-      return <CategoryFilterPreview />;
-    case "checkbox":
-      return <CheckboxPreview />;
-    case "collapsible":
-      return <CollapsiblePreview />;
-    case "checklist":
-      return <ChecklistPreview />;
-    case "code-block":
-      return <CodeBlockPreview />;
-    case "code-playground":
-      return <CodePlaygroundPreview />;
-    case "command":
-      return <CommandPreview />;
-    case "comparison":
-      return <ComparisonPreview />;
-    case "completion-dialog":
-      return (
-        <SimplePreview description="A dialog for displaying completion status with confetti animation." />
-      );
-    case "content-intro":
-      return (
-        <SimplePreview description="An introduction section with progress tracking and action buttons." />
-      );
-    case "context-menu":
-      return <ContextMenuPreview />;
-    case "countdown-timer":
-      return <CountdownTimerPreview />;
-    case "credit-badge":
-      return <CreditBadgePreview />;
-    case "dialog":
-      return <DialogPreview />;
-    case "drawer":
-      return <DrawerPreview />;
-    case "dropdown-menu":
-      return <DropdownMenuPreview />;
-    case "exercise":
-      return <ExercisePreview />;
-    case "faq":
-      return <FAQPreview />;
-    case "flashcard":
-      return <FlashcardPreview />;
-    case "edge-label":
-      return (
-        <SimplePreview description="Compact edge annotation badge used inside connector paths." />
-      );
-    case "file-upload":
-      return <FileUploadPreview />;
-    case "filter-bar":
-      return (
-        <SimplePreview description="A filter bar with search, sort, and filter controls." />
-      );
-    case "floating-action-button":
-      return <FloatingActionButtonPreview />;
-    case "form":
-      return <FormPreview />;
-    case "group-hull":
-      return (
-        <SimplePreview description="Dashed grouping surface for related spatial objects." />
-      );
-    case "horizontal-scroll-row":
-      return <HorizontalScrollRowPreview />;
-    case "hover-card":
-      return <HoverCardPreview />;
-    case "inline-input":
-      return <InlineInputPreview />;
-    case "input":
-      return <InputPreview />;
-    case "input-otp":
-      return <InputOTPPreview />;
-    case "date-picker":
-      return <DatePickerPreview />;
-    case "key-concept":
-      return <KeyConceptPreview />;
-    case "keyboard-shortcuts-help":
-      return <KeyboardShortcutsHelpPreview />;
-    case "left-rail":
-      return (
-        <SimplePreview description="Primary left-side rail for workspace navigation and context controls." />
-      );
-    case "lang-provider":
-      return <LangProviderPreview />;
-    case "learning-objectives":
-      return <LearningObjectivesPreview />;
-    case "line-chart":
-      return <LineChartPreview />;
-    case "marquee":
-      return <MarqueePreview />;
-    case "live-feed":
-      return <LiveFeedPreview />;
-    case "market-treemap":
-      return <MarketTreemapPreview />;
-    case "mdx-content":
-      return <MDXContentPreview />;
-    case "menubar":
-      return <MenubarPreview />;
-    case "mini-map-panel":
-      return (
-        <SimplePreview description="Viewport overview panel showing camera position within the world surface." />
-      );
-    case "metric-gauge":
-      return <MetricGaugePreview />;
-    case "model-selector":
-      return (
-        <SimplePreview description="A dialog for selecting AI models with search and filtering." />
-      );
-    case "multi-select":
-      return <MultiSelectPreview />;
-    case "tags-input":
-      return <TagsInputPreview />;
-    case "segmented-control":
-      return <SegmentedControlPreview />;
-    case "navbar-saas":
-      return (
-        <SimplePreview description="A responsive navigation bar for SaaS applications." />
-      );
-    case "navigation-menu":
-      return <NavigationMenuPreview />;
-    case "number-input":
-      return <NumberInputPreview />;
-    case "number-ticker":
-      return <NumberTickerPreview />;
-    case "object-card":
-      return (
-        <SimplePreview description="Object card primitive for spatial entities with metrics, actions, and ports." />
-      );
-    case "object-handle":
-      return (
-        <SimplePreview description="Drag/move handle affordance for manipulating canvas objects." />
-      );
-    case "order-book":
-      return <OrderBookPreview />;
-    case "pagination":
-      return <PaginationPreview />;
-    case "password-input":
-      return <PasswordInputPreview />;
-    case "popover":
-      return <PopoverPreview />;
-    case "pro-tip":
-      return <ProTipPreview />;
-    case "profile-section":
-      return <ProfileSectionPreview />;
-    case "progress-bar":
-      return <ProgressBarPreview />;
-    case "progress-card":
-      return (
-        <SimplePreview description="A card component with progress tracking." />
-      );
-    case "quiz":
-      return <QuizPreview />;
-    case "radio-group":
-      return <RadioGroupPreview />;
-    case "resizable":
-      return <ResizablePreview />;
-    case "right-dock":
-      return (
-        <SimplePreview description="Right-side dock for inspector, agent, or activity panels in the workspace shell." />
-      );
-    case "scroll-area":
-      return <ScrollAreaPreview />;
-    case "search-bar":
-      return <SearchBarPreview />;
-    case "search-dialog":
-      return (
-        <SimplePreview description="A command palette style search dialog." />
-      );
-    case "scope-selector":
-      return <ScopeSelectorPreview />;
-    case "select":
-      return <SelectPreview />;
-    case "separator":
-      return <SeparatorPreview />;
-    case "severity-badge":
-      return <SeverityBadgePreview />;
-    case "share-section":
-      return <ShareSectionPreview />;
-    case "sheet":
-      return <SheetPreview />;
-    case "sidebar":
-      return <SidebarPreview />;
-    case "skeleton":
-      return <SkeletonPreview />;
-    case "slider":
-      return <SliderPreview />;
-    case "spinner":
-      return <SpinnerPreview />;
-    case "stat-card":
-      return <StatCardPreview />;
-    case "status-board":
-      return <StatusBoardPreview />;
-    case "sidebar-provider":
+const PRIMARY_SOURCE_PREVIEW_IMAGE = `data:image/svg+xml,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" width="320" height="200"><rect width="320" height="200" fill="#efe7d3"/><g fill="#9c8e6a"><rect x="24" y="26" width="190" height="10" rx="3"/><rect x="24" y="52" width="272" height="6" rx="3"/><rect x="24" y="68" width="272" height="6" rx="3"/><rect x="24" y="84" width="236" height="6" rx="3"/><rect x="24" y="108" width="272" height="6" rx="3"/><rect x="24" y="124" width="252" height="6" rx="3"/></g><circle cx="252" cy="162" r="22" fill="#b23b3b"/></svg>',
+)}`;
+
+function AnimatedBeamPreview() {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const fromRef = React.useRef<HTMLDivElement>(null);
+  const toRef = React.useRef<HTMLDivElement>(null);
+  return (
+    <div
+      className="relative flex h-28 w-72 items-center justify-between rounded-xl border bg-card p-6"
+      ref={containerRef}
+    >
+      <div
+        className="z-10 flex size-10 items-center justify-center rounded-full border bg-background text-sm"
+        ref={fromRef}
+      >
+        A
+      </div>
+      <div
+        className="z-10 flex size-10 items-center justify-center rounded-full border bg-background text-sm"
+        ref={toRef}
+      >
+        B
+      </div>
+      <AnimatedBeam
+        containerRef={containerRef}
+        fromRef={fromRef}
+        toRef={toRef}
+      />
+    </div>
+  );
+}
+
+function ChoroplethMapPreview() {
+  return (
+    <div className="w-full max-w-[280px]">
+      <ChoroplethMap
+        data={{ DE: 4082, ES: 1397, FR: 2937, IT: 2107 }}
+        regions={[
+          {
+            coordinates: [
+              [-5, 51],
+              [10, 51],
+              [10, 41],
+              [-5, 41],
+              [-5, 51],
+            ],
+            id: "FR",
+            name: "France",
+          },
+          {
+            coordinates: [
+              [5, 55],
+              [15, 55],
+              [15, 47],
+              [5, 47],
+              [5, 55],
+            ],
+            id: "DE",
+            name: "Germany",
+          },
+          {
+            coordinates: [
+              [6, 47],
+              [18, 47],
+              [18, 37],
+              [6, 37],
+              [6, 47],
+            ],
+            id: "IT",
+            name: "Italy",
+          },
+          {
+            coordinates: [
+              [-9, 44],
+              [3, 44],
+              [3, 36],
+              [-9, 36],
+              [-9, 44],
+            ],
+            id: "ES",
+            name: "Spain",
+          },
+        ]}
+      >
+        <ChoroplethTooltip />
+        <ChoroplethLegend title="GDP (B USD)" />
+      </ChoroplethMap>
+    </div>
+  );
+}
+
+function ChronologicalTimelinePreview() {
+  return (
+    <div className="w-full max-w-md">
+      <ChronologicalTimeline title="The Space Race">
+        <ChronoEvent
+          date="1957"
+          id="sputnik"
+          subtitle="First artificial satellite"
+          title="Sputnik 1"
+        />
+        <ChronoEvent
+          date="1961"
+          id="vostok"
+          subtitle="First human in space"
+          title="Vostok 1"
+        />
+        <ChronoEvent
+          date="1969"
+          featured
+          id="apollo"
+          subtitle="First crewed Moon landing"
+          title="Apollo 11"
+        />
+      </ChronologicalTimeline>
+    </div>
+  );
+}
+
+function FloatingToolbarPreview() {
+  return (
+    <div className="relative h-[160px] w-full max-w-md rounded-2xl border bg-muted/30">
+      <FloatingToolbar
+        actions={[
+          {
+            id: "rename",
+            label: "Rename",
+            onActivate: noop,
+            variant: "primary",
+          },
+          { id: "duplicate", label: "Duplicate", onActivate: noop },
+          {
+            id: "delete",
+            label: "Delete",
+            onActivate: noop,
+            variant: "destructive",
+          },
+        ]}
+        x={90}
+        y={110}
+      />
+    </div>
+  );
+}
+
+function FollowModePreview() {
+  return (
+    <div className="h-[160px] w-full max-w-md">
+      <FollowMode color="emerald" name="Sam">
+        <div className="flex h-full w-full items-center justify-center bg-muted/20 text-sm text-muted-foreground">
+          Followed canvas content
+        </div>
+      </FollowMode>
+    </div>
+  );
+}
+
+function GeographyQuizMapPreview() {
+  return (
+    <div className="w-full max-w-[280px]">
+      <GeographyQuizMap
+        questions={[
+          { answerRegionId: "FR", id: "q1", prompt: "Click on France" },
+          { answerRegionId: "DE", id: "q2", prompt: "Click on Germany" },
+        ]}
+        regions={[
+          {
+            coordinates: [
+              [-5, 51],
+              [10, 51],
+              [10, 41],
+              [-5, 41],
+              [-5, 51],
+            ],
+            id: "FR",
+            name: "France",
+          },
+          {
+            coordinates: [
+              [5, 55],
+              [15, 55],
+              [15, 47],
+              [5, 47],
+              [5, 55],
+            ],
+            id: "DE",
+            name: "Germany",
+          },
+          {
+            coordinates: [
+              [6, 47],
+              [18, 47],
+              [18, 37],
+              [6, 37],
+              [6, 47],
+            ],
+            id: "IT",
+            name: "Italy",
+          },
+        ]}
+      >
+        <GeographyQuizMapPrompt />
+        <GeographyQuizMapScore />
+      </GeographyQuizMap>
+    </div>
+  );
+}
+
+function GlassProgressPreview() {
+  return (
+    <div className="w-full max-w-xs rounded-xl bg-gradient-to-br from-primary/30 to-primary/10 p-8">
+      <GlassProgress value={60} />
+    </div>
+  );
+}
+
+function Globe3dPreview() {
+  return (
+    <div className="w-full max-w-[220px]">
+      <Globe3D autoRotate={false} initialPosition={{ lat: 30, lng: -30 }}>
+        <GlobeMarker
+          color="blue"
+          id="paris"
+          label="Paris"
+          lat={48.85}
+          lng={2.35}
+        />
+        <GlobeMarker
+          color="red"
+          id="ny"
+          label="New York"
+          lat={40.71}
+          lng={-74}
+        />
+        <GlobeMarker
+          color="emerald"
+          id="rio"
+          label="Rio"
+          lat={-22.9}
+          lng={-43.2}
+        />
+      </Globe3D>
+    </div>
+  );
+}
+
+function HandoffBeaconPreview() {
+  return (
+    <div className="relative h-[160px] w-full max-w-md rounded-2xl border bg-muted/30">
+      <HandoffBeacon
+        level="info"
+        message="Heads up"
+        source="Sam"
+        x={70}
+        y={60}
+      />
+      <HandoffBeacon
+        level="urgent"
+        message="Schema mismatch"
+        source="Riley"
+        x={250}
+        y={90}
+      />
+    </div>
+  );
+}
+
+function HeatMapOverlayPreview() {
+  return (
+    <div className="w-full max-w-[280px]">
+      <HeatMapOverlay
+        data={[
+          { id: "ny", lat: 40.7, lng: -74, weight: 0.95 },
+          { id: "ldn", lat: 51.5, lng: -0.13, weight: 0.7 },
+          { id: "tok", lat: 35.7, lng: 139.7, weight: 0.85 },
+          { id: "syd", lat: -33.9, lng: 151.2, weight: 0.5 },
+          { id: "rio", lat: -22.9, lng: -43.2, weight: 0.45 },
+        ]}
+        radius={50}
+      />
+    </div>
+  );
+}
+
+function HistoricTimelinePreview() {
+  return (
+    <div className="w-full max-w-xl">
+      <HistoricTimeline
+        categories={[
+          { color: "blue", id: "science", label: "Science" },
+          { color: "red", id: "conflict", label: "Conflict" },
+        ]}
+        endYear={2025}
+        eras={[
+          {
+            color: "amber",
+            endYear: 476,
+            id: "ancient",
+            name: "Ancient",
+            startYear: -500,
+          },
+          {
+            color: "blue",
+            endYear: 2025,
+            id: "modern",
+            name: "Modern",
+            startYear: 476,
+          },
+        ]}
+        events={[
+          {
+            category: "conflict",
+            id: "fall-rome",
+            title: "Fall of Rome",
+            year: 476,
+          },
+          {
+            category: "science",
+            id: "press",
+            title: "Printing press",
+            year: 1450,
+          },
+          {
+            category: "science",
+            id: "moon",
+            title: "Moon landing",
+            year: 1969,
+          },
+        ]}
+        startYear={-500}
+      />
+    </div>
+  );
+}
+
+function InteractiveTimelinePreview() {
+  return (
+    <div className="w-full max-w-md">
+      <InteractiveTimeline
+        endDate={new Date("2025-01-01T00:00:00.000Z")}
+        events={[
+          {
+            id: "v1",
+            startDate: new Date("2024-03-01T00:00:00.000Z"),
+            title: "v1.0",
+            track: "release",
+          },
+          {
+            id: "v2",
+            startDate: new Date("2024-09-15T00:00:00.000Z"),
+            title: "v2.0",
+            track: "release",
+          },
+          {
+            endDate: new Date("2024-08-01T00:00:00.000Z"),
+            id: "search",
+            startDate: new Date("2024-06-01T00:00:00.000Z"),
+            title: "Search",
+            track: "feature",
+          },
+        ]}
+        startDate={new Date("2024-01-01T00:00:00.000Z")}
+        tracks={[
+          { color: "blue", id: "release", label: "Releases" },
+          { color: "emerald", id: "feature", label: "Features" },
+        ]}
+      />
+    </div>
+  );
+}
+
+function Map2dPreview() {
+  return (
+    <div className="w-full max-w-[300px]">
+      <Map2D center={[2, 48]} zoom={2}>
+        <MapLayer
+          data={[
+            {
+              coordinates: [
+                [-5, 51],
+                [10, 51],
+                [10, 41],
+                [-5, 41],
+                [-5, 51],
+              ],
+              id: "france-bbox",
+              type: "polygon",
+            },
+          ]}
+        />
+        <MapMarker popup="Paris" position={[2.35, 48.85]} />
+        <MapMarker popup="London" position={[-0.13, 51.5]} />
+        <MapMarker popup="Berlin" position={[13.4, 52.52]} />
+        <MapControls>
+          <MapZoomIn />
+          <MapZoomOut />
+        </MapControls>
+      </Map2D>
+    </div>
+  );
+}
+
+function MapTimelinePreview() {
+  return (
+    <div className="w-full max-w-[320px]">
+      <MapTimeline endYear={2025} initialYear={400} startYear={-500}>
+        <MapTimelineLayer
+          color="red"
+          endYear={476}
+          geometry={{
+            polygon: [
+              [-9, 56],
+              [10, 56],
+              [40, 50],
+              [40, 30],
+              [10, 30],
+              [-9, 36],
+              [-9, 56],
+            ],
+            type: "polygon",
+          }}
+          id="rome"
+          label="Roman Empire"
+          startYear={-27}
+        />
+        <MapTimelineLayer
+          color="purple"
+          endYear={1453}
+          geometry={{
+            polygon: [
+              [10, 45],
+              [42, 45],
+              [42, 30],
+              [10, 30],
+              [10, 45],
+            ],
+            type: "polygon",
+          }}
+          id="byzantium"
+          label="Byzantine Empire"
+          startYear={330}
+        />
+        <MapTimelineEvent
+          color="amber"
+          description="Pompeii destroyed"
+          id="vesuvius"
+          position={[14.48, 40.75]}
+          title="Vesuvius"
+          toleranceYears={400}
+          year={79}
+        />
+        <MapTimelineControls>
+          <MapTimelinePlayButton />
+          <MapTimelineSlider />
+        </MapTimelineControls>
+      </MapTimeline>
+    </div>
+  );
+}
+
+function PrimarySourceViewerPreview() {
+  return (
+    <div className="w-full max-w-[320px]">
+      <PrimarySourceViewer
+        origin="England"
+        period="Medieval"
+        source={{
+          alt: "Historical document scan",
+          src: PRIMARY_SOURCE_PREVIEW_IMAGE,
+          type: "image",
+        }}
+        title="Magna Carta (1215)"
+      >
+        <PrimarySourceToolbar>
+          <PrimarySourceZoomIn />
+          <PrimarySourceZoomOut />
+        </PrimarySourceToolbar>
+        <PrimarySourceAnnotations>
+          <PrimarySourceAnnotation
+            category="Artifact"
+            color="amber"
+            id="seal"
+            note="Royal seal of King John"
+            region={{ height: 16, width: 18, x: 70, y: 70 }}
+          />
+        </PrimarySourceAnnotations>
+      </PrimarySourceViewer>
+    </div>
+  );
+}
+
+function RouteMapPreview() {
+  return (
+    <div className="w-full max-w-[320px]">
+      <RouteMap
+        color="red"
+        lineStyle="dashed"
+        waypoints={[
+          { id: "chang", label: "Chang'an", position: [108.94, 34.34] },
+          { id: "kashgar", label: "Kashgar", position: [75.99, 39.47] },
+          { id: "samarkand", label: "Samarkand", position: [66.97, 39.65] },
+          {
+            id: "constantinople",
+            label: "Constantinople",
+            position: [28.98, 41.01],
+          },
+        ]}
+      >
+        <p className="font-medium">Silk Road</p>
+        <p className="text-muted-foreground">4 waypoints</p>
+      </RouteMap>
+    </div>
+  );
+}
+
+function SelectionHaloPreview() {
+  return (
+    <div className="relative h-[160px] w-full max-w-md rounded-2xl border bg-muted/30">
+      <SelectionHalo
+        bounds={{ height: 90, width: 180, x: 80, y: 40 }}
+        label="3 objects"
+      />
+    </div>
+  );
+}
+
+function SnapGuidesPreview() {
+  return (
+    <div className="relative h-[160px] w-full max-w-md rounded-2xl border bg-muted/30">
+      <SnapGuides
+        guides={[
+          { id: "v-120", orientation: "vertical", x: 120 },
+          { id: "v-300", orientation: "vertical", x: 300 },
+          { id: "h-60", orientation: "horizontal", y: 60 },
+          { id: "h-120", orientation: "horizontal", y: 120 },
+        ]}
+      />
+    </div>
+  );
+}
+
+function StoryMapPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <StoryMap>
+        <StoryMapChapter
+          center={[12.49, 41.89]}
+          color="red"
+          id="rome"
+          subtitle="476 AD"
+          title="The Fall of Rome"
+          zoom={3}
+        >
+          <p>The last Western Roman Emperor was deposed in 476 AD.</p>
+        </StoryMapChapter>
+        <StoryMapChapter
+          center={[28.98, 41.01]}
+          color="purple"
+          id="constantinople"
+          subtitle="476 - 1453"
+          title="Constantinople Endures"
+          zoom={3}
+        >
+          <p>Constantinople thrived as the Byzantine capital for centuries.</p>
+        </StoryMapChapter>
+      </StoryMap>
+    </div>
+  );
+}
+
+function TreeViewPreview() {
+  return (
+    <div className="w-full max-w-xs">
+      <TreeView
+        defaultExpanded={["src", "components"]}
+        defaultSelected={["button"]}
+        nodes={[
+          {
+            id: "src",
+            label: "src/",
+            nodes: [
+              {
+                id: "components",
+                label: "components/",
+                nodes: [
+                  { id: "button", label: "Button.tsx" },
+                  { id: "card", label: "Card.tsx" },
+                ],
+              },
+              { id: "utils", label: "utils/" },
+            ],
+          },
+          { id: "package", label: "package.json" },
+        ]}
+      />
+    </div>
+  );
+}
+
+function AlertPulsePreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <AlertPulse cx={80} cy={60} radius={28} severity="warn" />
+    </div>
+  );
+}
+
+function AnimatedGridPatternPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <AnimatedGridPattern height={28} squares={10} width={28} />
+    </div>
+  );
+}
+
+function CardFlipPreview() {
+  return (
+    <CardFlip
+      back={
+        <div className="flex h-full items-center justify-center rounded-xl border bg-primary text-sm text-primary-foreground">
+          Back
+        </div>
+      }
+      className="h-28 w-44"
+      front={
+        <div className="flex h-full items-center justify-center rounded-xl border bg-card text-sm text-card-foreground">
+          Front
+        </div>
+      }
+    />
+  );
+}
+
+function CommentPinPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <CommentPin authorInitial="B" color="#5b8def" unread={3} x={72} y={56} />
+    </div>
+  );
+}
+
+function ContextLensPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <ContextLens
+        focus={{ cx: 80, cy: 60, inner: 22, outer: 60 }}
+        opacity={0.55}
+      />
+    </div>
+  );
+}
+
+function CursorPreview() {
+  return (
+    <div className="relative flex h-[120px] w-[160px] items-center justify-center overflow-hidden rounded-lg border bg-card">
+      <Cursor size={24} />
+      <span className="text-xs text-muted-foreground">
+        Custom cursor follows pointer
+      </span>
+    </div>
+  );
+}
+
+function DotPatternPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <DotPattern spacing={14} />
+    </div>
+  );
+}
+
+function GlassCardPreview() {
+  return (
+    <div className="rounded-xl bg-gradient-to-br from-primary/30 via-primary/10 to-transparent p-5">
+      <GlassCard className="px-4 py-3 text-sm">Frosted glass</GlassCard>
+    </div>
+  );
+}
+
+function GlassPanelPreview() {
+  return (
+    <div className="rounded-xl bg-gradient-to-br from-primary/30 via-primary/10 to-transparent p-5">
+      <GlassPanel className="px-4 py-3 text-sm">Panel chrome</GlassPanel>
+    </div>
+  );
+}
+
+function InfinitePlanePreview() {
+  return (
+    <div className="h-[120px] w-[160px] overflow-hidden rounded-lg border">
+      <InfinitePlane pattern="dot" spacing={24} zoom={1} />
+    </div>
+  );
+}
+
+function LiquidGlassPreview() {
+  return (
+    <div className="rounded-xl bg-gradient-to-br from-primary/30 via-primary/10 to-transparent p-5">
+      <LiquidGlass className="px-4 py-3 text-sm">Liquid glass</LiquidGlass>
+    </div>
+  );
+}
+
+function LiveCursorPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <LiveCursor color="#5b8def" name="Bea" x={48} y={40} />
+    </div>
+  );
+}
+
+function MagneticPreview() {
+  return (
+    <Magnetic className="rounded-xl border border-border bg-card px-6 py-4 text-sm text-card-foreground">
+      Pull me
+    </Magnetic>
+  );
+}
+
+function MagneticButtonPreview() {
+  return (
+    <MagneticButton className="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground">
+      Hover me
+    </MagneticButton>
+  );
+}
+
+function MeteorsPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <Meteors count={10} />
+    </div>
+  );
+}
+
+function MultiSelectLassoPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <MultiSelectLasso
+        count={4}
+        hint="Drag"
+        rect={{ height: 64, width: 96, x: 32, y: 28 }}
+      />
+    </div>
+  );
+}
+
+function ParticlesPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <Particles count={24} />
+    </div>
+  );
+}
+
+function PlaybackGhostPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <PlaybackGhost
+        kind="run"
+        label="research"
+        opacity={0.4}
+        size={36}
+        x={80}
+        y={60}
+      />
+    </div>
+  );
+}
+
+function ProgressiveBlurPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <div className="p-3 text-xs leading-5 text-muted-foreground">
+        Progressive blur ramps content toward one edge so overflow fades into a
+        soft gradient.
+      </div>
+      <ProgressiveBlur blur={8} direction="bottom" />
+    </div>
+  );
+}
+
+function SelectionPresencePreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <SelectionPresence
+        color="#5b8def"
+        height={56}
+        name="Bea"
+        width={96}
+        x={32}
+        y={32}
+      />
+    </div>
+  );
+}
+
+function ShimmerButtonPreview() {
+  return <ShimmerButton>Get started</ShimmerButton>;
+}
+
+function ShineBorderPreview() {
+  return (
+    <ShineBorder className="rounded-xl bg-card px-6 py-4 text-sm text-card-foreground">
+      Featured
+    </ShineBorder>
+  );
+}
+
+function ShinyButtonPreview() {
+  return <ShinyButton>Learn more</ShinyButton>;
+}
+
+function SparklesPreview() {
+  return (
+    <Sparkles className="rounded-lg px-5 py-4" count={20}>
+      <span className="text-sm font-semibold">Sparkle field</span>
+    </Sparkles>
+  );
+}
+
+function SpotlightCardPreview() {
+  return (
+    <SpotlightCard className="rounded-xl border bg-card px-5 py-4 text-sm text-card-foreground">
+      Spotlight card
+    </SpotlightCard>
+  );
+}
+
+function StateBadgeOverlayPreview() {
+  return (
+    <div className="relative h-[120px] w-[160px] overflow-hidden rounded-lg border bg-card">
+      <StateBadgeOverlay anchor="top-right" state="running" x={108} y={40} />
+    </div>
+  );
+}
+
+function ThemePresetProviderPreview() {
+  return (
+    <ThemePresetProvider>
+      <ThemeSwitcher />
+    </ThemePresetProvider>
+  );
+}
+
+function ThemeSwitcherPreview() {
+  return <ThemeSwitcher />;
+}
+
+function ThreadBubblePreview() {
+  return (
+    <div className="w-full max-w-[280px]">
+      <ThreadBubble
+        messages={[
+          {
+            author: "Bea",
+            authorColor: "#5b8def",
+            body: "Why are we routing to fallback?",
+            id: "1",
+            ts: "12s",
+          },
+          {
+            author: "Lior",
+            authorColor: "#10b981",
+            body: "p95 spike on primary.",
+            id: "2",
+            ts: "9s",
+          },
+        ]}
+        title="research-2025"
+      />
+    </div>
+  );
+}
+
+function TiltCardPreview() {
+  return (
+    <TiltCard
+      className="flex h-28 w-44 items-center justify-center rounded-xl border bg-card text-sm text-card-foreground shadow-sm"
+      maxTilt={12}
+    >
+      Hover to tilt
+    </TiltCard>
+  );
+}
+
+function TruncatedTextPreview() {
+  return (
+    <div className="w-[160px]">
+      <TruncatedText maxWidth="160px">
+        This is a very long label that truncates with an ellipsis
+      </TruncatedText>
+    </div>
+  );
+}
+
+function AnimatedListPreview() {
+  return (
+    <AnimatedList className="w-full max-w-xs">
+      <span className="rounded-md border bg-card px-3 py-2 text-sm">
+        Deploy queued
+      </span>
+      <span className="rounded-md border bg-card px-3 py-2 text-sm">
+        Build passed
+      </span>
+      <span className="rounded-md border bg-card px-3 py-2 text-sm">
+        Shipped to production
+      </span>
+    </AnimatedList>
+  );
+}
+
+function AnimatedTestimonialsPreview() {
+  return (
+    <div className="w-full max-w-sm">
+      <AnimatedTestimonials
+        testimonials={[
+          {
+            name: "Ada Lovelace",
+            quote: "This shipped our launch in a day.",
+            title: "Engineer",
+          },
+          {
+            name: "Grace Hopper",
+            quote: "The motion feels effortless.",
+            title: "Admiral",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function BentoGridPreview() {
+  return (
+    <BentoGrid className="w-full max-w-sm auto-rows-[3.5rem] gap-2">
+      <BentoCard className="col-span-2 p-3 text-sm font-medium">
+        Featured
+      </BentoCard>
+      <BentoCard className="p-3 text-sm">Detail</BentoCard>
+      <BentoCard className="p-3 text-sm">Detail</BentoCard>
+      <BentoCard className="col-span-2 p-3 text-sm">Wide</BentoCard>
+    </BentoGrid>
+  );
+}
+
+function BlurRevealPreview() {
+  return (
+    <BlurReveal className="text-2xl font-semibold">
+      I sharpen into view
+    </BlurReveal>
+  );
+}
+
+function DocumentSiblingNavPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <DocumentSiblingNav
+        next={{ href: "#", title: "What we shipped this quarter" }}
+        previous={{ href: "#", title: "Why thin clients are back" }}
+      />
+    </div>
+  );
+}
+
+function ExpandableCardsPreview() {
+  return (
+    <div className="w-full max-w-sm">
+      <ExpandableCards
+        cards={[
+          {
+            content: "Detailed body revealed on expand.",
+            description: "Click to expand",
+            id: "one",
+            title: "Getting started",
+          },
+          {
+            content: "Another panel of content.",
+            id: "two",
+            title: "Advanced usage",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function ObjectInspectorPreview() {
+  return (
+    <div className="w-72">
+      <ObjectInspector
+        kind="run"
+        status="running"
+        subtitle="claude-3.7 · 128k ctx"
+        title="research-2025-04-15"
+      >
+        <PropertySection
+          entries={[
+            { id: "tokens", label: "Tokens", value: "12.4k" },
+            { id: "cost", label: "Cost", value: "$0.18" },
+          ]}
+          title="State"
+        />
+      </ObjectInspector>
+    </div>
+  );
+}
+
+function PlanBadgePreview() {
+  return (
+    <div className="flex flex-wrap gap-2">
+      <PlanBadge tier="free" />
+      <PlanBadge tier="starter" />
+      <PlanBadge tier="growth" />
+      <PlanBadge tier="enterprise" />
+      <PlanBadge state="trial" tier="starter" />
+    </div>
+  );
+}
+
+function PolicyDeliveryPanelPreview() {
+  return (
+    <div className="w-72">
+      <PolicyDeliveryPanel
+        policies={[
+          { id: "pii", name: "PII redaction", status: "enforced" },
+          {
+            description: "60 / s soft cap",
+            id: "rate",
+            name: "Rate limiting",
+            status: "advisory",
+          },
+          { id: "exp", name: "Experiment B", status: "disabled" },
+        ]}
+      />
+    </div>
+  );
+}
+
+function PropertySectionPreview() {
+  return (
+    <div className="w-72">
+      <PropertySection
+        entries={[
+          { id: "x", label: "X", value: "120" },
+          { id: "y", label: "Y", value: "80" },
+          { id: "w", label: "Width", value: "240" },
+          { id: "h", label: "Height", value: "120" },
+        ]}
+        title="Layout"
+      />
+    </div>
+  );
+}
+
+function RelationshipInspectorPreview() {
+  return (
+    <div className="w-72">
+      <RelationshipInspector
+        edges={[
+          {
+            direction: "inbound",
+            id: "1",
+            relation: "spawned-by",
+            target: "run-2025-04-15",
+            targetSublabel: "claude-3.7",
+          },
+          {
+            direction: "outbound",
+            id: "2",
+            relation: "emits",
+            target: "summary.md",
+            targetSublabel: "1.2 KB",
+          },
+          {
+            direction: "outbound",
+            id: "3",
+            relation: "calls",
+            target: "ranker",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function RevealTextPreview() {
+  return (
+    <RevealText className="text-2xl font-semibold">Reveal headline</RevealText>
+  );
+}
+
+function RoleBadgePreview() {
+  return (
+    <div className="flex flex-wrap gap-2">
+      <RoleBadge accountRole="owner" />
+      <RoleBadge accountRole="admin" />
+      <RoleBadge accountRole="member" />
+      <RoleBadge accountRole="billing" />
+    </div>
+  );
+}
+
+function RoutingAssignmentPanelPreview() {
+  return (
+    <div className="w-72">
+      <RoutingAssignmentPanel
+        assignments={[
+          { agent: "researcher", id: "1", load: 0.82, role: "primary" },
+          { agent: "researcher-mini", id: "2", load: 0.04, role: "fallback" },
+          { agent: "shadow-eval", id: "3", role: "shadow" },
+        ]}
+      />
+    </div>
+  );
+}
+
+function RuntimeOverviewPanelPreview() {
+  return (
+    <div className="w-72">
+      <RuntimeOverviewPanel
+        metrics={[
+          {
+            id: "runs",
+            label: "Active runs",
+            tone: "success",
+            trend: "up",
+            value: 3,
+          },
+          {
+            detail: "0 last hour",
+            id: "errs",
+            label: "Errors",
+            tone: "neutral",
+            trend: "flat",
+            value: 0,
+          },
+          {
+            id: "tps",
+            label: "Throughput",
+            tone: "success",
+            trend: "up",
+            value: "120 / s",
+          },
+          {
+            detail: "p95 240ms",
+            id: "lat",
+            label: "Latency",
+            tone: "warn",
+            trend: "down",
+            value: "180ms",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function ScrambleTextPreview() {
+  return <ScrambleText className="text-2xl font-semibold" text="DECRYPTED" />;
+}
+
+function ShimmerTextPreview() {
+  return (
+    <ShimmerText className="text-xl font-medium">
+      Loading your workspace
+    </ShimmerText>
+  );
+}
+
+function SpinningTextPreview() {
+  return (
+    <div className="flex items-center justify-center text-sm text-foreground">
+      <SpinningText radius={64}>vllnt design system • </SpinningText>
+    </div>
+  );
+}
+
+function SubscriptionCardPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <SubscriptionCard
+        note="Your annual discount is locked in until the next renewal date."
+        plan="growth"
+        priceLabel="$49/mo"
+        primaryActionLabel="Manage plan"
+        renewalLabel="Renews on May 1, 2026"
+        seatsLabel="12 seats"
+        secondaryActionLabel="View invoices"
+        status="active"
+        usageLabel="4.2M tokens used"
+      />
+    </div>
+  );
+}
+
+function TextAnimatePreview() {
+  return (
+    <TextAnimate
+      animation="slide-up"
+      className="text-2xl font-semibold"
+      startOnView={false}
+    >
+      Welcome aboard the platform
+    </TextAnimate>
+  );
+}
+
+function TextRevealPreview() {
+  return (
+    <TextReveal className="text-xl font-semibold">
+      Scroll to read this line word by word.
+    </TextReveal>
+  );
+}
+
+function TextShimmerPreview() {
+  return (
+    <TextShimmer className="text-2xl font-semibold">
+      Shimmering headline
+    </TextShimmer>
+  );
+}
+
+function TimelinePreview() {
+  return (
+    <div className="w-full max-w-xs">
+      <Timeline>
+        <TimelineItem
+          date="Jan 2026"
+          status="completed"
+          title="Project started"
+        />
+        <TimelineItem date="Mar 2026" status="completed" title="MVP launch" />
+        <TimelineItem date="Jul 2026" status="active" title="V2 release" />
+        <TimelineItem
+          date="Q4 2026"
+          isLast
+          status="upcoming"
+          title="Public release"
+        />
+      </Timeline>
+    </div>
+  );
+}
+
+function TypewriterPreview() {
+  return (
+    <Typewriter className="text-xl font-medium" text="Building the future." />
+  );
+}
+
+function BottomActivityStripPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <BottomActivityStrip
+        events={[
+          { id: "1", label: "deploy ok", tone: "success", ts: "12s" },
+          { id: "2", label: "queue spike", tone: "warn", ts: "1m" },
+          { id: "3", label: "alert resolved", tone: "info", ts: "3m" },
+          { id: "4", label: "p95 trip", tone: "danger", ts: "5m" },
+        ]}
+      />
+    </div>
+  );
+}
+
+function CandlestickChartPreview() {
+  return (
+    <div className="w-full max-w-[320px]">
+      <CandlestickChart
+        data={[
+          { close: 189.8, high: 191.2, label: "Mon", low: 182.4, open: 184.6 },
+          { close: 186.1, high: 193.5, label: "Tue", low: 184.8, open: 190.3 },
+          { close: 194.6, high: 196.8, label: "Wed", low: 185.9, open: 186.5 },
+          { close: 197.2, high: 199.4, label: "Thu", low: 192.7, open: 194.8 },
+          { close: 198.5, high: 201.1, label: "Fri", low: 192.4, open: 193.6 },
+        ]}
+        height={150}
+        showGrid={false}
+        width={300}
+      />
+    </div>
+  );
+}
+
+function ContributionGraphPreview() {
+  const data = Array.from({ length: 49 }, (_unused, index) => ({
+    count: Math.max(0, Math.round(3 + 3 * Math.sin(index / 3))),
+    date: new Date(Date.UTC(2026, 0, 4) + index * 86_400_000)
+      .toISOString()
+      .slice(0, 10),
+  }));
+  return (
+    <div className="w-full max-w-[260px]">
+      <ContributionGraph className="text-primary" data={data} weeks={7} />
+    </div>
+  );
+}
+
+function FlowDiagramPreview() {
+  return (
+    <div className="w-full max-w-sm">
+      <FlowDiagram
+        allowFullscreen={false}
+        edges={[
+          { id: "e1-2", source: "1", target: "2" },
+          { id: "e2-3", source: "2", target: "3" },
+        ]}
+        fitView
+        height={160}
+        nodes={[
+          {
+            data: { description: "Entry point", label: "Start" },
+            id: "1",
+            position: { x: 0, y: 0 },
+          },
+          {
+            data: { description: "Processing step", label: "Process" },
+            id: "2",
+            position: { x: 180, y: 0 },
+          },
+          {
+            data: { description: "Final step", label: "End" },
+            id: "3",
+            position: { x: 360, y: 0 },
+          },
+        ]}
+        showControls={false}
+      />
+    </div>
+  );
+}
+
+function GanttChartPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <GanttChart
+        endDate="2026-04-30"
+        groups={[
+          {
+            id: "phase-1",
+            name: "Phase 1",
+            tasks: [
+              {
+                color: "blue",
+                end: "2026-02-28",
+                id: "design",
+                progress: 100,
+                start: "2026-01-15",
+                title: "Design",
+              },
+              {
+                color: "emerald",
+                end: "2026-04-15",
+                id: "core",
+                progress: 60,
+                start: "2026-02-01",
+                title: "Build",
+              },
+            ],
+          },
+        ]}
+        milestones={[{ date: "2026-04-15", id: "v1", title: "v1.0" }]}
+        now="2026-03-01"
+        scale="month"
+        startDate="2026-01-01"
+      />
+    </div>
+  );
+}
+
+function GaugeChartPreview() {
+  return (
+    <div className="w-full max-w-[200px]">
+      <GaugeChart
+        className="text-primary"
+        label="CPU load"
+        max={100}
+        min={0}
+        size={150}
+        value={72}
+      />
+    </div>
+  );
+}
+
+function HeatOverlayPreview() {
+  return (
+    <SimplePreview description="Density heat overlay that plots weighted points as soft radial blooms over a workspace canvas." />
+  );
+}
+
+function MetricClusterPreview() {
+  return (
+    <div className="relative h-[150px] w-full max-w-[280px] overflow-hidden rounded-lg border bg-muted/30">
+      <MetricCluster
+        anchor="top-left"
+        metrics={[
+          { id: "qps", label: "qps", tone: "success", value: "240" },
+          { id: "errs", label: "errs", tone: "danger", value: "14" },
+          { id: "p95", label: "p95", value: "180ms" },
+        ]}
+        title="research-2025"
+        x={170}
+        y={130}
+      />
+    </div>
+  );
+}
+
+function OverviewBoardPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <OverviewBoard
+        eyebrow="Operator overview"
+        heading="Morning priorities"
+        items={[
+          {
+            description: "Retries that still need intervention.",
+            heading: "Errors",
+            id: "errors",
+            metric: "3",
+            tone: "danger",
+          },
+          {
+            description: "Approvals to clear before lunch.",
+            heading: "Actions",
+            id: "actions",
+            metric: "7",
+            tone: "warning",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function PieChartPreview() {
+  return (
+    <div className="w-full max-w-[200px]">
+      <PieChart
+        className="text-primary"
+        data={[
+          { label: "Direct", value: 40 },
+          { label: "Referral", value: 25 },
+          { label: "Organic", value: 35 },
+          { label: "Social", value: 18 },
+        ]}
+        innerRadius={0.6}
+        size={150}
+      />
+    </div>
+  );
+}
+
+function PresenceStackPreview() {
+  return (
+    <PresenceStack
+      max={4}
+      users={[
+        { color: "#5b8def", id: "1", initial: "B", name: "Bea" },
+        {
+          color: "#10b981",
+          id: "2",
+          initial: "L",
+          name: "Lior",
+          status: "away",
+        },
+        {
+          color: "#f59e0b",
+          id: "3",
+          initial: "S",
+          name: "Sam",
+          status: "idle",
+        },
+        { color: "#a855f7", id: "4", initial: "M", name: "Mira" },
+        {
+          color: "#ef4444",
+          id: "5",
+          initial: "R",
+          name: "Rae",
+          status: "offline",
+        },
+        { color: "#0ea5e9", id: "6", initial: "K", name: "Kim" },
+      ]}
+    />
+  );
+}
+
+function PresenceSyncIndicatorPreview() {
+  return (
+    <div className="flex flex-col items-start gap-2">
+      <PresenceSyncIndicator state="live" status="3 peers" />
+      <PresenceSyncIndicator state="syncing" status="2 changes" />
+      <PresenceSyncIndicator state="reconnecting" status="retry 2 / 5" />
+    </div>
+  );
+}
+
+function RadarChartPreview() {
+  return (
+    <div className="w-full max-w-[200px]">
+      <RadarChart
+        className="text-primary"
+        data={[
+          { label: "Speed", value: 80 },
+          { label: "Power", value: 60 },
+          { label: "Range", value: 90 },
+          { label: "Agility", value: 70 },
+          { label: "Defense", value: 50 },
+          { label: "Stamina", value: 65 },
+        ]}
+        max={100}
+        size={170}
+      />
+    </div>
+  );
+}
+
+function RunTimelinePreview() {
+  return (
+    <div className="w-full max-w-md">
+      <RunTimeline
+        cursor={1800}
+        end={3600}
+        formatValue={(value) => `${Math.round(value / 60)}m`}
+        lanes={[
+          { id: "ingest", label: "Ingest" },
+          { id: "rank", label: "Rank" },
+          { id: "emit", label: "Emit" },
+        ]}
+        phases={[
+          {
+            end: 600,
+            id: "i1",
+            label: "load",
+            laneId: "ingest",
+            start: 0,
+            state: "complete",
+          },
+          {
+            end: 2200,
+            id: "r1",
+            label: "score",
+            laneId: "rank",
+            start: 800,
+            state: "running",
+          },
+          {
+            end: 1500,
+            id: "r2",
+            label: "filter",
+            laneId: "rank",
+            start: 1200,
+            state: "failed",
+          },
+          {
+            end: 3600,
+            id: "e1",
+            label: "publish",
+            laneId: "emit",
+            start: 2300,
+            state: "queued",
+          },
+        ]}
+        start={0}
+      />
+    </div>
+  );
+}
+
+function SankeyChartPreview() {
+  return (
+    <div className="w-full max-w-[320px]">
+      <SankeyChart
+        className="text-primary"
+        height={150}
+        links={[
+          { source: "visits", target: "signup", value: 60 },
+          { source: "visits", target: "bounce", value: 40 },
+          { source: "signup", target: "trial", value: 35 },
+          { source: "signup", target: "churn", value: 25 },
+          { source: "trial", target: "paid", value: 20 },
+        ]}
+        nodes={[
+          { id: "visits", label: "Visits" },
+          { id: "signup", label: "Signup" },
+          { id: "bounce", label: "Bounce" },
+          { id: "trial", label: "Trial" },
+          { id: "churn", label: "Churn" },
+          { id: "paid", label: "Paid" },
+        ]}
+        width={300}
+      />
+    </div>
+  );
+}
+
+function SparklineGridPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <SparklineGrid
+        columns={2}
+        items={[
+          {
+            change: 2.14,
+            data: [14, 16, 17, 15, 19, 22],
+            label: "Tech momentum",
+            value: "$12.8M",
+          },
+          {
+            change: -1.08,
+            data: [9, 8, 7, 8, 6, 5],
+            label: "Energy breadth",
+            value: "$8.4M",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function StickyMetricPreview() {
+  return (
+    <div className="relative h-[120px] w-full max-w-[240px] overflow-hidden rounded-lg border bg-muted/30">
+      <StickyMetric
+        anchor="top-left"
+        detail="↑ 12%"
+        label="qps"
+        tone="success"
+        value="240"
+        x={170}
+        y={90}
+      />
+    </div>
+  );
+}
+
+function ThresholdRingPreview() {
+  return (
+    <div className="flex items-center justify-center gap-4">
+      <ThresholdRing
+        centerLabel="32%"
+        size={88}
+        threshold={0.7}
+        tone="success"
+        value={0.32}
+      />
+      <ThresholdRing
+        centerLabel="68%"
+        size={88}
+        threshold={0.7}
+        tone="warn"
+        value={0.68}
+      />
+      <ThresholdRing
+        centerLabel="92%"
+        size={88}
+        threshold={0.7}
+        tone="danger"
+        value={0.92}
+      />
+    </div>
+  );
+}
+
+function TickerTapePreview() {
+  return (
+    <div className="w-full max-w-md">
+      <TickerTape
+        items={[
+          { change: 1.42, price: 182.33, symbol: "AAPL", volume: "Vol 32M" },
+          { change: -0.64, price: 431.8, symbol: "MSFT", volume: "Vol 18M" },
+          { change: 3.08, price: 512.9, symbol: "NVDA", volume: "Vol 44M" },
+          { change: -1.18, price: 287.12, symbol: "TSLA", volume: "Vol 51M" },
+        ]}
+      />
+    </div>
+  );
+}
+
+function ButtonGroupPreview() {
+  return (
+    <ButtonGroup>
+      <Button variant="outline">Day</Button>
+      <Button variant="outline">Week</Button>
+      <Button variant="outline">Month</Button>
+    </ButtonGroup>
+  );
+}
+
+function CheckboxGroupPreview() {
+  return (
+    <CheckboxGroup defaultValue={["email"]}>
+      <CheckboxGroupItem value="email">Email</CheckboxGroupItem>
+      <CheckboxGroupItem value="sms">SMS</CheckboxGroupItem>
+      <CheckboxGroupItem value="push">Push</CheckboxGroupItem>
+    </CheckboxGroup>
+  );
+}
+
+function ColorPickerPreview() {
+  return (
+    <div className="w-44">
+      <ColorPicker defaultValue="#3b82f6" />
+    </div>
+  );
+}
+
+function DateFieldPreview() {
+  return (
+    <div className="w-48">
+      <DateField aria-label="Date" defaultValue="2026-04-19" />
+    </div>
+  );
+}
+
+function DateRangePickerPreview() {
+  return (
+    <div className="w-60">
+      <DateRangePicker
+        defaultValue={{
+          from: new Date("2026-04-19T00:00:00.000Z"),
+          to: new Date("2026-04-26T00:00:00.000Z"),
+        }}
+      />
+    </div>
+  );
+}
+
+function FieldPreview() {
+  return (
+    <Field className="w-56">
+      <FieldLabel>Email</FieldLabel>
+      <FieldControl>
+        <Input placeholder="you@example.com" type="email" />
+      </FieldControl>
+      <FieldDescription>We never share it.</FieldDescription>
+    </Field>
+  );
+}
+
+function FieldsetPreview() {
+  return (
+    <Fieldset className="w-60">
+      <FieldsetLegend>Shipping address</FieldsetLegend>
+      <FieldsetContent>
+        <Input placeholder="Street" />
+        <Input placeholder="City" />
+      </FieldsetContent>
+    </Fieldset>
+  );
+}
+
+function InputGroupPreview() {
+  return (
+    <InputGroup className="w-56">
+      <InputGroupAddon>
+        <Search />
+      </InputGroupAddon>
+      <InputGroupInput placeholder="Search..." />
+    </InputGroup>
+  );
+}
+
+function ItemPreview() {
+  return (
+    <Item className="w-56" variant="outline">
+      <ItemContent>
+        <ItemTitle>Pro plan</ItemTitle>
+        <ItemDescription>Billed annually.</ItemDescription>
+      </ItemContent>
+      <ItemActions>
+        <Button size="sm">Upgrade</Button>
+      </ItemActions>
+    </Item>
+  );
+}
+
+function ListBoxPreview() {
+  return (
+    <ListBox className="w-48" defaultValue={["pst"]} label="Timezone">
+      <ListBoxItem value="utc">UTC</ListBoxItem>
+      <ListBoxItem value="est">Eastern</ListBoxItem>
+      <ListBoxItem value="pst">Pacific</ListBoxItem>
+    </ListBox>
+  );
+}
+
+function NativeSelectPreview() {
+  return (
+    <NativeSelect aria-label="Timezone" className="w-48" defaultValue="utc">
+      <option value="utc">UTC</option>
+      <option value="est">Eastern</option>
+      <option value="pst">Pacific</option>
+    </NativeSelect>
+  );
+}
+
+function NewsletterSignupPreview() {
+  return (
+    <div className="w-64">
+      <NewsletterSignup onSubmit={noop} variant="stacked" />
+    </div>
+  );
+}
+
+function PhoneInputPreview() {
+  return (
+    <div className="w-64">
+      <PhoneInput defaultCountry="US" placeholder="555 000 1234" />
+    </div>
+  );
+}
+
+function RangeCalendarPreview() {
+  return (
+    <RangeCalendar
+      defaultValue={{
+        from: new Date("2026-04-19T00:00:00.000Z"),
+        to: new Date("2026-04-26T00:00:00.000Z"),
+      }}
+      numberOfMonths={1}
+    />
+  );
+}
+
+function SearchFieldPreview() {
+  return (
+    <div className="w-56">
+      <SearchField defaultValue="components" placeholder="Search..." />
+    </div>
+  );
+}
+
+function TagGroupPreview() {
+  return (
+    <TagGroup defaultValue={["design"]} label="Topics" selectionMode="multiple">
+      <TagGroupItem value="design">Design</TagGroupItem>
+      <TagGroupItem value="engineering">Engineering</TagGroupItem>
+      <TagGroupItem value="product">Product</TagGroupItem>
+    </TagGroup>
+  );
+}
+
+function TextFieldPreview() {
+  return (
+    <div className="w-56">
+      <TextField
+        defaultValue="ada@vllnt.com"
+        label="Email"
+        placeholder="you@example.com"
+      />
+    </div>
+  );
+}
+
+function TimeFieldPreview() {
+  return (
+    <div className="w-44">
+      <TimeField aria-label="Time" defaultValue="08:15" />
+    </div>
+  );
+}
+
+function TimePickerPreview() {
+  return (
+    <div className="w-44">
+      <TimePicker defaultValue="09:30" placeholder="Select time" />
+    </div>
+  );
+}
+
+function TimelineScrubberPreview() {
+  return (
+    <div className="w-64">
+      <TimelineScrubber
+        end={3600}
+        formatValue={(value) => `${Math.round(value / 60)}m`}
+        onValueChange={noop}
+        start={0}
+        ticks={[
+          { id: "deploy", tone: "primary", value: 600 },
+          { id: "alert", tone: "danger", value: 2400 },
+        ]}
+        value={1800}
+      />
+    </div>
+  );
+}
+
+function AgentActivityPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <AgentActivity elapsed="8.4s" status="completed">
+        <AgentStep status="completed">
+          <AgentStepTitle>Searching codebase</AgentStepTitle>
+          <AgentStepDuration>1.2s</AgentStepDuration>
+          <AgentStepDetail>
+            Found 12 files matching &quot;auth&quot;.
+          </AgentStepDetail>
+        </AgentStep>
+        <AgentStep status="completed">
+          <AgentStepTitle>Reading auth.ts</AgentStepTitle>
+          <AgentStepDuration>0.4s</AgentStepDuration>
+        </AgentStep>
+      </AgentActivity>
+    </div>
+  );
+}
+
+function AiArtifactPreview() {
+  const source = `export function UserProfile({ name }: { name: string }) {
+  return <div className="profile">Hello, {name}</div>;
+}`;
+  return (
+    <div className="w-full max-w-md">
+      <AIArtifact
+        filename="UserProfile.tsx"
+        language="tsx"
+        subtitle="Generated component"
+        title="UserProfile.tsx"
+        type="code"
+        value={source}
+      >
+        <AIArtifactToolbar>
+          <AIArtifactCopyButton />
+          <AIArtifactDownloadButton />
+        </AIArtifactToolbar>
+        <AIArtifactContent>
+          <pre className="font-mono text-xs leading-relaxed">{source}</pre>
+        </AIArtifactContent>
+        <AIArtifactVersions>
+          <AIArtifactVersion label="v1" />
+          <AIArtifactVersion active label="v2" />
+        </AIArtifactVersions>
+      </AIArtifact>
+    </div>
+  );
+}
+
+function AiSidebarPreview() {
+  return (
+    <AISidebarProvider defaultOpen defaultPosition="right" defaultWidth={280}>
+      <div className="relative h-[280px] w-full max-w-sm overflow-hidden rounded-xl border bg-muted/30">
+        <AISidebar className="!absolute">
+          <AISidebarHeader>
+            <AISidebarTitle>AI Assistant</AISidebarTitle>
+            <AISidebarClose />
+          </AISidebarHeader>
+          <AISidebarContent>
+            <p className="text-sm text-muted-foreground">
+              Ask anything about this document.
+            </p>
+          </AISidebarContent>
+          <AISidebarFooter>
+            <p className="text-xs text-muted-foreground">Composer goes here…</p>
+          </AISidebarFooter>
+        </AISidebar>
+      </div>
+    </AISidebarProvider>
+  );
+}
+
+function ChainOfThoughtPreview() {
+  return (
+    <div className="w-full max-w-sm">
+      <ChainOfThought
+        steps={[
+          {
+            description: "Loaded src/index.ts",
+            status: "complete",
+            title: "Read the file",
+          },
+          { status: "complete", title: "Apply the edit" },
+          { status: "complete", title: "Run the test suite" },
+        ]}
+      />
+    </div>
+  );
+}
+
+function ChatDockSectionPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <ChatDockSection
+        contextLabel="Today · overview"
+        messages={[
+          {
+            body: "Three failed runs came in overnight. Start with the invoice retry and the security digest.",
+            id: "assistant",
+            speaker: "Assistant",
+          },
+          {
+            body: "Queue the approvals first, then review the stale automations after lunch.",
+            id: "operator",
+            speaker: "Operator",
+          },
+        ]}
+        title="Assistant"
+      />
+    </div>
+  );
+}
+
+function ModelComparisonPreview() {
+  return (
+    <div className="w-full max-w-2xl">
+      <ModelComparison prompt="Explain closures in JavaScript">
+        <ModelComparisonColumn label="Sonnet" model="claude-sonnet-4-6">
+          <p className="text-sm">
+            A closure is a function bundled together with references to its
+            surrounding state.
+          </p>
+          <ModelComparisonMeta cost="$0.003" latency="0.8s" tokens={320} />
+        </ModelComparisonColumn>
+        <ModelComparisonColumn label="GPT-4o" model="gpt-4o">
+          <p className="text-sm">
+            Closures let an inner function remember the variables of the outer
+            function it was created in.
+          </p>
+          <ModelComparisonMeta cost="$0.005" latency="1.1s" tokens={410} />
+        </ModelComparisonColumn>
+      </ModelComparison>
+    </div>
+  );
+}
+
+function PromptInputPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <PromptInput
+        defaultValue="Summarize this thread and list the open action items."
+        isLoading={false}
+        placeholder="Ask anything…"
+      />
+    </div>
+  );
+}
+
+function PromptTemplatesPreview() {
+  return (
+    <div className="w-full max-w-2xl">
+      <PromptTemplates
+        categories={[{ name: "Code" }, { name: "Analysis" }]}
+        templates={[
+          {
+            category: "Code",
+            description: "Review code for bugs, performance, and improvements",
+            id: "code-review",
+            template: "Review this {{language}} code for bugs:\n\n{{code}}",
+            title: "Code Review",
+          },
+          {
+            category: "Analysis",
+            description: "Explain code line by line",
+            id: "code-explain",
+            template: "Explain what this code does line by line.",
+            title: "Explain code",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function ReasoningPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <Reasoning
+        duration={4}
+        isStreaming={false}
+        steps={[
+          "Parse the user request and identify the goal.",
+          "Check the cache for a recent matching answer.",
+          "Compose the final response from the retrieved context.",
+        ]}
+      />
+    </div>
+  );
+}
+
+function AiChatInputPreview() {
+  return (
+    <div className="w-full max-w-2xl">
+      <AIChatInput
+        helperText="Shift + Enter adds a new line"
+        isSubmitting={false}
+        status="2 files attached"
+        value="Draft a release note for the latest accessibility fixes."
+      />
+    </div>
+  );
+}
+
+function AiMessageBubblePreview() {
+  return (
+    <div className="w-full max-w-md space-y-3">
+      <AIMessageBubble author="You" messageRole="user" timestamp="3m ago">
+        Can you check the failing background job?
+      </AIMessageBubble>
+      <AIMessageBubble author="Assistant" timestamp="2m ago">
+        I reviewed the integration logs and found a single failing background
+        job.
+      </AIMessageBubble>
+    </div>
+  );
+}
+
+function AiSourceCitationPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <AISourceCitation
+        href="https://example.com/research/agent-patterns"
+        snippet="Agent interfaces work best when message state, tool traces, and citations share the same visual language."
+        source="Agent UI research"
+        title="Designing readable AI conversations"
+      />
+    </div>
+  );
+}
+
+function AiStreamingTextPreview() {
+  return (
+    <div className="w-full max-w-md text-sm">
+      <AIStreamingText
+        isStreaming={false}
+        text="I checked the deployment logs and found the slow step in the image optimization pipeline."
+      />
+    </div>
+  );
+}
+
+function AiToolCallDisplayPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <AIToolCallDisplay
+        description="Gathered logs from the latest deployment run."
+        duration="1.2s"
+        input='{"service":"registry","window":"15m"}'
+        output='{"errors":0,"warnings":2}'
+        status="complete"
+        toolName="logs.fetch"
+      />
+    </div>
+  );
+}
+
+function AnnotationPreview() {
+  return (
+    <p className="max-w-md text-sm leading-7 text-foreground">
+      In guided reading,{" "}
+      <Annotation annotation="Scaffolding provides temporary support while a learner builds confidence.">
+        scaffolding
+      </Annotation>{" "}
+      helps learners focus on the next{" "}
+      <Highlight tone="sky">meaningful step</Highlight>.
+    </p>
+  );
+}
+
+function ConversationThreadPreview() {
+  return (
+    <div className="h-[280px] w-full max-w-md overflow-hidden rounded-xl border">
+      <ConversationThread
+        isStreaming={false}
+        messages={[
+          {
+            content: "Summarize the UI PR stack and call out blockers.",
+            id: "user-1",
+            role: "user",
+          },
+          {
+            content:
+              "I reconciled the stacked branches against main and queued the next merge in order.",
+            id: "assistant-1",
+            role: "assistant",
+            thinking:
+              "Check the PR states, confirm quality gates, then merge only the clean branches.",
+            toolCalls: [
+              { id: "tool-1", input: { pr: 149 }, name: "gh_pr_checks" },
+            ],
+          },
+        ]}
+      >
+        <ConversationHeader>
+          <ConversationTitle>Workspace assistant</ConversationTitle>
+        </ConversationHeader>
+        <ConversationMessages />
+      </ConversationThread>
+    </div>
+  );
+}
+
+function CurriculumPreview() {
+  return (
+    <div className="w-full max-w-lg">
+      <Curriculum
+        defaultExpandedModules={["mod-1"]}
+        title="Full-Stack Development"
+        totalHours={40}
+      >
+        <CurriculumModule
+          description="Core web technologies"
+          estimatedHours={8}
+          id="mod-1"
+          title="Module 1: Foundations"
+        >
+          <CurriculumLesson
+            difficulty="beginner"
+            duration="45 min"
+            href="/lessons/html"
+            status="completed"
+            title="HTML & Semantic Markup"
+          />
+          <CurriculumLesson
+            difficulty="beginner"
+            duration="60 min"
+            href="/lessons/css"
+            status="in-progress"
+            title="CSS Layout"
+          />
+          <CurriculumLesson
+            difficulty="intermediate"
+            duration="90 min"
+            status="locked"
+            title="JavaScript Fundamentals"
+          />
+        </CurriculumModule>
+      </Curriculum>
+    </div>
+  );
+}
+
+function ProgressTrackerPreview() {
+  return (
+    <div className="w-full max-w-2xl">
+      <ProgressTracker
+        overallProgress={0.65}
+        streak={7}
+        title="Frontend mastery path"
+      >
+        <ProgressTrackerOverview description="A curriculum-level dashboard for lessons, exercises, and learning streaks." />
+        <ProgressTrackerStats>
+          <ProgressTrackerStat label="Streak" value="7 days" />
+          <ProgressTrackerStat label="Time spent" value="24h" />
+          <ProgressTrackerStat label="Exercises" value="45/80" />
+          <ProgressTrackerStat label="Skills" value="12" />
+        </ProgressTrackerStats>
+        <ProgressTrackerModules>
+          <ProgressTrackerModule
+            badge="Foundation"
+            completedExercises={18}
+            completedLessons={12}
+            description="Build confidence with variables, functions, and arrays."
+            exercises={18}
+            lessons={12}
+            progress={1}
+            skills={["Syntax", "Functions", "Arrays"]}
+            status="completed"
+            timeSpent="8h 10m"
+            title="JavaScript Basics"
+          />
+          <ProgressTrackerModule
+            badge="Now learning"
+            completedExercises={5}
+            completedLessons={3}
+            currentLesson="Hooks in action"
+            description="Move from JSX to reusable interactive interfaces."
+            exercises={12}
+            lessons={8}
+            progress={0.4}
+            skills={["Components", "Hooks", "State"]}
+            status="in-progress"
+            timeSpent="6h 20m"
+            title="React Fundamentals"
+          />
+        </ProgressTrackerModules>
+      </ProgressTracker>
+    </div>
+  );
+}
+
+function RatingPreview() {
+  return <Rating defaultValue={4} label="Lesson quality" readOnly showValue />;
+}
+
+function StepperPreview() {
+  return (
+    <div className="w-full max-w-lg">
+      <Stepper
+        currentStep={2}
+        steps={[
+          {
+            description: "Set context and vocabulary.",
+            id: "intro",
+            title: "Introduction",
+          },
+          {
+            description: "Work through a solved example.",
+            id: "practice",
+            meta: "8 min",
+            title: "Guided practice",
+          },
+          {
+            description: "Answer a quick prompt to confirm understanding.",
+            id: "check",
+            title: "Knowledge check",
+          },
+          {
+            description: "Capture the main takeaway.",
+            id: "reflect",
+            title: "Reflection",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function TourPreview() {
+  return (
+    <div className="w-full max-w-md">
+      <Tour
+        defaultStep={0}
+        steps={[
+          {
+            badge: "Start here",
+            description:
+              "The overview introduces goals, key vocabulary, and the pacing for the lesson.",
+            id: "overview",
+            title: "Overview",
+          },
+          {
+            description:
+              "Worked examples walk through a complete solution with annotations and checkpoints.",
+            id: "examples",
+            title: "Examples",
+          },
+          {
+            badge: "Wrap up",
+            description:
+              "End with a quick self-check and a reflection prompt so learners can consolidate the takeaway.",
+            id: "wrap-up",
+            title: "Wrap up",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+function BannerPreview() {
+  return (
+    <div className="w-full max-w-sm overflow-hidden rounded-lg border">
+      <Banner dismissible icon={<AlertTriangle />} variant="warning">
+        Scheduled maintenance tonight at 11pm UTC.
+        <BannerAction>View status</BannerAction>
+      </Banner>
+    </div>
+  );
+}
+
+function CookieConsentPreview() {
+  return (
+    <div
+      className="relative h-40 w-full max-w-sm overflow-hidden rounded-lg border bg-muted/20"
+      style={{ transform: "translateZ(0)" }}
+    >
+      <CookieConsent
+        acceptText="Accept"
+        declineText="Decline"
+        message="This site uses cookies to improve your experience."
+        position="bottom-left"
+        settingsHref="/privacy"
+        settingsText="Learn more"
+      />
+    </div>
+  );
+}
+
+function CopyButtonPreview() {
+  return (
+    <div className="flex items-center gap-3">
+      <CopyButton value="EXAMPLE_API_KEY" />
+      <CopyButton
+        label="Copy link"
+        value="https://ui.vllnt.ai"
+        variant="button"
+      />
+    </div>
+  );
+}
+
+function EmptyStatePreview() {
+  return (
+    <div className="w-full max-w-sm">
+      <EmptyState
+        description="Try adjusting your search or filters."
+        icon={<Inbox />}
+        size="sm"
+        title="No results found"
+      >
+        <Button size="sm" variant="outline">
+          Clear filters
+        </Button>
+      </EmptyState>
+    </div>
+  );
+}
+
+function GridPreview() {
+  return (
+    <div className="w-full max-w-xs">
+      <Grid cols={3} gap={2}>
+        {Array.from({ length: 6 }, (_, index) => (
+          <div
+            className="rounded-md border border-border bg-muted p-3 text-center text-xs"
+            key={`grid-cell-${index + 1}`}
+          >
+            {index + 1}
+          </div>
+        ))}
+      </Grid>
+    </div>
+  );
+}
+
+function KbdPreview() {
+  return (
+    <div className="flex flex-col items-center gap-2 text-sm">
+      <span className="inline-flex items-center gap-1">
+        <Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>
+      </span>
+      <Kbd shortcut="mod+shift+p" />
+    </div>
+  );
+}
+
+function LabelPreview() {
+  return (
+    <div className="flex items-center gap-2">
+      <Checkbox id="newsletter" />
+      <Label htmlFor="newsletter">Subscribe to newsletter</Label>
+    </div>
+  );
+}
+
+function LinkPreview() {
+  return (
+    <div className="flex flex-col items-start gap-2 text-sm">
+      <Link href="#">Read the docs</Link>
+      <Link href="#" variant="muted">
+        Muted link
+      </Link>
+      <Link external href="https://example.com">
+        Visit example.com
+      </Link>
+    </div>
+  );
+}
+
+function MeterPreview() {
+  return (
+    <div className="flex w-full max-w-xs flex-col gap-3">
+      <Meter label="Disk usage" value={72} valueText="72% used" />
+      <Meter
+        label="Storage almost full"
+        value={94}
+        valueText="94% used"
+        variant="destructive"
+      />
+      <Meter
+        label="Signal strength"
+        max={5}
+        segments={5}
+        value={3}
+        valueText="3 of 5 bars"
+      />
+    </div>
+  );
+}
+
+function PanelPreview() {
+  return (
+    <Panel className="w-full max-w-sm">
+      <PanelHeader>
+        <PanelTitle>Workspace settings</PanelTitle>
+        <PanelDescription>Update how your team collaborates.</PanelDescription>
+      </PanelHeader>
+      <PanelBody>
+        <p className="text-sm text-muted-foreground">Body content goes here.</p>
+      </PanelBody>
+      <PanelFooter className="justify-end gap-2">
+        <Button size="sm" variant="ghost">
+          Cancel
+        </Button>
+        <Button size="sm">Save</Button>
+      </PanelFooter>
+    </Panel>
+  );
+}
+
+function QrCodePreview() {
+  return <QrCode size={140} value="https://vllnt.com" />;
+}
+
+function SwitchPreview() {
+  return (
+    <div className="flex items-center gap-2">
+      <Switch defaultChecked id="airplane-mode" />
+      <Label htmlFor="airplane-mode">Airplane mode</Label>
+    </div>
+  );
+}
+
+function ToolbarPreview() {
+  return (
+    <Toolbar aria-label="Text formatting">
+      <Button size="sm" variant="ghost">
+        Bold
+      </Button>
+      <Button size="sm" variant="ghost">
+        Italic
+      </Button>
+      <ToolbarSeparator />
+      <Button size="sm" variant="ghost">
+        Link
+      </Button>
+    </Toolbar>
+  );
+}
+
+function TypographyPreview() {
+  return (
+    <div className="w-full max-w-sm text-left">
+      <H3>The quick brown fox</H3>
+      <P>
+        A standard body paragraph with inline code like{" "}
+        <InlineCode>npm install</InlineCode>.
+      </P>
+      <Muted>Muted secondary text for captions.</Muted>
+    </div>
+  );
+}
+
+function AnimatedTooltipPreview() {
+  return (
+    <div className="flex min-h-24 items-center justify-center p-6">
+      <AnimatedTooltip content="Tooltip content">
+        <Button variant="outline">Hover me</Button>
+      </AnimatedTooltip>
+    </div>
+  );
+}
+
+function ShareDialogPreview() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <>
+      <Button
+        onClick={() => {
+          setOpen(true);
+        }}
+        variant="outline"
+      >
+        Share
+      </Button>
+      <ShareDialog
+        description="Share this article with your network."
+        onOpenChange={setOpen}
+        open={open}
+        platforms={[
+          {
+            buildUrl: (url) => `https://x.com/intent/tweet?url=${url}`,
+            key: "x",
+            label: "X",
+          },
+          {
+            buildUrl: (url) =>
+              `https://www.linkedin.com/sharing/share-offsite/?url=${url}`,
+            key: "linkedin",
+            label: "LinkedIn",
+          },
+        ]}
+        title="Share"
+      />
+    </>
+  );
+}
+
+function AnimatedTabsPreview() {
+  return (
+    <AnimatedTabs
+      defaultValue="overview"
+      tabs={[
+        { label: "Overview", value: "overview" },
+        { label: "Activity", value: "activity" },
+        { label: "Settings", value: "settings" },
+      ]}
+    />
+  );
+}
+
+function BottomBarPreview() {
+  return (
+    <div className="w-full max-w-md rounded-xl border border-dashed border-border/70 p-2">
+      <BottomBar
+        center={
+          <span className="rounded-full border border-border/70 px-3 py-1 text-xs text-muted-foreground">
+            7 awaiting action
+          </span>
+        }
+        leading={
+          <span className="text-xs text-muted-foreground">System healthy</span>
+        }
+        trailing={
+          <Button size="sm" variant="ghost">
+            Open inbox
+          </Button>
+        }
+      />
+    </div>
+  );
+}
+
+function DockPreview() {
+  return (
+    <Dock>
+      <DockIcon>A</DockIcon>
+      <DockIcon>B</DockIcon>
+      <DockIcon>C</DockIcon>
+      <DockIcon>D</DockIcon>
+    </Dock>
+  );
+}
+
+function FloatingNavbarPreview() {
+  return (
+    <div
+      className="relative flex h-20 w-full max-w-md items-center justify-center overflow-hidden rounded-lg border bg-muted/20"
+      style={{ transform: "translateZ(0)" }}
+    >
+      <FloatingNavbar className="text-sm">
+        <Link href="#">Home</Link>
+        <Link href="#">About</Link>
+        <Link href="#">Contact</Link>
+      </FloatingNavbar>
+    </div>
+  );
+}
+
+function JarvisDockPreview() {
+  return (
+    <JarvisDock
+      actions={[
+        {
+          glyph: "+",
+          id: "summon",
+          label: "Summon",
+          onActivate: noop,
+          tone: "primary",
+        },
+        {
+          badge: "3",
+          glyph: "✓",
+          id: "review",
+          label: "Review",
+          onActivate: noop,
+          tone: "success",
+        },
+        {
+          glyph: "↻",
+          id: "retry",
+          label: "Retry",
+          onActivate: noop,
+        },
+      ]}
+      onOpenPalette={noop}
+    />
+  );
+}
+
+function ViewportBookmarksPreview() {
+  return (
+    <div className="w-full max-w-[240px]">
+      <ViewportBookmarks
+        activeId="incidents"
+        bookmarks={[
+          { color: "#5b8def", id: "home", label: "Home base" },
+          {
+            color: "#10b981",
+            detail: "1.4× zoom",
+            id: "drilldown",
+            label: "Drill-down",
+          },
+          {
+            color: "#ef4444",
+            detail: "5 open",
+            id: "incidents",
+            label: "Incidents",
+          },
+        ]}
+        onSelect={noop}
+      />
+    </div>
+  );
+}
+
+function WorldBreadcrumbsPreview() {
+  return (
+    <WorldBreadcrumbs
+      crumbs={[
+        { id: "world", kind: "world", label: "Production" },
+        { id: "group", kind: "group", label: "Ingest cluster" },
+        { id: "run", kind: "run", label: "research-2025" },
+      ]}
+      onSelect={noop}
+    />
+  );
+}
+
+function AutoReloadPreview() {
+  return (
+    <div className="w-full max-w-[280px]">
+      <AutoReload defaultEnabled />
+    </div>
+  );
+}
+
+function PricingTablePreview() {
+  return (
+    <div className="w-full max-w-[260px] pt-3">
+      <PricingTable>
+        <PricingPlan
+          badge="Most Popular"
+          cta={{ label: "Start trial" }}
+          description="For teams"
+          features={[
+            { included: true, label: "Unlimited projects" },
+            { included: "100 GB", label: "Storage" },
+            { included: true, label: "API access" },
+          ]}
+          highlighted
+          name="Pro"
+          period="/month"
+          price="$29"
+        />
+      </PricingTable>
+    </div>
+  );
+}
+
+function TransactionListPreview() {
+  return (
+    <div className="w-full max-w-[300px]">
+      <TransactionList
+        currency="USD"
+        locale="en-US"
+        transactions={[
+          {
+            amountCents: 2000,
+            createdAt: Date.UTC(2025, 2, 10),
+            description: "Credit reload",
+            id: "1",
+            type: "credit",
+          },
+          {
+            amountCents: 150,
+            createdAt: Date.UTC(2025, 2, 8),
+            description: "API usage — March",
+            id: "2",
+            type: "debit",
+          },
+        ]}
+      >
+        <TransactionListPinned>
+          <TransactionListSubscriptionRow
+            amountCents={1200}
+            interval="month"
+            plan="AI OS Pro"
+            renewsAt={Date.UTC(2025, 3, 15)}
+            status="active"
+          />
+        </TransactionListPinned>
+      </TransactionList>
+    </div>
+  );
+}
+
+function CivilizationCardPreview() {
+  return (
+    <div className="w-full max-w-[280px]">
+      <CivilizationCard
+        achievements={["Aqueducts", "Roads", "Law"]}
+        capital="Rome"
+        color="red"
+        era={{ end: 476, start: -27 }}
+        leaders={["Augustus", "Trajan"]}
+        name="Roman Empire"
+        peakPopulation="70 million"
+        region="Mediterranean"
+      />
+    </div>
+  );
+}
+
+function EraComparisonPreview() {
+  return (
+    <div className="w-full max-w-[280px]">
+      <EraComparison>
+        <EraColumn
+          color="amber"
+          name="Renaissance"
+          period="1400–1600"
+          region="Europe"
+        >
+          <EraDomain name="Art">
+            <EraHighlight>Perspective painting, humanism</EraHighlight>
+            <div className="flex flex-wrap gap-1.5">
+              <EraFigure name="Leonardo da Vinci" />
+              <EraFigure name="Michelangelo" />
+            </div>
+          </EraDomain>
+          <EraDomain name="Science">
+            <EraHighlight>Heliocentrism, anatomy</EraHighlight>
+          </EraDomain>
+        </EraColumn>
+      </EraComparison>
+    </div>
+  );
+}
+
+function HistoricalFigureCardPreview() {
+  return (
+    <div className="w-full max-w-[280px]">
+      <HistoricalFigureCard
+        birth={{ place: "Vinci, Italy", year: 1452 }}
+        death={{ place: "Amboise, France", year: 1519 }}
+        era="Renaissance"
+        fields={["Art", "Science", "Anatomy"]}
+        name="Leonardo da Vinci"
+        quote={{
+          source: "Notebooks",
+          text: "Learning never exhausts the mind.",
+        }}
+        title="Polymath"
+        works={["Mona Lisa", "Vitruvian Man"]}
+      />
+    </div>
+  );
+}
+
+function KnowledgeCheckPreview() {
+  return (
+    <div className="w-full max-w-[300px]">
+      <KnowledgeCheck
+        questions={[
+          {
+            id: "react-purpose",
+            options: [
+              { correct: true, label: "A UI library", value: "ui" },
+              { label: "A database", value: "db" },
+              { label: "A backend framework", value: "backend" },
+            ],
+            question: "What is React?",
+            type: "multiple-choice",
+          },
+          {
+            answer: false,
+            id: "react-framework",
+            question: "React is a framework.",
+            type: "true-false",
+          },
+        ]}
+        title="Check your understanding"
+      />
+    </div>
+  );
+}
+
+function ParallelTimelinePreview() {
+  return (
+    <div className="w-full max-w-[340px]">
+      <ParallelTimeline
+        endYear={500}
+        startYear={-500}
+        tracks={[
+          {
+            color: "red",
+            events: [
+              { id: "augustus", title: "Augustus", year: -27 },
+              { id: "fall", title: "Fall of Rome", year: 476 },
+            ],
+            id: "rome",
+            name: "Rome",
+            region: "Mediterranean",
+          },
+          {
+            color: "amber",
+            events: [
+              { id: "qin", title: "Qin unifies China", year: -221 },
+              { id: "han-end", title: "End of Han", year: 220 },
+            ],
+            id: "china",
+            name: "China",
+            region: "East Asia",
+          },
+        ]}
+      />
+    </div>
+  );
+}
+
+// eslint-disable-next-line max-lines-per-function -- Switch statement mapping all components
+export function ComponentPreview({ componentName }: ComponentPreviewProps) {
+  switch (componentName) {
+    case "accordion":
+      return <AccordionPreview />;
+    case "activity-heatmap":
+      return <ActivityHeatmapPreview />;
+    case "activity-log":
+      return <ActivityLogPreview />;
+    case "alert":
+      return <AlertPreview />;
+    case "alert-dialog":
+      return <AlertDialogPreview />;
+    case "animated-text":
+      return <AnimatedTextPreview />;
+    case "area-chart":
+      return <AreaChartPreview />;
+    case "aspect-ratio":
+      return <AspectRatioPreview />;
+    case "avatar":
+      return <AvatarPreview />;
+    case "avatar-group":
+      return <AvatarGroupPreview />;
+    case "border-beam":
+      return <BorderBeamPreview />;
+    case "badge":
+      return <BadgePreview />;
+    case "bar-chart":
+      return <BarChartPreview />;
+    case "blog-card":
+      return <BlogCardPreview />;
+    case "breadcrumb":
+      return <BreadcrumbPreview />;
+    case "button":
+      return <ButtonPreview />;
+    case "anchor-port":
+      return (
+        <SimplePreview description="Connection port primitive for object graph cards and edges." />
+      );
+    case "callout":
+      return <CalloutPreview />;
+    case "calendar":
+      return <CalendarPreview />;
+    case "combobox":
+      return <ComboboxPreview />;
+    case "card":
+      return <CardPreview />;
+    case "data-list":
+      return <DataListPreview />;
+    case "data-table":
+      return <DataTablePreview />;
+    case "carousel":
+      return <CarouselPreview />;
+    case "canvas-shell":
+      return (
+        <SimplePreview description="Overlay shell for infinite-canvas workspaces with floating chrome regions." />
+      );
+    case "canvas-view":
+      return <CanvasViewPreview />;
+    case "connector-edge":
+      return (
+        <SimplePreview description="Curved connector edge for linking spatial objects on the canvas." />
+      );
+    case "category-filter":
+      return <CategoryFilterPreview />;
+    case "checkbox":
+      return <CheckboxPreview />;
+    case "collapsible":
+      return <CollapsiblePreview />;
+    case "checklist":
+      return <ChecklistPreview />;
+    case "code-block":
+      return <CodeBlockPreview />;
+    case "code-playground":
+      return <CodePlaygroundPreview />;
+    case "command":
+      return <CommandPreview />;
+    case "comparison":
+      return <ComparisonPreview />;
+    case "completion-dialog":
+      return (
+        <SimplePreview description="A dialog for displaying completion status with confetti animation." />
+      );
+    case "content-intro":
+      return (
+        <SimplePreview description="An introduction section with progress tracking and action buttons." />
+      );
+    case "context-menu":
+      return <ContextMenuPreview />;
+    case "countdown-timer":
+      return <CountdownTimerPreview />;
+    case "credit-badge":
+      return <CreditBadgePreview />;
+    case "dialog":
+      return <DialogPreview />;
+    case "drawer":
+      return <DrawerPreview />;
+    case "dropdown-menu":
+      return <DropdownMenuPreview />;
+    case "exercise":
+      return <ExercisePreview />;
+    case "faq":
+      return <FAQPreview />;
+    case "flashcard":
+      return <FlashcardPreview />;
+    case "edge-label":
+      return (
+        <SimplePreview description="Compact edge annotation badge used inside connector paths." />
+      );
+    case "file-upload":
+      return <FileUploadPreview />;
+    case "filter-bar":
+      return (
+        <SimplePreview description="A filter bar with search, sort, and filter controls." />
+      );
+    case "floating-action-button":
+      return <FloatingActionButtonPreview />;
+    case "form":
+      return <FormPreview />;
+    case "group-hull":
+      return (
+        <SimplePreview description="Dashed grouping surface for related spatial objects." />
+      );
+    case "horizontal-scroll-row":
+      return <HorizontalScrollRowPreview />;
+    case "hover-card":
+      return <HoverCardPreview />;
+    case "inline-input":
+      return <InlineInputPreview />;
+    case "input":
+      return <InputPreview />;
+    case "input-otp":
+      return <InputOTPPreview />;
+    case "date-picker":
+      return <DatePickerPreview />;
+    case "key-concept":
+      return <KeyConceptPreview />;
+    case "keyboard-shortcuts-help":
+      return <KeyboardShortcutsHelpPreview />;
+    case "left-rail":
+      return (
+        <SimplePreview description="Primary left-side rail for workspace navigation and context controls." />
+      );
+    case "lang-provider":
+      return <LangProviderPreview />;
+    case "learning-objectives":
+      return <LearningObjectivesPreview />;
+    case "line-chart":
+      return <LineChartPreview />;
+    case "marquee":
+      return <MarqueePreview />;
+    case "live-feed":
+      return <LiveFeedPreview />;
+    case "market-treemap":
+      return <MarketTreemapPreview />;
+    case "mdx-content":
+      return <MDXContentPreview />;
+    case "menubar":
+      return <MenubarPreview />;
+    case "mini-map-panel":
+      return (
+        <SimplePreview description="Viewport overview panel showing camera position within the world surface." />
+      );
+    case "metric-gauge":
+      return <MetricGaugePreview />;
+    case "model-selector":
+      return (
+        <SimplePreview description="A dialog for selecting AI models with search and filtering." />
+      );
+    case "multi-select":
+      return <MultiSelectPreview />;
+    case "tags-input":
+      return <TagsInputPreview />;
+    case "segmented-control":
+      return <SegmentedControlPreview />;
+    case "navbar-saas":
+      return (
+        <SimplePreview description="A responsive navigation bar for SaaS applications." />
+      );
+    case "navigation-menu":
+      return <NavigationMenuPreview />;
+    case "number-input":
+      return <NumberInputPreview />;
+    case "number-ticker":
+      return <NumberTickerPreview />;
+    case "object-card":
+      return (
+        <SimplePreview description="Object card primitive for spatial entities with metrics, actions, and ports." />
+      );
+    case "object-handle":
+      return (
+        <SimplePreview description="Drag/move handle affordance for manipulating canvas objects." />
+      );
+    case "order-book":
+      return <OrderBookPreview />;
+    case "pagination":
+      return <PaginationPreview />;
+    case "password-input":
+      return <PasswordInputPreview />;
+    case "popover":
+      return <PopoverPreview />;
+    case "pro-tip":
+      return <ProTipPreview />;
+    case "profile-section":
+      return <ProfileSectionPreview />;
+    case "progress-bar":
+      return <ProgressBarPreview />;
+    case "progress-card":
+      return (
+        <SimplePreview description="A card component with progress tracking." />
+      );
+    case "quiz":
+      return <QuizPreview />;
+    case "radio-group":
+      return <RadioGroupPreview />;
+    case "resizable":
+      return <ResizablePreview />;
+    case "right-dock":
+      return (
+        <SimplePreview description="Right-side dock for inspector, agent, or activity panels in the workspace shell." />
+      );
+    case "scroll-area":
+      return <ScrollAreaPreview />;
+    case "search-bar":
+      return <SearchBarPreview />;
+    case "search-dialog":
+      return (
+        <SimplePreview description="A command palette style search dialog." />
+      );
+    case "scope-selector":
+      return <ScopeSelectorPreview />;
+    case "select":
+      return <SelectPreview />;
+    case "separator":
+      return <SeparatorPreview />;
+    case "severity-badge":
+      return <SeverityBadgePreview />;
+    case "share-section":
+      return <ShareSectionPreview />;
+    case "sheet":
+      return <SheetPreview />;
+    case "sidebar":
+      return <SidebarPreview />;
+    case "skeleton":
+      return <SkeletonPreview />;
+    case "slider":
+      return <SliderPreview />;
+    case "spinner":
+      return <SpinnerPreview />;
+    case "stat-card":
+      return <StatCardPreview />;
+    case "status-board":
+      return <StatusBoardPreview />;
+    case "sidebar-provider":
       return <SidebarProviderPreview />;
     case "sidebar-toggle":
       return <SidebarTogglePreview />;
@@ -2516,6 +5690,342 @@ export function ComponentPreview({ componentName }: ComponentPreviewProps) {
       );
     case "world-clock-bar":
       return <WorldClockBarPreview />;
+    case "animated-beam":
+      return <AnimatedBeamPreview />;
+    case "choropleth-map":
+      return <ChoroplethMapPreview />;
+    case "chronological-timeline":
+      return <ChronologicalTimelinePreview />;
+    case "floating-toolbar":
+      return <FloatingToolbarPreview />;
+    case "follow-mode":
+      return <FollowModePreview />;
+    case "geography-quiz-map":
+      return <GeographyQuizMapPreview />;
+    case "glass-progress":
+      return <GlassProgressPreview />;
+    case "globe-3d":
+      return <Globe3dPreview />;
+    case "handoff-beacon":
+      return <HandoffBeaconPreview />;
+    case "heat-map-overlay":
+      return <HeatMapOverlayPreview />;
+    case "historic-timeline":
+      return <HistoricTimelinePreview />;
+    case "interactive-timeline":
+      return <InteractiveTimelinePreview />;
+    case "map-2d":
+      return <Map2dPreview />;
+    case "map-timeline":
+      return <MapTimelinePreview />;
+    case "primary-source-viewer":
+      return <PrimarySourceViewerPreview />;
+    case "route-map":
+      return <RouteMapPreview />;
+    case "scroll-progress":
+      return (
+        <SimplePreview description="A fixed progress bar pinned to the top of the page that fills as the reader scrolls." />
+      );
+    case "selection-halo":
+      return <SelectionHaloPreview />;
+    case "snap-guides":
+      return <SnapGuidesPreview />;
+    case "story-map":
+      return <StoryMapPreview />;
+    case "tree-view":
+      return <TreeViewPreview />;
+    case "alert-pulse":
+      return <AlertPulsePreview />;
+    case "animated-grid-pattern":
+      return <AnimatedGridPatternPreview />;
+    case "card-flip":
+      return <CardFlipPreview />;
+    case "comment-pin":
+      return <CommentPinPreview />;
+    case "context-lens":
+      return <ContextLensPreview />;
+    case "cursor":
+      return <CursorPreview />;
+    case "dot-pattern":
+      return <DotPatternPreview />;
+    case "glass-card":
+      return <GlassCardPreview />;
+    case "glass-panel":
+      return <GlassPanelPreview />;
+    case "infinite-plane":
+      return <InfinitePlanePreview />;
+    case "liquid-glass":
+      return <LiquidGlassPreview />;
+    case "live-cursor":
+      return <LiveCursorPreview />;
+    case "magnetic":
+      return <MagneticPreview />;
+    case "magnetic-button":
+      return <MagneticButtonPreview />;
+    case "meteors":
+      return <MeteorsPreview />;
+    case "multi-select-lasso":
+      return <MultiSelectLassoPreview />;
+    case "particles":
+      return <ParticlesPreview />;
+    case "playback-ghost":
+      return <PlaybackGhostPreview />;
+    case "progressive-blur":
+      return <ProgressiveBlurPreview />;
+    case "selection-presence":
+      return <SelectionPresencePreview />;
+    case "shimmer-button":
+      return <ShimmerButtonPreview />;
+    case "shine-border":
+      return <ShineBorderPreview />;
+    case "shiny-button":
+      return <ShinyButtonPreview />;
+    case "sparkles":
+      return <SparklesPreview />;
+    case "spotlight-card":
+      return <SpotlightCardPreview />;
+    case "state-badge-overlay":
+      return <StateBadgeOverlayPreview />;
+    case "theme-preset-provider":
+      return <ThemePresetProviderPreview />;
+    case "theme-switcher":
+      return <ThemeSwitcherPreview />;
+    case "thread-bubble":
+      return <ThreadBubblePreview />;
+    case "tilt-card":
+      return <TiltCardPreview />;
+    case "truncated-text":
+      return <TruncatedTextPreview />;
+    case "animated-list":
+      return <AnimatedListPreview />;
+    case "animated-testimonials":
+      return <AnimatedTestimonialsPreview />;
+    case "bento-grid":
+      return <BentoGridPreview />;
+    case "blur-reveal":
+      return <BlurRevealPreview />;
+    case "document-sibling-nav":
+      return <DocumentSiblingNavPreview />;
+    case "expandable-cards":
+      return <ExpandableCardsPreview />;
+    case "object-inspector":
+      return <ObjectInspectorPreview />;
+    case "plan-badge":
+      return <PlanBadgePreview />;
+    case "policy-delivery-panel":
+      return <PolicyDeliveryPanelPreview />;
+    case "property-section":
+      return <PropertySectionPreview />;
+    case "relationship-inspector":
+      return <RelationshipInspectorPreview />;
+    case "reveal-text":
+      return <RevealTextPreview />;
+    case "role-badge":
+      return <RoleBadgePreview />;
+    case "routing-assignment-panel":
+      return <RoutingAssignmentPanelPreview />;
+    case "runtime-overview-panel":
+      return <RuntimeOverviewPanelPreview />;
+    case "scramble-text":
+      return <ScrambleTextPreview />;
+    case "shimmer-text":
+      return <ShimmerTextPreview />;
+    case "spinning-text":
+      return <SpinningTextPreview />;
+    case "subscription-card":
+      return <SubscriptionCardPreview />;
+    case "text-animate":
+      return <TextAnimatePreview />;
+    case "text-reveal":
+      return <TextRevealPreview />;
+    case "text-shimmer":
+      return <TextShimmerPreview />;
+    case "timeline":
+      return <TimelinePreview />;
+    case "typewriter":
+      return <TypewriterPreview />;
+    case "bottom-activity-strip":
+      return <BottomActivityStripPreview />;
+    case "candlestick-chart":
+      return <CandlestickChartPreview />;
+    case "contribution-graph":
+      return <ContributionGraphPreview />;
+    case "flow-diagram":
+      return <FlowDiagramPreview />;
+    case "gantt-chart":
+      return <GanttChartPreview />;
+    case "gauge-chart":
+      return <GaugeChartPreview />;
+    case "heat-overlay":
+      return <HeatOverlayPreview />;
+    case "metric-cluster":
+      return <MetricClusterPreview />;
+    case "overview-board":
+      return <OverviewBoardPreview />;
+    case "pie-chart":
+      return <PieChartPreview />;
+    case "presence-stack":
+      return <PresenceStackPreview />;
+    case "presence-sync-indicator":
+      return <PresenceSyncIndicatorPreview />;
+    case "radar-chart":
+      return <RadarChartPreview />;
+    case "run-timeline":
+      return <RunTimelinePreview />;
+    case "sankey-chart":
+      return <SankeyChartPreview />;
+    case "sparkline-grid":
+      return <SparklineGridPreview />;
+    case "sticky-metric":
+      return <StickyMetricPreview />;
+    case "threshold-ring":
+      return <ThresholdRingPreview />;
+    case "ticker-tape":
+      return <TickerTapePreview />;
+    case "button-group":
+      return <ButtonGroupPreview />;
+    case "checkbox-group":
+      return <CheckboxGroupPreview />;
+    case "color-picker":
+      return <ColorPickerPreview />;
+    case "date-field":
+      return <DateFieldPreview />;
+    case "date-range-picker":
+      return <DateRangePickerPreview />;
+    case "field":
+      return <FieldPreview />;
+    case "fieldset":
+      return <FieldsetPreview />;
+    case "input-group":
+      return <InputGroupPreview />;
+    case "item":
+      return <ItemPreview />;
+    case "list-box":
+      return <ListBoxPreview />;
+    case "native-select":
+      return <NativeSelectPreview />;
+    case "newsletter-signup":
+      return <NewsletterSignupPreview />;
+    case "phone-input":
+      return <PhoneInputPreview />;
+    case "range-calendar":
+      return <RangeCalendarPreview />;
+    case "search-field":
+      return <SearchFieldPreview />;
+    case "tag-group":
+      return <TagGroupPreview />;
+    case "text-field":
+      return <TextFieldPreview />;
+    case "time-field":
+      return <TimeFieldPreview />;
+    case "time-picker":
+      return <TimePickerPreview />;
+    case "timeline-scrubber":
+      return <TimelineScrubberPreview />;
+    case "agent-activity":
+      return <AgentActivityPreview />;
+    case "ai-artifact":
+      return <AiArtifactPreview />;
+    case "ai-sidebar":
+      return <AiSidebarPreview />;
+    case "chain-of-thought":
+      return <ChainOfThoughtPreview />;
+    case "chat-dock-section":
+      return <ChatDockSectionPreview />;
+    case "model-comparison":
+      return <ModelComparisonPreview />;
+    case "prompt-input":
+      return <PromptInputPreview />;
+    case "prompt-templates":
+      return <PromptTemplatesPreview />;
+    case "reasoning":
+      return <ReasoningPreview />;
+    case "ai-chat-input":
+      return <AiChatInputPreview />;
+    case "ai-message-bubble":
+      return <AiMessageBubblePreview />;
+    case "ai-source-citation":
+      return <AiSourceCitationPreview />;
+    case "ai-streaming-text":
+      return <AiStreamingTextPreview />;
+    case "ai-tool-call-display":
+      return <AiToolCallDisplayPreview />;
+    case "annotation":
+      return <AnnotationPreview />;
+    case "conversation-thread":
+      return <ConversationThreadPreview />;
+    case "curriculum":
+      return <CurriculumPreview />;
+    case "progress-tracker":
+      return <ProgressTrackerPreview />;
+    case "rating":
+      return <RatingPreview />;
+    case "stepper":
+      return <StepperPreview />;
+    case "tour":
+      return <TourPreview />;
+    case "banner":
+      return <BannerPreview />;
+    case "cookie-consent":
+      return <CookieConsentPreview />;
+    case "copy-button":
+      return <CopyButtonPreview />;
+    case "empty-state":
+      return <EmptyStatePreview />;
+    case "grid":
+      return <GridPreview />;
+    case "kbd":
+      return <KbdPreview />;
+    case "label":
+      return <LabelPreview />;
+    case "link":
+      return <LinkPreview />;
+    case "meter":
+      return <MeterPreview />;
+    case "panel":
+      return <PanelPreview />;
+    case "qr-code":
+      return <QrCodePreview />;
+    case "switch":
+      return <SwitchPreview />;
+    case "toolbar":
+      return <ToolbarPreview />;
+    case "typography":
+      return <TypographyPreview />;
+    case "animated-tooltip":
+      return <AnimatedTooltipPreview />;
+    case "share-dialog":
+      return <ShareDialogPreview />;
+    case "animated-tabs":
+      return <AnimatedTabsPreview />;
+    case "bottom-bar":
+      return <BottomBarPreview />;
+    case "dock":
+      return <DockPreview />;
+    case "floating-navbar":
+      return <FloatingNavbarPreview />;
+    case "jarvis-dock":
+      return <JarvisDockPreview />;
+    case "viewport-bookmarks":
+      return <ViewportBookmarksPreview />;
+    case "world-breadcrumbs":
+      return <WorldBreadcrumbsPreview />;
+    case "auto-reload":
+      return <AutoReloadPreview />;
+    case "pricing-table":
+      return <PricingTablePreview />;
+    case "transaction-list":
+      return <TransactionListPreview />;
+    case "civilization-card":
+      return <CivilizationCardPreview />;
+    case "era-comparison":
+      return <EraComparisonPreview />;
+    case "historical-figure-card":
+      return <HistoricalFigureCardPreview />;
+    case "knowledge-check":
+      return <KnowledgeCheckPreview />;
+    case "parallel-timeline":
+      return <ParallelTimelinePreview />;
     default:
       return <PlaceholderPreview componentName={componentName} />;
   }

From 434803bef2afdffcc8a2a9a0614dc0b49627e9ed Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:20:28 +0200
Subject: [PATCH 05/16] feat(registry): shared ComponentCard + live previews on
 the AI hub
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extract one ComponentCard (live preview + title + description + story count)
and use it on the components index, the per-family pages, and the /ai hub —
so /ai's curated groups now show real component previews like every other
family, and the three surfaces share one card (removes the duplicated markup;
card title is a <p>, not a heading-inside-link).

Also add CollectionPage + ItemList JSON-LD to /ai (alongside its FAQ +
breadcrumb), so the AI hub is the richest family page: curated copy + previews
+ FAQ + ItemList structured data.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 apps/registry/app/[locale]/ai/page.tsx        | 69 ++++++++++---------
 .../registry/app/[locale]/components/page.tsx | 51 +++-----------
 .../app/[locale]/families/[category]/page.tsx | 52 +++-----------
 .../component-card/component-card.tsx         | 69 +++++++++++++++++++
 .../components/component-card/index.ts        |  1 +
 5 files changed, 124 insertions(+), 118 deletions(-)
 create mode 100644 apps/registry/components/component-card/component-card.tsx
 create mode 100644 apps/registry/components/component-card/index.ts

diff --git a/apps/registry/app/[locale]/ai/page.tsx b/apps/registry/app/[locale]/ai/page.tsx
index 47dafd29..9d1e3168 100644
--- a/apps/registry/app/[locale]/ai/page.tsx
+++ b/apps/registry/app/[locale]/ai/page.tsx
@@ -4,6 +4,7 @@ import type { Metadata } from "next";
 import Link from "next/link";
 import { setRequestLocale } from "next-intl/server";
 
+import { ComponentCard } from "@/components/component-card";
 import { Footer } from "@/components/footer/footer";
 import type { Locale } from "@/i18n/routing";
 import {
@@ -11,7 +12,12 @@ import {
   getAiComponentSlugs,
   resolveAiComponent,
 } from "@/lib/ai-seo";
-import { breadcrumbLd, faqPageLd, jsonLdScriptAttributes } from "@/lib/jsonld";
+import {
+  breadcrumbLd,
+  collectionPageLd,
+  faqPageLd,
+  jsonLdScriptAttributes,
+} from "@/lib/jsonld";
 import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
 import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
 import { getSidebarSections } from "@/lib/sidebar-sections";
@@ -73,35 +79,15 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   };
 }
 
-function ComponentCard({ locale, slug }: { locale: Locale; slug: string }) {
-  const resolved = resolveAiComponent(slug);
-  if (!resolved) {
-    return null;
-  }
-  return (
-    <li>
-      <Link
-        className="group flex h-full flex-col rounded-lg border border-border p-5 hover:border-foreground/40"
-        href={localizePathname(`/components/${resolved.name}`, locale)}
-      >
-        <p className="font-medium">{resolved.title}</p>
-        <p className="mt-2 flex-1 text-sm text-muted-foreground">
-          {resolved.description}
-        </p>
-        <span className="mt-4 inline-flex items-center gap-1 text-xs font-medium text-foreground">
-          View component
-          <ArrowRight className="size-3 transition-transform group-hover:translate-x-0.5" />
-        </span>
-      </Link>
-    </li>
-  );
-}
-
 export default async function AiHubPage({ params }: Props) {
   const { locale } = await params;
   setRequestLocale(locale);
 
-  const componentCount = getAiComponentSlugs().length;
+  const aiComponents = getAiComponentSlugs().flatMap((slug) => {
+    const resolved = resolveAiComponent(slug);
+    return resolved ? [resolved] : [];
+  });
+  const componentCount = aiComponents.length;
 
   return (
     <>
@@ -111,6 +97,15 @@ export default async function AiHubPage({ params }: Props) {
             { name: "Home", url: SITE_URL },
             { name: "AI components", url: `${SITE_URL}${PATHNAME}` },
           ]),
+          collectionPageLd({
+            description: DESCRIPTION,
+            items: aiComponents.map((component) => ({
+              name: component.title,
+              url: `${SITE_URL}/components/${component.name}`,
+            })),
+            title: TITLE,
+            url: `${SITE_URL}${PATHNAME}`,
+          }),
           faqPageLd(FAQ),
         ])}
       />
@@ -167,11 +162,23 @@ export default async function AiHubPage({ params }: Props) {
                   <p className="mt-1 max-w-2xl text-sm text-muted-foreground">
                     {group.blurb}
                   </p>
-                  <ul className="mt-5 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
-                    {group.slugs.map((slug) => (
-                      <ComponentCard key={slug} locale={locale} slug={slug} />
-                    ))}
-                  </ul>
+                  <div className="mt-5 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+                    {group.slugs.map((slug) => {
+                      const resolved = resolveAiComponent(slug);
+                      if (!resolved) {
+                        return null;
+                      }
+                      return (
+                        <ComponentCard
+                          description={resolved.description}
+                          key={slug}
+                          locale={locale}
+                          slug={resolved.name}
+                          title={resolved.title}
+                        />
+                      );
+                    })}
+                  </div>
                 </div>
               ))}
             </div>
diff --git a/apps/registry/app/[locale]/components/page.tsx b/apps/registry/app/[locale]/components/page.tsx
index 80840c89..19eb9ff3 100644
--- a/apps/registry/app/[locale]/components/page.tsx
+++ b/apps/registry/app/[locale]/components/page.tsx
@@ -3,9 +3,8 @@ import type { Metadata } from "next";
 import Link from "next/link";
 import { setRequestLocale } from "next-intl/server";
 
-import { ComponentThumbnail } from "@/components/component-thumbnail";
+import { ComponentCard } from "@/components/component-card";
 import type { Locale } from "@/i18n/routing";
-import componentMetadata from "@/lib/component-metadata.json";
 import { getPageContent } from "@/lib/content";
 import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
 import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
@@ -20,15 +19,6 @@ type Props = {
   readonly params: Promise<{ locale: Locale }>;
 };
 
-const metadata_map = componentMetadata as Record<
-  string,
-  {
-    description: string;
-    stories: { id: string; name: string }[];
-    title: string;
-  }
->;
-
 export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const { locale } = await params;
   const { frontmatter } = await getPageContent("components", locale);
@@ -85,38 +75,13 @@ export default async function ComponentsPage({ params }: Props) {
                 </Link>
               </h2>
               <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-                {group.items.map((component) => {
-                  const meta = metadata_map[component.name];
-                  const storyCount = meta?.stories?.length ?? 0;
-
-                  return (
-                    <Link
-                      className="group flex flex-col rounded-lg border bg-card hover:border-foreground/20 transition-colors overflow-hidden"
-                      href={localizePathname(
-                        `/components/${component.name}`,
-                        locale,
-                      )}
-                      key={component.name}
-                    >
-                      <ComponentThumbnail componentName={component.name} />
-                      <div className="flex flex-1 flex-col p-4">
-                        <h3 className="text-sm font-medium group-hover:text-foreground transition-colors">
-                          {component.title}
-                        </h3>
-                        {meta?.description ? (
-                          <p className="text-xs text-muted-foreground mt-1 line-clamp-2">
-                            {meta.description}
-                          </p>
-                        ) : null}
-                        {storyCount > 0 ? (
-                          <span className="mt-3 text-xs text-muted-foreground">
-                            {`${storyCount} ${storyCount === 1 ? "story" : "stories"}`}
-                          </span>
-                        ) : null}
-                      </div>
-                    </Link>
-                  );
-                })}
+                {group.items.map((component) => (
+                  <ComponentCard
+                    key={component.name}
+                    locale={locale}
+                    slug={component.name}
+                  />
+                ))}
               </div>
             </section>
           ))}
diff --git a/apps/registry/app/[locale]/families/[category]/page.tsx b/apps/registry/app/[locale]/families/[category]/page.tsx
index f1df0237..aa50d291 100644
--- a/apps/registry/app/[locale]/families/[category]/page.tsx
+++ b/apps/registry/app/[locale]/families/[category]/page.tsx
@@ -1,12 +1,10 @@
 import { Breadcrumb, Sidebar } from "@vllnt/ui";
 import type { Metadata } from "next";
-import Link from "next/link";
 import { notFound } from "next/navigation";
 import { setRequestLocale } from "next-intl/server";
 
-import { ComponentThumbnail } from "@/components/component-thumbnail";
+import { ComponentCard } from "@/components/component-card";
 import { type Locale, routing } from "@/i18n/routing";
-import componentMetadata from "@/lib/component-metadata.json";
 import {
   breadcrumbLd,
   collectionPageLd,
@@ -25,15 +23,6 @@ type Props = {
   readonly params: Promise<{ category: string; locale: Locale }>;
 };
 
-const metadata_map = componentMetadata as Record<
-  string,
-  {
-    description: string;
-    stories: { id: string; name: string }[];
-    title: string;
-  }
->;
-
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
 
 /**
@@ -149,38 +138,13 @@ export default async function FamilyPage({ params }: Props) {
           </div>
 
           <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-            {group.items.map((component) => {
-              const meta = metadata_map[component.name];
-              const storyCount = meta?.stories?.length ?? 0;
-
-              return (
-                <Link
-                  className="group flex flex-col rounded-lg border bg-card hover:border-foreground/20 transition-colors overflow-hidden"
-                  href={localizePathname(
-                    `/components/${component.name}`,
-                    locale,
-                  )}
-                  key={component.name}
-                >
-                  <ComponentThumbnail componentName={component.name} />
-                  <div className="flex flex-1 flex-col p-4">
-                    <h2 className="text-sm font-medium group-hover:text-foreground transition-colors">
-                      {component.title}
-                    </h2>
-                    {meta?.description ? (
-                      <p className="text-xs text-muted-foreground mt-1 line-clamp-2">
-                        {meta.description}
-                      </p>
-                    ) : null}
-                    {storyCount > 0 ? (
-                      <span className="mt-3 text-xs text-muted-foreground">
-                        {`${storyCount} ${storyCount === 1 ? "story" : "stories"}`}
-                      </span>
-                    ) : null}
-                  </div>
-                </Link>
-              );
-            })}
+            {group.items.map((component) => (
+              <ComponentCard
+                key={component.name}
+                locale={locale}
+                slug={component.name}
+              />
+            ))}
           </div>
         </div>
       </main>
diff --git a/apps/registry/components/component-card/component-card.tsx b/apps/registry/components/component-card/component-card.tsx
new file mode 100644
index 00000000..651b5520
--- /dev/null
+++ b/apps/registry/components/component-card/component-card.tsx
@@ -0,0 +1,69 @@
+import Link from "next/link";
+
+import { ComponentThumbnail } from "@/components/component-thumbnail";
+import type { Locale } from "@/i18n/routing";
+import componentMetadata from "@/lib/component-metadata.json";
+import { localizePathname } from "@/lib/seo";
+
+const META = componentMetadata as Record<
+  string,
+  {
+    description?: string;
+    stories?: { id: string; name: string }[];
+    title?: string;
+  }
+>;
+
+type ComponentCardProps = {
+  /** Optional description override (e.g. AI-SEO copy); falls back to registry metadata. */
+  readonly description?: string;
+  readonly locale: Locale;
+  /** Registry slug — links to `/components/<slug>` and resolves the preview. */
+  readonly slug: string;
+  /** Optional title override; falls back to registry metadata. */
+  readonly title?: string;
+};
+
+/**
+ * Shared gallery card: a live component preview above its title, description, and
+ * story count, linking to the component page. Used by the components index, the
+ * per-family landing pages, and the AI hub so every surface looks identical.
+ *
+ * @param slug - registry component slug
+ * @param locale - active locale for the link
+ */
+export function ComponentCard({
+  description,
+  locale,
+  slug,
+  title,
+}: ComponentCardProps) {
+  const meta = META[slug];
+  const displayTitle = title ?? meta?.title ?? slug;
+  const displayDescription = description ?? meta?.description;
+  const storyCount = meta?.stories?.length ?? 0;
+
+  return (
+    <Link
+      className="group flex flex-col overflow-hidden rounded-lg border bg-card transition-colors hover:border-foreground/20"
+      href={localizePathname(`/components/${slug}`, locale)}
+    >
+      <ComponentThumbnail componentName={slug} />
+      <div className="flex flex-1 flex-col p-4">
+        <p className="text-sm font-medium transition-colors group-hover:text-foreground">
+          {displayTitle}
+        </p>
+        {displayDescription ? (
+          <p className="mt-1 line-clamp-2 text-xs text-muted-foreground">
+            {displayDescription}
+          </p>
+        ) : null}
+        {storyCount > 0 ? (
+          <span className="mt-3 text-xs text-muted-foreground">
+            {`${storyCount} ${storyCount === 1 ? "story" : "stories"}`}
+          </span>
+        ) : null}
+      </div>
+    </Link>
+  );
+}
diff --git a/apps/registry/components/component-card/index.ts b/apps/registry/components/component-card/index.ts
new file mode 100644
index 00000000..22addd21
--- /dev/null
+++ b/apps/registry/components/component-card/index.ts
@@ -0,0 +1 @@
+export { ComponentCard } from "./component-card";

From 4ffdeaab6a5fd4ab239d8af4e29eb1183e522c5a Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Tue, 30 Jun 2026 16:20:50 +0200
Subject: [PATCH 06/16] fix(registry): move AI components out of the learning
 family

Seven AI components (ai-chat-input, ai-message-bubble, ai-source-citation,
ai-streaming-text, ai-tool-call-display, conversation-thread, thinking-block)
were categorized as `learning`; model-selector was in `form`. Recategorize all
eight to `ai` so they group under the AI family in the sidebar and registry.
AI family: 9 -> 17. Regenerated registry.json + component-metadata.json.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 apps/registry/lib/component-metadata.json | 16 ++++++++--------
 apps/registry/registry.json               | 18 +++++++++---------
 2 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/apps/registry/lib/component-metadata.json b/apps/registry/lib/component-metadata.json
index 12f43c5a..4ebd0f8f 100644
--- a/apps/registry/lib/component-metadata.json
+++ b/apps/registry/lib/component-metadata.json
@@ -101,7 +101,7 @@
     "title": "AI Artifact"
   },
   "ai-chat-input": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-chatinput--default",
     "description": "Prompt composer for conversational interfaces with helper text, toolbar actions, and submit states.",
     "name": "ai-chat-input",
@@ -118,7 +118,7 @@
     "title": "AI Chat Input"
   },
   "ai-message-bubble": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-messagebubble--default",
     "description": "Chat bubble for assistant, user, tool, and system messages using the current design system surfaces.",
     "name": "ai-message-bubble",
@@ -160,7 +160,7 @@
     "title": "AI Sidebar"
   },
   "ai-source-citation": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "designingreadableaiconversations--default",
     "description": "Compact source reference card for AI answers with a title, origin label, and optional excerpt.",
     "name": "ai-source-citation",
@@ -173,7 +173,7 @@
     "title": "AI Source Citation"
   },
   "ai-streaming-text": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-streamingtext--default",
     "description": "Readable text block for partial assistant output with an optional live cursor while tokens stream in.",
     "name": "ai-streaming-text",
@@ -190,7 +190,7 @@
     "title": "AI Streaming Text"
   },
   "ai-tool-call-display": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-toolcalldisplay--default",
     "description": "Structured card for tool invocation traces, statuses, serialized input, and returned output.",
     "name": "ai-tool-call-display",
@@ -1289,7 +1289,7 @@
     "title": "Contribution Graph"
   },
   "conversation-thread": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-conversationthread--default",
     "description": "Compound component family for AI chat UIs that orchestrates auto-scroll, streaming indicators, empty states, and message rendering.",
     "name": "conversation-thread",
@@ -2875,7 +2875,7 @@
     "title": "Model Comparison"
   },
   "model-selector": {
-    "category": "form",
+    "category": "ai",
     "defaultStoryId": "form-modelselector--default",
     "description": "Dropdown selector for choosing AI models.",
     "name": "model-selector",
@@ -4893,7 +4893,7 @@
     "title": "Theme Toggle"
   },
   "thinking-block": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "learning-thinkingblock--default",
     "description": "Collapsible block showing AI thinking/reasoning with streaming support.",
     "name": "thinking-block",
diff --git a/apps/registry/registry.json b/apps/registry/registry.json
index e3f9bf5e..85dd4521 100644
--- a/apps/registry/registry.json
+++ b/apps/registry/registry.json
@@ -116,7 +116,7 @@
         "@vllnt/ui@^0.3.0",
         "lucide-react"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -136,7 +136,7 @@
         "@vllnt/ui@^0.3.0",
         "class-variance-authority"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -176,7 +176,7 @@
         "@vllnt/ui@^0.3.0",
         "lucide-react"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -195,7 +195,7 @@
       "dependencies": [
         "@vllnt/ui@^0.3.0"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -216,7 +216,7 @@
         "class-variance-authority",
         "lucide-react"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -1548,7 +1548,7 @@
       "dependencies": [
         "@vllnt/ui@^0.3.0"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -3242,7 +3242,7 @@
       "dependencies": [
         "@vllnt/ui@^0.3.0"
       ],
-      "category": "form",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -5416,7 +5416,7 @@
         "@vllnt/ui@^0.3.0",
         "lucide-react"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -6108,5 +6108,5 @@
     }
   ],
   "version": "0.3.0",
-  "generatedAt": "2026-06-27T20:12:37.143Z"
+  "generatedAt": "2026-06-30T14:18:02.601Z"
 }

From c662555b067b7f40a22bc2b0979b40128faf70f5 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Wed, 1 Jul 2026 21:17:41 +0200
Subject: [PATCH 07/16] fix(registry): scale gallery previews to fit their card
 (no clipping)

Component previews rendered at natural size in a fixed 176px card and got
clipped / overlapped when larger than the box. Wrap the preview in a FitPreview
that measures the natural content size (ResizeObserver) and applies a centered
transform: scale so the WHOLE component fits (contain, never upscaled past 1x).
Applies everywhere the thumbnail is used: /components, /families/*, /ai.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 .../component-thumbnail.tsx                   | 66 ++++++++++++++++++-
 1 file changed, 64 insertions(+), 2 deletions(-)

diff --git a/apps/registry/components/component-thumbnail/component-thumbnail.tsx b/apps/registry/components/component-thumbnail/component-thumbnail.tsx
index 404099aa..044bc065 100644
--- a/apps/registry/components/component-thumbnail/component-thumbnail.tsx
+++ b/apps/registry/components/component-thumbnail/component-thumbnail.tsx
@@ -22,6 +22,64 @@ type ComponentThumbnailProps = {
  *
  * @param componentName - Registry slug used to resolve the matching preview.
  */
+/**
+ * Scales its child down (never up) so the whole preview fits the card without
+ * clipping or overflow. Measures the natural content size with a ResizeObserver
+ * and applies a centered `transform: scale` — `contain` behaviour for a live
+ * component. Large components render small but complete; the detail page shows
+ * them full size.
+ */
+function FitPreview({ children }: { children: React.ReactNode }) {
+  const boxRef = React.useRef<HTMLDivElement>(null);
+  const stageRef = React.useRef<HTMLDivElement>(null);
+  const [scale, setScale] = React.useState(1);
+
+  React.useEffect(() => {
+    const box = boxRef.current;
+    const stage = stageRef.current;
+    if (!box || !stage) {
+      return;
+    }
+
+    const observer = new ResizeObserver(() => {
+      const availableWidth = box.clientWidth - 32;
+      const availableHeight = box.clientHeight - 32;
+      const contentWidth = stage.scrollWidth;
+      const contentHeight = stage.scrollHeight;
+      if (contentWidth === 0 || contentHeight === 0) {
+        return;
+      }
+      const next = Math.min(
+        availableWidth / contentWidth,
+        availableHeight / contentHeight,
+        1,
+      );
+      setScale(next > 0 ? next : 1);
+    });
+
+    observer.observe(box);
+    observer.observe(stage);
+    return () => {
+      observer.disconnect();
+    };
+  }, []);
+
+  return (
+    <div
+      className="flex h-full w-full items-center justify-center overflow-hidden"
+      ref={boxRef}
+    >
+      <div
+        className="shrink-0"
+        ref={stageRef}
+        style={{ transform: `scale(${scale})` }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+
 export function ComponentThumbnail({
   componentName,
 }: ComponentThumbnailProps): React.ReactElement {
@@ -53,11 +111,15 @@ export function ComponentThumbnail({
 
   return (
     <div
-      className="pointer-events-none flex h-44 items-center justify-center overflow-hidden border-b bg-muted/30 p-4 [contain:layout]"
+      className="pointer-events-none h-44 overflow-hidden border-b bg-muted/30 [contain:layout]"
       inert
       ref={containerRef}
     >
-      {isVisible ? <ComponentPreview componentName={componentName} /> : null}
+      {isVisible ? (
+        <FitPreview>
+          <ComponentPreview componentName={componentName} />
+        </FitPreview>
+      ) : null}
     </div>
   );
 }

From 255935fa48b8d3eb51035e08b36fa9b943315cd3 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 15:32:00 +0200
Subject: [PATCH 08/16] feat(registry): SEO copy + FAQ on every family page

Each /families/[category] page was a bare hero + grid. Give every family the
same SEO treatment as /ai: an editorial intro paragraph and a short FAQ, with
FAQPage JSON-LD alongside the existing CollectionPage + breadcrumb. Intro also
becomes the meta description. Copy lives in lib/family-copy.ts (one entry per
family; falls back to the one-line description if absent).

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 .../app/[locale]/families/[category]/page.tsx |  25 ++-
 apps/registry/lib/family-copy.ts              | 178 ++++++++++++++++++
 2 files changed, 201 insertions(+), 2 deletions(-)
 create mode 100644 apps/registry/lib/family-copy.ts

diff --git a/apps/registry/app/[locale]/families/[category]/page.tsx b/apps/registry/app/[locale]/families/[category]/page.tsx
index aa50d291..fa5e7903 100644
--- a/apps/registry/app/[locale]/families/[category]/page.tsx
+++ b/apps/registry/app/[locale]/families/[category]/page.tsx
@@ -5,9 +5,11 @@ import { setRequestLocale } from "next-intl/server";
 
 import { ComponentCard } from "@/components/component-card";
 import { type Locale, routing } from "@/i18n/routing";
+import { getFamilyCopy } from "@/lib/family-copy";
 import {
   breadcrumbLd,
   collectionPageLd,
+  faqPageLd,
   jsonLdScriptAttributes,
 } from "@/lib/jsonld";
 import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
@@ -56,7 +58,8 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
 
   const pathname = `/families/${category}`;
   const title = `${group.label} components`;
-  const description = getCategoryDescription(group.category);
+  const copy = getFamilyCopy(group.category);
+  const description = copy?.intro ?? getCategoryDescription(group.category);
 
   return {
     alternates: {
@@ -88,7 +91,8 @@ export default async function FamilyPage({ params }: Props) {
     notFound();
   }
 
-  const description = getCategoryDescription(group.category);
+  const copy = getFamilyCopy(group.category);
+  const description = copy?.intro ?? getCategoryDescription(group.category);
   const pathname = `/families/${category}`;
 
   return (
@@ -109,6 +113,7 @@ export default async function FamilyPage({ params }: Props) {
             title: `${group.label} components`,
             url: `${SITE_URL}${pathname}`,
           }),
+          ...(copy && copy.faq.length > 0 ? [faqPageLd(copy.faq)] : []),
         ])}
       />
       <Sidebar sections={getSidebarSections(group.category, locale)} />
@@ -146,6 +151,22 @@ export default async function FamilyPage({ params }: Props) {
               />
             ))}
           </div>
+
+          {copy && copy.faq.length > 0 ? (
+            <section className="mt-16">
+              <h2 className="text-2xl font-semibold">Frequently asked</h2>
+              <dl className="mt-6 space-y-6">
+                {copy.faq.map((item) => (
+                  <div className="max-w-3xl" key={item.question}>
+                    <dt className="font-medium">{item.question}</dt>
+                    <dd className="mt-2 text-muted-foreground">
+                      {item.answer}
+                    </dd>
+                  </div>
+                ))}
+              </dl>
+            </section>
+          ) : null}
         </div>
       </main>
     </>
diff --git a/apps/registry/lib/family-copy.ts b/apps/registry/lib/family-copy.ts
new file mode 100644
index 00000000..2406d069
--- /dev/null
+++ b/apps/registry/lib/family-copy.ts
@@ -0,0 +1,178 @@
+import type { ComponentCategory } from "@/types/registry";
+
+/**
+ * Editorial copy for a component family landing page — an SEO-oriented intro and
+ * a short FAQ. Families without an entry fall back to the one-line
+ * `getCategoryDescription`. The `ai` family has its own curated page at `/ai`,
+ * so this map skips it.
+ */
+export type FamilyCopy = {
+  readonly category: ComponentCategory;
+  readonly faq: readonly {
+    readonly answer: string;
+    readonly question: string;
+  }[];
+  readonly intro: string;
+};
+
+const FAMILY_COPY: readonly FamilyCopy[] = [
+  {
+    category: "core",
+    faq: [
+      {
+        answer:
+          "The foundational, unopinionated primitives — Button, Input, Label, Switch, Badge, Kbd, Separator, and the layout atoms — that every other component composes from.",
+        question: "What counts as a core component?",
+      },
+      {
+        answer:
+          "No. Every @vllnt/ui component installs independently with the shadcn CLI — add only the ones you use.",
+        question: "Do I have to install all of them?",
+      },
+    ],
+    intro:
+      "Core components are the primitives every interface is built from — buttons, inputs, labels, switches, badges, and the layout atoms underneath them. They're unopinionated, accessible, and the foundation the rest of the library composes on.",
+  },
+  {
+    category: "form",
+    faq: [
+      {
+        answer:
+          "Text, search, and phone fields, selects and comboboxes, checkboxes and radio groups, date/time/range pickers, ratings, OTP inputs, and validation wrappers.",
+        question: "What input types are covered?",
+      },
+      {
+        answer:
+          "Yes. Inputs are accessible by default and integrate with react-hook-form via the Form components; they work controlled or uncontrolled.",
+        question: "Are the form components accessible and validated?",
+      },
+    ],
+    intro:
+      "Form components cover the full input surface — text and search fields, selects, checkboxes, date and time pickers, ratings, and validation — so you can assemble accessible, controlled forms without wiring primitives by hand.",
+  },
+  {
+    category: "overlay",
+    faq: [
+      {
+        answer:
+          "Dialogs and alert dialogs, sheets and drawers, popovers, hover cards, tooltips, and toasts — content that layers above the page.",
+        question: "What's in the overlay family?",
+      },
+    ],
+    intro:
+      "Overlay components layer content above the page — dialogs, sheets, drawers, popovers, tooltips, and toasts. Focus management and dismissal are handled for you, built on accessible Radix primitives.",
+  },
+  {
+    category: "navigation",
+    faq: [
+      {
+        answer:
+          "Menus and menubars, breadcrumbs, tabs, pagination, command palettes, docks and rails, and floating navbars — everything for moving through an app.",
+        question: "What's in the navigation family?",
+      },
+    ],
+    intro:
+      "Navigation components move people through an app — menus, breadcrumbs, tabs, pagination, docks, rails, and floating navbars. Keyboard-accessible and composable into any shell.",
+  },
+  {
+    category: "data",
+    faq: [
+      {
+        answer:
+          "Tables and data tables, lists, charts, metrics, gauges, status boards, and activity feeds — the surfaces that read, filter, and summarize records.",
+        question: "What's in the data family?",
+      },
+    ],
+    intro:
+      "Data components turn records into something readable — sortable tables, lists, charts, metrics, gauges, and live status boards. Feed them your data and they handle filtering, formatting, and layout.",
+  },
+  {
+    category: "data-display",
+    faq: [
+      {
+        answer:
+          "Visualization-first components — maps, globes, choropleths, heatmaps, timelines, and specialized charts — that render spatial or temporal data.",
+        question: "How is data-display different from data?",
+      },
+    ],
+    intro:
+      "Data-display components visualize spatial and temporal data — 2D maps, 3D globes, choropleths, heatmaps, route maps, and timelines. They render from plain data props, no map tiles or external services required.",
+  },
+  {
+    category: "content",
+    faq: [
+      {
+        answer:
+          "Layout and presentation components — bento grids, cards, testimonials, marquees, expandable panels, timelines, and text-reveal effects — for marketing and editorial surfaces.",
+        question: "What's in the content family?",
+      },
+    ],
+    intro:
+      "Content components lay out and animate information — bento grids, cards, testimonials, timelines, expandable panels, and text effects. Use them to build landing pages, docs, and editorial surfaces that stay on the design system.",
+  },
+  {
+    category: "learning",
+    faq: [
+      {
+        answer:
+          "Tutorials and curricula, lessons and flashcards, quizzes and exercises, steppers, progress trackers, and guided tours — the scaffolding for learning products.",
+        question: "What's in the learning family?",
+      },
+    ],
+    intro:
+      "Learning components structure guided experiences — curricula, tutorials, flashcards, quizzes, steppers, progress trackers, and tours. Compose them into onboarding flows, courses, and interactive docs.",
+  },
+  {
+    category: "educational",
+    faq: [
+      {
+        answer:
+          "Knowledge-check runners, comparison and figure cards, and era/parallel timelines — components for teaching and reference products.",
+        question: "What's in the educational family?",
+      },
+    ],
+    intro:
+      "Educational components support teaching and reference experiences — knowledge checks, historical figure and civilization cards, era comparisons, and parallel timelines. Built for courseware, wikis, and study tools.",
+  },
+  {
+    category: "billing",
+    faq: [
+      {
+        answer:
+          "Pricing tables, plan cards, subscription and wallet cards, credit badges, and transaction lists — the surfaces that show cost, usage, and renewal state.",
+        question: "What's in the billing family?",
+      },
+      {
+        answer:
+          "No. These are presentational React components — wire them to Stripe, Polar, or your own billing API. They render state; they don't process payments.",
+        question: "Do these components handle payments?",
+      },
+    ],
+    intro:
+      "Billing components render the money side of a product — pricing tables, plan and subscription cards, credit badges, wallets, and transaction history. Drop them in and connect your billing provider; they present cost, usage, and renewal state without prescribing a backend.",
+  },
+  {
+    category: "utility",
+    faq: [
+      {
+        answer:
+          "Indicators and helpers — spinners, skeletons, copy buttons, QR codes — plus visual effects like glass surfaces, particles, shimmer, and magnetic interactions.",
+        question: "What's in the utility family?",
+      },
+    ],
+    intro:
+      "Utility components are the helpers and effects that finish an interface — spinners, skeletons, copy buttons, QR codes, and visual flourishes like glass, particles, and shimmer. Small pieces that glue the rest together.",
+  },
+];
+
+/**
+ * Editorial copy for a family landing page, or `undefined` when the family has
+ * no dedicated copy (the page falls back to the one-line description).
+ *
+ * @param category - the component category
+ */
+export function getFamilyCopy(
+  category: ComponentCategory,
+): FamilyCopy | undefined {
+  return FAMILY_COPY.find((entry) => entry.category === category);
+}

From e6f539cc4457192500dfde41ab0dd68aa353833a Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 15:37:47 +0200
Subject: [PATCH 09/16] feat(registry): maximize family-page SEO (branded title
 + keywords)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Browser audit (agent-browser) of the live family pages showed the <title> was
"X components" with no brand suffix and only generic site-wide keywords. Give
each family page a branded title ("X Components — VLLNT UI") and per-family
keywords (family + long-tail per-component terms). Combined with the intro,
FAQ, and CollectionPage/ItemList/FAQPage/Breadcrumb JSON-LD already added, each
family page now carries the full SEO surface.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 .../app/[locale]/families/[category]/page.tsx | 21 +++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/apps/registry/app/[locale]/families/[category]/page.tsx b/apps/registry/app/[locale]/families/[category]/page.tsx
index fa5e7903..38ef7be0 100644
--- a/apps/registry/app/[locale]/families/[category]/page.tsx
+++ b/apps/registry/app/[locale]/families/[category]/page.tsx
@@ -57,9 +57,21 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
   }
 
   const pathname = `/families/${category}`;
-  const title = `${group.label} components`;
   const copy = getFamilyCopy(group.category);
   const description = copy?.intro ?? getCategoryDescription(group.category);
+  const ogTitle = `${group.label} components`;
+  const lower = group.label.toLowerCase();
+  const keywords = [
+    `${lower} components`,
+    `react ${lower} components`,
+    `${lower} ui components`,
+    `${lower} component library`,
+    `shadcn ${lower} components`,
+    `accessible ${lower} components`,
+    ...group.items
+      .slice(0, 6)
+      .map((item) => `${item.title.toLowerCase()} component`),
+  ];
 
   return {
     alternates: {
@@ -67,15 +79,16 @@ export async function generateMetadata({ params }: Props): Promise<Metadata> {
       languages: languageAlternates(pathname),
     },
     description,
+    keywords,
     openGraph: generateOGMetadata(
-      { category: group.label, description, title, type: "page" },
+      { category: group.label, description, title: ogTitle, type: "page" },
       { locale, pathname },
     ),
-    title,
+    title: `${group.label} Components — VLLNT UI`,
     twitter: generateTwitterMetadata({
       category: group.label,
       description,
-      title,
+      title: ogTitle,
       type: "page",
     }),
   };

From 9554800f89724ce7a4cb5821be4b1a2848c2f880 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 15:56:05 +0200
Subject: [PATCH 10/16] fix(registry): dedupe Organization/WebSite JSON-LD
 (rendered twice)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Organization + WebSite JSON-LD were emitted as two <script> tags inside
<head> in the locale layout. React 19 hoists inline scripts to <head>, so each
rendered twice (audited via agent-browser: Organization, WebSite, Organization,
WebSite). Emit them as one array <script> in <body> — matching the per-page
JSON-LD pattern that renders once.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 apps/registry/app/[locale]/layout.tsx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/apps/registry/app/[locale]/layout.tsx b/apps/registry/app/[locale]/layout.tsx
index f5bb46f2..5274b094 100644
--- a/apps/registry/app/[locale]/layout.tsx
+++ b/apps/registry/app/[locale]/layout.tsx
@@ -128,10 +128,9 @@ export default async function LocaleLayout({ children, params }: Props) {
           title="VLLNT UI releases"
           type="application/atom+xml"
         />
-        <script {...jsonLdScriptAttributes(organizationLd())} />
-        <script {...jsonLdScriptAttributes(websiteLd())} />
       </head>
       <body className="h-full overflow-hidden">
+        <script {...jsonLdScriptAttributes([organizationLd(), websiteLd()])} />
         <ThemeProvider
           attribute="class"
           defaultTheme="dark"

From 0ad652f5fb56f5e7f67c3c631c866cd39caf8685 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 16:05:42 +0200
Subject: [PATCH 11/16] feat(registry): consolidate all family landings under
 /families

Move the AI hub to /families/ai (a Next static segment that wins over the
dynamic [category]) so every family lives under one namespace, and add a
/families index listing all 12 families. familyPath now returns
/families/<category> for all; old /ai permanently redirects to /families/ai
(preserves SEO). Unify the template: family pages get the Footer like the AI
page. Update internal links (build, vs, component breadcrumb, landing) and the
sitemap (drop standalone /ai, add /families + /families/ai).

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 apps/registry/app/[locale]/ai/page.tsx        | 260 +----------------
 .../app/[locale]/build/[slug]/page.tsx        |   4 +-
 .../app/[locale]/components/[slug]/page.tsx   |   2 +-
 .../app/[locale]/families/[category]/page.tsx |   2 +
 .../app/[locale]/families/ai/page.tsx         | 261 ++++++++++++++++++
 apps/registry/app/[locale]/families/page.tsx  | 126 +++++++++
 .../app/[locale]/vs/assistant-ui/page.tsx     |   2 +-
 apps/registry/app/sitemap.ts                  |  24 +-
 apps/registry/components/landing/landing.tsx  |   2 +-
 apps/registry/lib/component-categories.ts     |   6 +-
 10 files changed, 420 insertions(+), 269 deletions(-)
 create mode 100644 apps/registry/app/[locale]/families/ai/page.tsx
 create mode 100644 apps/registry/app/[locale]/families/page.tsx

diff --git a/apps/registry/app/[locale]/ai/page.tsx b/apps/registry/app/[locale]/ai/page.tsx
index 9d1e3168..124a8634 100644
--- a/apps/registry/app/[locale]/ai/page.tsx
+++ b/apps/registry/app/[locale]/ai/page.tsx
@@ -1,260 +1,24 @@
-import { Sidebar } from "@vllnt/ui";
-import { ArrowRight, Sparkles, Terminal } from "lucide-react";
-import type { Metadata } from "next";
-import Link from "next/link";
+import { permanentRedirect } from "next/navigation";
 import { setRequestLocale } from "next-intl/server";
 
-import { ComponentCard } from "@/components/component-card";
-import { Footer } from "@/components/footer/footer";
-import type { Locale } from "@/i18n/routing";
-import {
-  AI_COMPONENT_GROUPS,
-  getAiComponentSlugs,
-  resolveAiComponent,
-} from "@/lib/ai-seo";
-import {
-  breadcrumbLd,
-  collectionPageLd,
-  faqPageLd,
-  jsonLdScriptAttributes,
-} from "@/lib/jsonld";
-import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
-import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
-import { getSidebarSections } from "@/lib/sidebar-sections";
+import { type Locale, routing } from "@/i18n/routing";
+import { localizePathname } from "@/lib/seo";
 
 type Props = {
   readonly params: Promise<{ locale: Locale }>;
 };
 
-const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
-const PATHNAME = "/ai";
-
-const TITLE = "AI Agent UI Components — chat, streaming, tools, citations";
-const DESCRIPTION =
-  "The open-source UI design system for AI agents and AI-first apps. React components for AI chat, streaming text, tool calls, citations, agent activity, and artifacts. Install via the shadcn CLI.";
-
-const FAQ = [
-  {
-    answer:
-      "An agent-first design system gives you the UI primitives that AI products actually need — chat input, message bubbles, streaming text, tool-call displays, source citations, agent activity timelines, and artifacts — and also ships every component as machine-readable JSON so AI coding agents can install it without scraping HTML. VLLNT UI is open source (MIT) and installs with the shadcn CLI.",
-    question: "What is an agent-first UI design system?",
-  },
-  {
-    answer:
-      "At minimum: AI Chat Input for the composer, AI Message Bubble to render each turn, and AI Streaming Text for token-by-token output. Add AI Tool Call Display and Agent Activity for agentic flows, AI Source Citation for RAG, and AI Artifact for canvas-style output.",
-    question: "Which components do I need to build an AI chat app in React?",
-  },
-  {
-    answer:
-      "Three surfaces: /llms.txt (a concise index per the llmstxt.org spec), /llms-full.txt (the full registry context in one fetch), and /r/<name>.json (a machine-readable descriptor per component with props, accessibility schema, and examples). Coding agents like Claude, Cursor, Cline, and Continue read these directly.",
-    question: "How do AI agents consume VLLNT UI?",
-  },
-  {
-    answer:
-      "Yes. VLLNT UI is open source under the MIT license. You own the source after install, with no backend and no tracking.",
-    question: "Is VLLNT UI free to use?",
-  },
-];
-
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { locale } = await params;
-  const ogParameters = {
-    description: DESCRIPTION,
-    title: TITLE,
-    type: "page" as const,
-  };
-
-  return {
-    alternates: {
-      canonical: canonical(PATHNAME, locale),
-      languages: languageAlternates(PATHNAME),
-    },
-    description: DESCRIPTION,
-    openGraph: generateOGMetadata(ogParameters, {
-      locale,
-      pathname: PATHNAME,
-    }),
-    title: `${TITLE} | VLLNT UI`,
-    twitter: generateTwitterMetadata(ogParameters),
-  };
+export function generateStaticParams(): { locale: Locale }[] {
+  return routing.locales.map((locale) => ({ locale }));
 }
 
-export default async function AiHubPage({ params }: Props) {
+/**
+ * The AI hub moved to `/families/ai` (all family landings now live under
+ * `/families`). Permanently redirect the old `/ai` URL to preserve its SEO
+ * equity and any external links.
+ */
+export default async function AiRedirect({ params }: Props) {
   const { locale } = await params;
   setRequestLocale(locale);
-
-  const aiComponents = getAiComponentSlugs().flatMap((slug) => {
-    const resolved = resolveAiComponent(slug);
-    return resolved ? [resolved] : [];
-  });
-  const componentCount = aiComponents.length;
-
-  return (
-    <>
-      <script
-        {...jsonLdScriptAttributes([
-          breadcrumbLd([
-            { name: "Home", url: SITE_URL },
-            { name: "AI components", url: `${SITE_URL}${PATHNAME}` },
-          ]),
-          collectionPageLd({
-            description: DESCRIPTION,
-            items: aiComponents.map((component) => ({
-              name: component.title,
-              url: `${SITE_URL}/components/${component.name}`,
-            })),
-            title: TITLE,
-            url: `${SITE_URL}${PATHNAME}`,
-          }),
-          faqPageLd(FAQ),
-        ])}
-      />
-      <Sidebar sections={getSidebarSections(undefined, locale)} />
-      <main className="flex-1 overflow-y-auto bg-background">
-        {/* Hero / manifesto */}
-        <section className="border-b border-border">
-          <div className="mx-auto max-w-7xl px-4 py-20 lg:px-8">
-            <div className="flex items-center gap-2 text-sm font-medium text-muted-foreground">
-              <Sparkles className="size-4" />
-              UI for AI agents
-            </div>
-            <h1 className="mt-3 text-4xl font-semibold leading-tight md:text-5xl">
-              The UI design system for AI agents and AI-first apps.
-            </h1>
-            <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
-              Every AI product needs the same surfaces — a chat composer,
-              message bubbles, streaming output, tool calls, citations, agent
-              activity, and artifacts. VLLNT UI ships {componentCount} of them
-              as accessible React components you own after install, each also
-              readable by AI coding agents as JSON.
-            </p>
-            <div className="mt-8 flex flex-wrap gap-3">
-              <Link
-                className="inline-flex h-11 items-center gap-2 rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
-                href={localizePathname("/build/ai-chat-ui", locale)}
-              >
-                Build an AI chat UI
-                <ArrowRight className="size-4" />
-              </Link>
-              <Link
-                className="inline-flex h-11 items-center gap-2 rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
-                href={localizePathname("/docs/agents", locale)}
-              >
-                How agents consume the registry
-              </Link>
-            </div>
-          </div>
-        </section>
-
-        {/* Component family grouped by job-to-be-done */}
-        <section className="border-b border-border">
-          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
-            <h2 className="text-2xl font-semibold">The AI component family</h2>
-            <p className="mt-2 max-w-2xl text-muted-foreground">
-              Grouped by the job they do in an AI product. Mix and match — every
-              component installs independently with the shadcn CLI.
-            </p>
-
-            <div className="mt-10 space-y-12">
-              {AI_COMPONENT_GROUPS.map((group) => (
-                <div key={group.heading}>
-                  <h3 className="text-lg font-semibold">{group.heading}</h3>
-                  <p className="mt-1 max-w-2xl text-sm text-muted-foreground">
-                    {group.blurb}
-                  </p>
-                  <div className="mt-5 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-                    {group.slugs.map((slug) => {
-                      const resolved = resolveAiComponent(slug);
-                      if (!resolved) {
-                        return null;
-                      }
-                      return (
-                        <ComponentCard
-                          description={resolved.description}
-                          key={slug}
-                          locale={locale}
-                          slug={resolved.name}
-                          title={resolved.title}
-                        />
-                      );
-                    })}
-                  </div>
-                </div>
-              ))}
-            </div>
-          </div>
-        </section>
-
-        {/* Agent surface */}
-        <section className="border-b border-border bg-muted/30">
-          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
-            <div className="flex items-center gap-2 text-sm font-medium text-muted-foreground">
-              <Terminal className="size-4" />
-              Readable by agents
-            </div>
-            <h2 className="mt-2 text-2xl font-semibold">
-              Your AI agent can install these too.
-            </h2>
-            <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
-              The registry is exposed as structured data, so coding agents pick
-              the right component without scraping HTML.
-            </p>
-            <div className="mt-8 grid gap-4 md:grid-cols-3">
-              <a
-                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
-                href="/llms.txt"
-                rel="noreferrer"
-                target="_blank"
-              >
-                <p className="font-mono text-sm">/llms.txt</p>
-                <p className="mt-3 text-sm text-muted-foreground">
-                  Concise index per the llmstxt.org spec — sections, links,
-                  descriptions.
-                </p>
-              </a>
-              <a
-                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
-                href="/llms-full.txt"
-                rel="noreferrer"
-                target="_blank"
-              >
-                <p className="font-mono text-sm">/llms-full.txt</p>
-                <p className="mt-3 text-sm text-muted-foreground">
-                  Full registry context in one fetch — docs plus every component
-                  descriptor.
-                </p>
-              </a>
-              <Link
-                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
-                href={localizePathname("/docs/agents", locale)}
-              >
-                <p className="font-mono text-sm">/r/&lt;name&gt;.json</p>
-                <p className="mt-3 text-sm text-muted-foreground">
-                  Per-component descriptor: props, accessibility schema, and
-                  usage examples.
-                </p>
-              </Link>
-            </div>
-          </div>
-        </section>
-
-        {/* FAQ */}
-        <section>
-          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
-            <h2 className="text-2xl font-semibold">Frequently asked</h2>
-            <dl className="mt-8 space-y-8">
-              {FAQ.map((item) => (
-                <div className="max-w-3xl" key={item.question}>
-                  <dt className="font-medium">{item.question}</dt>
-                  <dd className="mt-2 text-muted-foreground">{item.answer}</dd>
-                </div>
-              ))}
-            </dl>
-          </div>
-        </section>
-
-        <Footer />
-      </main>
-    </>
-  );
+  permanentRedirect(localizePathname("/families/ai", locale));
 }
diff --git a/apps/registry/app/[locale]/build/[slug]/page.tsx b/apps/registry/app/[locale]/build/[slug]/page.tsx
index f7e6c09d..09a38c35 100644
--- a/apps/registry/app/[locale]/build/[slug]/page.tsx
+++ b/apps/registry/app/[locale]/build/[slug]/page.tsx
@@ -94,7 +94,7 @@ export default async function UseCasePage({ params }: Props) {
           <p className="text-sm font-medium uppercase tracking-wide text-muted-foreground">
             <Link
               className="hover:text-foreground"
-              href={localizePathname("/ai", locale)}
+              href={localizePathname("/families/ai", locale)}
             >
               UI for AI agents
             </Link>
@@ -154,7 +154,7 @@ export default async function UseCasePage({ params }: Props) {
           <div className="mt-14 border-t border-border pt-8">
             <Link
               className="inline-flex items-center gap-1 font-medium text-foreground underline"
-              href={localizePathname("/ai", locale)}
+              href={localizePathname("/families/ai", locale)}
             >
               Browse all AI agent components
               <ArrowRight className="size-4" />
diff --git a/apps/registry/app/[locale]/components/[slug]/page.tsx b/apps/registry/app/[locale]/components/[slug]/page.tsx
index 2f834440..04b238e8 100644
--- a/apps/registry/app/[locale]/components/[slug]/page.tsx
+++ b/apps/registry/app/[locale]/components/[slug]/page.tsx
@@ -291,7 +291,7 @@ export default async function ComponentPage(props: Props) {
                   </p>
                   <Link
                     className="mt-4 inline-flex items-center gap-1 text-sm font-medium text-foreground underline"
-                    href={localizePathname("/ai", locale)}
+                    href={localizePathname("/families/ai", locale)}
                   >
                     Browse all AI agent components
                     <ExternalLink className="size-3" />
diff --git a/apps/registry/app/[locale]/families/[category]/page.tsx b/apps/registry/app/[locale]/families/[category]/page.tsx
index 38ef7be0..86078e2d 100644
--- a/apps/registry/app/[locale]/families/[category]/page.tsx
+++ b/apps/registry/app/[locale]/families/[category]/page.tsx
@@ -4,6 +4,7 @@ import { notFound } from "next/navigation";
 import { setRequestLocale } from "next-intl/server";
 
 import { ComponentCard } from "@/components/component-card";
+import { Footer } from "@/components/footer/footer";
 import { type Locale, routing } from "@/i18n/routing";
 import { getFamilyCopy } from "@/lib/family-copy";
 import {
@@ -181,6 +182,7 @@ export default async function FamilyPage({ params }: Props) {
             </section>
           ) : null}
         </div>
+        <Footer />
       </main>
     </>
   );
diff --git a/apps/registry/app/[locale]/families/ai/page.tsx b/apps/registry/app/[locale]/families/ai/page.tsx
new file mode 100644
index 00000000..58bd358c
--- /dev/null
+++ b/apps/registry/app/[locale]/families/ai/page.tsx
@@ -0,0 +1,261 @@
+import { Sidebar } from "@vllnt/ui";
+import { ArrowRight, Sparkles, Terminal } from "lucide-react";
+import type { Metadata } from "next";
+import Link from "next/link";
+import { setRequestLocale } from "next-intl/server";
+
+import { ComponentCard } from "@/components/component-card";
+import { Footer } from "@/components/footer/footer";
+import type { Locale } from "@/i18n/routing";
+import {
+  AI_COMPONENT_GROUPS,
+  getAiComponentSlugs,
+  resolveAiComponent,
+} from "@/lib/ai-seo";
+import {
+  breadcrumbLd,
+  collectionPageLd,
+  faqPageLd,
+  jsonLdScriptAttributes,
+} from "@/lib/jsonld";
+import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
+import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
+import { getSidebarSections } from "@/lib/sidebar-sections";
+
+type Props = {
+  readonly params: Promise<{ locale: Locale }>;
+};
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const PATHNAME = "/families/ai";
+
+const TITLE = "AI Agent UI Components — chat, streaming, tools, citations";
+const DESCRIPTION =
+  "The open-source UI design system for AI agents and AI-first apps. React components for AI chat, streaming text, tool calls, citations, agent activity, and artifacts. Install via the shadcn CLI.";
+
+const FAQ = [
+  {
+    answer:
+      "An agent-first design system gives you the UI primitives that AI products actually need — chat input, message bubbles, streaming text, tool-call displays, source citations, agent activity timelines, and artifacts — and also ships every component as machine-readable JSON so AI coding agents can install it without scraping HTML. VLLNT UI is open source (MIT) and installs with the shadcn CLI.",
+    question: "What is an agent-first UI design system?",
+  },
+  {
+    answer:
+      "At minimum: AI Chat Input for the composer, AI Message Bubble to render each turn, and AI Streaming Text for token-by-token output. Add AI Tool Call Display and Agent Activity for agentic flows, AI Source Citation for RAG, and AI Artifact for canvas-style output.",
+    question: "Which components do I need to build an AI chat app in React?",
+  },
+  {
+    answer:
+      "Three surfaces: /llms.txt (a concise index per the llmstxt.org spec), /llms-full.txt (the full registry context in one fetch), and /r/<name>.json (a machine-readable descriptor per component with props, accessibility schema, and examples). Coding agents like Claude, Cursor, Cline, and Continue read these directly.",
+    question: "How do AI agents consume VLLNT UI?",
+  },
+  {
+    answer:
+      "Yes. VLLNT UI is open source under the MIT license. You own the source after install, with no backend and no tracking.",
+    question: "Is VLLNT UI free to use?",
+  },
+];
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const ogParameters = {
+    description: DESCRIPTION,
+    title: TITLE,
+    type: "page" as const,
+  };
+
+  return {
+    alternates: {
+      canonical: canonical(PATHNAME, locale),
+      languages: languageAlternates(PATHNAME),
+    },
+    description: DESCRIPTION,
+    openGraph: generateOGMetadata(ogParameters, {
+      locale,
+      pathname: PATHNAME,
+    }),
+    title: `${TITLE} | VLLNT UI`,
+    twitter: generateTwitterMetadata(ogParameters),
+  };
+}
+
+export default async function AiHubPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+
+  const aiComponents = getAiComponentSlugs().flatMap((slug) => {
+    const resolved = resolveAiComponent(slug);
+    return resolved ? [resolved] : [];
+  });
+  const componentCount = aiComponents.length;
+
+  return (
+    <>
+      <script
+        {...jsonLdScriptAttributes([
+          breadcrumbLd([
+            { name: "Home", url: SITE_URL },
+            { name: "Components", url: `${SITE_URL}/components` },
+            { name: "AI", url: `${SITE_URL}${PATHNAME}` },
+          ]),
+          collectionPageLd({
+            description: DESCRIPTION,
+            items: aiComponents.map((component) => ({
+              name: component.title,
+              url: `${SITE_URL}/components/${component.name}`,
+            })),
+            title: TITLE,
+            url: `${SITE_URL}${PATHNAME}`,
+          }),
+          faqPageLd(FAQ),
+        ])}
+      />
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        {/* Hero / manifesto */}
+        <section className="border-b border-border">
+          <div className="mx-auto max-w-7xl px-4 py-20 lg:px-8">
+            <div className="flex items-center gap-2 text-sm font-medium text-muted-foreground">
+              <Sparkles className="size-4" />
+              UI for AI agents
+            </div>
+            <h1 className="mt-3 text-4xl font-semibold leading-tight md:text-5xl">
+              The UI design system for AI agents and AI-first apps.
+            </h1>
+            <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
+              Every AI product needs the same surfaces — a chat composer,
+              message bubbles, streaming output, tool calls, citations, agent
+              activity, and artifacts. VLLNT UI ships {componentCount} of them
+              as accessible React components you own after install, each also
+              readable by AI coding agents as JSON.
+            </p>
+            <div className="mt-8 flex flex-wrap gap-3">
+              <Link
+                className="inline-flex h-11 items-center gap-2 rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
+                href={localizePathname("/build/ai-chat-ui", locale)}
+              >
+                Build an AI chat UI
+                <ArrowRight className="size-4" />
+              </Link>
+              <Link
+                className="inline-flex h-11 items-center gap-2 rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
+                href={localizePathname("/docs/agents", locale)}
+              >
+                How agents consume the registry
+              </Link>
+            </div>
+          </div>
+        </section>
+
+        {/* Component family grouped by job-to-be-done */}
+        <section className="border-b border-border">
+          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
+            <h2 className="text-2xl font-semibold">The AI component family</h2>
+            <p className="mt-2 max-w-2xl text-muted-foreground">
+              Grouped by the job they do in an AI product. Mix and match — every
+              component installs independently with the shadcn CLI.
+            </p>
+
+            <div className="mt-10 space-y-12">
+              {AI_COMPONENT_GROUPS.map((group) => (
+                <div key={group.heading}>
+                  <h3 className="text-lg font-semibold">{group.heading}</h3>
+                  <p className="mt-1 max-w-2xl text-sm text-muted-foreground">
+                    {group.blurb}
+                  </p>
+                  <div className="mt-5 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+                    {group.slugs.map((slug) => {
+                      const resolved = resolveAiComponent(slug);
+                      if (!resolved) {
+                        return null;
+                      }
+                      return (
+                        <ComponentCard
+                          description={resolved.description}
+                          key={slug}
+                          locale={locale}
+                          slug={resolved.name}
+                          title={resolved.title}
+                        />
+                      );
+                    })}
+                  </div>
+                </div>
+              ))}
+            </div>
+          </div>
+        </section>
+
+        {/* Agent surface */}
+        <section className="border-b border-border bg-muted/30">
+          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
+            <div className="flex items-center gap-2 text-sm font-medium text-muted-foreground">
+              <Terminal className="size-4" />
+              Readable by agents
+            </div>
+            <h2 className="mt-2 text-2xl font-semibold">
+              Your AI agent can install these too.
+            </h2>
+            <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
+              The registry is exposed as structured data, so coding agents pick
+              the right component without scraping HTML.
+            </p>
+            <div className="mt-8 grid gap-4 md:grid-cols-3">
+              <a
+                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
+                href="/llms.txt"
+                rel="noreferrer"
+                target="_blank"
+              >
+                <p className="font-mono text-sm">/llms.txt</p>
+                <p className="mt-3 text-sm text-muted-foreground">
+                  Concise index per the llmstxt.org spec — sections, links,
+                  descriptions.
+                </p>
+              </a>
+              <a
+                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
+                href="/llms-full.txt"
+                rel="noreferrer"
+                target="_blank"
+              >
+                <p className="font-mono text-sm">/llms-full.txt</p>
+                <p className="mt-3 text-sm text-muted-foreground">
+                  Full registry context in one fetch — docs plus every component
+                  descriptor.
+                </p>
+              </a>
+              <Link
+                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
+                href={localizePathname("/docs/agents", locale)}
+              >
+                <p className="font-mono text-sm">/r/&lt;name&gt;.json</p>
+                <p className="mt-3 text-sm text-muted-foreground">
+                  Per-component descriptor: props, accessibility schema, and
+                  usage examples.
+                </p>
+              </Link>
+            </div>
+          </div>
+        </section>
+
+        {/* FAQ */}
+        <section>
+          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
+            <h2 className="text-2xl font-semibold">Frequently asked</h2>
+            <dl className="mt-8 space-y-8">
+              {FAQ.map((item) => (
+                <div className="max-w-3xl" key={item.question}>
+                  <dt className="font-medium">{item.question}</dt>
+                  <dd className="mt-2 text-muted-foreground">{item.answer}</dd>
+                </div>
+              ))}
+            </dl>
+          </div>
+        </section>
+
+        <Footer />
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/[locale]/families/page.tsx b/apps/registry/app/[locale]/families/page.tsx
new file mode 100644
index 00000000..139b5851
--- /dev/null
+++ b/apps/registry/app/[locale]/families/page.tsx
@@ -0,0 +1,126 @@
+import { Breadcrumb, Sidebar } from "@vllnt/ui";
+import type { Metadata } from "next";
+import Link from "next/link";
+import { setRequestLocale } from "next-intl/server";
+
+import { Footer } from "@/components/footer/footer";
+import type { Locale } from "@/i18n/routing";
+import {
+  breadcrumbLd,
+  collectionPageLd,
+  jsonLdScriptAttributes,
+} from "@/lib/jsonld";
+import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
+import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
+import {
+  familyPath,
+  getCategoryDescription,
+  getSidebarSections,
+  groupedComponents,
+} from "@/lib/sidebar-sections";
+
+type Props = {
+  readonly params: Promise<{ locale: Locale }>;
+};
+
+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
+const PATHNAME = "/families";
+const TITLE = "Component families";
+const DESCRIPTION =
+  "Browse VLLNT UI by family — AI, forms, data, overlays, navigation, content, and more. Every component installs independently with the shadcn CLI.";
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+
+  return {
+    alternates: {
+      canonical: canonical(PATHNAME, locale),
+      languages: languageAlternates(PATHNAME),
+    },
+    description: DESCRIPTION,
+    openGraph: generateOGMetadata(
+      { description: DESCRIPTION, title: TITLE, type: "page" },
+      { locale, pathname: PATHNAME },
+    ),
+    title: `${TITLE} — VLLNT UI`,
+    twitter: generateTwitterMetadata({
+      description: DESCRIPTION,
+      title: TITLE,
+      type: "page",
+    }),
+  };
+}
+
+export default async function FamiliesPage({ params }: Props) {
+  const { locale } = await params;
+  setRequestLocale(locale);
+
+  return (
+    <>
+      <script
+        {...jsonLdScriptAttributes([
+          breadcrumbLd([
+            { name: "Home", url: SITE_URL },
+            { name: "Components", url: `${SITE_URL}/components` },
+            { name: "Families", url: `${SITE_URL}${PATHNAME}` },
+          ]),
+          collectionPageLd({
+            description: DESCRIPTION,
+            items: groupedComponents.map((group) => ({
+              name: `${group.label} components`,
+              url: `${SITE_URL}${familyPath(group.category)}`,
+            })),
+            title: TITLE,
+            url: `${SITE_URL}${PATHNAME}`,
+          }),
+        ])}
+      />
+      <Sidebar sections={getSidebarSections(undefined, locale)} />
+      <main className="flex-1 overflow-y-auto bg-background">
+        <div className="container mx-auto px-4 py-16 lg:px-8">
+          <Breadcrumb
+            className="mb-4 text-muted-foreground"
+            items={[
+              { href: localizePathname("/", locale), label: "Home" },
+              {
+                href: localizePathname("/components", locale),
+                label: "Components",
+              },
+              { label: "Families" },
+            ]}
+          />
+          <div className="mb-12">
+            <h1 className="text-4xl font-semibold mb-4">Component families</h1>
+            <p className="text-muted-foreground text-lg">{DESCRIPTION}</p>
+            <p className="text-muted-foreground text-sm mt-2">
+              {`${groupedComponents.length} families`}
+            </p>
+          </div>
+
+          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+            {groupedComponents.map((group) => (
+              <Link
+                className="group flex flex-col rounded-lg border bg-card p-6 transition-colors hover:border-foreground/20"
+                href={localizePathname(familyPath(group.category), locale)}
+                key={group.category}
+              >
+                <div className="flex items-baseline justify-between gap-3">
+                  <span className="text-lg font-semibold transition-colors group-hover:text-foreground">
+                    {group.label}
+                  </span>
+                  <span className="shrink-0 text-xs text-muted-foreground">
+                    {group.items.length}
+                  </span>
+                </div>
+                <p className="mt-2 line-clamp-3 text-sm text-muted-foreground">
+                  {getCategoryDescription(group.category)}
+                </p>
+              </Link>
+            ))}
+          </div>
+        </div>
+        <Footer />
+      </main>
+    </>
+  );
+}
diff --git a/apps/registry/app/[locale]/vs/assistant-ui/page.tsx b/apps/registry/app/[locale]/vs/assistant-ui/page.tsx
index a7117969..ac1d50b5 100644
--- a/apps/registry/app/[locale]/vs/assistant-ui/page.tsx
+++ b/apps/registry/app/[locale]/vs/assistant-ui/page.tsx
@@ -139,7 +139,7 @@ export default async function VsAssistantUiPage({ params }: Props) {
           <div className="mt-12 border-t border-border pt-8">
             <Link
               className="inline-flex items-center gap-1 font-medium text-foreground underline"
-              href={localizePathname("/ai", locale)}
+              href={localizePathname("/families/ai", locale)}
             >
               Explore all AI agent components
             </Link>
diff --git a/apps/registry/app/sitemap.ts b/apps/registry/app/sitemap.ts
index 254eb022..9fe2c774 100644
--- a/apps/registry/app/sitemap.ts
+++ b/apps/registry/app/sitemap.ts
@@ -63,7 +63,7 @@ function localizedEntries(
 function staticRoutes(lastModified: Date): MetadataRoute.Sitemap {
   const routes = [
     { changeFrequency: "weekly", path: "/", priority: 1 },
-    { changeFrequency: "weekly", path: "/ai", priority: 0.9 },
+    { changeFrequency: "weekly", path: "/families", priority: 0.9 },
     { changeFrequency: "weekly", path: "/components", priority: 1 },
     { changeFrequency: "weekly", path: "/templates", priority: 0.8 },
     { changeFrequency: "weekly", path: "/changelog", priority: 0.8 },
@@ -80,18 +80,16 @@ function staticRoutes(lastModified: Date): MetadataRoute.Sitemap {
 }
 
 function familyRoutes(lastModified: Date): MetadataRoute.Sitemap {
-  return groupedComponents
-    .filter((group) => group.category !== "ai")
-    .flatMap((group) =>
-      localizedEntries(
-        {
-          changeFrequency: "weekly",
-          path: `/families/${group.category}`,
-          priority: 0.7,
-        },
-        lastModified,
-      ),
-    );
+  return groupedComponents.flatMap((group) =>
+    localizedEntries(
+      {
+        changeFrequency: "weekly",
+        path: `/families/${group.category}`,
+        priority: group.category === "ai" ? 0.9 : 0.7,
+      },
+      lastModified,
+    ),
+  );
 }
 
 function docsRoutes(lastModified: Date): MetadataRoute.Sitemap {
diff --git a/apps/registry/components/landing/landing.tsx b/apps/registry/components/landing/landing.tsx
index 486ce28a..b10a7a63 100644
--- a/apps/registry/components/landing/landing.tsx
+++ b/apps/registry/components/landing/landing.tsx
@@ -33,7 +33,7 @@ function HeroActions({ componentCount }: { componentCount: number }) {
     <div className="mt-6 flex flex-wrap gap-3">
       <Link
         className="inline-flex h-11 items-center gap-2 rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
-        href="/ai"
+        href="/families/ai"
       >
         Explore AI components
         <ArrowRight className="size-4" />
diff --git a/apps/registry/lib/component-categories.ts b/apps/registry/lib/component-categories.ts
index 569f5176..c8803aaf 100644
--- a/apps/registry/lib/component-categories.ts
+++ b/apps/registry/lib/component-categories.ts
@@ -120,14 +120,14 @@ function getCategoryDescription(category: ComponentCategory): string {
 }
 
 /**
- * Canonical site path for a component family. The `ai` family resolves to the
- * curated `/ai` landing; every other family resolves to `/families/<category>`.
+ * Canonical site path for a component family — `/families/<category>` for every
+ * family, including the AI family's curated landing at `/families/ai`.
  *
  * @param category - the component category
  * @returns the locale-agnostic family path (pass through `localizePathname`)
  */
 function familyPath(category: ComponentCategory): string {
-  return category === "ai" ? "/ai" : `/families/${category}`;
+  return `/families/${category}`;
 }
 
 export {

From 4762bd3545b77012842a43fd7a7c7e34f1e9fc51 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 16:20:52 +0200
Subject: [PATCH 12/16] fix(registry): actually dedupe Org/WebSite JSON-LD
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The layout's Organization+WebSite <script> emitted twice regardless of head vs
body-array form, while every page's own JSON-LD (rendered deep inside the
children subtree) emitted once. Move the layout's JSON-LD to the same depth —
a sibling of {children} — so it renders a single time.

Claude-Session: https://claude.ai/code/session_01KB2yTDBo7Knydqvz1VvFdF
---
 apps/registry/app/[locale]/layout.tsx | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/apps/registry/app/[locale]/layout.tsx b/apps/registry/app/[locale]/layout.tsx
index 5274b094..c57f3958 100644
--- a/apps/registry/app/[locale]/layout.tsx
+++ b/apps/registry/app/[locale]/layout.tsx
@@ -130,7 +130,6 @@ export default async function LocaleLayout({ children, params }: Props) {
         />
       </head>
       <body className="h-full overflow-hidden">
-        <script {...jsonLdScriptAttributes([organizationLd(), websiteLd()])} />
         <ThemeProvider
           attribute="class"
           defaultTheme="dark"
@@ -142,7 +141,12 @@ export default async function LocaleLayout({ children, params }: Props) {
             <div className="flex h-full flex-col overflow-hidden">
               <NextIntlClientProvider>
                 <Header locale={locale} />
-                <div className="flex flex-1 overflow-hidden">{children}</div>
+                <div className="flex flex-1 overflow-hidden">
+                  <script
+                    {...jsonLdScriptAttributes([organizationLd(), websiteLd()])}
+                  />
+                  {children}
+                </div>
               </NextIntlClientProvider>
             </div>
           </SidebarProvider>

From 6325f65108e5eac53bb3e28600ad0acf5745f593 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 18:29:14 +0200
Subject: [PATCH 13/16] feat(registry): unify every family landing on one
 grouped SEO template

All families (including ai) now render through the shared
/families/[category] template: hero + CTAs, per-family SEO sub-groups
(family-groups.ts), an agent surface, and a FAQ. Removes the bespoke
/families/ai hub so ai shares the same UI, and enriches the ai family
copy (2 -> 4 FAQ).

Adds an e2e case asserting /families/ai renders the grouped template.

Claude-Session: https://claude.ai/code/session_01B9kb7NGCUjYYYeWB17Z3S9
---
 ROADMAP.md                                    |  23 +-
 .../app/[locale]/families/[category]/page.tsx | 178 +++--
 .../app/[locale]/families/ai/page.tsx         | 261 -------
 apps/registry/e2e/family-homepage.spec.ts     |  23 +-
 apps/registry/lib/family-copy.ts              |  34 +-
 apps/registry/lib/family-groups.ts            | 704 ++++++++++++++++++
 6 files changed, 909 insertions(+), 314 deletions(-)
 delete mode 100644 apps/registry/app/[locale]/families/ai/page.tsx
 create mode 100644 apps/registry/lib/family-groups.ts

diff --git a/ROADMAP.md b/ROADMAP.md
index b89a1fe4..35ff69b8 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,8 +1,8 @@
 # Roadmap
 
 > **Goal:** the most complete, agent-ready React component registry on the @vllnt design system — every component documented, typed, installable via the shadcn CLI, and discoverable by humans and agents.
-> **Now:** `component-sidebar` (0.4.0 canary cycle).
-> **Last updated:** 2026-06-27
+> **Now:** `family-pages` code-complete on `feat/family-homepage` (pending merge); `component-sidebar` next. 0.4.0 canary cycle.
+> **Last updated:** 2026-07-02
 > **Channels:** `@latest` = `0.3.0` · `@canary` = `0.4.0-canary.<sha>` (auto-publishes on every merge to main). Tracking: [milestone 0.3.0](https://github.com/vllnt/ui/milestone/1)
 
 Convention: phases are kebab-case outcome slugs, ordered DONE → ACTIVE → PLANNED. Tasks carry stable `<slug>.<n>` IDs; functional tasks pair with a `Validate`/`E2E` task. History is never deleted. Shipped 0.3.0 detail lives in `CHANGELOG.md` and the 197 closed issues; phases below summarize it.
@@ -60,6 +60,20 @@ Convention: phases are kebab-case outcome slugs, ordered DONE → ACTIVE → PLA
 
 ---
 
+## family-pages [ACTIVE — code-complete on `feat/family-homepage`, pending merge]
+
+**Goal:** A per-family landing at `/families/[category]` — the SEO / agent-surface destination for the Family breadcrumb crumb (#461) and the sidebar drill-down.
+**Exit criteria:** 12 family landings on one shared `/families/[category]` template (`ai` included), each hero + CTAs + count + SEO sub-groups (`family-groups.ts`) + editorial copy + FAQ + agent surface; sitemap'd; `CollectionPage`/`ItemList` + `FAQPage` JSON-LD; `/components` headings + component-page family crumb link in via `familyPath`.
+**Verify:** `/families/form` renders the Form grid + FAQ; `/ai` permanently redirects to `/families/ai`; Google Rich Results clean on a family page. Moves to the DONE cluster on merge to main + canary publish.
+
+- [x] family-pages.1 `/families/[category]` route: hero + description + count + data-driven grid, zero nav maintenance — #463
+- [x] family-pages.2 Internal links: `/components` family headings + component-page family crumb → family page via `familyPath` — #463
+- [x] family-pages.3 sitemap `familyRoutes()` + `collectionPageLd` (CollectionPage/ItemList) + `faqPageLd` — #463
+- [x] family-pages.4 `ai` reconciled: consolidated under `/families/ai` (shared template, grouped), `/ai` → permanent redirect, `familyPath` helper — #463
+- [x] family-pages.5 Per-family SEO copy + FAQ (`family-copy.ts`) + branded titles / keywords — #463
+- [x] family-pages.6 Validate: e2e `family-homepage.spec.ts` + unit `component-categories.test.ts` (E2E)
+- [x] family-pages.7 One shared landing template for every family incl. `ai` (hero + CTAs + agent surface); per-family SEO sub-groups (`family-groups.ts`); `/families` index — #463
+
 ## component-sidebar [ACTIVE]
 
 **Goal:** Navigate 309 components via a single-pane **drill-down** — families list ⇄ one family's components — synced to the breadcrumb, so the sidebar never shows more than one family at once.
@@ -117,6 +131,7 @@ Deferred families (Later): voice (6), IDE code surfaces (9), workflow canvas (5)
 Unscheduled — pull into a phase when prioritized.
 
 - **react-doctor-90** — push score 71 → 90 (sweep issues closed but target not fully met; see `codebase-health` caveat).
+- **typography-primitives** (#465) — foundation `Text` / `Heading` / `Display` (/`Prose`) with token-driven font-family, heading-weight, and type-scale, all theme-overridable. Feasible (~12–18 files; an existing `typography` component — H1–H4/P/Lead/… — to model or extend), **but needs 3 triage decisions before scheduling**: (1) `--font-display` is a net-new token → conflicts with "no new design tokens beyond DESIGN.md baseline" (Out of scope) — resolve by adding a display family to the DESIGN.md baseline, or drop `--font-display` and map `Display` to `--font-sans`; (2) wire `--font-sans` as the actual default — today the body font is `font-mono` (`packages/ui/src/styles.css`), not sans, so "default stays semibold sans" isn't literally true; (3) reconcile the default heading weight — existing `typography.tsx` h1 uses `font-extrabold` (800) vs DESIGN.md's 600 semibold.
 - **ai-elements-voice** (6) — AudioPlayer, MicSelector, Persona, SpeechInput, Transcription, VoiceSelector.
 - **ai-elements-ide** (9) — Commit, EnvironmentVariables, FileTree, PackageInfo, SchemaDisplay, Snippet, StackTrace, Terminal, TestResults.
 - **ai-elements-canvas** (5) — Canvas, Connection, Controls, Node, Panel (verify against existing `@xyflow`-based components first).
@@ -234,7 +249,7 @@ Semver discipline starts hard at `1.0.0`. Until then, `0.x.0` may include breaki
 - React Compiler adoption.
 - Right-to-left language support.
 - Backend services for `/report` or `/request-component` (prefilled GitHub URLs — no backend).
-- New design tokens beyond DESIGN.md baseline.
+- New design tokens beyond DESIGN.md baseline (this is what gates `typography-primitives` #465's `--font-display` — see Later).
 - Versioned docs (deferred until breaking changes appear).
 - Component analytics (privacy-respecting telemetry — separate decision).
 
@@ -242,6 +257,6 @@ Semver discipline starts hard at `1.0.0`. Until then, `0.x.0` may include breaki
 
 ## Tracking
 
-- Open issues: `gh issue list -R vllnt/ui --state open` (currently 0 — file issues per phase as work starts; the repo enforces issue-linked PRs).
+- Open issues: `gh issue list -R vllnt/ui --state open` (2 open: #463 `family-pages` — code-complete on `feat/family-homepage`, pending merge; #465 `typography-primitives` — needs triage, see Later. Repo enforces issue-linked PRs).
 - react-doctor score: `pnpm doctor:score`.
 - Channels: `npm view @vllnt/ui dist-tags`.
diff --git a/apps/registry/app/[locale]/families/[category]/page.tsx b/apps/registry/app/[locale]/families/[category]/page.tsx
index 86078e2d..90b2926f 100644
--- a/apps/registry/app/[locale]/families/[category]/page.tsx
+++ b/apps/registry/app/[locale]/families/[category]/page.tsx
@@ -1,5 +1,7 @@
 import { Breadcrumb, Sidebar } from "@vllnt/ui";
+import { ArrowRight } from "lucide-react";
 import type { Metadata } from "next";
+import Link from "next/link";
 import { notFound } from "next/navigation";
 import { setRequestLocale } from "next-intl/server";
 
@@ -7,6 +9,7 @@ import { ComponentCard } from "@/components/component-card";
 import { Footer } from "@/components/footer/footer";
 import { type Locale, routing } from "@/i18n/routing";
 import { getFamilyCopy } from "@/lib/family-copy";
+import { getFamilyGroups } from "@/lib/family-groups";
 import {
   breadcrumbLd,
   collectionPageLd,
@@ -28,16 +31,8 @@ type Props = {
 
 const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
 
-/**
- * Component families that get their own landing page. `ai` stays out — its
- * curated landing lives at `/ai` (see `familyPath`).
- */
-const familyGroups = groupedComponents.filter(
-  (group) => group.category !== "ai",
-);
-
 function findFamily(category: string) {
-  return familyGroups.find((group) => group.category === category);
+  return groupedComponents.find((group) => group.category === category);
 }
 
 export function generateStaticParams(): {
@@ -45,7 +40,7 @@ export function generateStaticParams(): {
   locale: Locale;
 }[] {
   return routing.locales.flatMap((locale) =>
-    familyGroups.map((group) => ({ category: group.category, locale })),
+    groupedComponents.map((group) => ({ category: group.category, locale })),
   );
 }
 
@@ -107,6 +102,7 @@ export default async function FamilyPage({ params }: Props) {
 
   const copy = getFamilyCopy(group.category);
   const description = copy?.intro ?? getCategoryDescription(group.category);
+  const groups = getFamilyGroups(group.category);
   const pathname = `/families/${category}`;
 
   return (
@@ -132,44 +128,141 @@ export default async function FamilyPage({ params }: Props) {
       />
       <Sidebar sections={getSidebarSections(group.category, locale)} />
       <main className="flex-1 overflow-y-auto bg-background">
-        <div className="container mx-auto px-4 py-16 lg:px-8">
-          <Breadcrumb
-            className="mb-4 text-muted-foreground"
-            items={[
-              { href: localizePathname("/", locale), label: "Home" },
-              {
-                href: localizePathname("/components", locale),
-                label: "Components",
-              },
-              { label: group.label },
-            ]}
-          />
-          <div className="mb-12">
-            <h1 className="text-4xl font-semibold mb-4">
+        <section className="border-b border-border">
+          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
+            <Breadcrumb
+              className="mb-6 text-muted-foreground"
+              items={[
+                { href: localizePathname("/", locale), label: "Home" },
+                {
+                  href: localizePathname("/components", locale),
+                  label: "Components",
+                },
+                { label: group.label },
+              ]}
+            />
+            <p className="text-sm font-medium text-muted-foreground">
+              VLLNT UI · Component family
+            </p>
+            <h1 className="mt-3 text-4xl font-semibold leading-tight md:text-5xl">
               {group.label} components
             </h1>
             {description ? (
-              <p className="text-muted-foreground text-lg">{description}</p>
+              <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
+                {description}
+              </p>
             ) : null}
-            <p className="text-muted-foreground text-sm mt-2">
-              {`${group.items.length} ${group.items.length === 1 ? "component" : "components"}`}
-            </p>
+            <div className="mt-8 flex flex-wrap items-center gap-3">
+              <Link
+                className="inline-flex h-11 items-center gap-2 rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
+                href={localizePathname("/components", locale)}
+              >
+                Browse all components
+                <ArrowRight className="size-4" />
+              </Link>
+              <Link
+                className="inline-flex h-11 items-center rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
+                href={localizePathname("/docs/agents", locale)}
+              >
+                How agents consume the registry
+              </Link>
+              <span className="text-sm text-muted-foreground">
+                {`${group.items.length} ${group.items.length === 1 ? "component" : "components"}`}
+              </span>
+            </div>
           </div>
+        </section>
 
-          <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-            {group.items.map((component) => (
-              <ComponentCard
-                key={component.name}
-                locale={locale}
-                slug={component.name}
-              />
-            ))}
+        <section className="border-b border-border">
+          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
+            {groups ? (
+              <div className="space-y-14">
+                {groups.map((section) => (
+                  <div key={section.heading}>
+                    <h2 className="text-2xl font-semibold">
+                      {section.heading}
+                    </h2>
+                    <p className="mt-2 max-w-2xl text-muted-foreground">
+                      {section.blurb}
+                    </p>
+                    <div className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+                      {section.slugs.map((slug) => (
+                        <ComponentCard key={slug} locale={locale} slug={slug} />
+                      ))}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            ) : (
+              <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
+                {group.items.map((component) => (
+                  <ComponentCard
+                    key={component.name}
+                    locale={locale}
+                    slug={component.name}
+                  />
+                ))}
+              </div>
+            )}
           </div>
+        </section>
 
-          {copy && copy.faq.length > 0 ? (
-            <section className="mt-16">
+        <section className="border-b border-border bg-muted/30">
+          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
+            <p className="text-sm font-medium text-muted-foreground">
+              Readable by agents
+            </p>
+            <h2 className="mt-2 text-2xl font-semibold">
+              Your AI agent can install these too.
+            </h2>
+            <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
+              The registry is exposed as structured data, so coding agents pick
+              the right component without scraping HTML.
+            </p>
+            <div className="mt-8 grid gap-4 md:grid-cols-3">
+              <a
+                className="rounded-lg border border-border p-5 hover:border-foreground/40"
+                href="/llms.txt"
+                rel="noreferrer"
+                target="_blank"
+              >
+                <p className="font-mono text-sm">/llms.txt</p>
+                <p className="mt-3 text-sm text-muted-foreground">
+                  Concise index per the llmstxt.org spec — sections, links, and
+                  descriptions.
+                </p>
+              </a>
+              <a
+                className="rounded-lg border border-border p-5 hover:border-foreground/40"
+                href="/llms-full.txt"
+                rel="noreferrer"
+                target="_blank"
+              >
+                <p className="font-mono text-sm">/llms-full.txt</p>
+                <p className="mt-3 text-sm text-muted-foreground">
+                  Full registry context in one fetch — docs plus every component
+                  descriptor.
+                </p>
+              </a>
+              <Link
+                className="rounded-lg border border-border p-5 hover:border-foreground/40"
+                href={localizePathname("/docs/agents", locale)}
+              >
+                <p className="font-mono text-sm">{"/r/<name>.json"}</p>
+                <p className="mt-3 text-sm text-muted-foreground">
+                  Per-component descriptor: props, accessibility schema, and
+                  usage examples.
+                </p>
+              </Link>
+            </div>
+          </div>
+        </section>
+
+        {copy && copy.faq.length > 0 ? (
+          <section>
+            <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
               <h2 className="text-2xl font-semibold">Frequently asked</h2>
-              <dl className="mt-6 space-y-6">
+              <dl className="mt-8 space-y-8">
                 {copy.faq.map((item) => (
                   <div className="max-w-3xl" key={item.question}>
                     <dt className="font-medium">{item.question}</dt>
@@ -179,9 +272,10 @@ export default async function FamilyPage({ params }: Props) {
                   </div>
                 ))}
               </dl>
-            </section>
-          ) : null}
-        </div>
+            </div>
+          </section>
+        ) : null}
+
         <Footer />
       </main>
     </>
diff --git a/apps/registry/app/[locale]/families/ai/page.tsx b/apps/registry/app/[locale]/families/ai/page.tsx
deleted file mode 100644
index 58bd358c..00000000
--- a/apps/registry/app/[locale]/families/ai/page.tsx
+++ /dev/null
@@ -1,261 +0,0 @@
-import { Sidebar } from "@vllnt/ui";
-import { ArrowRight, Sparkles, Terminal } from "lucide-react";
-import type { Metadata } from "next";
-import Link from "next/link";
-import { setRequestLocale } from "next-intl/server";
-
-import { ComponentCard } from "@/components/component-card";
-import { Footer } from "@/components/footer/footer";
-import type { Locale } from "@/i18n/routing";
-import {
-  AI_COMPONENT_GROUPS,
-  getAiComponentSlugs,
-  resolveAiComponent,
-} from "@/lib/ai-seo";
-import {
-  breadcrumbLd,
-  collectionPageLd,
-  faqPageLd,
-  jsonLdScriptAttributes,
-} from "@/lib/jsonld";
-import { generateOGMetadata, generateTwitterMetadata } from "@/lib/og";
-import { canonical, languageAlternates, localizePathname } from "@/lib/seo";
-import { getSidebarSections } from "@/lib/sidebar-sections";
-
-type Props = {
-  readonly params: Promise<{ locale: Locale }>;
-};
-
-const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.ai";
-const PATHNAME = "/families/ai";
-
-const TITLE = "AI Agent UI Components — chat, streaming, tools, citations";
-const DESCRIPTION =
-  "The open-source UI design system for AI agents and AI-first apps. React components for AI chat, streaming text, tool calls, citations, agent activity, and artifacts. Install via the shadcn CLI.";
-
-const FAQ = [
-  {
-    answer:
-      "An agent-first design system gives you the UI primitives that AI products actually need — chat input, message bubbles, streaming text, tool-call displays, source citations, agent activity timelines, and artifacts — and also ships every component as machine-readable JSON so AI coding agents can install it without scraping HTML. VLLNT UI is open source (MIT) and installs with the shadcn CLI.",
-    question: "What is an agent-first UI design system?",
-  },
-  {
-    answer:
-      "At minimum: AI Chat Input for the composer, AI Message Bubble to render each turn, and AI Streaming Text for token-by-token output. Add AI Tool Call Display and Agent Activity for agentic flows, AI Source Citation for RAG, and AI Artifact for canvas-style output.",
-    question: "Which components do I need to build an AI chat app in React?",
-  },
-  {
-    answer:
-      "Three surfaces: /llms.txt (a concise index per the llmstxt.org spec), /llms-full.txt (the full registry context in one fetch), and /r/<name>.json (a machine-readable descriptor per component with props, accessibility schema, and examples). Coding agents like Claude, Cursor, Cline, and Continue read these directly.",
-    question: "How do AI agents consume VLLNT UI?",
-  },
-  {
-    answer:
-      "Yes. VLLNT UI is open source under the MIT license. You own the source after install, with no backend and no tracking.",
-    question: "Is VLLNT UI free to use?",
-  },
-];
-
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { locale } = await params;
-  const ogParameters = {
-    description: DESCRIPTION,
-    title: TITLE,
-    type: "page" as const,
-  };
-
-  return {
-    alternates: {
-      canonical: canonical(PATHNAME, locale),
-      languages: languageAlternates(PATHNAME),
-    },
-    description: DESCRIPTION,
-    openGraph: generateOGMetadata(ogParameters, {
-      locale,
-      pathname: PATHNAME,
-    }),
-    title: `${TITLE} | VLLNT UI`,
-    twitter: generateTwitterMetadata(ogParameters),
-  };
-}
-
-export default async function AiHubPage({ params }: Props) {
-  const { locale } = await params;
-  setRequestLocale(locale);
-
-  const aiComponents = getAiComponentSlugs().flatMap((slug) => {
-    const resolved = resolveAiComponent(slug);
-    return resolved ? [resolved] : [];
-  });
-  const componentCount = aiComponents.length;
-
-  return (
-    <>
-      <script
-        {...jsonLdScriptAttributes([
-          breadcrumbLd([
-            { name: "Home", url: SITE_URL },
-            { name: "Components", url: `${SITE_URL}/components` },
-            { name: "AI", url: `${SITE_URL}${PATHNAME}` },
-          ]),
-          collectionPageLd({
-            description: DESCRIPTION,
-            items: aiComponents.map((component) => ({
-              name: component.title,
-              url: `${SITE_URL}/components/${component.name}`,
-            })),
-            title: TITLE,
-            url: `${SITE_URL}${PATHNAME}`,
-          }),
-          faqPageLd(FAQ),
-        ])}
-      />
-      <Sidebar sections={getSidebarSections(undefined, locale)} />
-      <main className="flex-1 overflow-y-auto bg-background">
-        {/* Hero / manifesto */}
-        <section className="border-b border-border">
-          <div className="mx-auto max-w-7xl px-4 py-20 lg:px-8">
-            <div className="flex items-center gap-2 text-sm font-medium text-muted-foreground">
-              <Sparkles className="size-4" />
-              UI for AI agents
-            </div>
-            <h1 className="mt-3 text-4xl font-semibold leading-tight md:text-5xl">
-              The UI design system for AI agents and AI-first apps.
-            </h1>
-            <p className="mt-6 max-w-2xl text-lg text-muted-foreground">
-              Every AI product needs the same surfaces — a chat composer,
-              message bubbles, streaming output, tool calls, citations, agent
-              activity, and artifacts. VLLNT UI ships {componentCount} of them
-              as accessible React components you own after install, each also
-              readable by AI coding agents as JSON.
-            </p>
-            <div className="mt-8 flex flex-wrap gap-3">
-              <Link
-                className="inline-flex h-11 items-center gap-2 rounded-md bg-foreground px-5 text-sm font-medium text-background hover:opacity-90"
-                href={localizePathname("/build/ai-chat-ui", locale)}
-              >
-                Build an AI chat UI
-                <ArrowRight className="size-4" />
-              </Link>
-              <Link
-                className="inline-flex h-11 items-center gap-2 rounded-md border border-border px-5 text-sm font-medium hover:bg-muted"
-                href={localizePathname("/docs/agents", locale)}
-              >
-                How agents consume the registry
-              </Link>
-            </div>
-          </div>
-        </section>
-
-        {/* Component family grouped by job-to-be-done */}
-        <section className="border-b border-border">
-          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
-            <h2 className="text-2xl font-semibold">The AI component family</h2>
-            <p className="mt-2 max-w-2xl text-muted-foreground">
-              Grouped by the job they do in an AI product. Mix and match — every
-              component installs independently with the shadcn CLI.
-            </p>
-
-            <div className="mt-10 space-y-12">
-              {AI_COMPONENT_GROUPS.map((group) => (
-                <div key={group.heading}>
-                  <h3 className="text-lg font-semibold">{group.heading}</h3>
-                  <p className="mt-1 max-w-2xl text-sm text-muted-foreground">
-                    {group.blurb}
-                  </p>
-                  <div className="mt-5 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
-                    {group.slugs.map((slug) => {
-                      const resolved = resolveAiComponent(slug);
-                      if (!resolved) {
-                        return null;
-                      }
-                      return (
-                        <ComponentCard
-                          description={resolved.description}
-                          key={slug}
-                          locale={locale}
-                          slug={resolved.name}
-                          title={resolved.title}
-                        />
-                      );
-                    })}
-                  </div>
-                </div>
-              ))}
-            </div>
-          </div>
-        </section>
-
-        {/* Agent surface */}
-        <section className="border-b border-border bg-muted/30">
-          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
-            <div className="flex items-center gap-2 text-sm font-medium text-muted-foreground">
-              <Terminal className="size-4" />
-              Readable by agents
-            </div>
-            <h2 className="mt-2 text-2xl font-semibold">
-              Your AI agent can install these too.
-            </h2>
-            <p className="mt-4 max-w-2xl text-lg text-muted-foreground">
-              The registry is exposed as structured data, so coding agents pick
-              the right component without scraping HTML.
-            </p>
-            <div className="mt-8 grid gap-4 md:grid-cols-3">
-              <a
-                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
-                href="/llms.txt"
-                rel="noreferrer"
-                target="_blank"
-              >
-                <p className="font-mono text-sm">/llms.txt</p>
-                <p className="mt-3 text-sm text-muted-foreground">
-                  Concise index per the llmstxt.org spec — sections, links,
-                  descriptions.
-                </p>
-              </a>
-              <a
-                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
-                href="/llms-full.txt"
-                rel="noreferrer"
-                target="_blank"
-              >
-                <p className="font-mono text-sm">/llms-full.txt</p>
-                <p className="mt-3 text-sm text-muted-foreground">
-                  Full registry context in one fetch — docs plus every component
-                  descriptor.
-                </p>
-              </a>
-              <Link
-                className="group rounded-lg border border-border p-5 hover:border-foreground/40"
-                href={localizePathname("/docs/agents", locale)}
-              >
-                <p className="font-mono text-sm">/r/&lt;name&gt;.json</p>
-                <p className="mt-3 text-sm text-muted-foreground">
-                  Per-component descriptor: props, accessibility schema, and
-                  usage examples.
-                </p>
-              </Link>
-            </div>
-          </div>
-        </section>
-
-        {/* FAQ */}
-        <section>
-          <div className="mx-auto max-w-7xl px-4 py-16 lg:px-8">
-            <h2 className="text-2xl font-semibold">Frequently asked</h2>
-            <dl className="mt-8 space-y-8">
-              {FAQ.map((item) => (
-                <div className="max-w-3xl" key={item.question}>
-                  <dt className="font-medium">{item.question}</dt>
-                  <dd className="mt-2 text-muted-foreground">{item.answer}</dd>
-                </div>
-              ))}
-            </dl>
-          </div>
-        </section>
-
-        <Footer />
-      </main>
-    </>
-  );
-}
diff --git a/apps/registry/e2e/family-homepage.spec.ts b/apps/registry/e2e/family-homepage.spec.ts
index 1e73fe84..129218e3 100644
--- a/apps/registry/e2e/family-homepage.spec.ts
+++ b/apps/registry/e2e/family-homepage.spec.ts
@@ -3,10 +3,10 @@ import { expect, test } from "@playwright/test";
 /**
  * Component family homepages (component-family phase).
  *
- * Each non-AI category has a landing page at /families/[category] with a hero,
- * a component grid, and a breadcrumb. The /components index family headings and
- * the component-page family crumb both link here. The `ai` family is excluded —
- * its curated landing lives at /ai.
+ * Every category — `ai` included — shares one landing template at
+ * /families/[category] with a hero, SEO sub-groups, a component grid, and a
+ * breadcrumb. The /components index family headings and the component-page
+ * family crumb both link here. `/ai` permanently redirects to /families/ai.
  */
 
 test.describe("component family homepage", () => {
@@ -26,6 +26,21 @@ test.describe("component family homepage", () => {
     ).toBeVisible();
   });
 
+  test("the ai family uses the shared grouped landing template", async ({
+    page,
+  }) => {
+    await page.goto("/families/ai");
+
+    await expect(
+      page.getByRole("heading", { level: 1, name: "AI components" }),
+    ).toBeVisible();
+
+    // SEO sub-groups render — the shared template, not the old bespoke hub.
+    await expect(
+      page.getByRole("heading", { level: 2, name: "Chat & Conversation" }),
+    ).toBeVisible();
+  });
+
   test("an unknown family 404s", async ({ page }) => {
     const response = await page.goto("/families/not-a-real-family");
     expect(response?.status()).toBe(404);
diff --git a/apps/registry/lib/family-copy.ts b/apps/registry/lib/family-copy.ts
index 2406d069..36180544 100644
--- a/apps/registry/lib/family-copy.ts
+++ b/apps/registry/lib/family-copy.ts
@@ -2,9 +2,9 @@ import type { ComponentCategory } from "@/types/registry";
 
 /**
  * Editorial copy for a component family landing page — an SEO-oriented intro and
- * a short FAQ. Families without an entry fall back to the one-line
- * `getCategoryDescription`. The `ai` family has its own curated page at `/ai`,
- * so this map skips it.
+ * a short FAQ. Every family (including `ai`) shares the one landing template at
+ * `/families/[category]`. Families without an entry fall back to the one-line
+ * `getCategoryDescription`.
  */
 export type FamilyCopy = {
   readonly category: ComponentCategory;
@@ -16,6 +16,34 @@ export type FamilyCopy = {
 };
 
 const FAMILY_COPY: readonly FamilyCopy[] = [
+  {
+    category: "ai",
+    faq: [
+      {
+        answer:
+          "An agent-first design system gives you the UI primitives that AI products actually need — chat input, message bubbles, streaming text, tool-call displays, source citations, agent activity timelines, and artifacts — and also ships every component as machine-readable JSON so AI coding agents can install it without scraping HTML. VLLNT UI is open source (MIT) and installs with the shadcn CLI.",
+        question: "What is an agent-first UI design system?",
+      },
+      {
+        answer:
+          "At minimum: AI Chat Input for the composer, AI Message Bubble to render each turn, and AI Streaming Text for token-by-token output. Add AI Tool Call Display and Agent Activity for agentic flows, AI Source Citation for RAG, and AI Artifact for canvas-style output.",
+        question:
+          "Which components do I need to build an AI chat app in React?",
+      },
+      {
+        answer:
+          "Three surfaces: /llms.txt (a concise index per the llmstxt.org spec), /llms-full.txt (the full registry context in one fetch), and /r/[name].json (a machine-readable descriptor per component with props, accessibility schema, and examples). Coding agents like Claude, Cursor, Cline, and Continue read these directly.",
+        question: "How do AI agents consume VLLNT UI?",
+      },
+      {
+        answer:
+          "Yes. VLLNT UI is open source under the MIT license. You own the source after install, with no backend and no tracking.",
+        question: "Is VLLNT UI free to use?",
+      },
+    ],
+    intro:
+      "Chat, agents, reasoning, tool calls, citations, and artifacts — the UI surfaces every AI product needs. Accessible React components you own after install, each also readable by AI coding agents as JSON.",
+  },
   {
     category: "core",
     faq: [
diff --git a/apps/registry/lib/family-groups.ts b/apps/registry/lib/family-groups.ts
new file mode 100644
index 00000000..d423989b
--- /dev/null
+++ b/apps/registry/lib/family-groups.ts
@@ -0,0 +1,704 @@
+import type { ComponentCategory } from "@/types/registry";
+
+/**
+ * SEO sub-groups for each component family landing page. Each group lists the
+ * slugs it holds, and the build checks these lists against the registry so every
+ * family member appears once and no slug repeats. Families without an entry fall
+ * back to a single flat grid.
+ */
+export type FamilyGroup = {
+  readonly blurb: string;
+  readonly heading: string;
+  readonly slugs: readonly string[];
+};
+
+type FamilyGroupSet = {
+  readonly category: ComponentCategory;
+  readonly groups: readonly FamilyGroup[];
+};
+
+const FAMILY_GROUPS: readonly FamilyGroupSet[] = [
+  {
+    category: "core",
+    groups: [
+      {
+        blurb:
+          "Buttons, copy-to-clipboard controls, toggles, and toolbars for triggering and grouping primary user actions.",
+        heading: "Buttons & Actions",
+        slugs: ["button", "copy-button", "toggle", "toggle-group", "toolbar"],
+      },
+      {
+        blurb:
+          "Core input primitives including text fields, checkboxes, radios, switches, sliders, and labels for capturing user data.",
+        heading: "Form Inputs",
+        slugs: [
+          "input",
+          "textarea",
+          "checkbox",
+          "radio-group",
+          "switch",
+          "slider",
+          "label",
+        ],
+      },
+      {
+        blurb:
+          "Badges, banners, meters, skeleton loaders, empty states, and cookie consent for surfacing status and system feedback.",
+        heading: "Status & Feedback",
+        slugs: [
+          "badge",
+          "banner",
+          "meter",
+          "skeleton",
+          "empty-state",
+          "cookie-consent",
+        ],
+      },
+      {
+        blurb:
+          "Structural primitives like grids, panels, and separators for composing page layout and content surfaces.",
+        heading: "Layout & Surfaces",
+        slugs: ["grid", "panel", "separator"],
+      },
+      {
+        blurb:
+          "Avatars, typography, links, QR codes, and keyboard hints for presenting content and identity.",
+        heading: "Content & Display",
+        slugs: ["avatar", "typography", "link", "qr-code", "kbd"],
+      },
+    ],
+  },
+  {
+    category: "form",
+    groups: [
+      {
+        blurb:
+          "Typed input fields for text, numbers, passwords, phone numbers, OTP codes, and inline editing.",
+        heading: "Text Inputs",
+        slugs: [
+          "text-field",
+          "inline-input",
+          "input-group",
+          "input-otp",
+          "number-input",
+          "password-input",
+          "phone-input",
+        ],
+      },
+      {
+        blurb:
+          "Dropdowns, comboboxes, list boxes, and multi-select controls for choosing from predefined options.",
+        heading: "Selection Controls",
+        slugs: [
+          "select",
+          "native-select",
+          "combobox",
+          "multi-select",
+          "list-box",
+          "segmented-control",
+          "button-group",
+          "checkbox-group",
+        ],
+      },
+      {
+        blurb:
+          "Tag editors, color pickers, and scoped selectors for specialized selection and entry tasks.",
+        heading: "Tags & Custom Pickers",
+        slugs: ["tag-group", "tags-input", "color-picker", "scope-selector"],
+      },
+      {
+        blurb:
+          "Search bars, search fields, filter bars, and category filters for querying and narrowing content lists.",
+        heading: "Search & Filtering",
+        slugs: ["category-filter", "filter-bar", "search-bar", "search-field"],
+      },
+      {
+        blurb:
+          "Calendars, date pickers, range pickers, and time selectors for capturing dates, times, and playback ranges.",
+        heading: "Date & Time",
+        slugs: [
+          "calendar",
+          "range-calendar",
+          "date-field",
+          "date-picker",
+          "date-range-picker",
+          "time-field",
+          "time-picker",
+          "timeline-scrubber",
+        ],
+      },
+      {
+        blurb:
+          "Form wrappers, fields, fieldsets, item rows, and file uploads for composing and validating complete forms.",
+        heading: "Form Structure",
+        slugs: [
+          "form",
+          "field",
+          "fieldset",
+          "item",
+          "file-upload",
+          "newsletter-signup",
+        ],
+      },
+    ],
+  },
+  {
+    category: "overlay",
+    groups: [
+      {
+        blurb:
+          "Modal dialogs for confirming actions, focusing attention, and sharing content, including alert and share dialogs.",
+        heading: "Modal Dialogs",
+        slugs: ["alert-dialog", "dialog", "share-dialog"],
+      },
+      {
+        blurb:
+          "Edge-anchored drawers and sheets for secondary content and mobile-friendly slide-out navigation.",
+        heading: "Slide-Out Panels",
+        slugs: ["drawer", "sheet"],
+      },
+      {
+        blurb:
+          "Command palettes and context, dropdown, and right-click menus for quick keyboard-driven actions.",
+        heading: "Menus & Commands",
+        slugs: ["command", "context-menu", "dropdown-menu"],
+      },
+      {
+        blurb:
+          "Floating popovers, hover cards, and tooltips for contextual hints and on-hover content previews.",
+        heading: "Popovers & Tooltips",
+        slugs: ["popover", "hover-card", "tooltip", "animated-tooltip"],
+      },
+      {
+        blurb:
+          "Transient toasts, canvas edge labels, and zoom HUD controls for feedback and on-canvas overlays.",
+        heading: "Notifications & Overlays",
+        slugs: ["toast", "edge-label", "zoom-hud"],
+      },
+    ],
+  },
+  {
+    category: "navigation",
+    groups: [
+      {
+        blurb:
+          "Top-level header bars, menu bars, and site chrome for orienting users across React and Next.js apps.",
+        heading: "Navigation Bars",
+        slugs: [
+          "navbar-saas",
+          "navigation-menu",
+          "menubar",
+          "floating-navbar",
+          "top-bar",
+        ],
+      },
+      {
+        blurb:
+          "Collapsible sidebars, vertical rails, and side docks for persistent app and canvas navigation.",
+        heading: "Sidebars & Rails",
+        slugs: [
+          "sidebar",
+          "sidebar-provider",
+          "sidebar-toggle",
+          "left-rail",
+          "right-dock",
+        ],
+      },
+      {
+        blurb:
+          "macOS-style docks and pinned bottom bars that host quick actions and calm canvas chrome.",
+        heading: "Docks & Bottom Bars",
+        slugs: ["dock", "jarvis-dock", "bottom-bar"],
+      },
+      {
+        blurb:
+          "Tabs, view switchers, and saved-view bookmarks for toggling between panels, workspaces, and layouts.",
+        heading: "Tabs & Views",
+        slugs: [
+          "tabs",
+          "animated-tabs",
+          "view-switcher",
+          "workspace-switcher",
+          "viewport-bookmarks",
+        ],
+      },
+      {
+        blurb:
+          "Breadcrumb trails, pagination, step navigation, and scroll rows for moving through paged and hierarchical content.",
+        heading: "Breadcrumbs & Paging",
+        slugs: [
+          "breadcrumb",
+          "world-breadcrumbs",
+          "pagination",
+          "step-navigation",
+          "horizontal-scroll-row",
+        ],
+      },
+    ],
+  },
+  {
+    category: "data",
+    groups: [
+      {
+        blurb:
+          "Area, bar, line, pie, radar, gauge, sankey, and flow charts for visualizing any dataset.",
+        heading: "Charts & Graphs",
+        slugs: [
+          "area-chart",
+          "bar-chart",
+          "line-chart",
+          "pie-chart",
+          "radar-chart",
+          "gauge-chart",
+          "sankey-chart",
+          "flow-diagram",
+        ],
+      },
+      {
+        blurb:
+          "Candlestick charts, order books, treemaps, ticker tapes, and watchlists for financial and market data.",
+        heading: "Market & Trading",
+        slugs: [
+          "candlestick-chart",
+          "order-book",
+          "market-treemap",
+          "ticker-tape",
+          "watchlist",
+        ],
+      },
+      {
+        blurb:
+          "Sortable data tables, key-value lists, and side-by-side comparisons for structured records.",
+        heading: "Tables & Lists",
+        slugs: [
+          "data-table",
+          "table",
+          "data-list",
+          "usage-breakdown",
+          "comparison",
+        ],
+      },
+      {
+        blurb:
+          "Stat cards, metric gauges, sparklines, progress bars, and overview boards for headline metrics and dashboards.",
+        heading: "Metrics & KPIs",
+        slugs: [
+          "stat-card",
+          "metric-cluster",
+          "metric-gauge",
+          "sticky-metric",
+          "threshold-ring",
+          "sparkline-grid",
+          "overview-board",
+          "progress-bar",
+          "progress-card",
+        ],
+      },
+      {
+        blurb:
+          "Status boards, indicators, severity badges, alerts, and timers for real-time operational health.",
+        heading: "Status & Signals",
+        slugs: [
+          "status-board",
+          "status-indicator",
+          "severity-badge",
+          "alert",
+          "countdown-timer",
+          "presence-sync-indicator",
+        ],
+      },
+      {
+        blurb:
+          "Activity feeds, heatmaps, timelines, live streams, and presence avatars for monitoring what is happening and who is online.",
+        heading: "Activity & Presence",
+        slugs: [
+          "activity-heatmap",
+          "activity-log",
+          "contribution-graph",
+          "live-feed",
+          "bottom-activity-strip",
+          "run-timeline",
+          "heat-overlay",
+          "gantt-chart",
+          "mini-map-panel",
+          "world-clock-bar",
+          "avatar-group",
+          "presence-stack",
+        ],
+      },
+    ],
+  },
+  {
+    category: "data-display",
+    groups: [
+      {
+        blurb:
+          "Choropleth maps, 3D globes, route maps, and geographic heat maps for spatial and geospatial data.",
+        heading: "Maps & Geography",
+        slugs: [
+          "choropleth-map",
+          "geography-quiz-map",
+          "globe-3d",
+          "heat-map-overlay",
+          "map-2d",
+          "map-timeline",
+          "route-map",
+          "story-map",
+        ],
+      },
+      {
+        blurb:
+          "Chronological, historical, and interactive multi-track timelines for sequencing events over time.",
+        heading: "Timelines",
+        slugs: [
+          "chronological-timeline",
+          "historic-timeline",
+          "interactive-timeline",
+        ],
+      },
+      {
+        blurb:
+          "Beams, beacons, selection halos, snap guides, and follow-mode chrome for interactive spatial canvases.",
+        heading: "Canvas Overlays",
+        slugs: [
+          "animated-beam",
+          "follow-mode",
+          "handoff-beacon",
+          "selection-halo",
+          "snap-guides",
+        ],
+      },
+      {
+        blurb:
+          "Scroll and glass progress bars plus floating toolbars for reading state and contextual selection actions.",
+        heading: "Progress & Toolbars",
+        slugs: ["glass-progress", "scroll-progress", "floating-toolbar"],
+      },
+      {
+        blurb:
+          "Tree views and primary-source document viewers for exploring nested data and archival source material.",
+        heading: "Documents & Hierarchy",
+        slugs: ["tree-view", "primary-source-viewer"],
+      },
+    ],
+  },
+  {
+    category: "content",
+    groups: [
+      {
+        blurb:
+          "React card and layout components — accordions, bento grids, carousels, and expandable cards for organizing page content.",
+        heading: "Cards & Layout",
+        slugs: [
+          "accordion",
+          "animated-list",
+          "animated-testimonials",
+          "bento-grid",
+          "blog-card",
+          "card",
+          "carousel",
+          "collapsible",
+          "expandable-cards",
+          "faq",
+          "slideshow",
+        ],
+      },
+      {
+        blurb:
+          "Animated text effect components for React — blur, shimmer, scramble, typewriter, and scroll-reveal typography.",
+        heading: "Text Effects",
+        slugs: [
+          "blur-reveal",
+          "reveal-text",
+          "scramble-text",
+          "shimmer-text",
+          "spinning-text",
+          "text-animate",
+          "text-reveal",
+          "text-shimmer",
+          "typewriter",
+        ],
+      },
+      {
+        blurb:
+          "Content blocks for articles and docs — code blocks, callouts, video embeds, timelines, and MDX rendering.",
+        heading: "Article & Media Blocks",
+        slugs: [
+          "callout",
+          "code-block",
+          "code-playground",
+          "content-intro",
+          "document-sibling-nav",
+          "mdx-content",
+          "share-section",
+          "terminal",
+          "timeline",
+          "tldr-section",
+          "video-embed",
+        ],
+      },
+      {
+        blurb:
+          "Right-dock inspector panels for canvas objects — property grids, relationships, routing, and runtime overviews.",
+        heading: "Canvas Inspectors",
+        slugs: [
+          "object-card",
+          "object-inspector",
+          "policy-delivery-panel",
+          "property-section",
+          "relationship-inspector",
+          "routing-assignment-panel",
+          "runtime-overview-panel",
+        ],
+      },
+      {
+        blurb:
+          "Account and billing status components — plan, role, and credit badges plus subscription and wallet cards.",
+        heading: "Account & Billing Badges",
+        slugs: [
+          "credit-badge",
+          "plan-badge",
+          "role-badge",
+          "subscription-card",
+          "wallet-card",
+        ],
+      },
+    ],
+  },
+  {
+    category: "learning",
+    groups: [
+      {
+        blurb:
+          "Tutorial and curriculum components for building courses, lesson browsers, and guided onboarding tours.",
+        heading: "Tutorials & Curriculum",
+        slugs: [
+          "curriculum",
+          "tour",
+          "tutorial-card",
+          "tutorial-complete",
+          "tutorial-filters",
+          "tutorial-intro-content",
+          "tutorial-mdx",
+        ],
+      },
+      {
+        blurb:
+          "Interactive quiz, exercise, and flashcard components with ratings for active-recall learning.",
+        heading: "Quizzes & Exercises",
+        slugs: ["quiz", "exercise", "flashcard", "rating"],
+      },
+      {
+        blurb:
+          "Learning progress components — checklists, steppers, progress trackers, and completion dialogs for tracking course advancement.",
+        heading: "Progress & Steps",
+        slugs: [
+          "checklist",
+          "completion-dialog",
+          "progress-tracker",
+          "step-by-step",
+          "stepper",
+        ],
+      },
+      {
+        blurb:
+          "Study aid components — annotations, key-concept blocks, pro tips, and learning objectives for educational content.",
+        heading: "Study Aids & Callouts",
+        slugs: ["annotation", "key-concept", "learning-objectives", "pro-tip"],
+      },
+      {
+        blurb:
+          "Learner utility components — profile sections, search dialogs, and keyboard shortcut helpers for learning platforms.",
+        heading: "Learner Utilities",
+        slugs: ["profile-section", "search-dialog", "keyboard-shortcuts-help"],
+      },
+    ],
+  },
+  {
+    category: "educational",
+    groups: [
+      {
+        blurb:
+          "Historical reference components — civilization overviews, historical figure profiles, and side-by-side era comparisons.",
+        heading: "Historical Reference Cards",
+        slugs: [
+          "civilization-card",
+          "era-comparison",
+          "historical-figure-card",
+        ],
+      },
+      {
+        blurb:
+          "Comparative history timelines and inline knowledge-check quizzes for teaching historical eras.",
+        heading: "History Timelines & Quizzes",
+        slugs: ["parallel-timeline", "knowledge-check"],
+      },
+    ],
+  },
+  {
+    category: "utility",
+    groups: [
+      {
+        blurb:
+          "Decorative animated backgrounds — grid, dot, particle, meteor, and sparkle effects that add ambient motion behind any React section.",
+        heading: "Background Effects",
+        slugs: [
+          "animated-grid-pattern",
+          "dot-pattern",
+          "meteors",
+          "particles",
+          "sparkles",
+        ],
+      },
+      {
+        blurb:
+          "Frosted glass surfaces, animated borders, spotlights, and progressive blur for premium card and panel styling.",
+        heading: "Surface & Border Effects",
+        slugs: [
+          "glass-card",
+          "glass-panel",
+          "liquid-glass",
+          "border-beam",
+          "shine-border",
+          "spotlight-card",
+          "progressive-blur",
+        ],
+      },
+      {
+        blurb:
+          "Magnetic buttons, 3D card flips, shimmer sheens, animated counters, marquees, and loading spinners that bring pointer-driven motion to your UI.",
+        heading: "Motion & Hover Interactions",
+        slugs: [
+          "card-flip",
+          "tilt-card",
+          "magnetic",
+          "magnetic-button",
+          "shimmer-button",
+          "shiny-button",
+          "cursor",
+          "floating-action-button",
+          "animated-text",
+          "number-ticker",
+          "marquee",
+          "spinner",
+        ],
+      },
+      {
+        blurb:
+          "Pan-and-zoom canvas shells, connectors, object handles, and real-time presence cursors for building spatial, multiplayer workspaces.",
+        heading: "Canvas Workspace & Collaboration",
+        slugs: [
+          "canvas-shell",
+          "canvas-view",
+          "infinite-plane",
+          "anchor-port",
+          "connector-edge",
+          "object-handle",
+          "group-hull",
+          "context-lens",
+          "multi-select-lasso",
+          "playback-ghost",
+          "alert-pulse",
+          "state-badge-overlay",
+          "comment-pin",
+          "live-cursor",
+          "selection-presence",
+          "thread-bubble",
+        ],
+      },
+      {
+        blurb:
+          "Aspect-ratio boxes, resizable panels, custom scroll areas, tables of contents, and text truncation for structuring page layouts.",
+        heading: "Layout Helpers",
+        slugs: [
+          "aspect-ratio",
+          "resizable",
+          "scroll-area",
+          "table-of-contents",
+          "table-of-contents-panel",
+          "truncated-text",
+        ],
+      },
+      {
+        blurb:
+          "Light/dark theme toggles, preset switchers, and context providers for theming and internationalization across your app.",
+        heading: "Theming & Providers",
+        slugs: [
+          "lang-provider",
+          "theme-preset-provider",
+          "theme-provider",
+          "theme-switcher",
+          "theme-toggle",
+        ],
+      },
+    ],
+  },
+  {
+    category: "billing",
+    groups: [
+      {
+        blurb:
+          "Pricing tables, auto-reload controls, and transaction history for subscription billing, credits, and payment management.",
+        heading: "Billing & Payments",
+        slugs: ["auto-reload", "pricing-table", "transaction-list"],
+      },
+    ],
+  },
+  {
+    category: "ai",
+    groups: [
+      {
+        blurb:
+          "Message bubbles, threaded conversations, and assistant sidebars for building complete AI chat interfaces.",
+        heading: "Chat & Conversation",
+        slugs: [
+          "ai-message-bubble",
+          "conversation-thread",
+          "ai-sidebar",
+          "chat-dock-section",
+        ],
+      },
+      {
+        blurb:
+          "Auto-growing prompt inputs, chat composers, and reusable prompt template galleries for capturing user instructions.",
+        heading: "Prompt Composition",
+        slugs: ["ai-chat-input", "prompt-input", "prompt-templates"],
+      },
+      {
+        blurb:
+          "Live token streaming, chain-of-thought traces, and collapsible reasoning blocks that reveal how an AI model thinks.",
+        heading: "Streaming & Reasoning",
+        slugs: [
+          "ai-streaming-text",
+          "chain-of-thought",
+          "reasoning",
+          "thinking-block",
+        ],
+      },
+      {
+        blurb:
+          "Agent activity chains, tool-call traces, and source citations that make AI agent execution transparent and verifiable.",
+        heading: "Agent Tools & Citations",
+        slugs: ["agent-activity", "ai-tool-call-display", "ai-source-citation"],
+      },
+      {
+        blurb:
+          "Rendered AI artifacts, model selectors, and side-by-side model comparison for generated outputs and model choice.",
+        heading: "Artifacts & Models",
+        slugs: ["ai-artifact", "model-selector", "model-comparison"],
+      },
+    ],
+  },
+];
+
+/**
+ * Ordered SEO sub-groups for a family, or `undefined` when the family has no
+ * grouping (the landing page then renders a single flat grid).
+ *
+ * @param category - the component category
+ */
+export function getFamilyGroups(
+  category: ComponentCategory,
+): readonly FamilyGroup[] | undefined {
+  return FAMILY_GROUPS.find((set) => set.category === category)?.groups;
+}

From dce9f03c4ddbef11ac776808961507c90dc43f51 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 21:16:23 +0200
Subject: [PATCH 14/16] =?UTF-8?q?test(registry):=20enforce=20family-groups?=
 =?UTF-8?q?=E2=86=94registry=20integrity=20+=20fix=20stale=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds family-groups.test.ts asserting, per family, that the grouped slugs
stay a complete, non-overlapping cover of the registry members — so the
landing hero count and grid can never diverge (and every family keeps a
groups entry). Corrects the family-groups.ts docstring that claimed a
non-existent build check, and refreshes ai-seo.ts / component-card.tsx
comments that referenced the removed /ai hub.

Claude-Session: https://claude.ai/code/session_01B9kb7NGCUjYYYeWB17Z3S9
---
 .../component-card/component-card.tsx         |  4 +-
 apps/registry/lib/ai-seo.ts                   | 14 +++---
 apps/registry/lib/family-groups.test.ts       | 45 +++++++++++++++++++
 apps/registry/lib/family-groups.ts            |  7 +--
 4 files changed, 60 insertions(+), 10 deletions(-)
 create mode 100644 apps/registry/lib/family-groups.test.ts

diff --git a/apps/registry/components/component-card/component-card.tsx b/apps/registry/components/component-card/component-card.tsx
index 651b5520..bae66d89 100644
--- a/apps/registry/components/component-card/component-card.tsx
+++ b/apps/registry/components/component-card/component-card.tsx
@@ -26,8 +26,8 @@ type ComponentCardProps = {
 
 /**
  * Shared gallery card: a live component preview above its title, description, and
- * story count, linking to the component page. Used by the components index, the
- * per-family landing pages, and the AI hub so every surface looks identical.
+ * story count, linking to the component page. Used by the components index and
+ * the per-family landing pages so every surface looks identical.
  *
  * @param slug - registry component slug
  * @param locale - active locale for the link
diff --git a/apps/registry/lib/ai-seo.ts b/apps/registry/lib/ai-seo.ts
index af6f18c0..32f1c62a 100644
--- a/apps/registry/lib/ai-seo.ts
+++ b/apps/registry/lib/ai-seo.ts
@@ -7,9 +7,11 @@ import { registry } from "@/lib/registry";
  * 1. The component page (`/components/[slug]`) — overrides the document title +
  *    meta description for AI components and renders a "When to use in an AI app"
  *    block, so both Google and answer engines understand the use-case.
- * 2. The AI category hub (`/ai`) — groups the AI component family by
- *    job-to-be-done and links to every member, concentrating internal-link
- *    equity on the wedge.
+ * 2. The sitemap (`app/sitemap.ts`) — `getAiComponentSlugs()` (derived from
+ *    `AI_COMPONENT_GROUPS`) marks the AI wedge for higher crawl priority. That
+ *    curated set is a marketing grouping, separate from the registry `ai` family
+ *    in `family-groups.ts` (which drives the `/families/ai` landing); it also
+ *    lists components from other families.
  *
  * Keep SEO copy here, not in the generated `component-metadata.json` (that file
  * is rebuilt by `registry:build` and would overwrite hand-written copy).
@@ -143,8 +145,10 @@ export type AiComponentGroup = {
 };
 
 /**
- * The AI component family grouped by job-to-be-done. Drives the `/ai` hub and
- * the internal-linking structure that concentrates equity on AI components.
+ * The AI component family grouped by job-to-be-done — a curated marketing set
+ * that feeds `getAiComponentSlugs()` and the sitemap's AI-wedge crawl priority.
+ * Separate from the registry `ai` family in `family-groups.ts`; it also lists
+ * components from other families.
  */
 export const AI_COMPONENT_GROUPS: readonly AiComponentGroup[] = [
   {
diff --git a/apps/registry/lib/family-groups.test.ts b/apps/registry/lib/family-groups.test.ts
new file mode 100644
index 00000000..a0d91bb6
--- /dev/null
+++ b/apps/registry/lib/family-groups.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { groupedComponents } from "@/lib/component-categories";
+import { getFamilyGroups } from "@/lib/family-groups";
+
+/**
+ * Integrity guard for the family landing template. The hero count and the
+ * `collectionPageLd` read from `groupedComponents` (registry-derived), while the
+ * grid renders the hand-authored slugs in `family-groups.ts`. If the two drift,
+ * the page shows a wrong count or renders a component twice. These tests keep the
+ * grouped slugs a complete, non-overlapping cover of each family's registry
+ * members.
+ */
+describe("family-groups integrity", () => {
+  it("gives every family a groups entry, so none renders the flat-grid fallback", () => {
+    const missing = groupedComponents
+      .filter((group) => getFamilyGroups(group.category) === undefined)
+      .map((group) => group.category);
+
+    expect(missing).toEqual([]);
+  });
+
+  it("covers every registry member of a family once, with no foreign or duplicate slugs", () => {
+    const mismatches = groupedComponents
+      .filter((group) => {
+        const groups = getFamilyGroups(group.category);
+        if (!groups) {
+          return false;
+        }
+
+        const itemSlugs = group.items.map((item) => item.name).sort();
+        const groupSlugs = groups.flatMap((section) => section.slugs);
+        const uniqueGroupSlugs = [...new Set(groupSlugs)].sort();
+
+        const hasDuplicate = groupSlugs.length !== uniqueGroupSlugs.length;
+        const coversMembers =
+          JSON.stringify(uniqueGroupSlugs) === JSON.stringify(itemSlugs);
+
+        return hasDuplicate || !coversMembers;
+      })
+      .map((group) => group.category);
+
+    expect(mismatches).toEqual([]);
+  });
+});
diff --git a/apps/registry/lib/family-groups.ts b/apps/registry/lib/family-groups.ts
index d423989b..ae261a1c 100644
--- a/apps/registry/lib/family-groups.ts
+++ b/apps/registry/lib/family-groups.ts
@@ -2,9 +2,10 @@ import type { ComponentCategory } from "@/types/registry";
 
 /**
  * SEO sub-groups for each component family landing page. Each group lists the
- * slugs it holds, and the build checks these lists against the registry so every
- * family member appears once and no slug repeats. Families without an entry fall
- * back to a single flat grid.
+ * slugs it holds; `family-groups.test.ts` asserts these slugs stay a complete,
+ * non-overlapping cover of each family's registry members, so the hero count and
+ * the rendered grid never diverge. Families without an entry fall back to a
+ * single flat grid.
  */
 export type FamilyGroup = {
   readonly blurb: string;

From 9c26dba0f4a1ead314bae91446e15bb9641cc136 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 21:59:07 +0200
Subject: [PATCH 15/16] chore(registry): regenerate metadata after merge +
 changelog

Merges origin/main. Regenerates component-metadata.json so the AI
recategorization (learning/form -> ai) survives the merge (taking main's
generated file had reverted it). Adds the family-pages entry to the
CHANGELOG Unreleased section.

Claude-Session: https://claude.ai/code/session_01B9kb7NGCUjYYYeWB17Z3S9
---
 CHANGELOG.md                              | 17 ++++++++++++++++-
 apps/registry/lib/component-metadata.json | 16 ++++++++--------
 2 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8744a636..1dfd1868 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,22 @@ Release automation can regenerate this file from Conventional Commits with
 
 ## [Unreleased]
 
-_Nothing yet._
+### Added
+
+- **Component family landing pages** - every component family has a standalone,
+  SEO-oriented landing at `/families/[category]`, plus a `/families` index. One
+  shared template renders a hero with CTAs, per-family SEO sub-groups with
+  editorial copy and live component previews, an agent-readable surface
+  (`/llms.txt`, `/llms-full.txt`, `/r/<name>.json`), and a FAQ. Each page ships
+  `CollectionPage`/`ItemList`, `FAQPage`, and `BreadcrumbList` JSON-LD and is
+  listed in the sitemap.
+
+### Changed
+
+- **AI family consolidated onto the shared template** - the bespoke `/ai` hub is
+  gone; `/ai` now permanently redirects to `/families/ai`, which renders through
+  the same family template. AI components are recategorized out of the
+  `learning` family into `ai`.
 
 ## [0.3.0] - 2026-06-26
 
diff --git a/apps/registry/lib/component-metadata.json b/apps/registry/lib/component-metadata.json
index 735addd0..4ae735c2 100644
--- a/apps/registry/lib/component-metadata.json
+++ b/apps/registry/lib/component-metadata.json
@@ -101,7 +101,7 @@
     "title": "AI Artifact"
   },
   "ai-chat-input": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-chatinput--default",
     "description": "Prompt composer for conversational interfaces with helper text, toolbar actions, and submit states.",
     "name": "ai-chat-input",
@@ -118,7 +118,7 @@
     "title": "AI Chat Input"
   },
   "ai-message-bubble": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-messagebubble--default",
     "description": "Chat bubble for assistant, user, tool, and system messages using the current design system surfaces.",
     "name": "ai-message-bubble",
@@ -160,7 +160,7 @@
     "title": "AI Sidebar"
   },
   "ai-source-citation": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-sourcecitation--default",
     "description": "Compact source reference card for AI answers with a title, origin label, and optional excerpt.",
     "name": "ai-source-citation",
@@ -173,7 +173,7 @@
     "title": "AI Source Citation"
   },
   "ai-streaming-text": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-streamingtext--default",
     "description": "Readable text block for partial assistant output with an optional live cursor while tokens stream in.",
     "name": "ai-streaming-text",
@@ -190,7 +190,7 @@
     "title": "AI Streaming Text"
   },
   "ai-tool-call-display": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-toolcalldisplay--default",
     "description": "Structured card for tool invocation traces, statuses, serialized input, and returned output.",
     "name": "ai-tool-call-display",
@@ -1289,7 +1289,7 @@
     "title": "Contribution Graph"
   },
   "conversation-thread": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "ai-conversationthread--default",
     "description": "Compound component family for AI chat UIs that orchestrates auto-scroll, streaming indicators, empty states, and message rendering.",
     "name": "conversation-thread",
@@ -2875,7 +2875,7 @@
     "title": "Model Comparison"
   },
   "model-selector": {
-    "category": "form",
+    "category": "ai",
     "defaultStoryId": "form-modelselector--default",
     "description": "Dropdown selector for choosing AI models.",
     "name": "model-selector",
@@ -4893,7 +4893,7 @@
     "title": "Theme Toggle"
   },
   "thinking-block": {
-    "category": "learning",
+    "category": "ai",
     "defaultStoryId": "learning-thinkingblock--default",
     "description": "Collapsible block showing AI thinking/reasoning with streaming support.",
     "name": "thinking-block",

From 2e442447a4f19e9abfd61b10385d959aef7bf4a0 Mon Sep 17 00:00:00 2001
From: bntvllnt <bntvllnt@users.noreply.github.com>
Date: Thu, 2 Jul 2026 22:19:37 +0200
Subject: [PATCH 16/16] fix(registry): re-apply AI recategorization + group new
 typography primitives

Merging main pulled in the typography primitives (#465, +4 core components)
and reverted the AI recategorization in registry.json. Re-flips the 8 AI
components (learning/form -> ai) and adds a Typography group to the core
family so `family-groups.test.ts` stays green (every family's groups cover
its registry members).

Claude-Session: https://claude.ai/code/session_01B9kb7NGCUjYYYeWB17Z3S9
---
 apps/registry/lib/family-groups.ts |  6 ++++++
 apps/registry/registry.json        | 18 +++++++++---------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/apps/registry/lib/family-groups.ts b/apps/registry/lib/family-groups.ts
index ae261a1c..2e9638de 100644
--- a/apps/registry/lib/family-groups.ts
+++ b/apps/registry/lib/family-groups.ts
@@ -67,6 +67,12 @@ const FAMILY_GROUPS: readonly FamilyGroupSet[] = [
         heading: "Content & Display",
         slugs: ["avatar", "typography", "link", "qr-code", "kbd"],
       },
+      {
+        blurb:
+          "Text, heading, display, and prose primitives with token-driven font family, weight, and type scale for consistent typography.",
+        heading: "Typography",
+        slugs: ["text", "heading", "display", "prose"],
+      },
     ],
   },
   {
diff --git a/apps/registry/registry.json b/apps/registry/registry.json
index d785a01d..6e3f4493 100644
--- a/apps/registry/registry.json
+++ b/apps/registry/registry.json
@@ -116,7 +116,7 @@
         "@vllnt/ui@^0.3.0",
         "lucide-react"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -136,7 +136,7 @@
         "@vllnt/ui@^0.3.0",
         "class-variance-authority"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -176,7 +176,7 @@
         "@vllnt/ui@^0.3.0",
         "lucide-react"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -195,7 +195,7 @@
       "dependencies": [
         "@vllnt/ui@^0.3.0"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -216,7 +216,7 @@
         "class-variance-authority",
         "lucide-react"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -1548,7 +1548,7 @@
       "dependencies": [
         "@vllnt/ui@^0.3.0"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -3287,7 +3287,7 @@
       "dependencies": [
         "@vllnt/ui@^0.3.0"
       ],
-      "category": "form",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -5506,7 +5506,7 @@
         "@vllnt/ui@^0.3.0",
         "lucide-react"
       ],
-      "category": "learning",
+      "category": "ai",
       "version": "0.3.0",
       "stability": "stable"
     },
@@ -6198,5 +6198,5 @@
     }
   ],
   "version": "0.3.0",
-  "generatedAt": "2026-07-02T19:20:42.087Z"
+  "generatedAt": "2026-07-02T20:13:54.208Z"
 }