Themes & UI 主题与界面

SXSEditor's UI is driven by a token-based theme system. Every color, spacing, radius, font size, motion duration, and shadow is a CSS custom property (--token) injected on :root. Themes are plain JSON objects that override these tokens. The system lives in src/themes/ and runs in the renderer process.

SXSEditor 的界面由基于 token 的主题系统驱动。每种颜色、间距、圆角、字号、动效时长与阴影都是一个注入到 :root 上的 CSS 自定义属性（--token）。主题是覆盖这些 token 的纯 JSON 对象。该系统位于 src/themes/，运行在渲染进程中。

Theme System Overview 主题系统总览

┌─ tokenCatalog.js ─────────────────────────────────────────┐
│  TOKEN_CATALOG: { '--token-name': { layer, group, type,   │
│                    default, label } }                      │
│  buildDefaultTokens(): flat { name: value } from catalog   │
│  Layers: 'global' | 'alias' | 'component'                  │
│  Types:  'color' | 'size' | 'motion' | 'shadow' | 'string' │
└────────────────────────────────────────────────────────────┘
        │ defaults
        ▼
┌─ themeManager.js (renderer) ───────────────────────────────┐
│  registry: Map(id -> { theme, source })                    │
│  activate(id): flattenTheme(extends chain) → injectTokens  │
│  mergeOverrides(patch): transient patch (not persisted)    │
│  pushHistory / undo / redo: 20-step undo stack             │
│  export(id) → JSON string; import(json) → theme object     │
│  Events: 'theme-changed', 'theme-list-changed',            │
│          'theme-overwritten', 'theme-imported'              │
└────────────────────────────────────────────────────────────┘
        │ setProperty('--token', value) on documentElement
        ▼
┌─ DOM :root ────────────────────────────────────────────────┐
│  All CSS in src/renderer.css consumes var(--token)          │
│  Canvas 2D reads via canvasTheme.getCanvasColors()          │
└────────────────────────────────────────────────────────────┘

Token Catalog Token 目录

TOKEN_CATALOG in src/themes/tokenCatalog.js is the single source of truth for every token. Each entry has a layer, group, type, default value, and a Chinese label. Tokens are organized into three layers:

src/themes/tokenCatalog.js 中的 TOKEN_CATALOG 是每个 token 的唯一来源。每个条目包含 layer、group、type、default 值与中文 label。token 分为三层：

Token types drive validation: color (hex/rgb/hsl), size (number + unit), motion (duration), shadow (free-form CSS), string (any non-empty). buildDefaultTokens() produces a flat { name: value } map from the catalog defaults, used as the base when no theme is loaded.

Token 类型驱动校验：color（hex/rgb/hsl）、size（数值 + 单位）、motion（时长）、shadow（自由 CSS）、string（任意非空）。buildDefaultTokens() 从目录默认值生成扁平的 { name: value } 映射，作为未加载主题时的基础。

Built-in Themes 内置主题

Four themes ship with SXSEditor, defined as JSON files in src/themes/builtins/ and aggregated by builtins/index.js into the BUILTIN_THEMES array:

SXSEditor 内置 4 个主题，以 JSON 文件形式定义在 src/themes/builtins/，由 builtins/index.js 聚合为 BUILTIN_THEMES 数组：

Built-in themes are imported as ES module exports so webpack bundles them. BUILTIN_THEME_IDS is the array of their ids. They are registered on startup via themeManager.registerBuiltins(BUILTIN_THEMES).

内置主题以 ES 模块导出导入，以便 webpack 打包。BUILTIN_THEME_IDS 是其 id 数组。启动时通过 themeManager.registerBuiltins(BUILTIN_THEMES) 注册。

.theme.json Format .theme.json 格式

A theme file is a JSON object with this shape (example abbreviated from dark-aurora.theme.json):

主题文件是如下结构的 JSON 对象（示例节选自 dark-aurora.theme.json）：

{
  "id": "dark-aurora",
  "name": "Aurora Dark",
  "version": "1.0.0",
  "author": "SXSEditor",
  "isDark": true,
  "description": "默认暗色主题，复刻 SXSEditor 经典蓝紫风格",
  "tags": ["builtin", "dark", "default"],
  "extends": null,
  "tokens": {
    "--color-blue-500": "#4a7de0",
    "--bg-app":     "#14141f",
    "--bg-panel":   "#1a1a2a",
    "--fg-primary": "#e0e0f0",
    "--accent":     "#5b8def",
    "--button-primary-bg": "var(--bg-button-primary)",
    ...
  }
}

Fields:

字段说明：

• id — kebab-case identifier (validated by ID_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/). Must be unique in the registry.id — kebab-case 标识符（由 ID_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/ 校验）。在注册表中必须唯一。
• name — human-readable display name.name — 人类可读的显示名。
• version — semver string (defaults to 1.0.0).version — semver 字符串（默认 1.0.0）。
• isDark — boolean. If omitted, computeIsDark derives it from --bg-app perceived luminance.isDark — 布尔值。若省略，computeIsDark 由 --bg-app 的感知亮度推导。
• author, description, tags — optional metadata.author、description、tags — 可选元数据。
• extends — id of a parent theme to inherit from (depth ≤ 3, no cycles). Parent tokens are applied first, then this theme's tokens override them.extends — 要继承的父主题 id（深度 ≤ 3，无环）。父 token 先应用，再被本主题的 tokens 覆盖。
• tokens — map of --token-name → value. Token names must match TOKEN_NAME_RE = /^--[a-z0-9][a-z0-9-]*$/.tokens — --token-name → 值 的映射。token 名必须匹配 TOKEN_NAME_RE = /^--[a-z0-9][a-z0-9-]*$/。

