diff --git a/examples/astro/src/lib/docs.config.ts b/examples/astro/src/lib/docs.config.ts
index 285d4295..4c74438a 100644
--- a/examples/astro/src/lib/docs.config.ts
+++ b/examples/astro/src/lib/docs.config.ts
@@ -82,6 +82,7 @@ export default defineDocs({
   sitemap: { enabled: true, baseUrl: "https://docs.farming-labs.dev" },
   lastUpdated: { enabled: true, position: "below-title" },
   themeToggle: { enabled: true, default: "dark" },
+  tweaks: { reader: true, author: process.env.NODE_ENV !== "production" },
   breadcrumb: { enabled: true },
   metadata: {
     titleTemplate: "%s – Docs",
diff --git a/examples/next/docs.config.tsx b/examples/next/docs.config.tsx
index 5de5e033..81ea03e7 100644
--- a/examples/next/docs.config.tsx
+++ b/examples/next/docs.config.tsx
@@ -189,6 +189,7 @@ export default defineDocs({
     enabled: true,
     default: "light",
   },
+  tweaks: { reader: true, author: process.env.NODE_ENV !== "production", position: "both" },
   og: {
     enabled: true,
     type: "dynamic",
diff --git a/examples/nuxt/docs.config.ts b/examples/nuxt/docs.config.ts
index fc95da37..13fb2913 100644
--- a/examples/nuxt/docs.config.ts
+++ b/examples/nuxt/docs.config.ts
@@ -52,6 +52,7 @@ export default defineDocs({
     ],
   },
   themeToggle: { enabled: true, default: "dark" },
+  tweaks: { reader: true, author: process.env.NODE_ENV !== "production" },
   breadcrumb: { enabled: true },
   metadata: {
     titleTemplate: "%s – Docs",
diff --git a/examples/sveltekit/src/lib/docs.config.ts b/examples/sveltekit/src/lib/docs.config.ts
index b167ae03..d8128531 100644
--- a/examples/sveltekit/src/lib/docs.config.ts
+++ b/examples/sveltekit/src/lib/docs.config.ts
@@ -60,6 +60,7 @@ export default defineDocs({
   },
   readingTime: { enabled: true, wordsPerMinute: 220 },
   themeToggle: { enabled: true, default: "dark" },
+  tweaks: { reader: true, author: process.env.NODE_ENV !== "production" },
   breadcrumb: { enabled: true },
   metadata: {
     titleTemplate: "%s – Docs",
diff --git a/examples/tanstack-start/docs.config.tsx b/examples/tanstack-start/docs.config.tsx
index b5800734..d06e60ba 100644
--- a/examples/tanstack-start/docs.config.tsx
+++ b/examples/tanstack-start/docs.config.tsx
@@ -67,4 +67,5 @@ export default defineDocs({
     enabled: true,
     default: "dark",
   },
+  tweaks: { reader: true, author: process.env.NODE_ENV !== "production" },
 });
diff --git a/packages/docs/src/define-docs.ts b/packages/docs/src/define-docs.ts
index 2596c3ee..67676030 100644
--- a/packages/docs/src/define-docs.ts
+++ b/packages/docs/src/define-docs.ts
@@ -22,6 +22,7 @@ export function defineDocs(config: DocsConfig): DocsConfig {
     onCopyClick: config.onCopyClick,
     codeBlocks: config.codeBlocks,
     feedback: config.feedback,
+    tweaks: config.tweaks,
     search: config.search,
     mcp: config.mcp,
     icons: config.icons,
diff --git a/packages/docs/src/index.ts b/packages/docs/src/index.ts
index ccd045ed..187405e6 100644
--- a/packages/docs/src/index.ts
+++ b/packages/docs/src/index.ts
@@ -272,6 +272,7 @@ export type {
   DocsAgentFeedbackData,
   FeedbackConfig,
   AgentFeedbackConfig,
+  TweaksConfig,
   DocsAskAIMcpConfig,
   DocsSearchAdapter,
   DocsSearchAdapterContext,
diff --git a/packages/docs/src/types.ts b/packages/docs/src/types.ts
index b865607b..0a74a173 100644
--- a/packages/docs/src/types.ts
+++ b/packages/docs/src/types.ts
@@ -2107,6 +2107,96 @@ export interface FeedbackConfig {
   agent?: boolean | AgentFeedbackConfig;
 }
 
+/**
+ * Built-in "Tweaks" dialog configuration.
+ *
+ * The dialog has two modes, each independently opt-in. **Both are off by
+ * default** — site authors must explicitly enable whichever they want.
+ *
+ * - **Reader mode** (`reader: true`) exposes a limited knob set (accent,
+ *   density, radius, preset, font) to anyone visiting the docs. Choices
+ *   persist per-browser via `localStorage` and re-apply pre-paint on the
+ *   next load.
+ * - **Author mode** (`author: true`) exposes the *full* knob set — every
+ *   color token, sidebar/TOC style, layout dimensions — plus a code-export
+ *   panel that emits a ready-to-paste `createTheme({...})` snippet. Use
+ *   while iterating on a theme locally; typically gated to development:
+ *   `author: process.env.NODE_ENV !== "production"`.
+ *
+ * When both are enabled, author mode supersedes reader mode for the docs
+ * author. Public visitors still see only the reader-mode dialog.
+ *
+ * @example Reader-only — let visitors tweak their view in production
+ * ```ts
+ * export default defineDocs({
+ *   entry: "docs",
+ *   theme: fumadocs(),
+ *   tweaks: { reader: true },
+ * });
+ * ```
+ *
+ * @example Author-only — fast theme iteration during local dev
+ * ```ts
+ * export default defineDocs({
+ *   entry: "docs",
+ *   theme: fumadocs(),
+ *   tweaks: { author: process.env.NODE_ENV !== "production" },
+ * });
+ * ```
+ */
+export interface TweaksConfig {
+  /**
+   * Show the limited reader-mode Tweaks dialog to all visitors.
+   * @default false
+   */
+  reader?: boolean;
+  /**
+   * Show the full author-mode Tweaks dialog (extra knobs + code export).
+   * Typically gated to development. Supersedes reader mode when both are
+   * enabled.
+   * @default false
+   */
+  author?: boolean;
+  /**
+   * Which knobs to show in **reader mode**. Author mode always shows the
+   * full set regardless of this value.
+   * @default ["color", "density", "radius", "preset", "font-family"]
+   */
+  knobs?: Array<"color" | "density" | "radius" | "preset" | "font-family">;
+  /**
+   * Where the trigger button is mounted.
+   *
+   * - `"sidebar-footer"` — portaled next to the theme toggle (recommended).
+   * - `"floating"` — fixed bottom-right button only.
+   * - `"both"` — sidebar trigger on wide screens, floating fallback below `md`.
+   * - `"manual"` — neither trigger is auto-mounted; render
+   *   `<TweaksSidebarTrigger>` yourself wherever you want. The dialog still
+   *   mounts and opens when your trigger toggles it (shared state).
+   *
+   * @default "both"
+   */
+  position?: "sidebar-footer" | "floating" | "both" | "manual";
+  /** Label shown on the trigger button. @default "Tweaks" */
+  label?: string;
+  /** localStorage key used to persist selections. @default "fd:tweaks:v1" */
+  storageKey?: string;
+  /** Persist selections across page loads. @default true */
+  persist?: boolean;
+  /**
+   * Curated list of sans-serif fonts the reader can pick from. Each value is
+   * written into `--fd-font-sans`; the font must already be loaded on the
+   * page (the framework does not fetch arbitrary fonts at runtime).
+   *
+   * @default ["Inter", "Geist", "system-ui", "serif"]
+   */
+  fontOptions?: string[];
+  /**
+   * Async callback fired whenever a tweak is applied (color pick, preset
+   * change, slider drag-end, etc.). Useful for analytics.
+   */
+  onApply?: (state: Record<string, string>) => void | Promise<void>;
+}
+
 export interface DocsI18nConfig {
   /** Supported locale identifiers (e.g. ["en", "fr"]). */
   locales: string[];
@@ -2722,6 +2812,29 @@ export interface DocsConfig {
    * ```
    */
   feedback?: boolean | FeedbackConfig;
+  /**
+   * Built-in "Tweaks" dialog for live-tweaking theme tokens at runtime.
+   *
+   * Both modes are **off by default** — pick which audiences you want:
+   *
+   * - `{ reader: true }` → reader-mode dialog visible to all visitors.
+   * - `{ author: true }` → author-mode dialog (extra knobs + code export),
+   *   typically gated to development with
+   *   `author: process.env.NODE_ENV !== "production"`.
+   * - `true` → shorthand for `{ author: true }` (fast local iteration).
+   * - `false` / omitted → no dialog at all.
+   *
+   * @example Reader-facing, persisted per-browser
+   * ```ts
+   * tweaks: { reader: true }
+   * ```
+   *
+   * @example Author-only, dev-time theme iteration
+   * ```ts
+   * tweaks: { author: process.env.NODE_ENV !== "production" }
+   * ```
+   */
+  tweaks?: boolean | TweaksConfig;
   /**
    * Built-in MCP server for agent/assistant access to your docs content.
    *
diff --git a/packages/fumadocs/package.json b/packages/fumadocs/package.json
index 866ac80b..598725ff 100644
--- a/packages/fumadocs/package.json
+++ b/packages/fumadocs/package.json
@@ -113,6 +113,11 @@
       "import": "./dist/ai-search-dialog.mjs",
       "default": "./dist/ai-search-dialog.mjs"
     },
+    "./tweaks": {
+      "types": "./dist/tweaks-dialog.d.mts",
+      "import": "./dist/tweaks-dialog.mjs",
+      "default": "./dist/tweaks-dialog.mjs"
+    },
     "./css": "./styles/default.css",
     "./base/css": "./styles/base.css",
     "./default/css": "./styles/default.css",
diff --git a/packages/fumadocs/src/docs-layout.tsx b/packages/fumadocs/src/docs-layout.tsx
index 6d601a8d..9637ea10 100644
--- a/packages/fumadocs/src/docs-layout.tsx
+++ b/packages/fumadocs/src/docs-layout.tsx
@@ -25,6 +25,7 @@ import type {
   AIConfig,
   OrderingItem,
   PageFrontmatter,
+  TweaksConfig,
   OpenDocsConfig,
 } from "@farming-labs/docs";
 import { DocsPageClient } from "./docs-page-client.js";
@@ -34,6 +35,8 @@ import { resolveOpenDocsProviders } from "./open-docs-providers.js";
 import { resolvePageReadingTime, resolveReadingTimeOptions } from "./reading-time.js";
 import { SidebarSearchWithAI } from "./sidebar-search-ai.js";
 import { LocaleThemeControl } from "./locale-theme-control.js";
+import { TweaksAutoPortalTrigger, TweaksControl } from "./tweaks-dialog.js";
+import { buildFoucScript as buildTweaksFoucScript } from "./tweaks-runtime.js";
 import { withLangInUrl } from "./i18n.js";
 // ─── Tree node types (mirrors fumadocs-core/page-tree) ───────────────
 interface PageNode {
@@ -968,6 +971,7 @@ export function createDocsLayout(config: DocsConfig, options?: { locale?: string
   // llms.txt config
   const llmsTxtEnabled = resolveEnabledByDefault(config.llmsTxt);
   const feedbackConfig = resolveFeedbackConfig(config.feedback);
+  const tweaksConfig = resolveTweaksConfig(config.tweaks);
 
   // Serialize provider icons to HTML strings so they survive the
   // server → client component boundary.
@@ -1057,6 +1061,10 @@ export function createDocsLayout(config: DocsConfig, options?: { locale?: string
     const finalSidebarProps = { ...sidebarProps } as Record<string, unknown>;
     const sidebarFooter = sidebarProps.footer as ReactNode;
 
+    const tweaksAutoTrigger =
+      tweaksConfig.mode !== null &&
+      (tweaksConfig.position === "sidebar-footer" || tweaksConfig.position === "both");
+
     if (i18n) {
       finalSidebarProps.footer = (
         <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
@@ -1098,6 +1106,32 @@ export function createDocsLayout(config: DocsConfig, options?: { locale?: string
         <TypographyStyle typography={typography} />
         <LayoutStyle layout={layoutDimensions} />
         {forcedTheme && <ForcedThemeScript theme={forcedTheme} />}
+        {tweaksConfig.mode !== null && (
+          <script
+            dangerouslySetInnerHTML={{
+              __html: buildTweaksFoucScript(tweaksConfig.storageKey),
+            }}
+          />
+        )}
+        {tweaksConfig.mode !== null && (
+          <Suspense fallback={null}>
+            <TweaksControl
+              mode={tweaksConfig.mode!}
+              knobs={tweaksConfig.knobs}
+              position={tweaksConfig.position}
+              label={tweaksConfig.label}
+              storageKey={tweaksConfig.storageKey}
+              persist={tweaksConfig.persist}
+              fontOptions={tweaksConfig.fontOptions}
+              onApply={tweaksConfig.onApply}
+            />
+          </Suspense>
+        )}
+        {tweaksAutoTrigger && (
+          <Suspense fallback={null}>
+            <TweaksAutoPortalTrigger label={tweaksConfig.label} />
+          </Suspense>
+        )}
         {!staticExport && (
           <Suspense fallback={null}>
             <DocsCommandSearch
@@ -1216,6 +1250,59 @@ function resolveFeedbackConfig(feedback: DocsConfig["feedback"]) {
   };
 }
 
+interface ResolvedTweaksConfig {
+  /**
+   * Which dialog to mount, if any:
+   *   "author" — full knob set + code export (typically dev-only)
+   *   "reader" — limited knob set, public-facing
+   *   null     — no dialog mounted at all
+   */
+  mode: "author" | "reader" | null;
+  knobs: NonNullable<TweaksConfig["knobs"]>;
+  position: "sidebar-footer" | "floating" | "both" | "manual";
+  label: string;
+  storageKey: string;
+  persist: boolean;
+  fontOptions: ReadonlyArray<{ label: string; value: string }> | undefined;
+  onApply: TweaksConfig["onApply"];
+}
+
+function resolveTweaksConfig(tweaks: DocsConfig["tweaks"]): ResolvedTweaksConfig {
+  const defaults: ResolvedTweaksConfig = {
+    mode: null,
+    knobs: ["color", "density", "radius", "preset", "font-family"],
+    position: "both",
+    label: "Tweaks",
+    storageKey: "fd:tweaks:v1",
+    persist: true,
+    fontOptions: undefined,
+    onApply: undefined,
+  };
+
+  if (tweaks === undefined || tweaks === false) return defaults;
+  if (tweaks === true) return { ...defaults, mode: "author" };
+
+  // Author mode supersedes reader when both are set
+  const mode: "author" | "reader" | null = tweaks.author
+    ? "author"
+    : tweaks.reader
+      ? "reader"
+      : null;
+
+  return {
+    mode,
+    knobs: tweaks.knobs ?? defaults.knobs,
+    position: tweaks.position ?? defaults.position,
+    label: tweaks.label ?? defaults.label,
+    storageKey: tweaks.storageKey ?? defaults.storageKey,
+    persist: tweaks.persist !== false,
+    fontOptions: tweaks.fontOptions
+      ? tweaks.fontOptions.map((value: string) => ({ label: value.split(",")[0] ?? value, value }))
+      : undefined,
+    onApply: tweaks.onApply,
+  };
+}
+
 /**
  * Tiny inline script to force a theme when the toggle is hidden.
  * Sets the class on <html> before React hydrates to avoid FOUC.
diff --git a/packages/fumadocs/src/index.ts b/packages/fumadocs/src/index.ts
index 7b1e8811..9003d931 100644
--- a/packages/fumadocs/src/index.ts
+++ b/packages/fumadocs/src/index.ts
@@ -91,6 +91,19 @@ export { DocsFeedback } from "./docs-feedback.js";
 // ─── Page action buttons (Copy Markdown, Open in LLM) ─────────────────
 export { PageActions } from "./page-actions.js";
 
+// ─── Tweaks dialog (runtime theme tweaker) ────────────────────────────
+export {
+  TweaksAutoPortalTrigger,
+  TweaksControl,
+  TweaksFoucScript,
+  TweaksSidebarTrigger,
+} from "./tweaks-dialog.js";
+export type {
+  TweaksAutoPortalTriggerProps,
+  TweaksKnob,
+  TweaksSidebarTriggerProps,
+} from "./tweaks-dialog.js";
+
 // ─── Built-in Command Palette Search ────────────────────────────────
 export { DocsCommandSearch } from "./docs-command-search.js";
 export { withLangInUrl } from "./i18n.js";
@@ -119,6 +132,7 @@ export type {
   FeedbackConfig,
   DocsFeedbackData,
   DocsFeedbackValue,
+  TweaksConfig,
 } from "@farming-labs/docs";
 
 // ─── MDX components (for use in custom layouts or overrides) ──────────
diff --git a/packages/fumadocs/src/tweaks-dialog.tsx b/packages/fumadocs/src/tweaks-dialog.tsx
new file mode 100644
index 00000000..23a711e4
--- /dev/null
+++ b/packages/fumadocs/src/tweaks-dialog.tsx
@@ -0,0 +1,1128 @@
+"use client";
+
+import { useState, useEffect, useRef, useCallback } from "react";
+import { createPortal } from "react-dom";
+import { highlight as sugarHighlight } from "sugar-high";
+import {
+  TWEAKS_ACCENT_SWATCHES,
+  TWEAKS_COLOR_KEYS,
+  TWEAKS_DEFAULT_FONT_OPTIONS,
+  TWEAKS_DEFAULT_STORAGE_KEY,
+  TWEAKS_PRESET_BUNDLE,
+  applyTweaks,
+  buildFoucScript,
+  clearSavedTweaks,
+  readSavedTweaks,
+  resetTweaks,
+  writeSavedTweaks,
+  type TweaksColorKey,
+  type TweaksDensity,
+  type TweaksPresetKey,
+  type TweaksState,
+} from "./tweaks-runtime.js";
+import { SidebarCollapseTrigger } from "fumadocs-ui/components/sidebar/base";
+
+
+export type TweaksKnob = "color" | "density" | "radius" | "preset" | "font-family";
+
+const DEFAULT_KNOBS: ReadonlyArray<TweaksKnob> = [
+  "color",
+  "density",
+  "radius",
+  "preset",
+  "font-family",
+];
+
+const DENSITY_OPTIONS: ReadonlyArray<{ label: string; value: TweaksDensity }> = [
+  { label: "Compact", value: "compact" },
+  { label: "Cozy", value: "comfortable" },
+  { label: "Roomy", value: "roomy" },
+];
+
+const PRESET_OPTIONS: ReadonlyArray<{ label: string; value: TweaksPresetKey }> = (
+  Object.entries(TWEAKS_PRESET_BUNDLE) as Array<[TweaksPresetKey, { label: string }]>
+).map(([value, tokens]) => ({ value, label: tokens.label }));
+
+const COLOR_KEY_LABELS: Record<TweaksColorKey, string> = {
+  primary: "Primary",
+  primaryForeground: "Primary fg",
+  background: "Background",
+  foreground: "Foreground",
+  muted: "Muted",
+  mutedForeground: "Muted fg",
+  border: "Border",
+  card: "Card",
+  cardForeground: "Card fg",
+  accent: "Accent",
+  accentForeground: "Accent fg",
+  secondary: "Secondary",
+  secondaryForeground: "Secondary fg",
+  popover: "Popover",
+  popoverForeground: "Popover fg",
+  ring: "Ring",
+};
+
+const DEFAULT_FALLBACKS: Record<TweaksColorKey, string> = {
+  primary: "#6366f1",
+  primaryForeground: "#ffffff",
+  background: "#0c0c0c",
+  foreground: "#fafafa",
+  muted: "#262626",
+  mutedForeground: "#a3a3a3",
+  border: "#262626",
+  card: "#141414",
+  cardForeground: "#fafafa",
+  accent: "#1f1f1f",
+  accentForeground: "#fafafa",
+  secondary: "#141414",
+  secondaryForeground: "#fafafa",
+  popover: "#141414",
+  popoverForeground: "#fafafa",
+  ring: "#6366f1",
+};
+
+function parsePxWidth(raw: string | undefined, fallback: number): number {
+  if (!raw) return fallback;
+  const m = raw.match(/^([\d.]+)(px|rem)?$/);
+  if (!m) return fallback;
+  const n = Number(m[1]);
+  if (Number.isNaN(n)) return fallback;
+  return m[2] === "rem" ? Math.round(n * 16) : Math.round(n);
+}
+
+// ─── Icons (inline SVG, stroke="currentColor", matches repo convention) ─
+
+function SettingsIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="12" cy="12" r="3" />
+      <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z" />
+    </svg>
+  );
+}
+
+function CloseIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M18 6 6 18" />
+      <path d="m6 6 12 12" />
+    </svg>
+  );
+}
+
+function CheckIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+function TweaksColorRow({
+  value,
+  onChange,
+}: {
+  value: string | undefined;
+  onChange: (color: string) => void;
+}) {
+  return (
+    <div className="fd-tweaks-row">
+      <span className="fd-tweaks-row-label">Accent color</span>
+      <div className="fd-tweaks-swatches" role="radiogroup" aria-label="Accent color">
+        {TWEAKS_ACCENT_SWATCHES.map((s) => {
+          const selected = value === s.value;
+          return (
+            <button
+              key={s.value}
+              type="button"
+              role="radio"
+              aria-checked={selected}
+              aria-label={s.name}
+              className="fd-tweaks-swatch"
+              data-selected={selected || undefined}
+              style={{ background: s.value }}
+              onClick={() => onChange(s.value)}
+            >
+              {selected && (
+                <span className="fd-tweaks-swatch-check" aria-hidden="true">
+                  <CheckIcon />
+                </span>
+              )}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function TweaksChipGroup<T extends string>({
+  label,
+  value,
+  options,
+  onChange,
+}: {
+  label: string;
+  value: T | undefined;
+  options: ReadonlyArray<{ label: string; value: T }>;
+  onChange: (next: T) => void;
+}) {
+  return (
+    <div className="fd-tweaks-row">
+      <span className="fd-tweaks-row-label">{label}</span>
+      <div className="fd-tweaks-chips" role="radiogroup" aria-label={label}>
+        {options.map((option) => {
+          const selected = value === option.value;
+          return (
+            <button
+              key={option.value}
+              type="button"
+              role="radio"
+              aria-checked={selected}
+              className="fd-tweaks-chip"
+              data-selected={selected || undefined}
+              onClick={() => onChange(option.value)}
+            >
+              {option.label}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function TweaksSlider({
+  label, value, min,
+  max, step, format,
+  onChange, disabled
+}: {
+  label: string;
+  value: number;
+  min: number;
+  max: number;
+  step: number;
+  format: (v: number) => string;
+  onChange: (next: number) => void;
+  disabled?: boolean
+}) {
+  return (
+    <div className="fd-tweaks-row">
+      <span className="fd-tweaks-row-label">
+        <span>{label}</span>
+        <span className="fd-tweaks-row-value">{format(value)}</span>
+      </span>
+      <input
+        type="range"
+        className="fd-tweaks-slider"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        aria-label={label}
+        onChange={(e) => onChange(Number(e.target.value))}
+        disabled={disabled}
+      />
+    </div>
+  );
+}
+
+function buildCreateThemeSnippet(state: TweaksState): string {
+  const lines: string[] = [];
+  lines.push(`import { createTheme } from "@farming-labs/docs";`);
+  lines.push(``);
+  lines.push(`export const theme = createTheme({`);
+  lines.push(`  name: "custom",`);
+  lines.push(`  ui: {`);
+
+  const colorEntries: Array<[string, string]> = [];
+  if (state.primary) colorEntries.push(["primary", state.primary]);
+  if (state.colors) {
+    for (const key of TWEAKS_COLOR_KEYS) {
+      const v = state.colors[key];
+      if (v && !(key === "primary" && state.primary)) colorEntries.push([key, v]);
+    }
+  }
+  if (colorEntries.length > 0) {
+    lines.push(`    colors: {`);
+    for (const [k, v] of colorEntries) lines.push(`      ${k}: ${JSON.stringify(v)},`);
+    lines.push(`    },`);
+  }
+
+  if (state.radius) lines.push(`    radius: ${JSON.stringify(state.radius)},`);
+
+  if (state.fontFamily) {
+    lines.push(`    typography: { font: { style: { sans: ${JSON.stringify(state.fontFamily)} } } },`);
+  }
+
+  const layoutBits: string[] = [];
+  if (state.contentWidth) layoutBits.push(`contentWidth: ${JSON.stringify(state.contentWidth)}`);
+  if (state.sidebarWidth) layoutBits.push(`sidebarWidth: ${JSON.stringify(state.sidebarWidth)}`);
+  if (state.tocWidth) layoutBits.push(`tocWidth: ${JSON.stringify(state.tocWidth)}`);
+  if (layoutBits.length > 0) {
+    lines.push(`    layout: { ${layoutBits.join(", ")} },`);
+  }
+
+  lines.push(`  },`);
+  lines.push(`});`);
+  return lines.join("\n");
+}
+
+function buildCssSnippet(state: TweaksState): string {
+  const rules: string[] = [":root {"];
+  const colorRules = (key: TweaksColorKey, value: string) =>
+    rules.push(`  --color-fd-${cssVarSegment(key)}: ${value};`);
+
+  if (state.primary) {
+    colorRules("primary", state.primary);
+    colorRules("ring", state.primary);
+  }
+  if (state.colors) {
+    for (const key of TWEAKS_COLOR_KEYS) {
+      const v = state.colors[key];
+      if (v) colorRules(key, v);
+    }
+  }
+  if (state.radius) rules.push(`  --radius: ${state.radius};`);
+  if (state.fontFamily) rules.push(`  --fd-font-sans: ${state.fontFamily};`);
+  if (state.density) {
+    const scale = state.density === "compact" ? "0.9" : state.density === "roomy" ? "1.1" : "1";
+    rules.push(`  --fd-font-scale: ${scale};`);
+  }
+  if (state.sidebarWidth) rules.push(`  --fd-sidebar-width: ${state.sidebarWidth};`);
+  if (state.contentWidth) rules.push(`  --fd-content-width: ${state.contentWidth};`);
+  if (state.tocWidth) rules.push(`  --fd-toc-width: ${state.tocWidth};`);
+
+  rules.push("}");
+  return rules.join("\n");
+}
+
+function cssVarSegment(key: TweaksColorKey): string {
+  // primaryForeground → primary-foreground
+  return key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+
+function isPristineState(state: TweaksState): boolean {
+  if (state.primary) return false;
+  if (state.density) return false;
+  if (state.radius) return false;
+  if (state.preset) return false;
+  if (state.fontFamily) return false;
+  if (state.sidebarWidth || state.contentWidth || state.tocWidth) return false;
+  if (state.colors && Object.values(state.colors).some((v) => v)) return false;
+  return true;
+}
+
+function highlightSnippet(code: string): string {
+  try {
+    return sugarHighlight(code);
+  } catch {
+    const div = typeof document !== "undefined" ? document.createElement("div") : null;
+    if (div) {
+      div.textContent = code;
+      return div.innerHTML;
+    }
+    return code.replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[c]!);
+  }
+}
+
+function TweaksCodeExport({ state }: { state: TweaksState }) {
+  const [tab, setTab] = useState<"ts" | "css">("ts");
+  const [copied, setCopied] = useState(false);
+  const code = tab === "ts" ? buildCreateThemeSnippet(state) : buildCssSnippet(state);
+  const highlighted = highlightSnippet(code);
+
+  const handleCopy = useCallback(() => {
+    void navigator.clipboard.writeText(code).then(() => {
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1600);
+    });
+  }, [code]);
+
+
+  return (
+    <div className="fd-tweaks-export">
+      <div className="fd-tweaks-export-tabs" role="tablist" aria-label="Export format">
+        <button
+          type="button"
+          role="tab"
+          aria-selected={tab === "ts"}
+          data-selected={tab === "ts" || undefined}
+          className="fd-tweaks-export-tab"
+          onClick={() => setTab("ts")}
+        >
+          createTheme
+        </button>
+        <button
+          type="button"
+          role="tab"
+          aria-selected={tab === "css"}
+          data-selected={tab === "css" || undefined}
+          className="fd-tweaks-export-tab"
+          onClick={() => setTab("css")}
+        >
+          CSS
+        </button>
+        <button
+          type="button"
+          className="fd-tweaks-export-copy"
+          aria-label="Copy snippet"
+          onClick={handleCopy}
+        >
+          {copied ? "Copied" : "Copy"}
+        </button>
+      </div>
+      <pre
+        className="fd-tweaks-export-code fd-tweaks-export-code-highlighted"
+        aria-live="polite"
+        dangerouslySetInnerHTML={{ __html: highlighted }}
+      />
+    </div>
+  );
+}
+
+function TweaksHexColorRow({
+  label,
+  value,
+  fallback,
+  onChange,
+}: {
+  label: string;
+  value: string | undefined;
+  fallback: string;
+  onChange: (next: string) => void;
+}) {
+  const swatchRef = useRef<HTMLInputElement>(null);
+  const display = value ?? "";
+  const swatchColor = value || fallback;
+  return (
+    <div className="fd-tweaks-color-pair">
+      <button
+        type="button"
+        className="fd-tweaks-color-swatch-mini"
+        style={{ background: swatchColor }}
+        aria-label={`Pick ${label}`}
+        onClick={() => swatchRef.current?.click()}
+      />
+      <input
+        ref={swatchRef}
+        type="color"
+        value={/^#[0-9a-f]{6}$/i.test(swatchColor) ? swatchColor : "#000000"}
+        onChange={(e) => onChange(e.target.value)}
+        style={{ position: "absolute", opacity: 0, width: 0, height: 0, pointerEvents: "none" }}
+        tabIndex={-1}
+        aria-hidden="true"
+      />
+      <input
+        type="text"
+        className="fd-tweaks-color-text"
+        value={display}
+        placeholder={fallback}
+        spellCheck={false}
+        aria-label={label}
+        onChange={(e) => onChange(e.target.value)}
+      />
+      <span className="fd-tweaks-color-label">{label}</span>
+    </div>
+  );
+}
+
+function TweaksSelect<T extends string>({
+  label,
+  value,
+  options,
+  onChange,
+}: {
+  label: string;
+  value: T | "";
+  options: ReadonlyArray<{ label: string; value: T }>;
+  onChange: (next: T) => void;
+}) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [flipUp, setFlipUp] = useState(false);
+  const wrapRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    function handler(e: MouseEvent) {
+      if (wrapRef.current && !wrapRef.current.contains(e.target as Node)) {
+        setIsOpen(false);
+      }
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === "Escape") setIsOpen(false);
+    }
+    document.addEventListener("mousedown", handler);
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("mousedown", handler);
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [isOpen]);
+
+  // Decide flip direction *before* opening so the menu renders in the right
+  // place on the first paint — no jump. The reader-mode dialog floats near
+  // the viewport edge, so the menu often has no room below the trigger.
+  const handleToggle = () => {
+    if (!isOpen && triggerRef.current) {
+      const rect = triggerRef.current.getBoundingClientRect();
+      const menuHeight = 244; // max-height (240) + gap (4)
+      const spaceBelow = window.innerHeight - rect.bottom;
+      const spaceAbove = rect.top;
+      setFlipUp(spaceBelow < menuHeight && spaceAbove > spaceBelow);
+    }
+    setIsOpen((v) => !v);
+  };
+
+  const selected = options.find((o) => o.value === value);
+
+  return (
+    <div className="fd-tweaks-row">
+      <span className="fd-tweaks-row-label">{label}</span>
+      <div className="fd-tweaks-select-wrap" ref={wrapRef}>
+        <button
+          ref={triggerRef}
+          type="button"
+          className="fd-tweaks-select-trigger"
+          aria-haspopup="listbox"
+          aria-expanded={isOpen}
+          aria-label={label}
+          data-open={isOpen || undefined}
+          onClick={handleToggle}
+        >
+          <span className="fd-tweaks-select-trigger-label">
+            {selected?.label ?? "Default"}
+          </span>
+          <svg
+            width="10"
+            height="10"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            className="fd-tweaks-select-chevron"
+            aria-hidden="true"
+          >
+            <path d="m6 9 6 6 6-6" />
+          </svg>
+        </button>
+        {isOpen && (
+          <div
+            className="fd-tweaks-select-menu"
+            role="listbox"
+            aria-label={label}
+            data-flip-up={flipUp || undefined}
+          >
+            {options.map((option) => {
+              const active = option.value === value;
+              return (
+                <button
+                  type="button"
+                  key={option.value}
+                  role="option"
+                  aria-selected={active}
+                  data-active={active || undefined}
+                  className="fd-tweaks-select-option"
+                  onClick={() => {
+                    onChange(option.value);
+                    setIsOpen(false);
+                  }}
+                >
+                  <span className="fd-tweaks-select-option-dot" aria-hidden="true" />
+                  <span className="fd-tweaks-select-option-label">{option.label}</span>
+                </button>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+
+interface TweaksDialogProps {
+  open: boolean;
+  onClose: () => void;
+  mode: TweaksMode;
+  knobs: ReadonlyArray<TweaksKnob>;
+  fontOptions: ReadonlyArray<{ label: string; value: string }>;
+  state: TweaksState;
+  onPatch: (patch: Partial<TweaksState>) => void;
+  onReset: () => void;
+  title: string;
+}
+
+function parseRadiusPx(raw: string | undefined): number {
+  if (!raw) return 8;
+  const matchResult = raw.match(/^([\d.]+)(px|rem)?$/);
+  if (!matchResult) return 8;
+  const numericValue = Number(matchResult[1]);
+  if (Number.isNaN(numericValue)) return 8;
+  return matchResult[2] === "rem" ? Math.round(numericValue * 16) : Math.round(numericValue);
+}
+
+function TweaksDialog({
+  open,
+  onClose,
+  mode,
+  knobs,
+  fontOptions,
+  state,
+  onPatch,
+  onReset,
+  title,
+}: TweaksDialogProps) {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const [mounted, setMounted] = useState(false);
+  const [side, setSide] = useState<"left" | "right">(state.dialogSide ?? "right");
+  const [dragX, setDragX] = useState(0);
+  const dragRef = useRef({ startX: 0, active: false });
+  const [ tocInvisibe, setTocInvisible ] = useState(false);
+  const [ sidebarInvisible, setSidebarInvisible ] = useState(false);
+
+  useEffect(() => {
+    const windowWidth = window?.matchMedia("(min-width: 1200px)")
+    setTocInvisible(!windowWidth.matches)
+
+    const handler = (e: MediaQueryListEvent) => setTocInvisible(!e.matches)
+    windowWidth.addEventListener("change", handler)
+
+    return () => {
+        windowWidth.removeEventListener("change", handler)
+    }
+  }, [])
+
+  useEffect(() => {
+    const windowWidth = window?.matchMedia("(min-width: 767px)")
+    setSidebarInvisible(!windowWidth.matches)
+
+    const handler = (e: MediaQueryListEvent) => setSidebarInvisible(!e.matches)
+    windowWidth.addEventListener("change", handler)
+
+    return () => {
+        windowWidth.removeEventListener("change", handler)
+    }
+  }, [])
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  useEffect(() => {
+    setSide(state.dialogSide ?? "right");
+  }, [state.dialogSide]);
+
+  const DRAG_SNAP_THRESHOLD = 30;
+
+  function onHeaderPointerDown(e: React.PointerEvent) {
+    if ((e.target as HTMLElement).closest(".fd-tweaks-close")) return;
+    dragRef.current = { startX: e.clientX, active: true };
+    setDragX(0);
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+  }
+
+  function onHeaderPointerMove(e: React.PointerEvent) {
+    if (!dragRef.current.active) return;
+    setDragX(e.clientX - dragRef.current.startX);
+  }
+
+  function onHeaderPointerUp(e: React.PointerEvent) {
+    if (!dragRef.current.active) return;
+    dragRef.current.active = false;
+    const dist = e.clientX - dragRef.current.startX;
+    if (Math.abs(dist) > DRAG_SNAP_THRESHOLD) {
+      const newSide: "left" | "right" = dist < 0 ? "left" : "right";
+      if (newSide !== side) {
+        setSide(newSide);
+        onPatch({ dialogSide: newSide });
+      }
+    }
+    setDragX(0);
+  }
+
+  useEffect(() => {
+    if (!open) return;
+    function onKey(e: KeyboardEvent) {
+      if (e.key === "Escape") onClose();
+    }
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+
+  // Click outside the dialog closes it. 
+  useEffect(() => {
+    if (!open) return;
+
+    let attached = false;
+    function onPointer(e: MouseEvent) {
+      const target = e.target as Element | null;
+      if (!target || !dialogRef.current) return;
+      if (dialogRef.current.contains(target)) return;
+      if (target.closest?.(".fd-tweaks-trigger")) return;
+      onClose();
+    }
+
+    const t = window.setTimeout(() => {
+      attached = true;
+      document.addEventListener("mousedown", onPointer);
+    }, 0);
+    return () => {
+      window.clearTimeout(t);
+      if (attached) document.removeEventListener("mousedown", onPointer);
+    };
+  }, [open, onClose]);
+
+  if (!mounted || !open) return null;
+
+  const radiusPx = parseRadiusPx(state.radius);
+
+  const node = (
+    <div className="fd-tweaks-backdrop" role="presentation">
+      <div
+        ref={dialogRef}
+        className="fd-tweaks-dialog"
+        role="dialog"  
+        aria-modal="true"
+        aria-label={title}
+        data-side={side}
+        style={dragX !== 0 ? { transform: `translateX(${dragX}px)`, transition: "none" } : undefined}
+      >
+        <div
+          className="fd-tweaks-header"
+          onPointerDown={onHeaderPointerDown}
+          onPointerMove={onHeaderPointerMove}
+          onPointerUp={onHeaderPointerUp}
+          onPointerCancel={onHeaderPointerUp}
+        >
+          <span className="fd-tweaks-title">{title}</span>
+          <button
+            type="button"
+            className="fd-tweaks-reset"
+            onClick={onReset}
+            onPointerDown={(e) => e.stopPropagation()}
+          >
+            Reset
+          </button>
+          <button
+            type="button"
+            className="fd-tweaks-close"
+            aria-label={`Close ${title}`}
+            onClick={onClose}
+            onPointerDown={(e) => e.stopPropagation()}
+          >
+            <CloseIcon />
+          </button>
+        </div>
+        <div className="fd-tweaks-body">
+          {knobs.includes("color") && (
+            <TweaksColorRow value={state.primary} onChange={(primary) => onPatch({ primary })} />
+          )}
+          {knobs.includes("density") && (
+            <TweaksChipGroup<TweaksDensity>
+              label="Density"
+              value={state.density ?? "comfortable"}
+              options={DENSITY_OPTIONS}
+              onChange={(density) => onPatch({ density })}
+            />
+          )}
+          {knobs.includes("radius") && (
+            <TweaksSlider
+              label="Border radius"
+              value={radiusPx}
+              min={0}
+              max={16}
+              step={2}
+              format={(v) => `${v}px`}
+              onChange={(v) => onPatch({ radius: `${v}px` })}
+            />
+          )}
+          {knobs.includes("preset") && (
+            <TweaksSelect<TweaksPresetKey>
+              label="Theme preset"
+              value={state.preset ?? ""}
+              options={PRESET_OPTIONS}
+              onChange={(preset) => onPatch({ preset })}
+            />
+          )}
+          {knobs.includes("font-family") && (
+            <TweaksSelect<string>
+              label="Font"
+              value={
+                fontOptions.find((o) => o.value === state.fontFamily)?.value ?? ""
+              }
+              options={fontOptions}
+              onChange={(fontFamily) => onPatch({ fontFamily })}
+            />
+          )}
+          {mode === "author" && (
+            <>
+              <div className="fd-tweaks-section-divider" role="separator">
+                <span className="fd-tweaks-section-label">Tokens</span>
+              </div>
+              <div className="fd-tweaks-color-grid">
+                {TWEAKS_COLOR_KEYS.map((key) => (
+                  <TweaksHexColorRow
+                    key={key}
+                    label={COLOR_KEY_LABELS[key]}
+                    value={state.colors?.[key]}
+                    fallback={DEFAULT_FALLBACKS[key]}
+                    onChange={(next) =>
+                      onPatch({ colors: { ...state.colors, [key]: next } })
+                    }
+                  />
+                ))}
+              </div>
+              <div className="fd-tweaks-section-divider" role="separator">
+                <span className="fd-tweaks-section-label">Layout</span>
+              </div>
+              <TweaksSlider
+                label="Sidebar width"
+                value={parsePxWidth(state.sidebarWidth, 280)}
+                min={200}
+                max={400}
+                step={4}
+                format={(v) => `${v}px`}
+                onChange={(v) => onPatch({ sidebarWidth: `${v}px` })}
+                disabled={sidebarInvisible}
+              />
+              <TweaksSlider
+                label="Content width"
+                value={parsePxWidth(state.contentWidth, 768)}
+                min={560}
+                max={1100}
+                step={8}
+                format={(v) => `${v}px`}
+                onChange={(v) => onPatch({ contentWidth: `${v}px` })}
+              />
+              <TweaksSlider
+                label="TOC width"
+                value={parsePxWidth(state.tocWidth , 224)}
+                min={160}
+                max={320}
+                step={4}
+                format={(v) => `${v}px`}
+                onChange={(v) => onPatch({ tocWidth: `${window.innerWidth < 1200 ? 0 : v}px` })}
+                disabled={tocInvisibe}
+              />
+              {!isPristineState(state) && (
+                <>
+                  <div className="fd-tweaks-section-divider" role="separator">
+                    <span className="fd-tweaks-section-label">Export</span>
+                  </div>
+                  <TweaksCodeExport state={state} />
+                </>
+              )}
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+
+  return createPortal(node, document.body);
+}
+
+interface TweaksTriggerProps {
+  variant: "sidebar" | "floating";
+  label: string;
+  open: boolean;
+  onClick: () => void;
+  fallback?: boolean;
+}
+
+function TweaksTrigger({ variant, label, open, onClick, fallback }: TweaksTriggerProps) {
+  return (
+    <button
+      type="button"
+      className={`fd-tweaks-trigger fd-tweaks-trigger-${variant}`}
+      data-open={open || undefined}
+      data-fallback={fallback || undefined}
+      aria-expanded={open}
+      aria-label={open ? `Hide ${label}` : label}
+      onClick={onClick}
+    >
+      <SettingsIcon />
+      <span className="fd-tweaks-trigger-label">{open ? `Hide ${label}` : label}</span>
+    </button>
+  );
+}
+
+let openState = false;
+const openListeners = new Set<(open: boolean) => void>();
+
+function setTweaksOpen(open: boolean) {
+  if (open === openState) return;
+  openState = open;
+  openListeners.forEach((cb) => cb(open));
+}
+
+function useTweaksOpen(): [boolean, (open: boolean) => void] {
+  const [open, setOpen] = useState(openState);
+  useEffect(() => {
+    const cb = (v: boolean) => setOpen(v);
+    openListeners.add(cb);
+    return () => {
+      openListeners.delete(cb);
+    };
+  }, []);
+  return [open, setTweaksOpen];
+}
+
+export interface TweaksSidebarTriggerProps {
+  label?: string;
+}
+
+export function TweaksSidebarTrigger({ label = "Tweaks" }: TweaksSidebarTriggerProps) {
+  const [mounted, setMounted] = useState(false);
+  const [open, setOpen] = useTweaksOpen();
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+  if (!mounted) return null;
+  return (
+    <TweaksTrigger
+      variant="sidebar"
+      label={label}
+      open={open}
+      onClick={() => setOpen(!open)}
+    />
+  );
+}
+
+// ─── Auto-portal trigger (framework default) ──────────────────────────
+//
+// Finds the page's `[data-theme-toggle]` element (fumadocs-ui's default
+// dark/light pill and our `LocaleThemeControl`) and portals the trigger
+// in as a sibling immediately before it, so the visual result is:
+//   [ Tweaks ] [ ☀ ☾ ]
+// regardless of which sidebar slot the host theme uses for the toggle.
+
+const PORTAL_CONTAINER_CLASS = "fd-tweaks-portal-slot";
+
+export interface TweaksAutoPortalTriggerProps {
+  label?: string;
+}
+
+export function TweaksAutoPortalTrigger({ label = "Tweaks" }: TweaksAutoPortalTriggerProps) {
+  const [container, setContainer] = useState<HTMLElement | null>(null);
+  const [open, setOpen] = useTweaksOpen();
+
+  useEffect(() => {
+    function tryAttach(): boolean {
+      const toggle = document.querySelector<HTMLElement>("[data-theme-toggle]");
+      if (!toggle || !toggle.parentElement) return false;
+
+      // If injected, setContainer and bail, else create and inject slot
+      const slot = document.querySelector<HTMLElement>(`.${PORTAL_CONTAINER_CLASS}`)
+      if (slot) {
+        // Refresh radius in case the host theme switched.
+        const radius = window.getComputedStyle(toggle).borderRadius || "0px";
+        slot.style.setProperty("--fd-tweaks-trigger-radius-match", radius);
+        setContainer(slot);
+        return true;
+      } else {
+        const computed = window.getComputedStyle(toggle);
+        const radius = computed.borderRadius || "0px";
+
+        const slot = document.createElement("span");
+        slot.className = PORTAL_CONTAINER_CLASS;
+        slot.style.display = "inline-flex"; 
+        slot.style.alignItems = "center";
+        slot.style.setProperty("--fd-tweaks-trigger-radius-match", radius);
+      
+        toggle.before(slot);
+
+        setContainer(slot);
+        return true;
+    }
+    }
+
+    // Initial attach attempt.
+    tryAttach();
+
+    // Permanent observer: check if slot exists on every subtree mutation. Reattach if not exists
+    const observer = new MutationObserver(() => {
+      const toggle = document.querySelector<HTMLElement>("[data-theme-toggle]");
+      if (!toggle || !toggle.parentElement) return;
+      if (document.querySelector(`.${PORTAL_CONTAINER_CLASS}`)) return;
+      tryAttach();
+    });
+    observer.observe(document.body, { childList: true, subtree: true });
+
+    return () => {
+      observer.disconnect();
+      // Remove any slots on unmount
+      const slots = document.querySelectorAll<HTMLElement>(`.${PORTAL_CONTAINER_CLASS}`);
+      slots.forEach((slot) => {
+        const parent = slot.parentElement;
+        parent?.removeChild(slot);
+      });
+    };
+  }, []);
+
+  if (!container) return null;
+
+  return createPortal(
+    <TweaksTrigger
+      variant="sidebar"
+      label={label}
+      open={open}
+      onClick={() => setOpen(!open)}
+    />,
+    container,
+  );
+}
+
+// ─── Public composite — dialog + (optional) floating FAB ───────────────
+
+export type TweaksMode = "reader" | "author";
+
+interface TweaksControlProps {
+  /**
+   * Dialog power level.
+   * - `"reader"`: limited knobs (accent, density, radius, preset, font).
+   * - `"author"`: full knob set (all 16 colors, sidebar/TOC style, layout) + code export.
+   *
+   * @default "reader"
+   */
+  mode?: TweaksMode;
+  knobs?: ReadonlyArray<TweaksKnob>;
+  position?: "sidebar-footer" | "floating" | "both" | "manual";
+  label?: string;
+  storageKey?: string;
+  persist?: boolean;
+  fontOptions?: ReadonlyArray<{ label: string; value: string }>;
+  onApply?: (state: Record<string, string>) => void | Promise<void>;
+}
+
+function stateToRecord(s: TweaksState): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (s.preset) out.preset = s.preset;
+  if (s.primary) out.primary = s.primary;
+  if (s.radius) out.radius = s.radius;
+  if (s.density) out.density = s.density;
+  if (s.fontFamily) out.fontFamily = s.fontFamily;
+  return out;
+}
+
+export function TweaksControl({
+  mode = "reader",
+  knobs = DEFAULT_KNOBS,
+  position = "both",
+  label = "Tweaks",
+  storageKey = TWEAKS_DEFAULT_STORAGE_KEY,
+  persist = true,
+  fontOptions = TWEAKS_DEFAULT_FONT_OPTIONS,
+  onApply,
+}: TweaksControlProps) {
+  const [mounted, setMounted] = useState(false);
+  const [open, setOpen] = useTweaksOpen();
+  const [state, setState] = useState<TweaksState>({});
+
+  // Hydrate from localStorage after mount (the FOUC script already applied
+  // saved tweaks to the DOM pre-paint; this just syncs React state).
+  useEffect(() => {
+    const saved = readSavedTweaks(storageKey);
+    if (saved) {
+      setState(saved);
+      applyTweaks(saved);
+    }
+    setMounted(true);
+  }, [storageKey]);
+
+  const patch = useCallback(
+    (next: Partial<TweaksState>) => {
+      setState((prev) => {
+        const merged: TweaksState = { ...prev, ...next };
+        applyTweaks(merged);
+        if (persist) writeSavedTweaks(merged, storageKey);
+        void onApply?.(stateToRecord(merged));
+        return merged;
+      });
+    },
+    [onApply, persist, storageKey],
+  );
+
+  const reset = useCallback(() => {
+    setState({});
+    resetTweaks();
+    if (persist) clearSavedTweaks(storageKey);
+    void onApply?.({});
+  }, [onApply, persist, storageKey]);
+
+  const showFloating = position === "floating" || position === "both";
+  const floatingIsFallback = position === "both";
+
+  if (!mounted) return null;
+
+  return (
+    <>
+      {showFloating && (
+        <TweaksTrigger
+          variant="floating"
+          label={label}
+          open={open}
+          onClick={() => setOpen(!open)}
+          fallback={floatingIsFallback}
+        />
+      )}
+      <TweaksDialog
+        open={open}
+        onClose={() => setOpen(false)}
+        mode={mode}
+        knobs={knobs}
+        fontOptions={fontOptions}
+        state={state}
+        onPatch={patch}
+        onReset={reset}
+        title={mode === "author" ? `${label} · Author` : label}
+      />
+    </>
+  );
+}
+
+// ─── FOUC prevention script (renders an inline <script> in <head>) ─────
+
+export function TweaksFoucScript({
+  storageKey = TWEAKS_DEFAULT_STORAGE_KEY,
+}: {
+  storageKey?: string;
+}) {
+  // Self-contained IIFE that reads localStorage and writes inline styles to
+  // documentElement before paint
+  return <script dangerouslySetInnerHTML={{ __html: buildFoucScript(storageKey) }} />;
+}
diff --git a/packages/fumadocs/src/tweaks-runtime.ts b/packages/fumadocs/src/tweaks-runtime.ts
new file mode 100644
index 00000000..26fe9c70
--- /dev/null
+++ b/packages/fumadocs/src/tweaks-runtime.ts
@@ -0,0 +1,602 @@
+/**
+ * Tweaks runtime — preset bundle, persistence, and FOUC prevention.
+ *
+ * The Tweaks dialog calls into this module to apply visual changes to
+ * `document.documentElement` and persist them across reloads.
+ * `buildFoucScript()` returns an inline `<script>` body that re-applies
+ * saved selections before the browser paints, so there is no flash of the
+ * un-tweaked theme on the next page load.
+ *
+ * Pure utilities — no React, no JSX. Safe to import from server and client.
+ */
+
+export type TweaksPresetKey =
+  | "default"
+  | "colorful"
+  | "darksharp"
+  | "pixel-border"
+  | "shiny"
+  | "ledger"
+  | "darkbold";
+
+export type TweaksDensity = "compact" | "comfortable" | "roomy";
+
+/**
+ * Author-mode color tokens. These map 1:1 to fumadocs' `--color-fd-*`
+ * variables; the reader-mode `primary` field is a shortcut that also
+ * sets `--color-fd-ring`.
+ */
+export type TweaksColorKey =
+  | "primary"
+  | "primaryForeground"
+  | "background"
+  | "foreground"
+  | "muted"
+  | "mutedForeground"
+  | "border"
+  | "card"
+  | "cardForeground"
+  | "accent"
+  | "accentForeground"
+  | "secondary"
+  | "secondaryForeground"
+  | "popover"
+  | "popoverForeground"
+  | "ring";
+
+export const TWEAKS_COLOR_KEYS: ReadonlyArray<TweaksColorKey> = [
+  "primary",
+  "primaryForeground",
+  "background",
+  "foreground",
+  "muted",
+  "mutedForeground",
+  "border",
+  "card",
+  "cardForeground",
+  "accent",
+  "accentForeground",
+  "secondary",
+  "secondaryForeground",
+  "popover",
+  "popoverForeground",
+  "ring",
+];
+
+const COLOR_KEY_TO_CSS_VAR: Record<TweaksColorKey, string> = {
+  primary: "--color-fd-primary",
+  primaryForeground: "--color-fd-primary-foreground",
+  background: "--color-fd-background",
+  foreground: "--color-fd-foreground",
+  muted: "--color-fd-muted",
+  mutedForeground: "--color-fd-muted-foreground",
+  border: "--color-fd-border",
+  card: "--color-fd-card",
+  cardForeground: "--color-fd-card-foreground",
+  accent: "--color-fd-accent",
+  accentForeground: "--color-fd-accent-foreground",
+  secondary: "--color-fd-secondary",
+  secondaryForeground: "--color-fd-secondary-foreground",
+  popover: "--color-fd-popover",
+  popoverForeground: "--color-fd-popover-foreground",
+  ring: "--color-fd-ring",
+};
+
+export interface TweaksState {
+  // Reader-mode knobs
+  preset?: TweaksPresetKey;
+  primary?: string;
+  radius?: string;
+  density?: TweaksDensity;
+  fontFamily?: string;
+
+  // Author-mode extras
+  /** Per-token color overrides; takes precedence over `primary`. */
+  colors?: Partial<Record<TweaksColorKey, string>>;
+  /** Sidebar column width, e.g. `"280px"`. Writes `--fd-sidebar-width`. */
+  sidebarWidth?: string;
+  /** Content prose width, e.g. `"768px"`. Writes `--fd-content-width`. */
+  contentWidth?: string;
+  /** TOC column width, e.g. `"14rem"`. Writes `--fd-toc-width`. */
+  tocWidth?: string;
+
+  // UI preferences (don't affect theme; persisted alongside theme state for
+  // convenience so a single localStorage key holds everything reader-related)
+  /** Which side of the viewport the dialog snaps to. @default "right" */
+  dialogSide?: "left" | "right";
+}
+
+interface PresetTokens {
+  label: string;
+  primary: string;
+  primaryForeground: string;
+  background: string;
+  foreground: string;
+  muted: string;
+  mutedForeground: string;
+  border: string;
+  card: string;
+  ring: string;
+  radius: string;
+  fontSans: string;
+}
+
+/**
+ * Hand-curated token bundle for the seven presets where every color variable
+ * is fully known from the preset's TS module + its companion CSS file.
+ *
+ * Adding more presets (greentree, hardline, concrete, command-grid) is a
+ * mechanical lift — drop their `:root` declarations into a new entry here.
+ */
+export const TWEAKS_PRESET_BUNDLE: Record<TweaksPresetKey, PresetTokens> = {
+  default: {
+    label: "Default",
+    primary: "#6366f1",
+    primaryForeground: "#ffffff",
+    background: "#0c0c0c",
+    foreground: "#fafafa",
+    muted: "#262626",
+    mutedForeground: "#a3a3a3",
+    border: "#262626",
+    card: "#141414",
+    ring: "#6366f1",
+    radius: "0.5rem",
+    fontSans: "Inter, system-ui, sans-serif",
+  },
+  colorful: {
+    label: "Colorful",
+    primary: "hsl(45, 100%, 60%)",
+    primaryForeground: "hsl(0, 0%, 5%)",
+    background: "hsl(0, 0%, 7.04%)",
+    foreground: "hsl(0, 0%, 92%)",
+    muted: "hsl(0, 0%, 12.9%)",
+    mutedForeground: "hsla(0, 0%, 70%, 0.8)",
+    border: "hsla(0, 0%, 40%, 20%)",
+    card: "hsl(0, 0%, 9.8%)",
+    ring: "hsl(45, 90%, 55%)",
+    radius: "0.75rem",
+    fontSans: "Inter, system-ui, sans-serif",
+  },
+  darksharp: {
+    label: "Darksharp",
+    primary: "#fafaf9",
+    primaryForeground: "#0c0a09",
+    background: "#000000",
+    foreground: "#fafaf9",
+    muted: "#1c1917",
+    mutedForeground: "#a8a29e",
+    border: "#292524",
+    card: "#0c0a09",
+    ring: "#fafaf9",
+    radius: "0.2rem",
+    fontSans: "Inter, system-ui, sans-serif",
+  },
+  "pixel-border": {
+    label: "Pixel Border",
+    primary: "#fbfbfa",
+    primaryForeground: "#0a0a0a",
+    background: "#050505",
+    foreground: "#fafafa",
+    muted: "#262626",
+    mutedForeground: "#8c8c8c",
+    border: "#262626",
+    card: "#0d0d0d",
+    ring: "#fbfbfa",
+    radius: "0px",
+    fontSans: "Inter, system-ui, sans-serif",
+  },
+  shiny: {
+    label: "Shiny",
+    primary: "hsl(256, 100%, 72%)",
+    primaryForeground: "#ffffff",
+    background: "hsl(240, 10%, 7%)",
+    foreground: "hsl(0, 0%, 95%)",
+    muted: "hsl(240, 5%, 16%)",
+    mutedForeground: "hsl(240, 4%, 58%)",
+    border: "hsl(240, 5%, 18%)",
+    card: "hsl(240, 8%, 10%)",
+    ring: "hsl(256, 85%, 65%)",
+    radius: "0.75rem",
+    fontSans: "Inter, system-ui, sans-serif",
+  },
+  ledger: {
+    label: "Ledger",
+    primary: "#5f6cf6",
+    primaryForeground: "#ffffff",
+    background: "#f6f8fb",
+    foreground: "#30364a",
+    muted: "#eef3fb",
+    mutedForeground: "#677187",
+    border: "#dbe3ef",
+    card: "#ffffff",
+    ring: "#5f6cf6",
+    radius: "0.5rem",
+    fontSans: "Inter, system-ui, sans-serif",
+  },
+  darkbold: {
+    label: "DarkBold",
+    primary: "#ffffff",
+    primaryForeground: "#000000",
+    background: "#0a0a0a",
+    foreground: "#ededed",
+    muted: "#1a1a1a",
+    mutedForeground: "#888888",
+    border: "#333333",
+    card: "#111111",
+    ring: "#ffffff",
+    radius: "0.5rem",
+    fontSans: "Geist, system-ui, sans-serif",
+  },
+};
+
+export const TWEAKS_ACCENT_SWATCHES: ReadonlyArray<{ value: string; name: string }> = [
+  { value: "#ef4444", name: "Red" },
+  { value: "#f97316", name: "Orange" },
+  { value: "#eab308", name: "Yellow" },
+  { value: "#22c55e", name: "Green" },
+  { value: "#14b8a6", name: "Teal" },
+  { value: "#3b82f6", name: "Blue" },
+  { value: "#6366f1", name: "Indigo" },
+  { value: "#8b5cf6", name: "Violet" },
+  { value: "#ec4899", name: "Pink" },
+  { value: "#fafafa", name: "White" },
+];
+
+export const TWEAKS_DENSITY_SCALE: Record<TweaksDensity, string> = {
+  compact: "0.9",
+  comfortable: "1",
+  roomy: "1.1",
+};
+
+export const TWEAKS_DEFAULT_STORAGE_KEY = "fd:tweaks:v1";
+
+/**
+ * Default font options use generic family stacks that are guaranteed to be
+ * different visually regardless of which fonts the host site loaded. If you
+ * want named fonts (Inter, Geist, …) provide them via `TweaksConfig.fontOptions`
+ * — but only after ensuring the host actually loads them, otherwise the
+ * browser silently falls back to the same system font and the change is
+ * invisible.
+ */
+export const TWEAKS_DEFAULT_FONT_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [
+  { label: "System", value: "system-ui, -apple-system, sans-serif" },
+  { label: "Sans", value: "ui-sans-serif, system-ui, sans-serif" },
+  { label: "Serif", value: "ui-serif, Georgia, 'Times New Roman', serif" },
+  { label: "Mono", value: "ui-monospace, Menlo, Monaco, monospace" },
+];
+
+export function readSavedTweaks(storageKey: string = TWEAKS_DEFAULT_STORAGE_KEY): TweaksState | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed && typeof parsed === "object") return parsed as TweaksState;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSavedTweaks(
+  state: TweaksState,
+  storageKey: string = TWEAKS_DEFAULT_STORAGE_KEY,
+): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(storageKey, JSON.stringify(state));
+  } catch {
+    // silently ignore
+  }
+}
+
+/** Remove the persisted tweaks entry. No-op on SSR. */
+export function clearSavedTweaks(storageKey: string = TWEAKS_DEFAULT_STORAGE_KEY): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(storageKey);
+  } catch {
+    // noop
+  }
+}
+
+const RADIUS_OVERRIDE_STYLE_ID = "fd-tweaks-radius-override";
+const LAYOUT_OVERRIDE_STYLE_ID = "fd-tweaks-layout-override";
+const FOUC_VARS_STYLE_ID = "fd-tweaks-vars";
+
+/**
+ * Apply token-level tweaks (preset colors, radius, font scale, font family,
+ * per-token color overrides) via a single `<style id="fd-tweaks-vars">`
+ * element in `<head>`, rather than mutating inline styles on `<html>` /
+ * `<body>`.
+ *
+ * Why: writing inline styles on the documentElement before React hydrates
+ * creates a server/client attribute mismatch that aborts hydration on the
+ * entire tree (every onClick handler fails to attach). A fresh `<style>`
+ * element appended to `<head>` isn't part of React's SSR tree, so it
+ * doesn't show up in the hydration diff. The cascade resolves the
+ * variables identically either way.
+ *
+ * Targets both `:root` and `body` because Next.js's `next/font` className
+ * redefines `--fd-font-sans` on `<body>`; rules on `:root` alone would lose
+ * the cascade at body scope. `!important` is added so we beat any
+ * className-scoped definitions (which lack `!important` themselves).
+ */
+function applyFoucVars(state: TweaksState): void {
+  if (typeof document === "undefined") return;
+
+  const declarations: string[] = [];
+
+  if (state.preset && state.preset in TWEAKS_PRESET_BUNDLE) {
+    const p = TWEAKS_PRESET_BUNDLE[state.preset];
+    declarations.push(`--color-fd-primary:${p.primary}`);
+    declarations.push(`--color-fd-primary-foreground:${p.primaryForeground}`);
+    declarations.push(`--color-fd-background:${p.background}`);
+    declarations.push(`--color-fd-foreground:${p.foreground}`);
+    declarations.push(`--color-fd-muted:${p.muted}`);
+    declarations.push(`--color-fd-muted-foreground:${p.mutedForeground}`);
+    declarations.push(`--color-fd-border:${p.border}`);
+    declarations.push(`--color-fd-card:${p.card}`);
+    declarations.push(`--color-fd-ring:${p.ring}`);
+    declarations.push(`--radius:${p.radius}`);
+    declarations.push(`--fd-font-sans:${p.fontSans}`);
+  }
+  if (state.primary) {
+    declarations.push(`--color-fd-primary:${state.primary}`);
+    declarations.push(`--color-fd-ring:${state.primary}`);
+  }
+  if (state.radius) {
+    declarations.push(`--radius:${state.radius}`);
+  }
+  if (state.density) {
+    declarations.push(`--fd-font-scale:${TWEAKS_DENSITY_SCALE[state.density]}`);
+  }
+  if (state.fontFamily) {
+    declarations.push(`--fd-font-sans:${state.fontFamily}`);
+  }
+  if (state.colors) {
+    for (const key of TWEAKS_COLOR_KEYS) {
+      const value = state.colors[key];
+      if (value) declarations.push(`${COLOR_KEY_TO_CSS_VAR[key]}:${value}`);
+    }
+  }
+
+  let style = document.getElementById(FOUC_VARS_STYLE_ID) as HTMLStyleElement | null;
+  if (!style) {
+    style = document.createElement("style");
+    style.id = FOUC_VARS_STYLE_ID;
+    document.head.appendChild(style);
+  }
+
+  style.textContent =
+    declarations.length === 0
+      ? ""
+      : `:root, body { ${declarations.map((d) => d + " !important").join("; ")}; }`;
+}
+
+function clearFoucVars(): void {
+  if (typeof document === "undefined") return;
+  const style = document.getElementById(FOUC_VARS_STYLE_ID);
+  if (style) style.remove();
+}
+
+/**
+ * Most preset CSS files hardcode `border-radius` per element rather than
+ * referencing `var(--radius)`, so setting --radius alone has no visible
+ * effect. We additionally emit a `<style>` block that overrides common
+ * rounded UI elements with the chosen value.
+ *
+ * The override targets framework-shipped element classes; theme authors
+ * who want their custom elements to participate can use `var(--radius)`
+ * in their own CSS.
+ */
+function applyRadiusOverride(value: string): void {
+  if (typeof document === "undefined") return;
+  let style = document.getElementById(RADIUS_OVERRIDE_STYLE_ID) as HTMLStyleElement | null;
+  if (!style) {
+    style = document.createElement("style");
+    style.id = RADIUS_OVERRIDE_STYLE_ID;
+    document.head.appendChild(style);
+  }
+  style.textContent =
+    `:where(.fd-page-action-btn, .fd-page-action-menu, .fd-page-action-menu-item, ` +
+    `.fd-feedback-input, .fd-feedback-submit, .fd-feedback-choice, ` +
+    `.fd-page-nav-card, .fd-prompt, .fd-prompt-body, .fd-prompt-action-btn, ` +
+    `.fd-prompt-menu, .fd-prompt-menu-item, .fd-ai-dialog, .fd-ai-floating-btn, ` +
+    `.fd-ai-suggestion, .fd-ai-input-wrap, .fd-tweaks-dialog, .fd-tweaks-swatch, ` +
+    `.fd-tweaks-chip, .fd-tweaks-select, .fd-tweaks-reset, .fd-tweaks-chips) ` +
+    `{ border-radius: ${value} !important; }`;
+}
+
+function clearRadiusOverride(): void {
+  if (typeof document === "undefined") return;
+  const style = document.getElementById(RADIUS_OVERRIDE_STYLE_ID);
+  if (style) style.remove();
+}
+
+/**
+ * Override layout dimensions at runtime. The framework's `LayoutStyle`
+ * SSR-emits these on `:root` and (for sidebar) on `[style*="fd-sidebar-col"]`
+ * with `!important`. Additionally, fumadocs-ui's sidebar placeholder gets a
+ * Tailwind arbitrary class like `md:layout:[--fd-sidebar-width:268px]` that
+ * sets the variable on that specific element — which beats any cascade from
+ * `documentElement`. So we have to inject an `!important` override that
+ * targets the same elements.
+ *
+ * TOC and sidebar widths are responsive: TOC hides below 1200px, sidebar
+ * hides below 767px. A matchMedia listener re-applies the override when
+ * the viewport crosses those thresholds.
+ */
+
+let lastLayoutOptions: { sidebarWidth?: string; contentWidth?: string; tocWidth?: string } | null = null;
+let layoutMediaCleanup: (() => void) | null = null;
+
+function applyLayoutOverride(options: {
+  sidebarWidth?: string;
+  contentWidth?: string;
+  tocWidth?: string;
+}): void {
+  if (typeof document === "undefined") return;
+
+  lastLayoutOptions = options;
+
+  let style = document.getElementById(LAYOUT_OVERRIDE_STYLE_ID) as HTMLStyleElement | null;
+  if (!style) {
+    style = document.createElement("style");
+    style.id = LAYOUT_OVERRIDE_STYLE_ID;
+    document.head.appendChild(style);
+  }
+  const rules: string[] =           [];
+  if (options.sidebarWidth) {
+    const sidebarVisible = window.matchMedia("(min-width: 767px)").matches;
+    if (sidebarVisible) {
+      rules.push(
+        `:root, [data-sidebar-placeholder], [style*="fd-sidebar-col"] {` +
+          ` --fd-sidebar-width: ${options.sidebarWidth} !important;` +
+          ` --fd-sidebar-col: ${options.sidebarWidth} !important;` +
+          ` }`,
+      );
+    }
+  }
+  if (options.contentWidth) {
+    rules.push(
+      `:root { --fd-content-width: ${options.contentWidth} !important; }`,
+    );
+    rules.push(
+      `article#nd-page, article#nd-page > .prose {` +
+        ` max-width: ${options.contentWidth} !important;` +
+        ` }`,
+    );
+  }
+  if (options.tocWidth) {
+    const tocVisible = window.matchMedia("(min-width: 1200px)").matches;
+    if (tocVisible) {
+      rules.push(
+        `:root, [style*="--fd-toc-width"], [style*="fd-sidebar-col"] {` +
+          ` --fd-toc-width: ${options.tocWidth} !important;` +
+          ` }`,
+      );
+    }
+  }
+  style.textContent = rules.join("\n");
+
+  setupLayoutMediaListeners();
+}
+
+function setupLayoutMediaListeners(): void {
+  if (typeof window === "undefined" || layoutMediaCleanup) return;
+
+  const tocMediaQuery = window.matchMedia("(min-width: 1200px)");
+  const sidebarMediaQuery = window.matchMedia("(min-width: 767px)");
+
+  const handler = () => {
+    if (lastLayoutOptions) applyLayoutOverride(lastLayoutOptions);
+  };
+
+  tocMediaQuery.addEventListener("change", handler);
+  sidebarMediaQuery.addEventListener("change", handler);
+
+  layoutMediaCleanup = () => {
+    tocMediaQuery.removeEventListener("change", handler);
+    sidebarMediaQuery.removeEventListener("change", handler);
+  };
+}
+
+function clearLayoutOverride(): void {
+  if (typeof document === "undefined") return;
+  const style = document.getElementById(LAYOUT_OVERRIDE_STYLE_ID);
+  if (style) style.remove();
+  lastLayoutOptions = null;
+  if (layoutMediaCleanup) {
+    layoutMediaCleanup();
+    layoutMediaCleanup = null;
+  }
+}
+
+/**
+ * Apply the given tweaks state. Writes a single `<style id="fd-tweaks-vars">`
+ * element to `<head>` (no inline-style mutation on `<html>` / `<body>`), so
+ * applying tweaks before React hydrates does not produce a hydration
+ * mismatch. No-op on SSR.
+ */
+export function applyTweaks(state: TweaksState): void {
+  if (typeof document === "undefined") return;
+
+  applyFoucVars(state);
+
+  if (state.radius) {
+    applyRadiusOverride(state.radius);
+  }
+  if (state.sidebarWidth || state.contentWidth || state.tocWidth) {
+    applyLayoutOverride({
+      sidebarWidth: state.sidebarWidth,
+      contentWidth: state.contentWidth,
+      tocWidth: state.tocWidth,
+    });
+  }
+}
+
+/**
+ * Remove every CSS variable Tweaks may have set, reverting to the
+ * SSR-applied preset values.
+ */
+export function resetTweaks(): void {
+  if (typeof document === "undefined") return;
+  clearFoucVars();
+  clearRadiusOverride();
+  clearLayoutOverride();
+}
+
+/**
+ * Inline `<script>` body that applies saved tweaks before the browser paints —
+ * the same trick `next-themes` uses for dark-mode FOUC prevention.
+ *
+ * Mirrors `applyFoucVars` exactly: builds a list of declarations from the
+ * saved state and appends a single `<style id="fd-tweaks-vars">` element to
+ * `<head>`. We can't mutate inline styles on `<html>` / `<body>` here because
+ * those attributes would differ between server render and client paint,
+ * triggering a React hydration mismatch that aborts hydration for the entire
+ * tree (every onClick handler stops working). A `<style>` element appended to
+ * `<head>` isn't part of React's hydration diff.
+ */
+export function buildFoucScript(storageKey: string = TWEAKS_DEFAULT_STORAGE_KEY): string {
+  const bundle = JSON.stringify(TWEAKS_PRESET_BUNDLE);
+  const density = JSON.stringify(TWEAKS_DENSITY_SCALE);
+  const colorMap = JSON.stringify(COLOR_KEY_TO_CSS_VAR);
+  const key = JSON.stringify(storageKey);
+  return (
+    "(function(){try{" +
+    `var storage=localStorage.getItem(${key});if(!storage)return;` +
+    "var tweaks=JSON.parse(storage);if(!tweaks||typeof tweaks!=='object')return;" +
+    `var presets=${bundle};` +
+    `var densityMap=${density};` +
+    `var colorMap=${colorMap};` +
+    "var declarations=[];" +
+    "if(tweaks.preset&&presets[tweaks.preset]){var p=presets[tweaks.preset];" +
+    "declarations.push('--color-fd-primary:'+p.primary);" +
+    "declarations.push('--color-fd-primary-foreground:'+p.primaryForeground);" +
+    "declarations.push('--color-fd-background:'+p.background);" +
+    "declarations.push('--color-fd-foreground:'+p.foreground);" +
+    "declarations.push('--color-fd-muted:'+p.muted);" +
+    "declarations.push('--color-fd-muted-foreground:'+p.mutedForeground);" +
+    "declarations.push('--color-fd-border:'+p.border);" +
+    "declarations.push('--color-fd-card:'+p.card);" +
+    "declarations.push('--color-fd-ring:'+p.ring);" +
+    "declarations.push('--radius:'+p.radius);" +
+    "declarations.push('--fd-font-sans:'+p.fontSans);}" +
+    "if(tweaks.primary){declarations.push('--color-fd-primary:'+tweaks.primary);declarations.push('--color-fd-ring:'+tweaks.primary);}" +
+    "if(tweaks.radius){declarations.push('--radius:'+tweaks.radius);" +
+    `var radiusOverride=document.createElement('style');radiusOverride.id='${RADIUS_OVERRIDE_STYLE_ID}';` +
+    "radiusOverride.textContent=':where(.fd-page-action-btn,.fd-page-action-menu,.fd-page-action-menu-item,.fd-feedback-input,.fd-feedback-submit,.fd-feedback-choice,.fd-page-nav-card,.fd-prompt,.fd-prompt-body,.fd-prompt-action-btn,.fd-prompt-menu,.fd-prompt-menu-item,.fd-ai-dialog,.fd-ai-floating-btn,.fd-ai-suggestion,.fd-ai-input-wrap,.fd-tweaks-dialog,.fd-tweaks-swatch,.fd-tweaks-chip,.fd-tweaks-select,.fd-tweaks-reset,.fd-tweaks-chips){border-radius:'+tweaks.radius+' !important;}';" +
+    "document.head.appendChild(radiusOverride);}" +
+    "if(tweaks.density&&densityMap[tweaks.density]){declarations.push('--fd-font-scale:'+densityMap[tweaks.density]);}" +
+    "if(tweaks.fontFamily){declarations.push('--fd-font-sans:'+tweaks.fontFamily);}" +
+    "if(tweaks.colors){for(var k in tweaks.colors){if(colorMap[k]&&tweaks.colors[k]){declarations.push(colorMap[k]+':'+tweaks.colors[k]);}}}" +
+    "if(declarations.length){" +
+    `var varsStyle=document.createElement('style');varsStyle.id='${FOUC_VARS_STYLE_ID}';` +
+    "var parts=[];for(var i=0;i<declarations.length;i++){parts.push(declarations[i]+' !important');}" +
+    "varsStyle.textContent=':root, body { '+parts.join('; ')+'; }';" +
+    "document.head.appendChild(varsStyle);}" +
+    "}catch(e){}})();"
+  );
+}
diff --git a/packages/fumadocs/styles/base.css b/packages/fumadocs/styles/base.css
index ace2c80b..b90e3698 100644
--- a/packages/fumadocs/styles/base.css
+++ b/packages/fumadocs/styles/base.css
@@ -4,6 +4,9 @@
 /* Omni Command Palette — built-in search */
 @import "./omni.css";
 
+/* Tweaks dialog — runtime theme tweaker */
+@import "./tweaks.css";
+
 /* Shared base styles for all @farming-labs/theme themes.
  *
  * Typography CSS custom properties:
@@ -66,7 +69,7 @@ samp {
 
 .prose h1,
 article h1 {
-  font-size: var(--fd-h1-size, 2.25rem);
+  font-size: calc(var(--fd-h1-size, 2.25rem) * var(--fd-font-scale, 1));
   font-weight: var(--fd-h1-weight, 700);
   line-height: var(--fd-h1-line-height, 1.2);
   letter-spacing: var(--fd-h1-letter-spacing, -0.02em);
@@ -74,7 +77,7 @@ article h1 {
 
 .prose h2,
 article h2 {
-  font-size: var(--fd-h2-size, 1.5rem);
+  font-size: calc(var(--fd-h2-size, 1.5rem) * var(--fd-font-scale, 1));
   font-weight: var(--fd-h2-weight, 600);
   line-height: var(--fd-h2-line-height, 1.3);
   letter-spacing: var(--fd-h2-letter-spacing, -0.01em);
@@ -82,7 +85,7 @@ article h2 {
 
 .prose h3,
 article h3 {
-  font-size: var(--fd-h3-size, 1.25rem);
+  font-size: calc(var(--fd-h3-size, 1.25rem) * var(--fd-font-scale, 1));
   font-weight: var(--fd-h3-weight, 600);
   line-height: var(--fd-h3-line-height, 1.4);
   letter-spacing: var(--fd-h3-letter-spacing, normal);
@@ -90,7 +93,7 @@ article h3 {
 
 .prose h4,
 article h4 {
-  font-size: var(--fd-h4-size, 1.125rem);
+  font-size: calc(var(--fd-h4-size, 1.125rem) * var(--fd-font-scale, 1));
   font-weight: var(--fd-h4-weight, 600);
   line-height: var(--fd-h4-line-height, 1.4);
   letter-spacing: var(--fd-h4-letter-spacing, normal);
@@ -102,7 +105,7 @@ article h4 {
 .prose li,
 .prose td,
 article p {
-  font-size: var(--fd-body-size, 1rem);
+  font-size: calc(var(--fd-body-size, 1rem) * var(--fd-font-scale, 1));
   font-weight: var(--fd-body-weight, 400);
   line-height: var(--fd-body-line-height, 1.75);
 }
@@ -112,7 +115,7 @@ article p {
 .prose small,
 article small,
 .text-sm {
-  font-size: var(--fd-small-size, 0.875rem);
+  font-size: calc(var(--fd-small-size, 0.875rem) * var(--fd-font-scale, 1));
   font-weight: var(--fd-small-weight, 400);
   line-height: var(--fd-small-line-height, 1.5);
 }
diff --git a/packages/fumadocs/styles/tweaks.css b/packages/fumadocs/styles/tweaks.css
new file mode 100644
index 00000000..5e6817e7
--- /dev/null
+++ b/packages/fumadocs/styles/tweaks.css
@@ -0,0 +1,719 @@
+/* ─── Tweaks dialog ─────────────────────────────────────────────────
+ *
+ * Floating panel readers (and theme authors) use to live-tweak theme
+ * tokens. Visual language: frosted-glass — the dialog itself uses a
+ * translucent background with a moderate backdrop-filter blur, and
+ * interactive elements inside it use a heavier blur so the layering
+ * reads as nested glass rather than a flat surface.
+ *
+ * Variants:
+ *   .fd-tweaks-trigger-sidebar   — pill button portal-mounted next to
+ *                                  the host's [data-theme-toggle].
+ *                                  border-radius matches the toggle's
+ *                                  computed radius via
+ *                                  --fd-tweaks-trigger-radius-match.
+ *   .fd-tweaks-trigger-floating  — fixed bottom-right FAB.
+ *     [data-fallback]            — hidden at md+ when used as fallback.
+ */
+
+@keyframes fd-tweaks-slide-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px) scale(0.98);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+/* ─── Backdrop ──────────────────────────────────────────────────────── */
+
+.fd-tweaks-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  pointer-events: none;
+}
+
+/* ─── Dialog — frosted-glass panel ──────────────────────────────────── */
+
+.fd-tweaks-dialog {
+  position: fixed;
+  bottom: 1rem;
+  right: 1rem;
+  left: auto;
+  z-index: 60;
+  width: 320px;
+  max-width: calc(100vw - 2rem);
+  pointer-events: auto;
+  transition: left 220ms cubic-bezier(0.2, 0.8, 0.2, 1), right 220ms cubic-bezier(0.2, 0.8, 0.2, 1);
+
+  /* 18% opaque: enough to give the panel a tint but transparent enough
+   * for the backdrop-filter blur to be visible. Higher than ~25% makes
+   * the panel read as solid and kills the glass effect. */
+  background: color-mix(in srgb, var(--color-fd-card, var(--color-fd-background, #0a0a0a)) 18%, transparent);
+  color: var(--color-fd-foreground, #fafafa);
+  border: 1px solid color-mix(in srgb, var(--color-fd-border, rgba(255, 255, 255, 0.12)) 45%, transparent);
+  border-radius: 0.875rem;
+  /* Strong blur + saturation boost — standard frosted-glass recipe. */
+  backdrop-filter: blur(28px) saturate(180%);
+  box-shadow:
+    0 24px 60px -12px rgba(0, 0, 0, 0.45),
+    inset 0 1px 0 rgba(255, 255, 255, 0.08);
+  font-family: var(--fd-font-sans, system-ui, sans-serif);
+  animation: fd-tweaks-slide-in 180ms ease-out;
+  /* Isolate so nested backdrop-filter on inner elements creates a layered
+   * glass effect within the dialog rather than blurring page content twice. */
+  isolation: isolate;
+}
+
+/* Drag-to-snap side variants — defaults to right above; left mirrors. */
+.fd-tweaks-dialog[data-side="left"] {
+  left: 1rem;
+  right: auto;
+}
+
+@media (max-width: 480px) {
+  .fd-tweaks-dialog,
+  .fd-tweaks-dialog[data-side="left"] {
+    left: 1rem;
+    right: 1rem;
+    width: auto;
+  }
+}
+
+/* ─── Header ────────────────────────────────────────────────────────── */
+
+.fd-tweaks-header {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.625rem 0.875rem;
+  border-bottom: 1px solid color-mix(in srgb, var(--color-fd-border) 60%, transparent);
+  cursor: grab;
+  user-select: none;
+  touch-action: none;
+}
+
+.fd-tweaks-title {
+  margin-right: auto;
+}
+
+.fd-tweaks-header:active {
+  cursor: grabbing;
+}
+
+.fd-tweaks-title {
+  font-size: 0.6875rem;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--color-fd-muted-foreground);
+}
+
+.fd-tweaks-close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  background: transparent;
+  color: var(--color-fd-muted-foreground);
+  border: 0;
+  border-radius: 0.375rem;
+  cursor: pointer;
+  transition:
+    background 0.15s,
+    color 0.15s;
+}
+
+.fd-tweaks-close:hover {
+  background: color-mix(in srgb, var(--color-fd-accent) 70%, transparent);
+  color: var(--color-fd-foreground);
+}
+
+/* ─── Body ──────────────────────────────────────────────────────────── */
+
+.fd-tweaks-body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.875rem;
+  padding: 0.875rem;
+}
+
+.fd-tweaks-row {
+  display: flex;
+  flex-direction: column;
+  gap: 0.4375rem;
+}
+
+.fd-tweaks-row-label {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  font-size: 0.625rem;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--color-fd-muted-foreground);
+}
+
+.fd-tweaks-row-value {
+  font-family: var(--fd-font-mono, ui-monospace, monospace);
+  font-size: 0.6875rem;
+  font-weight: 400;
+  letter-spacing: 0;
+  text-transform: none;
+  color: var(--color-fd-foreground);
+}
+
+/* ─── Color swatches ────────────────────────────────────────────────── */
+
+.fd-tweaks-swatches {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 0.375rem;
+}
+
+.fd-tweaks-swatch {
+  position: relative;
+  aspect-ratio: 1 / 1;
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 70%, transparent);
+  border-radius: 0.375rem;
+  cursor: pointer;
+  transition:
+    transform 0.1s ease,
+    box-shadow 0.1s ease;
+  padding: 0;
+  /* Nested blur so swatches feel like floating tiles. */
+  backdrop-filter: blur(28px);
+}
+
+.fd-tweaks-swatch:hover {
+  transform: scale(1.06);
+}
+
+.fd-tweaks-swatch[data-selected] {
+  box-shadow:
+    0 0 0 2px color-mix(in srgb, var(--color-fd-background, #0a0a0a) 85%, transparent),
+    0 0 0 4px var(--color-fd-foreground, #fafafa);
+}
+
+.fd-tweaks-swatch-check {
+  position: absolute;
+  inset: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: #fff;
+  mix-blend-mode: difference;
+}
+
+/* ─── Chip group ────────────────────────────────────────────────────── */
+
+.fd-tweaks-chips {
+  display: flex;
+  gap: 0.25rem;
+  padding: 0.25rem;
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 40%, transparent);
+  border-radius: 0.5rem;
+  /* Very translucent — heavy blur compounds with the dialog's own blur
+   * to give a "deeper" frosted look on the inner groove. */
+  background: color-mix(in srgb, var(--color-fd-muted) 10%, transparent);
+  backdrop-filter: blur(40px);
+  isolation: isolate;
+}
+
+.fd-tweaks-chip {
+  flex: 1;
+  padding: 0.4rem 0.5rem;
+  font-size: 0.75rem;
+  font-weight: 500;
+  font-family: inherit;
+  color: var(--color-fd-muted-foreground);
+  background: transparent;
+  border: 0;
+  border-radius: 0.375rem;
+  cursor: pointer;
+  transition:
+    background 0.15s,
+    color 0.15s;
+}
+
+.fd-tweaks-chip:hover {
+  color: var(--color-fd-foreground);
+}
+
+.fd-tweaks-chip[data-selected] {
+  background: color-mix(in srgb, var(--color-fd-accent, var(--color-fd-foreground)) 22%, transparent);
+  color: var(--color-fd-foreground);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12);
+  backdrop-filter: blur(48px);
+}
+
+/* ─── Slider ────────────────────────────────────────────────────────── */
+
+.fd-tweaks-slider {
+  width: 100%;
+  height: 4px;
+  appearance: none;
+  -webkit-appearance: none;
+  background: color-mix(in srgb, var(--color-fd-muted) 45%, transparent);
+  border-radius: 9999px;
+  outline: none;
+  cursor: pointer;
+  margin-top: 0.25rem;
+}
+
+.fd-tweaks-slider::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 14px;
+  height: 14px;
+  border-radius: 9999px;
+  background: var(--color-fd-primary);
+  border: 2px solid var(--color-fd-background, #0a0a0a);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
+  cursor: pointer;
+}
+
+.fd-tweaks-slider::-moz-range-thumb {
+  width: 14px;
+  height: 14px;
+  border-radius: 9999px;
+  background: var(--color-fd-primary);
+  border: 2px solid var(--color-fd-background, #0a0a0a);
+  cursor: pointer;
+}
+
+/* ─── Select (custom dropdown — cross-browser consistent) ──────────── */
+
+.fd-tweaks-select-wrap {
+  position: relative;
+  width: 100%;
+}
+
+.fd-tweaks-select-trigger {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  width: 100%;
+  height: 2rem;
+  padding: 0 0.625rem;
+  font-family: inherit;
+  font-size: 0.8125rem;
+  color: var(--color-fd-foreground);
+  background: color-mix(in srgb, var(--color-fd-background, transparent) 10%, transparent);
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 40%, transparent);
+  border-radius: 0.375rem;
+  outline: none;
+  cursor: pointer;
+  transition:
+    border-color 0.15s,
+    background 0.15s;
+}
+
+.fd-tweaks-select-trigger:hover {
+  border-color: color-mix(in srgb, var(--color-fd-foreground) 25%, var(--color-fd-border));
+  background: color-mix(in srgb, var(--color-fd-background, transparent) 18%, transparent);
+}
+
+.fd-tweaks-select-trigger:focus-visible {
+  border-color: var(--color-fd-primary);
+  box-shadow: 0 0 0 1px var(--color-fd-primary);
+}
+
+.fd-tweaks-select-trigger-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  text-align: left;
+}
+
+.fd-tweaks-select-chevron {
+  opacity: 0.5;
+  transition: transform 0.15s;
+  flex-shrink: 0;
+}
+
+.fd-tweaks-select-trigger[data-open] .fd-tweaks-select-chevron {
+  transform: rotate(180deg);
+}
+
+.fd-tweaks-select-menu {
+  position: absolute;
+  top: calc(100% + 0.25rem);
+  left: 0;
+  right: 0;
+  z-index: 50;
+  display: flex;
+  flex-direction: column;
+  padding: 0.25rem;
+  max-height: 240px;
+  overflow-y: auto;
+  background: var(--color-fd-popover, var(--color-fd-card));
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 65%, transparent);
+  border-radius: 0.5rem;
+  box-shadow:
+    0 10px 28px -10px rgba(0, 0, 0, 0.45),
+    0 4px 10px -4px rgba(0, 0, 0, 0.35);
+}
+
+.fd-tweaks-select-menu[data-flip-up] {
+  top: auto;
+  bottom: calc(100% + 0.25rem);
+}
+
+.fd-tweaks-select-option {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  padding: 0.375rem 0.5rem;
+  font-family: inherit;
+  font-size: 0.75rem;
+  color: color-mix(in srgb, var(--color-fd-foreground) 65%, transparent);
+  background: transparent;
+  border: none;
+  border-radius: 0.25rem;
+  text-align: left;
+  cursor: pointer;
+  transition:
+    background 0.1s,
+    color 0.1s;
+}
+
+.fd-tweaks-select-option:hover {
+  color: var(--color-fd-foreground);
+  background: color-mix(in srgb, var(--color-fd-foreground) 6%, transparent);
+}
+
+.fd-tweaks-select-option[data-active] {
+  color: var(--color-fd-foreground);
+  background: color-mix(in srgb, var(--color-fd-foreground) 8%, transparent);
+}
+
+.fd-tweaks-select-option-dot {
+  width: 0.25rem;
+  height: 0.25rem;
+  border-radius: 9999px;
+  background: transparent;
+  flex-shrink: 0;
+}
+
+.fd-tweaks-select-option[data-active] .fd-tweaks-select-option-dot {
+  background: var(--color-fd-primary);
+}
+
+/* ─── Author mode: section divider + label ───────────────────────────── */
+
+.fd-tweaks-section-divider {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-top: 0.25rem;
+}
+
+.fd-tweaks-section-divider::after {
+  content: "";
+  flex: 1;
+  height: 1px;
+  background: color-mix(in srgb, var(--color-fd-border) 55%, transparent);
+}
+
+.fd-tweaks-section-label {
+  font-family: var(--fd-font-mono, ui-monospace, monospace);
+  font-size: 0.625rem;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--color-fd-muted-foreground);
+}
+
+/* ─── Author mode: color token grid ──────────────────────────────────── */
+
+.fd-tweaks-color-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 0.375rem 0.5rem;
+}
+
+.fd-tweaks-color-pair {
+  display: grid;
+  grid-template-columns: 16px minmax(0, 1fr);
+  align-items: center;
+  gap: 0.375rem;
+  position: relative;
+}
+
+.fd-tweaks-color-swatch-mini {
+  width: 16px;
+  height: 16px;
+  border-radius: 0.25rem;
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 70%, transparent);
+  padding: 0;
+  cursor: pointer;
+  transition: transform 0.1s ease;
+}
+
+.fd-tweaks-color-swatch-mini:hover {
+  transform: scale(1.1);
+}
+
+.fd-tweaks-color-text {
+  width: 100%;
+  min-width: 0;
+  height: 1.625rem;
+  padding: 0 0.4rem;
+  font-family: var(--fd-font-mono, ui-monospace, monospace);
+  font-size: 0.6875rem;
+  color: var(--color-fd-foreground);
+  background: color-mix(in srgb, var(--color-fd-background, transparent) 8%, transparent);
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 40%, transparent);
+  border-radius: 0.25rem;
+  outline: none;
+  backdrop-filter: blur(40px);
+  transition: border-color 0.15s;
+}
+
+.fd-tweaks-color-text:focus {
+  border-color: var(--color-fd-primary);
+}
+
+.fd-tweaks-color-label {
+  grid-column: 1 / -1;
+  font-size: 0.5625rem;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--color-fd-muted-foreground);
+  padding-inline-start: 1.625rem;
+  margin-top: -0.125rem;
+  line-height: 1;
+}
+
+/* ─── Author mode: code export panel ─────────────────────────────────── */
+
+.fd-tweaks-export {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 40%, transparent);
+  border-radius: 0.5rem;
+  background: color-mix(in srgb, var(--color-fd-background, transparent) 8%, transparent);
+  backdrop-filter: blur(40px);
+  overflow: hidden;
+}
+
+.fd-tweaks-export-tabs {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.25rem 0.25rem 0.25rem 0.375rem;
+  border-bottom: 1px solid color-mix(in srgb, var(--color-fd-border) 45%, transparent);
+}
+
+.fd-tweaks-export-tab {
+  padding: 0.25rem 0.5rem;
+  font-family: var(--fd-font-mono, ui-monospace, monospace);
+  font-size: 0.625rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--color-fd-muted-foreground);
+  background: transparent;
+  border: 0;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  transition: color 0.15s, background 0.15s;
+}
+
+.fd-tweaks-export-tab:hover {
+  color: var(--color-fd-foreground);
+}
+
+.fd-tweaks-export-tab[data-selected] {
+  color: var(--color-fd-foreground);
+  background: color-mix(in srgb, var(--color-fd-accent) 60%, transparent);
+}
+
+.fd-tweaks-export-copy {
+  margin-inline-start: auto;
+  padding: 0.25rem 0.625rem;
+  font-family: var(--fd-font-mono, ui-monospace, monospace);
+  font-size: 0.625rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--color-fd-muted-foreground);
+  background: color-mix(in srgb, var(--color-fd-muted) 30%, transparent);
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 50%, transparent);
+  border-radius: 0.25rem;
+  cursor: pointer;
+  transition: color 0.15s, background 0.15s, border-color 0.15s;
+}
+
+.fd-tweaks-export-copy:hover {
+  color: var(--color-fd-foreground);
+  background: color-mix(in srgb, var(--color-fd-accent) 55%, transparent);
+  border-color: color-mix(in srgb, var(--color-fd-foreground) 25%, var(--color-fd-border));
+}
+
+.fd-tweaks-export-code {
+  margin: 0;
+  padding: 0.5rem 0.625rem;
+  max-height: 200px;
+  overflow: auto;
+  font-family: var(--fd-font-mono, ui-monospace, monospace);
+  font-size: 0.6875rem;
+  line-height: 1.55;
+  color: var(--color-fd-foreground);
+  white-space: pre;
+  background: transparent;
+}
+
+/* sugar-high token colors. The library emits inline style="color:var(--sh-*)"
+ * on each token; we define those vars here so they adapt to light/dark. */
+.fd-tweaks-export-code-highlighted {
+  --sh-class: #6366f1;
+  --sh-identifier: var(--color-fd-foreground);
+  --sh-sign: color-mix(in srgb, var(--color-fd-muted-foreground) 80%, transparent);
+  --sh-property: #0ea5e9;
+  --sh-entity: #0ea5e9;
+  --sh-jsxliterals: #8b5cf6;
+  --sh-string: #15803d;
+  --sh-keyword: #d946ef;
+  --sh-comment: color-mix(in srgb, var(--color-fd-muted-foreground) 70%, transparent);
+}
+
+.dark .fd-tweaks-export-code-highlighted {
+  --sh-class: #a5b4fc;
+  --sh-identifier: var(--color-fd-foreground);
+  --sh-sign: color-mix(in srgb, var(--color-fd-muted-foreground) 90%, transparent);
+  --sh-property: #7dd3fc;
+  --sh-entity: #7dd3fc;
+  --sh-jsxliterals: #c4b5fd;
+  --sh-string: #86efac;
+  --sh-keyword: #f0abfc;
+  --sh-comment: color-mix(in srgb, var(--color-fd-muted-foreground) 70%, transparent);
+}
+
+.fd-tweaks-export-code-highlighted .sh__line {
+  display: block;
+}
+
+/* Author dialog grows a bit wider for the 2-col color grid. When content
+ * exceeds the viewport height, the whole dialog scrolls (header and footer
+ * scroll along with the body). This is simpler and more robust than an
+ * inner flex-column with a scrolling body — the latter collapses to zero
+ * height in flex containers that have no explicit height to grow into. */
+.fd-tweaks-dialog:has(.fd-tweaks-color-grid) {
+  width: 360px;
+  max-height: calc(100vh - 2rem);
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+/* ─── Reset (header) ───────────────────────────────────────────────── */
+
+.fd-tweaks-reset {
+  padding: 0.25rem 0.5rem;
+  font-size: 0.625rem;
+  font-weight: 500;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  font-family: inherit;
+  color: var(--color-fd-muted-foreground);
+  background: transparent;
+  border: 1px solid color-mix(in srgb, var(--color-fd-border) 60%, transparent);
+  border-radius: 0.3125rem;
+  cursor: pointer;
+  transition:
+    color 0.15s,
+    border-color 0.15s,
+    background 0.15s;
+}
+
+.fd-tweaks-reset:hover {
+  color: var(--color-fd-foreground);
+  border-color: color-mix(in srgb, var(--color-fd-foreground) 30%, var(--color-fd-border));
+  background: color-mix(in srgb, var(--color-fd-accent) 50%, transparent);
+}
+
+/* ─── Triggers ──────────────────────────────────────────────────────── */
+
+.fd-tweaks-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  color: var(--color-fd-muted-foreground);
+  background: transparent;
+  border: 1px solid var(--color-fd-border);
+  font-family: inherit;
+  cursor: pointer;
+  transition:
+    background 0.15s,
+    color 0.15s,
+    border-color 0.15s;
+}
+
+.fd-tweaks-trigger:hover {
+  color: var(--color-fd-foreground);
+  background: var(--color-fd-accent);
+}
+
+.fd-tweaks-trigger[data-open] {
+  color: var(--color-fd-accent-foreground, var(--color-fd-foreground));
+  background: var(--color-fd-accent);
+  border-color: color-mix(in srgb, var(--color-fd-primary) 35%, var(--color-fd-border));
+}
+
+.fd-tweaks-trigger svg {
+  flex-shrink: 0;
+}
+
+/* Sidebar variant — border-radius is set dynamically by the auto-portal
+ * trigger from the host theme toggle's computed radius (see
+ * tweaks-dialog.tsx → TweaksAutoPortalTrigger). The default 1.5rem
+ * fallback covers the case where this is rendered manually without a
+ * portal context. */
+.fd-tweaks-trigger-sidebar {
+  padding: 0.375rem 0.625rem;
+  border-radius: var(--fd-tweaks-trigger-radius-match, 1.5rem);
+  font-size: 0.75rem;
+  font-weight: 500;
+  letter-spacing: 0.02em;
+  line-height: 1;
+}
+
+.fd-tweaks-trigger-sidebar .fd-tweaks-trigger-label {
+  text-transform: capitalize;
+}
+
+/* Floating variant — fixed FAB. When used as the fallback in
+ * position="both", it is hidden at md+ where the sidebar is visible. */
+.fd-tweaks-trigger-floating {
+  position: fixed;
+  bottom: 1rem;
+  left: 1rem;
+  z-index: 40;
+  height: 2.5rem;
+  padding: 0 0.875rem;
+  border-radius: 9999px;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  background: color-mix(in srgb, var(--color-fd-card, var(--color-fd-background)) 22%, transparent);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.18);
+  backdrop-filter: blur(28px) saturate(180%);
+}
+
+@media (min-width: 768px) {
+  .fd-tweaks-trigger-floating[data-fallback] {
+    display: none;
+  }
+}
+