AtomUI/docs/engineering/contributing/mobile-documentation-guidelines.md

AtomUI Mobile 文档规范

本文档定义 AtomUI Mobile 架构、模块、Control、平台工程、Gallery 和 LLMS 文档的责任边界、证据状态和同步要求。 通用目录与命名规则见 文档结构与命名规范，单 Control 文件契约见 AtomUI Control 文档规范。本文只补充 Mobile 专项规则。

定位

AtomUI Mobile 文档同时承担两种责任：在源码实现前保存已经批准的目标契约，在源码实现后准确反映可用能力和验证证据。 这两种责任不能混写。目标设计可以约束 Foundation 和控件波次，但不能被表述为已存在的项目、API、平台支持或发布结果。

Mobile 文档遵守以下不变量：

• AtomUI.Mobile.Controls 与 AtomUI.Desktop.Controls 平行，Mobile 不依赖 Desktop。
• iOS 是首个实现平台，公共架构从 Foundation 开始同时考虑 iOS 和 Android。
• Mobile 复用 AtomUI Global Token、Theme Algorithm、ThemeConfigProvider 和 Localization 运行时。
• Safe Area、键盘遮挡、方向、打开状态、选择状态和 gesture progress 是运行时状态，不是 Token。
• 当前 AtomUI.Toolkits.GalleryBase 直接依赖 Desktop Controls，不作为 Mobile Gallery Foundation 的依赖。
• Desktop 与 Mobile Control 文档、Gallery 证据和 LLMS 输出分别拥有独立路径。

文档路由

内容	正式 owner	不应放入
Mobile Runtime、Viewport、Overlay、Gesture 和跨平台能力契约	docs/architecture/systems/mobile/	单 Control 文档、平台环境指南
AtomUI.Mobile.Controls 包、注册、源码 ownership、adapter 和打包	docs/modules/mobile-controls/	Runtime 总体架构、单 Control API
Mobile 平台导航、分类兼容清单和具体 Control 契约	docs/controls/mobile/	签名流程、包注册、跨控件状态机
iOS/Android 工具链、签名、构建、模拟器和真机	docs/engineering/platforms/	Control API、Token 和 Gallery 内容模型
Mobile Gallery 内容主体及 iOS/Android Host 责任	docs/gallery/platforms/mobile-gallery.md	完整平台工具链和 Control 契约
LLMS 配置、输入输出和隔离规则	docs/engineering/tooling/llms-generator-design.md	手工生成产物和 Control 专属知识
方案、实施计划和日期化验证证据	docs/superpowers/	正式架构和当前能力的唯一来源

稳定事实只由一个正式 owner 维护。其他入口保留摘要和链接，不复制完整状态机、平台矩阵、Token 规则或验证清单。

预实现架构规则

当 AtomUI.Mobile.Controls 尚未存在时，Mobile Architecture、Module、Controls 和 Gallery 正式入口使用以下 notice：

状态：预实现架构。本文定义已批准的目标契约，不表示当前仓库已经包含或发布 AtomUI.Mobile.Controls。

notice 只在文档入口出现一次。正文直接描述目标契约，但必须遵守：

• 不把目标项目列入当前解决方案项目表。
• 不展示虚构的 .csproj、源码文件清单、生成 API、测试项目或 Gallery route。
• 不使用“已经支持”“可直接使用”“已验证”“即将发布”等没有证据的措辞。
• Approved target API 名称必须明确属于目标契约；源码落地后再按真实声明校准。
• 一个入口只有在其描述的源码和验证证据实际存在后才能移除 notice，不能全局批量移除。

证据与状态模型

移动能力的状态按维度独立维护：

维度	初始状态	允许提升状态的证据
Design	能力已纳入总体设计	已批准的系统或控件族设计
Source	未实现	Public API、Theme、注册入口和实际项目源码
iOS	未验证	可追溯的 Simulator 或真机场景、日期和结果
Android	未验证	可追溯的 Emulator 或真机场景、日期和结果
Release	未验证	对应平台 Release/AOT/trim 产物构建并成功启动
Publication	未发布	可追溯的 NuGet 或应用版本与发布日期

状态不能互相替代：Headless 测试不等于平台验证，Simulator 不等于真机结论，compile 不等于 Release/AOT，iOS 证据 不等于 Android 证据。状态提升必须附证据链接；证据失效或契约变化时必须回退状态并说明重新验证条件。

正式平台文档保存稳定规则。精确 Xcode、SDK、设备、系统版本、机器路径、性能数据和视觉校准值进入日期化的 docs/superpowers/progress/YYYY-MM-DD-<platform>-<scenario>-validation.md。

Mobile Control 分类与兼容清单

Mobile Control 使用七个分类：

分类	职责
general	高频基础操作和通用视觉原子
layout	空间、对齐、分区和安全区域
navigation	页面、分区、步骤和当前位置切换
data-entry	获取、编辑、选择、验证和提交数据
data-display	展示结构化内容、媒体、状态数据和集合
feedback	结果、进度、加载、确认和临时覆盖反馈
other	横跨多种分类且以移动交互基础能力为主的能力

Mobile 不创建 window 分类。系统栏、Safe Area、系统返回和生命周期属于 Mobile Runtime/Platform，不是 Desktop Window Control 家族。

每项上游能力恰好由一个分类 overview.md 维护。兼容清单使用固定字段：

