fix(docs): prevent theme reset to dark after user switches to auto/light by lifeiyu071 · Pull Request #1079 · coleam00/Archon

lifeiyu071 · 2026-04-11T07:25:44Z

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

Bug Fixes
- Enhanced theme initialization to ensure dark theme settings are properly applied and persisted across page reloads.

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 · 2026-04-11T07:25:57Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c5a1964b-b8a7-466d-bbd5-92c7c4ff12ca

📥 Commits

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

📒 Files selected for processing (1)

packages/docs-web/astro.config.mjs

📝 Walkthrough

Walkthrough

The theme-initialization script in packages/docs-web/astro.config.mjs now checks and sets a new localStorage key (archon-theme-init) instead of starlight-theme to determine whether theme setup has already been executed, while continuing to set both keys during initialization.

Changes

Cohort / File(s)	Summary
Theme Initialization Configuration `packages/docs-web/astro.config.mjs`	Modified the inline theme-initialization script to gate dark theme setup on the new `archon-theme-init` localStorage key instead of `starlight-theme`. The script now sets both `archon-theme-init` and `starlight-theme` when initializing.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

feat(docs): add logo, dark theme, feature cards to docs site #1022: Added the original head script that initializes starlight-theme in astro.config.mjs; this PR refactors the initialization condition to use a dedicated archon-theme-init key instead.

Poem

🐰 A key renamed with care, localStorage now knows,
archon-theme-init guards the dark that glows,
One line out, one line in—the theme dance refined,
Cleaner initialization, peace of mind! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the main bug fix: preventing the theme from resetting to dark after users switch to auto/light mode.
Description check	✅ Passed	The PR description covers all critical sections from the template: clear problem statement, why it matters, what changed, scope boundaries, validation evidence with test results, security impact, compatibility, human verification, side effects, and rollback plan.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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.}

Wirasm · 2026-04-17T15:20:20Z

This PR looks similar to #1078, which was closed on April 11, 2026. You may want to read the discussion there before pushing further.

lifeiyu071 · 2026-04-18T11:11:49Z

@Wirasm Because I accidentally submitted the same issue twice, and the functions to be fixed were actually the same, I closed one of them.

Wirasm merged commit eb730c0 into coleam00:dev Apr 20, 2026
1 check passed

prospapledge88 mentioned this pull request Apr 24, 2026

chore: cherry-pick Tier 1-2 upstream fixes (14 commits) prospapledge88/Archon#6

Open

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

fix(docs): prevent theme reset to dark after user switches to auto/light#1079
Wirasm merged 1 commit intocoleam00:devfrom
lifeiyu071:dev

lifeiyu071 commented Apr 11, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 11, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

Wirasm commented Apr 17, 2026

Uh oh!

lifeiyu071 commented Apr 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

lifeiyu071 commented Apr 11, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Label Snapshot

Change Metadata

Validation Evidence (required)

Security Impact (required)

Compatibility / Migration

Human Verification (required)

Side Effects / Blast Radius (required)

Rollback Plan (required)

Risks and Mitigations

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

Wirasm commented Apr 17, 2026

Uh oh!

lifeiyu071 commented Apr 18, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lifeiyu071 commented Apr 11, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 11, 2026 •

edited

Loading