From a5c9c83b7861c4ca5529e8a327b93e0d50fcc667 Mon Sep 17 00:00:00 2001
From: Harish Kukreja <harish.kukreja@gmail.com>
Date: Mon, 4 May 2026 14:08:50 -0400
Subject: [PATCH] fix(web): force light color-scheme on docs iframe
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Documentation tab embeds the public Hermes Agent docs site via an
<iframe>. On any system where the browser's prefers-color-scheme
resolves to dark — the default on macOS with system dark mode, and
common on Linux/Windows too — the docs body text rendered nearly
invisible against its own background.

Cause: Docusaurus intentionally leaves <html> and <body> transparent
and relies on the browser's Canvas color to fill the viewport. Inside
our iframe, the iframe element had bg-background (the dashboard's dark
canvas) AND inherited the dashboard's dark color-scheme, so the
browser set the iframe's Canvas to a dark value. Docusaurus's
transparent body exposed that dark Canvas, and the docs body text
(tuned for a light Canvas) became near-illegible. Affects every
built-in dashboard theme.

Fix: replace bg-background on the iframe with [color-scheme:light]
(spec-blessed cross-origin override of the inherited color-scheme;
forces the iframe's Canvas to light) and bg-white (belt-and-suspenders
fallback during the brief paint window before content loads). The
docs site's own theme toggle keeps working — Docusaurus stores its
choice in localStorage and applies opaque dark backgrounds to its
layout elements that cover the white Canvas we forced.
---
 web/src/pages/DocsPage.tsx | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/web/src/pages/DocsPage.tsx b/web/src/pages/DocsPage.tsx
index 95ef2718f7..fa929377b1 100644
--- a/web/src/pages/DocsPage.tsx
+++ b/web/src/pages/DocsPage.tsx
@@ -50,7 +50,15 @@ export default function DocsPage() {
         className={cn(
           "min-h-0 w-full min-w-0 flex-1",
           "rounded-sm border border-current/20",
-          "bg-background",
+          // Docusaurus paints over a transparent <html> / <body> and
+          // relies on the browser's canvas color (light by default) to
+          // fill the viewport. Inheriting the dashboard's dark color
+          // scheme makes that canvas dark, so the docs body text — which
+          // is tuned for a light canvas — becomes near-invisible. Force a
+          // light color scheme + white background on the iframe element so
+          // the docs render cleanly regardless of the active dashboard
+          // theme or the user's prefers-color-scheme.
+          "[color-scheme:light] bg-white",
         )}
         sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
         referrerPolicy="no-referrer-when-downgrade"