Capability | AtomUI mapping | API strategy | Wave | Design | Source | iOS | Android | Release | Publication | Evidence

API strategy 只允许：

• Tier 1 候选：现有跨产品抽象可能完整承接公共状态和语义，仍需控件族设计确认。
• Tier 2 候选：共享 model/coordinator，Mobile Control 和 Theme 独立。
• Tier 3：移动语义占主导，设计独立 Mobile API。
• 波次设计未冻结：总体能力已经纳入，但 API 复用层级必须由对应控件族设计决定。

分类页拥有逐项状态；平台入口只聚合分类数量和导航。单 Control 文档描述当前契约，不复制兼容清单的阶段状态。 上游 ConfigProvider 映射到现有 AtomUI Theme、Localization、启动 options、Control 属性、DataTemplate 和 ControlTheme，不作为第 83 个 Control 进入分类。

单 Control 文档创建门禁

不得预先批量创建空的 Mobile Control 目录。只有以下证据在同一变更中均可审查时，才创建 docs/controls/mobile/<category>/<control>/：

1. Control 或紧密 Control 家族已经存在可审查的 Public API 源码。
2. 已存在默认 ControlTheme，或有明确的无 Theme 设计证据。
3. 已存在 Contract/Headless 测试入口。
4. Mobile Gallery 已有结构化 API、Token 和稳定 ShowCase 的承载位置。
5. iOS 与 Android 的适用验证状态可以准确填写；未完成的平台明确为 未验证。

门禁满足后继续遵守标准文件契约：

overview.md
implementation.md
token.md          # 有专属 Token 时创建
changelog.md
<topic>-design.md # 仅在稳定专项设计需要独立维护时创建

上游文档、截图、Demo 或总体设计不能替代 Public API、Theme、测试和 Gallery 证据。源码、主题、测试和文档冲突时，先 确定目标契约，再同步修正；不能选择最方便的一份作为事实。

平台文档规则

iOS 与 Android 使用平行的责任模型，但验证状态允许不同：

• iOS/Android 公共语义、Control API、Localization 文案和 Theme 契约保持一致。
• 平台差异通过 capability adapter 和 platform profile 表达，不散落在 Control 文档中。
• 工具链文档只记录稳定约束；版本组合必须有官方约束或真实执行证据。
• 未执行的命令不能标记为标准命令，未启动的产物不能标记为 Release 验证通过。
• Simulator/Emulator、真机、屏幕阅读器、IME、旋转、前后台和 Host 重建分别记录证据。
• iOS-first 不允许删除 Android 列、Android adapter 边界或 Android 验证要求。

Gallery 与 LLMS 隔离

Mobile Gallery 文档必须反映真实依赖：

• Mobile Gallery content 拥有 ShowCase、API table、Token table 和兼容状态。
• iOS Host 与 Android Host 只拥有平台启动、生命周期、签名/部署和 adapter 注册。
• 当前 Desktop-bound AtomUI.Toolkits.GalleryBase 不能作为 Mobile Foundation 依赖。
• 共享 Gallery contracts 只有在出现真实、稳定、无 Desktop 语义的重复后才能另行设计。

Desktop 与 Mobile LLMS 使用独立配置和输出 owner。当前 Desktop 继续使用：

docs/AI/generated/llms.config.json
docs/AI/generated/llms/

Mobile Foundation 的目标路径是：

docs/AI/generated/mobile-llms.config.json
docs/AI/generated/mobile-llms/

在 Mobile 配置和 Generator 支持实际落地前，不创建上述文件或目录。任何生成内容都从正式 Control 文档、源码、Theme、 Token 和 Gallery 结构化输入生成，禁止手工编辑。

同步矩阵

变更	必须同步
Mobile Runtime contract	Mobile Architecture、Module 摘要、受影响 Control 摘要、验证文档
包依赖、注册或 adapter	Module、dependency graph、runtime platforms、Native 边界、AOT/打包说明
Public API 或行为	Control overview/implementation/changelog、Gallery API/ShowCase、Contract tests、兼容状态
Theme、Token 或 Semantic Part	Control overview/token/implementation、Theme tests、Gallery Token 表、LLMS source
iOS/Android 证据	分类兼容清单、平台文档或日期化证据、Release 状态
Gallery Host 结构	Mobile Gallery 文档、平台入口、受影响 ShowCase ownership
LLMS 接入	Generator 设计、独立配置、输出验证、Control 文档输入覆盖

Foundation 和每个控件波次结束时，逐项检查 Architecture、Module、Controls、Engineering Platforms、Gallery 和 LLMS 影响。没有影响的领域应明确为无变更，不能默认遗漏。

验证清单

• Mobile 当前状态和目标架构是否明确分开。
• 每个稳定事实是否只有一个正式 owner。
• 是否没有创建无源码/Theme/测试/Gallery 证据的单 Control 目录。
• 七个分类是否完整覆盖能力清单且没有重复。
• iOS、Android、Release 和 Publication 是否分别表达。
• Theme 文档是否复用现有全局系统，运行时状态是否保持在 Token 之外。
• Gallery 文档是否反映当前 Desktop-bound GalleryBase 依赖。
• Desktop/Mobile LLMS 路径是否隔离，生成产物是否未被手工修改。
• 所有人工维护目录是否使用 overview.md。
• 相对链接、旧路径扫描、LLMS verify 和 git diff --check 是否通过。