fix(docs): namespace custom CSS variables to prevent Mintlify collision (#285)

The `Copy page` dropdown panel rendered with a transparent background in
light mode because `docs/custom.css` defined `--background-light: #ffffff`
on `:root`. Mintlify's Maple theme owns that variable as a Tailwind color
(space-separated RGB used via `rgb(var(--background-light)/<alpha>)`), so
the hex override produced invalid CSS like `rgb(#ffffff/1)` and the
dropdown's `bg-background-light` class fell back to transparent. Dark
mode was unaffected because the dropdown panel uses `bg-background-dark`,
which custom.css didn't redefine.

Namespaced every custom variable with `--hf-` to make collisions
impossible, and updated the two consumers (`pre`, `::selection`, link
color in custom.css; `.tpl-card:hover` border in template-gallery.css).
This commit is contained in:
James Russo
2026-04-15 14:07:34 -07:00
committed by GitHub
parent 0a3ca498ea
commit 87ce26de8a
2 changed files with 53 additions and 45 deletions
+52 -44
View File
@@ -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 {
+1 -1
View File
@@ -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 {