From 98b69b180af265a566871f42fa28f111d2e53cb8 Mon Sep 17 00:00:00 2001
From: "2569718930@qq.com" <2569718930@qq.com>
Date: Sat, 6 Jun 2026 19:52:27 +0800
Subject: [PATCH] fix: improve docs page readability

---
 .../components/docs/DocsLayout.module.css     | 241 +++++++++++-------
 .../docs/__tests__/docsLayoutContrast.test.ts |  21 ++
 2 files changed, 168 insertions(+), 94 deletions(-)
 create mode 100644 frontend/components/docs/__tests__/docsLayoutContrast.test.ts

diff --git a/frontend/components/docs/DocsLayout.module.css b/frontend/components/docs/DocsLayout.module.css
index 2a810970..f665ab43 100644
--- a/frontend/components/docs/DocsLayout.module.css
+++ b/frontend/components/docs/DocsLayout.module.css
@@ -1,6 +1,8 @@
 .docsShell {
   min-height: 100vh;
-  color: rgba(226, 232, 240, 0.94);
+  background:
+    linear-gradient(180deg, #f8fbff 0%, #eef4fb 100%);
+  color: #0f172a;
 }
 
 .docsHeader {
@@ -11,10 +13,11 @@
   align-items: center;
   justify-content: space-between;
   gap: 16px;
-  padding: 18px 24px;
-  background: rgba(2, 6, 23, 0.82);
-  border-bottom: 1px solid rgba(148, 163, 184, 0.12);
-  backdrop-filter: blur(16px);
+  padding: 16px 24px;
+  background: rgba(255, 255, 255, 0.94);
+  border-bottom: 1px solid #d9e3ef;
+  box-shadow: 0 1px 0 rgba(15, 23, 42, 0.04);
+  backdrop-filter: blur(14px);
 }
 
 .brandWrap {
@@ -24,15 +27,15 @@
 }
 
 .brandLink {
-  color: #67e8f9;
-  font-size: 1.9rem;
+  color: #0891b2;
+  font-size: 1.55rem;
   font-weight: 800;
   text-decoration: none;
 }
 
 .brandSubtitle {
-  color: rgba(148, 163, 184, 0.88);
-  font-size: 0.95rem;
+  color: #64748b;
+  font-size: 0.92rem;
 }
 
 .headerActions {
@@ -49,23 +52,32 @@
   min-height: 38px;
   padding: 0 14px;
   border-radius: 999px;
-  border: 1px solid rgba(148, 163, 184, 0.18);
-  background: rgba(15, 23, 42, 0.75);
-  color: rgba(226, 232, 240, 0.95);
+  border: 1px solid #cbd5e1;
+  background: #ffffff;
+  color: #334155;
   text-decoration: none;
   font-size: 0.92rem;
-  font-weight: 600;
+  font-weight: 700;
+  cursor: pointer;
+  transition:
+    border-color 160ms ease,
+    color 160ms ease,
+    background 160ms ease;
 }
 
-.headerGhost {
-  background: transparent;
+.headerButton:hover,
+.headerGhost:hover {
+  border-color: #38bdf8;
+  color: #075985;
+  background: #f0f9ff;
 }
 
 .langSwitch {
   display: flex;
-  border: 1px solid rgba(148, 163, 184, 0.18);
+  border: 1px solid #cbd5e1;
   border-radius: 999px;
   overflow: hidden;
+  background: #ffffff;
 }
 
 .langButton {
@@ -73,60 +85,76 @@
   min-height: 38px;
   border: 0;
   background: transparent;
-  color: rgba(148, 163, 184, 0.92);
-  font-weight: 700;
+  color: #64748b;
+  font-weight: 800;
+  cursor: pointer;
 }
 
 .langButtonActive {
-  background: rgba(34, 211, 238, 0.16);
-  color: #67e8f9;
+  background: #e0f2fe;
+  color: #0369a1;
 }
 
 .docsFrame {
   display: grid;
-  grid-template-columns: 280px minmax(0, 1fr) 220px;
+  grid-template-columns: 260px minmax(0, 820px) 220px;
+  justify-content: center;
   gap: 28px;
+  width: 100%;
+  max-width: 1440px;
+  margin: 0 auto;
   padding: 24px;
 }
 
 .sidebar {
   position: sticky;
-  top: 86px;
+  top: 84px;
   align-self: start;
-  max-height: calc(100vh - 110px);
+  max-height: calc(100vh - 108px);
   overflow: auto;
-  padding: 20px;
-  border: 1px solid rgba(148, 163, 184, 0.12);
-  border-radius: 20px;
-  background: rgba(15, 23, 42, 0.72);
+  padding: 16px;
+  border: 1px solid #d8e3ef;
+  border-radius: 16px;
+  background: #ffffff;
+  box-shadow: 0 12px 32px rgba(15, 23, 42, 0.06);
 }
 
 .sidebarGroup + .sidebarGroup {
-  margin-top: 24px;
+  margin-top: 22px;
 }
 
 .sidebarTitle {
-  margin: 0 0 10px;
-  color: rgba(148, 163, 184, 0.92);
-  font-size: 0.8rem;
-  font-weight: 700;
-  letter-spacing: 0.08em;
+  margin: 0 0 8px;
+  color: #64748b;
+  font-size: 0.78rem;
+  font-weight: 800;
+  letter-spacing: 0.06em;
   text-transform: uppercase;
 }
 
 .sidebarLink {
   display: block;
-  margin-bottom: 6px;
-  padding: 10px 12px;
-  border-radius: 12px;
-  color: rgba(226, 232, 240, 0.88);
+  margin-bottom: 4px;
+  padding: 9px 10px;
+  border-radius: 8px;
+  color: #334155;
   text-decoration: none;
-  font-size: 0.95rem;
+  font-size: 0.94rem;
+  line-height: 1.35;
+  transition:
+    background 160ms ease,
+    color 160ms ease;
+}
+
+.sidebarLink:hover {
+  background: #f1f5f9;
+  color: #0f172a;
 }
 
 .sidebarLinkActive {
-  background: rgba(34, 211, 238, 0.12);
-  color: #67e8f9;
+  background: #e0f2fe;
+  color: #0369a1;
+  font-weight: 800;
 }
 
 .content {
@@ -134,80 +162,87 @@
 }
 
 .contentInner {
-  padding: 12px 0 48px;
+  padding: 16px 0 56px;
 }
 
 .pageTitle {
   margin: 0;
-  font-size: clamp(2.1rem, 4vw, 3.2rem);
-  font-weight: 800;
-  letter-spacing: -0.03em;
+  color: #0f172a;
+  font-size: clamp(2rem, 4vw, 3.05rem);
+  font-weight: 850;
+  line-height: 1.12;
 }
 
 .pageDescription {
-  max-width: 820px;
+  max-width: 760px;
   margin: 14px 0 0;
-  color: rgba(191, 219, 254, 0.9);
+  color: #475569;
   font-size: 1.03rem;
   line-height: 1.75;
 }
 
 .section {
   margin-top: 40px;
-  scroll-margin-top: 110px;
+  scroll-margin-top: 104px;
 }
 
 .sectionTitle {
-  margin: 0 0 16px;
-  font-size: 1.65rem;
-  font-weight: 700;
+  margin: 0 0 14px;
+  color: #1e293b;
+  font-size: 1.45rem;
+  font-weight: 800;
+  line-height: 1.25;
 }
 
 .paragraph {
-  margin: 0 0 16px;
-  color: rgba(226, 232, 240, 0.94);
-  line-height: 1.9;
+  margin: 0 0 15px;
+  color: #334155;
+  font-size: 1rem;
+  line-height: 1.85;
 }
 
 .callout {
-  margin: 18px 0;
+  margin: 20px 0;
   padding: 18px 20px;
-  border: 1px solid rgba(148, 163, 184, 0.16);
-  border-radius: 18px;
-  background: rgba(15, 23, 42, 0.72);
+  border: 1px solid #d8e3ef;
+  border-radius: 12px;
+  background: #ffffff;
+  box-shadow: 0 8px 24px rgba(15, 23, 42, 0.05);
 }
 
 .calloutInfo {
-  border-color: rgba(34, 211, 238, 0.24);
-  background: rgba(8, 47, 73, 0.26);
+  border-color: #bae6fd;
+  background: #f0f9ff;
 }
 
 .calloutWarning {
-  border-color: rgba(251, 191, 36, 0.24);
-  background: rgba(120, 53, 15, 0.2);
+  border-color: #fde68a;
+  background: #fffbeb;
 }
 
 .calloutSuccess {
-  border-color: rgba(52, 211, 153, 0.24);
-  background: rgba(6, 78, 59, 0.22);
+  border-color: #bbf7d0;
+  background: #f0fdf4;
 }
 
 .calloutTitle {
   margin: 0 0 8px;
+  color: #0f172a;
   font-size: 0.98rem;
-  font-weight: 700;
+  font-weight: 800;
 }
 
 .calloutText {
   margin: 0;
-  line-height: 1.8;
+  color: #334155;
+  line-height: 1.75;
 }
 
 .list {
-  margin: 0;
-  padding-left: 20px;
-  color: rgba(226, 232, 240, 0.94);
-  line-height: 1.85;
+  margin: 0 0 16px;
+  padding-left: 22px;
+  color: #334155;
+  line-height: 1.8;
 }
 
 .list li + li {
@@ -221,52 +256,59 @@
   min-height: 42px;
   padding: 0 16px;
   border-radius: 999px;
-  border: 1px solid rgba(34, 211, 238, 0.34);
-  background: rgba(8, 47, 73, 0.3);
-  color: #67e8f9;
+  border: 1px solid #38bdf8;
+  background: #e0f2fe;
+  color: #0369a1;
   text-decoration: none;
-  font-weight: 700;
+  font-weight: 800;
 }
 
 .linkCard:hover {
-  background: rgba(34, 211, 238, 0.12);
+  background: #bae6fd;
 }
 
 .linkCaption {
   margin: 10px 0 0;
-  color: rgba(148, 163, 184, 0.92);
-  line-height: 1.75;
+  color: #64748b;
+  line-height: 1.7;
 }
 
 .toc {
   position: sticky;
-  top: 86px;
+  top: 84px;
   align-self: start;
-  padding: 20px;
-  border: 1px solid rgba(148, 163, 184, 0.12);
-  border-radius: 20px;
-  background: rgba(15, 23, 42, 0.64);
+  padding: 16px;
+  border: 1px solid #d8e3ef;
+  border-radius: 16px;
+  background: #ffffff;
+  box-shadow: 0 12px 32px rgba(15, 23, 42, 0.06);
 }
 
 .tocTitle {
-  margin: 0 0 12px;
-  color: rgba(148, 163, 184, 0.92);
-  font-size: 0.82rem;
-  font-weight: 700;
-  letter-spacing: 0.08em;
+  margin: 0 0 10px;
+  color: #64748b;
+  font-size: 0.78rem;
+  font-weight: 800;
+  letter-spacing: 0.06em;
   text-transform: uppercase;
 }
 
 .tocLink {
   display: block;
-  color: rgba(226, 232, 240, 0.86);
+  padding: 5px 0;
+  color: #475569;
   text-decoration: none;
-  line-height: 1.7;
+  line-height: 1.55;
   font-size: 0.92rem;
 }
 
+.tocLink:hover {
+  color: #0369a1;
+}
+
 .mobileMenuButton {
   display: none;
+  margin-bottom: 18px;
 }
 
 .mobileSidebarBackdrop {
@@ -275,7 +317,8 @@
 
 @media (max-width: 1200px) {
   .docsFrame {
-    grid-template-columns: 260px minmax(0, 1fr);
+    grid-template-columns: 240px minmax(0, 820px);
+    justify-content: start;
   }
 
   .toc {
@@ -305,7 +348,7 @@
     width: min(320px, 88vw);
     height: 100vh;
     max-height: none;
-    border-radius: 0 20px 20px 0;
+    border-radius: 0 16px 16px 0;
     transform: translateX(-100%);
     transition: transform 180ms ease-out;
   }
@@ -318,14 +361,14 @@
     position: fixed;
     inset: 0;
     z-index: 50;
-    background: rgba(2, 6, 23, 0.52);
+    background: rgba(15, 23, 42, 0.48);
     display: block;
   }
 }
 
 @media (max-width: 640px) {
   .docsHeader {
-    padding: 16px;
+    padding: 14px 16px;
   }
 
   .docsFrame {
@@ -338,7 +381,17 @@
     gap: 4px;
   }
 
-  .pageDescription {
-    font-size: 0.98rem;
+  .headerActions {
+    width: 100%;
+    justify-content: space-between;
+  }
+
+  .pageTitle {
+    font-size: 2rem;
+  }
+
+  .pageDescription,
+  .paragraph {
+    font-size: 1rem;
   }
 }
diff --git a/frontend/components/docs/__tests__/docsLayoutContrast.test.ts b/frontend/components/docs/__tests__/docsLayoutContrast.test.ts
new file mode 100644
index 00000000..d434824d
--- /dev/null
+++ b/frontend/components/docs/__tests__/docsLayoutContrast.test.ts
@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export function runTests() {
+  const cssPath = path.join(process.cwd(), "components", "docs", "DocsLayout.module.css");
+  const source = fs.readFileSync(cssPath, "utf8");
+
+  assert(
+    source.includes("background:") && source.includes("#f8fbff") && source.includes("#eef4fb"),
+    "docs shell must define a light page background instead of inheriting mixed app styles",
+  );
+  assert(source.includes(".pageTitle") && source.includes("color: #0f172a"), "docs title must use high-contrast dark text");
+  assert(source.includes(".paragraph") && source.includes("color: #334155"), "docs body copy must use readable dark text");
+  assert(source.includes(".sidebar") && source.includes("background: #ffffff"), "docs sidebar must use a solid light surface");
+  assert(source.includes(".toc") && source.includes("background: #ffffff"), "docs table of contents must use a solid light surface");
+  assert(!source.includes("color: rgba(226, 232, 240"), "docs layout must not use dark-theme pale text on a light page");
+}