Godot UI 主题化：需要统一界面视觉风格或多主题/深色…

在 Godot 中实现一致 UI 样式、支持运行时换肤（浅色/深色/高对比度）、RTL 镜像与手柄提示图标时使用。

适用场景

解决思路

1. 应用级外观：在 Project Settings → GUI → Theme 指定项目默认主题，在 Theme 编辑器里创作，不要逐节点手写 StyleBox。
2. 单个 Control 需要不同样式时：只在该节点上使用 add_theme_*_override；绝不用它做全局样式。
3. 按钮/面板子类型：用 theme_type_variation，通过 node.theme_type_variation = &"DangerButton" 或 Inspector 下拉赋值，不要为颜色变体 fork Button 场景。
4. 运行时只想调色又不污染共享 Theme：先 stylebox.duplicate() 再改副本颜色；绝不要就地修改 Theme 里的 StyleBox。
5. 主题继承：把 Theme 资源应用在根 Control 节点上，靠级联传播到所有后代；注意子节点若自带 theme 会阻断父级级联。
6. 需要按节点/子类型覆盖时用 theme_type_variation，而不是给子节点挂自己的 theme。
7. 换根主题时用 remove_theme_*_override 清掉旧 override，避免残留 override 与新 Theme 打架。
8. 不要用标准 set() 设置主题属性（node.set("font_color", red) 无效），必须用专用 API 如 add_theme_color_override()。
9. 不要在 StyleBox 里硬编码颜色，用 theme.get_color() 取色，保持调色板单一数据源。
10. 不要在 _ready() 里为大量节点创建 StyleBox：StyleBoxFlat.new() 调用 100 次会产生 100 个独立对象；改用 Theme 资源共享继承。
11. 不要为了改一个颜色就复制场景或主题；在同一 Theme 里用 theme_type_variation 建轻量派生样式（如 "DangerButton"）。
12. StyleBoxFlat 四角圆角一致时用 corner_radius_all 简写，而不是写四个独立半径字段。
13. 不要把 StyleBox 定义为 _draw() 内的局部变量——会在 RenderingServer 完成绘制前被垃圾回收；必须存到类级别（见 memory_safe_custom_drawing.gd）。
14. 不要在 _draw() 或 _process() 中修改主题资源，频繁的布局重算会严重降低性能。
15. 不要给焦点样式直接赋 StyleBoxEmpty 而没有兜底——会隐形破坏手柄/键盘导航；务必提供可见替代（例如缩放变化），见 focus_prompt_icon_swapper.gd。
16. 不要用 expand_margin_* 扩大可点击区域——它只扩大视觉边界；改用 StyleBox 的 content_margin_* 或调整 Control 的 size。
17. 共享调色板（静态模式）：在 .theme 文件里建自定义类型 Palette，加入 Color 项（如 primary、danger、accent）。
18. 再用 SharedPalette 类提供 static func get_primary() -> Color，从 ThemeDB.get_project_theme() 取值，确保 UI 脚本与视觉主题不漂移。
19. 运行时换肤（无障碍）：给根 Control 节点换一个新的 Theme 资源，由 Godot 级联传播；不要遍历每个 Control 逐个赋主题（见 theme_swapper.gd）。
20. 对不支持自动主题的元素（自定义 _draw() 逻辑、RichText 效果）用 NOTIFICATION_THEME_CHANGED 通知更新；动态生成的 UI 用 procedural_theme_safe.gd 的模式。
21. 高对比度主题使用纯黑/纯白和更粗的焦点描边，照顾低视力无障碍需求。
22. RTL/LTR 镜像：布局方向翻转时交换 StyleBox / type-variation 库（rtl_theme_mirroring.gd），不要手翻锚点或硬编码 LTR 边距。
23. 主题化资源加载（季节变体）：把 UI 图标定义为独立 Theme 资源里的 Icon 项（如 halloween.theme、christmas.theme），换根主题资源即可瞬间级联替换所有按钮和面板的图标贴图。
24. UI 焦点管理：按设备切换手柄/键盘提示图标库，并用 Tween 把高亮面板动画到 get_global_rect()；不要把 joypad 图标路径硬编码进 Control 脚本。
25. 字体与 StyleBox 通过 Theme editor / Project Theme 编辑；运行时用 global_theme_manager.gd、theme_swapper.gd、procedural_theme_safe.gd。
26. 分辨率无关缩放用 content_scale_factor 保持字体清晰（crisp_ui_scaler.gd）；运行时主题切换与 DPI/分辨率缩放管理用 ui_scale_manager.gd。
27. 自定义 _draw() 中读取当前 Theme 的颜色/字体，参考 custom_chart_drawing.gd 的模式。
28. HUD 一致性：用 theme_isolation.gd 把节点从父主题隔离并引用 Project Defaults。
29. 动画 UI 样式：用 Tween 直接瞄准 StyleBox 属性，且必须在 duplicate() 之后操作（见 pulsating_ui_theme.gd）。
30. Atlas 打包：用 AtlasTexture 从一张大图裁切小 UI 元素，减少 VRAM 状态切换与 draw call。
31. 压缩策略：2D/像素艺术用 Lossless 避免模糊伪影；UI 背景大图用 Lossy 或 Basis Universal 省磁盘空间且不增加 VRAM 占用。
32. 资源依赖审计：用 ResourceLoader.get_dependencies(scene_path) 确认没有未压缩的原始资源（如 .png）泄漏进最终导出。
33. 需要 StyleBox / 字体的具体配置配方时，按需查阅 references/theme-authoring-recipes.md，不要预加载全部文档。

适用边界 · 注意事项

• 只做单个控件的临时颜色调整时，不必搭整套 Theme 体系，用局部 add_theme_*_override 即可。
• 非 Godot 项目不适用（依赖 Theme / StyleBox / Control 与 GDScript API）。
• 需要逐帧高频修改主题资源的场景不适用，会导致布局重算与性能严重下降。