diff --git a/docs/architecture/foundations/startup-and-registration.md b/docs/architecture/foundations/startup-and-registration.md
index 507eb2d21..862ee1104 100644
--- a/docs/architecture/foundations/startup-and-registration.md
+++ b/docs/architecture/foundations/startup-and-registration.md
@@ -58,7 +58,7 @@ public override void Initialize()
 本地化 bootstrap 先注册应用 Catalog 和外部语言包 Bundle，随后执行用户注册动作；最后分别构建全部支持语言
 Snapshot 与主题 schema、ControlTheme asset manifest、首个 ThemeSnapshot、Root ThemeContext 和唯一 ThemeManager。
 
-构建后的主题运行流见 [AtomUI.Core 主题系统](../../modules/core/theme-system.md)。简化顺序是：
+构建后的主题运行流见 [AtomUI 主题系统](../systems/theming/runtime.md)。简化顺序是：
 
 1. 本地化 Builder 冻结 Catalog/Bundle Registry，为全部支持语言生成完整 Snapshot，并以默认语言初始化稳定
    `LanguageResourceProvider`、`ILanguageManager` 与 `ILocalizer`。
diff --git a/docs/architecture/systems/index.md b/docs/architecture/systems/index.md
index 8b1dd9026..810a581d7 100644
--- a/docs/architecture/systems/index.md
+++ b/docs/architecture/systems/index.md
@@ -5,4 +5,6 @@
 系统文档必须定义稳定模型、职责 owner、数据流、生命周期、兼容性和验证不变量。单个模块的实现结构继续放在
 `docs/modules/`；使用步骤和示例进入 `docs/guides/`；精确格式和协议进入 `docs/reference/`。
 
-主题、本地化、Control 基础设施、渲染和窗口系统将在完成职责迁移后从本入口统一导航。
+- [主题系统](theming/index.md)：主题运行时、Token、Semantic Part、定制 Guide 和 XML Reference。
+
+本地化、Control 基础设施、渲染和窗口系统在对应文档完成迁移后继续从本入口统一导航。
diff --git a/docs/architecture/systems/theming/index.md b/docs/architecture/systems/theming/index.md
new file mode 100644
index 000000000..8431a0e72
--- /dev/null
+++ b/docs/architecture/systems/theming/index.md
@@ -0,0 +1,10 @@
+# 主题系统
+
+AtomUI 主题系统跨越 Core 运行时、Control 包、主题资产、Source Generator、配置文件和 Gallery 工具。
+
+- [主题系统架构](runtime.md)：配置、编译、Snapshot、资源、作用域、事务、缓存、生命周期和 AOT。
+- [Semantic Part 系统](semantic-parts.md)：稳定视觉区域、Selector、descriptor、Popup 和兼容性。
+- [主题定制指南](../../../guides/theming/customization.md)：应用和第三方 Control 的使用路径。
+- [主题定义 XML v1](../../../reference/theming/theme-definition-xml-v1.md)：版本化主题文件协议。
+- [AtomUI.Core 模块](../../../modules/core/index.md)：主题运行时在 Core 项目中的源码所有权。
+- [AtomUI.Generator 模块](../../../modules/generator/overview.md)：主题和 Semantic Part 的构建期生成实现。
diff --git a/docs/modules/core/theme-system.md b/docs/architecture/systems/theming/runtime.md
similarity index 99%
rename from docs/modules/core/theme-system.md
rename to docs/architecture/systems/theming/runtime.md
index cee625e7d..c000b6e3d 100644
--- a/docs/modules/core/theme-system.md
+++ b/docs/architecture/systems/theming/runtime.md
@@ -1,12 +1,10 @@
 # AtomUI 主题系统架构
 
-本文是 AtomUI 主题系统唯一的长期架构设计文档。它定义最终运行时模型、公开配置语义、主题来源解析、主题文件
-处理、Catalog 刷新、Token 编译、动态作用域、资源发布、事件契约、AOT 边界和验收标准。阶段性分析、迁移过程和
-任务进度不写入本文。
+本文是 AtomUI 主题系统唯一的长期架构设计文档。它定义当前运行时模型、公开配置语义、主题来源解析、主题文件
+处理、Catalog 刷新、Token 编译、动态作用域、资源发布、事件契约、AOT 边界和验收标准。
 
