From 06878f2d36a4e49587235965dc4213dad943e54c Mon Sep 17 00:00:00 2001
From: Din <iamdinq@gmail.com>
Date: Wed, 4 Mar 2026 01:23:11 +0000
Subject: [PATCH] fix(www): SEO/AEO audit improvements
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add robots.txt with sitemap reference
- Add Organization JSON-LD structured data site-wide
- Add BreadcrumbList JSON-LD to doc and component pages
- Fix heading hierarchy on homepage (h3 → h2)
- Add noindex to 404 page
- Fix og:type from website to article on component pages
- Add aria-hidden to decorative SVGs on landing page
- Support robotsMeta and structuredData props in root layout

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 apps/www/public/robots.txt                    |  6 ++++
 .../landing/components-overview.astro         |  2 +-
 apps/www/src/components/landing/cta.astro     | 16 +++++-----
 .../www/src/components/landing/features.astro | 12 +++----
 apps/www/src/components/landing/shadcn.astro  |  4 +--
 apps/www/src/components/structured-data.astro | 12 +++++++
 apps/www/src/layouts/root-layout.astro        | 23 +++++++++++--
 apps/www/src/pages/404.astro                  |  1 +
 apps/www/src/pages/docs/[...slug].astro       | 24 ++++++++++++++
 .../pages/docs/components/[component].astro   | 32 ++++++++++++++++++-
 10 files changed, 112 insertions(+), 20 deletions(-)
 create mode 100644 apps/www/public/robots.txt
 create mode 100644 apps/www/src/components/structured-data.astro

diff --git a/apps/www/public/robots.txt b/apps/www/public/robots.txt
new file mode 100644
index 00000000..ba358d88
--- /dev/null
+++ b/apps/www/public/robots.txt
@@ -0,0 +1,6 @@
+User-agent: *
+Allow: /
+
+Disallow: /api/
+
+Sitemap: https://ui.shipbase.xyz/sitemap-index.xml
diff --git a/apps/www/src/components/landing/components-overview.astro b/apps/www/src/components/landing/components-overview.astro
index b654c2c6..e05b31ea 100644
--- a/apps/www/src/components/landing/components-overview.astro
+++ b/apps/www/src/components/landing/components-overview.astro
@@ -4,7 +4,7 @@ import ExampleCards from "../example-cards/index.astro"
 
 <section class="relative overflow-hidden">
   <div class="p-6 xs:p-8 flex flex-col gap-4">
-    <h3 class="text-3xl font-bold">Everything you need to build</h3>
+    <h2 class="text-3xl font-bold">Everything you need to build</h2>
     <p class="text-muted-foreground leading-relaxed">
       A comprehensive component library with 30+ production-ready components,
       rich examples, and ready-to-use blocks. Built on Ark UI primitives with
diff --git a/apps/www/src/components/landing/cta.astro b/apps/www/src/components/landing/cta.astro
index 35c8228d..94e1206a 100644
--- a/apps/www/src/components/landing/cta.astro
+++ b/apps/www/src/components/landing/cta.astro
@@ -59,19 +59,19 @@ import Vue from "@/assets/logos/vue.svg"
     </p>
     <div class="flex flex-wrap justify-center gap-3 sm:gap-6">
       <div class="flex items-center gap-2">
-        <TailwindCSS width="24" height="24" />
+        <TailwindCSS width="24" height="24" aria-hidden="true" />
         <span class="text-sm">Tailwind CSS</span>
       </div>
       <div class="flex items-center gap-2">
-        <ArkUI width="24" height="24" />
+        <ArkUI width="24" height="24" aria-hidden="true" />
         <span class="text-sm">Ark UI</span>
       </div>
       <div class="flex items-center gap-2">
-        <TypeScript width="24" height="24" />
+        <TypeScript width="24" height="24" aria-hidden="true" />
         <span class="text-sm">TypeScript</span>
       </div>
       <div class="flex items-center gap-2">
-        <CVA width="24" height="24" />
+        <CVA width="24" height="24" aria-hidden="true" />
         <span class="text-sm">CVA</span>
       </div>
     </div>
@@ -85,19 +85,19 @@ import Vue from "@/assets/logos/vue.svg"
     </p>
     <div class="flex flex-wrap justify-center gap-6 sm:gap-12 md:gap-16">
       <div class="flex flex-col items-center gap-2">
-        <React width="32" height="32" />
+        <React width="32" height="32" aria-hidden="true" />
         <span class="text-sm">React</span>
       </div>
       <div class="flex flex-col items-center gap-2">
-        <Vue width="32" height="32" />
+        <Vue width="32" height="32" aria-hidden="true" />
         <span class="text-sm">Vue</span>
       </div>
       <div class="flex flex-col items-center gap-2 opacity-50">
-        <Svelte width="32" height="32" />
+        <Svelte width="32" height="32" aria-hidden="true" />
         <span class="text-sm text-muted-foreground">Soon</span>
       </div>
       <div class="flex flex-col items-center gap-2 opacity-50">
-        <Solid width="32" height="32" />
+        <Solid width="32" height="32" aria-hidden="true" />
         <span class="text-sm text-muted-foreground">Soon</span>
       </div>
     </div>
diff --git a/apps/www/src/components/landing/features.astro b/apps/www/src/components/landing/features.astro
index 3f4047ef..b6ff74b3 100644
--- a/apps/www/src/components/landing/features.astro
+++ b/apps/www/src/components/landing/features.astro
@@ -12,7 +12,7 @@ import { cn } from "@/lib/utils"
 <section class="relative overflow-hidden">
   <!-- Featured item: Meta-Framework Support -->
   <div class="p-6 xs:p-8 flex flex-col gap-2 border-b border-border/50 hover:bg-card/70">
-    <h3 class="text-2xl font-bold">Framework Agnostic</h3>
+    <h2 class="text-2xl font-bold">Framework Agnostic</h2>
     <p class="text-muted-foreground leading-tight">
       Works with any React, Vue, Solid, Svelte stack. Whether you're using
       Next.js, Nuxt, Astro, or SvelteKit. our components integrate seamlessly
@@ -51,7 +51,7 @@ import { cn } from "@/lib/utils"
     <div
       class="p-6 xs:p-8 flex flex-col gap-2 border-r hover:bg-card/70 transition-colors"
     >
-      <h3 class="text-xl font-bold">Composable Design</h3>
+      <h2 class="text-xl font-bold">Composable Design</h2>
       <p class="text-muted-foreground leading-tight">
         Every component uses a common, composable interface. Build complex UIs
         effortlessly with modular components that work seamlessly together.
@@ -62,7 +62,7 @@ import { cn } from "@/lib/utils"
     <div
       class="p-6 xs:p-8 flex flex-col gap-2 hover:bg-card/70 transition-colors"
     >
-      <h3 class="text-xl font-bold">Fully Accessible</h3>
+      <h2 class="text-xl font-bold">Fully Accessible</h2>
       <p class="text-muted-foreground leading-tight">
         Screen reader tested. Keyboard navigation perfected. Built-in focus
         management. Accessibility isn't an afterthought—it's the foundation.
@@ -76,7 +76,7 @@ import { cn } from "@/lib/utils"
     <div
       class="p-6 xs:p-8 flex flex-col gap-2 border-r hover:bg-card/70 transition-colors"
     >
-      <h3 class="text-xl font-bold">Beautiful Defaults</h3>
+      <h2 class="text-xl font-bold">Beautiful Defaults</h2>
       <p class="text-muted-foreground leading-tight">
         Thoughtfully crafted default styles that look professional from day one.
         Beautiful foundations, endless customization possibilities.
@@ -87,7 +87,7 @@ import { cn } from "@/lib/utils"
     <div
       class="p-6 xs:p-8 flex flex-col gap-2 border-r hover:bg-card/70 transition-colors"
     >
-      <h3 class="text-xl font-bold">Code Ownership</h3>
+      <h2 class="text-xl font-bold">Code Ownership</h2>
       <p class="text-muted-foreground leading-tight">
         No vendor lock-in. No hidden dependencies. Install via CLI or
         copy-paste. All components live in your repo — you own your codebase.
@@ -102,7 +102,7 @@ import { cn } from "@/lib/utils"
         "before:absolute before:inset-0 before:bg-gradient-to-br before:from-transparent before:to-primary/5 before:opacity-0 hover:before:opacity-100 before:transition-opacity before:duration-300"
       )}
     >
-      <h3 class="text-xl font-bold">Open Source</h3>
+      <h2 class="text-xl font-bold">Open Source</h2>
       <p class="text-muted-foreground leading-tight">
         MIT licensed. Transparent development. Community contributions welcome.
         Built by developers, for developers, with developers.
diff --git a/apps/www/src/components/landing/shadcn.astro b/apps/www/src/components/landing/shadcn.astro
index 21c6f660..4fe8f854 100644
--- a/apps/www/src/components/landing/shadcn.astro
+++ b/apps/www/src/components/landing/shadcn.astro
@@ -6,7 +6,7 @@ import ShadcnXTitle from "@/components/landing/shadcn-x-title.astro"
 
 <section class="grid lg:grid-cols-2 items-center">
   <div class="h-full p-6 xs:p-8 flex flex-col gap-2">
-    <h3 class="text-xl font-bold flex items-center gap-3">
+    <h2 class="text-xl font-bold flex items-center gap-3">
       Inspired by
       <span class="inline-flex items-center gap-1">
         <ShadcnUIDark
@@ -23,7 +23,7 @@ import ShadcnXTitle from "@/components/landing/shadcn-x-title.astro"
         />
         shadcn/ui
       </span>
-    </h3>
+    </h2>
     <p class="text-muted-foreground leading-tight">
       shadcn/ui is a game changer that revolutionized the way to build component
       libraries through Composition, Distribution system, and AI-Ready.
diff --git a/apps/www/src/components/structured-data.astro b/apps/www/src/components/structured-data.astro
new file mode 100644
index 00000000..cb0efbf1
--- /dev/null
+++ b/apps/www/src/components/structured-data.astro
@@ -0,0 +1,12 @@
+---
+export interface Props {
+  data: Record<string, unknown> | Record<string, unknown>[]
+}
+
+const { data } = Astro.props
+const items = Array.isArray(data) ? data : [data]
+---
+
+{items.map((item) => (
+  <script type="application/ld+json" set:html={JSON.stringify(item)} />
+))}
diff --git a/apps/www/src/layouts/root-layout.astro b/apps/www/src/layouts/root-layout.astro
index c5c5c6c3..c9a4c2a1 100644
--- a/apps/www/src/layouts/root-layout.astro
+++ b/apps/www/src/layouts/root-layout.astro
@@ -3,6 +3,7 @@ import { ClientRouter } from "astro:transitions"
 
 import SiteFooter from "@/components/side-footer.astro"
 import SiteHeader from "@/components/site-header.astro"
+import StructuredData from "@/components/structured-data.astro"
 import TailwindIndicator from "@/components/tailwind-indicator.astro"
 import { META_THEME_COLORS, siteConfig } from "@/config/site"
 
@@ -14,6 +15,7 @@ export interface Props {
   metadata: {
     title: string
     description: string
+    robotsMeta?: string
     openGraph: {
       type: "website" | "article" | "book" | "profile" | (string & {})
       title: string
@@ -31,10 +33,24 @@ export interface Props {
       }
     }
   }
+  structuredData?: Record<string, unknown> | Record<string, unknown>[]
 }
 
-const { metadata } = Astro.props as Props
+const { metadata, structuredData } = Astro.props as Props
 const url = Astro.url
+const robotsMeta = metadata.robotsMeta ?? "index,follow"
+
+const organizationSchema = {
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  name: "shipbase",
+  url: siteConfig.url,
+  logo: `${siteConfig.url}/logo.png`,
+  sameAs: [
+    siteConfig.links.twitter,
+    siteConfig.links.github,
+  ],
+}
 ---
 
 <!doctype html>
@@ -52,7 +68,7 @@ const url = Astro.url
     <meta name="author" content={siteConfig.author} />
     <meta name="creator" content={siteConfig.creator} />
     <meta name="theme-color" content={META_THEME_COLORS.light} />
-    <meta name="robots" content="index,follow" />
+    <meta name="robots" content={robotsMeta} />
 
     <meta property="og:locale" content="en_US" />
     <meta property="og:url" content={url.toString()} />
@@ -79,6 +95,9 @@ const url = Astro.url
 
     <link rel="sitemap" href="/sitemap-index.xml" />
 
+    <StructuredData data={organizationSchema} />
+    {structuredData && <StructuredData data={structuredData} />}
+
     <ClientRouter />
 
     <script is:inline>
diff --git a/apps/www/src/pages/404.astro b/apps/www/src/pages/404.astro
index 34d3729d..090964f3 100644
--- a/apps/www/src/pages/404.astro
+++ b/apps/www/src/pages/404.astro
@@ -10,6 +10,7 @@ const imageUrl = new URL(siteConfig.ogImage, url.origin).toString()
   metadata={{
     title: "Page Not Found",
     description: siteConfig.description,
+    robotsMeta: "noindex,nofollow",
     openGraph: {
       type: "website",
       title: "Page Not Found",
diff --git a/apps/www/src/pages/docs/[...slug].astro b/apps/www/src/pages/docs/[...slug].astro
index c8b3f23a..1b25375a 100644
--- a/apps/www/src/pages/docs/[...slug].astro
+++ b/apps/www/src/pages/docs/[...slug].astro
@@ -27,6 +27,30 @@ const imageURL = new URL(
 ---
 
 <RootLayout
+  structuredData={{
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: [
+      {
+        "@type": "ListItem",
+        position: 1,
+        name: "Home",
+        item: url.origin,
+      },
+      {
+        "@type": "ListItem",
+        position: 2,
+        name: "Docs",
+        item: `${url.origin}/docs`,
+      },
+      {
+        "@type": "ListItem",
+        position: 3,
+        name: entry.data.title,
+        item: url.toString(),
+      },
+    ],
+  }}
   metadata={{
     title: entry.data.title,
     description: entry.data.description,
diff --git a/apps/www/src/pages/docs/components/[component].astro b/apps/www/src/pages/docs/components/[component].astro
index 0303dbde..3b0a3835 100644
--- a/apps/www/src/pages/docs/components/[component].astro
+++ b/apps/www/src/pages/docs/components/[component].astro
@@ -34,11 +34,41 @@ const imageURL = new URL(
 ---
 
 <RootLayout
+  structuredData={{
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: [
+      {
+        "@type": "ListItem",
+        position: 1,
+        name: "Home",
+        item: url.origin,
+      },
+      {
+        "@type": "ListItem",
+        position: 2,
+        name: "Docs",
+        item: `${url.origin}/docs`,
+      },
+      {
+        "@type": "ListItem",
+        position: 3,
+        name: "Components",
+        item: `${url.origin}/docs/components`,
+      },
+      {
+        "@type": "ListItem",
+        position: 4,
+        name: entry.data.title,
+        item: url.toString(),
+      },
+    ],
+  }}
   metadata={{
     title: entry.data.title,
     description: entry.data.description,
     openGraph: {
-      type: "website",
+      type: "article",
       title: entry.data.title,
       description: entry.data.description,
       image: { url: imageURL },