chore: sync workspace state

docs/api/XCEngine/Editor/UI/StyleTokens/StyleTokens.md

@@ -2,45 +2,90 @@
 
 **命名空间**: `XCEngine::Editor::UI`
 
-**类型**: `header-helper`
+**类型**: `header-helper + struct`
 
 **源文件**: `editor/src/UI/StyleTokens.h`
 
-**描述**: 统一定义编辑器 UI 使用的颜色、尺寸、间距和布局 token。
+**描述**: 集中定义 Editor UI 的颜色、尺寸、间距与树视图样式，是当前编辑器设计系统的单一 token 源。
 
 ## 概述
 
-`StyleTokens.h` 是当前 UI 层的设计 token 中心。  
-它集中提供了大量 inline token helper，例如：
+`StyleTokens.h` 是当前 Editor UI 的设计语言中心。它把原本最容易散落在各个面板、各类 helper 和临时控件中的“魔法数字”集中成一组具名 token，让代码能够表达设计意图，而不是只暴露数值本身。
 
-- Dock 标签颜色
-- 工具栏高度与 padding
-- 资产网格尺寸
-- Inspector 标签列宽
-- 弹窗按钮尺寸
-- 向量控件按钮颜色
-- Console 状态颜色
+例如：
+
+- `ProjectNavigationDefaultWidth()` 表达的是“项目导航栏默认宽度”。
+- `InspectorPropertyControlColumnStart()` 表达的是“Inspector 控件列起点”。
+- `PanelSplitterHitThickness()` 表达的是“splitter 命中区宽度”。
+
+这比直接写 `248.0f`、`236.0f`、`4.0f` 更接近商业编辑器的工程实践，因为当 UI 逐步复杂起来后，真正难维护的从来不是控件本身，而是这些散落的视觉约束。
+
+## 当前 token 分组
+
+按 `editor/src/UI/StyleTokens.h` 的实现，当前 token 大致可以分成下面几类：
+
+| 类别 | 代表 token | 主要消费者 |
+|------|-------------|------------|
+| Dock host / tab | `DockHostFramePadding()`、`DockTabSelectedColor()` | `DockHostStyle`、`DockTabBarChrome` |
+| 面板与工具栏 | `PanelWindowPadding()`、`ToolbarPadding()` | `PanelChrome`、各类 panel toolbar |
+| Project 浏览器 | `ProjectNavigationDefaultWidth()`、`AssetGridSpacing()` | `ProjectPanel`、`Widgets` |
+| TreeView 导航树 | `NavigationTreeIconSize()`、`NavigationTreePrefixWidth()` | `TreeView`、`HierarchyPanel`、`ProjectPanel` |
+| Inspector / 属性布局 | `InspectorPropertyControlColumnStart()`、`ControlFramePadding()` | `PropertyLayout`、`ScalarControls`、`VectorControls`、`PropertyGrid` |
+| Popup / Combo | `PopupWindowPadding()`、`ComboPopupBackgroundColor()` | `Core`、`Widgets` |
+| 资产卡片与图标 | `AssetTileSize()`、`BuiltInFolderIconBodyColor()` | `Widgets`、`BuiltInIcons` |
+| Console / 状态栏 | `ConsoleRowHoverFillColor()`、`MenuBarStatusIdleColor()` | `Widgets`、菜单栏与 Console UI |
+
+此外，`StyleTokens.h` 里还定义了：
+
+- `struct TreeViewStyle`
+- `NavigationTreeStyle()`
+- `HierarchyTreeStyle()`
+- `ProjectFolderTreeStyle()`
+
+它们是树视图层的“组合 token”，不是单个数值，而是一组可复用的树节点视觉约束。
+
+## 当前实现行为
+
+按当前源码，这一层有几个很重要的特点：
+
+- token 目前全部是 header-only inline 函数，不是配置资产，也不是运行时可热更新的数据表。
+- 很多 helper 会把这里的 token 当默认值，而不是自己再声明一套局部常量。
+- `PropertyLayout`、`SplitterChrome`、`DockTabBarChrome`、`BuiltInIcons`、`Widgets` 都直接依赖这里的 token。
+- 某些 token 之间存在设计上的复用关系，例如 `PanelDividerColor()` 当前直接复用 splitter 的 idle 颜色。
+
+这意味着 `StyleTokens.h` 不是“装饰性文件”，而是整个 Editor UI 复用层的上游依赖。
 
 ## 设计说明
 
-这是商业编辑器 UI 非常推荐的做法。  
-不要在控件代码里到处写 `6.0f`、`0.24f`、`104.0f` 这种魔法数字，而应先抽象成 token。
+为什么这层很重要？
 
-收益包括：
+- 当你在重构 `ProjectPanel` 时，不应该顺手发明一套新的资产卡片尺寸。
+- 当你在做 `HierarchyPanel` 的树前缀图标时，不应该自己再决定一套图标槽宽。
+- 当你在优化 Inspector 的密度时，真正应该改的是 token，而不是 5 个不同 helper 里的重复常量。
 
-- 调整风格时能集中修改
-- 命名本身就表达设计意图
-- 高层 widget 与具体数值解耦
+这就是商业级编辑器常说的“设计系统落地到代码层”的意义。对于 XCEngine 来说，这一层还没有演化成完整的主题资产系统，但它已经承担了相同的架构角色。
+
+## 与其他 UI helper 的关系
+
+- `PropertyLayout` 使用它定义属性行的列宽、label inset 和 frame padding。
+- `TreeView` 使用它定义缩进、前缀插槽宽度和图标尺寸。
+- `SplitterChrome` 与 `DividerChrome` 使用它定义边界线和分隔条视觉。
+- `Widgets` 使用它定义资产卡片、面包屑、组件 section 和各种通用控件的视觉细节。
+- `BuiltInIcons` 使用它定义文件 / 文件夹 fallback 图标颜色。
+
+从依赖方向上说，这一层应该尽量保持在 UI 栈的较底部，避免反向依赖更高层的业务 widget。
 
 ## 当前限制
 
-- 仍然是 header inline 常量函数，而不是数据驱动主题系统
-- token 数量已经较多，后续可能需要再分层
-- 当前主要围绕唯一默认主题设计
+- 当前仍然是“写死在代码里的默认主题”，不是运行时可切换的主题资源系统。
+- token 命名已经带有明显的面板语义，例如 `ProjectNavigationPanePadding()`，说明它还是偏应用内设计系统，而不是完全抽象的通用 design token。
+- 还没有颜色模式切换、用户主题文件或样式编辑器一类更高阶能力。
 
 ## 相关文档
 
 - [UI](../UI.md)
 - [BaseTheme](../BaseTheme/BaseTheme.md)
-- [PanelChrome](../PanelChrome/PanelChrome.md)
-- [Widgets](../Widgets/Widgets.md)
+- [DockHostStyle](../DockHostStyle/DockHostStyle.md)
+- [PropertyLayout](../PropertyLayout/PropertyLayout.md)
+- [TreeView](../TreeView/TreeView.md)
+- [SplitterChrome](../SplitterChrome/SplitterChrome.md)