-本文描述目标架构。实现过程中不得为了保留旧主题系统 API 而偏离这些约束。
-面向主题作者和 Control 开发者的分层讲解与定制示例见
-[AtomUI 主题系统架构与主题定制指南](theme-architecture-and-customization.md)。
+本文定义当前架构。既有兼容对象不得成为绕过这些约束的旁路。面向主题作者和 Control 开发者的分层讲解与定制
+示例见 [AtomUI 主题定制指南](../../../guides/theming/customization.md)。
 
 ## 1. 设计目标
 
@@ -400,8 +398,8 @@ Token 和主题资产。Own Token 使用无参数 `[ControlDesignToken]` 供生
 - Token 是空元素，必须通过 `Value` 属性提供非空值，不允许正文值或类型分类属性。
 
 完整格式、词法、安全限制、diagnostic 和版本演进规则见
-[主题定义 XML v1 规范](theme-definition-xml.md)，机器可读标准见
-[AtomUI Theme Definition XML Schema v1](schemas/atomui-theme-v1.xsd)。
+[主题定义 XML v1 规范](../../../reference/theming/theme-definition-xml-v1.md)，机器可读标准见
+[AtomUI Theme Definition XML Schema v1](../../../reference/theming/schemas/atomui-theme-v1.xsd)。
 
 ### 6.2 两阶段处理
 
@@ -1047,7 +1045,7 @@ deferred AXAML 和 manifest 必须由同一资产输入确定性产生；运行
 
 Control 的稳定视觉区域通过 `.semantic-*` Selector 和生成式 `ControlSemanticDescriptor` 公开。Descriptor 记录
 Part name、path、ContractType、cardinality、customization 和跨视觉根信息；运行时样式匹配仍完全由 Avalonia
-Selector 完成。完整模型见 [Semantic Part 系统设计](semantic-part-system.md)。
+Selector 完成。完整模型见 [Semantic Part 系统设计](semantic-parts.md)。
 
 稳定且允许用户完整替换的 public 子 Control 可以额外通过强类型 `ControlTheme?` 属性公开，例如
 `SearchEdit.SearchButtonTheme`。这类 Semantic Part Theme 不创建 Token identity，也不使用字符串 Part 字典。
@@ -1468,9 +1466,9 @@ ThemeManager 提交 snapshot，Resources 只读取已提交 snapshot。Compilati
 替换为下划线，禁止多个程序集生成相同全限定类型名，也禁止把生成 namespace 嵌套在可能同名的 Control
 类型下面。
 
-## 21. 明确删除的旧设计
+## 21. 禁止的架构旁路
 
-新架构实现时删除：
+以下旁路不属于当前架构，禁止重新引入：
 
 - `Theme`、`ITheme` 以及预创建 Theme variant pool。
 - `ThemeCoordinator` 以及一对一 `ThemeManager`/`ThemeEngine` facade 分层；事务队列和当前状态只有 Manager 一个
@@ -1495,7 +1493,7 @@ ThemeManager 提交 snapshot，Resources 只读取已提交 snapshot。Compilati
 - cache pin、父 snapshot Version cache key 和字符串拼接 cache key。
 - 旧主题 XML 的 `ControlTokens/ControlToken` 结构。
 
-这些内容不建立 adapter，不标记 obsolete 后继续保留，也不作为迁移阶段的内部真源。
+这些内容不建立 adapter，也不能以 obsolete、兼容层或内部入口的形式继续存在。
 
 ## 22. 验收标准
 
diff --git a/docs/modules/core/semantic-part-system.md b/docs/architecture/systems/theming/semantic-parts.md
similarity index 94%
rename from docs/modules/core/semantic-part-system.md
rename to docs/architecture/systems/theming/semantic-parts.md
index 432a1cf1d..1ae0604a6 100644
--- a/docs/modules/core/semantic-part-system.md
+++ b/docs/architecture/systems/theming/semantic-parts.md
@@ -5,8 +5,8 @@ Semantic Part 是 AtomUI Control 对稳定视觉区域提供的公共定制契
 internal 类型或偶然的视觉树结构。
 
 本文档定义 Semantic Part 的统一模型、Selector 契约、主题边界、构建期描述、兼容性和验证要求。ControlTheme
