feat: Add dark mode support and CSS improvements #15753

White-Devil2839 · 2025-11-18T05:32:38Z

Summary

This PR adds comprehensive CSS improvements to the Mongoose documentation, including dark mode support, accessibility enhancements, and responsive design improvements. The changes improve the user experience across all devices and provide users with manual control over their preferred theme.

Motivation

The Mongoose documentation currently only supports light mode and lacks some modern accessibility features. This PR addresses:

User requests for dark mode support
Accessibility improvements (WCAG compliance)
Better mobile/tablet experience
Enhanced code readability with improved syntax highlighting

Changes Made

✅ Dark Mode Support: Added automatic dark mode detection via prefers-color-scheme media query
✅ Theme Toggle Button: Added manual theme toggle button in top-left corner with localStorage persistence
✅ CSS Custom Properties: Implemented CSS variables for easy theming and maintenance
✅ Accessibility Improvements: Enhanced focus states, contrast ratios, and ARIA support
✅ Responsive Design: Improved breakpoints for mobile, tablet, and desktop
✅ Code Block Styling: Better syntax highlighting with dark mode support
✅ Print Stylesheet: Optimized styles for printing
✅ Mobile Navigation: Enhanced mobile menu styling and interactions
✅ API Navigation: Improved sidebar responsiveness

Examples

Before:

Only light mode available
No manual theme control
Basic focus states
Limited responsive breakpoints

After:

Automatic dark mode based on system preference
Manual theme toggle button (top-left)
Enhanced accessibility with visible focus indicators
Better responsive design across all screen sizes
Improved code block readability in both themes

Files Changed

docs/css/mongoose5.css - Main documentation styles with dark mode and theme toggle
docs/css/api.css - API page styles with responsive improvements
docs/css/github.css - Syntax highlighting with dark mode support
docs/css/style.css - Homepage styles with dark mode
docs/js/theme-toggle.js - Theme toggle functionality (new file)
docs/layout.pug - Added theme toggle button to documentation pages
index.pug - Added theme toggle button and mongoose5.css to homepage
docs/api_split.pug - Added cache-busting query parameters

Testing

Notes

All changes are backward compatible
CSS variables include fallbacks for older browsers
Theme preference persists across page reloads via localStorage
Follows existing code style guidelines (2 spaces, no trailing whitespace)
No generated HTML files included (ran npm run docs:clean)
Only source files (CSS, JS, PUG) are modified

- Add CSS custom properties for theming - Implement dark mode with prefers-color-scheme and manual toggle - Add theme toggle button in top-left corner with localStorage persistence - Improve accessibility with focus states and contrast ratios - Enhance responsive design with better breakpoints - Improve code block styling with dark mode syntax highlighting - Add print stylesheet optimizations - Improve mobile navigation styling - Enhance API navigation sidebar responsiveness

White-Devil2839 · 2025-11-18T05:38:21Z

@vkarpov15 can you approve this please.

Copilot

Pull request overview

This PR adds comprehensive dark mode support to the Mongoose documentation with a manual theme toggle, improving accessibility and user experience. The implementation uses CSS custom properties for theming, supports both system preferences and manual selection, and includes responsive design improvements across all device sizes.

Key Changes:

Dark mode implementation with three-state theme toggle (system/dark/light) using localStorage persistence
CSS custom properties system for consistent theming across light and dark modes
Enhanced accessibility with improved focus states, WCAG-compliant contrast ratios, and keyboard navigation support

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
`index.pug`	Added theme toggle button, mongoose5.css inclusion, and cache-busting query parameters to homepage
`docs/layout.pug`	Added theme toggle button and theme-toggle.js script to documentation layout with cache-busting
`docs/js/theme-toggle.js`	New file implementing three-state theme toggle with localStorage persistence
`docs/css/style.css`	Added dark mode support, theme toggle button styles, and enhanced code block styling for homepage
`docs/css/mongoose5.css`	Comprehensive theming system with CSS custom properties, dark mode support, responsive improvements, and print styles
`docs/css/github.css`	Added dark mode syntax highlighting colors and improved code block styling with transitions
`docs/css/api.css`	Enhanced API navigation with dark mode support, custom scrollbars, and responsive breakpoints
`docs/api_split.pug`	Added cache-busting query parameter to API CSS

Comments suppressed due to low confidence (1)

docs/js/theme-toggle.js:29

Unused variable theme.

    const theme = document.documentElement.getAttribute('data-theme');

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/js/theme-toggle.js

docs/css/style.css

docs/css/github.css

docs/css/mongoose5.css

index.pug

docs/layout.pug

docs/js/theme-toggle.js

docs/layout.pug

docs/api_split.pug

index.pug

docs/css/style.css

docs/js/theme-toggle.js

hasezoey

Thanks for implementing this, but there are many nitpicks i have:

I basically agree with all of Copilot's points
Isnt there some kind of option to de-duplicate @media color queries and data-theme queries?
Is body.code-theme-dark really necessary?
The Theme toggle button should reflect the state of "system" instead of keeping the previous button

Aside from those broad things, some issues i have noticed (they are collapsed to not spam the thread)

Issue Screenshots

Homepage

They are all dark-theme related issues:

Homepage buttons's radius somehow has white:

Homepage code overlaps:

Github Sponsers have weird checkered line around them:

The tagline is hard to read:

External buttons are still white:

Docs Guides (& API)

While in dark mode, the version selector is still white:

The left sidebar text is, in my opinion, way too similar to the background (especially if it has class selected), maybe boost it a bit more in the white direction?:

Docs API

Due to the right TOC bar now having a different color than the rest of the page, the text should be padded on the left side:

In any mode, it is way too blue:

For comparison, in the current live side, basically all visible blue is a red (which i think is more pleasant on the eyes) and there is a difference between code: color(red) and pre code: color(grey) (note that both do not contain any hljs classes)

Other

The system button should maybe look something along the lines of what docusaurus does:

hasezoey · 2025-12-01T12:08:40Z

docs/css/mongoose5.css

+/* Light mode override */
+[data-theme="light"] {
+  --bg-primary: #ffffff;
+  --bg-secondary: #eee;
+  --bg-tertiary: #fafafa;
+  --text-primary: #000000;
+  --text-secondary: #333333;
+  --text-muted: #777777;
+  --link-color: #0971B2;
+  --link-hover: #065a8f;
+  --border-color: #ddd;
+  --code-bg: #f5f5f5;
+  --code-text: #333;
+  --menu-bg: #eee;
+  --menu-hover: rgba(0,0,0, 0.1);
+  --menu-selected: rgba(0,0,0, 0.15);
+  --shadow: rgba(0, 0, 0, 0.1);
+  --focus-ring: #0971B2;
+}


Is this duplication (compared to the :root definition) really necessary? Wouldnt [data-theme="light"] {}(empty) just use the ones defined in :root?

Sorry for the issues and late reply @hasezoey and @vkarpov15 I will try to update it as soon as possible and will also resolve all the issues and will check everything before pushing this time so that nothing would be left,
also can you assign this issue to me as I’ve been working through the related code recently, so I can address it efficiently and ensure a clean, complete fix.

hasezoey · 2025-12-01T12:11:03Z

docs/css/mongoose5.css

+@media (prefers-color-scheme: dark) {
+  .search input:focus {
+    box-shadow: 0 0 0 2px rgba(74, 158, 255, 0.2);
+  }


Unless i missed something, shouldnt this also be applied to data-theme="dark"?

docs/js/theme-toggle.js

hasezoey · 2025-12-01T12:51:30Z

Additionally, i just tried the print mode, consider removing the underlines on headers and maybe also adding links to relative paths (api/something):

Co-authored-by: Copilot <[email protected]>

Removed version query parameter from API CSS link.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 16 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/layout.pug

docs/css/style.css

docs/css/api.css

docs/css/mongoose5.css

docs/css/github.css

Co-authored-by: Copilot <[email protected]>

vkarpov15

Wow this PR had a lot of issues. I made a bunch of fixes and improvements, likely a few things I missed but should be good enough to merge and test more locally before release.

This comment was marked as spam.

Sign in to view

vkarpov15 requested a review from Copilot November 25, 2025 21:46

Copilot started reviewing on behalf of vkarpov15 November 25, 2025 21:47 View session

Merge branch 'master' into master

f48de5b

Copilot finished reviewing on behalf of vkarpov15 November 25, 2025 21:49

Copilot AI reviewed Nov 25, 2025

View reviewed changes

vkarpov15 requested changes Nov 25, 2025

View reviewed changes

docs/css/style.css Outdated Show resolved Hide resolved

docs/js/theme-toggle.js Outdated Show resolved Hide resolved

Fix: Requested changes

49200a1

White-Devil2839 requested a review from vkarpov15 November 28, 2025 10:56

hasezoey requested changes Dec 1, 2025

View reviewed changes

hasezoey added the docs This issue is due to a mistake or omission in the mongoosejs.com documentation label Dec 1, 2025

hasezoey mentioned this pull request Dec 1, 2025

Update homepage style #15775

Open

vkarpov15 and others added 9 commits December 2, 2025 20:46

Update docs/api_split.pug

3f5e6e9

Co-authored-by: Copilot <[email protected]>

Update API CSS link in api_split.pug

dc35cfa

Removed version query parameter from API CSS link.

Change logo text color and adjust theme toggle position

fddbf21

Remove cache-busting query parameters from CSS links

8af7b0b

Adjust theme toggle button position

72150d3

Refactor theme toggle functions for improved clarity

17d3adf

Refactor theme styles for dark and light modes

8144b3f

Refactor dark mode styles for syntax highlighting

5bbe4ad

Refactor theme toggle logic for body class

032ac69

vkarpov15 requested a review from Copilot December 4, 2025 21:23

Copilot started reviewing on behalf of vkarpov15 December 4, 2025 21:23 View session

Copilot finished reviewing on behalf of vkarpov15 December 4, 2025 21:27

Copilot AI reviewed Dec 4, 2025

View reviewed changes

Update docs/css/github.css

68757db

Co-authored-by: Copilot <[email protected]>

vkarpov15 and others added 2 commits December 4, 2025 17:16

Update docs/css/mongoose5.css

3398f0c

Co-authored-by: Copilot <[email protected]>

Update docs/js/theme-toggle.js

e2464af

Co-authored-by: Copilot <[email protected]>

vkarpov15 approved these changes Dec 4, 2025

View reviewed changes

vkarpov15 added this to the 9.0.1 milestone Dec 4, 2025

vkarpov15 merged commit 9d094b3 into Automattic:master Dec 4, 2025
2 checks passed

AbdelrahmanHafez mentioned this pull request Dec 5, 2025

chore: fix lint #15876

Open

Uh oh!

feat: Add dark mode support and CSS improvements #15753

feat: Add dark mode support and CSS improvements #15753

Conversation

White-Devil2839 commented Nov 18, 2025

Uh oh!

White-Devil2839 commented Nov 18, 2025

Uh oh!

This comment was marked as spam.

This comment was marked as spam.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hasezoey left a comment

Choose a reason for hiding this comment

Homepage

Docs Guides (& API)

Docs API

Other

Uh oh!

hasezoey Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

White-Devil2839 Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

hasezoey Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hasezoey commented Dec 1, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vkarpov15 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants