Skip to content

Polish typography for GitHub-like font rendering and spacing #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
justin808 wants to merge 4 commits into from
Closed

Polish typography for GitHub-like font rendering and spacing #46

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9fdd566
Polish typography for a tighter GitHub-like reading experience
justin808 Mar 21, 2026
c171cac
Keep original font sizes/weights, add structural typography improvements
justin808 Mar 21, 2026
a3169b1
Fix dark-mode soft-surface color matching page background
justin808 Mar 21, 2026
bea8add
Fix sidebar toggle arrow rendering as black square
justin808 Mar 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 65 additions & 1 deletion prototypes/docusaurus/src/css/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,10 @@
--docusaurus-highlighted-code-line-bg: rgba(47, 129, 247, 0.2);
--site-border: #30363d;
--site-surface: #161b22;
--site-soft-surface: #0d1117;
--site-soft-surface: #161b22;
Copy link
Copy Markdown

@cursor cursor bot Mar 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dark mode soft-surface equals surface, losing hover contrast

Medium Severity

In dark mode, --site-soft-surface was changed to #161b22, which is now identical to --site-surface (#161b22). This eliminates visible hover feedback on .button--secondary:hover (which transitions from --site-surface to --site-soft-surface) and the newly added .menu__link:hover (which sets --site-soft-surface against the sidebar's --ifm-background-surface-color, also #161b22). Both hover states become invisible in dark mode.

Additional Locations (1)
Fix in Cursor Fix in Web

--site-inline-code-surface: #161b22;
--site-inline-code-text: #c9d1d9;
--ifm-menu-link-sublist-icon-filter: invert(1);
}

html,
Expand All @@ -63,6 +64,8 @@ body {
-moz-osx-font-smoothing: grayscale;
}

/* ── Navbar ───────────────────────────────────────────────── */

.navbar {
border-bottom: 1px solid var(--site-border);
box-shadow: none;
Expand All @@ -77,10 +80,14 @@ body {
font-weight: 500;
}

/* ── Footer ───────────────────────────────────────────────── */

.footer {
border-top: 1px solid var(--site-border);
}

/* ── Sidebar ──────────────────────────────────────────────── */

.theme-doc-sidebar-container {
border-right: 1px solid var(--site-border);
}
Expand All @@ -92,25 +99,82 @@ body {
font-weight: 500;
}

.menu__link:hover {
background: var(--site-soft-surface);
Copy link
Copy Markdown

@cursor cursor bot Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hover overrides active sidebar link in light mode

Medium Severity

The new .menu__link:hover rule has CSS specificity (0,2,0) which is higher than .menu__link--active at (0,1,0). In light mode, hovering over the active sidebar link replaces its distinctive blue background with the generic grey --site-soft-surface hover background, losing the visual active-link indicator. The dark mode variant is unaffected because [data-theme='dark'] .menu__link--active raises specificity to (0,2,0) and wins by source order.

Additional Locations (1)
Fix in Cursor Fix in Web

}

.menu__link--active {
background: rgba(9, 105, 218, 0.1);
color: var(--ifm-color-primary-dark);
font-weight: 600;
}

.menu__list-item-collapsible .menu__link {
font-weight: 600;
color: var(--ifm-color-content);
Comment on lines +112 to +114
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot Mar 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve active styling for linked sidebar categories

For any category that has a link in prototypes/docusaurus/sidebars.ts (for example Getting Started, Core Concepts, and Historical Reference), Docusaurus renders the category label as an active .menu__link--active inside .menu__list-item-collapsible. This new selector is both later and more specific than .menu__link--active, so on those category index pages it resets the label color back to var(--ifm-color-content) in light mode. The result is that category landing pages no longer get the active-color treatment that ordinary doc pages still have, which makes the current location in the sidebar much harder to see.

Useful? React with 👍 / 👎.

}

[data-theme='dark'] .menu__link--active {
background: rgba(47, 129, 247, 0.18);
color: #c9d1d9;
}

/* ── Markdown typography ──────────────────────────────────── */

.markdown h1 {
padding-bottom: 0.3em;
border-bottom: 1px solid var(--site-border);
}

.markdown h2 {
padding-bottom: 0.3em;
border-bottom: 1px solid var(--site-border);
}

.markdown code {
background: var(--site-inline-code-surface);
border: 1px solid var(--site-border);
border-radius: 6px;
padding: 0.2em 0.4em;
font-family: var(--ifm-font-family-monospace);
color: var(--site-inline-code-text);
}

/* ── Blockquotes ──────────────────────────────────────────── */

.markdown blockquote {
border-left: 0.25rem solid var(--site-border);
color: var(--ifm-color-content-secondary);
padding: 0 1em;
margin: 0 0 1rem;
background: none;
}

/* ── Tables ────────────────────────────────────────────────── */

.markdown table {
display: block;
width: max-content;
max-width: 100%;
overflow: auto;
}

.markdown th {
font-weight: 600;
}

.markdown th,
.markdown td {
padding: 0.4rem 0.8rem;
border: 1px solid var(--site-border);
}

.markdown tr:nth-child(2n) {
background: var(--site-soft-surface);
}

/* ── Pagination & misc ────────────────────────────────────── */

.pagination-nav__link {
border: 1px solid var(--site-border);
border-radius: 8px;
Expand Down
Loading