-资产、Token schema 和主题运行时的完整架构分别见 [主题系统架构](theme-system.md)；生成器实现见
-[Semantic Part Generator](../generator/semantic-part-generator.md)。
+资产、Token schema 和主题运行时的完整架构见 [主题系统架构](runtime.md)；生成器实现见
+[Semantic Part Generator](../../../modules/generator/semantic-part-generator.md)。
 
 ## 1. 设计定位
 
@@ -368,7 +368,7 @@ public partial class Button;
 ```
 
 生成器负责产生静态 descriptor、Part 名称与 class 常量、包级注册以及诊断。详细输入输出见
-[Semantic Part Generator](../generator/semantic-part-generator.md)。
+[Semantic Part Generator](../../../modules/generator/semantic-part-generator.md)。
 
 ## 12. 性能与 AOT
 
@@ -440,12 +440,12 @@ Button 的 `root`、`icon`、`content` 可以作为基础契约测试样本；
 
 ## 16. 相关文档
 
-- [Semantic Part Generator 设计](../generator/semantic-part-generator.md)：构建期输入、模板分析、descriptor、诊断和
+- [Semantic Part Generator 设计](../../../modules/generator/semantic-part-generator.md)：构建期输入、模板分析、descriptor、诊断和
   AOT 输出。
-- [AtomUI 控件研发标准规范](../../engineering/control-development-guidelines.md)：Control 作者必须遵守的 Part
+- [AtomUI 控件研发标准规范](../../../engineering/control-development-guidelines.md)：Control 作者必须遵守的 Part
   声明、模板和兼容性规则。
-- [AtomUI 控件 Token 设计规范](../../engineering/control-token-guidelines.md)：Semantic Part、Part Theme 和 Token
+- [AtomUI 控件 Token 设计规范](../../../engineering/control-token-guidelines.md)：Semantic Part、Part Theme 和 Token
   identity 的职责边界。
-- [AtomUI 控件文档规范](../../engineering/control-documentation-guidelines.md)：单控件 Semantic Parts 表与 LLMS
+- [AtomUI 控件文档规范](../../../engineering/control-documentation-guidelines.md)：单控件 Semantic Parts 表与 LLMS
   文档同步规则。
-- [AOT 编程规范](../../engineering/aot-programming-guidelines.md)：静态注册、反射和运行时发现边界。
+- [AOT 编程规范](../../../engineering/aot-programming-guidelines.md)：静态注册、反射和运行时发现边界。
diff --git a/docs/engineering/control-development-guidelines.md b/docs/engineering/control-development-guidelines.md
index 8a4df35b1..e12124dfd 100644
--- a/docs/engineering/control-development-guidelines.md
+++ b/docs/engineering/control-development-guidelines.md
@@ -58,7 +58,7 @@ API 和主题契约包括但不限于：
 ## Semantic Part
 
 Control 对稳定视觉区域提供公共定制入口时，必须遵循
-[AtomUI Semantic Part 系统设计](../modules/core/semantic-part-system.md)。Semantic Part 是主题兼容性契约，不是
+[AtomUI Semantic Part 系统设计](../architecture/systems/theming/semantic-parts.md)。Semantic Part 是主题兼容性契约，不是
 模板节点清单。
 
 - 除隐式 `root` 外，公开 Part 使用唯一 `.semantic-*` class，名称由语义职责产生，不包含 `PART_*`、序号或当前
diff --git a/docs/engineering/control-token-guidelines.md b/docs/engineering/control-token-guidelines.md
index 5de18c064..4cb66b5e6 100644
--- a/docs/engineering/control-token-guidelines.md
+++ b/docs/engineering/control-token-guidelines.md
@@ -2,9 +2,9 @@
 
 本文档定义 `AtomUI.Controls`、`AtomUI.Desktop.Controls`、DataGrid、ColorPicker 和第三方 AtomUI Control 包的
 Control Token、ControlTheme Asset 与组合主题规则。完整编译、snapshot 和资源发布模型见
-[AtomUI 主题系统架构](../modules/core/theme-system.md)。单个 Control 的 `token.md` 只记录 Own Token 语义和必要的
+[AtomUI 主题系统架构](../architecture/systems/theming/runtime.md)。单个 Control 的 `token.md` 只记录 Own Token 语义和必要的
 Global Token 使用示例；全部 Global Token 都可覆盖，不在单 Control 文档中复制支持清单。面向主题作者的完整定制流程见
-[主题系统架构与主题定制指南](../modules/core/theme-architecture-and-customization.md)。
+[主题定制指南](../guides/theming/customization.md)。
 
 ## Token 分层
 
@@ -195,7 +195,7 @@ AXAML。只有一个 ControlTheme 时就只有一个主题文件。
 ## Semantic Part 与 Semantic Part Theme
 
 Semantic Part 的基础契约是 `.semantic-*` Selector、稳定 ContractType 和生成式 descriptor，完整设计见
-[AtomUI Semantic Part 系统设计](../modules/core/semantic-part-system.md)。Token 只表达 Control 的稳定设计值，不为
+[AtomUI Semantic Part 系统设计](../architecture/systems/theming/semantic-parts.md)。Token 只表达 Control 的稳定设计值，不为
 每个 Part 创建独立 Token identity，也不使用模板节点名称扩展 Token schema。
 
 当某个 Part 是真实 public Control，并且允许用户完整替换其 ControlTheme 时，可以额外通过强类型
diff --git a/docs/guides/index.md b/docs/guides/index.md
new file mode 100644
index 000000000..0089883d4
--- /dev/null
+++ b/docs/guides/index.md
@@ -0,0 +1,6 @@
+# 使用指南
+
+本目录按开发任务组织 AtomUI 的使用、接入和定制说明。Guide 解释如何完成任务，但不单独定义公共 API、格式协议
+或架构不变量；稳定契约分别由 Architecture、Control 文档和 Reference 拥有。
+
+- [主题指南](theming/index.md)
diff --git a/docs/modules/core/theme-architecture-and-customization.md b/docs/guides/theming/customization.md
similarity index 95%
rename from docs/modules/core/theme-architecture-and-customization.md
rename to docs/guides/theming/customization.md
index 9ff67f577..40f66dfc9 100644
--- a/docs/modules/core/theme-architecture-and-customization.md
+++ b/docs/guides/theming/customization.md
@@ -1,9 +1,9 @@
-# AtomUI 主题系统架构与主题定制指南
+# AtomUI 主题定制指南
 
 AtomUI 的主题系统不是一组可以随意覆盖的 Brush，也不是在每个 ControlTheme 外面再包一层 ResourceDictionary。
 它解决的是一个更完整的问题：如何用稳定的设计语言描述全局视觉，允许单个 Control 精确偏离全局规则，又能在
 运行时安全切换主题、建立局部主题、支持第三方 Control，并保持 NativeAOT、性能和资源生命周期可控。
-本文定义这些能力在 Avalonia、C# 和 AtomUI ControlTheme 中的稳定语义与使用边界。
+本文说明这些能力在 Avalonia、C# 和 AtomUI ControlTheme 中的使用方式与定制边界。
 
 本文面向两类读者：
 
@@ -11,8 +11,7 @@ AtomUI 的主题系统不是一组可以随意覆盖的 Brush，也不是在每
 - 希望开发 AtomUI Control、主题包或维护主题运行时的工程师。
 
 本文先建立容易理解的心智模型，再逐步进入 Token 计算、Control identity、主题资产、作用域、事务和 AOT 等
-实现边界。本文与主题系统架构文档共同描述目标契约；示例表达最终稳定用法，不承担旧主题 API 的兼容说明。
-严格的协议与验收条件仍以 [AtomUI 主题系统架构](theme-system.md) 为准。
+使用边界。稳定运行时契约与验收条件以 [AtomUI 主题系统架构](../../architecture/systems/theming/runtime.md) 为准。
 
 ## 1. 先把主题理解成一次编译
 
@@ -329,7 +328,7 @@ Theme Definition XML 适合声明可命名、可切换、可放入应用资源
 Binder 会根据当前 registry revision 验证 Button identity、Token 名和值类型。Button Own Token 与任意已注册
 Global Token 都可以配置；只有名称在这两个 schema 中都不存在时才失败。
 
-完整 XML 协议、算法形态和安全限制见 [主题定义 XML v1 规范](theme-definition-xml.md)。
+完整 XML 协议、算法形态和安全限制见 [主题定义 XML v1 规范](../../reference/theming/theme-definition-xml-v1.md)。
 
 ### 8.1 让主题进入 ThemeCatalog
 
@@ -471,7 +470,7 @@ ControlTheme 不声明 Token scope。`RatingTokenResource` 已经明确了 ident
 
 Control 通过稳定 `.semantic-*` Selector 开放少量公共视觉区域。用户可以在 Application、局部 StyleHost 或单个
 Control 的 `Styles` 中定制这些区域，而不依赖 `PART_*`、Name 或 internal 类型。完整契约见
-[Semantic Part 系统设计](semantic-part-system.md)。
+[Semantic Part 系统设计](../../architecture/systems/theming/semantic-parts.md)。
 
 当 Part 是真实 public 子 Control，并且需要允许完整替换其 ControlTheme 时，owner 可以额外使用强类型
 `ControlTheme?` 属性开放 Semantic Part Theme。
@@ -532,7 +531,7 @@ this.UseAtomUI(builder =>
 });
 ```
 
