@docubook/flame 1.0.1 → 1.2.0

package/.docu/components/Context.tsx

@@ -4,8 +4,8 @@ import { useState } from "react";
 import { cn } from "../node/utils";
 import { Dropdown, DropdownItem } from "@docubook/ui-react/dropdown";
 import { routes } from "../node/client-routes";
-import { ChevronsUpDown, Check, type LucideIcon } from "lucide-react";
-import * as LucideIcons from "lucide-react";
+import { ChevronsUpDown, Check } from "lucide-react";
+import { renderLucideIcon } from "./Lucide";
 
 interface ContextProps {
   className?: string;
@@ -24,11 +24,6 @@ function getActiveContextRoute(path: string) {
   return getContextRoutes().find((route) => docPath.startsWith(route.href));
 }
 
-function getIcon(name: string): LucideIcon {
-  const Icon = LucideIcons[name as keyof typeof LucideIcons] as LucideIcon | undefined;
-  return Icon || LucideIcons.FileQuestion;
-}
-
 export function Context({ className }: ContextProps) {
   const [pathname] = useState(() =>
     typeof window !== "undefined" ? window.location.pathname : "/"
@@ -57,10 +52,7 @@ export function Context({ className }: ContextProps) {
           <div className="flex min-w-0 items-center gap-2">
             {displayRoute?.context?.icon && (
               <span className="text-primary bg-primary/10 border-primary flex-shrink-0 rounded border p-0.5">
-                {(() => {
-                  const Icon = getIcon(displayRoute.context.icon);
-                  return <Icon className="h-4 w-4" />;
-                })()}
+                {renderLucideIcon(displayRoute.context.icon, "h-4 w-4")}
               </span>
             )}
             <span className="truncate">{displayRoute?.context?.title || displayRoute?.title}</span>
@@ -93,10 +85,7 @@ export function Context({ className }: ContextProps) {
                   isActive ? "text-primary" : "text-base-content/60"
                 )}
               >
-                {(() => {
-                  const Icon = getIcon(route.context.icon);
-                  return <Icon className="h-4 w-4" />;
-                })()}
+                {renderLucideIcon(route.context.icon)}
               </span>
             )}
             <div className="min-w-0 flex-1">

package/.docu/components/Lucide.tsx

@@ -0,0 +1,20 @@
+import * as LucideIcons from "lucide-react";
+import type { LucideIcon } from "lucide-react";
+
+/**
+ * Get Lucide icon component by name
+ * Icon names must match Lucide's export names exactly (e.g., "Zap", "BookOpen", "Search")
+ */
+export function getLucideIcon(name: string): LucideIcon | null {
+  if (!name) return null;
+  const icon = (LucideIcons as Record<string, LucideIcon | undefined>)[name];
+  return icon || null;
+}
+
+/**
+ * Render Lucide icon component
+ */
+export function renderLucideIcon(name: string, className?: string) {
+  const Icon = getLucideIcon(name);
+  return Icon ? <Icon className={className} /> : null;
+}

package/.docu/components/Search.tsx

@@ -1,9 +1,40 @@
 "use client";
 
 import { useState, useEffect, useRef, useCallback } from "react";
-import { Search as SearchIcon, FileText, CornerDownLeft, Hash, AlignLeft } from "lucide-react";
+import {
+  Search as SearchIcon,
+  FileText,
+  CornerDownLeft,
+  Hash,
+  AlignLeft,
+  Command,
+  Option,
+  ChevronUp,
+  ArrowBigUp,
+  CircleArrowOutUpLeft,
+  Space,
+  Delete,
+  ArrowRightToLine,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+} from "lucide-react";
 import { Modal, useModal } from "@docubook/ui-react/modal";
 import { Kbd, FnKey } from "@docubook/ui-react/kbd";
+
+FnKey.configure({
+  Command,
+  Option,
+  ChevronUp,
+  ArrowBigUp,
+  CircleArrowOutUpLeft,
+  Space,
+  Delete,
+  ArrowRightToLine,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+});
 import { cn } from "../node/utils";
 import { search, type SearchResult } from "../node/search";
 import type { SearchRecord } from "../node/search-indexer";
@@ -181,16 +212,16 @@ export default function Search({ className }: SearchProps) {
 
           <div className="border-base-300 hidden items-center gap-3 border-t px-4 py-2.5 md:flex">
             <div className="flex items-center gap-1">
-              <Kbd size="xs">
+              <Kbd size="s">
                 <FnKey.Down />
               </Kbd>
-              <Kbd size="xs">
+              <Kbd size="s">
                 <FnKey.Up />
               </Kbd>
               <span className="text-base-content/50 text-xs">navigate</span>
             </div>
             <div className="flex items-center gap-1">
-              <Kbd size="xs">
+              <Kbd size="s">
                 <CornerDownLeft className="h-3 w-3" />
               </Kbd>
               <span className="text-base-content/50 text-xs">select</span>

package/.docu/components/Social.tsx

@@ -79,7 +79,7 @@ const iconMap: Record<string, ReturnType<typeof createIcon>> = {
   mastodon: MastodonIcon,
 };
 
-function getIcon(name: string) {
+export function getSocialIcon(name: string) {
   const key = name.toLowerCase().replace(/\s+/g, "");
   return iconMap[key] || null;
 }
@@ -92,7 +92,7 @@ export default function Social({ className = "", size = 16 }: SocialProps) {
   return (
     <div className={`flex gap-1 ${className}`}>
       {socialLinks.map((link) => {
-        const Icon = getIcon(link.name);
+        const Icon = getSocialIcon(link.name);
         return (
           <a
             key={link.name}

package/.docu/components/home/Features.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import type { HomeFeature } from "../../node/types";
+import { cn } from "../../node/utils";
+import { renderLucideIcon } from "../Lucide";
+
+interface FeaturesProps {
+  features: HomeFeature[];
+  className?: string;
+}
+
+interface FeatureCardProps {
+  feature: HomeFeature;
+  index: number;
+}
+
+function FeatureCard({ feature, index }: FeatureCardProps) {
+  const Wrapper = feature.link ? "a" : "div";
+  const wrapperProps = feature.link ? { href: feature.link } : {};
+
+  // Use index-based patternId to avoid collisions
+  const patternId = `grid-${index}`;
+
+  return (
+    <Wrapper
+      {...wrapperProps}
+      className={cn(
+        "border-base-200 bg-base-100 hover:border-primary/40 group relative overflow-hidden rounded-2xl border p-6 transition-all hover:shadow-lg",
+        feature.link && "cursor-pointer"
+      )}
+    >
+      {/* Grid pattern background */}
+      <svg
+        className="absolute inset-0 h-full w-full"
+        xmlns="http://www.w3.org/2000/svg"
+        style={{ color: "var(--color-primary)" }}
+        aria-hidden="true"
+      >
+        <defs>
+          <pattern id={patternId} width="40" height="40" patternUnits="userSpaceOnUse">
+            <path
+              d="M 40 0 L 0 0 0 40"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="0.5"
+              opacity="0.15"
+            />
+          </pattern>
+        </defs>
+        <rect width="100%" height="100%" fill={`url(#${patternId})`} />
+      </svg>
+
+      {/* Content */}
+      <div className="relative z-10">
+        {feature.icon && (
+          <div className="bg-primary/10 mb-4 inline-flex h-12 w-12 items-center justify-center rounded-lg">
+            {renderLucideIcon(feature.icon, "h-6 w-6 text-primary")}
+          </div>
+        )}
+        <h3 className="mb-2 text-lg font-semibold">{feature.title}</h3>
+        <p className="text-muted-foreground text-sm">{feature.description}</p>
+      </div>
+    </Wrapper>
+  );
+}
+
+export function Features({ features, className }: FeaturesProps) {
+  if (!features || features.length === 0) return null;
+
+  return (
+    <div className={cn("mx-auto max-w-5xl px-6 pb-24", className)}>
+      <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+        {features.map((feature, index) => (
+          <FeatureCard key={index} feature={feature} index={index} />
+        ))}
+      </div>
+    </div>
+  );
+}

package/.docu/components/home/Hero.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import type { Hero as HeroType, HeroAction } from "../../node/types";
+import { cn } from "../../node/utils";
+import { renderLucideIcon } from "../Lucide";
+import { getSocialIcon } from "../Social";
+
+interface HeroProps {
+  hero: HeroType;
+  className?: string;
+}
+
+interface ActionButtonProps {
+  action: HeroAction;
+}
+
+function isExternalLink(link: string): boolean {
+  return /^https?:\/\//.test(link);
+}
+
+function renderActionButtonIcon(iconName: string | undefined, className?: string) {
+  if (!iconName) return null;
+
+  // Try Lucide icon first
+  const lucideIcon = renderLucideIcon(iconName, className);
+  if (lucideIcon) return lucideIcon;
+
+  // Fallback to social icon
+  const SocialIcon = getSocialIcon(iconName);
+  if (SocialIcon) return <SocialIcon className={className} />;
+
+  return null;
+}
+
+function ActionButton({ action }: ActionButtonProps) {
+  const themeClasses = {
+    primary: "bg-primary text-primary-content hover:bg-primary/90",
+    secondary: "bg-secondary text-secondary-content hover:bg-secondary/90",
+    ghost: "bg-transparent text-muted-foreground border border-base-300 hover:bg-base-200",
+  };
+
+  const isExternal = isExternalLink(action.link);
+
+  return (
+    <a
+      href={action.link}
+      target={isExternal ? "_blank" : undefined}
+      rel={isExternal ? "noopener noreferrer" : undefined}
+      className={cn(
+        "inline-flex items-center gap-2 rounded-lg px-6 py-3 text-sm font-medium transition-colors",
+        themeClasses[action.theme || "primary"]
+      )}
+    >
+      {renderActionButtonIcon(action.icon, "h-4 w-4")}
+      {action.text}
+    </a>
+  );
+}
+
+export function Hero({ hero, className }: HeroProps) {
+  const { tagline, headline, description, actions } = hero;
+
+  return (
+    <div className={cn("mx-auto max-w-4xl px-6 py-32 sm:py-44", className)}>
+      <div className="text-center">
+        {tagline && <p className="text-primary mb-4 text-lg font-semibold">{tagline}</p>}
+        <h1 className="text-balance text-5xl font-semibold tracking-tight sm:text-7xl">
+          {headline}
+        </h1>
+        {description && (
+          <p className="text-muted-foreground mt-8 text-pretty text-lg sm:text-xl">{description}</p>
+        )}
+        {actions && actions.length > 0 && (
+          <div className="mt-10 flex flex-wrap items-center justify-center gap-4">
+            {actions.map((action, index) => (
+              <ActionButton key={index} action={action} />
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/.docu/components/home/index.tsx

@@ -0,0 +1,2 @@
+export { Hero } from "./Hero";
+export { Features } from "./Features";

package/.docu/node/build.ts

@@ -16,7 +16,7 @@ import {
 } from "./paths";
 import { htmlShell as createHtmlShell } from "./html";
 import { generateSearchIndex } from "./search-indexer";
-import { buildClientBundle } from "./hydrate";
+import { buildClientBundle, computeInlineThemeCss } from "./hydrate";
 import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
 import type { BuildCache, CliArgs } from "./types";
@@ -95,6 +95,8 @@ export function shouldRebuild(path: string, mtime: number, cache: BuildCache): b
 
 let assetManifest = { js: "client.js", css: "client.css" };
 
+let inlineThemeCss: string | undefined;
+
 function htmlShell(title: string, description: string, body: string): string {
   const favicon = docuConfig.meta?.favicon || "/favicon.ico";
   return createHtmlShell({
@@ -104,6 +106,7 @@ function htmlShell(title: string, description: string, body: string): string {
     favicon,
     css: assetManifest.css,
     js: assetManifest.js,
+    themeCss: inlineThemeCss,
   });
 }
 
@@ -189,6 +192,8 @@ async function build() {
   assetManifest = await buildClientBundle();
   logger.bundleDone(Math.round(performance.now() - t));
 
+  inlineThemeCss = computeInlineThemeCss();
+
   const lastManifest = cache["__assets__"];
   const assetsChanged =
     !lastManifest || lastManifest.hash !== `${assetManifest.js}:${assetManifest.css}`;

package/.docu/node/html.ts

@@ -7,11 +7,13 @@ export interface HtmlShellOptions {
   js: string;
   nonce?: string;
   extraScripts?: string;
+  themeCss?: string;
 }
 
 export function htmlShell(opts: HtmlShellOptions): string {
-  const { title, description, body, favicon, css, js, nonce, extraScripts } = opts;
+  const { title, description, body, favicon, css, js, nonce, extraScripts, themeCss } = opts;
   const nonceAttr = nonce ? ` nonce="${Bun.escapeHTML(nonce)}"` : "";
+  const themeStyle = themeCss ? `\n  <style${nonceAttr}>${Bun.escapeHTML(themeCss)}</style>` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -19,7 +21,7 @@ export function htmlShell(opts: HtmlShellOptions): string {
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>${Bun.escapeHTML(title)}</title>
   <meta name="description" content="${Bun.escapeHTML(description)}">
-  <link rel="icon" type="image/x-icon" href="${Bun.escapeHTML(favicon)}">
+  <link rel="icon" type="image/x-icon" href="${Bun.escapeHTML(favicon)}">${themeStyle}
   <link rel="stylesheet" href="/assets/${Bun.escapeHTML(css)}">
   <script${nonceAttr}>try{if(localStorage.getItem("theme")==="dark")document.documentElement.classList.add("dark")}catch(e){}</script>
 </head>

package/.docu/node/hydrate.ts

@@ -1,8 +1,12 @@
 import { join } from "node:path";
 import { mkdir, readdir, unlink } from "node:fs/promises";
+import { resolveTheme, generateThemeCss, presetRegistry } from "@docubook/themes-colors";
 import { ASSETS_DIR, LIB_DIR, STYLES_DIR, loadDocuConfig } from "./paths";
 import { resolveRoutes } from "./fs-scanner";
 import type { DocuRoute } from "./types";
+import type { ThemeConfig } from "@docubook/themes-colors";
+
+const themeRegistry = presetRegistry;
 
 async function cleanOldBundles() {
   try {
@@ -19,6 +23,53 @@ async function cleanOldBundles() {
   }
 }
 
+/**
+ * Read the effective theme config with this priority:
+ * 1. FLAME_THEME env var (CLI --theme flag)
+ * 2. docu.json theme.colors field
+ */
+export function getThemeConfig(): ThemeConfig | undefined {
+  if (process.env.FLAME_THEME) {
+    return process.env.FLAME_THEME;
+  }
+  const config = loadDocuConfig();
+  return config.themes?.colors;
+}
+
+/**
+ * Append theme CSS to compiled Tailwind output based on theme config.
+ */
+export function buildThemeCss(baseCss: string, themeConfig: unknown): string {
+  try {
+    const resolved = resolveTheme(themeConfig as ThemeConfig | undefined | null, themeRegistry);
+    return baseCss + "\n" + generateThemeCss(resolved);
+  } catch (err) {
+    console.warn(
+      `[flame] Failed to resolve theme CSS: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return baseCss;
+  }
+}
+
+/**
+ * Compute inline theme CSS for FOUC prevention.
+ * Returns undefined if no theme is configured or on error.
+ */
+export function computeInlineThemeCss(): string | undefined {
+  try {
+    const themeColors = getThemeConfig();
+    if (themeColors) {
+      const resolved = resolveTheme(themeColors, themeRegistry);
+      return generateThemeCss(resolved);
+    }
+  } catch (err) {
+    console.warn(
+      `[flame] Failed to compute inline theme CSS: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return undefined;
+}
+
 export async function buildClientBundle(): Promise<{ js: string; css: string }> {
   await mkdir(ASSETS_DIR, { recursive: true });
   await cleanOldBundles();
@@ -93,7 +144,20 @@ export async function buildClientBundle(): Promise<{ js: string; css: string }>
     const err = await new Response(proc.stderr).text();
     throw new Error(`Tailwind CSS build failed:\n${err}`);
   }
-  const cssContent = await Bun.file(tmpCss).arrayBuffer();
+
+  let cssContent = await Bun.file(tmpCss).text();
+
+  try {
+    const themeColors = getThemeConfig();
+    if (themeColors) {
+      cssContent = buildThemeCss(cssContent, themeColors);
+    }
+  } catch (err) {
+    console.warn(
+      `[flame] Failed to resolve theme config, falling back to globals.css only: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
   const cssHash = new Bun.CryptoHasher("md5").update(cssContent).digest("hex").slice(0, 8);
   const cssFile = `client-${cssHash}.css`;
   await Bun.write(join(ASSETS_DIR, cssFile), cssContent);

package/.docu/node/server.ts

@@ -11,7 +11,7 @@ import DocsPage from "../pages/docs/[[...slug]]";
 import NotFoundPage from "../pages/404";
 import IndexPage from "../pages/index";
 import { DocsLayout } from "../components/DocsLayout";
-import { buildClientBundle } from "./hydrate";
+import { buildClientBundle, computeInlineThemeCss } from "./hydrate";
 import { generateSearchIndex } from "./search-indexer";
 import { logger } from "./logger";
 import { initSentry, captureException } from "./sentry";
@@ -31,6 +31,8 @@ let t = performance.now();
 const assetManifest = await buildClientBundle();
 logger.bundleDone(Math.round(performance.now() - t));
 
+const inlineThemeCss = computeInlineThemeCss();
+
 logger.indexStart();
 t = performance.now();
 const records = await generateSearchIndex();
@@ -91,6 +93,7 @@ function createHtmlResponse(
     js: assetManifest.js,
     nonce,
     extraScripts: hmrScript(nonce),
+    themeCss: inlineThemeCss,
   });
   return htmlResponse(html, nonce, status);
 }

package/.docu/node/types.ts

@@ -40,12 +40,44 @@ export interface RepoConfig {
   edit: boolean;
 }
 
+export interface HeroAction {
+  text: string;
+  link: string;
+  theme?: "primary" | "secondary" | "ghost";
+  icon?: string;
+}
+
+export interface Hero {
+  tagline?: string;
+  headline: string;
+  description?: string;
+  actions?: HeroAction[];
+}
+
+export interface HomeFeature {
+  icon?: string;
+  title: string;
+  description: string;
+  link?: string;
+}
+
+export interface HomeConfig {
+  hero?: Hero;
+  features?: HomeFeature[];
+}
+
+import type { ThemeConfig } from "@docubook/themes-colors";
+
 export interface DocuConfig {
   meta: DocuMeta;
+  home?: HomeConfig;
   navbar: DocuNavbar;
   footer: DocuFooter;
   repo: RepoConfig;
   routes: DocuRoute[];
+  themes?: {
+    colors: ThemeConfig;
+  };
 }
 
 export interface BuildCache {

package/.docu/pages/index.tsx

@@ -1,5 +1,6 @@
-import * as icons from "lucide-react";
 import { loadDocuConfig } from "../node/paths";
+import { Hero, Features } from "../components/home";
+import type { HomeFeature } from "../node/types";
 
 const docuConfig = loadDocuConfig();
 
@@ -17,9 +18,26 @@ interface RouteItem {
 }
 
 export default function IndexPage() {
-  const { meta } = docuConfig;
+  const { meta, home } = docuConfig;
   const routes = (docuConfig.routes as RouteItem[]) || [];
-  const cards = routes.filter((r) => r.context);
+
+  // Use home.features if configured, otherwise fallback to routes with context
+  const features: HomeFeature[] =
+    home?.features ||
+    routes
+      .filter((r) => r.context)
+      .map((route) => ({
+        icon: route.context?.icon,
+        title: route.context?.title || route.title,
+        description: route.context?.description || "",
+        link: `/docs${route.href}${route.items?.[0]?.href || ""}`,
+      }));
+
+  // Use home.hero if configured, otherwise fallback to meta
+  const hero = home?.hero || {
+    headline: meta.title,
+    description: meta.description,
+  };
 
   return (
     <div className="bg-base-100 relative isolate min-h-screen overflow-hidden">
@@ -39,70 +57,11 @@ export default function IndexPage() {
         />
       </div>
 
-      {/* Hero */}
-      <div className="mx-auto max-w-2xl py-32 sm:py-44">
-        <div className="text-center">
-          <h1 className="text-balance text-5xl font-semibold tracking-tight sm:text-7xl">
-            {meta.title}
-          </h1>
-          <p className="text-muted-foreground mt-8 text-pretty text-lg sm:text-xl">
-            {meta.description}
-          </p>
-        </div>
-      </div>
+      {/* Hero Section */}
+      <Hero hero={hero} />
 
-      {/* Showcase Cards */}
-      {cards.length > 0 && (
-        <div className="relative mx-auto max-w-4xl px-6 pb-24">
-          <div className="grid grid-cols-1 gap-8 sm:grid-cols-2">
-            {cards.map((route) => {
-              const Icon = (icons as unknown as Record<string, icons.LucideIcon>)[
-                route.context!.icon || ""
-              ];
-              return (
-                <a
-                  key={route.href}
-                  href={`/docs${route.href}${route.items?.[0]?.href || ""}`}
-                  className="group"
-                >
-                  <div className="border-primary/20 bg-primary/5 group-hover:border-primary/40 relative flex aspect-[16/9] items-center justify-center overflow-hidden rounded-2xl border transition">
-                    {/* Grid pattern */}
-                    <svg
-                      className="absolute inset-0 h-full w-full"
-                      xmlns="http://www.w3.org/2000/svg"
-                    >
-                      <defs>
-                        <pattern
-                          id={`grid-${route.href}`}
-                          width="40"
-                          height="40"
-                          patternUnits="userSpaceOnUse"
-                        >
-                          <path
-                            d="M 40 0 L 0 0 0 40"
-                            fill="none"
-                            stroke="currentColor"
-                            strokeWidth="0.5"
-                            className="text-primary/15"
-                          />
-                        </pattern>
-                      </defs>
-                      <rect width="100%" height="100%" fill={`url(#grid-${route.href})`} />
-                    </svg>
-                    {Icon && (
-                      <Icon className="text-primary relative z-10" size={80} strokeWidth={1} />
-                    )}
-                  </div>
-                  <h3 className="mt-4 text-lg font-semibold">
-                    {route.context!.title || route.title}
-                  </h3>
-                  <p className="text-muted-foreground text-m mt-1">{route.context!.description}</p>
-                </a>
-              );
-            })}
-          </div>
-        </div>
-      )}
+      {/* Features Section */}
+      <Features features={features} />
 
       {/* Bottom gradient blob */}
       <div

package/README.md

@@ -65,25 +65,153 @@ bun run deploy    # Build + prepare for GitHub Pages
 
 ## Configuration
 
-`docu.json` controls your site:
+`docu.json` controls your site. Full example:
 
 ```json
 {
+  "$schema": "https://cdn.jsdelivr.net/npm/@docubook/flame/docu.schema.json",
   "meta": {
     "title": "My Docs",
-    "description": "Documentation powered by DocuBook Flame"
+    "description": "Documentation powered by DocuBook Flame",
+    "baseURL": "https://example.com",
+    "favicon": "/docs/assets/images/favicon.ico"
+  },
+  "home": {
+    "hero": {
+      "tagline": "#MyDocs",
+      "headline": "Documentation",
+      "description": "Welcome to your documentation site.",
+      "actions": [
+        { "text": "Get Started", "link": "/docs", "theme": "primary" },
+        { "text": "GitHub", "link": "https://github.com", "theme": "ghost", "icon": "github" }
+      ]
+    },
+    "features": [
+      { "icon": "Zap", "title": "Fast", "description": "Instant builds.", "link": "/docs" }
+    ]
   },
   "navbar": {
+    "logo": { "src": "/docs/assets/logo.svg", "alt": "Logo" },
     "logoText": "My Docs",
     "menu": [
       { "title": "Home", "href": "/" },
       { "title": "Docs", "href": "/docs" }
     ]
   },
+  "footer": {
+    "social": [
+      { "name": "github", "url": "https://github.com/you" }
+    ]
+  },
+  "repo": {
+    "url": "https://github.com/you/repo",
+    "path": "blob/main/{filePath}",
+    "edit": true
+  },
   "routes": []
 }
 ```
 
+### Home Page
+
+The `home` section configures your landing page with a hero section and feature cards:
+
+|      Property      |                             Description                             |
+| ------------------ | ------------------------------------------------------------------- |
+| `hero.tagline`     | Small text above the headline (e.g., product name)                  |
+| `hero.headline`    | **Required.** Main heading text                                     |
+| `hero.description` | Description below the headline                                      |
+| `hero.actions`     | Array of CTA buttons with `text`, `link`, `theme`, `icon` |
+| `features`         | Array of feature cards with `icon`, `title`, `description`, `link`  |
+
+### Theme Colors
+
+Flame uses `@docubook/themes-colors` for its config-driven color system. Configure via `docu.json`:
+
+```json
+{
+  "themes": {
+    "colors": "default"
+  }
+}
+```
+
+#### Preset Themes
+
+Use a preset name as a string. Three built-in presets are available:
+
+|     Name      |    Description    |  Hue   |
+| ------------- | ----------------- | ------ |
+| `"default"`   | Modern Blue theme | ~210   |
+| `"freshlime"` | Fresh Lime theme  | ~85    |
+| `"coffee"`    | Rich Coffee theme | ~25–35 |
+
+```json
+{
+  "themes": {
+    "colors": "freshlime"
+  }
+}
+```
+
+#### Custom Hex Colors
+
+Define a custom primary color as a hex value. The full 24-variable palette is auto-generated from it:
+
+```json
+{
+  "themes": {
+    "colors": {
+      "primary": "#FF5733"
+    }
+  }
+}
+```
+
+| Property  |      Type      | Required |                            Description                            |
+| --------- | -------------- | -------- | ----------------------------------------------------------------- |
+| `primary` | `string` (hex) | ✅ Yes    | Primary brand color. A full light + dark scale is auto-generated. |
+
+##### What gets auto-generated from `primary`
+
+A single hex color generates **24 CSS variables × 2 modes** (light `:root` + dark `.dark`) plus **12 syntax highlighting tokens × 2 modes** — all derived from the primary color.
+
+|                    Token                     |        Description         |
+| -------------------------------------------- | -------------------------- |
+| `--background` / `--foreground`              | Page background & text     |
+| `--card` / `--card-foreground`               | Card surface & text        |
+| `--popover` / `--popover-foreground`         | Popover surface & text     |
+| `--primary` / `--primary-foreground`         | Primary brand color & text |
+| `--secondary` / `--secondary-foreground`     | Secondary color & text     |
+| `--muted` / `--muted-foreground`             | Muted surface & text       |
+| `--accent` / `--accent-foreground`           | Accent color & text        |
+| `--destructive` / `--destructive-foreground` | Destructive action & text  |
+| `--border`                                   | Border color               |
+| `--input`                                    | Input field border         |
+| `--ring`                                     | Focus ring color           |
+| `--radius`                                   | Border radius value        |
+| `--base-100` / `--base-200` / `--base-300`   | DaisyUI surface layers     |
+| `--base-content`                             | DaisyUI content color      |
+
+#### CLI Override
+
+Override any theme without editing `docu.json`:
+
+```bash
+flame dev --theme freshlime
+flame build --theme coffee
+flame preview --theme default
+```
+
+#### Priority
+
+Theme resolution follows this order (first match wins):
+1. `--theme` CLI flag (e.g., `flame dev --theme coffee`)
+2. `docu.json` → `themes.colors`
+3. Falls back to `default` preset
+
+---
+
 ### Routes
 
 When `routes` is an empty array `[]`, Flame automatically scans your `docs/` folder at build-time and generates the sidebar navigation from the directory structure. Folders become collapsible sections, and `.mdx`/`.md` files become links — sorted alphabetically.
@@ -166,11 +294,11 @@ Reference in MDX:
 
 ## Comparison
 
-| Framework | Runtime | UI | Approach |
-|---|---|---|---|
-| Docusaurus | Node.js | React | Full-featured, plugin-heavy |
-| VitePress | Node.js | Vue | Lightweight, Vue-only |
-| Nextra | Node.js | React | Next.js-based |
+|      Framework      | Runtime |    UI     |          Approach           |
+| ------------------- | ------- | --------- | --------------------------- |
+| Docusaurus          | Node.js | React     | Full-featured, plugin-heavy |
+| VitePress           | Node.js | Vue       | Lightweight, Vue-only       |
+| Nextra              | Node.js | React     | Next.js-based               |
 | **@docubook/flame** | **Bun** | **React** | **Minimal, Bun-native SSR** |
 
 ---
@@ -209,6 +337,11 @@ Copy `.env.example` to `.env` to customize:
 # Server port (default: 3000)
 PORT=3000
 
+# Theme preset (optional — overrides docu.json themes.colors)
+# FLAME_THEME=default
+# FLAME_THEME=freshlime
+# FLAME_THEME=coffee
+
 # Error Monitoring (optional)
 SENTRY_DSN=https://your-dsn@sentry.io/project-id
 ```

package/bin/cli.js

@@ -16,6 +16,12 @@ const COMMAND_MAP = {
 
 const command = process.argv[2];
 
+// Parse --theme flag: set env before importing build script
+const themeIndex = process.argv.indexOf("--theme");
+if (themeIndex !== -1 && themeIndex + 1 < process.argv.length) {
+  process.env.FLAME_THEME = process.argv[themeIndex + 1];
+}
+
 if (!command || command === "--help" || command === "-h") {
   console.log(`
   @docubook/flame — A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.
@@ -31,7 +37,8 @@ if (!command || command === "--help" || command === "-h") {
     init      Scaffold a new project in current directory
 
   Options:
-    --help    Show this help message
+    --help        Show this help message
+    --theme <name>  Override theme preset (e.g. freshlime, coffee). Works with dev, build, preview.
 `);
   process.exit(0);
 }

package/docu.schema.json

@@ -10,6 +10,7 @@
     "meta": {
       "type": "object",
       "description": "Site metadata",
+      "additionalProperties": false,
       "properties": {
         "title": { "type": "string", "description": "Site title" },
         "description": { "type": "string", "description": "Site description" },
@@ -18,12 +19,27 @@
       },
       "required": ["title"]
     },
+    "home": {
+      "type": "object",
+      "description": "Home page configuration",
+      "additionalProperties": false,
+      "properties": {
+        "hero": { "$ref": "#/$defs/hero" },
+        "features": {
+          "type": "array",
+          "description": "Feature cards displayed on home page",
+          "items": { "$ref": "#/$defs/homeFeature" }
+        }
+      }
+    },
     "navbar": {
       "type": "object",
       "description": "Navigation bar configuration",
+      "additionalProperties": false,
       "properties": {
         "logo": {
           "type": "object",
+          "additionalProperties": false,
           "properties": {
             "src": { "type": "string", "description": "Logo image path" },
             "alt": { "type": "string", "description": "Logo alt text" }
@@ -35,6 +51,7 @@
           "description": "Top navigation menu items",
           "items": {
             "type": "object",
+            "additionalProperties": false,
             "properties": {
               "title": { "type": "string" },
               "href": { "type": "string" }
@@ -47,12 +64,14 @@
     "footer": {
       "type": "object",
       "description": "Footer configuration",
+      "additionalProperties": false,
       "properties": {
         "social": {
           "type": "array",
           "description": "Social media links",
           "items": {
             "type": "object",
+            "additionalProperties": false,
             "properties": {
               "name": {
                 "type": "string",
@@ -84,6 +103,7 @@
     "repo": {
       "type": "object",
       "description": "Repository configuration for edit links",
+      "additionalProperties": false,
       "properties": {
         "url": { "type": "string", "description": "Repository URL" },
         "path": {
@@ -97,11 +117,41 @@
       "type": "array",
       "description": "Documentation navigation routes. Leave empty for auto-detection from docs/ folder.",
       "items": { "$ref": "#/$defs/route" }
+    },
+    "themes": {
+      "type": "object",
+      "description": "Color themes configuration. Use preset name or custom hex values.",
+      "additionalProperties": false,
+      "properties": {
+        "colors": {
+          "description": "Theme colors — preset name (e.g. \"default\", \"freshlime\", \"coffee\") or custom hex object",
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": ["default", "freshlime", "coffee"]
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "primary": {
+                  "type": "string",
+                  "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
+                  "description": "Primary brand color in hex format"
+                }
+              },
+              "required": ["primary"]
+            }
+          ]
+        }
+      },
+      "required": ["colors"]
     }
   },
   "$defs": {
     "route": {
       "type": "object",
+      "additionalProperties": false,
       "properties": {
         "title": { "type": "string", "description": "Display title" },
         "href": { "type": "string", "description": "URL path" },
@@ -112,6 +162,7 @@
         "context": {
           "type": "object",
           "description": "Context metadata for sidebar section",
+          "additionalProperties": false,
           "properties": {
             "icon": { "type": "string", "description": "Lucide icon name" },
             "title": { "type": "string", "description": "Context switcher title" },
@@ -125,6 +176,56 @@
         }
       },
       "required": ["title", "href"]
+    },
+    "hero": {
+      "type": "object",
+      "description": "Hero section configuration for home page",
+      "additionalProperties": false,
+      "properties": {
+        "tagline": {
+          "type": "string",
+          "description": "Tagline displayed above the headline (e.g., product name)"
+        },
+        "headline": { "type": "string", "description": "Main heading text" },
+        "description": {
+          "type": "string",
+          "description": "Description text displayed below the headline"
+        },
+        "actions": {
+          "type": "array",
+          "description": "Action buttons displayed in the hero section",
+          "items": { "$ref": "#/$defs/heroAction" }
+        }
+      },
+      "required": ["headline"]
+    },
+    "heroAction": {
+      "type": "object",
+      "description": "Action button in hero section",
+      "additionalProperties": false,
+      "properties": {
+        "text": { "type": "string", "description": "Button label" },
+        "link": { "type": "string", "description": "Button link URL" },
+        "theme": {
+          "type": "string",
+          "description": "Button color theme",
+          "enum": ["primary", "secondary", "ghost"]
+        },
+        "icon": { "type": "string", "description": "Lucide icon name" }
+      },
+      "required": ["text", "link"]
+    },
+    "homeFeature": {
+      "type": "object",
+      "description": "Feature card for home page",
+      "additionalProperties": false,
+      "properties": {
+        "icon": { "type": "string", "description": "Lucide icon name" },
+        "title": { "type": "string", "description": "Feature title" },
+        "description": { "type": "string", "description": "Feature description" },
+        "link": { "type": "string", "description": "Feature link URL" }
+      },
+      "required": ["title", "description"]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -51,9 +51,10 @@
     "lucide-react": "^1.14.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@docubook/mdx-content": "^3.2.1",
     "@docubook/core": "^1.7.0",
-    "@docubook/ui-react": "^0.1.2"
+    "@docubook/mdx-content": "^3.2.1",
+    "@docubook/ui-react": "^0.1.3",
+    "@docubook/themes-colors": "^0.10.0"
   },
   "peerDependencies": {
     "@sentry/bun": "^9.0.0"

package/template/.env.example

@@ -1,5 +1,10 @@
 # Server
 PORT=3000
 
+# Theme (optional — overrides docu.json themes.colors)
+# FLAME_THEME=default
+# FLAME_THEME=freshlime
+# FLAME_THEME=coffee
+
 # Error Monitoring (optional)
 # SENTRY_DSN=https://your-dsn@sentry.io/project-id

package/template/docu.json

@@ -6,6 +6,49 @@
     "baseURL": "http://localhost:3000",
     "favicon": "/docs/assets/images/favicon.ico"
   },
+  "themes": {
+    "colors": "default"
+  },
+  "home": {
+    "hero": {
+      "tagline": "#MyDocs",
+      "headline": "Documentation",
+      "description": "Welcome to your documentation site powered by DocuBook Flame.",
+      "actions": [
+        {
+          "text": "Get Started",
+          "link": "/docs/getting-started/introduction",
+          "theme": "primary"
+        },
+        {
+          "text": "GitHub",
+          "link": "https://github.com/gitfromwildan",
+          "theme": "ghost",
+          "icon": "github"
+        }
+      ]
+    },
+    "features": [
+      {
+        "icon": "Zap",
+        "title": "Lightning Fast",
+        "description": "Powered by Bun for instant builds and hot module replacement.",
+        "link": "/docs"
+      },
+      {
+        "icon": "Paintbrush",
+        "title": "Themeable",
+        "description": "Customize with Tailwind CSS and DaisyUI for beautiful documentation.",
+        "link": "#"
+      },
+      {
+        "icon": "Search",
+        "title": "Full-Text Search",
+        "description": "Built-in search for easy content discovery.",
+        "link": "#"
+      }
+    ]
+  },
   "navbar": {
     "logo": {
       "src": "/docs/assets/images/docu.svg",