Align theme toggle with system preference and react to prefers-color-scheme changes

[Copilot]

Theme selection now treats browser/OS preference as the default mode instead of always persisting manual toggles. When a user-selected theme matches prefers-color-scheme, the override is removed so future system changes are reflected automatically.

• Behavior model

  • Introduced explicit resolution flow:
    • stored theme (if different from system) wins
    • otherwise system preference wins
  • Added normalization to clear legacy/local overrides that equal current system preference.

• Toggle semantics

  • Updated toggle handler to persist only true overrides.
  • If the toggled value equals current system preference, localStorage.theme is removed (return to system-following mode).

• Live system theme updates

  • Added matchMedia('(prefers-color-scheme: dark)') change listener.
  • On system theme change, re-applies theme only when no explicit override is stored.

<script>
  var colorSchemeMediaQuery = window.matchMedia('(prefers-color-scheme: dark)');

  function getSystemTheme() {
    return colorSchemeMediaQuery.matches ? 'dark' : 'light';
  }

  function getTheme() {
    return localStorage.getItem('theme') || getSystemTheme();
  }

  document.getElementById('theme-toggle').addEventListener('click', function() {
    var next = document.documentElement.getAttribute('data-bs-theme') === 'dark' ? 'light' : 'dark';
    if (next === getSystemTheme()) localStorage.removeItem('theme');
    else localStorage.setItem('theme', next);
    applyTheme(getTheme());
  });

  colorSchemeMediaQuery.addEventListener('change', function() {
    if (!localStorage.getItem('theme')) applyTheme(getTheme());
  });
</script>

Reference: #174 (comment)

---

📊 Dashboard preview 📊: https://python-docs-translations.github.io/dashboard/186/merge/

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0ed123f91a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[StanFromIreland]

stored theme (if different from system) wins

It always wins?

[m-aciek]

yes, please note we clear it when user changes the theme to the same as system

nothing changes for users that use always light theme or always dark

things change for those who use auto aka follow-the-sun

if you set to light during night, you'll have light in stored, therefore always light

but if you set to dark during night, the theme will start to be auto/follow-the-sun as your OS does (technically we will clear the stored theme, and then || getSystemTheme() will be used)