@farming-labs/astro-theme 0.0.2-beta.15 → 0.0.2-beta.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/astro-theme",
-  "version": "0.0.2-beta.15",
+  "version": "0.0.2-beta.17",
   "description": "Astro UI components for @farming-labs/docs — layout, sidebar, TOC, search, and theme toggle",
   "type": "module",
   "exports": {
@@ -25,12 +25,19 @@
       "import": "./src/themes/darksharp.js",
       "default": "./src/themes/darksharp.js"
     },
+    "./colorful": {
+      "types": "./src/themes/colorful.d.ts",
+      "import": "./src/themes/colorful.js",
+      "default": "./src/themes/colorful.js"
+    },
     "./css": "./styles/docs.css",
     "./fumadocs/css": "./styles/docs.css",
     "./styles/pixel-border.css": "./styles/pixel-border.css",
     "./styles/darksharp.css": "./styles/darksharp.css",
     "./pixel-border/css": "./styles/pixel-border-bundle.css",
-    "./darksharp/css": "./styles/darksharp-bundle.css"
+    "./darksharp/css": "./styles/darksharp-bundle.css",
+    "./styles/colorful.css": "./styles/colorful.css",
+    "./colorful/css": "./styles/colorful-bundle.css"
   },
   "typesVersions": {
     "*": {
@@ -62,8 +69,8 @@
   "license": "MIT",
   "dependencies": {
     "sugar-high": "^0.9.5",
-    "@farming-labs/astro": "0.0.2-beta.15",
-    "@farming-labs/docs": "0.0.2-beta.15"
+    "@farming-labs/docs": "0.0.2-beta.17",
+    "@farming-labs/astro": "0.0.2-beta.17"
   },
   "peerDependencies": {
     "astro": ">=4.0.0"

package/src/components/DocsContent.astro

@@ -8,6 +8,7 @@ const titleSuffix = config?.metadata?.titleTemplate
   : " – Docs";
 
 const tocEnabled = config?.theme?.ui?.layout?.toc?.enabled ?? true;
+const tocStyle = config?.theme?.ui?.layout?.toc?.style ?? "default";
 
 const breadcrumbEnabled = (() => {
   const bc = config?.breadcrumb;
@@ -29,11 +30,13 @@ const showLastModified = !!data.lastModified;
 <DocsPage
   entry={config?.entry ?? "docs"}
   tocEnabled={tocEnabled}
+  tocStyle={tocStyle}
   breadcrumbEnabled={breadcrumbEnabled}
   previousPage={data.previousPage}
   nextPage={data.nextPage}
   editOnGithub={showEditOnGithub ? data.editOnGithub : null}
   lastModified={showLastModified ? data.lastModified : null}
 >
+  {data.description && <p class="fd-page-description">{data.description}</p>}
   <Fragment set:html={data.html} />
 </DocsPage>

package/src/components/DocsLayout.astro

@@ -1,5 +1,6 @@
 ---
 import ThemeToggle from "./ThemeToggle.astro";
+import FloatingAIChat from "./FloatingAIChat.astro";
 
 const { tree, config = null, title, titleUrl } = Astro.props;
 
@@ -60,7 +61,7 @@ function buildColorsCSS(colors?: Record<string, string | undefined>): string {
     vars.push(`${COLOR_MAP[key]}: ${value};`);
   }
   if (vars.length === 0) return "";
-  return `:root, .dark {\n  ${vars.join("\n  ")}\n}`;
+  return `.dark {\n  ${vars.join("\n  ")}\n}`;
 }
 
 function buildFontStyleVars(prefix: string, style?: { size?: string; weight?: string | number; lineHeight?: string; letterSpacing?: string }): string {
@@ -270,6 +271,20 @@ const showFloatingAI = aiConfig?.mode === "floating" && aiConfig?.enabled;
   </main>
 </div>
 
+{showFloatingAI && (
+  <FloatingAIChat
+    api="/api/docs"
+    suggestedQuestions={aiConfig?.suggestedQuestions ?? []}
+    aiLabel={aiConfig?.aiLabel ?? "AI"}
+    position={aiConfig?.position ?? "bottom-right"}
+    floatingStyle={aiConfig?.floatingStyle ?? "panel"}
+  >
+    {Astro.slots.has("ai-trigger") && (
+      <slot name="ai-trigger" slot="trigger" />
+    )}
+  </FloatingAIChat>
+)}
+
 <script>
   // Sidebar toggle
   const menuBtn = document.getElementById('fd-menu-toggle');

package/src/components/DocsPage.astro

@@ -1,6 +1,7 @@
 ---
 const {
   tocEnabled = true,
+  tocStyle = "default",
   breadcrumbEnabled = true,
   entry = "docs",
   previousPage = null,
@@ -10,16 +11,12 @@ const {
 } = Astro.props;
 
 const pathname = Astro.url.pathname;
-const segments = pathname.split("/").filter(Boolean).filter(s => s.toLowerCase() !== entry.toLowerCase());
+const segments = pathname.split("/").filter(Boolean);
 const parentLabel = segments.length >= 2 ? segments[segments.length - 2].replace(/-/g, " ").replace(/\b\w/g, c => c.toUpperCase()) : "";
 const currentLabel = segments.length >= 2 ? segments[segments.length - 1].replace(/-/g, " ").replace(/\b\w/g, c => c.toUpperCase()) : "";
-const parentUrl = (() => {
-  if (segments.length < 2) return "";
-  const all = pathname.split("/").filter(Boolean);
-  const parentSegment = segments[segments.length - 2];
-  const parentIndex = all.indexOf(parentSegment);
-  return "/" + all.slice(0, parentIndex + 1).join("/");
-})();
+const parentUrl = segments.length >= 2
+  ? "/" + segments.slice(0, segments.length - 1).join("/")
+  : "";
 ---
 
 <div class="fd-page">
@@ -89,7 +86,7 @@ const parentUrl = (() => {
 
   {tocEnabled && (
     <aside class="fd-toc">
-      <div class="fd-toc-inner">
+      <div class={`fd-toc-inner ${tocStyle === "directional" ? "fd-toc-directional" : ""}`} data-toc-style={tocStyle}>
         <h3 class="fd-toc-title">
           <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
             <line x1="3" y1="6" x2="21" y2="6" />
@@ -98,42 +95,205 @@ const parentUrl = (() => {
           </svg>
           On this page
         </h3>
-        <ul class="fd-toc-list" id="fd-toc-list"></ul>
+        <ul class={`fd-toc-list ${tocStyle === "directional" ? "fd-toc-clerk" : ""}`} id="fd-toc-list" style={tocStyle === "directional" ? "position:relative" : ""}></ul>
       </div>
     </aside>
   )}
 </div>
 
 <script>
+  function getItemOffset(depth) {
+    if (depth <= 2) return 14;
+    if (depth === 3) return 26;
+    return 36;
+  }
+
+  function getLineOffset(depth) {
+    return depth >= 3 ? 10 : 0;
+  }
+
   function initDocsPage() {
-    // Scan headings for TOC
     const container = document.querySelector('.fd-page-body');
     const tocList = document.getElementById('fd-toc-list');
     if (container && tocList) {
       const headings = container.querySelectorAll('h2[id], h3[id], h4[id]');
       tocList.innerHTML = '';
+      const isClerk = tocList.closest('[data-toc-style]')?.getAttribute('data-toc-style') === 'directional';
+
+      const tocItems = [];
       headings.forEach(el => {
-        const depth = parseInt(el.tagName[1], 10);
+        tocItems.push({
+          id: el.id,
+          title: el.textContent?.replace(/^#\s*/, '') || '',
+          depth: parseInt(el.tagName[1], 10),
+        });
+      });
+
+      tocItems.forEach((item, index) => {
         const li = document.createElement('li');
         li.className = 'fd-toc-item';
         const a = document.createElement('a');
-        a.className = 'fd-toc-link';
-        a.href = `#${el.id}`;
-        a.textContent = el.textContent?.replace(/^#\s*/, '') || '';
-        a.style.paddingLeft = `${12 + (depth - 2) * 12}px`;
+        a.href = `#${item.id}`;
+
+        if (isClerk) {
+          a.className = 'fd-toc-link fd-toc-clerk-link';
+          a.style.position = 'relative';
+          a.style.paddingLeft = `${getItemOffset(item.depth)}px`;
+          a.style.paddingTop = '6px';
+          a.style.paddingBottom = '6px';
+          a.style.fontSize = item.depth <= 2 ? '14px' : '13px';
+          a.style.overflowWrap = 'anywhere';
+
+          const prevDepth = index > 0 ? tocItems[index - 1].depth : item.depth;
+          const nextDepth = index < tocItems.length - 1 ? tocItems[index + 1].depth : item.depth;
+          const lineDiv = document.createElement('div');
+          lineDiv.style.position = 'absolute';
+          lineDiv.style.left = `${getLineOffset(item.depth)}px`;
+          lineDiv.style.top = prevDepth !== item.depth ? '6px' : '0';
+          lineDiv.style.bottom = nextDepth !== item.depth ? '6px' : '0';
+          lineDiv.style.width = '1px';
+          lineDiv.style.background = 'hsla(0, 0%, 50%, 0.1)';
+          a.appendChild(lineDiv);
+
+          if (index > 0 && tocItems[index - 1].depth !== item.depth) {
+            const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+            svg.setAttribute('viewBox', '0 0 16 16');
+            svg.setAttribute('width', '16');
+            svg.setAttribute('height', '16');
+            svg.style.position = 'absolute';
+            svg.style.top = '-6px';
+            svg.style.left = '0';
+            const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
+            line.setAttribute('x1', String(getLineOffset(tocItems[index - 1].depth)));
+            line.setAttribute('y1', '0');
+            line.setAttribute('x2', String(getLineOffset(item.depth)));
+            line.setAttribute('y2', '12');
+            line.setAttribute('stroke', 'hsla(0, 0%, 50%, 0.1)');
+            line.setAttribute('stroke-width', '1');
+            svg.appendChild(line);
+            a.appendChild(svg);
+          }
+
+          a.appendChild(document.createTextNode(item.title));
+        } else {
+          a.className = 'fd-toc-link';
+          a.style.paddingLeft = `${12 + (item.depth - 2) * 12}px`;
+          a.textContent = item.title;
+        }
+
         li.appendChild(a);
         tocList.appendChild(li);
       });
 
-      // Intersection observer for active heading
+      let maskEl = null;
+      let thumbEl = null;
+
+      if (isClerk) {
+        function buildSvgPath() {
+          const links = tocList.querySelectorAll('.fd-toc-clerk-link');
+          if (links.length === 0) return null;
+          const d = [];
+          let w = 0, h = 0;
+          links.forEach((el, i) => {
+            if (i >= tocItems.length) return;
+            const depth = tocItems[i].depth;
+            const x = getLineOffset(depth) + 1;
+            const styles = getComputedStyle(el);
+            const top = el.offsetTop + parseFloat(styles.paddingTop);
+            const bottom = el.offsetTop + el.clientHeight - parseFloat(styles.paddingBottom);
+            w = Math.max(x, w);
+            h = Math.max(h, bottom);
+            d.push(`${i === 0 ? "M" : "L"}${x} ${top}`);
+            d.push(`L${x} ${bottom}`);
+          });
+          return { path: d.join(" "), width: w + 1, height: h };
+        }
+
+        function updateThumb(activeSet) {
+          if (!thumbEl) return;
+          const links = tocList.querySelectorAll('.fd-toc-clerk-link');
+          if (activeSet.size === 0 || links.length === 0) {
+            thumbEl.style.marginTop = '0px';
+            thumbEl.style.height = '0px';
+            return;
+          }
+          let upper = Infinity, lower = 0;
+          for (const id of activeSet) {
+            const el = tocList.querySelector(`a[href="#${id}"]`);
+            if (!el) continue;
+            const styles = getComputedStyle(el);
+            upper = Math.min(upper, el.offsetTop + parseFloat(styles.paddingTop));
+            lower = Math.max(lower, el.offsetTop + el.clientHeight - parseFloat(styles.paddingBottom));
+          }
+          if (upper === Infinity) {
+            thumbEl.style.marginTop = '0px';
+            thumbEl.style.height = '0px';
+            return;
+          }
+          thumbEl.style.marginTop = `${upper}px`;
+          thumbEl.style.height = `${lower - upper}px`;
+        }
+
+        requestAnimationFrame(() => {
+          const svgData = buildSvgPath();
+          if (svgData) {
+            maskEl = document.createElement('div');
+            maskEl.className = 'fd-toc-clerk-mask';
+            maskEl.style.position = 'absolute';
+            maskEl.style.left = '0';
+            maskEl.style.top = '0';
+            maskEl.style.width = svgData.width + 'px';
+            maskEl.style.height = svgData.height + 'px';
+            maskEl.style.pointerEvents = 'none';
+            const maskSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${svgData.width} ${svgData.height}"><path d="${svgData.path}" stroke="black" stroke-width="1" fill="none"/></svg>`;
+            const maskUrl = `url("data:image/svg+xml,${encodeURIComponent(maskSvg)}")`;
+            maskEl.style.maskImage = maskUrl;
+            maskEl.style.webkitMaskImage = maskUrl;
+            maskEl.style.maskRepeat = 'no-repeat';
+            maskEl.style.webkitMaskRepeat = 'no-repeat';
+
+            thumbEl = document.createElement('div');
+            thumbEl.className = 'fd-toc-clerk-thumb';
+            thumbEl.style.background = 'var(--color-fd-primary)';
+            thumbEl.style.transition = 'all 0.15s';
+            thumbEl.style.willChange = 'height, margin-top';
+            thumbEl.style.marginTop = '0px';
+            thumbEl.style.height = '0px';
+            maskEl.appendChild(thumbEl);
+            tocList.appendChild(maskEl);
+          }
+        });
+
+        var clerkActiveSet = new Set();
+      }
+
+      const activeSet = new Set();
+
       const observer = new IntersectionObserver((entries) => {
         for (const entry of entries) {
           if (entry.isIntersecting) {
-            tocList.querySelectorAll('.fd-toc-link').forEach(link => {
-              link.classList.toggle('fd-toc-link-active', link.getAttribute('href') === `#${entry.target.id}`);
-            });
+            activeSet.add(entry.target.id);
+          } else {
+            activeSet.delete(entry.target.id);
           }
         }
+
+        if (isClerk) {
+          tocList.querySelectorAll('.fd-toc-clerk-link').forEach(link => {
+            const id = link.getAttribute('href')?.slice(1);
+            if (activeSet.has(id)) {
+              link.setAttribute('data-active', 'true');
+            } else {
+              link.removeAttribute('data-active');
+            }
+          });
+          if (typeof updateThumb === 'function') updateThumb(activeSet);
+        } else {
+          tocList.querySelectorAll('.fd-toc-link').forEach(link => {
+            const id = link.getAttribute('href')?.slice(1);
+            link.classList.toggle('fd-toc-link-active', activeSet.has(id));
+          });
+        }
       }, { rootMargin: '-80px 0px -80% 0px' });
 
       headings.forEach(el => observer.observe(el));

package/src/components/FloatingAIChat.astro

@@ -7,6 +7,8 @@ const {
   floatingStyle = "panel",
 } = Astro.props;
 
+const hasCustomTrigger = Astro.slots.has("trigger");
+
 const isFullModal = floatingStyle === "full-modal";
 
 const BTN_POSITIONS: Record<string, string> = {
@@ -55,13 +57,19 @@ const containerStyle = getContainerStyle(floatingStyle, position);
 
     <!-- Bottom input bar -->
     <div class="fd-ai-fm-input-bar fd-ai-fm-input-bar--closed" id="fd-float-bar" style={btnStyle}>
-      <button id="fd-float-trigger" class="fd-ai-fm-trigger-btn" aria-label={`Ask ${aiLabel}`}>
-        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-          <path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/>
-          <path d="M20 3v4"/><path d="M22 5h-4"/>
-        </svg>
-        <span>Ask {aiLabel}</span>
-      </button>
+      {hasCustomTrigger ? (
+        <div id="fd-float-trigger" class="fd-ai-floating-trigger">
+          <slot name="trigger" />
+        </div>
+      ) : (
+        <button id="fd-float-trigger" class="fd-ai-fm-trigger-btn" aria-label={`Ask ${aiLabel}`}>
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/>
+            <path d="M20 3v4"/><path d="M22 5h-4"/>
+          </svg>
+          <span>Ask {aiLabel}</span>
+        </button>
+      )}
 
       <div id="fd-float-input-container" class="fd-ai-fm-input-container" style="display:none">
         <div class="fd-ai-fm-input-wrap">
@@ -161,12 +169,19 @@ const containerStyle = getContainerStyle(floatingStyle, position);
     </div>
 
     <!-- Floating trigger button -->
-    <button id="fd-float-btn" class="fd-ai-floating-btn" style={btnStyle} aria-label={`Ask ${aiLabel}`}>
-      <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-        <path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/>
-        <path d="M20 3v4"/><path d="M22 5h-4"/>
-      </svg>
-    </button>
+    {hasCustomTrigger ? (
+      <div id="fd-float-btn" class="fd-ai-floating-trigger" style={btnStyle}>
+        <slot name="trigger" />
+      </div>
+    ) : (
+      <button id="fd-float-btn" class="fd-ai-floating-btn" style={btnStyle} aria-label={`Ask ${aiLabel}`}>
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/>
+          <path d="M20 3v4"/><path d="M22 5h-4"/>
+        </svg>
+        <span>Ask {aiLabel}</span>
+      </button>
+    )}
   </Fragment>
 )}
 

package/src/themes/colorful.d.ts

@@ -0,0 +1,2 @@
+export declare const colorful: (overrides?: { ui?: Record<string, unknown> }) => import("@farming-labs/docs").DocsTheme;
+export declare const ColorfulUIDefaults: Record<string, unknown>;

package/src/themes/colorful.js

@@ -0,0 +1,42 @@
+import { createTheme } from "@farming-labs/docs";
+
+const ColorfulUIDefaults = {
+  colors: {
+    primary: "hsl(40, 96%, 40%)",
+    background: "#ffffff",
+    muted: "#64748b",
+    border: "#e5e7eb",
+  },
+  typography: {
+    font: {
+      style: {
+        sans: "Inter, system-ui, sans-serif",
+        mono: "JetBrains Mono, monospace",
+      },
+      h1: { size: "1.875rem", weight: 700, lineHeight: "1.2", letterSpacing: "-0.02em" },
+      h2: { size: "1.5rem", weight: 600, lineHeight: "1.3" },
+      h3: { size: "1.25rem", weight: 600, lineHeight: "1.4" },
+      h4: { size: "1.125rem", weight: 600, lineHeight: "1.4" },
+      body: { size: "1rem", weight: 400, lineHeight: "1.75" },
+      small: { size: "0.875rem", weight: 400, lineHeight: "1.5" },
+    },
+  },
+  layout: {
+    contentWidth: 768,
+    sidebarWidth: 260,
+    toc: { enabled: true, depth: 3, style: "directional" },
+    header: { height: 56, sticky: true },
+  },
+  components: {
+    Callout: { variant: "soft", icon: true },
+    CodeBlock: { showCopyButton: true },
+    Tabs: { style: "default" },
+  },
+};
+
+export const colorful = createTheme({
+  name: "fumadocs-colorful",
+  ui: ColorfulUIDefaults,
+});
+
+export { ColorfulUIDefaults };

package/styles/colorful-bundle.css

@@ -0,0 +1,2 @@
+@import "./docs.css";
+@import "./colorful.css";

package/styles/colorful.css

@@ -0,0 +1,148 @@
+/* @farming-labs/astro-theme — colorful theme overrides
+ * Fumadocs-inspired theme with warm yellow/amber accent colors.
+ * Import AFTER the base theme CSS (docs.css).
+ */
+
+/* ─── Colorful yellow accent overrides ────────────────────────────── */
+
+:root {
+  --color-fd-primary: hsl(40, 96%, 40%);
+  --color-fd-primary-foreground: hsl(0, 0%, 100%);
+  --color-fd-ring: hsl(40, 80%, 50%);
+}
+
+.dark {
+  --color-fd-primary: hsl(45, 100%, 60%);
+  --color-fd-primary-foreground: hsl(0, 0%, 5%);
+  --color-fd-ring: hsl(45, 90%, 55%);
+}
+
+/* ─── Description under title ──────────────────────────────────────── */
+
+.fd-page-description {
+  margin-bottom: 1rem;
+  font-size: 1.125rem;
+  line-height: 1.75;
+  color: var(--color-fd-muted-foreground);
+}
+
+/* ─── Sidebar dark overrides (fumadocs neutral) ────────────────────── */
+
+.dark .fd-sidebar {
+  --color-fd-muted: hsl(0, 0%, 16%);
+  --color-fd-secondary: hsl(0, 0%, 18%);
+  --color-fd-muted-foreground: hsl(0, 0%, 72%);
+}
+
+/* ─── Cards (fumadocs style) ────────────────────────────────────────── */
+
+.fd-card {
+  display: block;
+  border-radius: 0.75rem;
+  border: 1px solid var(--color-fd-border);
+  background: var(--color-fd-card);
+  padding: 1rem;
+  font-size: 0.875rem;
+  color: var(--color-fd-card-foreground);
+  box-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1);
+  transition: background-color 150ms, border-color 150ms;
+}
+
+.fd-card:hover {
+  background: var(--color-fd-accent);
+}
+
+.fd-card-icon {
+  margin-bottom: 0.5rem;
+  width: fit-content;
+  border-radius: 0.375rem;
+  border: 1px solid var(--color-fd-border);
+  padding: 0.375rem;
+  color: var(--color-fd-muted-foreground);
+}
+
+.fd-card-title {
+  font-weight: 500;
+}
+
+.fd-card-description {
+  color: var(--color-fd-muted-foreground);
+  margin-top: 0.25rem;
+}
+
+.fd-cards {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 1rem;
+}
+
+@media (min-width: 640px) {
+  .fd-cards {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+/* ─── Page nav cards ───────────────────────────────────────────────── */
+
+.fd-page-nav-card {
+  border-radius: 0.75rem;
+}
+
+/* ─── Inline code ──────────────────────────────────────────────────── */
+
+.fd-docs-content :not(pre) > code {
+  padding: 3px;
+  border: 1px solid var(--color-fd-border);
+  font-size: 13px;
+  border-radius: 5px;
+  background: var(--color-fd-muted);
+}
+
+/* ─── Links in prose ───────────────────────────────────────────────── */
+
+.fd-docs-content a:not(.fd-page-nav-card):not([class]) {
+  text-decoration: underline;
+  text-underline-offset: 3.5px;
+  text-decoration-color: var(--color-fd-primary);
+  text-decoration-thickness: 1.5px;
+  font-weight: 500;
+}
+
+/* ─── Tables (rounded) ─────────────────────────────────────────────── */
+
+.fd-docs-content table {
+  border-collapse: separate;
+  border-spacing: 0;
+  background: var(--color-fd-card);
+  border-radius: 0.75rem;
+  border: 1px solid var(--color-fd-border);
+  overflow: hidden;
+}
+
+.fd-docs-content th {
+  background: var(--color-fd-muted);
+  font-weight: 600;
+}
+
+.fd-docs-content th,
+.fd-docs-content td {
+  padding: 0.625rem;
+  border-bottom: 1px solid var(--color-fd-border);
+}
+
+.fd-docs-content tr:last-child td {
+  border-bottom: none;
+}
+
+/* ─── Blockquotes ──────────────────────────────────────────────────── */
+
+.fd-docs-content blockquote {
+  border-left: 2px solid var(--color-fd-primary);
+  padding-left: 1rem;
+  color: var(--color-fd-foreground);
+  font-style: normal;
+}
+
+.fd-docs-content hr {
+  border-color: var(--color-fd-border);
+}

package/styles/docs.css

@@ -477,6 +477,37 @@ code, kbd, pre, samp {
   border-left-color: var(--color-fd-primary);
 }
 
+/* ─── Clerk TOC (tree-line style) ────────────────────────────────────── */
+
+.fd-toc-clerk {
+  border-left: none !important;
+}
+
+.fd-toc-clerk .fd-toc-link {
+  display: block;
+  border-left: none;
+  margin-left: 0;
+  color: var(--color-fd-muted-foreground);
+  text-decoration: none;
+  transition: color 0.15s;
+}
+
+.fd-toc-clerk .fd-toc-link:hover {
+  color: var(--color-fd-foreground);
+}
+
+.fd-toc-clerk .fd-toc-link[data-active="true"] {
+  color: var(--color-fd-primary);
+}
+
+.fd-toc-clerk-mask {
+  overflow: hidden;
+}
+
+.fd-toc-clerk-thumb {
+  width: 100%;
+}
+
 @media (max-width: 1279px) {
   .fd-toc {
     display: none;
@@ -497,6 +528,15 @@ code, kbd, pre, samp {
   }
 }
 
+/* ─── Page description (frontmatter) ─────────────────────────────────── */
+
+.fd-page-description {
+  margin-bottom: 1rem;
+  font-size: 1.125rem;
+  line-height: 1.75;
+  color: var(--color-fd-muted-foreground);
+}
+
 /* ─── Breadcrumb ─────────────────────────────────────────────────────── */
 
 .fd-breadcrumb {
@@ -1749,11 +1789,6 @@ html.dark pre.shiki {
 
 .fd-ai-floating-btn {
   border-radius: 26px;
-  box-shadow: 0 8px 32px rgba(99, 102, 241, 0.3);
-}
-
-.fd-ai-floating-btn:hover {
-  box-shadow: 0 10px 40px rgba(99, 102, 241, 0.4);
 }
 
 .fd-ai-suggestion {
@@ -1802,24 +1837,32 @@ html.dark pre.shiki {
 .fd-ai-floating-btn {
   position: fixed;
   z-index: 9997;
-  width: 52px;
-  height: 52px;
-  border-radius: var(--radius, 26px);
-  border: 1px solid var(--color-fd-border, rgba(255, 255, 255, 0.1));
-  background: var(--color-fd-primary, #6366f1);
-  color: var(--color-fd-primary-foreground, #fff);
-  cursor: pointer;
   display: flex;
   align-items: center;
   justify-content: center;
-  box-shadow: 0 8px 32px color-mix(in srgb, var(--color-fd-primary, #6366f1) 30%, transparent);
-  transition: all 200ms;
+  gap: 8px;
+  padding: 8px 12px;
+  height: 40px;
+  border-radius: 16px;
+  border: 1px solid var(--color-fd-border, rgba(255, 255, 255, 0.1));
+  background: color-mix(in srgb, var(--color-fd-secondary, #f4f4f5) 80%, transparent);
+  backdrop-filter: blur(4px);
+  color: var(--color-fd-muted-foreground, #71717a);
+  cursor: pointer;
+  font-size: 14px;
+  box-shadow: 0 1px 3px color-mix(in srgb, var(--color-fd-background, #000) 20%, transparent);
+  transition: transform 150ms, background 150ms, color 150ms;
   animation: fd-ai-fade-in 300ms ease-out;
 }
 
 .fd-ai-floating-btn:hover {
-  transform: scale(1.05);
-  box-shadow: 0 10px 40px color-mix(in srgb, var(--color-fd-primary, #6366f1) 40%, transparent);
+  background: var(--color-fd-accent);
+  color: var(--color-fd-accent-foreground);
+  transform: scale(1.03);
+}
+
+.fd-ai-floating-btn:active {
+  transform: scale(0.97);
 }
 
 .fd-ai-floating-trigger {
@@ -2153,24 +2196,28 @@ html.dark pre.shiki {
   align-items: center;
   justify-content: center;
   gap: 8px;
-  padding: 8px 16px;
+  padding: 8px 12px;
   height: 40px;
-  border-radius: var(--radius, 16px);
+  border-radius: 16px;
   border: 1px solid var(--color-fd-border, rgba(255, 255, 255, 0.1));
-  background: var(--color-fd-secondary, rgba(255, 255, 255, 0.06));
+  background: color-mix(in srgb, var(--color-fd-secondary, #f4f4f5) 80%, transparent);
+  backdrop-filter: blur(4px);
   color: var(--color-fd-muted-foreground, #71717a);
   font-family: inherit;
   font-size: 14px;
   cursor: pointer;
-  backdrop-filter: blur(8px);
-  box-shadow: 0 8px 32px color-mix(in srgb, var(--color-fd-background, #000) 40%, transparent);
-  transition: all 200ms;
+  box-shadow: 0 1px 3px color-mix(in srgb, var(--color-fd-background, #000) 20%, transparent);
+  transition: transform 150ms, background 150ms, color 150ms;
   animation: fd-ai-fade-in 300ms ease-out;
   white-space: nowrap;
 }
 
 .fd-ai-fm-trigger-btn:hover {
-  background: var(--color-fd-accent, rgba(255, 255, 255, 0.1));
-  color: var(--color-fd-accent-foreground, #fff);
+  background: var(--color-fd-accent);
+  color: var(--color-fd-accent-foreground);
   transform: scale(1.03);
 }
+
+.fd-ai-fm-trigger-btn:active {
+  transform: scale(0.97);
+}