Skip to content

feat(website): follow the system dark mode and fix small-screen text - #1894

Merged
morluto merged 9 commits into
morluto:mainfrom
CassieFox23:feat/website-dark-mode-upstream
Oct 11, 2026
Merged

morluto merged 9 commits into
morluto:mainfrom
CassieFox23:feat/website-dark-mode-upstream

Conversation

@CassieFox23

@CassieFox23 CassieFox23 commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

TL;DR: The website now turns dark when the reader's system is set to dark. The same PR fixes small text and spacing problems that show in both modes. Light colors do not change.

Summary

The plan is in discussion #1727. Thanks, morluto, for the go-ahead. The site only had a light theme. With a dark system, readers got a white page. This PR adds a dark theme. It also fixes small layout problems that I found while measuring the pages.

Scope grew in review. This PR is bigger than the plan in #1727. The automated review found four places where dark mode made things worse. I fixed them here. They are the step highlight, the dinosaur game colors and its redraw, and the Touhou flywheel arrows. A new site test came too. If smaller pieces are easier to review, I can split it.

Problem and expected behavior

  • With the system set to dark, the site should be dark. With it set to light, the colors should stay as they are.
  • Some layout details fall short of WCAG 2.2. At 320 px, long terminal prompts and Copy buttons were cut off. Some labels were 9.6 px. Some header and footer links were 23.09 px tall.

Change and scope

The first four commits are the change, and each can be read alone. Five more came after review. They hold the four review fixes and a new site test.

  1. Layout fixes. These change the light theme on purpose:
    • Long terminal prompts and code-header buttons wrap at 320 px.
    • Headings and table cells break long words.
    • Header and footer links are at least 24 px tall.
    • Labels under 12 px now render at 12 px or more. Inline code never drops under 0.75rem.
    • On the home page, the two column rows share one gap and line up on the first baseline.
    • Terminals, step tabs and the assembly title bar use the 5 px corner and matching padding.
    • Highlight chips get room around the text. The active run in a step listing is one band, not a box per line.
  2. Dark mode. One @media (prefers-color-scheme: dark) block sits in styles.css, before the right-to-left rules. It swaps the six color variables to Catppuccin Mocha (MIT). It also sets color-scheme: dark. Fixed colors that would break on a dark page get dark values. The terminals get a border. The page template and the 17 pages get a second theme-color tag for dark. The style guide's color table gets a Dark column.
  3. Dark figures. Pages load the five SVG figures with an img tag, so page CSS cannot reach them. Each SVG carries its own dark block. All five share one color map. Markup, labels and shapes do not change.
  4. Catalog references. Commit 2 adds lines to every page head. That moves the line numbers that the translation catalogs cite. The command python3 scripts/website.py translations extract rewrites them. This commit is that run, unedited. It changes 19 files and about 31,600 lines. The changes are #: reference comments and one moved entry ("Main navigation"). No msgstr text changes. Without it, the site check fails. The error is "Translation sources changed". You can skip it when reviewing. You can also re-run the command yourself.

The translated pages need no extra CSS. The build makes them from the English pages. They load the same stylesheet. The language picker and the translation notice use the color variables. The right-to-left rules set no colors.

Not in this PR: the sharing image. It stays light. Link previews ignore the system setting.

Screenshots

These are placeholder previews from my fork build, made before the port to today's main. They show the look, not this exact branch.

Home page in dark mode, desktop
Home page in light mode, desktop
Home page in dark mode, phone width
The bullet-ring figure in dark mode

Contract and boundary impact

  • Semantic owner and earliest changed stage: website only.
  • CLI and MCP/tool-catalog contract: none.
  • Provider, bridge, target-format, or platform compatibility: none.
  • Evidence, artifact, provenance, or reconstruction contract: none.
  • Process execution, authorization, cleanup, or containment impact: none.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: none.

Evidence and regression coverage

