From b4e0b81c1f95949088fa6aacba972c07e78cbdc0 Mon Sep 17 00:00:00 2001 From: MCR-3 Date: Mon, 21 Sep 2026 11:37:00 +0200 Subject: [PATCH] feat: add a Light theme with a System/Light/Dark theme preference 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 --- CLAUDE.md | 1 + CONTEXT.md | 14 ++ README.md | 2 + frontend/index.html | 15 ++ frontend/src/components/GraphCanvas.tsx | 10 +- frontend/src/components/ThemeToggle.tsx | 22 +++ frontend/src/index.css | 212 ++++++++++++++++++------ frontend/src/main.tsx | 1 + frontend/src/theme.ts | 76 +++++++++ 9 files changed, 303 insertions(+), 50 deletions(-) create mode 100644 frontend/src/components/ThemeToggle.tsx create mode 100644 frontend/src/theme.ts diff --git a/CLAUDE.md b/CLAUDE.md index 39b25cc..c936e47 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,6 +37,7 @@ CI (`.github/workflows/pr-checks.yml`) only runs the frontend build and the back - **The server never reads the visitor's filesystem.** The browser reads picked files and POSTs `{root, files: [{path, content}]}` to `/api/analyze`. `analyze_path()` and the disk walk in `analyzer.py` exist for the CLI only. - **The wire format is a two-sided contract.** Backend `FunctionInfo.to_dict()` (`backend/languages/base.py`) emits camelCase; `frontend/src/types.ts` mirrors it by hand. Change one, change the other. - **`SKIP_DIRS` is duplicated** in `backend/languages/base.py` and `frontend/src/localFiles.ts`. Keep them in sync. +- **The theme is applied in two places.** The inline script in `frontend/index.html` sets `data-theme` before first paint, and `frontend/src/theme.ts` owns it afterwards. They share the storage key and the resolution rules; keep them in sync. Colors belong in the tokens at the top of `index.css`, never as literals (the function card header and the language badge text are the deliberately theme-independent surfaces). - **Paths must be relative to the picked folder's contents**, with the folder's own name stripped (`localFiles.ts`). Module-name derivation and import resolution in the plugins depend on it. - **Vocabulary lives in `CONTEXT.md`; use its terms.** The code hasn't caught up on two of them: **File mode** is still `"folder"` in the code (`OrgMode`, `FolderFrame`, `layoutFolderGraph`), and **Trace up / Trace down** is still `showFlow`. Don't rename these as a drive-by; use the glossary term in prose and the code name in code. - Function and file ids are namespaced by file path so languages can't collide when merged. diff --git a/CONTEXT.md b/CONTEXT.md index 8510718..db88168 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -74,3 +74,17 @@ _Avoid_: Folder mode **Explorer**: The sidebar's nested tree of the loaded files, each with a small language icon. _Avoid_: File browser, file list + +### Appearance + +**Theme**: +The overall appearance of the app: either the **Dark theme** or the **Light theme**. The Dark theme is the original look. "Mode" is not used here because Flow mode and File mode already own that word. +_Avoid_: Color mode, dark mode (as the name of the setting), skin + +**Theme preference**: +The user's choice of Theme: **System**, **Light** or **Dark**. It is System until the user picks otherwise, and it is remembered between visits. +_Avoid_: Theme setting, theme mode + +**System theme**: +The Theme the user's operating system currently asks for. It decides what the app shows only while the Theme preference is System, and the app follows it as it changes. If the system asks for nothing, the Dark theme applies. +_Avoid_: Auto theme, OS theme diff --git a/README.md b/README.md index 3c74869..b19e25b 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ The goal is to make the flow of a codebase visible instead of jumping between fi - Follow a function's flow upward (its callers) or downward (what it calls) with one click. - Auto arrange the graph two ways: by call order (flow mode) or grouped by file (folder mode, draggable as a group). - Search and a VS Code style file explorer for quick navigation, with a small language icon next to each file. +- A Dark and a Light theme. The topbar toggle cycles System, Light and Dark; System follows the OS and is the default. ### Supported languages @@ -73,6 +74,7 @@ sample_rust_project/ Rust demo fixture used for manual testing - `components/LanguageIcon.tsx`: the small per-file language badge shown in the Explorer. - `languages.ts`: the frontend's mirror of the backend's language registry - id, label, extensions, icon color per language. Adding a language to the backend also means adding one entry here. - `api.ts`, `types.ts`, `colors.ts`: fetch wrapper, wire format types, and per file color hashing. +- `theme.ts`, `components/ThemeToggle.tsx`: the theme preference (System, Light or Dark), the System theme tracking, and the topbar toggle. The resolved theme is set as `data-theme` on ``, and every color in `index.css` is a token that the Light theme overrides. The frontend only talks to the backend over HTTP, with no browser-only file APIs, so it can later be wrapped in an Electron or Tauri shell without changes. diff --git a/frontend/index.html b/frontend/index.html index f340545..ddeed4c 100644 --- a/frontend/index.html +++ b/frontend/index.html @@ -4,7 +4,22 @@ + Function Viewer + s.focusRequest); const layoutEpoch = useViewer((s) => s.layoutEpoch); const layoutMode = useViewer((s) => s.layoutMode); + const theme = useTheme(selectTheme); const [nodes, setNodes] = useState([]); const [hoveredId, setHoveredId] = useState(null); @@ -397,6 +400,7 @@ export function GraphCanvas() { > ⛶ Fit view + {graph && visible.size === 0 && ( @@ -431,8 +435,10 @@ export function GraphCanvas() { proOptions={{ hideAttribution: true }} nodesConnectable={false} deleteKeyCode={null} + colorMode={theme} > - + {/* dot grid, minimap background and mask take their colors from the theme tokens (see .react-flow in index.css) */} + diff --git a/frontend/src/components/ThemeToggle.tsx b/frontend/src/components/ThemeToggle.tsx new file mode 100644 index 0000000..51289da --- /dev/null +++ b/frontend/src/components/ThemeToggle.tsx @@ -0,0 +1,22 @@ +import { nextPreference, selectTheme, useTheme, type ThemePreference } from "../theme"; + +const GLYPHS: Record = { system: "◐", light: "☀", dark: "☾" }; +const NAMES: Record = { system: "System", light: "Light", dark: "Dark" }; + +export function ThemeToggle() { + const preference = useTheme((s) => s.preference); + const theme = useTheme(selectTheme); + const cycle = useTheme((s) => s.cycle); + + const current = preference === "system" ? `System (currently ${NAMES[theme]})` : NAMES[preference]; + + return ( + + ); +} diff --git a/frontend/src/index.css b/frontend/src/index.css index 795fde8..50985e1 100644 --- a/frontend/src/index.css +++ b/frontend/src/index.css @@ -1,23 +1,118 @@ -/* ============ Function Viewer, blueprint theme ============ */ +/* ============ Function Viewer, blueprint styling ============ */ + +/* Every color lives in a token. The Dark theme is the default (no data-theme + attribute means dark); the Light theme overrides it below. The theme is + applied as data-theme on by index.html and src/theme.ts. */ :root { + --font-ui: "Chakra Petch", sans-serif; + --font-code: "JetBrains Mono", monospace; + + /* The function card header is dark in both themes, so its text colors are + theme-independent. */ + --hdr-base: #10151d; + --hdr-text: #d6e2f0; + --hdr-text-dim: #8497ad; + --hdr-accent: #35c9dd; + --lock: #f0b849; +} + +:root, +:root[data-theme="dark"] { + color-scheme: dark; + --bg: #0b0f14; --bg-grid: #1b2634; --panel: #11161e; + --panel-end: #0d1219; --panel-2: #161d27; --card: rgba(15, 20, 27, 0.94); --border: #263141; + --border-soft: #151d28; --border-strong: #35455c; --text: #d6e2f0; --text-dim: #8497ad; --text-faint: #5a6b80; --accent: #35c9dd; + --accent-glow: rgba(53, 201, 221, 0.25); + --accent-fill: rgba(53, 201, 221, 0.16); + --toggled-text: #35c9dd; --green: #3fd97f; --red: #f4576b; - --lock: #f0b849; - - --font-ui: "Chakra Petch", sans-serif; - --font-code: "JetBrains Mono", monospace; + --error-text: #ff9daa; + --scroll-thumb: #26313f; + + --primary-from: #10404a; + --primary-to: #0c2f38; + --primary-border: #2a7f92; + --primary-text: #9beaf5; + + --card-shadow: 0 12px 32px rgba(0, 0, 0, 0.55); + --doc-tint: rgba(255, 255, 255, 0.015); + --dot-shade: rgba(0, 0, 0, 0.35); + --wire-blur: 4px; + --wire-mix: 100%; + --folder-label-base: white; + --folder-label-mix: 85%; + + --tok-keyword: #ff7b72; + --tok-function: #d2a8ff; + --tok-class: #ffa657; + --tok-string: #a5d6a2; + --tok-number: #79c0ff; + --tok-comment: #6e7c8f; + + --minimap-bg: #0d1219; + --minimap-mask: rgba(6, 10, 15, 0.75); +} + +/* Light theme: blueprint paper. */ +:root[data-theme="light"] { + color-scheme: light; + + --bg: #eef3f8; + --bg-grid: #c3d0df; + --panel: #f8fafc; + --panel-end: #edf2f7; + --panel-2: #e6edf5; + --card: rgba(255, 255, 255, 0.97); + --border: #d3dde9; + --border-soft: #e3eaf2; + --border-strong: #b3c2d5; + --text: #14202e; + --text-dim: #45586e; + --text-faint: #64768b; + --accent: #07748a; + --accent-glow: rgba(7, 116, 138, 0.22); + --accent-fill: rgba(7, 116, 138, 0.12); + --toggled-text: #075a6b; + --green: #1f9d57; + --red: #d63a52; + --error-text: #b4233a; + --scroll-thumb: #c3d0df; + + --primary-from: #dff3f7; + --primary-to: #c8e9f0; + --primary-border: #5db4c5; + --primary-text: #075a6b; + + --card-shadow: 0 8px 24px rgba(31, 55, 90, 0.14); + --doc-tint: rgba(10, 60, 110, 0.03); + --dot-shade: rgba(0, 0, 0, 0.22); + --wire-blur: 2px; + --wire-mix: 45%; + --folder-label-base: black; + --folder-label-mix: 60%; + + --tok-keyword: #cf222e; + --tok-function: #8250df; + --tok-class: #953800; + --tok-string: #0a3069; + --tok-number: #0550ae; + --tok-comment: #6e7781; + + --minimap-bg: #f8fafc; + --minimap-mask: rgba(190, 205, 222, 0.6); } * { @@ -44,7 +139,7 @@ body { height: 10px; } ::-webkit-scrollbar-thumb { - background: #26313f; + background: var(--scroll-thumb); border-radius: 5px; border: 2px solid var(--panel); } @@ -62,7 +157,7 @@ body { .sidebar { width: 320px; min-width: 320px; - background: linear-gradient(180deg, var(--panel) 0%, #0d1219 100%); + background: linear-gradient(180deg, var(--panel) 0%, var(--panel-end) 100%); border-right: 1px solid var(--border); display: flex; flex-direction: column; @@ -167,13 +262,13 @@ body { .btn:hover { border-color: var(--accent); - box-shadow: 0 0 10px rgba(53, 201, 221, 0.25); + box-shadow: 0 0 10px var(--accent-glow); } .btn.toggled { - background: rgba(53, 201, 221, 0.16); + background: var(--accent-fill); border-color: var(--accent); - color: var(--accent); + color: var(--toggled-text); } .btn:disabled { @@ -186,14 +281,14 @@ body { } .btn-primary { - background: linear-gradient(180deg, #10404a, #0c2f38); - border-color: #2a7f92; - color: #9beaf5; + background: linear-gradient(180deg, var(--primary-from), var(--primary-to)); + border-color: var(--primary-border); + color: var(--primary-text); } .btn-danger:hover { border-color: var(--red); - box-shadow: 0 0 10px rgba(244, 87, 107, 0.25); + box-shadow: 0 0 10px color-mix(in srgb, var(--red) 25%, transparent); } .btn-row { @@ -208,10 +303,10 @@ body { .error-box { margin-top: 8px; padding: 8px 10px; - border: 1px solid rgba(244, 87, 107, 0.4); - background: rgba(244, 87, 107, 0.08); + border: 1px solid color-mix(in srgb, var(--red) 40%, transparent); + background: color-mix(in srgb, var(--red) 8%, transparent); border-radius: 6px; - color: #ff9daa; + color: var(--error-text); font-size: 12px; word-break: break-word; } @@ -240,7 +335,7 @@ body { gap: 8px; padding: 6px 8px; cursor: pointer; - border-bottom: 1px solid #151d28; + border-bottom: 1px solid var(--border-soft); } .search-result:last-child { border-bottom: none; @@ -400,12 +495,12 @@ body { .status-dot.on { background: var(--green); - box-shadow: 0 0 10px rgba(63, 217, 127, 0.8), inset 0 -3px 6px rgba(0, 0, 0, 0.35); + box-shadow: 0 0 10px color-mix(in srgb, var(--green) 80%, transparent), inset 0 -3px 6px var(--dot-shade); } .status-dot.off { background: var(--red); - box-shadow: 0 0 8px rgba(244, 87, 107, 0.5), inset 0 -3px 6px rgba(0, 0, 0, 0.35); + box-shadow: 0 0 8px color-mix(in srgb, var(--red) 50%, transparent), inset 0 -3px 6px var(--dot-shade); } .tree-row .status-dot { @@ -443,7 +538,12 @@ body { justify-content: space-between; gap: 12px; padding: 10px 16px; - background: linear-gradient(180deg, rgba(11, 15, 20, 0.9) 0%, rgba(11, 15, 20, 0.55) 60%, transparent 100%); + background: linear-gradient( + 180deg, + color-mix(in srgb, var(--bg) 90%, transparent) 0%, + color-mix(in srgb, var(--bg) 55%, transparent) 60%, + transparent 100% + ); pointer-events: none; } @@ -466,6 +566,12 @@ body { flex-shrink: 0; } +/* Fixed width so the label swap (System / Light / Dark) doesn't shift the topbar */ + +.theme-toggle { + min-width: 92px; +} + /* Reorganize: button with a mode slider underneath */ .reorg-group { @@ -490,8 +596,8 @@ body { bottom: 2px; left: 2px; width: calc(50% - 2px); - background: linear-gradient(180deg, #10404a, #0c2f38); - border: 1px solid #2a7f92; + background: linear-gradient(180deg, var(--primary-from), var(--primary-to)); + border: 1px solid var(--primary-border); border-radius: 999px; transition: transform 0.2s ease; } @@ -523,7 +629,7 @@ body { } .mode-slider button.active { - color: #9beaf5; + color: var(--primary-text); } .mode-slider button:not(.active):hover { @@ -564,7 +670,7 @@ body { font-family: var(--font-code); font-size: 11px; font-weight: 600; - color: color-mix(in srgb, var(--folder-color, var(--text-dim)) 85%, white); + color: color-mix(in srgb, var(--folder-color, var(--text-dim)) var(--folder-label-mix), var(--folder-label-base)); background: color-mix(in srgb, var(--folder-color, var(--border-strong)) 20%, var(--bg)); border: 1.5px solid color-mix(in srgb, var(--folder-color, var(--border-strong)) 60%, var(--border-strong)); border-bottom: none; @@ -627,15 +733,27 @@ body { /* Edges: glowing wires */ +/* React Flow's own theme (colorMode) must not repaint the pane, dots or minimap: + those come from our tokens. */ +.react-flow { + --xy-background-color: transparent; + --xy-background-pattern-color: var(--bg-grid); + --xy-minimap-background-color: var(--minimap-bg); + --xy-minimap-mask-background-color: var(--minimap-mask); +} + +/* A wire glows softly by default (softer still in the Light theme); the wires + of a hovered or selected card get the full glow in both themes. */ .react-flow__edge-path { stroke-width: 2; - filter: drop-shadow(0 0 4px currentColor); + filter: drop-shadow(0 0 var(--wire-blur) color-mix(in srgb, currentColor var(--wire-mix), transparent)); } .react-flow__edge:hover .react-flow__edge-path, .react-flow__edge.edge-active .react-flow__edge-path { stroke-width: 3; stroke-dasharray: 8 4; + filter: drop-shadow(0 0 4px currentColor); animation: wire-flow 0.5s linear infinite; } @@ -655,7 +773,7 @@ body { border: 1px solid var(--border-strong); border-radius: 10px; font-family: var(--font-code); - box-shadow: 0 12px 32px rgba(0, 0, 0, 0.55); + box-shadow: var(--card-shadow); backdrop-filter: blur(4px); overflow: visible; transition: box-shadow 0.2s, border-color 0.2s, opacity 0.2s; @@ -663,7 +781,7 @@ body { .fn-card.active { border-color: color-mix(in srgb, var(--cat) 65%, var(--border-strong)); - box-shadow: 0 12px 32px rgba(0, 0, 0, 0.55), 0 0 18px color-mix(in srgb, var(--cat) 28%, transparent); + box-shadow: var(--card-shadow), 0 0 18px color-mix(in srgb, var(--cat) 28%, transparent); } .fn-card.inactive { @@ -680,7 +798,7 @@ body { gap: 9px; padding: 9px 12px; border-radius: 9px 9px 0 0; - background: linear-gradient(90deg, color-mix(in srgb, var(--cat) 42%, #10151d) 0%, #10151d 85%); + background: linear-gradient(90deg, color-mix(in srgb, var(--cat) 42%, var(--hdr-base)) 0%, var(--hdr-base) 85%); border-bottom: 1px solid var(--border); position: relative; } @@ -721,17 +839,17 @@ body { .fn-header .fn-sig { font-size: 11px; - color: color-mix(in srgb, var(--text) 80%, var(--cat)); + color: color-mix(in srgb, var(--hdr-text) 80%, var(--cat)); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; } .fn-sig .p-name { - color: var(--text); + color: var(--hdr-text); } .fn-sig .p-ann { - color: var(--text-dim); + color: var(--hdr-text-dim); } .fn-sig .p-ret { color: #9beaf5; @@ -752,9 +870,9 @@ body { } .fn-header .flow-btn:hover { - border-color: var(--accent); - color: var(--accent); - box-shadow: 0 0 8px rgba(53, 201, 221, 0.4); + border-color: var(--hdr-accent); + color: var(--hdr-accent); + box-shadow: 0 0 8px color-mix(in srgb, var(--hdr-accent) 40%, transparent); } /* Docstring */ @@ -762,7 +880,7 @@ body { .fn-doc { padding: 8px 12px; border-bottom: 1px solid var(--border); - background: rgba(255, 255, 255, 0.015); + background: var(--doc-tint); font-size: 11.5px; line-height: 1.55; color: var(--text-dim); @@ -840,40 +958,40 @@ body { font-weight: 700; } -/* Prism token colors (GitHub-dark-ish) */ +/* Prism token colors (GitHub-dark-ish in the Dark theme, GitHub-light in the Light one) */ .token.keyword { - color: #ff7b72; + color: var(--tok-keyword); } .token.function { - color: #d2a8ff; + color: var(--tok-function); } .token.class-name { - color: #ffa657; + color: var(--tok-class); } .token.string, .token.triple-quoted-string { - color: #a5d6a2; + color: var(--tok-string); } .token.number { - color: #79c0ff; + color: var(--tok-number); } .token.comment { - color: #6e7c8f; + color: var(--tok-comment); font-style: italic; } .token.builtin { - color: #ffa657; + color: var(--tok-class); } .token.boolean { - color: #79c0ff; + color: var(--tok-number); } .token.operator { - color: #ff7b72; + color: var(--tok-keyword); } .token.decorator, .token.punctuation.decorator { - color: #d2a8ff; + color: var(--tok-function); } /* Handles: blueprint-style pins */ diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx index c5eb7d1..d55e112 100644 --- a/frontend/src/main.tsx +++ b/frontend/src/main.tsx @@ -1,6 +1,7 @@ import { StrictMode } from 'react' import { createRoot } from 'react-dom/client' import './index.css' +import './theme.ts' // applies the Theme and tracks the System theme on import import App from './App.tsx' // requestAnimationFrame never fires while the tab is hidden, which stalls diff --git a/frontend/src/theme.ts b/frontend/src/theme.ts new file mode 100644 index 0000000..5a71a12 --- /dev/null +++ b/frontend/src/theme.ts @@ -0,0 +1,76 @@ +import { create } from "zustand"; + +export type Theme = "light" | "dark"; +export type ThemePreference = "system" | "light" | "dark"; + +/** Click order of the topbar toggle. */ +const ORDER: ThemePreference[] = ["system", "light", "dark"]; + +// The inline script in index.html applies the theme before first paint using +// this same key and the same resolution rules. Change one, change the other. +const STORAGE_KEY = "fv-theme-preference"; +const LIGHT_QUERY = "(prefers-color-scheme: light)"; + +function readPreference(): ThemePreference { + try { + const stored = localStorage.getItem(STORAGE_KEY); + if (stored === "light" || stored === "dark") return stored; + } catch { + // storage blocked or unavailable: fall through to System + } + return "system"; +} + +function writePreference(preference: ThemePreference) { + try { + localStorage.setItem(STORAGE_KEY, preference); + } catch { + // storage blocked or unavailable: the choice just won't survive a reload + } +} + +/** The System theme: Light only when the OS asks for it; no preference means Dark. */ +function readSystemTheme(): Theme { + return typeof matchMedia === "function" && matchMedia(LIGHT_QUERY).matches ? "light" : "dark"; +} + +function resolveTheme(preference: ThemePreference, system: Theme): Theme { + return preference === "system" ? system : preference; +} + +export function nextPreference(preference: ThemePreference): ThemePreference { + return ORDER[(ORDER.indexOf(preference) + 1) % ORDER.length]; +} + +interface ThemeState { + preference: ThemePreference; + /** What the OS currently asks for; only shown while the preference is System. */ + system: Theme; + cycle: () => void; +} + +export const useTheme = create((set, get) => ({ + preference: readPreference(), + system: readSystemTheme(), + cycle: () => { + const preference = nextPreference(get().preference); + writePreference(preference); + set({ preference }); + }, +})); + +/** The Theme actually on screen. */ +export const selectTheme = (s: ThemeState): Theme => resolveTheme(s.preference, s.system); + +function applyTheme(theme: Theme) { + document.documentElement.dataset.theme = theme; +} + +applyTheme(selectTheme(useTheme.getState())); +useTheme.subscribe((state) => applyTheme(selectTheme(state))); + +if (typeof matchMedia === "function") { + matchMedia(LIGHT_QUERY).addEventListener("change", (e) => { + useTheme.setState({ system: e.matches ? "light" : "dark" }); + }); +}