fix: add theme customization documentation and example CSS preset

Author: flamacore

README.md

@@ -75,6 +75,10 @@ You will also need:
 - Git available on your system `PATH`
 - A Windows environment for the current primary development target
 
+## Theming
+
+Theme customization notes and a reference preset CSS file are available in [docs/theme-customization.md](docs/theme-customization.md).
+
 ## Tech Stack
 
 - Tauri 2

docs/examples/aurora-glass-theme.css

@@ -0,0 +1,115 @@
+/*
+  Example UniGit theme preset.
+
+  This file is documentation and reference material.
+  It is not loaded automatically by the app today.
+
+  Use it when:
+  - adding a new built-in theme preset to src/styles.css
+  - designing a theme that needs selector-level treatment beyond JSON variable overrides
+*/
+
+:root[data-theme="aurora-glass"] {
+  color-scheme: dark;
+  --bg-0: #071018;
+  --bg-1: rgba(13, 21, 32, 0.76);
+  --bg-3: rgba(255, 255, 255, 0.08);
+  --line: rgba(255, 255, 255, 0.14);
+  --line-soft: rgba(255, 255, 255, 0.11);
+  --line-softer: rgba(255, 255, 255, 0.08);
+  --line-subtle: rgba(255, 255, 255, 0.1);
+  --line-strong: rgba(143, 198, 255, 0.38);
+  --text-1: #f2f7ff;
+  --text-2: rgba(229, 238, 255, 0.78);
+  --text-3: rgba(219, 232, 255, 0.56);
+  --accent: #8fc6ff;
+  --accent-2: #7ff5db;
+  --app-background:
+    radial-gradient(circle at 14% 10%, rgba(86, 150, 255, 0.18), transparent 22%),
+    radial-gradient(circle at 82% 18%, rgba(68, 233, 202, 0.14), transparent 24%),
+    radial-gradient(circle at 52% 76%, rgba(117, 94, 255, 0.12), transparent 30%),
+    linear-gradient(180deg, #16232b 0%, #0c141d 42%, #071018 100%);
+  --panel-bg-start: rgba(31, 42, 58, 0.54);
+  --panel-bg-end: rgba(10, 17, 28, 0.28);
+  --panel-shadow: 0 26px 84px rgba(0, 0, 0, 0.42), inset 0 1px 0 rgba(255, 255, 255, 0.16), inset 0 -1px 0 rgba(255, 255, 255, 0.04);
+  --elevated-shadow: 0 16px 42px rgba(0, 0, 0, 0.36), inset 0 1px 0 rgba(255, 255, 255, 0.14);
+  --surface-section: rgba(255, 255, 255, 0.08);
+  --surface-row: rgba(255, 255, 255, 0.1);
+  --surface-card: rgba(255, 255, 255, 0.1);
+  --surface-muted: rgba(255, 255, 255, 0.14);
+  --surface-input: rgba(10, 17, 28, 0.44);
+  --surface-menu-start: rgba(32, 43, 58, 0.64);
+  --surface-menu-end: rgba(10, 17, 28, 0.42);
+  --surface-selection: rgba(143, 198, 255, 0.18);
+  --surface-selection-soft: rgba(143, 198, 255, 0.14);
+  --surface-selection-subtle: rgba(143, 198, 255, 0.1);
+  --surface-overlay: rgba(4, 9, 15, 0.5);
+  --surface-fullscreen-start: rgba(16, 24, 35, 0.72);
+  --surface-fullscreen-end: rgba(7, 12, 18, 0.44);
+  --surface-frame: rgba(9, 15, 24, 0.3);
+  --surface-viewport:
+    radial-gradient(circle at 18% 20%, rgba(143, 198, 255, 0.18), transparent 24%),
+    radial-gradient(circle at 84% 74%, rgba(127, 245, 219, 0.12), transparent 24%),
+    rgba(7, 12, 20, 0.34);
+  --surface-tab-active: linear-gradient(180deg, rgba(143, 198, 255, 0.18), rgba(255, 255, 255, 0.06));
+  --surface-chip: rgba(255, 255, 255, 0.1);
+  --surface-chip-strong: rgba(255, 255, 255, 0.14);
+  --surface-button: rgba(255, 255, 255, 0.12);
+  --surface-button-strong: rgba(255, 255, 255, 0.18);
+  --surface-button-active: rgba(143, 198, 255, 0.18);
+  --text-inverse: #08121c;
+  --text-code: #e4eeff;
+  --scrollbar-thumb: rgba(143, 198, 255, 0.22);
+  --scrollbar-thumb-strong: rgba(143, 198, 255, 0.34);
+  --scrollbar-track: rgba(255, 255, 255, 0.08);
+  --ref-pill-bg: rgba(255, 255, 255, 0.16);
+  --ref-pill-text: #eef4ff;
+  --ref-pill-primary: rgba(143, 198, 255, 0.22);
+  --control-accent: #8fc6ff;
+  --panel-backdrop-filter: blur(34px) saturate(180%);
+  --surface-backdrop-filter: blur(28px) saturate(165%);
+  --control-backdrop-filter: blur(22px) saturate(160%);
+  --glass-surface-highlight: linear-gradient(180deg, rgba(255, 255, 255, 0.18), rgba(255, 255, 255, 0.05) 36%, rgba(255, 255, 255, 0.01) 62%, rgba(255, 255, 255, 0.03));
+  --glass-control-highlight: linear-gradient(180deg, rgba(255, 255, 255, 0.18), rgba(255, 255, 255, 0.05) 48%, rgba(255, 255, 255, 0.02));
+  --glass-surface-shadow: 0 18px 44px rgba(0, 0, 0, 0.22), inset 0 1px 0 rgba(255, 255, 255, 0.14), inset 0 -1px 0 rgba(255, 255, 255, 0.03);
+  --glass-control-shadow: 0 12px 28px rgba(0, 0, 0, 0.24), inset 0 1px 0 rgba(255, 255, 255, 0.14);
+  --glass-rim: rgba(255, 255, 255, 0.16);
+}
+
+:root[data-theme="aurora-glass"] .panel,
+:root[data-theme="aurora-glass"] .repo-tab,
+:root[data-theme="aurora-glass"] .repo-manager-section,
+:root[data-theme="aurora-glass"] .repo-manager-row,
+:root[data-theme="aurora-glass"] .lane,
+:root[data-theme="aurora-glass"] .change-card,
+:root[data-theme="aurora-glass"] .selection-card,
+:root[data-theme="aurora-glass"] .commit-box,
+:root[data-theme="aurora-glass"] .preview-frame,
+:root[data-theme="aurora-glass"] .branch-panel,
+:root[data-theme="aurora-glass"] .branch-row,
+:root[data-theme="aurora-glass"] .graph-viewport {
+  backdrop-filter: var(--surface-backdrop-filter);
+  box-shadow: var(--glass-surface-shadow);
+  border-color: var(--glass-rim);
+}
+
+:root[data-theme="aurora-glass"] .icon-button,
+:root[data-theme="aurora-glass"] .ghost-button,
+:root[data-theme="aurora-glass"] .branch-chip,
+:root[data-theme="aurora-glass"] .sync-chip,
+:root[data-theme="aurora-glass"] .changes-filter,
+:root[data-theme="aurora-glass"] .changes-select,
+:root[data-theme="aurora-glass"] .commit-box__input,
+:root[data-theme="aurora-glass"] .history-filter,
+:root[data-theme="aurora-glass"] .history-ref-pill {
+  backdrop-filter: var(--control-backdrop-filter);
+  box-shadow: var(--glass-control-shadow);
+  border-color: var(--glass-rim);
+}
+
+:root[data-theme="aurora-glass"] .repo-tab--active,
+:root[data-theme="aurora-glass"] .change-card--selected,
+:root[data-theme="aurora-glass"] .branch-row--selected,
+:root[data-theme="aurora-glass"] .ghost-button--active {
+  box-shadow: 0 16px 34px rgba(3, 6, 12, 0.28), inset 0 1px 0 rgba(255, 255, 255, 0.2);
+}

docs/theme-customization.md

@@ -0,0 +1,159 @@
+# Theme Customization
+
+UniGit supports theming in two layers:
+
+1. End-user custom themes through the Appearance section in the app.
+2. Full built-in themes in code by adding a new preset to the stylesheet and theme settings.
+
+The current implementation is centered around CSS variables applied to `document.documentElement`.
+
+## Quick Start For Users
+
+Open Repo Manager, then go to the `Appearance` section.
+
+If you want a simple custom theme:
+
+1. Select `Custom`.
+2. Pick a base preset such as `Dark`, `Light`, or `Liquid Glass`.
+3. Paste a JSON object with CSS variable overrides.
+
+Example:
+
+```json
+{
+  "--accent": "#8cb6ff",
+  "--accent-2": "#72f0df",
+  "--surface-card": "rgba(255, 255, 255, 0.08)",
+  "--surface-button": "rgba(255, 255, 255, 0.12)",
+  "--line-strong": "rgba(140, 182, 255, 0.42)"
+}
+```
+
+Important:
+
+- Custom themes in the current UI override CSS variables only.
+- The JSON must be a flat object.
+- Keys must start with `--`.
+- Values must be strings or numbers.
+
+## How The Theme System Works
+
+### Runtime application
+
+The app applies theme presets in [src/app/App.tsx](src/app/App.tsx) by:
+
+- Setting `document.documentElement.dataset.theme`
+- Setting `document.documentElement.style.colorScheme`
+- Applying any custom variable overrides directly on the root element
+
+### Theme settings and validation
+
+Theme preset IDs, saved state, JSON parsing, and validation live in [src/app/utils/themeSettings.ts](src/app/utils/themeSettings.ts).
+
+### CSS source of truth
+
+All theme variables and theme-specific selector overrides live in [src/styles.css](src/styles.css).
+
+The main pattern is:
+
+```css
+:root[data-theme="my-theme"] {
+  --accent: #8cb6ff;
+  --surface-card: rgba(255, 255, 255, 0.08);
+}
+
+:root[data-theme="my-theme"] .panel,
+:root[data-theme="my-theme"] .change-card {
+  backdrop-filter: blur(28px) saturate(165%);
+}
+```
+
+## Variables You Will Usually Override
+
+These variables give the biggest visual change with the least work:
+
+- `--app-background`
+- `--panel-bg-start`
+- `--panel-bg-end`
+- `--surface-section`
+- `--surface-row`
+- `--surface-card`
+- `--surface-input`
+- `--surface-button`
+- `--surface-button-strong`
+- `--surface-button-active`
+- `--surface-selection`
+- `--surface-selection-soft`
+- `--line`
+- `--line-strong`
+- `--text-1`
+- `--text-2`
+- `--text-3`
+- `--accent`
+- `--accent-2`
+- `--control-accent`
+
+For glass-like themes, these extra variables matter as well:
+
+- `--panel-backdrop-filter`
+- `--surface-backdrop-filter`
+- `--control-backdrop-filter`
+- `--glass-surface-highlight`
+- `--glass-control-highlight`
+- `--glass-surface-shadow`
+- `--glass-control-shadow`
+- `--glass-rim`
+
+## Common Selectors For Theme-Specific Styling
+
+If variables alone are not enough, these selectors are the main places to add extra treatment:
+
+- `.panel`
+- `.repo-tab`
+- `.repo-manager-section`
+- `.repo-manager-row`
+- `.lane`
+- `.change-card`
+- `.selection-card`
+- `.commit-box`
+- `.preview-frame`
+- `.branch-panel`
+- `.branch-row`
+- `.graph-viewport`
+- `.icon-button`
+- `.ghost-button`
+- `.branch-chip`
+- `.sync-chip`
+- `.changes-filter`
+- `.changes-select`
+- `.commit-box__input`
+- `.history-filter`
+
+The existing liquid-glass theme in [src/styles.css](src/styles.css) is a good example of using both variables and targeted selectors.
+
+## Adding A New Built-In Theme
+
+If you want a first-class theme preset instead of JSON overrides:
+
+1. Add the new preset ID to [src/app/utils/themeSettings.ts](src/app/utils/themeSettings.ts).
+2. Add its label and description to `themeOptions`.
+3. Add a `:root[data-theme="your-theme"]` block in [src/styles.css](src/styles.css).
+4. Add any theme-specific selector rules below the shared button and panel styles.
+5. Make sure the runtime `colorScheme` in [src/app/App.tsx](src/app/App.tsx) matches the visual intent of the theme.
+
+Use `dark` unless the theme is genuinely light, because native scrollbars and form controls follow that setting.
+
+## Example CSS Preset
+
+An example preset file is available at [docs/examples/aurora-glass-theme.css](docs/examples/aurora-glass-theme.css).
+
+That file shows:
+
+- A complete `:root[data-theme="aurora-glass"]` variable block
+- Shared glass variables
+- Theme-specific selector overrides for panels, cards, controls, and the graph viewport
+
+Note:
+
+- The example CSS file is for contributors adding a built-in theme or for future import tooling.
+- End users currently paste JSON variable overrides into the app, not raw CSS.

src/app/App.tsx

@@ -449,7 +449,7 @@ export function App() {
     const nextVariables = parseCustomThemeVariables(themeSettings);
 
     root.dataset.theme = presetId;
-    root.style.colorScheme = presetId === "dark" ? "dark" : "light";
+    root.style.colorScheme = presetId === "light" ? "light" : "dark";
 
     for (const key of appliedThemeVariableKeysRef.current) {
       if (!(key in nextVariables)) {

src/app/utils/themeSettings.ts

@@ -30,7 +30,7 @@ export const themeOptions: ThemeOption[] = [
   {
     id: "liquid-glass",
     label: "Liquid Glass",
-    description: "A translucent Apple-inspired glass treatment with bright, frosted surfaces.",
+    description: "A dark, translucent glass theme with layered highlights and deeper frosted surfaces.",
   },
   {
     id: "custom",