All numbers below were measured on the built site. I read computed styles in headless Chromium. I judged no looks from screenshots.

  • Tests added: one, in scripts/test-website.py. Every reading page, and its built copy in each language, must have a light and a dark theme-color tag. The stylesheet must keep its dark block. On fa9a7e5, before this PR, the test fails on every page. On this branch it passes. The other site tests still cover the pages, links and metadata.
  • Dark text contrast: 323 reading pages. At 1280 px that is 50,973 text elements. At 320 px it is 50,270. The lowest ratio is 5.97:1 at both widths. That is blue link text on a tinted highlight, on the home page. Nothing is below 4.5:1.
  • Dark on translated pages: the 34 Arabic and Persian pages (right to left) have the dark page color. So do the 17 Chinese pages. Every reading page has both theme-color tags.
  • Left out of every count here: the two example pages notes-electron and notes-web. They are sample apps, and this PR does not touch them. The 323 reading pages are 17 pages in each of 19 languages.
  • Light colors: I compared 82,992 elements on 323 pages, before and after. The colors I compared were text, background, border, outline, fill, stroke and shadow. There were 0 differences.
  • Light figures: a screenshot of each of the five SVGs is byte-for-byte identical before and after. The dark screenshots differ from the old ones, so the test can fail.
  • Figure text in dark: the five figures hold 94 text elements. For 81 of them, the script found the background behind the text. The lowest ratio is 5.97:1. For the other 13, the script found no background shape. Those 13 are not measured.
  • Light geometry at 320 px, on 323 pages: the smallest text went from 9.6 px to 12 px. The smallest header or footer link went from 23.09 px to 24 px. No page scrolled sideways, before or after.
  • !important: none added.
  • Dinosaur game: after review, the canvas reads its colors from CSS variables on .dino-stage. In light, its pixels match the old ones byte for byte on both pages that host it. In dark, the dinosaur is 8.3:1, cacti and text 7.9:1, and the crash color 7.6:1. The game redraws when the system theme changes, even while idle.
  • Touhou flywheel: in dark, two rules map its five hard-coded strokes to the accent and muted colors. They read 7.8:1 and 7.4:1, up from 2.0:1 and 2.8:1. Light keeps the old strokes.
  • Remaining proof gaps: see "Not run" below.

Not run

  • I looked at this branch's English pages by eye in dark mode, in LibreWolf 157 (a Firefox fork, MPL-2.0). I did not look at the translated pages by eye.
  • No measurement of hover, focus or pressed states.
  • The 320 px cut-off of prompts and buttons. I measured it in an earlier pass on my fork. I did not re-measure it here.
  • Firefox's engine was checked by eye only, in LibreWolf 157. No measurements ran there, and nothing ran in Safari.
  • A Pages preview deploy.

Validation performed

All ran on this branch.

The copy was clean, under /tmp. The Node version was 24.18.0.

  • python3 scripts/website.py check: exit 0.
  • python3 scripts/test-website.py: exit 0, 12 tests, with the new one.
  • npm ci: exit 0.
  • npm run check:fast: exit 0. This needed a git repository in the copy, because the lint step lists files with git.
  • npx oxfmt --check website scripts: exit 0.
  • The measuring scripts all ran to the end. They are not in the repo.

Compatibility, safety, and release

  • Breaking changes or migration steps: none. Readers with a light system see the same colors.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable. I measured in Chromium 154 only.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: not needed. Only CSS, HTML, SVG and catalog comments change. Nothing adds scripts or storage. The palette is Catppuccin Mocha (MIT).

Review checklist

  • This PR addresses a concrete problem or an agreed enhancement.
  • The PR has one focused outcome and the title follows type(scope): outcome. Two parts by choice, agreed in [Feature] Dark mode for rea.tools, plus a few small fixes for phones and accessibility #1727.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output. Not applicable: website only.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.
Test setup

🤖 Generated with Claude Code (Sonnet 5.5, verified by Opus 5.5) 🦊

Claude Sonnet 5.5 added 4 commits October 11, 2026 11:51
…spacing

From a layout audit of the built pages:

- Long terminal prompts and code-header buttons wrap instead of being cut
  off at 320px (WCAG 1.4.10).
- Headings and table cells break long words, so the 1.4.12 text-spacing
  test no longer widens pages past 320px.
- Header and footer links get a 24px minimum height (2.5.8).
- Labels that rendered under 12px now render at 12px or more, and inline
  code never drops under 0.75rem.
- The home page's hero and definition rows share one column gap and align
  on the first baseline, and stacked boxes share one corner size.
- Highlight chips get room around the text, and the active run in a step
  listing is one band instead of a box per line.

Colors are unchanged.

🤖 Generated with Claude Code (Sonnet 5.5) 🦊
The site was light only, so a reader with a dark system still got a white
page. Add one prefers-color-scheme: dark block to the stylesheet that swaps
the six color variables to Catppuccin Mocha (MIT) and overrides the fixed
colors that would break on a dark page: selection, buttons, tinted
highlights, flow nodes and arrows, and a visible border on the agent
terminal.

Add a dark theme-color tag beside the light one in the page template and
the 17 pages, and a Dark column to the style guide's color table.

Light colors are unchanged. The SVG figures follow in the next commit; the
blog page's inline strokes, the dinosaur game and the social card are left
as they are.

