Skip to content

feat: add a Light theme with a System/Light/Dark theme preference - #17

Merged
MCR-3 merged 1 commit into
mainfrom
16-light-theme
Sep 21, 2026
Merged

MCR-3 merged 1 commit into
mainfrom
16-light-theme

Conversation

@MCR-3

@MCR-3 MCR-3 commented Sep 21, 2026

Copy link
Copy Markdown
Member

Summary

Adds a Light theme and a Theme preference (System, Light or Dark), and keeps today's look as the Dark theme. A button at the right end of the canvas topbar cycles System → Light → Dark.

The app had a single dark look and ignored the OS colour scheme. Many colours were also hard-coded outside the CSS tokens (Prism token colours, the React Flow dot grid and minimap, several gradients and shadows), so a second theme couldn't be added by swapping variables alone. Every colour now lives in a token, and the Light theme overrides them.

Closes #16

Behaviour

  • System is the default. It follows the OS live, including changes while the page is open, and falls back to Dark if the OS expresses no preference.
  • The preference is remembered between visits. Storage access is guarded, so the app still works with storage blocked (the choice just won't survive a reload).
  • An inline script in index.html applies the theme before first paint, so a reload never flashes the wrong theme. frontend/src/theme.ts owns it afterwards; both share the storage key and resolution rules (recorded in CLAUDE.md).
  • The resolved theme is passed to React Flow's colorMode. Its pane, dot grid and minimap colours come from our tokens.
  • Wires keep a soft glow in the Light theme. The wires of a hovered or selected card get the full glow and dashed flow in both themes. The selected card itself is unchanged.
  • Card headers stay dark with light text in both themes, so the per-file colours read the same way. The 8-colour per-file palette is reused as is.

Two Light values differ from the token table in #16

  • --accent is #07748a, not #0a7f95. The original was 4.48:1 on the panel, just under the AA text contrast the acceptance criteria ask for. Text-token contrast on the Light surfaces is now 4.86:1 or better for the accent, and 6.55:1 or better for body and secondary text.
  • --lock stays #f0b849 in both themes. Its only use is the async badge on the card header, which is dark in both themes, so the table's dark amber would have been hard to read there.

Beyond the issue's to-do list

  • A CLAUDE.md bullet noting that the theme is applied in two places, and a README line for theme.ts / ThemeToggle.tsx.
  • CONTEXT.md gains an Appearance section: Theme, Theme preference, System theme.

Verification

There is no test suite, so this was checked by hand and with a throwaway browser script (not part of this PR) driving headless Edge against both apps.

  • npm run build and npm run lint pass.
  • 29 browser checks pass, in each of the last three runs:
    • OS light and dark map to the Light and Dark themes, and System follows a live OS change.
    • The cycle order, labels and persistence across reload are right, and choosing System again follows the OS again.
    • The inline script alone applies a stored theme, and the app works with localStorage blocked, with no page errors.
    • Engaged wires get the full glow and calm wires the softer one.
    • Text and accent contrast on the Light surfaces meet AA.
  • The Dark theme is pixel-identical to the previous build everywhere except the topbar, where the new toggle sits (compared on production builds of both).
  • Light theme reviewed visually in flow mode, file mode, with a card selected, and with search results open.

Things to know

  • The lowest-contrast file colours on the Light canvas are amber (#d29922) and sky (#58a6ff), about 2.3:1. They read fine in the screenshots and I left colors.ts alone as agreed, but they are the first to adjust if any look faint.
  • The Dark pixel comparison flaked once in roughly 18 runs. I didn't keep that run's images and the cause is unexplained (a late font load is my guess). The earlier failures were the original app's own load-time fitView race, which the comparison now sidesteps by clicking "Fit view" first.
  • Not covered: cross-tab sync of the preference (out of scope in the issue), and a real light-OS device, since the OS setting was emulated.

The app had a single dark look and ignored the OS colour scheme, so users
on a light setting or in bright rooms had no way to switch. Colours were
also hard-coded in several places outside the CSS tokens (Prism token
colours, the React Flow dot grid and minimap, gradients, shadows), which
meant a second theme could not be added by swapping variables alone.

Every colour now lives in a token, with the Dark theme unchanged (it was
checked pixel-for-pixel against the previous build) and a new Light theme
overriding the tokens. A topbar button cycles the Theme preference through
System, Light and Dark. System is the default, follows the OS live, and
falls back to Dark when the OS expresses no preference. The preference is
remembered, with storage access guarded, and an inline script in index.html
applies the theme before first paint so a reload never flashes the wrong
one. The resolved theme is also passed to React Flow as its colorMode.

Wires keep a soft glow in the Light theme; the wires of a hovered or
selected card get the full glow and dashed flow in both themes.

Two Light values differ from the token table in the issue. The accent is
#07748a rather than #0a7f95 because the original was 4.48:1 on the panel,
under the AA text contrast the acceptance criteria ask for. The card
header's --lock stays #f0b849 in both themes since its only use is the
async badge on the header, which is dark in both themes.

CONTEXT.md gains an Appearance section (Theme, Theme preference, System
theme), and CLAUDE.md records that the theme is applied in two places.

Closes #16
@MCR-3
MCR-3 merged commit 9c5f5fe into main Sep 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a Light theme with a System/Light/Dark theme preference

1 participant