From f9fe74ef94831c32a17bea9ddc09e626880647dd Mon Sep 17 00:00:00 2001
From: Raj Nandan Sharma <rajnandan1@gmail.com>
Date: Sat, 14 Mar 2026 10:08:14 +0530
Subject: [PATCH] refactor: streamline documentation layout and enhance styling

---
 .claude/settings.json               |   5 +
 src/routes/(docs)/docs/+page.svelte | 692 +++++++++++++++++++---------
 src/routes/docs.css                 |   2 +
 3 files changed, 483 insertions(+), 216 deletions(-)
 create mode 100644 .claude/settings.json

diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000..90308884
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "frontend-design@claude-plugins-official": true
+  }
+}
diff --git a/src/routes/(docs)/docs/+page.svelte b/src/routes/(docs)/docs/+page.svelte
index a08036fb..fe1c8934 100644
--- a/src/routes/(docs)/docs/+page.svelte
+++ b/src/routes/(docs)/docs/+page.svelte
@@ -1,8 +1,5 @@
 <script lang="ts">
   import { Badge } from "$lib/components/ui/badge/index.js";
-  import { Button } from "$lib/components/ui/button/index.js";
-  import * as Card from "$lib/components/ui/card/index.js";
-  import { Separator } from "$lib/components/ui/separator/index.js";
   import type { DocsConfig, DocsPage } from "$lib/types/docs";
   import { base } from "$app/paths";
   import ArrowRight from "@lucide/svelte/icons/arrow-right";
@@ -197,10 +194,6 @@
     }));
   }
 
