feat(registry): generalize component-page SEO (prose + FAQ + related) (#487)

## What

From Search Console: component pages earn impressions but rank page 1-2,
and the pages ranking best are exactly the ~13 AI components with
hand-written copy (`ai-seo.ts`). This generalizes that treatment to the
wider catalog — the striking-distance and vllnt-distinctive pages the
data flags (e.g. **"react callout"** = 22 impressions at pos 79).

## Changes (2 files, +850)

- **New `lib/component-seo.ts`** — general counterpart to `ai-seo.ts`.
Hand-written, **source-verified** (each entry authored after reading the
actual component) SEO for **26 components**: title, meta description, a
usage prose paragraph, **3 FAQs**, and related slugs. Targets: marquee,
data-table, callout, live-cursor, edge-label, canvas-view, anchor-port,
workspace-switcher, viewport-bookmarks, timeline-scrubber, gantt-chart,
quiz, checklist, search-dialog, segmented-control, border-beam,
carousel, toggle, select, command, hover-card, form, sheet,
dropdown-menu, calendar, table.
- **`components/[slug]/page.tsx`** consumes it:
- title/description precedence: `ai-seo` → `component-seo` → registry
(AI wedge unchanged).
- a "What it is & when to use" prose block (mirrors the AI block; links
to the component's family).
- **FAQPage structured data + a visible FAQ** — `searchAppearance` is
currently empty (zero rich results); this is the GEO / AI-overview
citation hook.
- a **Related components** section — internal linking, curated slugs
with a same-family-siblings fallback so *every* component page gains
related links.

## Why (data)

`docs/seo/gsc-improvement-plan.md`. The AI-wedge pages already rank pos
5-7 with this exact treatment; the rest of the catalog had generic
`"{Name} - VLLNT UI"` titles + one thin sentence. This is the proven
lever.

## Validation

- `eslint` clean, `tsc --noEmit` 0 errors (workspace deps installed in
an isolated worktree).
- 26 entries assembled from 6 parallel authoring passes; all slugs +
related verified against `component-metadata.json`.
- Full build + preview via CI; will spot-check a component page (e.g.
`/components/callout`) renders the FAQ + Related sections on the
preview.

## Not included (separate concerns)

- Off-site authority (shadcn registry index, Context7) — not code in
this repo.
- More components can be added incrementally to `component-seo.ts` using
the same shape.

Closes #486

Co-authored-by: bntvllnt <bntvllnt@users.noreply.github.com>

Author: bntvllnt

apps/registry/app/[locale]/components/[slug]/page.tsx

@@ -20,8 +20,10 @@ import { ShareEmbedBar } from "@/components/share-embed-bar";
 import { type Locale, routing } from "@/i18n/routing";
 import { getAiSeo } from "@/lib/ai-seo";
 import componentMetadata from "@/lib/component-metadata.json";
+import { getComponentSeo } from "@/lib/component-seo";
 import {
   breadcrumbLd,
+  faqPageLd,
   jsonLdScriptAttributes,
   softwareSourceCodeLd,
 } from "@/lib/jsonld";
@@ -91,9 +93,13 @@ export async function generateMetadata(props: Props): Promise<Metadata> {
   const meta = metadata_map[slug];
   const category = getCategoryForComponent(slug);
   const aiSeo = getAiSeo(slug);
+  const componentSeo = getComponentSeo(slug);
   const title = meta?.title ?? component.title;
   const description =
-    aiSeo?.description ?? meta?.description ?? component.description;
+    aiSeo?.description ??
+    componentSeo?.description ??
+    meta?.description ??
+    component.description;
   const pathname = `/components/${slug}`;
 
   const ogParameters = {
@@ -113,7 +119,7 @@ export async function generateMetadata(props: Props): Promise<Metadata> {
     },
     description,
     openGraph: generateOGMetadata(ogParameters, { locale, pathname }),
-    title: aiSeo?.title ?? `${title} - VLLNT UI`,
+    title: aiSeo?.title ?? componentSeo?.title ?? `${title} - VLLNT UI`,
     twitter: generateTwitterMetadata(ogParameters),
   };
 }
@@ -132,9 +138,14 @@ export default async function ComponentPage(props: Props) {
 
   const meta = metadata_map[slug];
   const aiSeo = getAiSeo(slug);
+  const componentSeo = getComponentSeo(slug);
   const displayTitle = meta?.title ?? component.title ?? component.name;
   const displayDescription =
-    aiSeo?.description ?? meta?.description ?? component.description ?? "";
+    aiSeo?.description ??
+    componentSeo?.description ??
+    meta?.description ??
+    component.description ??
+    "";
   const playgroundExample = getPlaygroundExample(component);
   const registryPackageVersion = getRegistryPackageVersion(registry.version);
 
@@ -195,6 +206,23 @@ export default async function ComponentPage(props: Props) {
     ? groupedComponents.find((group) => group.category === componentCategory)
     : undefined;
 
+  const relatedSlugs = (
+    componentSeo && componentSeo.related.length > 0
+      ? componentSeo.related
+      : (familyGroup?.items ?? []).map((item) => item.name)
+  )
+    .filter((name) => name !== component.name)
+    .slice(0, 6);
+  const relatedComponents = relatedSlugs
+    .map((name) =>
+      registry.items.find(
+        (item): item is RegistryComponent =>
+          item.name === name && item.type === "registry:component",
+      ),
+    )
+    .filter((item): item is RegistryComponent => item !== undefined)
+    .map((item) => ({ name: item.name, title: item.title ?? item.name }));
+
   const sections = [
     { id: "installation", title: "Installation" },
     ...(meta?.defaultStoryId ? [{ id: "preview", title: "Preview" }] : []),
@@ -203,6 +231,10 @@ export default async function ComponentPage(props: Props) {
     ...(component.dependencies && component.dependencies.length > 0
       ? [{ id: "dependencies", title: "Dependencies" }]
       : []),
+    ...(componentSeo?.faqs.length ? [{ id: "faq", title: "FAQ" }] : []),
+    ...(relatedComponents.length > 0
+      ? [{ id: "related", title: "Related" }]
+      : []),
   ] as { id: string; title: string }[];
 
   const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://ui.vllnt.com";
@@ -224,6 +256,7 @@ export default async function ComponentPage(props: Props) {
               url: `${SITE_URL}/components/${component.name}`,
             },
           ]),
+          ...(componentSeo?.faqs.length ? [faqPageLd(componentSeo.faqs)] : []),
         ])}
       />
       <Sidebar
