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

# StyleTokens

**命名空间**: `XCEngine::Editor::UI`

**类型**: `header-helper + struct`

**源文件**: `editor/src/UI/StyleTokens.h`

**描述**: 集中定义 Editor UI 的颜色、尺寸、间距与树视图样式，是当前编辑器设计系统的单一 token 源。

## 概述

`StyleTokens.h` 是当前 Editor UI 的设计语言中心。它把原本最容易散落在各个面板、各类 helper 和临时控件中的“魔法数字”集中成一组具名 token，让代码能够表达设计意图，而不是只暴露数值本身。

例如：

- `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 复用层的上游依赖。

## 设计说明

为什么这层很重要？

- 当你在重构 `ProjectPanel` 时，不应该顺手发明一套新的资产卡片尺寸。
- 当你在做 `HierarchyPanel` 的树前缀图标时，不应该自己再决定一套图标槽宽。
- 当你在优化 Inspector 的密度时，真正应该改的是 token，而不是 5 个不同 helper 里的重复常量。

这就是商业级编辑器常说的“设计系统落地到代码层”的意义。对于 XCEngine 来说，这一层还没有演化成完整的主题资产系统，但它已经承担了相同的架构角色。

## 与其他 UI helper 的关系

- `PropertyLayout` 使用它定义属性行的列宽、label inset 和 frame padding。
- `TreeView` 使用它定义缩进、前缀插槽宽度和图标尺寸。
- `SplitterChrome` 与 `DividerChrome` 使用它定义边界线和分隔条视觉。
- `Widgets` 使用它定义资产卡片、面包屑、组件 section 和各种通用控件的视觉细节。
- `BuiltInIcons` 使用它定义文件 / 文件夹 fallback 图标颜色。

从依赖方向上说，这一层应该尽量保持在 UI 栈的较底部，避免反向依赖更高层的业务 widget。

## 当前限制

- 当前仍然是“写死在代码里的默认主题”，不是运行时可切换的主题资源系统。
- token 命名已经带有明显的面板语义，例如 `ProjectNavigationPanePadding()`，说明它还是偏应用内设计系统，而不是完全抽象的通用 design token。
- 还没有颜色模式切换、用户主题文件或样式编辑器一类更高阶能力。

## 相关文档

- [UI](../UI.md)
- [BaseTheme](../BaseTheme/BaseTheme.md)
- [DockHostStyle](../DockHostStyle/DockHostStyle.md)
- [PropertyLayout](../PropertyLayout/PropertyLayout.md)
- [TreeView](../TreeView/TreeView.md)
- [SplitterChrome](../SplitterChrome/SplitterChrome.md)