@aravindc26/velu 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravindc26/velu",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A modern documentation site generator powered by Markdown and JSON configuration",
   "type": "module",
   "license": "MIT",

package/schema/velu.schema.json

@@ -10,6 +10,69 @@
       "type": "string",
       "description": "Path or URL to the JSON schema for editor validation."
     },
+    "theme": {
+      "type": "string",
+      "description": "Named theme preset that controls the overall look and feel.",
+      "enum": ["violet", "maple", "palm", "willow", "linden", "almond", "aspen"],
+      "default": "violet"
+    },
+    "colors": {
+      "type": "object",
+      "description": "Override the theme's accent colors.",
+      "properties": {
+        "primary": {
+          "type": "string",
+          "description": "Primary brand color (hex). Used as accent in both light and dark modes unless overridden.",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        },
+        "light": {
+          "type": "string",
+          "description": "Accent color for light mode (hex). Overrides primary in light mode.",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        },
+        "dark": {
+          "type": "string",
+          "description": "Accent color for dark mode (hex). Overrides primary in dark mode.",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "appearance": {
+      "type": "string",
+      "description": "Controls light/dark mode behavior.",
+      "enum": ["system", "light", "dark"],
+      "default": "system"
+    },
+    "styling": {
+      "type": "object",
+      "description": "Fine-grained styling options.",
+      "properties": {
+        "codeblocks": {
+          "type": "object",
+          "description": "Code block styling options.",
+          "properties": {
+            "theme": {
+              "description": "Shiki theme for syntax highlighting. Use a string for a single theme, or an object with light/dark keys.",
+              "oneOf": [
+                { "type": "string" },
+                {
+                  "type": "object",
+                  "properties": {
+                    "light": { "type": "string" },
+                    "dark": { "type": "string" }
+                  },
+                  "required": ["light", "dark"],
+                  "additionalProperties": false
+                }
+              ]
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "navigation": {
       "type": "object",
       "description": "Defines the site navigation hierarchy: tabs → groups → pages.",

package/src/build.ts

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync, rmSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
+import { generateThemeCss, type ThemeConfig, type VeluColors, type VeluStyling } from "./themes.js";
 
 // ── Types (used only by build.ts for page copying) ─────────────────────────────
 
@@ -17,6 +18,10 @@ interface VeluTab {
 
 interface VeluConfig {
   $schema?: string;
+  theme?: string;
+  colors?: VeluColors;
+  appearance?: "system" | "light" | "dark";
+  styling?: VeluStyling;
   navigation: {
     tabs?: VeluTab[];
     groups?: VeluGroup[];
@@ -132,6 +137,10 @@ export interface VeluTab {
 
 export interface VeluConfig {
   $schema?: string;
+  theme?: string;
+  colors?: { primary?: string; light?: string; dark?: string };
+  appearance?: 'system' | 'light' | 'dark';
+  styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
   navigation: {
     tabs?: VeluTab[];
     groups?: VeluGroup[];
@@ -296,9 +305,31 @@ export function getTabSidebarMap(): Record<string, string[]> {
   writeFileSync(join(outDir, "src", "lib", "velu.ts"), veluLib, "utf-8");
   console.log("📚 Generated config module");
 
-  // ── 4. Generate site config ────────────────────────────────────────────────
+  // ── 4. Generate theme CSS ─────────────────────────────────────────────────
+  const themeCss = generateThemeCss({
+    theme: config.theme,
+    colors: config.colors,
+    appearance: config.appearance,
+    styling: config.styling,
+  });
+  writeFileSync(join(outDir, "src", "styles", "velu-theme.css"), themeCss, "utf-8");
+  console.log(`🎨 Generated theme: ${config.theme || "mint"}`);
+
+  // ── 5. Generate site config ────────────────────────────────────────────────
+  // Build expressiveCode config for code block themes
+  let expressiveCodeConfig = "";
+  if (config.styling?.codeblocks?.theme) {
+    const cbt = config.styling.codeblocks.theme;
+    if (typeof cbt === "string") {
+      expressiveCodeConfig = `\n      expressiveCode: { themes: ['${cbt}'] },`;
+    } else {
+      expressiveCodeConfig = `\n      expressiveCode: { themes: ['${cbt.dark}', '${cbt.light}'] },`;
+    }
+  }
+
   const astroConfig = `import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import { ion } from 'starlight-ion-theme';
 import { getSidebar } from './src/lib/velu.ts';
 
 export default defineConfig({
@@ -306,11 +337,11 @@ export default defineConfig({
   integrations: [
     starlight({
       title: 'Velu Docs',
+      plugins: [ion()],
       components: {
-        Header: './src/components/Header.astro',
         Sidebar: './src/components/Sidebar.astro',
       },
-      customCss: ['./src/styles/tabs.css'],
+      customCss: ['./src/styles/velu-theme.css', './src/styles/tabs.css'],${expressiveCodeConfig}
       sidebar: getSidebar(),
     }),
   ],
@@ -319,64 +350,26 @@ export default defineConfig({
   writeFileSync(join(outDir, "_config.mjs"), astroConfig, "utf-8");
   console.log("⚙️  Generated site config");
 
-  // ── 5. Generate Header.astro — reads tabs from velu.ts ────────────────────
-  const headerComponent = `---
-import Default from '@astrojs/starlight/components/Header.astro';
-import { getTabs } from '../lib/velu.ts';
+  // ── 6. Generate Sidebar.astro — tabs at top + filtered content ─────────────
+  const sidebarComponent = `---
+import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
+import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro';
+import { getTabs, getTabSidebarMap } from '../lib/velu.ts';
 
 const tabs = getTabs();
+const tabSidebarMap = getTabSidebarMap();
 const currentPath = Astro.url.pathname;
 
 function isTabActive(tab: any, path: string): boolean {
   if (tab.href) return false;
   if (tab.pathPrefix === '__default__') {
     const otherPrefixes = tabs
-      .filter((t) => t.pathPrefix && t.pathPrefix !== '__default__' && !t.href)
-      .map((t) => t.pathPrefix);
-    return !otherPrefixes.some((p) => path.startsWith('/' + p + '/'));
+      .filter((t: any) => t.pathPrefix && t.pathPrefix !== '__default__' && !t.href)
+      .map((t: any) => t.pathPrefix);
+    return !otherPrefixes.some((p: string) => path.startsWith('/' + p + '/'));
   }
   return path.startsWith('/' + tab.pathPrefix + '/');
 }
----
-
-<Default {...Astro.props}>
-  <slot />
-</Default>
-
-<nav class="velu-tabs">
-  <div class="velu-tabs-inner">
-    {tabs.map((tab) => {
-      if (tab.href) {
-        return (
-          <a href={tab.href} class="velu-tab" target="_blank" rel="noopener noreferrer">
-            {tab.label}
-            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M7 17L17 7M17 7H7M17 7V17"/></svg>
-          </a>
-        );
-      }
-      const active = isTabActive(tab, currentPath);
-      const href = tab.firstPage ? '/' + tab.firstPage + '/' : '/';
-      return (
-        <a href={href} class:list={['velu-tab', { active }]}>
-          {tab.label}
-        </a>
-      );
-    })}
-  </div>
-</nav>
-`;
-  writeFileSync(join(outDir, "src", "components", "Header.astro"), headerComponent, "utf-8");
-  console.log("🧩 Generated header component");
-
-  // ── 6. Generate Sidebar.astro — reads filter map from velu.ts ─────────────
-  const sidebarComponent = `---
-import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
-import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
-import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro';
-import { getTabSidebarMap } from '../lib/velu.ts';
-
-const tabSidebarMap = getTabSidebarMap();
-const currentPath = Astro.url.pathname;
 
 function getActivePrefix(path: string): string {
   const prefixes = Object.keys(tabSidebarMap).filter(p => p !== '__default__');
@@ -396,9 +389,29 @@ const filteredSidebar = sidebar.filter((entry: any) => {
 });
 ---
 
-<SidebarPersister>
-  <SidebarSublist sublist={filteredSidebar} />
-</SidebarPersister>
+<div class="velu-sidebar-tabs">
+  {tabs.map((tab) => {
+    if (tab.href) {
+      return (
+        <a href={tab.href} class="velu-sidebar-tab" target="_blank" rel="noopener noreferrer">
+          {tab.icon && <span class="velu-sidebar-tab-icon" data-icon={tab.icon} />}
+          <span>{tab.label}</span>
+          <svg class="velu-external-icon" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M7 17L17 7M17 7H7M17 7V17"/></svg>
+        </a>
+      );
+    }
+    const active = isTabActive(tab, currentPath);
+    const href = tab.firstPage ? '/' + tab.firstPage + '/' : '/';
+    return (
+      <a href={href} class:list={['velu-sidebar-tab', { active }]}>
+        {tab.icon && <span class="velu-sidebar-tab-icon" data-icon={tab.icon} />}
+        <span>{tab.label}</span>
+      </a>
+    );
+  })}
+</div>
+
+<SidebarSublist sublist={filteredSidebar} />
 
 <div class="md:sl-hidden">
   <MobileMenuFooter />
@@ -408,74 +421,61 @@ const filteredSidebar = sidebar.filter((entry: any) => {
   console.log("📋 Generated sidebar component");
 
   // ── 7. Generate tabs.css ──────────────────────────────────────────────────
-  const tabsCss = `/* ── Velu layout overrides ──────────────────────────────────────────────── */
+  const tabsCss = `/* ── Velu sidebar tabs ─────────────────────────────────────────────────── */
 
 :root {
-  --sl-nav-height: 6rem;
+  --sl-sidebar-width: 16rem;
 }
 
-/* Fixed header: flex column, no bottom padding — tab bar sits at the bottom */
-.page > header.header {
+.velu-sidebar-tabs {
   display: flex;
   flex-direction: column;
-  padding-bottom: 0;
+  gap: 0.15rem;
+  padding: 0.35rem;
+  margin-bottom: 1rem;
+  background-color: var(--sl-color-bg);
+  border: 1px solid var(--sl-color-gray-5);
+  border-radius: 0.5rem;
 }
 
-/* Standard nav content fills the top */
-.page > header.header > .header.sl-flex {
-  height: auto;
-  flex: 1;
-}
-
-/* ── Tab bar ───────────────────────────────────────────────────────────── */
-
-.velu-tabs {
-  flex-shrink: 0;
-  /* Stretch to full header width past its padding */
-  margin-inline: calc(-1 * var(--sl-nav-pad-x));
-  padding-inline: var(--sl-nav-pad-x);
-  background: var(--sl-color-bg-nav);
-}
-
-.velu-tabs-inner {
+.velu-sidebar-tab {
   display: flex;
-  gap: 0.25rem;
-  overflow-x: auto;
-}
-
-.velu-tab {
-  display: inline-flex;
   align-items: center;
-  gap: 0.35rem;
-  padding: 0.55rem 0.85rem;
+  gap: 0.5rem;
+  padding: 0.45rem 0.65rem;
   font-size: var(--sl-text-sm);
-  font-weight: 500;
+  font-weight: 600;
   color: var(--sl-color-gray-3);
   text-decoration: none;
   border-radius: 0.375rem;
   transition: color 0.15s, background-color 0.15s;
-  white-space: nowrap;
 }
 
-.velu-tab:hover {
-  color: var(--sl-color-gray-1);
+.velu-sidebar-tab:hover {
+  color: var(--sl-color-white);
+  background-color: var(--sl-color-gray-6);
+}
+
+.velu-sidebar-tab.active {
+  color: var(--sl-color-white);
   background-color: var(--sl-color-gray-6);
 }
 
-.velu-tab.active {
+:root[data-theme='light'] .velu-sidebar-tab.active {
   color: var(--sl-color-white);
-  background-color: var(--sl-color-gray-5);
+  background-color: var(--sl-color-gray-7);
 }
 
-.velu-tab svg {
-  opacity: 0.5;
+.velu-external-icon {
+  opacity: 0.4;
   flex-shrink: 0;
+  margin-inline-start: auto;
 }
 `;
   writeFileSync(join(outDir, "src", "styles", "tabs.css"), tabsCss, "utf-8");
   console.log("🎨 Generated tabs.css");
 
-  // ── 8. Static boilerplate ─────────────────────────────────────────────────
+  // ── 9. Static boilerplate ─────────────────────────────────────────────────
   const astroPkg = {
     name: "velu-docs-site",
     version: "0.0.1",
@@ -487,9 +487,10 @@ const filteredSidebar = sidebar.filter((entry: any) => {
       preview: "astro preview",
     },
     dependencies: {
-      astro: "^5.1.0",
-      "@astrojs/starlight": "^0.32.0",
+      astro: "^5.12.0",
+      "@astrojs/starlight": "^0.35.0",
       sharp: "^0.33.0",
+      "starlight-ion-theme": "^2.3.0",
     },
   };
   writeFileSync(join(outDir, "package.json"), JSON.stringify(astroPkg, null, 2) + "\n", "utf-8");
@@ -513,7 +514,7 @@ const filteredSidebar = sidebar.filter((entry: any) => {
     "utf-8"
   );
 
-  // ── 9. Generate _server.mjs — programmatic dev/build/preview ────────────────
+  // ── 10. Generate _server.mjs — programmatic dev/build/preview ───────────────
   const serverScript = `import { dev, build, preview } from 'astro';
 import { watch } from 'node:fs';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from 'node:fs';
@@ -623,7 +624,7 @@ if (command === 'dev') {
 `;
   writeFileSync(join(outDir, "_server.mjs"), serverScript, "utf-8");
 
-  // ── 10. Generate .gitignore ──────────────────────────────────────────────
+  // ── 11. Generate .gitignore ──────────────────────────────────────────────
   writeFileSync(
     join(outDir, ".gitignore"),
     `.astro/\nnode_modules/\ndist/\n`,

package/src/cli.ts

@@ -17,7 +17,7 @@ function printHelp() {
     velu init              Scaffold a new docs project with example files
     velu lint              Validate velu.json and check referenced pages
     velu run [--port N]    Build site and start dev server (default: 4321)
-    velu build             Build site without starting the dev server
+    velu build             Build a deployable static site (SSG)
 
   Options:
     --port <number>   Port for the dev server (default: 4321)
@@ -38,6 +38,7 @@ function init(targetDir: string) {
   // velu.json
   const config = {
     $schema: "https://raw.githubusercontent.com/aravindc26/velu/main/schema/velu.schema.json",
+    theme: "violet" as const,
     navigation: {
       tabs: [
         {
@@ -109,13 +110,31 @@ async function lint(docsDir: string) {
 
 // ── build ────────────────────────────────────────────────────────────────────────
 
-async function buildSite(docsDir: string): Promise<string> {
+async function generateProject(docsDir: string): Promise<string> {
   const { build } = await import("./build.js");
   const outDir = join(docsDir, ".velu-out");
   build(docsDir, outDir);
   return outDir;
 }
 
+async function buildStatic(outDir: string) {
+  await new Promise<void>((res, rej) => {
+    const child = spawn("node", ["_server.mjs", "build"], {
+      cwd: outDir,
+      stdio: "inherit",
+    });
+    child.on("exit", (code) => (code === 0 ? res() : rej(new Error(`Build exited with ${code}`))));
+  });
+}
+
+async function buildSite(docsDir: string) {
+  const outDir = await generateProject(docsDir);
+  await installDeps(outDir);
+  await buildStatic(outDir);
+  const distDir = join(outDir, "dist");
+  console.log(`\n📁 Static site output: ${distDir}`);
+}
+
 // ── run ──────────────────────────────────────────────────────────────────────────
 
 async function installDeps(outDir: string) {
@@ -146,7 +165,7 @@ function spawnServer(outDir: string, command: string, port: number) {
 }
 
 async function run(docsDir: string, port: number) {
-  const outDir = await buildSite(docsDir);
+  const outDir = await generateProject(docsDir);
   await installDeps(outDir);
   spawnServer(outDir, "dev", port);
 }

package/src/themes.ts

@@ -0,0 +1,358 @@
+// ── Types ────────────────────────────────────────────────────────────────────
+
+interface ColorSet {
+  accentLow: string;
+  accent: string;
+  accentHigh: string;
+  white: string;
+  gray1: string;
+  gray2: string;
+  gray3: string;
+  gray4: string;
+  gray5: string;
+  gray6: string;
+  gray7: string;
+  black: string;
+}
+
+interface ThemePreset {
+  dark: ColorSet;
+  light: ColorSet;
+  font?: string;
+  fontMono?: string;
+}
+
+interface VeluColors {
+  primary?: string;
+  light?: string;
+  dark?: string;
+}
+
+interface VeluStyling {
+  codeblocks?: {
+    theme?: string | { light: string; dark: string };
+  };
+}
+
+interface ThemeConfig {
+  theme?: string;
+  colors?: VeluColors;
+  appearance?: "system" | "light" | "dark";
+  styling?: VeluStyling;
+}
+
+// ── Color utilities ──────────────────────────────────────────────────────────
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace("#", "");
+  return [
+    parseInt(h.substring(0, 2), 16),
+    parseInt(h.substring(2, 4), 16),
+    parseInt(h.substring(4, 6), 16),
+  ];
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  const clamp = (v: number) => Math.round(Math.max(0, Math.min(255, v)));
+  return (
+    "#" +
+    [clamp(r), clamp(g), clamp(b)]
+      .map((c) => c.toString(16).padStart(2, "0"))
+      .join("")
+  );
+}
+
+function mixColors(hex1: string, hex2: string, weight: number): string {
+  const [r1, g1, b1] = hexToRgb(hex1);
+  const [r2, g2, b2] = hexToRgb(hex2);
+  return rgbToHex(
+    r1 * weight + r2 * (1 - weight),
+    g1 * weight + g2 * (1 - weight),
+    b1 * weight + b2 * (1 - weight)
+  );
+}
+
+function deriveAccentPalette(primary: string): { dark: Pick<ColorSet, "accentLow" | "accent" | "accentHigh">; light: Pick<ColorSet, "accentLow" | "accent" | "accentHigh"> } {
+  return {
+    dark: {
+      accentLow: mixColors(primary, "#000000", 0.3),
+      accent: mixColors(primary, "#ffffff", 0.2),
+      accentHigh: mixColors(primary, "#ffffff", 0.8),
+    },
+    light: {
+      accentLow: mixColors(primary, "#ffffff", 0.15),
+      accent: primary,
+      accentHigh: mixColors(primary, "#000000", 0.55),
+    },
+  };
+}
+
+// ── Gray palettes ────────────────────────────────────────────────────────────
+// Starlight convention: gray-1 = strongest foreground, gray-7 = subtlest
+// In dark mode: gray-1 is light, gray-7 is dark
+// In light mode: gray-1 is dark, gray-7 is light
+// --sl-color-white = foreground extreme, --sl-color-black = background extreme
+
+const GRAY_SLATE = {
+  dark: {
+    white: "#ffffff",
+    gray1: "#eceef2",
+    gray2: "#c0c2c7",
+    gray3: "#888b96",
+    gray4: "#545861",
+    gray5: "#353841",
+    gray6: "#24272f",
+    gray7: "#17181c",
+    black: "#13141a",
+  },
+  light: {
+    white: "#13141a",
+    gray1: "#17181c",
+    gray2: "#24272f",
+    gray3: "#545861",
+    gray4: "#888b96",
+    gray5: "#c0c2c7",
+    gray6: "#eceef2",
+    gray7: "#f5f6f8",
+    black: "#ffffff",
+  },
+};
+
+const GRAY_ZINC = {
+  dark: {
+    white: "#ffffff",
+    gray1: "#ececef",
+    gray2: "#bfc0c4",
+    gray3: "#878890",
+    gray4: "#53545c",
+    gray5: "#34353b",
+    gray6: "#23242a",
+    gray7: "#17171a",
+    black: "#121214",
+  },
+  light: {
+    white: "#121214",
+    gray1: "#17171a",
+    gray2: "#23242a",
+    gray3: "#53545c",
+    gray4: "#878890",
+    gray5: "#bfc0c4",
+    gray6: "#ececef",
+    gray7: "#f5f5f7",
+    black: "#ffffff",
+  },
+};
+
+const GRAY_STONE = {
+  dark: {
+    white: "#ffffff",
+    gray1: "#eeeceb",
+    gray2: "#c3bfbb",
+    gray3: "#8c8680",
+    gray4: "#585550",
+    gray5: "#383532",
+    gray6: "#272421",
+    gray7: "#1a1816",
+    black: "#141210",
+  },
+  light: {
+    white: "#141210",
+    gray1: "#1a1816",
+    gray2: "#272421",
+    gray3: "#585550",
+    gray4: "#8c8680",
+    gray5: "#c3bfbb",
+    gray6: "#eeeceb",
+    gray7: "#f7f6f5",
+    black: "#ffffff",
+  },
+};
+
+// ── Theme presets ────────────────────────────────────────────────────────────
+
+const THEMES: Record<string, ThemePreset> = {
+  violet: {
+    dark: {
+      accentLow: "#1e1b4b",
+      accent: "#818cf8",
+      accentHigh: "#e0e7ff",
+      ...GRAY_SLATE.dark,
+    },
+    light: {
+      accentLow: "#e0e7ff",
+      accent: "#4f46e5",
+      accentHigh: "#1e1b4b",
+      ...GRAY_SLATE.light,
+    },
+  },
+
+  maple: {
+    dark: {
+      accentLow: "#2e1065",
+      accent: "#a78bfa",
+      accentHigh: "#ede9fe",
+      ...GRAY_ZINC.dark,
+    },
+    light: {
+      accentLow: "#ede9fe",
+      accent: "#7c3aed",
+      accentHigh: "#2e1065",
+      ...GRAY_ZINC.light,
+    },
+  },
+
+  palm: {
+    dark: {
+      accentLow: "#0c2d44",
+      accent: "#38bdf8",
+      accentHigh: "#e0f2fe",
+      ...GRAY_SLATE.dark,
+    },
+    light: {
+      accentLow: "#e0f2fe",
+      accent: "#0369a1",
+      accentHigh: "#0c2d44",
+      ...GRAY_SLATE.light,
+    },
+  },
+
+  willow: {
+    dark: {
+      accentLow: "#292524",
+      accent: "#a8a29e",
+      accentHigh: "#fafaf9",
+      ...GRAY_STONE.dark,
+    },
+    light: {
+      accentLow: "#f5f5f4",
+      accent: "#57534e",
+      accentHigh: "#1c1917",
+      ...GRAY_STONE.light,
+    },
+  },
+
+  linden: {
+    dark: {
+      accentLow: "#052e16",
+      accent: "#4ade80",
+      accentHigh: "#dcfce7",
+      ...GRAY_ZINC.dark,
+    },
+    light: {
+      accentLow: "#dcfce7",
+      accent: "#16a34a",
+      accentHigh: "#052e16",
+      ...GRAY_ZINC.light,
+    },
+    font: "'JetBrains Mono', 'Fira Code', 'Courier New', monospace",
+  },
+
+  almond: {
+    dark: {
+      accentLow: "#451a03",
+      accent: "#fbbf24",
+      accentHigh: "#fef3c7",
+      ...GRAY_STONE.dark,
+    },
+    light: {
+      accentLow: "#fef3c7",
+      accent: "#b45309",
+      accentHigh: "#451a03",
+      ...GRAY_STONE.light,
+    },
+  },
+
+  aspen: {
+    dark: {
+      accentLow: "#1e1b4b",
+      accent: "#818cf8",
+      accentHigh: "#e0e7ff",
+      ...GRAY_SLATE.dark,
+    },
+    light: {
+      accentLow: "#e0e7ff",
+      accent: "#4f46e5",
+      accentHigh: "#1e1b4b",
+      ...GRAY_SLATE.light,
+    },
+  },
+};
+
+// ── CSS generator ────────────────────────────────────────────────────────────
+
+function colorSetToCss(colors: ColorSet): string {
+  return [
+    `  --sl-color-accent-low: ${colors.accentLow};`,
+    `  --sl-color-accent: ${colors.accent};`,
+    `  --sl-color-accent-high: ${colors.accentHigh};`,
+    `  --sl-color-white: ${colors.white};`,
+    `  --sl-color-gray-1: ${colors.gray1};`,
+    `  --sl-color-gray-2: ${colors.gray2};`,
+    `  --sl-color-gray-3: ${colors.gray3};`,
+    `  --sl-color-gray-4: ${colors.gray4};`,
+    `  --sl-color-gray-5: ${colors.gray5};`,
+    `  --sl-color-gray-6: ${colors.gray6};`,
+    `  --sl-color-gray-7: ${colors.gray7};`,
+    `  --sl-color-black: ${colors.black};`,
+  ].join("\n");
+}
+
+function generateThemeCss(config: ThemeConfig): string {
+  const themeName = config.theme || "violet";
+  const preset = THEMES[themeName] || THEMES["violet"];
+
+  const darkColors: ColorSet = { ...preset.dark };
+  const lightColors: ColorSet = { ...preset.light };
+
+  // Apply color overrides
+  if (config.colors) {
+    const { primary, light, dark } = config.colors;
+
+    const lightAccent = light || primary;
+    const darkAccent = dark || primary;
+
+    if (lightAccent) {
+      const palette = deriveAccentPalette(lightAccent);
+      lightColors.accentLow = palette.light.accentLow;
+      lightColors.accent = palette.light.accent;
+      lightColors.accentHigh = palette.light.accentHigh;
+    }
+
+    if (darkAccent) {
+      const palette = deriveAccentPalette(darkAccent);
+      darkColors.accentLow = palette.dark.accentLow;
+      darkColors.accent = palette.dark.accent;
+      darkColors.accentHigh = palette.dark.accentHigh;
+    }
+  }
+
+  const lines: string[] = [];
+  lines.push(`/* Velu Theme: ${themeName} */`);
+  lines.push("");
+
+  // Dark mode (Starlight default)
+  lines.push(":root {");
+  lines.push(colorSetToCss(darkColors));
+  if (preset.font) {
+    lines.push(`  --sl-font: ${preset.font};`);
+  }
+  if (preset.fontMono) {
+    lines.push(`  --sl-font-mono: ${preset.fontMono};`);
+  }
+  lines.push("}");
+  lines.push("");
+
+  // Light mode
+  lines.push(":root[data-theme='light'] {");
+  lines.push(colorSetToCss(lightColors));
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function getThemeNames(): string[] {
+  return Object.keys(THEMES);
+}
+
+export { generateThemeCss, getThemeNames, THEMES, ThemeConfig, VeluColors, VeluStyling };

package/src/validate.ts

@@ -21,6 +21,10 @@ interface VeluTab {
 
 interface VeluConfig {
   $schema?: string;
+  theme?: string;
+  colors?: { primary?: string; light?: string; dark?: string };
+  appearance?: "system" | "light" | "dark";
+  styling?: { codeblocks?: { theme?: string | { light: string; dark: string } } };
   navigation: {
     tabs?: VeluTab[];
     groups?: VeluGroup[];