gavindiaz/PolyWeather
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: improve docs page readability

Browse Source
This commit is contained in:
2569718930@qq.com
2026-06-06 19:52:27 +08:00
parent d354fb12dd
commit 98b69b180a
2 changed files with 168 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/components/docs/DocsLayout.module.css
+147 -94
View File
@@ -1,6 +1,8 @@
.docsShell { .docsShell {
min-height: 100vh; min-height: 100vh;
color: rgba(226, 232, 240, 0.94); background:
linear-gradient(180deg, #f8fbff 0%, #eef4fb 100%);
color: #0f172a;
} }
.docsHeader { .docsHeader {
@@ -11,10 +13,11 @@
align-items: center; align-items: center;
justify-content: space-between; justify-content: space-between;
gap: 16px; gap: 16px;
padding: 18px 24px; padding: 16px 24px;
background: rgba(2, 6, 23, 0.82); background: rgba(255, 255, 255, 0.94);
border-bottom: 1px solid rgba(148, 163, 184, 0.12); border-bottom: 1px solid #d9e3ef;
backdrop-filter: blur(16px); box-shadow: 0 1px 0 rgba(15, 23, 42, 0.04);
backdrop-filter: blur(14px);
} }
.brandWrap { .brandWrap {
@@ -24,15 +27,15 @@
} }
.brandLink { .brandLink {
color: #67e8f9; color: #0891b2;
font-size: 1.9rem; font-size: 1.55rem;
font-weight: 800; font-weight: 800;
text-decoration: none; text-decoration: none;
} }
.brandSubtitle { .brandSubtitle {
color: rgba(148, 163, 184, 0.88); color: #64748b;
font-size: 0.95rem; font-size: 0.92rem;
} }
.headerActions { .headerActions {
@@ -49,23 +52,32 @@
min-height: 38px; min-height: 38px;
padding: 0 14px; padding: 0 14px;
border-radius: 999px; border-radius: 999px;
border: 1px solid rgba(148, 163, 184, 0.18); border: 1px solid #cbd5e1;
background: rgba(15, 23, 42, 0.75); background: #ffffff;
color: rgba(226, 232, 240, 0.95); color: #334155;
text-decoration: none; text-decoration: none;
font-size: 0.92rem; font-size: 0.92rem;
font-weight: 600; font-weight: 700;
cursor: pointer;
transition:
border-color 160ms ease,
color 160ms ease,
background 160ms ease;
} }
.headerGhost { .headerButton:hover,
background: transparent; .headerGhost:hover {
border-color: #38bdf8;
color: #075985;
background: #f0f9ff;
} }
.langSwitch { .langSwitch {
display: flex; display: flex;
border: 1px solid rgba(148, 163, 184, 0.18); border: 1px solid #cbd5e1;
border-radius: 999px; border-radius: 999px;
overflow: hidden; overflow: hidden;
background: #ffffff;
} }
.langButton { .langButton {
@@ -73,60 +85,76 @@
min-height: 38px; min-height: 38px;
border: 0; border: 0;
background: transparent; background: transparent;
color: rgba(148, 163, 184, 0.92); color: #64748b;
font-weight: 700; font-weight: 800;
cursor: pointer;
} }
.langButtonActive { .langButtonActive {
background: rgba(34, 211, 238, 0.16); background: #e0f2fe;
color: #67e8f9; color: #0369a1;
} }
.docsFrame { .docsFrame {
display: grid; display: grid;
grid-template-columns: 280px minmax(0, 1fr) 220px; grid-template-columns: 260px minmax(0, 820px) 220px;
justify-content: center;
gap: 28px; gap: 28px;
width: 100%;
max-width: 1440px;
margin: 0 auto;
padding: 24px; padding: 24px;
} }
.sidebar { .sidebar {
position: sticky; position: sticky;
top: 86px; top: 84px;
align-self: start; align-self: start;
max-height: calc(100vh - 110px); max-height: calc(100vh - 108px);
overflow: auto; overflow: auto;
padding: 20px; padding: 16px;
border: 1px solid rgba(148, 163, 184, 0.12); border: 1px solid #d8e3ef;
border-radius: 20px; border-radius: 16px;
background: rgba(15, 23, 42, 0.72); background: #ffffff;
box-shadow: 0 12px 32px rgba(15, 23, 42, 0.06);
} }
.sidebarGroup + .sidebarGroup { .sidebarGroup + .sidebarGroup {
margin-top: 24px; margin-top: 22px;
} }
.sidebarTitle { .sidebarTitle {
margin: 0 0 10px; margin: 0 0 8px;
color: rgba(148, 163, 184, 0.92); color: #64748b;
font-size: 0.8rem; font-size: 0.78rem;
font-weight: 700; font-weight: 800;
letter-spacing: 0.08em; letter-spacing: 0.06em;
text-transform: uppercase; text-transform: uppercase;
} }
.sidebarLink { .sidebarLink {
display: block; display: block;
margin-bottom: 6px; margin-bottom: 4px;
padding: 10px 12px; padding: 9px 10px;
border-radius: 12px; border-radius: 8px;
color: rgba(226, 232, 240, 0.88); color: #334155;
text-decoration: none; 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 { .sidebarLinkActive {
background: rgba(34, 211, 238, 0.12); background: #e0f2fe;
color: #67e8f9; color: #0369a1;
font-weight: 800;
} }
.content { .content {
@@ -134,80 +162,87 @@
} }
.contentInner { .contentInner {
padding: 12px 0 48px; padding: 16px 0 56px;
} }
.pageTitle { .pageTitle {
margin: 0; margin: 0;
font-size: clamp(2.1rem, 4vw, 3.2rem); color: #0f172a;
font-weight: 800; font-size: clamp(2rem, 4vw, 3.05rem);
letter-spacing: -0.03em; font-weight: 850;
line-height: 1.12;
} }
.pageDescription { .pageDescription {
max-width: 820px; max-width: 760px;
margin: 14px 0 0; margin: 14px 0 0;
color: rgba(191, 219, 254, 0.9); color: #475569;
font-size: 1.03rem; font-size: 1.03rem;
line-height: 1.75; line-height: 1.75;
} }
.section { .section {
margin-top: 40px; margin-top: 40px;
scroll-margin-top: 110px; scroll-margin-top: 104px;
} }
.sectionTitle { .sectionTitle {
margin: 0 0 16px; margin: 0 0 14px;
font-size: 1.65rem; color: #1e293b;
font-weight: 700; font-size: 1.45rem;
font-weight: 800;
line-height: 1.25;
} }
.paragraph { .paragraph {
margin: 0 0 16px; margin: 0 0 15px;
color: rgba(226, 232, 240, 0.94); color: #334155;
line-height: 1.9; font-size: 1rem;
line-height: 1.85;
} }
.callout { .callout {
margin: 18px 0; margin: 20px 0;
padding: 18px 20px; padding: 18px 20px;
border: 1px solid rgba(148, 163, 184, 0.16); border: 1px solid #d8e3ef;
border-radius: 18px; border-radius: 12px;
background: rgba(15, 23, 42, 0.72); background: #ffffff;
box-shadow: 0 8px 24px rgba(15, 23, 42, 0.05);
} }
.calloutInfo { .calloutInfo {
border-color: rgba(34, 211, 238, 0.24); border-color: #bae6fd;
background: rgba(8, 47, 73, 0.26); background: #f0f9ff;
} }
.calloutWarning { .calloutWarning {
border-color: rgba(251, 191, 36, 0.24); border-color: #fde68a;
background: rgba(120, 53, 15, 0.2); background: #fffbeb;
} }
.calloutSuccess { .calloutSuccess {
border-color: rgba(52, 211, 153, 0.24); border-color: #bbf7d0;
background: rgba(6, 78, 59, 0.22); background: #f0fdf4;
} }
.calloutTitle { .calloutTitle {
margin: 0 0 8px; margin: 0 0 8px;
color: #0f172a;
font-size: 0.98rem; font-size: 0.98rem;
font-weight: 700; font-weight: 800;
} }
.calloutText { .calloutText {
margin: 0; margin: 0;
line-height: 1.8; color: #334155;
line-height: 1.75;
} }
.list { .list {
margin: 0; margin: 0 0 16px;
padding-left: 20px; padding-left: 22px;
color: rgba(226, 232, 240, 0.94); color: #334155;
line-height: 1.85; line-height: 1.8;
} }
.list li + li { .list li + li {
@@ -221,52 +256,59 @@
min-height: 42px; min-height: 42px;
padding: 0 16px; padding: 0 16px;
border-radius: 999px; border-radius: 999px;
border: 1px solid rgba(34, 211, 238, 0.34); border: 1px solid #38bdf8;
background: rgba(8, 47, 73, 0.3); background: #e0f2fe;
color: #67e8f9; color: #0369a1;
text-decoration: none; text-decoration: none;
font-weight: 700; font-weight: 800;
} }
.linkCard:hover { .linkCard:hover {
background: rgba(34, 211, 238, 0.12); background: #bae6fd;
} }
.linkCaption { .linkCaption {
margin: 10px 0 0; margin: 10px 0 0;
color: rgba(148, 163, 184, 0.92); color: #64748b;
line-height: 1.75; line-height: 1.7;
} }
.toc { .toc {
position: sticky; position: sticky;
top: 86px; top: 84px;
align-self: start; align-self: start;
padding: 20px; padding: 16px;
border: 1px solid rgba(148, 163, 184, 0.12); border: 1px solid #d8e3ef;
border-radius: 20px; border-radius: 16px;
background: rgba(15, 23, 42, 0.64); background: #ffffff;
box-shadow: 0 12px 32px rgba(15, 23, 42, 0.06);
} }
.tocTitle { .tocTitle {
margin: 0 0 12px; margin: 0 0 10px;
color: rgba(148, 163, 184, 0.92); color: #64748b;
font-size: 0.82rem; font-size: 0.78rem;
font-weight: 700; font-weight: 800;
letter-spacing: 0.08em; letter-spacing: 0.06em;
text-transform: uppercase; text-transform: uppercase;
} }
.tocLink { .tocLink {
display: block; display: block;
color: rgba(226, 232, 240, 0.86); padding: 5px 0;
color: #475569;
text-decoration: none; text-decoration: none;
line-height: 1.7; line-height: 1.55;
font-size: 0.92rem; font-size: 0.92rem;
} }
.tocLink:hover {
color: #0369a1;
}
.mobileMenuButton { .mobileMenuButton {
display: none; display: none;
margin-bottom: 18px;
} }
.mobileSidebarBackdrop { .mobileSidebarBackdrop {
@@ -275,7 +317,8 @@
@media (max-width: 1200px) { @media (max-width: 1200px) {
.docsFrame { .docsFrame {
grid-template-columns: 260px minmax(0, 1fr); grid-template-columns: 240px minmax(0, 820px);
justify-content: start;
} }
.toc { .toc {
@@ -305,7 +348,7 @@
width: min(320px, 88vw); width: min(320px, 88vw);
height: 100vh; height: 100vh;
max-height: none; max-height: none;
border-radius: 0 20px 20px 0; border-radius: 0 16px 16px 0;
transform: translateX(-100%); transform: translateX(-100%);
transition: transform 180ms ease-out; transition: transform 180ms ease-out;
} }
@@ -318,14 +361,14 @@
position: fixed; position: fixed;
inset: 0; inset: 0;
z-index: 50; z-index: 50;
background: rgba(2, 6, 23, 0.52); background: rgba(15, 23, 42, 0.48);
display: block; display: block;
} }
} }
@media (max-width: 640px) { @media (max-width: 640px) {
.docsHeader { .docsHeader {
padding: 16px; padding: 14px 16px;
} }
.docsFrame { .docsFrame {
@@ -338,7 +381,17 @@
gap: 4px; gap: 4px;
} }
.pageDescription { .headerActions {
font-size: 0.98rem; width: 100%;
justify-content: space-between;
}
.pageTitle {
font-size: 2rem;
}
.pageDescription,
.paragraph {
font-size: 1rem;
} }
} }
frontend/components/docs/__tests__/docsLayoutContrast.test.ts
+21
View File
@@ -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");
}