-详细注册顺序见 [Desktop Controls 主题注册](../desktop-controls/theme-registration.md)。
+详细注册顺序见 [Desktop Controls 主题注册](../../modules/desktop-controls/theme-registration.md)。
 
 ## 15. 一次主题切换为什么不会暴露半成品
 
@@ -618,9 +617,9 @@ Control 使用同一条确定性路径。
 
 ## 相关文档
 
-- [AtomUI 主题系统架构](theme-system.md)：完整运行时模型、事务、缓存、生命周期和验收标准。
-- [Semantic Part 系统设计](semantic-part-system.md)：稳定视觉区域、Selector、ContractType、Popup 和兼容性契约。
+- [AtomUI 主题系统架构](../../architecture/systems/theming/runtime.md)：完整运行时模型、事务、缓存、生命周期和验收标准。
+- [Semantic Part 系统设计](../../architecture/systems/theming/semantic-parts.md)：稳定视觉区域、Selector、ContractType、Popup 和兼容性契约。
 - [Control Token 设计规范](../../engineering/control-token-guidelines.md)：Control 和第三方 Control 的研发约束。
-- [主题定义 XML v1 规范](theme-definition-xml.md)：主题文件格式、算法和验证规则。
-- [启动与注册链路](../../architecture/startup-and-registration.md)：应用、Control 包和 ThemeManager 的构建顺序。
-- [Desktop Controls 主题注册](../desktop-controls/theme-registration.md)：内置与第三方 Control 包注册边界。
+- [主题定义 XML v1 规范](../../reference/theming/theme-definition-xml-v1.md)：主题文件格式、算法和验证规则。
+- [启动与注册链路](../../architecture/foundations/startup-and-registration.md)：应用、Control 包和 ThemeManager 的构建顺序。
+- [Desktop Controls 主题注册](../../modules/desktop-controls/theme-registration.md)：内置与第三方 Control 包注册边界。
diff --git a/docs/guides/theming/index.md b/docs/guides/theming/index.md
new file mode 100644
index 000000000..0b01b9240
--- /dev/null
+++ b/docs/guides/theming/index.md
@@ -0,0 +1,5 @@
+# 主题指南
+
+- [主题定制指南](customization.md)：Token、主题文件、暗色与紧凑算法、局部主题、ControlTheme 和 Semantic Part。
+- [主题系统架构](../../architecture/systems/theming/runtime.md)：完整运行时契约。
+- [主题定义 XML v1](../../reference/theming/theme-definition-xml-v1.md)：主题文件协议。
diff --git a/docs/index.md b/docs/index.md
index 50ee72168..c436bbbbd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,8 +7,11 @@ AtomUI 文档按知识责任组织。跨模块系统设计、单个源码模块
 
 - [整体架构](architecture/index.md)：系统分层、源码包边界和核心运行链路。
 - [架构基础](architecture/foundations/index.md)：项目依赖、运行平台、启动注册、构建和打包。
