docs(theme): theme system guide (docs/theme.md) (#55)

README.md

@@ -95,6 +95,7 @@ flutter build macos
 ## More documentation
 
 - [Security / local data](docs/security.md)
+- [Theme system](docs/theme.md)
 - [User guide](docs/user-guide.md)
 - [Releases](docs/tags-and-releases.md)
 - [Release checklist](docs/release-checklist.md)

docs/roadmap.md

@@ -2,6 +2,11 @@
 
 Living document for planned work. Not a commitment order; adjust as priorities change.
 
+## Theme system
+
+- **Done:** runtime themes, VS Code `colors` import, `tokenColors` syntax highlighting — see [theme.md](theme.md).
+- **Later:** animated theme transitions ([#57](https://github.com/QueryaHub/Querya-Desktop/issues/57)), advanced editor (LSP / `code_forge` spike).
+
 ## Query history and favorites
 
 - **Done:** `sql_query_history` in SQLite + record/list APIs; **History** in PostgreSQL / MySQL toolbars; **Preferences → Query history limit** ([`AppSettings.getSqlHistoryMaxEntries`](lib/core/storage/app_settings.dart)).

docs/theme.md

@@ -0,0 +1,164 @@
+# Querya theme system
+
+Querya Desktop uses a VS Code–inspired theme pipeline: workbench chrome colors,
+editor syntax tokens, and optional import of community `.json` / `.jsonc` themes.
+
+## Architecture
+
+```mermaid
+flowchart TB
+  subgraph input [Input]
+    VSCode["VS Code theme file\n(colors + tokenColors)"]
+    Prefs["Preferences overrides"]
+  end
+
+  subgraph parse [Parser]
+    JSONC["stripJsonc"]
+    Manifest["VsCodeThemeManifest"]
+    Map["vscode_color_map"]
+    Tokens["TokenStyleResolver"]
+  end
+
+  subgraph models [Runtime models]
+    WB["QueryaWorkbenchTheme"]
+    ED["QueryaEditorTheme"]
+    QT["QueryaTheme"]
+  end
+
+  subgraph ui [UI]
+    Scope["QueryaThemeScope"]
+    Shadcn["ShadcnApp ColorScheme"]
+    Editor["QueryaCodeEditor\nsyntax_highlight"]
+  end
+
+  VSCode --> JSONC --> Manifest
+  Manifest --> Map --> WB
+  Manifest --> Map --> ED
+  Manifest --> Tokens --> ED
+  Prefs --> Map
+  WB --> QT
+  ED --> QT
+  QT --> Scope
+  QT --> Shadcn
+  QT --> Editor
+```
+
+| Layer | Purpose |
+|-------|---------|
+| **Workbench** | Sidebar, tabs, canvas, accents, git decoration |
+| **Editor** | SQL/JSON editor surface, selection, line numbers, syntax token hues |
+| **ColorScheme** | shadcn/Material widgets (buttons, inputs, dialogs) |
+
+`ThemeController` merges layers, persists settings in `AppSettings`, and drives
+`QueryaApp` via `ListenableBuilder`.
+
+## Built-in presets
+
+- **Querya Dark** — default (`QueryaThemePreset.queryaDark`)
+- **Querya Light** — light UI (`QueryaThemePreset.queryaLight`)
+- **Imported** — after a VS Code file is imported (`QueryaThemePreset.imported`)
+
+Access tokens in widgets:
+
+```dart
+final workbench = context.workbench;
+final editor = context.editorTheme;
+final scheme = Theme.of(context).colorScheme;
+```
+
+Requires `QueryaThemeScope` above the widget (provided by `QueryaApp`).
+
+## VS Code `colors` (workbench subset)
+
+Supported keys are listed in [theme-import.md](theme-import.md) and defined in
+`lib/core/theme/parser/vscode_color_map.dart`.
+
+Merge order for the active theme:
+
+```
+effectiveColors = merge(importedTheme.colors, userOverrides)
+```
+
+Built-in preset values apply for keys not present in the merged map.
+
+### User override example
+
+Stored in `theme_overrides_json` as VS Code key → hex:
+
+```json
+{
+  "sideBar.background": "#1a1a2e",
+  "editor.background": "#16161e",
+  "focusBorder": "#89b4fa"
+}
+```
+
+API:
+
+```dart
+await ThemeController.instance.setWorkbenchColor('sideBar.background', color);
+await ThemeController.instance.clearColorOverrides();
+```
+
+## VS Code `tokenColors` (syntax highlighting)
+
+`tokenColors` entries map TextMate scopes to foreground/background/fontStyle.
+`TokenStyleResolver` resolves scopes by longest prefix (`keyword.control.sql` →
+`keyword.control` → `keyword`).
+
+Imported rules are:
+
+1. Persisted in the copied theme file under app data
+2. Applied to `QueryaEditorTheme` token fields (comment, keyword, string, …)
+3. Converted to `syntax_highlight` `HighlighterTheme` for `QueryaCodeEditor`
+
+Buffers ≥ 8KB are highlighted in a background isolate to keep typing responsive.
+
+## Importing a theme
+
+1. Open **Preferences → Appearance**
+2. Choose **Theme mode** (Dark / Light / System)
+3. Click **Import theme…** and select a VS Code `.json` or `.jsonc` file
+4. Select the imported preset from **Color preset**
+
+The file must include a `colors` object (required for import). `tokenColors` are
+optional but recommended for editor highlighting.
+
+See also: [theme-import.md](theme-import.md).
+
+## Adding a new workbench token
+
+1. Add a field to `QueryaWorkbenchTheme` (or reuse an existing one)
+2. Map a VS Code key in `kVsCodeColorMap` / `kSupportedVsCodeColorKeys`
+3. Handle the field in `_applyWorkbenchField` in `querya_theme_from_vscode.dart`
+4. Migrate UI surfaces to `context.workbench.<field>` instead of hardcoded colors
+5. Add a fixture + unit test under `test/core/theme/`
+
+## Testing
+
+| Area | Location |
+|------|----------|
+| JSONC / manifest | `test/core/theme/parser/` |
+| Color merge | `test/core/theme/parser/vscode_colors_merge_test.dart` |
+| Fixtures | `test/fixtures/themes/` |
+| ThemeController | `test/core/theme/theme_controller_test.dart` |
+| Editor highlighting | `test/core/editor/` |
+
+Run: `flutter test test/core/theme/`
+
+## Roadmap (Phase 2+)
+
+| Topic | Status |
+|-------|--------|
+| Workbench `colors` import | Done |
+| Preferences UI | Done |
+| SQL/JSON syntax highlighting | Done |
+| `tokenColors` → highlighter | Done |
+| Theme transition animation | [#57](https://github.com/QueryaHub/Querya-Desktop/issues/57) |
+| `code_forge` / LSP editor | [#52](https://github.com/QueryaHub/Querya-Desktop/issues/52) |
+
+## Related docs
+
+- [theme-import.md](theme-import.md) — supported `colors` keys and merge behavior
+- [research_theme.md](research_theme.md) — background research (RU)
+- [editor-spike-report.md](editor-spike-report.md) — code editor package evaluation