Skip to content

Add docs site dark mode#322

Merged
steipete merged 2 commits into
openclaw:mainfrom
joshka:joshka/docs-site-dark-mode
Jun 19, 2026
Merged

Add docs site dark mode#322
steipete merged 2 commits into
openclaw:mainfrom
joshka:joshka/docs-site-dark-mode

Conversation

@joshka

@joshka joshka commented Jun 18, 2026

Copy link
Copy Markdown
Contributor

Summary

  • add a system/light/dark theme switcher to the generated Pages docs site
  • apply the theme before paint and keep theme-color in sync
  • move the picker into the sidebar footer so it stays subtle and out of the primary docs nav

Validation

  • node scripts/build-docs-site.mjs
  • pnpm run format:check
  • pnpm run lint:scripts
  • in-app browser check at 1280x720 and 390x844
  • representative WCAG contrast audit for light and dark theme text/background pairs

@clawsweeper

clawsweeper Bot commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed June 18, 2026, 5:29 PM ET / 21:29 UTC.

Summary
The branch modifies scripts/build-docs-site.mjs to add a system/light/dark docs-site theme picker, early theme application, theme-color updates, and dark-theme CSS variables.

Reproducibility: not applicable. this is a docs-site feature PR rather than a reported bug. Source review confirms the current main generator does not already provide a theme picker.

Review metrics: 1 noteworthy metric.

  • Diff surface: 1 file modified, 188 additions, 51 deletions. The change is contained to the generated docs-site builder, which keeps the review and rollback surface narrow.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Add screenshots or a short recording showing system, light, and dark theme switching at desktop and mobile sizes.
  • Redact private details from proof artifacts before posting them in the PR body.

Proof guidance:

  • [P1] Needs real behavior proof before merge: The PR body lists manual checks but does not attach inspectable after-fix proof; add redacted screenshots or a short recording in the PR body to trigger a fresh review, or ask a maintainer for @clawsweeper re-review if needed. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Mantis proof suggestion
The visible docs-site theme picker is a good fit for browser visual proof if a maintainer wants independent confirmation. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: verify the docs site theme picker switches system, light, and dark modes without flash or layout overlap on desktop and mobile.

Risk before merge

  • [P1] Contributor real behavior proof is absent; the PR body states browser and contrast checks but does not attach inspectable after-fix screenshots, recordings, terminal output, or logs.
  • [P1] This is a new visible docs-site preference, so maintainers still need to accept the product and visual direction before merge.

Maintainer options:

  1. Decide the mitigation before merge
    Merge a narrow docs-site theme picker after maintainers accept the UX direction and the contributor adds visible after-fix proof for desktop and mobile.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

  • [P1] The remaining action is contributor proof plus maintainer UX acceptance; there is no concrete branch repair for ClawSweeper to perform.

Security
Cleared: The one-file docs generator diff adds inline theme code and CSS variables, with no dependency, workflow, permission, secret, or package-resolution changes.

Review details

Best possible solution:

Merge a narrow docs-site theme picker after maintainers accept the UX direction and the contributor adds visible after-fix proof for desktop and mobile.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a docs-site feature PR rather than a reported bug. Source review confirms the current main generator does not already provide a theme picker.

Is this the best way to solve the issue?

Likely yes; keeping the implementation localized to the docs-site generator is the narrow maintainable path. Merge should still wait for visible proof and maintainer acceptance of the visual direction.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against a6ee02e323c1.

Label changes

Label changes:

  • add P3: The PR is a low-risk docs-site usability enhancement rather than a core runtime, security, or automation fix.
  • add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
  • add status: 🛠️ actively grinding: The PR author has acted after the latest ClawSweeper review and work remains. Needs real behavior proof before merge: The PR body lists manual checks but does not attach inspectable after-fix proof; add redacted screenshots or a short recording in the PR body to trigger a fresh review, or ask a maintainer for @clawsweeper re-review if needed. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

  • P3: The PR is a low-risk docs-site usability enhancement rather than a core runtime, security, or automation fix.
  • rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
  • status: 🛠️ actively grinding: The PR author has acted after the latest ClawSweeper review and work remains. Needs real behavior proof before merge: The PR body lists manual checks but does not attach inspectable after-fix proof; add redacted screenshots or a short recording in the PR body to trigger a fresh review, or ask a maintainer for @clawsweeper re-review if needed. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed

What I checked:

  • Repository policy read: AGENTS.md was read fully and its conservative read-only review guidance applies to this PR review. (AGENTS.md:1, a6ee02e323c1)
  • PR diff scope: The diff changes one generated docs-site builder file and adds the theme control, early init script, CSS variables, and runtime button handlers. (scripts/build-docs-site.mjs:405, f4edfe30d9e3)
  • Head implementation: The head file inserts themeInitScript() before the generated CSS, defines system/light/dark buttons in the sidebar footer, and updates localStorage, data-theme, and theme-color after load. (scripts/build-docs-site.mjs:424, f4edfe30d9e3)
  • Current main behavior: Current main has only the static docs-site theme-color and sidebar footer links; no existing theme picker or saved theme behavior appears in the generator. (scripts/build-docs-site.mjs:408, a6ee02e323c1)
  • Proof check: The PR body lists build, format, lint, browser, and contrast checks, but the PR has no attached screenshots, recordings, terminal output, linked artifacts, or reviewer-visible logs. (f4edfe30d9e3)
  • Docs generator history: The current layout, sidebar footer, and CSS block in scripts/build-docs-site.mjs trace to the v0.3.0 release commit, with the docs-site generator originally introduced by an earlier Pages deployment commit. (scripts/build-docs-site.mjs:389, dc824915bb6c)

Likely related people:

  • Peter Steinberger: Git blame and history attribute the existing docs-site generator, layout, sidebar footer, CSS block, and Pages workflow setup to commits associated with this person. (role: introduced current docs-site generator; confidence: high; commits: 43d2232ac821, dc824915bb6c; files: scripts/build-docs-site.mjs, .github/workflows/pages.yml)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 🛠️ actively grinding The PR author has acted after the latest ClawSweeper review and work remains. labels Jun 18, 2026
@joshka

joshka commented Jun 18, 2026

Copy link
Copy Markdown
Contributor Author

Corrected dark mode screenshot from local Pages build (1920x1080, top of page):

ClawSweeper docs dark mode at 1920x1080

joshka and others added 2 commits June 19, 2026 07:44
@joshka @steipete
Add docs site dark mode
67e6ece 
Add a system-aware theme switcher to the generated Pages site so users can choose system, light, or dark display modes.
@steipete
test: cover docs theme output
fe2f578
@steipete
steipete force-pushed the joshka/docs-site-dark-mode branch from f4edfe3 to fe2f578 Compare June 19, 2026 11:45
@steipete
steipete merged commit 471bf80 into openclaw:main Jun 19, 2026
1 check passed
@steipete

steipete commented Jun 19, 2026

Copy link
Copy Markdown
Contributor

Landed after maintainer product approval and verification.

Proof:

  • Rebased onto current main and added an execution-level generated-HTML regression test.
  • node --test test/docs-site-theme.test.ts: passed.
  • pnpm run lint:scripts, pnpm run format:check, and git diff --check: passed.
  • Structured Codex autoreview against origin/main: clean, no accepted/actionable findings.
  • Inspected the contributor's 1920x1080 dark-mode screenshot: readable contrast, intact sidebar/layout, and visible theme control.
  • Existing-profile Chrome automation was unavailable because Chrome had no attached real tab/window; no isolated-browser result is claimed.
  • Fork PR CI did not create CI/CodeQL jobs; only the notification workflow ran.

Landed commit: 471bf8065dd4055ae2a464bb90e5358753e60171

@joshka

joshka commented Jun 19, 2026

Copy link
Copy Markdown
Contributor Author

Thanks landing this - much easier on the eyes

@brokemac79 brokemac79 mentioned this pull request Jun 27, 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

rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 🛠️ actively grinding The PR author has acted after the latest ClawSweeper review and work remains.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@joshka @steipete