Skip to content

fix(docs): prevent theme reset to dark after user switches to auto/light#1078

Closed
lifeiyu071 wants to merge 1 commit intocoleam00:devfrom
lifeiyu071:dev
Closed

fix(docs): prevent theme reset to dark after user switches to auto/light#1078
lifeiyu071 wants to merge 1 commit intocoleam00:devfrom
lifeiyu071:dev

Conversation

@lifeiyu071
Copy link
Copy Markdown
Contributor

@lifeiyu071 lifeiyu071 commented Apr 11, 2026 •
edited by coderabbitai Bot
Loading

Summary

  • Problem: The docs site (archon.diy) resets to dark theme on every page refresh or internal navigation after the user switches to "auto" or "light" mode
  • Why it matters: Users cannot use any theme other than dark — their preference is silently discarded on every navigation
  • What changed: The <head> init script now uses a separate archon-theme-init localStorage sentinel instead of checking starlight-theme directly. Starlight deletes starlight-theme when the user selects "auto", which caused the old guard to re-fire and force dark on every load
  • What did not change (scope boundary): No CSS, no Starlight config, no other docs-web files

Label Snapshot

  • Risk: risk: low
  • Size: size: XS
  • Scope: docs
  • Module: docs:theme

Change Metadata

  • Change type: bug
  • Primary scope: docs

Validation Evidence (required)

bun run validate  # all pass (type-check, lint, format, tests)
  • Local Playwright test verified the full flow:
    1. First visit → defaults to dark ✅
    2. Switch to auto → theme changes to light (system default in headless) ✅
    3. Refresh → theme stays light (no longer forced back to dark) ✅

Security Impact (required)

  • New permissions/capabilities? No
  • New external network calls? No
  • Secrets/tokens handling changed? No
  • File system access scope changed? No

Compatibility / Migration

  • Backward compatible? Yes
  • Config/env changes? No
  • Database migration needed? No

Human Verification (required)

  • Verified scenarios: First visit defaults to dark; switching to auto persists across refresh and internal navigation
  • Edge cases checked: localStorage cleared → re-initializes dark (correct first-visit behavior)
  • What was not verified: Live deployment on archon.diy

Side Effects / Blast Radius (required)

  • Affected subsystems/workflows: docs-web theme initialization only
  • Potential unintended effects: None — the sentinel key is independent of Starlight internals
  • Guardrails/monitoring: Visual check on archon.diy after deploy

Rollback Plan (required)

  • Fast rollback: Revert this single commit
  • Observable failure symptoms: Theme not defaulting to dark on first visit

Risks and Mitigations

  • Risk: Existing users who already have starlight-theme in localStorage but no archon-theme-init will see the init script run once more on next visit, setting dark again
    • Mitigation: This is the same as current behavior (one-time), and only affects the very first page load after deploy

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Chores
    • Improved theme initialization logic for better reliability.

@NewsNIng @claude
fix(docs): prevent theme reset to dark after user switches to auto/light
fc4dd42 
Starlight removes the `starlight-theme` localStorage key when the user
selects "auto" mode. The old init script checked that key, so every
navigation or refresh re-forced dark theme. Use a separate
`archon-theme-init` sentinel that persists across theme changes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 11, 2026 •
edited
Loading

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 236a849f-5c5a-434c-9ebe-c44ce709d59f

📥 Commits

Reviewing files that changed from the base of the PR and between 536584d and fc4dd42.

📒 Files selected for processing (1)
  • packages/docs-web/astro.config.mjs
📝 Walkthrough

Walkthrough

Updated the theme initialization check in the Astro configuration to use archon-theme-init as the localStorage key instead of starlight-theme, while maintaining dark theme initialization on first load.

Changes

Cohort / File(s) Summary
Theme Initialization Storage Key
packages/docs-web/astro.config.mjs		 Changed localStorage key from starlight-theme to archon-theme-init for tracking first-run theme setup, while preserving initialization of both storage values and document theme attribute.

Possibly Related PRs

Poem

🐰 A rabbit hops through local storage bright,
Trading old keys for new ones in the night,
Archon-theme-init takes the starlight place,
Dark mode loads with localStorage grace! ✨

Estimated Code Review Effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@lifeiyu071 lifeiyu071 closed this Apr 11, 2026
@Wirasm Wirasm mentioned this pull request Apr 17, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@lifeiyu071 @NewsNIng