-  function getMetrics(): Array<{ label: string; value: string }> {
-    return [];
-  }
-
   function getCtaButtons(): CtaButton[] {
     const quickStartSlug = getQuickStartSlug();
 
@@ -247,263 +240,287 @@
   <link rel="icon" href={data.config.favicon} />
 </svelte:head>
 
-<div class="bg-background text-foreground min-h-screen">
-  <header class="bg-background/95 border-border fixed top-0 z-50 w-full border-b backdrop-blur">
-    <div class="mx-auto flex max-w-[1200px] items-center justify-between p-4 px-6">
-      <a href={getHref("/docs")} class="text-foreground no-underline">
-        <span class="inline-flex items-center gap-2 text-base font-medium">
-          <img src="/logo96.png" alt="Logo" class="h-6 w-6 rounded-sm" />
-          {data.config.name}
+<div class="docs-landing bg-background text-foreground min-h-screen">
+  <!-- Navbar -->
+  <header class="nav-bar border-border/50 fixed top-0 z-50 w-full border-b backdrop-blur-xl">
+    <div class="mx-auto flex max-w-[1200px] items-center justify-between px-6 py-3">
+      <a href={getHref("/docs")} class="text-foreground group no-underline">
+        <span class="inline-flex items-center gap-2.5 text-base font-medium tracking-tight">
+          <img src="/logo96.png" alt="Logo" class="h-7 w-7 rounded-md transition-transform duration-300 group-hover:scale-110" />
+          <span class="font-display text-lg font-semibold">{data.config.name}</span>
         </span>
       </a>
-      <div class="flex items-center gap-3 sm:gap-6">
+      <div class="flex items-center gap-2 sm:gap-4">
         {#if data.config.footerLinks}
           {#each data.config.footerLinks.slice(0, 3) as link (link.url)}
-            <Button
-              variant="ghost"
-              size="sm"
+            <a
               href={link.url}
               target="_blank"
               rel="noopener noreferrer"
-              class="text-muted-foreground hover:text-foreground hidden sm:inline-flex"
+              class="text-muted-foreground hover:text-foreground hidden text-sm font-medium tracking-tight transition-colors duration-200 sm:inline-flex"
             >
               {link.name}
-            </Button>
+            </a>
           {/each}
         {/if}
-        <Button variant="ghost" size="icon" onclick={toggleMode} aria-label="Toggle theme">
+        <button
+          onclick={toggleMode}
+          aria-label="Toggle theme"
+          class="text-muted-foreground hover:text-foreground hover:bg-muted/50 inline-flex h-9 w-9 items-center justify-center rounded-lg transition-all duration-200"
+        >
           {#if mode.current === "dark"}
-            <Sun class="h-5 w-5" />
+            <Sun class="h-[18px] w-[18px]" />
           {:else}
-            <Moon class="h-5 w-5" />
+            <Moon class="h-[18px] w-[18px]" />
           {/if}
-        </Button>
+        </button>
       </div>
     </div>
   </header>
 
-  <section class="bg-background min-h-screen bg-(image:--docs-home-hero-gradient) px-6 py-20 md:py-24">
-    <div class="mx-auto mt-20 grid max-w-[1200px] items-center gap-10">
-      <div class="text-center">
-        <Badge variant="outline" class="mb-6 inline-flex items-center gap-2 px-3 py-1 text-xs">
-          <Shield class="h-3.5 w-3.5" />
-          Production-ready status page platform
-        </Badge>
-        <h1 class="text-foreground mb-6 text-2xl leading-tight font-bold tracking-tight md:text-4xl">
-          Build stunning status pages with
-          <span class="from-primary to-accent-foreground bg-linear-to-r bg-clip-text text-transparent"> Kener </span>
+  <!-- Hero -->
+  <section class="hero-section relative overflow-hidden px-6 pt-32 pb-20 md:pt-40 md:pb-28">
+    <!-- Animated gradient orbs -->
+    <div class="hero-orb hero-orb-1"></div>
+    <div class="hero-orb hero-orb-2"></div>
+    <div class="hero-orb hero-orb-3"></div>
+    <!-- Grain overlay -->
+    <div class="grain-overlay"></div>
+
+    <div class="relative z-10 mx-auto max-w-[1200px]">
+      <div class="mx-auto max-w-[820px] text-center">
+        <div class="fade-up mb-8 inline-flex items-center gap-2">
+          <Badge variant="outline" class="hero-badge border-foreground/10 bg-background/60 gap-2 rounded-full px-4 py-1.5 text-xs font-medium tracking-wide backdrop-blur-sm">
+            <span class="bg-primary inline-block h-1.5 w-1.5 animate-pulse rounded-full"></span>
+            Production-ready status page platform
+          </Badge>
+        </div>
+
+        <h1 class="fade-up font-display text-foreground mb-6 text-4xl leading-[1.1] font-bold tracking-tight md:text-6xl lg:text-7xl" style="animation-delay: 80ms">
+          Build stunning<br />
+          status pages with
+          <span class="hero-gradient-text">Kener</span>
         </h1>
-        <p class="text-muted-foreground mx-auto mb-8 max-w-[760px] text-sm leading-relaxed md:text-base">
-          From quick setup to advanced operations, Kener gives you open-source monitoring, incident workflows,
-          notifications, maintenance scheduling, embeds, and automation APIs—all in one modern platform.
+
+        <p class="fade-up font-body text-muted-foreground mx-auto mb-10 max-w-[640px] text-base leading-relaxed font-light md:text-lg" style="animation-delay: 160ms">
+          Open-source monitoring, incident workflows, notifications, maintenance scheduling, embeds, and automation APIs — all in one modern platform.
         </p>
 
-        <div class="mb-8 flex flex-wrap items-center justify-center gap-3 md:gap-4 lg:justify-center">
+        <div class="fade-up mb-6 flex flex-wrap items-center justify-center gap-3" style="animation-delay: 240ms">
           {#each getCtaButtons() as button (button.title)}
-            <Button
-              href={getHref(button.href)}
-              variant={button.primary ? "default" : "outline"}
-              rel="external"
-              size="lg"
-            >
-              {button.title}
-              {#if button.primary}
+            {#if button.primary}
+              <a
+                href={getHref(button.href)}
+                class="cta-primary inline-flex items-center gap-2 rounded-lg px-6 py-3 text-sm font-semibold tracking-tight transition-all duration-300"
+              >
+                {button.title}
                 <ArrowRight class="h-4 w-4" />
-              {/if}
-            </Button>
+              </a>
+            {:else}
+              <a
+                href={getHref(button.href)}
+                class="border-border/60 text-foreground hover:bg-muted/40 inline-flex items-center gap-2 rounded-lg border bg-transparent px-6 py-3 text-sm font-medium tracking-tight backdrop-blur-sm transition-all duration-300"
+              >
+                {button.title}
+              </a>
+            {/if}
           {/each}
+        </div>
+
+        <div class="fade-up flex flex-wrap items-center justify-center gap-3" style="animation-delay: 300ms">
           <a
             href="https://railway.com/deploy/spSvic?referralCode=1Pn7vs&utm_medium=integration&utm_source=template&utm_campaign=generic"
             target="_blank"
             rel="noopener noreferrer"
+            class="opacity-70 transition-opacity duration-200 hover:opacity-100"
           >
-            <img src="https://railway.com/button.svg" alt="Deploy on Railway" class="h-10" />
+            <img src="https://railway.com/button.svg" alt="Deploy on Railway" class="h-9" />
           </a>
           <a
             href="https://zeabur.com/templates/1YRTMI?referralCode=rajnandan1"
             target="_blank"
             rel="noopener noreferrer"
+            class="opacity-70 transition-opacity duration-200 hover:opacity-100"
           >
-            <img src="https://zeabur.com/button.svg" alt="Deploy on Zeabur" class="h-10" />
+            <img src="https://zeabur.com/button.svg" alt="Deploy on Zeabur" class="h-9" />
           </a>
         </div>
+      </div>
 
-        {#if getMetrics().length > 0}
-          <div class="grid max-w-[920px] grid-cols-2 gap-3 sm:grid-cols-4">
-            {#each getMetrics() as metric (metric.label)}
-              <Card.Root class="bg-card/70 backdrop-blur">
-                <Card.Content class="px-4 py-3">
-                  <p class="text-foreground text-lg font-bold md:text-xl">{metric.value}</p>
-                  <p class="text-muted-foreground text-xs tracking-wide uppercase">{metric.label}</p>
-                </Card.Content>
-              </Card.Root>
-            {/each}
+      <!-- Hero image -->
+      <div class="fade-up mx-auto mt-16 max-w-[960px]" style="animation-delay: 380ms">
+        <div class="hero-image-wrapper group relative">
+          <div class="hero-image-glow"></div>
+          <div class="relative overflow-hidden rounded-xl border border-white/10 shadow-2xl">
+            <img
+              src="/og.jpg"
+              alt="Kener documentation preview"
+              class="bg-muted h-auto w-full object-cover transition-transform duration-700 group-hover:scale-[1.02]"
+              loading="eager"
+            />
           </div>
-        {/if}
-      </div>
-
-      <div class="overflow-hidden rounded-md border-2 shadow-xl">
-        <img
-          src="/og.jpg"
-          alt="Kener documentation preview"
-          class="bg-muted h-auto w-full rounded-md object-cover"
-          loading="eager"
-        />
+        </div>
       </div>
     </div>
   </section>
 
-  <div class="mx-auto max-w-[1200px] px-6">
-    <Separator />
-  </div>
-
-  <section class="bg-background px-6 py-20 md:py-24">
-    <div class="mx-auto mb-10 max-w-[1200px] text-center">
-      <h2 class="text-foreground mb-3 text-3xl font-bold tracking-tight md:text-4xl">
-        Everything from Introduction—and more
-      </h2>
-      <p class="text-muted-foreground mx-auto max-w-[760px] text-sm leading-relaxed md:text-base">
-        This docs homepage brings together Kener's full capabilities from the introduction page plus advanced admin
-        workflows you may have missed.
-      </p>
-    </div>
-
-    <div class="mx-auto grid max-w-[1200px] grid-cols-1 gap-5 sm:grid-cols-2 xl:grid-cols-3">
-      {#each coreFeatures as feature (feature.title)}
-        <Card.Root
-          class="hover:border-accent-foreground transition-all duration-300 hover:-translate-y-1 hover:shadow-lg"
-        >
-          <Card.Header>
-            <div class="mb-2 flex items-start justify-between gap-4">
-              <div
-                class="bg-accent text-accent-foreground inline-flex h-11 w-11 items-center justify-center rounded-md"
-              >
-                <feature.icon class="h-5 w-5" />
-              </div>
-              {#if feature.href}
-                <Button href={getHref(feature.href)} variant="ghost" size="sm" class="text-xs">Learn more →</Button>
-              {/if}
-            </div>
-            <Card.Title class="text-lg">{feature.title}</Card.Title>
-          </Card.Header>
-          <Card.Content>
-            <p class="text-muted-foreground text-sm leading-relaxed">{feature.description}</p>
-          </Card.Content>
-        </Card.Root>
-      {/each}
-    </div>
-  </section>
-
-  <div class="mx-auto max-w-[1200px] px-6">
-    <Separator />
-  </div>
-
-  <section class="bg-muted/30 px-6 py-20 md:py-24">
-    <div class="mx-auto mb-10 max-w-[1200px]">
-      <h2 class="text-foreground text-center text-3xl font-bold tracking-tight md:text-4xl">
-        Advanced power tools for ops teams
-      </h2>
-      <p class="text-muted-foreground mx-auto mt-3 max-w-[760px] text-center text-sm leading-relaxed md:text-base">
-        Beyond public status pages, Kener includes deep operational tooling surfaced in the admin app.
-      </p>
-    </div>
-
-    <div class="mx-auto grid max-w-[1200px] grid-cols-1 gap-5 md:grid-cols-2 xl:grid-cols-3">
-      {#each advancedFeatures as feature (feature.title)}
-        <Card.Root class="bg-background shadow-sm transition-all duration-300 hover:shadow-md">
-          <Card.Header>
-            <div class="mb-2 flex items-center justify-between gap-3">
-              <div
-                class="bg-accent text-accent-foreground inline-flex h-10 w-10 items-center justify-center rounded-md"
-              >
-                <feature.icon class="h-5 w-5" />
-              </div>
-              {#if feature.tag}
-                <Badge variant="secondary" class="text-[11px] tracking-wide uppercase">{feature.tag}</Badge>
-              {/if}
-            </div>
-            <Card.Title class="text-lg">{feature.title}</Card.Title>
-          </Card.Header>
-          <Card.Content>
-            <p class="text-muted-foreground text-sm leading-relaxed">{feature.description}</p>
-          </Card.Content>
-        </Card.Root>
-      {/each}
-    </div>
-  </section>
-
-  <div class="mx-auto max-w-[1200px] px-6">
-    <Separator />
-  </div>
-
-  <section class="bg-background px-6 py-20 md:py-24">
-    <div class="mx-auto mb-10 max-w-[1200px]">
-      <h2 class="text-foreground text-center text-3xl font-bold tracking-tight md:text-4xl">Explore by topic</h2>
-      <p class="text-muted-foreground mx-auto mt-3 max-w-[680px] text-center text-sm leading-relaxed md:text-base">
-        Jump to major sections and quickly find the pages your team needs most.
-      </p>
-    </div>
-
-    <div class="mx-auto grid max-w-[1200px] grid-cols-1 gap-5 md:grid-cols-2 lg:grid-cols-3">
-      {#each getGroupHighlights() as group (group.group)}
-        <Card.Root>
-          <Card.Header>
-            <Card.Title class="text-lg">{group.group}</Card.Title>
-          </Card.Header>
-          <Card.Content class="space-y-2">
-            {#each group.pages as page (page.slug)}
-              <Button
-                href={getHref(`/docs/${page.slug}`)}
-                variant="ghost"
-                class="text-muted-foreground hover:text-foreground flex w-full items-center justify-between"
-              >
-                <span>{page.title}</span>
-                <ArrowRight class="h-3.5 w-3.5" />
-              </Button>
-            {/each}
-          </Card.Content>
-        </Card.Root>
-      {/each}
-    </div>
-  </section>
-
-  <section class="bg-background px-6 pb-6">
+  <!-- Core Features -->
+  <section class="relative px-6 py-24 md:py-32">
     <div class="mx-auto max-w-[1200px]">
-      <Card.Root>
-        <Card.Content
-          class="flex flex-col items-center justify-between gap-4 px-6 py-6 text-center md:flex-row md:text-left"
-        >
+      <div class="mx-auto mb-16 max-w-[640px] text-center">
+        <p class="font-body text-primary mb-3 text-sm font-semibold tracking-widest uppercase">Capabilities</p>
+        <h2 class="font-display text-foreground mb-4 text-3xl font-bold tracking-tight md:text-5xl">
+          Everything you need
+        </h2>
+        <p class="font-body text-muted-foreground text-base leading-relaxed font-light md:text-lg">
+          From quick setup to advanced operations — monitoring, incidents, notifications, and more.
+        </p>
+      </div>
+
+      <div class="grid grid-cols-1 gap-4 sm:grid-cols-2 xl:grid-cols-3">
+        {#each coreFeatures as feature, i (feature.title)}
+          <div
+            class="feature-card group relative overflow-hidden rounded-xl border border-transparent p-6 transition-all duration-500"
+            style="animation-delay: {i * 50}ms"
+          >
+            <div class="feature-card-bg"></div>
+            <div class="relative z-10">
+              <div class="mb-4 flex items-start justify-between gap-4">
+                <div class="feature-icon-wrapper inline-flex h-11 w-11 items-center justify-center rounded-lg transition-all duration-300">
+                  <feature.icon class="h-5 w-5" />
+                </div>
+                {#if feature.href}
+                  <a
+                    href={getHref(feature.href)}
+                    class="text-muted-foreground hover:text-foreground inline-flex items-center gap-1 text-xs font-medium tracking-tight opacity-0 transition-all duration-300 group-hover:opacity-100"
+                  >
+                    Learn more
+                    <ArrowRight class="h-3 w-3" />
+                  </a>
+                {/if}
+              </div>
+              <h3 class="font-display text-foreground mb-2 text-lg font-semibold tracking-tight">{feature.title}</h3>
+              <p class="font-body text-muted-foreground text-sm leading-relaxed font-light">{feature.description}</p>
+            </div>
+          </div>
+        {/each}
+      </div>
+    </div>
+  </section>
+
+  <!-- Advanced Features -->
+  <section class="relative overflow-hidden px-6 py-24 md:py-32">
+    <div class="section-accent-bg"></div>
+    <div class="relative z-10 mx-auto max-w-[1200px]">
+      <div class="mx-auto mb-16 max-w-[640px] text-center">
+        <p class="font-body text-primary mb-3 text-sm font-semibold tracking-widest uppercase">For Ops Teams</p>
+        <h2 class="font-display text-foreground mb-4 text-3xl font-bold tracking-tight md:text-5xl">
+          Advanced power tools
+        </h2>
+        <p class="font-body text-muted-foreground text-base leading-relaxed font-light md:text-lg">
+          Deep operational tooling surfaced in the admin dashboard.
+        </p>
+      </div>
+
+      <div class="grid grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-3">
+        {#each advancedFeatures as feature, i (feature.title)}
+          <div class="advanced-card group relative overflow-hidden rounded-xl p-6 transition-all duration-500" style="animation-delay: {i * 60}ms">
+            <div class="advanced-card-border"></div>
+            <div class="relative z-10">
+              <div class="mb-4 flex items-center justify-between gap-3">
+                <div class="bg-primary/10 text-primary inline-flex h-10 w-10 items-center justify-center rounded-lg">
+                  <feature.icon class="h-5 w-5" />
+                </div>
+                {#if feature.tag}
+                  <span class="text-muted-foreground bg-muted/60 rounded-md px-2.5 py-1 text-[10px] font-semibold tracking-widest uppercase">{feature.tag}</span>
+                {/if}
+              </div>
+              <h3 class="font-display text-foreground mb-2 text-lg font-semibold tracking-tight">{feature.title}</h3>
+              <p class="font-body text-muted-foreground text-sm leading-relaxed font-light">{feature.description}</p>
+            </div>
+          </div>
+        {/each}
+      </div>
+    </div>
+  </section>
+
+  <!-- Explore by Topic -->
+  <section class="px-6 py-24 md:py-32">
+    <div class="mx-auto max-w-[1200px]">
+      <div class="mx-auto mb-16 max-w-[640px] text-center">
+        <p class="font-body text-primary mb-3 text-sm font-semibold tracking-widest uppercase">Documentation</p>
+        <h2 class="font-display text-foreground mb-4 text-3xl font-bold tracking-tight md:text-5xl">Explore by topic</h2>
+        <p class="font-body text-muted-foreground text-base leading-relaxed font-light md:text-lg">
+          Jump to the sections your team needs most.
+        </p>
+      </div>
+
+      <div class="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+        {#each getGroupHighlights() as group (group.group)}
+          <div class="topic-card group rounded-xl border border-transparent p-6 transition-all duration-400">
+            <h3 class="font-display text-foreground mb-4 text-lg font-semibold tracking-tight">{group.group}</h3>
+            <div class="space-y-1">
+              {#each group.pages as page (page.slug)}
+                <a
+                  href={getHref(`/docs/${page.slug}`)}
+                  class="text-muted-foreground hover:text-foreground hover:bg-muted/40 flex items-center justify-between rounded-lg px-3 py-2.5 text-sm font-medium tracking-tight transition-all duration-200"
+                >
+                  <span>{page.title}</span>
+                  <ArrowRight class="h-3.5 w-3.5 opacity-0 transition-all duration-200 group-hover:opacity-60" />
+                </a>
+              {/each}
+            </div>
+          </div>
+        {/each}
+      </div>
+    </div>
+  </section>
+
+  <!-- CTA Banner -->
+  <section class="px-6 pb-12">
+    <div class="mx-auto max-w-[1200px]">
+      <div class="cta-banner relative overflow-hidden rounded-2xl p-8 md:p-12">
+        <div class="cta-banner-bg"></div>
+        <div class="relative z-10 flex flex-col items-center justify-between gap-6 md:flex-row">
           <div>
-            <h3 class="text-foreground text-lg font-semibold">Need help or want to contribute?</h3>
-            <p class="text-muted-foreground text-sm">
+            <h3 class="font-display text-foreground mb-2 text-xl font-bold tracking-tight md:text-2xl">
+              Need help or want to contribute?
+            </h3>
+            <p class="font-body text-muted-foreground text-sm font-light">
               Join the community, browse examples, and help shape Kener's future.
             </p>
           </div>
-          <Button href="https://github.com/rajnandan1/kener" target="_blank" rel="noopener noreferrer">
+          <a
+            href="https://github.com/rajnandan1/kener"
+            target="_blank"
+            rel="noopener noreferrer"
+            class="cta-github inline-flex shrink-0 items-center gap-2.5 rounded-lg px-6 py-3 text-sm font-semibold tracking-tight transition-all duration-300"
+          >
             <Github class="h-4 w-4" />
             Star on GitHub
-          </Button>
-        </Card.Content>
-      </Card.Root>
+          </a>
+        </div>
+      </div>
     </div>
   </section>
 
-  <footer class="bg-background border-border border-t px-6 py-8">
+  <!-- Footer -->
+  <footer class="border-border/40 border-t px-6 py-8">
     <div class="mx-auto flex max-w-[1200px] flex-col items-center justify-between gap-4 md:flex-row">
-      <p class="text-muted-foreground text-sm">Built with ❤️ by the Kener team</p>
+      <p class="font-body text-muted-foreground text-sm font-light">
+        Built with care by the Kener team
+      </p>
       {#if data.config.footerLinks}
-        <div class="flex flex-wrap items-center justify-center gap-4 md:gap-6">
+        <div class="flex flex-wrap items-center justify-center gap-5">
           {#each data.config.footerLinks as link (link.url)}
-            <Button
-              variant="link"
-              size="sm"
+            <a
               href={link.url}
               target="_blank"
               rel="noopener noreferrer"
-              class="text-muted-foreground hover:text-foreground h-auto p-0"
+              class="text-muted-foreground hover:text-foreground text-sm font-medium tracking-tight transition-colors duration-200"
             >
               {link.name}
-            </Button>
+            </a>
           {/each}
         </div>
       {/if}
@@ -512,21 +529,264 @@
 </div>
 
 <style>
-  :global(:root) {
-    --docs-home-hero-gradient: radial-gradient(
-      circle at 80% 20%,
-      rgba(255, 180, 77, 0.5) 0%,
-      rgba(255, 143, 61, 0.2) 30%,
-      transparent 60%
-    );
+  /* ===== Typography ===== */
+  .docs-landing :global(.font-display) {
+    font-family: "Instrument Serif", Georgia, "Times New Roman", serif;
+  }
+  .docs-landing :global(.font-body) {
+    font-family: "Source Sans 3", system-ui, -apple-system, sans-serif;
   }
 
-  :global(.dark) {
-    --docs-home-hero-gradient: radial-gradient(
-      circle at 80% 20%,
-      rgba(72, 54, 24, 0.3) 0%,
-      rgba(72, 54, 24, 0.1) 30%,
-      transparent 70%
+  /* ===== Entrance Animations ===== */
+  @keyframes fadeUp {
+    from {
+      opacity: 0;
+      transform: translateY(24px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  .fade-up {
+    opacity: 0;
+    animation: fadeUp 0.8s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+  }
+
+  /* ===== Navbar ===== */
+  .nav-bar {
+    background: color-mix(in oklch, var(--background) 80%, transparent);
+  }
+
+  /* ===== Hero Section ===== */
+  .hero-section {
+    position: relative;
+    background: var(--background);
+  }
+
+  /* Gradient orbs */
+  .hero-orb {
+    position: absolute;
+    border-radius: 50%;
+    filter: blur(80px);
+    opacity: 0.5;
+    animation: orbFloat 12s ease-in-out infinite;
+  }
+
+  .hero-orb-1 {
+    width: 500px;
+    height: 500px;
+    top: -10%;
+    right: -5%;
+    background: color-mix(in oklch, var(--primary) 25%, transparent);
+    animation-delay: 0s;
+  }
+
+  .hero-orb-2 {
+    width: 350px;
+    height: 350px;
+    top: 40%;
+    left: -8%;
+    background: color-mix(in oklch, var(--primary) 15%, transparent);
+    animation-delay: -4s;
+  }
+
+  .hero-orb-3 {
+    width: 250px;
+    height: 250px;
+    bottom: 10%;
+    right: 20%;
+    background: color-mix(in oklch, var(--primary) 12%, transparent);
+    animation-delay: -8s;
+  }
+
+  @keyframes orbFloat {
+    0%,
+    100% {
+      transform: translate(0, 0) scale(1);
+    }
+    33% {
+      transform: translate(20px, -30px) scale(1.05);
+    }
+    66% {
+      transform: translate(-15px, 15px) scale(0.95);
+    }
+  }
+
+  /* Grain texture */
+  .grain-overlay {
+    position: absolute;
+    inset: 0;
+    opacity: 0.03;
+    pointer-events: none;
+    z-index: 1;
+    background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E");
+    background-repeat: repeat;
+    background-size: 200px 200px;
+  }
+
+  :global(.dark) .grain-overlay {
+    opacity: 0.04;
+  }
+
+  /* Hero gradient text */
+  .hero-gradient-text {
+    background: linear-gradient(135deg, var(--primary) 0%, color-mix(in oklch, var(--primary) 60%, transparent) 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+  }
+
+  /* Hero badge */
+  :global(.hero-badge) {
+    transition: all 0.3s ease;
+  }
+  :global(.hero-badge:hover) {
+    border-color: color-mix(in oklch, var(--primary) 30%, transparent);
+  }
+
+  /* CTA primary button */
+  .cta-primary {
+    background: var(--primary);
+    color: var(--primary-foreground);
+    box-shadow:
+      0 1px 2px color-mix(in oklch, var(--primary) 30%, transparent),
+      0 4px 16px color-mix(in oklch, var(--primary) 15%, transparent);
+  }
+  .cta-primary:hover {
+    box-shadow:
+      0 1px 2px color-mix(in oklch, var(--primary) 40%, transparent),
+      0 8px 24px color-mix(in oklch, var(--primary) 25%, transparent);
+    transform: translateY(-1px);
+  }
+
+  /* Hero image */
+  .hero-image-wrapper {
+    position: relative;
+  }
+
+  .hero-image-glow {
+    position: absolute;
+    inset: -1px;
+    border-radius: 0.85rem;
+    background: linear-gradient(
+      135deg,
+      color-mix(in oklch, var(--primary) 30%, transparent),
+      color-mix(in oklch, var(--primary) 5%, transparent),
+      color-mix(in oklch, var(--primary) 20%, transparent)
     );
+    z-index: -1;
+    opacity: 0.6;
+    transition: opacity 0.5s ease;
+  }
+
+  .hero-image-wrapper:hover .hero-image-glow {
+    opacity: 1;
+  }
+
+  /* ===== Feature Cards ===== */
+  .feature-card {
+    cursor: default;
+  }
+
+  .feature-card-bg {
+    position: absolute;
+    inset: 0;
+    border-radius: 0.75rem;
+    background: var(--card);
+    border: 1px solid color-mix(in oklch, var(--border) 50%, transparent);
+    transition: all 0.5s cubic-bezier(0.16, 1, 0.3, 1);
+  }
+
+  .feature-card:hover .feature-card-bg {
+    border-color: color-mix(in oklch, var(--primary) 30%, transparent);
+    box-shadow: 0 8px 32px color-mix(in oklch, var(--primary) 6%, transparent);
+  }
+
+  .feature-icon-wrapper {
+    background: color-mix(in oklch, var(--primary) 8%, transparent);
+    color: var(--primary);
+  }
+
+  .feature-card:hover .feature-icon-wrapper {
+    background: color-mix(in oklch, var(--primary) 14%, transparent);
+    transform: scale(1.05);
+  }
+
+  /* ===== Advanced Section ===== */
+  .section-accent-bg {
+    position: absolute;
+    inset: 0;
+    background: color-mix(in oklch, var(--muted) 30%, transparent);
+  }
+
+  .advanced-card {
+    position: relative;
+    background: var(--background);
+    cursor: default;
+  }
+
+  .advanced-card-border {
+    position: absolute;
+    inset: 0;
+    border-radius: 0.75rem;
+    border: 1px solid color-mix(in oklch, var(--border) 40%, transparent);
+    transition: all 0.4s ease;
+    pointer-events: none;
+  }
+
+  .advanced-card:hover .advanced-card-border {
+    border-color: color-mix(in oklch, var(--primary) 25%, transparent);
+  }
+
+  /* ===== Topic Cards ===== */
+  .topic-card {
+    background: color-mix(in oklch, var(--card) 50%, transparent);
+    border: 1px solid color-mix(in oklch, var(--border) 40%, transparent);
+  }
+
+  .topic-card:hover {
+    background: var(--card);
+    border-color: color-mix(in oklch, var(--border) 70%, transparent);
+  }
+
+  /* ===== CTA Banner ===== */
+  .cta-banner {
+    border: 1px solid color-mix(in oklch, var(--border) 50%, transparent);
+  }
+
+  .cta-banner-bg {
+    position: absolute;
+    inset: 0;
+    background:
+      radial-gradient(ellipse at 20% 50%, color-mix(in oklch, var(--primary) 6%, transparent) 0%, transparent 60%),
+      radial-gradient(ellipse at 80% 50%, color-mix(in oklch, var(--primary) 4%, transparent) 0%, transparent 60%),
+      var(--card);
+    border-radius: inherit;
+  }
+
+  .cta-github {
+    background: var(--foreground);
+    color: var(--background);
+  }
+
+  .cta-github:hover {
+    opacity: 0.9;
+    transform: translateY(-1px);
+    box-shadow: 0 4px 16px color-mix(in oklch, var(--foreground) 20%, transparent);
+  }
+
+  /* ===== Dark mode adjustments ===== */
+  :global(.dark) .hero-orb {
+    opacity: 0.25;
+  }
+
+  :global(.dark) .hero-image-glow {
+    opacity: 0.4;
+  }
+
+  :global(.dark) .feature-card:hover .feature-card-bg {
+    box-shadow: 0 8px 32px color-mix(in oklch, var(--primary) 4%, transparent);
   }
 </style>
diff --git a/src/routes/docs.css b/src/routes/docs.css
index ecf69fca..a8c9d1cd 100644
--- a/src/routes/docs.css
+++ b/src/routes/docs.css
@@ -1,3 +1,5 @@
+@import url("https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&display=swap");
+
 /* Prose/Content Body Styles - needed for markdown rendering */
 .docs-content-body {
   font-size: 1rem;