theme — 主题

主题插件 = 数据预设（theme.json，换色换令牌）+ 可选的界面 QML 插槽（ui_extensions）。

---

声明

{
  "id": "example.cyberpunk.theme",
  "name": "赛博朋克极客荧光主题",
  "version": "1.0.0",
  "target_app_version": "0.2",
  "type": "theme",
  "style_layer": "full",
  "entrypoint": "theme.json",
  "icon": "icon.svg",
  "enabled": false,
  "ui_extensions": {
    "overlay_background": "CyberpunkBackground.qml",
    "dialog_background": "CyberpunkDialogBackground.qml",
    "settings_background": "CyberpunkSettingsBackground.qml",
    "history_background": "CyberpunkHistoryBackground.qml",
    "audio_level": "CyberpunkAudioLevel.qml"
  },
  "config_schema": [
    { "key": "cyber_glow", "label": "高能荧光光晕", "type": "boolean", "default": true }
  ]
}

⚠️ window_backdrop 不要写在 mod.json（会被忽略），写在 theme.json 里。

主题默认 enabled: false（避免装完就换肤）。

---

theme.json

{
  "theme_id": "example.cyberpunk.theme",
  "name": "赛博朋克极客荧光主题",
  "style_layer": "full",
  "window_backdrop": "acrylic",
  "tokens": {
    "primary": "#00f0ff",
    "primaryHover": "#38f9d7",
    "primaryGlow": "rgba(0, 240, 255, 0.45)",
    "solidBg": "#2563eb",
    "solidBgHover": "#1d4ed8",
    "glassBackground": "#070b19",
    "glassCardBg": "rgba(9, 14, 32, 0.82)",
    "glassCardBorder": "rgba(0, 240, 255, 0.38)",
    "glassHoverBg": "rgba(0, 240, 255, 0.12)",
    "glassHoverBorder": "rgba(0, 240, 255, 0.65)",
    "neonBorderColor": "#00f0ff",
    "neonGlowColor": "#ff007f",
    "textPrimary": "#e0f7fa",
    "textSecondary": "#80deea"
  },
  "style_overrides": {
    "bgColor": "#070b19",
    "textColor": "#00f0ff",
    "sourceColor": "#ff2a85",
    "neonBorderColor": "#00f0ff",
    "neonGlowColor": "#ff007f",
    "fontSize": 28,
    "fontFamily": "MiSans VF",
    "bgOpacity": 0.65,
    "fontOpacity": 1.0
  }
}

---

1) 全局设计令牌 tokens

tokens 驱动全应用一键换肤（卡片、输入框、下拉框、高光、按钮）。宿主允许别名：

Token	开放别名	作用范围	默认兜底
primary	—	品牌主色、焦点强调、滑块激活、主要图标	#38bdf8
primaryHover	—	强调色悬停高亮	#60a5fa
primaryGlow	—	强调色外发光 / 光晕光斑（建议带透明度）	rgba(0.2, 0.5, 0.98, 0.28)
solidBg	actionBg	实底行动主按钮背景	#2563eb
solidBgHover	actionBgHover	实底行动主按钮悬停	#1d4ed8
activeBg	—	选中态底色	由 primary 派生
activeBgHover	—	选中态悬停底色	由 primary 派生
glassBackground	surface	深色底层磨砂背景	#11141c
glassCardBg	glassSurface	全局卡片底板	rgba(1,1,1,0.05)
glassCardBorder	glassBorder	卡片外边缘边框（霓虹主题在这里注入发光描边）	rgba(1,1,1,0.12)
glassHoverBg	hoverBg	卡片/交互项悬停底色	rgba(1,1,1,0.12)
glassHoverBorder	hoverBorder	卡片/交互项悬停描边	rgba(1,1,1,0.24)
neonBorderColor	neonBorder	霓虹发光边框主色	空（继承原生）
neonGlowColor	neonGlow	霓虹外晕辅助色	空（继承原生）
textPrimary	—	一级标题与正文	#ffffff
textSecondary	—	次级说明文案	#cbd5e1
textMuted	—	弱化辅助 / 未选中态	#94a3b8
textSubtle	—	更弱的提示文字	#64748b
divider	—	分割线与细微内衬线	rgba(1,1,1,0.08)
success / successBg	—	成功语义色	#10b981
warning / warningBg	—	警告语义色	#f59e0b
danger / dangerBg	—	危险语义色	#ef4444
fontFamily	—	全局字体族	MiSans VF
fontSizeSmall/Normal/Medium/Title/Large	—	字号档位	10 / 11 / 12 / 14 / 16
radiusSmall/Medium/Large/Pill	—	圆角档位	6 / 8 / 12 / 14

实底按钮可读性：solidBg 系底色必须压到白字对比度 ≥ 4:1（不要拿亮天蓝直接平涂白字）。 官方默认 #2563eb / 悬停 #1d4ed8 已是合规值。

---

2) 字幕悬浮窗参数 style_overrides

键	说明
bgColor（别名 background）	字幕窗底色
textColor（别名 text_color）	译文颜色
sourceColor（别名 source_color）	原文颜色
neonBorderColor / neonGlowColor（蛇形别名同义）	字幕窗双色霓虹发光
fontSize / fontFamily	字号（默认 28）与字体族（字体名会被安全清洗）
bgOpacity / fontOpacity	0.1~1.0

---

3) 分层叠层 style_layer

值	语义
full	全量预设。互斥生效；停用时自动恢复官方默认底座
material	只覆盖材质/底色维度
typography	只覆盖文字排版维度
effects	只覆盖光效装饰维度

非 full 的层可以互相混搭共存，也可以和 full 主题叠加。局部 UI 插槽扩展（如只换音柱）通常用 effects。

---

4) 窗口材质 window_backdrop

写在 theme.json 顶层（mod.json 里写了会被忽略）：

值	效果
acrylic	Windows Acrylic 亚克力
mica / mica_alt	Windows Mica / Mica Alt
blur	普通模糊
none	不使用系统材质（主题自己画底板）

---

5) 需要 QML 时

主题的 QML 插槽与背景绘制准则见：

• UI 插槽 — 槽位清单、互斥规则、背景插槽「必须自绘边框 / 圆角自适应 / 配置热响应」三条准则
• UI 扩展（QML） — 通用 QML 写法与 HostContext

参考实现：extensions/example_theme_cyberpunk/（full + 5 个插槽）、 extensions/community_theme_glassmorphism/（玻璃质感）、 extensions/example_custom_waveform_ui/（只换 audio_level 的局部扩展）。

---

相关

• UI 插槽
• UI 扩展（QML）
• config_schema — 主题的 neon_glow 之类开关
• 示例库