From c94023213858f765bcd7e28228144269e638016f Mon Sep 17 00:00:00 2001 From: ZhuchkaTriplesix Date: Sat, 13 Jun 2026 23:59:07 +0300 Subject: [PATCH 1/2] docs(theme): add querya.theme.v1 custom JSON schema Document required fields, color formats, key mappings, fallback rules, and examples for the native Querya theme format. Closes #96. --- docs/theme-custom-json.md | 276 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 docs/theme-custom-json.md diff --git a/docs/theme-custom-json.md b/docs/theme-custom-json.md new file mode 100644 index 00000000..c2a09f49 --- /dev/null +++ b/docs/theme-custom-json.md @@ -0,0 +1,276 @@ +# Querya custom theme JSON (`querya.theme.v1`) + +Querya supports two theme file formats: + +| Format | Root marker | Import | Docs | +|--------|-------------|--------|------| +| **Querya custom** | `"schema": "querya.theme.v1"` | Planned (theme registry) | this document | +| **VS Code** | `"colors"` object (no `schema`) | **Supported today** | [theme-import.md](theme-import.md) | + +VS Code JSON/JSONC import remains fully supported. The custom format is a first-class +Querya schema with explicit `shadcn_colors` and `editor_colors` sections instead of +VS Code workbench key names. + +## Purpose + +- Ship themes that map directly to Querya runtime models (`ColorScheme`, + `QueryaEditorTheme`, `QueryaWorkbenchTheme`) without VS Code key indirection. +- Keep theme list scans lightweight: read metadata and color maps as strings; build + `QueryaTheme` only when a theme is selected. +- Scale to 50+ installed themes with predictable fallback behavior. + +Implementation (planned): `lib/core/theme/parser/querya_theme_manifest.dart` and +registry services described in +[theme-parser-implementation-tasks.md](theme-parser-implementation-tasks.md). + +## Root object + +### Required fields + +| Field | Type | Description | +|-------|------|-------------| +| `schema` | string | Must be exactly `querya.theme.v1`. | +| `id` | string | Stable machine id (slug). Used for filenames and settings. Lowercase letters, digits, hyphens recommended. | +| `name` | string | Human-readable label shown in Preferences. | +| `type` | string | `"dark"` or `"light"`. Selects fallback preset (`QueryaTheme.darkDefault` / `QueryaTheme.lightDefault`). | +| `shadcn_colors` | object | String map → shadcn `ColorScheme` tokens. May be `{}`; missing keys fall back to the preset. | +| `editor_colors` | object | String map → editor and workbench tokens. May be `{}`; missing keys fall back to the preset. | + +### Optional fields + +| Field | Type | Description | +|-------|------|-------------| +| `tokenColors` | array | VS Code–compatible syntax rules (same shape as VS Code themes). Applied to SQL/JSON highlighting. | +| `description` | string | Short summary for theme picker / marketplace. | +| `author` | string | Author or org name. | +| `version` | string | Theme package version (informational). | + +Unknown root fields are ignored. In debug builds the parser may log skipped keys. + +## Color string formats + +All color values are hex strings. The parser reuses `parseVsCodeColor` (via a thin +Querya wrapper) and accepts: + +| Format | Example | Notes | +|--------|---------|-------| +| `#RRGGBB` | `"#22D3EE"` | Most common | +| `RRGGBB` | `"22D3EE"` | `#` optional | +| `#RRGGBBAA` | `"#FF22D3EE"` | Alpha last (VS Code style) | +| `RRGGBBAA` | `"FF22D3EE"` | `#` optional | +| `#RGB` | `"#F0A"` | Expanded to `#FF00AA` | +| `#RGBA` | `"#F0A8"` | Expanded to `#FF00AA88` | + +Invalid optional color values are **skipped** for that key; the fallback preset value +is used instead. Empty strings are treated as invalid. + +## `shadcn_colors` keys + +Maps to `shadcn_flutter.ColorScheme` (see `QueryaTheme.colorScheme`). + +| Key | Role | +|-----|------| +| `background` | App / page background | +| `foreground` | Primary text | +| `card` | Card surface | +| `cardForeground` | Text on cards | +| `popover` | Popover / dropdown surface | +| `popoverForeground` | Text on popovers | +| `primary` | Primary actions | +| `primaryForeground` | Text on primary | +| `secondary` | Secondary surfaces | +| `secondaryForeground` | Text on secondary | +| `muted` | Muted surfaces | +| `mutedForeground` | Muted labels | +| `accent` | Hover / accent fills | +| `accentForeground` | Text on accent | +| `destructive` | Destructive actions | +| `destructiveForeground` | Text on destructive | +| `border` | Borders | +| `input` | Input borders / fills | +| `ring` | Focus ring | +| `chart1` … `chart5` | Chart palette | + +Brightness comes from `type`, not from individual colors. + +## `editor_colors` keys + +One map feeds both `QueryaEditorTheme` and `QueryaWorkbenchTheme`. + +### Editor (syntax surface) + +| Key | Target | +|-----|--------| +| `background` | Editor background | +| `foreground` | Default text | +| `lineHighlight` | Current line highlight | +| `selection` | Selection background | +| `lineNumber` | Gutter numbers | +| `bracketMatch` | Matching bracket highlight | +| `widgetBorder` | Editor chrome border | +| `comment` | Comment token (fallback when no `tokenColors` match) | +| `keyword` | Keyword token | +| `string` | String token | +| `number` | Numeric token | +| `operator` | Operator token | +| `function` | Function token | +| `type` | Type name token | + +### Workbench (chrome) + +| Key | Target | +|-----|--------| +| `canvas` | Main app canvas (title bar, status areas) | +| `surface` | Raised panels, tabs | +| `sidebarBackground` | Explorer / sidebar | +| `editorBackground` | Editor pane chrome (may differ from syntax `background`) | +| `mutedForeground` | Secondary labels | +| `accent` | Brand / focus accent | +| `onAccent` | Text/icons on accent | +| `borderSubtle` | Subtle dividers | +| `destructive` | Error / delete emphasis | +| `success` | Success state | +| `warning` | Warning state | +| `gitModified` | Git modified decoration | +| `gitUntracked` | Git untracked decoration | + +If `background` appears without `canvas`, the parser does **not** auto-map it unless +explicitly documented in a future schema revision. Prefer `canvas` and +`editorBackground`. + +## `tokenColors` + +Same structure as VS Code themes: array of objects with `scope` (string or array), +optional `name`, and `settings.foreground` / `settings.background` / `settings.fontStyle`. + +Querya applies these through `TokenStyleResolver` → SQL/JSON highlighters. See +[theme-import.md](theme-import.md) for behavior notes. + +## Fallback and error handling + +| Situation | Behavior | +|-----------|----------| +| Missing optional color key | Use value from `QueryaTheme.darkDefault` or `QueryaTheme.lightDefault` (based on `type`). | +| Invalid optional color | Skip key; use fallback value. | +| Missing required root field (`schema`, `id`, `name`, `type`, `shadcn_colors`, `editor_colors`) | Parsing fails; theme is not loaded. | +| Wrong `schema` value | Parsing fails. | +| Invalid `type` | Parsing fails. | +| Broken file at startup (selected theme) | App starts with **Querya Dark**; error surfaced in Preferences (planned). User setting is not deleted. | +| Broken file in directory scan | Skipped or shown as disabled in picker (planned); scan does not crash the app. | + +## JSONC + +Comments and trailing commas are allowed in `.jsonc` files. The shared preprocessor +`stripJsonc` runs before `jsonDecode` (same as VS Code import). + +## Minimal example + +Only required fields; all colors come from Querya Dark defaults: + +```json +{ + "schema": "querya.theme.v1", + "id": "querya-dark-clone", + "name": "Querya Dark (minimal)", + "type": "dark", + "shadcn_colors": {}, + "editor_colors": {} +} +``` + +## Full example (dark) + +```json +{ + "schema": "querya.theme.v1", + "id": "cyberpunk-neon", + "name": "Cyberpunk Neon", + "type": "dark", + "description": "Neon cyberpunk preset for Querya workbench and SQL editor.", + "author": "QueryaHub", + "version": "1.0.0", + "shadcn_colors": { + "background": "#09090B", + "foreground": "#F8FAFC", + "card": "#111113", + "cardForeground": "#F8FAFC", + "popover": "#111113", + "popoverForeground": "#F8FAFC", + "primary": "#00F5FF", + "primaryForeground": "#020617", + "secondary": "#18181B", + "secondaryForeground": "#F8FAFC", + "muted": "#18181B", + "mutedForeground": "#94A3B8", + "accent": "#FF2A6D", + "accentForeground": "#F8FAFC", + "destructive": "#EF4444", + "destructiveForeground": "#F8FAFC", + "border": "#27272A", + "input": "#27272A", + "ring": "#00F5FF", + "chart1": "#00F5FF", + "chart2": "#FF2A6D", + "chart3": "#FCEE09", + "chart4": "#BD00FF", + "chart5": "#39FF14" + }, + "editor_colors": { + "background": "#0A0A14", + "foreground": "#E8F4FF", + "selection": "#FF2A6D44", + "lineNumber": "#4A3F7A", + "bracketMatch": "#00F5FF33", + "widgetBorder": "#00F5FF66", + "canvas": "#050508", + "surface": "#14102A", + "sidebarBackground": "#0C0820", + "editorBackground": "#0A0A14", + "mutedForeground": "#8B7CF8", + "accent": "#00F5FF", + "onAccent": "#020617", + "borderSubtle": "#27272A", + "destructive": "#EF4444", + "gitModified": "#FCEE09", + "gitUntracked": "#39FF14" + }, + "tokenColors": [ + { + "name": "Comments", + "scope": ["comment", "comment.line"], + "settings": { "foreground": "#5C4D8A", "fontStyle": "italic" } + }, + { + "name": "Keywords", + "scope": ["keyword", "keyword.control"], + "settings": { "foreground": "#FF2A6D", "fontStyle": "bold" } + }, + { + "name": "Strings", + "scope": ["string"], + "settings": { "foreground": "#FCEE09" } + } + ] +} +``` + +## VS Code format vs Querya custom + +| | VS Code JSON/JSONC | Querya custom | +|--|-------------------|---------------| +| Detection | No `schema`; has `colors` | `"schema": "querya.theme.v1"` | +| UI colors | VS Code keys (`editor.background`, `sideBar.background`, …) | `shadcn_colors` + `editor_colors` Querya keys | +| Stable id | File name only | Required `id` field | +| Import today | **Yes** — Preferences → Import theme | Planned via theme registry | +| Syntax tokens | `tokenColors` | `tokenColors` (same) | + +To convert a VS Code theme manually, map keys using +[theme-import.md](theme-import.md) and place workbench values into `editor_colors`; +derive shadcn tokens from your palette or leave `{}` to use preset defaults. + +## Related docs + +- [Theme import (VS Code)](theme-import.md) +- [Theme system overview](theme.md) +- [Implementation plan](theme-parser-implementation-tasks.md) +- Sample VS Code themes: `themes/samples/cyberpunk-neon.json` From 6ade631c1529f395dc5115c7a640c337e72210a6 Mon Sep 17 00:00:00 2001 From: ZhuchkaTriplesix Date: Sat, 13 Jun 2026 23:59:07 +0300 Subject: [PATCH 2/2] docs(theme): link custom theme JSON from import guide and index Point VS Code import docs and the docs index to theme-custom-json.md. --- docs/README.md | 1 + docs/theme-import.md | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/docs/README.md b/docs/README.md index 8d3112d6..2eecb4c7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,6 +14,7 @@ Index of Querya Desktop documentation, grouped by audience. - [Architecture](architecture.md) — `lib/` layout and module responsibilities. - [Theme system](theme.md) — runtime theming and VS Code theme tokens. - [Theme import](theme-import.md) — supported `colors` keys and merge behavior. +- [Custom theme JSON](theme-custom-json.md) — `querya.theme.v1` schema and fallback rules. - [Performance baseline](perf-baseline.md) — per-milestone DevTools checklist. ## For release managers diff --git a/docs/theme-import.md b/docs/theme-import.md index 0ccacb70..6403ef83 100644 --- a/docs/theme-import.md +++ b/docs/theme-import.md @@ -3,6 +3,10 @@ Querya can apply a **subset** of VS Code theme JSON / JSONC `colors` to `QueryaWorkbenchTheme`, `QueryaEditorTheme`, and the shadcn `ColorScheme`. +For the native Querya custom format (`querya.theme.v1`), see +**[theme-custom-json.md](theme-custom-json.md)**. Both formats will coexist; VS Code +import remains supported. + Imported `tokenColors` are persisted with the theme file and applied to SQL/JSON syntax highlighting via `TokenStyleResolver` → `HighlighterTheme` (issue #46).