Skip to content

Add light theme support to docs site (toggle + OS preference detection) #93

@dleshchev

Description

@dleshchev

Problem

The DAQIRI docs site at https://nvidia.github.io/daqiri/ is dark-only across both rendering paths:

  • MkDocs Material pages (/getting-started/, /configuration/, /api-guide/, tutorials) — mkdocs.yml declares both slate and default palettes with toggle icons, but docs/stylesheets/extra.css scopes every NVIDIA-branded override to [data-md-color-scheme="slate"]. Toggling to light strips all branding and falls back to stock Material.
  • Hand-written landing page (/) — docs/index.html hard-codes dark hex values via CSS variables (--bg-dark:#0a0a0a, etc.) with no light variant.

Visitors get dark mode regardless of their OS preference or personal preference, and there's no discoverable way to switch.

Proposed change

Add proper light-theme support to both rendering paths, defaulting to the visitor's OS prefers-color-scheme and exposing a manual toggle that persists across pages.

Scope:

  • mkdocs.yml — change palette toggles to use media: "(prefers-color-scheme: dark|light)" so the default follows OS preference. Keep toggle icons for manual override.
  • docs/stylesheets/extra.css — mirror every [data-md-color-scheme="slate"] rule with a [data-md-color-scheme="default"] counterpart. Retune NVIDIA green for white backgrounds (pure #76b900 fails WCAG AA on white for body text — use #5a8f00 for link text; keep #76b900 for buttons/badges on contrasting backgrounds). Retune code-block syntax colors (current palette is tuned for dark backgrounds).
  • docs/index.html — tokenize the ~15 inlined hex values currently outside the CSS-variable system; add [data-theme="dark"|"light"] selectors; inline a pre-body <script> that reads localStorage.getItem("data-md-color-scheme") (Material's storage key, so the toggle syncs with MkDocs pages) and falls back to prefers-color-scheme. Add a sun/moon button to #navbar.

Out of scope

  • docs/daqiri-api.html — being removed by [DOC] Add API documentation for Python bindings #69 (docs/api-reference-flow). This issue is gated on that branch landing first to avoid double conflict resolution on the three shared files (index.html, extra.css, mkdocs.yml).

Verification

  • mkdocs build --strict passes.
  • Manual visual pass across all pages in both themes; confirm toggle persists across MkDocs ↔ landing-page navigation.
  • Contrast check (Lighthouse / axe) on light theme, especially green-on-white surfaces.
  • Verify OS prefers-color-scheme is honored in an incognito window (no localStorage set).
  • Test in Chrome, Firefox, and Safari.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions