Implement optional dark mode for the documentation site by Copilot · Pull Request #230 · drasi-project/docs

Copilot · 2026-06-04T02:52:10Z

Adds an optional light/dark theme toggle to the docs site. Builds on the approach from #229 but uses Docsy v0.13.0's built-in dark mode (no theme upgrade required — the submodule is already on v0.13.0), and preserves Drasi's distinctive always-dark code blocks. Light mode is the default; dark mode is opt-in via the navbar toggle.

Changes

Enable the toggle — showLightDarkModeMenu = true in config.toml surfaces the navbar light/dark/auto switch.
Default to light mode — an overridden docs/assets/js/dark-mode.js makes light the default theme, and an early inline script in the head-end.html hook forces light before paint when no preference is stored. The OS prefers-color-scheme is intentionally ignored for the default (it's only honoured when the visitor explicitly picks "auto"). Both spots are needed because Docsy v0.13 otherwise falls back to the OS preference in both the deferred JS and the inline FOUC script.
FOUC prevention — the project's overridden docs/baseof.html was missing Docsy's data-theme-init on <html>; added it to mirror upstream and avoid a flash of the wrong theme on load.
Lighten the brand navy — $lighten-amount-for-dark-color-variant: 30% plus an import of Docsy's td/color-adjustments-dark, so the deep-navy $primary is legible as links/accents on a dark canvas.
Adapt custom components — a scoped [data-bs-theme="dark"] block overrides the ~35 Drasi components that hard-code $primary as a foreground colour (card/content titles, the hero/h1 gradient, h3-based card titles, nav accents, CTA buttons, learning-path/blockquote surfaces, related-content links).
Readable secondary text in dark mode — muted/secondary greys ($gray-600/$gray-700) used for section intros, captions, taglines and descriptions are lightened to $gray-400/$gray-300 so they stay legible on the dark canvas.
Visible flow-diagram boxes — the "How Drasi Works" .flow-step boxes (also used on the Drasi Server getting started page) used a deep-navy border that disappeared on dark; in dark mode they now get an elevated surface, a visible border and a shadow.
Theme-aware shortcode — scrollable-code.html container swaps hard-coded light colours for var(--bs-border-color) / var(--bs-tertiary-bg).

Preserved style choices

Always-dark Dracula code blocks in both modes (the deliberate choice carried over from Dark mode #229) — Docsy's td/code-dark is intentionally not imported.
Diátaxis accent colours (orange Concepts / purple Reference) stay intact in dark mode; the base-icon override is scoped to non-variant cards via :not([class*="unified-card--"]).

Notes for reviewers

The h3 fix is the non-obvious one: Diátaxis card titles render as <h3 class="unified-card-title">, and .td-content h3 { color: darken($primary,5%) } out-specifies the --bs-heading-color variable — so the dark block targets .td-content h3 directly rather than relying on the heading-colour var alone.

[data-bs-theme="dark"] {
  --bs-heading-color: #{$gray-100};

  .td-content h3 { color: $gray-100; }            // also covers card titles

  .td-content h1,
  .hero-title {                                    // navy gradient → light gradient
    background: linear-gradient(135deg, $gray-100 0%, lighten($secondary, 5%) 100%);
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    background-clip: text;
  }
}

agentofreality · 2026-06-04T05:03:06Z

@copilot

The default mode should remain light mode.

In dark mode, some elements are not rendering well.

The attached image is from the Home Page. The text under the headings is to hard to see in dark mode, and the boxes used in the diagram in the "How Drasi Works" section cannot be seen properly.

The same diagram with the same problem exists on the Drasi Server Getting Started Page.

Copilot · 2026-06-04T05:18:12Z

@copilot

The default mode should remain light mode.
...

Fixed in 4e3c1f4 (see latest commit on the branch):

Light is now the default — the site only switches to dark when a visitor explicitly picks it from the toggle; the OS prefers-color-scheme is no longer used for the default. This is enforced both before paint (head hook) and in the theme script, so there's no flash of dark mode on OS-dark devices.
Text under headings — the muted/secondary greys (section intros, captions, taglines, etc.) were hard-coded light-mode $gray-600/$gray-700; they're now lightened in dark mode so they're readable.
"How Drasi Works" diagram boxes — the box border used a deep-navy that was invisible on the dark canvas. In dark mode the boxes now get a visible elevated surface, border and shadow. The same shortcode drives the Drasi Server getting started page, so that diagram is fixed too.

Verified with a local Hugo build + browser check in both modes.

@copilot

The default mode should remain light mode.
...

Correction: the commit is 8edce96 (I mistyped the hash above).

Copilot

Pull request overview

This PR adds an opt-in light/dark theme toggle to the Drasi documentation site using Docsy/Bootstrap’s built-in color modes, while preserving the site’s always-dark Dracula code-block styling. It updates configuration, early theme initialization (to prevent FOUC), and introduces dark-mode-specific styling overrides for Drasi’s custom components.

Changes:

Enable Docsy’s navbar theme toggle and force “light” as the default unless the visitor explicitly chooses otherwise.
Add a Docsy/Bootstrap-derived dark-mode.js override and ensure the <html> element participates in Docsy’s theme initialization flow.
Introduce dark-mode SCSS adjustments for headings, cards, navigation accents, muted text, and specific custom components (e.g., flow-step boxes), plus theme-variable usage in the scrollable-code shortcode.

Reviewed changes

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

Show a summary per file

File	Description
docs/layouts/shortcodes/scrollable-code.html	Uses Bootstrap CSS variables for theme-aware border/background in the shortcode container.
docs/layouts/partials/hooks/head-end.html	Adds an early inline script to default to light theme when no stored preference exists (FOUC mitigation).
docs/layouts/docs/baseof.html	Adds Docsy theme-init attribute gating (but currently uses `partialCached` incorrectly).
docs/config.toml	Enables Docsy’s light/dark/auto toggle menu in the navbar.
docs/assets/scss/_variables_project.scss	Sets the dark-mode primary lighten amount used by Docsy dark adjustments.
docs/assets/scss/_styles_project.scss	Imports Docsy dark color adjustments and adds extensive `[data-bs-theme="dark"]` overrides for custom components.
docs/assets/js/dark-mode.js	Adds a Docsy-adapted Bootstrap color-mode toggler that defaults to light mode.

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

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

ruokun-niu · 2026-06-10T23:55:30Z

@copilot

The borderline for the Why Drasi button is hard to see in dark mode

Copilot · 2026-06-10T23:58:02Z

@copilot

The borderline for the Why Drasi button is hard to see in dark mode
...

Fixed in 53c5ba3.

I updated dark-mode styling for .cta-button--secondary to set an explicit green border color in the default (non-hover) state so the Why Drasi button outline is clearly visible on dark backgrounds.

Initial plan

2b2ad0b

Copilot AI assigned Copilot and agentofreality Jun 4, 2026

Copilot AI requested review from Copilot and removed request for Copilot June 4, 2026 02:52

Copilot started work on behalf of agentofreality June 4, 2026 02:52 View session

Copilot AI linked an issue Jun 4, 2026 that may be closed by this pull request

Dark Mode #228

Closed

Implement optional dark mode for the docs site

975596c

Copilot AI requested review from Copilot and removed request for Copilot June 4, 2026 03:15

Copilot AI changed the title ~~[WIP] Implement dark mode on documentation site~~ Implement optional dark mode for the documentation site Jun 4, 2026

Copilot finished work on behalf of agentofreality June 4, 2026 03:17

Copilot AI requested a review from agentofreality June 4, 2026 03:17

Copilot started work on behalf of agentofreality June 4, 2026 05:03 View session

Default to light mode and fix dark-mode contrast issues

8edce96

Copilot AI requested review from Copilot and removed request for Copilot June 4, 2026 05:16

Copilot finished work on behalf of agentofreality June 4, 2026 05:19

agentofreality marked this pull request as ready for review June 4, 2026 05:23

agentofreality requested a review from a team as a code owner June 4, 2026 05:23

Copilot AI review requested due to automatic review settings June 4, 2026 05:23

Copilot started reviewing on behalf of agentofreality June 4, 2026 05:23 View session

agentofreality mentioned this pull request Jun 4, 2026

Dark mode #229

Closed

Copilot AI reviewed Jun 4, 2026

View reviewed changes

Comment thread docs/layouts/docs/baseof.html Outdated

Comment thread docs/assets/js/dark-mode.js Outdated

Comment thread docs/assets/js/dark-mode.js

Merge branch 'main' into copilot/implement-dark-mode

327c0dc

agentofreality marked this pull request as draft June 8, 2026 23:53

agentofreality and others added 2 commits June 10, 2026 09:44

Potential fix for pull request finding

f7a33fa

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

de97099

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

agentofreality and others added 2 commits June 10, 2026 09:44

Potential fix for pull request finding

43839f4

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Merge branch 'main' into copilot/implement-dark-mode

00a81f9

agentofreality marked this pull request as ready for review June 10, 2026 16:51

NValsan approved these changes Jun 10, 2026

View reviewed changes

Copilot started work on behalf of ruokun-niu June 10, 2026 23:55 View session

fix: improve dark mode visibility for secondary CTA border

53c5ba3

Copilot finished work on behalf of ruokun-niu June 10, 2026 23:58

Copilot AI requested a review from ruokun-niu June 10, 2026 23:58

ruokun-niu approved these changes Jun 11, 2026

View reviewed changes

Merge branch 'main' into copilot/implement-dark-mode

a4aa4c9

agentofreality merged commit ac43b7b into main Jun 11, 2026
4 checks passed

agentofreality deleted the copilot/implement-dark-mode branch June 11, 2026 04:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Implement optional dark mode for the documentation site#230

Implement optional dark mode for the documentation site#230
agentofreality merged 10 commits into
mainfrom
copilot/implement-dark-mode

Copilot AI commented Jun 4, 2026 •

edited

Loading

Uh oh!

agentofreality commented Jun 4, 2026

Uh oh!

Copilot AI commented Jun 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ruokun-niu commented Jun 10, 2026

Uh oh!

Copilot AI commented Jun 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

Copilot AI commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Preserved style choices

Notes for reviewers

Uh oh!

agentofreality commented Jun 4, 2026

Uh oh!

Copilot AI commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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!

ruokun-niu commented Jun 10, 2026

Uh oh!

Copilot AI commented Jun 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Copilot AI commented Jun 4, 2026 •

edited

Loading

Copilot AI commented Jun 4, 2026 •

edited

Loading