@barodoc/theme-docs 2.0.0 → 5.0.0

package/src/components/mdx/Steps.astro

@@ -2,7 +2,7 @@
 // Steps component for step-by-step guides
 ---
 
-<div class="not-prose my-6 space-y-4 border-l-2 border-[var(--color-border)] pl-6 ml-2">
+<div class="not-prose my-6 space-y-4 border-l-2 border-[var(--bd-border)] pl-6 ml-2">
   <slot />
 </div>
 
@@ -23,8 +23,8 @@
     height: 1.5rem;
     font-size: 0.75rem;
     font-weight: 600;
-    background-color: var(--color-bg);
-    border: 2px solid var(--color-border);
+    background-color: var(--bd-bg);
+    border: 2px solid var(--bd-border);
     border-radius: 9999px;
   }
 </style>

package/src/components/mdx/Steps.tsx

@@ -8,15 +8,8 @@ interface StepsProps {
 
 export function Steps({ children, className }: StepsProps) {
   return (
-    <div className={cn("not-prose my-6 ml-4 border-l-2 border-[var(--color-border)] pl-6 space-y-6", className)}>
-      {React.Children.map(children, (child, index) => {
-        if (React.isValidElement(child)) {
-          return React.cloneElement(child as React.ReactElement<StepProps>, {
-            stepNumber: index + 1,
-          });
-        }
-        return child;
-      })}
+    <div className={cn("bd-steps", className)}>
+      {children}
     </div>
   );
 }
@@ -24,22 +17,20 @@ export function Steps({ children, className }: StepsProps) {
 interface StepProps {
   title: string;
   children?: React.ReactNode;
-  stepNumber?: number;
   className?: string;
 }
 
-export function Step({ title, children, stepNumber = 1, className }: StepProps) {
+export function Step({ title, children, className }: StepProps) {
   return (
-    <div className={cn("relative", className)}>
-      {/* Step number circle */}
-      <div className="absolute -left-[2.125rem] flex h-6 w-6 items-center justify-center rounded-full border-2 border-[var(--color-border)] bg-[var(--color-bg)] text-xs font-semibold text-[var(--color-text-muted)]">
-        {stepNumber}
+    <div className={cn("bd-step", className)}>
+      <div className="bd-step-indicator">
+        <span className="bd-step-number" />
+        <div className="bd-step-connector" />
       </div>
-      {/* Content */}
-      <div>
-        <h3 className="font-semibold text-[var(--color-text)] mb-2">{title}</h3>
+      <div className="bd-step-content">
+        <h3 className="bd-step-title">{title}</h3>
         {children && (
-          <div className="text-sm text-[var(--color-text-secondary)] prose prose-sm dark:prose-invert max-w-none">
+          <div className="bd-step-body prose prose-sm dark:prose-invert max-w-none">
             {children}
           </div>
         )}

package/src/components/mdx/Tabs.tsx

@@ -16,22 +16,19 @@ export function Tabs({ items, defaultValue }: TabsProps) {
 
   return (
     <div className="not-prose my-4">
-      <div className="flex border-b border-[var(--color-border)]">
+      <div className="flex border-b border-[var(--bd-border)]">
         {items.map((item) => {
           const isActive = activeTab === item.value;
           return (
             <button
               key={item.value}
               type="button"
-              onClick={() => {
-                console.log('Tab clicked:', item.value);
-                setActiveTab(item.value);
-              }}
+              onClick={() => setActiveTab(item.value)}
               style={{ cursor: 'pointer' }}
               className={`px-4 py-2 text-sm font-medium transition-colors ${
                 isActive
-                  ? "border-b-2 border-blue-600 text-blue-600 -mb-px"
-                  : "text-gray-500 hover:text-gray-900"
+                  ? "border-b-2 border-primary-500 text-primary-600 dark:text-primary-400 -mb-px"
+                  : "text-[var(--bd-text-muted)] hover:text-[var(--bd-text)]"
               }`}
             >
               {item.label}
@@ -45,7 +42,7 @@ export function Tabs({ items, defaultValue }: TabsProps) {
           if (!isActive) return null;
           return (
             <div key={item.value}>
-              <pre className="bg-gray-50 dark:bg-gray-900 border border-gray-200 dark:border-gray-700 rounded-md p-3 text-sm overflow-x-auto">
+              <pre className="bg-[var(--bd-bg-code)] border border-[var(--bd-border)] rounded-md p-3 text-sm overflow-x-auto">
                 <code>{item.children}</code>
               </pre>
             </div>

package/src/components/mdx/Tooltip.tsx

@@ -1,6 +1,5 @@
 import * as React from "react";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
-import { cn } from "../../lib/utils.js";
 
 interface TooltipProps {
   children: React.ReactNode;
@@ -8,28 +7,30 @@ interface TooltipProps {
 }
 
 export function Tooltip({ children, tip }: TooltipProps) {
+  const [container, setContainer] = React.useState<HTMLElement | null>(null);
+
+  React.useEffect(() => {
+    setContainer(document.body);
+  }, []);
+
   return (
-    <TooltipPrimitive.Provider delayDuration={200}>
+    <TooltipPrimitive.Provider delayDuration={150}>
       <TooltipPrimitive.Root>
         <TooltipPrimitive.Trigger asChild>
-          <span className="cursor-help border-b border-dashed border-[var(--color-text-muted)] text-[var(--color-text)]">
-            {children}
-          </span>
+          <span className="bd-tooltip-trigger">{children}</span>
         </TooltipPrimitive.Trigger>
-        <TooltipPrimitive.Portal>
-          <TooltipPrimitive.Content
-            className={cn(
-              "z-50 overflow-hidden rounded-md bg-[var(--color-bg-tertiary)] px-3 py-1.5 text-sm text-[var(--color-text)] shadow-md",
-              "animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95",
-              "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
-              "max-w-xs"
-            )}
-            sideOffset={4}
-          >
-            {tip}
-            <TooltipPrimitive.Arrow className="fill-[var(--color-bg-tertiary)]" />
-          </TooltipPrimitive.Content>
-        </TooltipPrimitive.Portal>
+        {container && (
+          <TooltipPrimitive.Portal container={container}>
+            <TooltipPrimitive.Content
+              className="bd-tooltip-content"
+              sideOffset={6}
+              style={{ zIndex: 99999 }}
+            >
+              {tip}
+              <TooltipPrimitive.Arrow className="bd-tooltip-arrow" />
+            </TooltipPrimitive.Content>
+          </TooltipPrimitive.Portal>
+        )}
       </TooltipPrimitive.Root>
     </TooltipPrimitive.Provider>
   );

package/src/components/ui/accordion.tsx

@@ -11,7 +11,7 @@ const AccordionItem = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <AccordionPrimitive.Item
     ref={ref}
-    className={cn("border-b border-[var(--color-border)]", className)}
+    className={cn("border-b border-[var(--bd-border)]", className)}
     {...props}
   />
 ));
@@ -31,7 +31,7 @@ const AccordionTrigger = React.forwardRef<
       {...props}
     >
       {children}
-      <ChevronDown className="h-4 w-4 shrink-0 text-[var(--color-text-secondary)] transition-transform duration-200" />
+      <ChevronDown className="h-4 w-4 shrink-0 text-[var(--bd-text-secondary)] transition-transform duration-200" />
     </AccordionPrimitive.Trigger>
   </AccordionPrimitive.Header>
 ));

package/src/components/ui/alert.tsx

@@ -7,7 +7,7 @@ const alertVariants = cva(
   {
     variants: {
       variant: {
-        default: "bg-[var(--color-bg-secondary)] border-l-[var(--color-border)] text-[var(--color-text)]",
+        default: "bg-[var(--bd-bg-subtle)] border-l-[var(--bd-border)] text-[var(--bd-text)]",
         info: "bg-blue-50/70 dark:bg-blue-950/30 border-l-blue-500 text-blue-900 dark:text-blue-100 [&>svg]:text-blue-600",
         warning: "bg-orange-50/70 dark:bg-orange-950/30 border-l-orange-500 text-orange-900 dark:text-orange-100 [&>svg]:text-orange-600",
         success: "bg-green-50/70 dark:bg-green-950/30 border-l-green-500 text-green-900 dark:text-green-100 [&>svg]:text-green-600",

package/src/components/ui/button.tsx

@@ -13,11 +13,11 @@ const buttonVariants = cva(
         destructive:
           "bg-red-600 text-white shadow-sm hover:bg-red-700",
         outline:
-          "border border-[var(--color-border)] bg-transparent shadow-sm hover:bg-[var(--color-bg-secondary)] hover:text-[var(--color-text)]",
+          "border border-[var(--bd-border)] bg-transparent shadow-sm hover:bg-[var(--bd-bg-subtle)] hover:text-[var(--bd-text)]",
         secondary:
-          "bg-[var(--color-bg-secondary)] text-[var(--color-text)] shadow-sm hover:bg-[var(--color-bg-tertiary)]",
+          "bg-[var(--bd-bg-subtle)] text-[var(--bd-text)] shadow-sm hover:bg-[var(--bd-bg-muted)]",
         ghost:
-          "hover:bg-[var(--color-bg-secondary)] hover:text-[var(--color-text)]",
+          "hover:bg-[var(--bd-bg-subtle)] hover:text-[var(--bd-text)]",
         link: "text-primary-600 underline-offset-4 hover:underline",
       },
       size: {

package/src/components/ui/card.tsx

@@ -8,7 +8,7 @@ const Card = React.forwardRef<
   <div
     ref={ref}
     className={cn(
-      "rounded-xl border border-[var(--color-border)] bg-[var(--color-bg)] text-[var(--color-text)] shadow-sm",
+      "rounded-xl border border-[var(--bd-border)] bg-[var(--bd-bg)] text-[var(--bd-text)] shadow-sm",
       className
     )}
     {...props}
@@ -46,7 +46,7 @@ const CardDescription = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn("text-sm text-[var(--color-text-secondary)]", className)}
+    className={cn("text-sm text-[var(--bd-text-secondary)]", className)}
     {...props}
   />
 ));

package/src/components/ui/dialog.tsx

@@ -35,7 +35,7 @@ const DialogContent = React.forwardRef<
     <DialogPrimitive.Content
       ref={ref}
       className={cn(
-        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border border-[var(--color-border)] bg-[var(--color-bg)] p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
+        "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border border-[var(--bd-border)] bg-[var(--bd-bg)] p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg",
         className
       )}
       {...props}
@@ -99,7 +99,7 @@ const DialogDescription = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <DialogPrimitive.Description
     ref={ref}
-    className={cn("text-sm text-[var(--color-text-secondary)]", className)}
+    className={cn("text-sm text-[var(--bd-text-secondary)]", className)}
     {...props}
   />
 ));

package/src/components/ui/scroll-area.tsx

@@ -37,7 +37,7 @@ const ScrollBar = React.forwardRef<
     )}
     {...props}
   >
-    <ScrollAreaPrimitive.ScrollAreaThumb className="relative flex-1 rounded-full bg-[var(--color-border)]" />
+    <ScrollAreaPrimitive.ScrollAreaThumb className="relative flex-1 rounded-full bg-[var(--bd-border)]" />
   </ScrollAreaPrimitive.ScrollAreaScrollbar>
 ));
 ScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName;

package/src/components/ui/separator.tsx

@@ -15,7 +15,7 @@ const Separator = React.forwardRef<
       decorative={decorative}
       orientation={orientation}
       className={cn(
-        "shrink-0 bg-[var(--color-border)]",
+        "shrink-0 bg-[var(--bd-border)]",
         orientation === "horizontal" ? "h-[1px] w-full" : "h-full w-[1px]",
         className
       )}

package/src/components/ui/sheet.tsx

@@ -28,7 +28,7 @@ const SheetOverlay = React.forwardRef<
 SheetOverlay.displayName = SheetPrimitive.Overlay.displayName;
 
 const sheetVariants = cva(
-  "fixed z-50 gap-4 bg-[var(--color-bg)] p-6 shadow-lg transition ease-in-out data-[state=closed]:duration-300 data-[state=open]:duration-500 data-[state=open]:animate-in data-[state=closed]:animate-out",
+  "fixed z-50 gap-4 bg-[var(--bd-bg)] p-6 shadow-lg transition ease-in-out data-[state=closed]:duration-300 data-[state=open]:duration-500 data-[state=open]:animate-in data-[state=closed]:animate-out",
   {
     variants: {
       side: {
@@ -105,7 +105,7 @@ const SheetTitle = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <SheetPrimitive.Title
     ref={ref}
-    className={cn("text-lg font-semibold text-[var(--color-text)]", className)}
+    className={cn("text-lg font-semibold text-[var(--bd-text)]", className)}
     {...props}
   />
 ));
@@ -117,7 +117,7 @@ const SheetDescription = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <SheetPrimitive.Description
     ref={ref}
-    className={cn("text-sm text-[var(--color-text-secondary)]", className)}
+    className={cn("text-sm text-[var(--bd-text-secondary)]", className)}
     {...props}
   />
 ));

package/src/components/ui/tabs.tsx

@@ -11,7 +11,7 @@ const TabsList = React.forwardRef<
   <TabsPrimitive.List
     ref={ref}
     className={cn(
-      "inline-flex h-10 items-center justify-center rounded-lg bg-[var(--color-bg-secondary)] p-1 text-[var(--color-text-secondary)]",
+      "inline-flex h-10 items-center justify-center rounded-lg bg-[var(--bd-bg-subtle)] p-1 text-[var(--bd-text-secondary)]",
       className
     )}
     {...props}
@@ -26,7 +26,7 @@ const TabsTrigger = React.forwardRef<
   <TabsPrimitive.Trigger
     ref={ref}
     className={cn(
-      "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-[var(--color-bg)] data-[state=active]:text-[var(--color-text)] data-[state=active]:shadow",
+      "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-[var(--bd-bg)] data-[state=active]:text-[var(--bd-text)] data-[state=active]:shadow",
       className
     )}
     {...props}

package/src/components/ui/tooltip.tsx

@@ -17,7 +17,7 @@ const TooltipContent = React.forwardRef<
       ref={ref}
       sideOffset={sideOffset}
       className={cn(
-        "z-50 overflow-hidden rounded-md bg-[var(--color-text)] px-3 py-1.5 text-xs text-[var(--color-bg)] animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        "z-50 overflow-hidden rounded-md bg-[var(--bd-text)] px-3 py-1.5 text-xs text-[var(--bd-bg)] animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className
       )}
       {...props}

package/src/index.ts

@@ -84,6 +84,12 @@ function createThemeIntegration(
           integrations: [mdx(), react()],
           vite: {
             plugins: [tailwindcss()],
+            optimizeDeps: {
+              include: ["mermaid"],
+            },
+            ssr: {
+              noExternal: [],
+            },
             resolve: {
               dedupe: ["react", "react-dom"],
             },

package/src/layouts/BaseLayout.astro

@@ -1,7 +1,9 @@
 ---
 import ThemeScript from "../components/ThemeScript.astro";
 import { SearchDialog } from "../components/SearchDialog";
+import { ClientRouter } from "astro:transitions";
 import config from "virtual:barodoc/config";
+import { generateThemeCSS } from "@barodoc/core";
 import "@barodoc/theme-docs/styles/global.css";
 
 interface Props {
@@ -16,6 +18,8 @@ const canonicalUrl = config.site ? new URL(Astro.url.pathname, config.site).href
 const ogImageUrl = ogImage
   ? (config.site ? new URL(ogImage, config.site).href : ogImage)
   : undefined;
+
+const themeCSS = config.theme?.colors ? generateThemeCSS(config.theme.colors) : "";
 ---
 
 <!doctype html>
@@ -43,8 +47,10 @@ const ogImageUrl = ogImage
 
     <title>{title}</title>
     <ThemeScript />
+    <ClientRouter />
+    {themeCSS && <style set:html={themeCSS} />}
   </head>
-  <body class="min-h-screen bg-[var(--color-bg)] text-[var(--color-text)] antialiased">
+  <body class="min-h-screen bg-[var(--bd-bg)] text-[var(--bd-text)] antialiased">
     <slot />
     <SearchDialog client:load />
   </body>

package/src/layouts/DocsLayout.astro

@@ -48,18 +48,18 @@ const feedbackEndpoint = config.feedback?.endpoint;
   <Header currentLocale={currentLocale} currentPath={currentPath} />
   
   <!-- Centered container for docs layout -->
-  <div class="w-full min-w-0 min-h-[calc(100vh-3.5rem)] flex justify-center overflow-x-hidden">
-    <div class="flex w-full max-w-[1120px] min-w-0">
+  <div class="w-full min-w-0 min-h-[calc(100vh-3.5rem)] flex justify-center overflow-x-clip">
+    <div class="flex w-full max-w-[1280px] min-w-0">
       <!-- Desktop Sidebar -->
-      <aside class="hidden lg:block w-[220px] shrink-0">
-        <div class="sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto py-6 pr-4">
+      <aside class="hidden lg:block w-[240px] shrink-0 border-r border-[var(--bd-border)]">
+        <div class="sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto overscroll-contain pt-2 pb-8 px-4 sidebar-scroll">
           <Sidebar currentPath={currentPath} currentLocale={currentLocale} />
         </div>
       </aside>
 
-      <!-- Main Content: no min-width on mobile to avoid horizontal scroll -->
-      <main class="flex-1 min-w-0 lg:min-w-[650px] max-w-[720px]">
-        <div class="px-4 py-6 sm:px-6 sm:py-8 lg:px-8 lg:py-8">
+      <!-- Main Content -->
+      <main class="flex-1 min-w-0 max-w-[768px]">
+        <div class="px-4 py-8 sm:px-6 sm:py-10 lg:px-10 lg:py-10">
           {breadcrumbs.length > 0 && <Breadcrumb items={breadcrumbs} />}
           <article class="prose prose-gray dark:prose-invert max-w-none min-w-0 overflow-x-auto">
             <slot />
@@ -67,21 +67,21 @@ const feedbackEndpoint = config.feedback?.endpoint;
           
           <!-- Page Navigation -->
           {(prevPage || nextPage) && (
-            <nav class="mt-8 pt-6 border-t border-[var(--color-border)]" aria-label="Page navigation">
+            <nav class="mt-12 pt-8 border-t border-[var(--bd-border)]" aria-label="Page navigation">
               <div class="grid grid-cols-2 gap-4">
                 <div class="col-span-1">
                   {prevPage && (
                     <a 
                       href={prevPage.href}
-                      class="group flex flex-col gap-1 p-3 rounded-lg border border-[var(--color-border)] hover:border-primary-300 dark:hover:border-primary-700 hover:bg-[var(--color-bg-secondary)] transition-all"
+                      class="group flex flex-col gap-1.5 p-4 rounded-lg border border-[var(--bd-border)] hover:border-primary-400/50 dark:hover:border-primary-500/40 hover:shadow-[var(--bd-shadow-sm)] transition-all"
                     >
-                      <span class="text-xs text-[var(--color-text-muted)] flex items-center gap-1">
+                      <span class="text-xs font-medium text-[var(--bd-text-muted)] flex items-center gap-1">
                         <svg class="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7"></path>
                         </svg>
                         Previous
                       </span>
-                      <span class="text-sm font-medium text-[var(--color-text)] group-hover:text-primary-600 dark:group-hover:text-primary-400 transition-colors">
+                      <span class="text-sm font-medium text-[var(--bd-text)] group-hover:text-primary-600 dark:group-hover:text-primary-400 transition-colors">
                         {prevPage.title}
                       </span>
                     </a>
@@ -91,15 +91,15 @@ const feedbackEndpoint = config.feedback?.endpoint;
                   {nextPage && (
                     <a 
                       href={nextPage.href}
-                      class="group flex flex-col gap-1 p-3 rounded-lg border border-[var(--color-border)] hover:border-primary-300 dark:hover:border-primary-700 hover:bg-[var(--color-bg-secondary)] transition-all text-right"
+                      class="group flex flex-col gap-1.5 p-4 rounded-lg border border-[var(--bd-border)] hover:border-primary-400/50 dark:hover:border-primary-500/40 hover:shadow-[var(--bd-shadow-sm)] transition-all text-right"
                     >
-                      <span class="text-xs text-[var(--color-text-muted)] flex items-center gap-1 justify-end">
+                      <span class="text-xs font-medium text-[var(--bd-text-muted)] flex items-center gap-1 justify-end">
                         Next
                         <svg class="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7"></path>
                         </svg>
                       </span>
-                      <span class="text-sm font-medium text-[var(--color-text)] group-hover:text-primary-600 dark:group-hover:text-primary-400 transition-colors">
+                      <span class="text-sm font-medium text-[var(--bd-text)] group-hover:text-primary-600 dark:group-hover:text-primary-400 transition-colors">
                         {nextPage.title}
                       </span>
                     </a>
@@ -110,8 +110,8 @@ const feedbackEndpoint = config.feedback?.endpoint;
           )}
 
           <!-- Page footer -->
-          <footer class="mt-6 pt-4 border-t border-[var(--color-border-light)] flex flex-col gap-3">
-            <div class="flex flex-wrap items-center justify-between gap-2 text-sm text-[var(--color-text-muted)]">
+          <footer class="mt-8 pt-6 border-t border-[var(--bd-border-subtle)] flex flex-col gap-3">
+            <div class="flex flex-wrap items-center justify-between gap-2 text-[13px] text-[var(--bd-text-muted)]">
               {lastUpdated && (
                 <span>
                   Last updated: <time datetime={lastUpdated.toISOString()}>
@@ -124,7 +124,7 @@ const feedbackEndpoint = config.feedback?.endpoint;
                   href={editUrl}
                   target="_blank"
                   rel="noopener noreferrer"
-                  class="inline-flex items-center gap-1 text-primary-600 dark:text-primary-400 hover:underline"
+                  class="inline-flex items-center gap-1.5 text-[var(--bd-text-secondary)] hover:text-primary-600 dark:hover:text-primary-400 transition-colors"
                 >
                   <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                     <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z" />
@@ -134,12 +134,12 @@ const feedbackEndpoint = config.feedback?.endpoint;
               )}
             </div>
             {hasFeedback && (
-              <div class="doc-feedback flex items-center gap-3 text-sm text-[var(--color-text-muted)]" data-endpoint={feedbackEndpoint}>
+              <div class="doc-feedback flex items-center gap-3 text-sm text-[var(--bd-text-muted)]" data-endpoint={feedbackEndpoint}>
                 <span>Was this page helpful?</span>
-                <button type="button" class="feedback-btn inline-flex items-center gap-1 px-2 py-1 rounded border border-[var(--color-border)] hover:bg-[var(--color-bg-secondary)] transition-colors" data-value="yes" aria-label="Yes">
+                <button type="button" class="feedback-btn inline-flex items-center gap-1 px-2 py-1 rounded border border-[var(--bd-border)] hover:bg-[var(--bd-bg-subtle)] transition-colors" data-value="yes" aria-label="Yes">
                   <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M14 9V5a3 3 0 00-3-3l-4 9v11h11.28a2 2 0 002-1.7l1.38-9a2 2 0 00-2-2.3H14z" /></svg>
                 </button>
-                <button type="button" class="feedback-btn inline-flex items-center gap-1 px-2 py-1 rounded border border-[var(--color-border)] hover:bg-[var(--color-bg-secondary)] transition-colors" data-value="no" aria-label="No">
+                <button type="button" class="feedback-btn inline-flex items-center gap-1 px-2 py-1 rounded border border-[var(--bd-border)] hover:bg-[var(--bd-bg-subtle)] transition-colors" data-value="no" aria-label="No">
                   <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 15v3.586a1 1 0 01-.293.707l-2 2A1 1 0 016 20.586V15m4 0h5.17a2 2 0 001.98-1.742l1.08-7.56A1 1 0 0017.242 4.5H10m0 10.5V4.5m0 0H7.5A2.5 2.5 0 005 7v3" /></svg>
                 </button>
                 <span class="feedback-thanks hidden text-green-600 dark:text-green-400">Thanks for your feedback!</span>
@@ -151,8 +151,8 @@ const feedbackEndpoint = config.feedback?.endpoint;
 
       <!-- Table of Contents -->
       {headings.length > 0 && (
-        <aside class="hidden xl:block w-[180px] shrink-0">
-          <div class="sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto py-6 pl-6">
+        <aside class="hidden xl:block w-[220px] shrink-0">
+          <div class="sticky top-14 h-[calc(100vh-3.5rem)] overflow-y-auto py-10 pl-8">
             <TableOfContents headings={headings} />
           </div>
         </aside>
@@ -166,6 +166,23 @@ const feedbackEndpoint = config.feedback?.endpoint;
   <!-- Code copy functionality -->
   <CodeCopy />
 
+  <!-- Heading anchor links -->
+  <script>
+    function initHeadingAnchors() {
+      document.querySelectorAll('.prose h2[id], .prose h3[id], .prose h4[id]').forEach((heading) => {
+        if (heading.querySelector('.heading-anchor')) return;
+        const anchor = document.createElement('a');
+        anchor.className = 'heading-anchor';
+        anchor.href = `#${heading.id}`;
+        anchor.textContent = '#';
+        anchor.setAttribute('aria-label', `Link to ${heading.textContent}`);
+        heading.appendChild(anchor);
+      });
+    }
+    initHeadingAnchors();
+    document.addEventListener('astro:page-load', initHeadingAnchors);
+  </script>
+
   {hasFeedback && (
     <script>
       function initFeedback() {

package/src/pages/404.astro

@@ -8,10 +8,10 @@ const pathname = new URL(Astro.request.url).pathname;
 <BaseLayout title={`${config.name} · Page not found`} description="The page you are looking for does not exist.">
   <div class="min-h-screen flex flex-col items-center justify-center px-4">
     <div class="text-center max-w-md">
-      <p class="text-8xl font-bold text-[var(--color-text-muted)] select-none" aria-hidden="true">404</p>
-      <h1 class="text-2xl font-semibold text-[var(--color-text)] mt-4">Page not found</h1>
-      <p class="text-[var(--color-text-secondary)] mt-2">
-        The page at <code class="text-sm bg-[var(--color-bg-secondary)] px-2 py-1 rounded break-all">{pathname}</code> does not exist.
+      <p class="text-8xl font-bold text-[var(--bd-text-muted)] select-none" aria-hidden="true">404</p>
+      <h1 class="text-2xl font-semibold text-[var(--bd-text)] mt-4">Page not found</h1>
+      <p class="text-[var(--bd-text-secondary)] mt-2">
+        The page at <code class="text-sm bg-[var(--bd-bg-subtle)] px-2 py-1 rounded break-all">{pathname}</code> does not exist.
       </p>
       <div class="flex flex-col sm:flex-row items-center justify-center gap-3 mt-8">
         <a
@@ -22,7 +22,7 @@ const pathname = new URL(Astro.request.url).pathname;
         </a>
         <a
           href="/docs/introduction"
-          class="px-5 py-2.5 border border-[var(--color-border)] text-[var(--color-text)] rounded-xl hover:bg-[var(--color-bg-secondary)] transition-colors font-medium"
+          class="px-5 py-2.5 border border-[var(--bd-border)] text-[var(--bd-text)] rounded-xl hover:bg-[var(--bd-bg-subtle)] transition-colors font-medium"
         >
           Documentation
         </a>

package/src/pages/docs/[...slug].astro

@@ -124,13 +124,13 @@ breadcrumbs.push({ label: doc.data.title });
   breadcrumbs={breadcrumbs}
 >
   {category && (
-    <p class="text-xs font-medium uppercase tracking-wider text-primary-600 dark:text-primary-400 mb-2">
+    <p class="text-xs font-semibold uppercase tracking-widest text-primary-600 dark:text-primary-400 mb-3">
       {category}
     </p>
   )}
   <h1>{doc.data.title}</h1>
   {doc.data.description && (
-    <p class="lead text-sm text-[var(--color-text-secondary)] mt-1 mb-4">
+    <p class="lead text-base text-[var(--bd-text-secondary)] mt-2 mb-6 leading-relaxed">
       {doc.data.description}
     </p>
   )}