@@ -299,6 +332,30 @@ export default async function ComponentPage(props: Props) {
                 </div>
               ) : null}
 
+              {/* Usage block for non-AI components */}
+              {!aiSeo?.whenToUse && componentSeo?.whatItIs ? (
+                <div className="mb-8 rounded-lg border border-border bg-muted/30 p-6">
+                  <h2 className="text-sm font-medium uppercase tracking-wide text-muted-foreground">
+                    What it is &amp; when to use
+                  </h2>
+                  <p className="mt-3 text-base leading-relaxed">
+                    {componentSeo.whatItIs}
+                  </p>
+                  {familyGroup ? (
+                    <Link
+                      className="mt-4 inline-flex items-center gap-1 text-sm font-medium text-foreground underline"
+                      href={localizePathname(
+                        familyPath(familyGroup.category),
+                        locale,
+                      )}
+                    >
+                      Browse all {familyGroup.label}
+                      <ExternalLink className="size-3" />
+                    </Link>
+                  ) : null}
+                </div>
+              ) : null}
+
               {/* Preview + Playground */}
               {meta?.defaultStoryId ? (
                 <PreviewPlaygroundTabs
@@ -393,6 +450,48 @@ export default async function ComponentPage(props: Props) {
                 </div>
               ) : null}
 
+              {/* FAQ (visible content backing FAQPage structured data) */}
+              {componentSeo?.faqs.length ? (
+                <div className="mb-8 scroll-mt-8" id="faq">
+                  <h2 className="text-2xl font-semibold mb-4">
+                    Frequently asked questions
+                  </h2>
+                  <dl className="space-y-6">
+                    {componentSeo.faqs.map((faq) => (
+                      <div key={faq.question}>
+                        <dt className="font-medium">{faq.question}</dt>
+                        <dd className="mt-2 leading-relaxed text-muted-foreground">
+                          {faq.answer}
+                        </dd>
+                      </div>
+                    ))}
+                  </dl>
+                </div>
+              ) : null}
+
+              {/* Related components (internal linking) */}
+              {relatedComponents.length > 0 ? (
+                <div className="mb-8 scroll-mt-8" id="related">
+                  <h2 className="text-2xl font-semibold mb-4">
+                    Related components
+                  </h2>
+                  <div className="flex flex-wrap gap-2">
+                    {relatedComponents.map((related) => (
+                      <Link
+                        className="rounded-md border px-3 py-1 text-sm transition-colors hover:bg-muted"
+                        href={localizePathname(
+                          `/components/${related.name}`,
+                          locale,
+                        )}
+                        key={related.name}
+                      >
+                        {related.title}
+                      </Link>
+                    ))}
+                  </div>
+                </div>
+              ) : null}
+
               <ShareSection
                 shareOn="Share on"
                 shareTitle="Share this component"