+- [跨模块系统](architecture/systems/index.md)：主题及后续跨模块系统的统一入口。
 - [源码模块](modules/)：按源码项目或发布包理解职责和实现边界。
 - [Control 文档](controls/overview.md)：按平台和类别查看具体 Control 的设计、实现、Token 和变更。
+- [使用指南](guides/index.md)：按任务查看主题定制与后续接入指南。
+- [Reference](reference/index.md)：版本化格式、协议和稳定公共契约。
 - [工程规范](engineering/)：开发、AOT、诊断、文档、测试和发布规则。
 - [Gallery 文档](gallery/)：Gallery 组织、ShowCase 和平台维护说明。
 - [Superpowers](superpowers/)：设计过程、实施计划和阶段进度，不作为正式架构的事实来源。
diff --git a/docs/modules/core/overview.md b/docs/modules/core/index.md
similarity index 82%
rename from docs/modules/core/overview.md
rename to docs/modules/core/index.md
index 5e9db1184..be63ea506 100644
--- a/docs/modules/core/overview.md
+++ b/docs/modules/core/index.md
@@ -15,7 +15,7 @@
 
 ## 关键目录
 
-主题系统按照 [主题系统架构](theme-system.md) 的职责边界组织：
+主题实现按照 [主题系统架构](../../architecture/systems/theming/runtime.md) 的职责边界组织：
 
 | 目录 | 说明 |
 |---|---|
@@ -43,12 +43,11 @@ registry 后不扫描上层程序集或 AXAML。它对多个上层项目开放 `
 
 ## 相关文档
 
-- [主题系统架构](theme-system.md)
-- [Semantic Part 系统设计](semantic-part-system.md)
+- [主题系统架构](../../architecture/systems/theming/runtime.md)
+- [Semantic Part 系统设计](../../architecture/systems/theming/semantic-parts.md)
 - [AtomUI 多语言模块架构](../localization/overview.md)
-- [主题系统架构与主题定制指南](theme-architecture-and-customization.md)
-- [主题算法枚举化设计](theme-algorithm-enum-design.md)
-- [主题定义 XML v1 规范](theme-definition-xml.md)
-- [AtomUI Theme Definition XML Schema v1](schemas/atomui-theme-v1.xsd)
-- [../../architecture/startup-and-registration.md](../../architecture/startup-and-registration.md)
-- [../../architecture/runtime-platforms.md](../../architecture/runtime-platforms.md)
+- [主题定制指南](../../guides/theming/customization.md)
+- [主题定义 XML v1 规范](../../reference/theming/theme-definition-xml-v1.md)
+- [AtomUI Theme Definition XML Schema v1](../../reference/theming/schemas/atomui-theme-v1.xsd)
+- [启动与注册链路](../../architecture/foundations/startup-and-registration.md)
+- [运行平台策略](../../architecture/foundations/runtime-platforms.md)
diff --git a/docs/modules/desktop-controls/architecture.md b/docs/modules/desktop-controls/architecture.md
index fa1a89165..4fdbb2918 100644
--- a/docs/modules/desktop-controls/architecture.md
+++ b/docs/modules/desktop-controls/architecture.md
@@ -25,7 +25,7 @@
 
 ## Semantic Part 集成
 
-采用 Semantic Part 的桌面控件必须实现 [Semantic Part 系统设计](../core/semantic-part-system.md) 定义的公共契约，
+采用 Semantic Part 的桌面控件必须实现 [Semantic Part 系统设计](../../architecture/systems/theming/semantic-parts.md) 定义的公共契约，
 不为桌面平台建立第二套 Part 命名或样式机制。
 
 - ControlTemplate 中的稳定视觉区域使用 `.semantic-*` class；`PART_*` 继续只服务于控件实现查找。
diff --git a/docs/modules/desktop-controls/browser-compatibility.md b/docs/modules/desktop-controls/browser-compatibility.md
index ec54c53d1..ee49f9cb3 100644
--- a/docs/modules/desktop-controls/browser-compatibility.md
+++ b/docs/modules/desktop-controls/browser-compatibility.md
@@ -27,4 +27,4 @@ RuntimePlatform.Features.SupportsNativeWindow
 ## 相关文档
 
 - [../../gallery/browser-gallery-porting-notes.md](../../gallery/browser-gallery-porting-notes.md)
-- [../../architecture/runtime-platforms.md](../../architecture/runtime-platforms.md)
+- [运行平台策略](../../architecture/foundations/runtime-platforms.md)
diff --git a/docs/modules/desktop-controls/overview.md b/docs/modules/desktop-controls/overview.md
index c98c91670..e2ce9ce7f 100644
--- a/docs/modules/desktop-controls/overview.md
+++ b/docs/modules/desktop-controls/overview.md
@@ -22,7 +22,7 @@
 - [architecture.md](architecture.md)
 - [theme-registration.md](theme-registration.md)
 - [browser-compatibility.md](browser-compatibility.md)
-- [../core/semantic-part-system.md](../core/semantic-part-system.md)
+- [Semantic Part 系统设计](../../architecture/systems/theming/semantic-parts.md)
 - [../../controls/desktop/overview.md](../../controls/desktop/overview.md)
 
 DataGrid、ColorPicker 和 Extras 虽然属于桌面控件体系，但它们是独立包，内部架构分别放在：
diff --git a/docs/modules/desktop-controls/theme-registration.md b/docs/modules/desktop-controls/theme-registration.md
index 40991b97e..424678d7d 100644
--- a/docs/modules/desktop-controls/theme-registration.md
+++ b/docs/modules/desktop-controls/theme-registration.md
@@ -1,7 +1,7 @@
 # Desktop Controls 主题注册
 
 `AtomUI.Desktop.Controls` 的包级注册入口是 `UseDesktopControls()`。Control、Token 和主题资产通过约定与生成代码
-进入该入口，不逐 Control 手工注册。主题系统完整契约见 [AtomUI 主题系统架构](../core/theme-system.md)，Control
+进入该入口，不逐 Control 手工注册。主题系统完整契约见 [AtomUI 主题系统架构](../../architecture/systems/theming/runtime.md)，Control
 开发规则见 [Control Token 设计规范](../../engineering/control-token-guidelines.md)。
 
 ## 注册流程
diff --git a/docs/modules/generator/semantic-part-generator.md b/docs/modules/generator/semantic-part-generator.md
index a88fb3357..31ada2c19 100644
--- a/docs/modules/generator/semantic-part-generator.md
+++ b/docs/modules/generator/semantic-part-generator.md
@@ -2,7 +2,7 @@
 
 Semantic Part Generator 为 AtomUI Control 的公开视觉区域生成静态 descriptor、名称常量、包级注册和构建期诊断。
 公共语义、Selector、Popup、Theme 和兼容性契约由
-[AtomUI Semantic Part 系统设计](../core/semantic-part-system.md) 定义；本文档只定义生成器职责。
+[AtomUI Semantic Part 系统设计](../../architecture/systems/theming/semantic-parts.md) 定义；本文档只定义生成器职责。
 
 ## 1. 设计定位
 
diff --git a/docs/modules/toolkits-gallery-base/overview.md b/docs/modules/toolkits-gallery-base/overview.md
index 3f3d61194..bf0570a0f 100644
--- a/docs/modules/toolkits-gallery-base/overview.md
+++ b/docs/modules/toolkits-gallery-base/overview.md
@@ -64,4 +64,4 @@
 - [theming-localization.md](theming-localization.md)
 - [migration-and-testing.md](migration-and-testing.md)
 - [../../gallery/gallery-showcase-design-pattern.md](../../gallery/gallery-showcase-design-pattern.md)
-- [../../architecture/startup-and-registration.md](../../architecture/startup-and-registration.md)
+- [启动与注册链路](../../architecture/foundations/startup-and-registration.md)
diff --git a/docs/modules/toolkits-gallery-base/theming-localization.md b/docs/modules/toolkits-gallery-base/theming-localization.md
index 82c11543c..dd2b45a4c 100644
--- a/docs/modules/toolkits-gallery-base/theming-localization.md
+++ b/docs/modules/toolkits-gallery-base/theming-localization.md
@@ -84,7 +84,7 @@ AtomUIGallery 当前产品主题目录由 XML definition 唯一描述，显示
 `UseUserThemeDirectory()` 追加用户目录；Browser Gallery 只使用随应用发布的显式 Resolver。Gallery 不提供独立的
 reload command 或菜单，宿主需要刷新用户主题时直接调用 `IThemeManager.ReloadThemesAsync()`。Catalog 的冲突、
 首次用户来源降级、整批原子刷新和删除当前用户主题后的默认回退语义以
-[Core 主题系统设计](../core/theme-system.md)为准。
+[主题系统架构](../../architecture/systems/theming/runtime.md)为准。
 
 ## Shell 主题选择状态
 
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 000000000..ede810de5
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,6 @@
+# Reference
+
+Reference 保存可被工具、第三方包和应用严格依赖的格式、协议与公共契约。Reference 定义合法输入、错误边界、版本
+和兼容性，不承担源码实现说明或使用 walkthrough。
+
+- [主题 Reference](theming/index.md)
diff --git a/docs/modules/core/examples/daybreak-blue.theme.xml b/docs/reference/theming/examples/daybreak-blue.theme.xml
similarity index 100%
rename from docs/modules/core/examples/daybreak-blue.theme.xml
rename to docs/reference/theming/examples/daybreak-blue.theme.xml
diff --git a/docs/reference/theming/index.md b/docs/reference/theming/index.md
new file mode 100644
index 000000000..4cfbb021a
--- /dev/null
+++ b/docs/reference/theming/index.md
@@ -0,0 +1,6 @@
+# 主题 Reference
+
+- [AtomUI 主题定义 XML v1](theme-definition-xml-v1.md)
+- [XML Schema v1](schemas/atomui-theme-v1.xsd)
+- [完整示例](examples/daybreak-blue.theme.xml)
+- [主题系统架构](../../architecture/systems/theming/runtime.md)
diff --git a/docs/modules/core/schemas/atomui-theme-v1.xsd b/docs/reference/theming/schemas/atomui-theme-v1.xsd
similarity index 100%
rename from docs/modules/core/schemas/atomui-theme-v1.xsd
rename to docs/reference/theming/schemas/atomui-theme-v1.xsd
diff --git a/docs/modules/core/theme-definition-xml.md b/docs/reference/theming/theme-definition-xml-v1.md
similarity index 99%
rename from docs/modules/core/theme-definition-xml.md
rename to docs/reference/theming/theme-definition-xml-v1.md
index 000761353..876568828 100644
--- a/docs/modules/core/theme-definition-xml.md
+++ b/docs/reference/theming/theme-definition-xml-v1.md
@@ -128,7 +128,7 @@ AtomUI 的 `Default`、`Dark`、`Compact` descriptor effect 分别为 `Light`、
 `ThemeConfig` 可以整体替换有效全局算法链，但不会修改 definition 元数据；编译器始终从 Light baseline 折叠
 当前有效算法链，最终 `ThemeSnapshot.Appearance` 才是发布 Avalonia Light/Dark variant 的唯一依据。父 Dark +
 子显式 Compact 的结果因此是 Light Compact；Dark Compact 必须显式声明完整算法链。具体根作用域、局部
-`Inherit` 和 FollowSystem 规则见 [主题系统架构](theme-system.md)。
+`Inherit` 和 FollowSystem 规则见 [主题系统架构](../../architecture/systems/theming/runtime.md)。
 
 ## 5. Algorithms 与 Algorithm
 
diff --git a/docs/superpowers/progress/2026-07-16-theme-system.md b/docs/superpowers/progress/2026-07-16-theme-system.md
index f170d549f..0ed55aae3 100644
--- a/docs/superpowers/progress/2026-07-16-theme-system.md
+++ b/docs/superpowers/progress/2026-07-16-theme-system.md
@@ -2,14 +2,14 @@
 
 This file tracks implementation progress for
 [the theme system implementation plan](../plans/2026-07-16-theme-system-implementation.md).
-The normative design remains in `docs/modules/core/theme-system.md` and
-`docs/modules/core/theme-definition-xml.md`.
+The normative design remains in `docs/architecture/systems/theming/runtime.md` and
+`docs/reference/theming/theme-definition-xml-v1.md`.
 
 ## Current State
 
 | Item | Status | Evidence |
 |---|---|---|
-| Formal architecture | Complete | `docs/modules/core/theme-system.md` |
+| Formal architecture | Complete | `docs/architecture/systems/theming/runtime.md` |
 | XML v1 specification and XSD | Complete | XSD validated by `xmllint` and .NET `XmlSchemaSet` |
 | Baseline Core tests | Complete | 141 passed, 0 failed on 2026-07-16 |
 | Task 1: XML syntax and algorithm state | Complete | 15 focused tests; secure XSD reader implemented |
diff --git a/docs/modules/core/theme-algorithm-enum-design.md b/docs/superpowers/specs/2026-08-02-theme-algorithm-enum-design.md
similarity index 100%
rename from docs/modules/core/theme-algorithm-enum-design.md
rename to docs/superpowers/specs/2026-08-02-theme-algorithm-enum-design.md