Creating a Custom Theme 创建自定义主题

1. Create the JSON file — place it at src/themes/builtins/my-theme.theme.json (to bundle it) or load it at runtime via themeManager.import(jsonString).创建 JSON 文件— 放在 src/themes/builtins/my-theme.theme.json（打包）或运行时通过 themeManager.import(jsonString) 加载。
2. Pick a parent — set extends to "dark-aurora" or "light-paper" so you only override the tokens you care about.选择父主题— 将 extends 设为 "dark-aurora" 或 "light-paper"，只覆盖关心的 token。
3. Override tokens — only list the --token keys you want to change. Unknown tokens are accepted as free CSS values but won't appear in the editor UI.覆盖 token— 只列出要改的 --token 键。未知 token 会作为自由 CSS 值接受，但不会出现在编辑器 UI 中。
4. Register it — for bundled themes, add an import to builtins/index.js and append to BUILTIN_THEMES. For runtime themes, call themeManager.register(themeObj).注册— 打包主题：在 builtins/index.js 加导入并追加到 BUILTIN_THEMES。运行时主题：调用 themeManager.register(themeObj)。
5. Validate — run validate(theme, { getThemeById }) from themeValidator.js. It returns { ok, errors, warnings } and does not throw.校验— 调用 themeValidator.js 的 validate(theme, { getThemeById })。返回 { ok, errors, warnings }，不会抛异常。
6. Activate — call themeManager.activate('my-theme'). Tokens are injected on :root and the 'theme-changed' event fires.激活— 调用 themeManager.activate('my-theme')。token 注入到 :root 并触发 'theme-changed' 事件。

Theme Manager API 主题管理器 API

The themeManager singleton (renderer process) exposes:

themeManager 单例（渲染进程）暴露：

Events: 'theme-changed', 'theme-list-changed', 'theme-overwritten', 'theme-imported'. Persisted overrides use the localStorage key sxseditor-theme-overrides.

事件：'theme-changed'、'theme-list-changed'、'theme-overwritten'、'theme-imported'。持久化的覆盖使用 localStorage 键 sxseditor-theme-overrides。

Extends Resolution extends 解析

flattenTheme(theme) walks the extends chain (parent first, child overrides last) and merges all tokens maps into one flat object. The chain depth is capped at MAX_EXTENDS_DEPTH=3; cycles are rejected. If a parent id is not in the registry, an error is thrown.

flattenTheme(theme) 沿 extends 链（父在前、子覆盖在后）将所有 tokens 映射合并为一个扁平对象。链深度上限 MAX_EXTENDS_DEPTH=3；环会被拒绝。若父 id 不在注册表中，则抛错。

// Example: a custom theme extending dark-aurora
{
  "id": "my-theme",
  "name": "My Theme",
  "extends": "dark-aurora",
  "tokens": {
    "--accent": "#a855f7",          // override accent to purple
    "--bg-app":  "#1a0a2a"          // override app background
    // all other tokens inherited from dark-aurora
  }
}

Canvas Theming Canvas 主题化

Canvas 2D rendering cannot read CSS var() directly. src/themes/canvasTheme.js bridges this: getCanvasColors() reads the relevant custom properties from :root (inline style first, then getComputedStyle) and returns a plain object like { bgApp, bgPanel, fgPrimary, accent, success, danger, ... }. Results are cached until invalidateCanvasThemeCache() is called.

Canvas 2D 渲染无法直接读取 CSS var()。src/themes/canvasTheme.js 桥接此问题：getCanvasColors() 从 :root 读取相关自定义属性（先内联样式，再 getComputedStyle），返回 { bgApp, bgPanel, fgPrimary, accent, success, danger, ... } 等普通对象。结果缓存直到调用 invalidateCanvasThemeCache()。

import { getCanvasColors, invalidateCanvasThemeCache } from '../themes/canvasTheme.js';
import themeManager from '../themes/themeManager.js';

themeManager.on('theme-changed', () => invalidateCanvasThemeCache());

function drawPianoRoll(ctx) {
  const c = getCanvasColors();
  ctx.fillStyle = c.bgApp;
  ctx.fillRect(0, 0, width, height);
  ctx.strokeStyle = c.accent;
  // ...
}

Theme Validation 主题校验

themeValidator.js validates theme objects without throwing — it returns { ok, errors, warnings }. Pass getThemeById to enable extends validation (parent existence, depth ≤ 3, no cycles). Validation rules:

themeValidator.js 校验主题对象但不抛异常——返回 { ok, errors, warnings }。传入 getThemeById 可启用 extends 校验（父存在、深度 ≤ 3、无环）。校验规则：

If validation fails, ThemeValidationError can be constructed from the errors array (it carries error.errors) — but the validator itself never throws, so callers decide how to surface problems.

若校验失败，可由 errors 数组构造 ThemeValidationError（它带有 error.errors）——但校验器本身从不抛异常，由调用方决定如何呈现问题。