🤖 Generated with Claude Code (Sonnet 5.5) 🦊
Pages load the figures with <img>, so page CSS cannot reach inside them.
Each figure now carries its own @media (prefers-color-scheme: dark) block
of attribute-selector overrides that map every light color to a Catppuccin
Mocha color, with one shared map across all five. No markup, labels,
shapes or positions change, and nothing uses !important.

Four figures also paint a mantle canvas so "Open figure" works on its own;
analyst-thinking.svg stays transparent, since it sits on the page rather
than in a figure box.

🤖 Generated with Claude Code (Sonnet 5.5) 🦊
The theme-color tags move the page lines that the catalogs cite, so
python3 scripts/website.py translations extract rewrites the source
references in messages.pot and the 18 PO files. No message text changes.
The same run moves the "Main navigation" entry to its new position in each
catalog.

🤖 Generated with Claude Code (Sonnet 5.5) 🦊
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-11T17:25:30.662594Z 9e0e445 New commits
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 754f3ec52c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread website/public/assets/styles.css Resolved
Claude Opus 5.5 added 2 commits October 11, 2026 12:31
The full-width band for the active step now applies only to code-step
blocks. The inline parameter highlights in the dx-ball and th04
signatures stay inline again.

🤖 Generated with Claude Code (Opus 5.5) 🦊
Each authored reading page, and its built copy in every language,
must carry one theme-color tag for light and one for dark. The
stylesheet must keep its dark color scheme block. On the commit before
dark mode, this test fails on every page.

🤖 Generated with Claude Code (Opus 5.5) 🦊

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4f252518ce

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread website/public/assets/styles.css Resolved
In dark mode the game box turned dark, but the game still drew with
its light colors, so the dinosaur, cacti and text fell to about 2:1
contrast. The canvas now reads five colors from CSS variables on
.dino-stage. Light values are the old ones, so light mode draws the
same pixels. Dark values are Catppuccin Mocha: 8.3:1 for the
dinosaur, 7.9:1 for cacti and text, 7.6:1 for the crash color.

The moved lines in dino-demo.js shift the translation catalog
references, so the catalogs are refreshed too (reference comments
only).

🤖 Generated with Claude Code (Opus 5.5) 🦊
CassieFox23 pushed a commit to CassieFox23/rea that referenced this pull request Oct 11, 2026
Rendered in headless Chromium 154 from the morluto#1894 head b9ef65d, at
2x scale.

🤖 Generated with Claude Code (Opus 5.5) 🦊

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b9ef65dded

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment thread website/public/assets/styles.css Resolved
Comment thread website/public/assets/dino-demo.js Resolved
Claude Opus 5.5 added 2 commits October 11, 2026 13:13
The inline flywheel SVG on the Touhou article hard-codes its stroke
colors, so on the dark page its connectors fell to about 2:1. Two
dark-only rules map those strokes to the page accent and muted colors
(7.8:1 and 7.4:1). Light mode is unchanged.

🤖 Generated with Claude Code (Opus 5.5) 🦊
The canvas reads its colors only when it draws, so an idle, paused or
crashed game kept the old palette after a theme switch. Each demo now
redraws on a prefers-color-scheme change.

The added lines shift the translation catalog references, so the
catalogs are refreshed too (reference comments only).

🤖 Generated with Claude Code (Opus 5.5) 🦊
@CassieFox23

Copy link
Copy Markdown
Contributor Author

TL;DR: All four review notes are fixed, and a new site test guards the dark theme tags. Light mode still looks the same.

What changed since I opened this:

Commit Change
fb59ba8 The wide step band now only covers whole code steps. Small inline highlights stay small.
4f25251 New site test. Every page needs a light and a dark theme-color tag. It fails on the base and passes here.
b9ef65d The dinosaur game reads its colors from CSS. Dark is now 7.6:1 or higher.
9e0e445 The game redraws when the system theme changes.
5f907ed The Touhou flywheel arrows use the page colors in dark, at 7.8:1 and 7.4:1.

For each fix, I checked that light mode draws the same pixels as before. The site check and the pre-push checks pass. The body now notes that the scope grew. I can split the PR if that helps.

🤖 Generated with Claude Code (Opus 5.5) 🦊

CassieFox23 pushed a commit to CassieFox23/rea that referenced this pull request Oct 11, 2026
Rendered in headless Chromium 154 from the morluto#1894 head 9e0e445, at
2x scale.

🤖 Generated with Claude Code (Opus 5.5) 🦊
@morluto
morluto merged commit 12ee785 into morluto:main Oct 11, 2026
2 checks passed
@morluto

morluto commented Oct 11, 2026

Copy link
Copy Markdown
Owner

Looks good thank you for this Cassie!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants