diff --git a/docs/custom.css b/docs/custom.css
index 4daf5c987..71db70174 100644
--- a/docs/custom.css
+++ b/docs/custom.css
@@ -37,58 +37,66 @@
 }
 
 /* ── Light mode (default) ── */
+/*
+ * NOTE: All custom variables are namespaced with `--hf-` to avoid
+ * colliding with Mintlify's Tailwind color system, which owns names
+ * like `--background-light` / `--background-dark` and uses them via
+ * `rgb(var(--background-light)/<alpha>)`. Overriding those with hex
+ * values breaks the rgb() call and makes surfaces transparent (e.g.
+ * the "Copy page" dropdown panel in light mode).
+ */
 
 :root {
-  --background: #f6f5f1;
-  --background-light: #ffffff;
-  --surface2: #eeedea;
-  --border-color: #e0dfdb;
-  --border-color-light: #d0cfcb;
-  --text: #1a1a1a;
-  --text-secondary: #6b6b6b;
-  --text-tertiary: #999999;
-  --heading: #0a0a0a;
-  --code-bg: #ffffff;
+  --hf-background: #f6f5f1;
+  --hf-background-light: #ffffff;
+  --hf-surface2: #eeedea;
+  --hf-border-color: #e0dfdb;
+  --hf-border-color-light: #d0cfcb;
+  --hf-text: #1a1a1a;
+  --hf-text-secondary: #6b6b6b;
+  --hf-text-tertiary: #999999;
+  --hf-heading: #0a0a0a;
+  --hf-code-bg: #ffffff;
 
-  --accent-green: #1a7a0a;
-  --accent-green-light: rgba(26, 122, 10, 0.07);
-  --accent-green-border: rgba(26, 122, 10, 0.25);
-  --accent-blue: #2563eb;
-  --accent-blue-light: rgba(37, 99, 235, 0.06);
-  --accent-blue-border: rgba(37, 99, 235, 0.2);
-  --accent-purple: #7c3aed;
-  --accent-purple-light: rgba(124, 58, 237, 0.06);
-  --accent-purple-border: rgba(124, 58, 237, 0.2);
+  --hf-accent-green: #1a7a0a;
+  --hf-accent-green-light: rgba(26, 122, 10, 0.07);
+  --hf-accent-green-border: rgba(26, 122, 10, 0.25);
+  --hf-accent-blue: #2563eb;
+  --hf-accent-blue-light: rgba(37, 99, 235, 0.06);
+  --hf-accent-blue-border: rgba(37, 99, 235, 0.2);
+  --hf-accent-purple: #7c3aed;
+  --hf-accent-purple-light: rgba(124, 58, 237, 0.06);
+  --hf-accent-purple-border: rgba(124, 58, 237, 0.2);
 
-  --selection-bg: rgba(128, 128, 128, 0.2);
+  --hf-selection-bg: rgba(128, 128, 128, 0.2);
 }
 
 /* ── Dark mode ── */
 
 .dark,
 [data-theme="dark"] {
-  --background: #0a0a0a;
-  --background-light: #141414;
-  --surface2: #1a1a1a;
-  --border-color: #2a2a2a;
-  --border-color-light: #3a3a3a;
-  --text: #e5e5e5;
-  --text-secondary: #a0a0a0;
-  --text-tertiary: #666666;
-  --heading: #f5f5f5;
-  --code-bg: #141414;
+  --hf-background: #0a0a0a;
+  --hf-background-light: #141414;
+  --hf-surface2: #1a1a1a;
+  --hf-border-color: #2a2a2a;
+  --hf-border-color-light: #3a3a3a;
+  --hf-text: #e5e5e5;
+  --hf-text-secondary: #a0a0a0;
+  --hf-text-tertiary: #666666;
+  --hf-heading: #f5f5f5;
+  --hf-code-bg: #141414;
 
-  --accent-green: #22c55e;
-  --accent-green-light: rgba(34, 197, 94, 0.1);
-  --accent-green-border: rgba(34, 197, 94, 0.3);
-  --accent-blue: #3b82f6;
-  --accent-blue-light: rgba(59, 130, 246, 0.1);
-  --accent-blue-border: rgba(59, 130, 246, 0.3);
-  --accent-purple: #a78bfa;
-  --accent-purple-light: rgba(167, 139, 250, 0.1);
-  --accent-purple-border: rgba(167, 139, 250, 0.3);
+  --hf-accent-green: #22c55e;
+  --hf-accent-green-light: rgba(34, 197, 94, 0.1);
+  --hf-accent-green-border: rgba(34, 197, 94, 0.3);
+  --hf-accent-blue: #3b82f6;
+  --hf-accent-blue-light: rgba(59, 130, 246, 0.1);
+  --hf-accent-blue-border: rgba(59, 130, 246, 0.3);
+  --hf-accent-purple: #a78bfa;
+  --hf-accent-purple-light: rgba(167, 139, 250, 0.1);
+  --hf-accent-purple-border: rgba(167, 139, 250, 0.3);
 
-  --selection-bg: rgba(255, 255, 255, 0.15);
+  --hf-selection-bg: rgba(255, 255, 255, 0.15);
 }
 
 /* ── Typography ── */
@@ -119,21 +127,21 @@ code, pre, pre code, kbd,
 /* ── Code blocks ── */
 
 pre {
-  background: var(--code-bg) !important;
-  border: 1px solid var(--border-color) !important;
+  background: var(--hf-code-bg) !important;
+  border: 1px solid var(--hf-border-color) !important;
   border-radius: 8px !important;
 }
 
 /* ── Selection ── */
 
 ::selection {
-  background: var(--selection-bg);
+  background: var(--hf-selection-bg);
 }
 
 /* ── Links ── */
 
 a:not([class]) {
-  color: var(--accent-blue);
+  color: var(--hf-accent-blue);
 }
 
 a:not([class]):hover {
diff --git a/docs/template-gallery.css b/docs/template-gallery.css
index f2ab2f646..49f0e5002 100644
--- a/docs/template-gallery.css
+++ b/docs/template-gallery.css
@@ -11,7 +11,7 @@
 
 .tpl-card:hover {
   transform: translateY(-2px);
-  border-color: var(--border-color-light, #d0cfcb);
+  border-color: var(--hf-border-color-light, #d0cfcb);
 }
 
 .tpl-label {