文档
目标与设计原则
Native Shell 为 iOS、Android、macOS、Windows、Linux 和 Web 提供原生视图与交互，视觉设计由应用掌握。一套组件模型同时服务于完整应用、嵌入式功能和动态下发的界面。
#原生基础，应用设计
NSH 使用各平台的视图、文本与输入基础设施，并根据设备适配交互：键盘导航、鼠标与触摸输入、文本编辑、滚动和无障碍（简介）。
应用定义颜色、字体、间距、形状、状态反馈和动画。设置页面可以在 iOS 和 Android 上保持应用的品牌设计，同时让输入和导航遵循设备的习惯。设计师通过样式与组件部件持续调整这套视觉语言。
原生视图是渲染的基础。系统外观控件是一种具体的视觉与行为选择。NSH 的通用控件提供共享行为与可定制的部件，供应用构建自己的设计系统。
#原生集成的具体含义
原生基础包括渲染、由帧时钟驱动的动画、输入和无障碍语义。在 iOS 和 Android 上，Input 使用平台文本输入控件：编辑、文本选择菜单、输入法，以及平台支持的自动填充服务由系统处理。应用通过 autoComplete 描述字段，例如密码的 current-password、邮政编码的 postal-code，系统根据设置和服务提供可用的填充建议（表单与键盘）。应用可以定制输入框样式，同时保留这种系统集成。
这与在自绘渲染器里完整绘制输入框有架构上的区别：自绘渲染器需要自行对接系统编辑和无障碍服务，NSH 则在后端提供平台文本控件的地方直接使用它们。各后端文档定义具体的集成范围，包括 Windows 与 GPUI 嵌入后端中由 NSH 实现的编辑器（平台）。
GPUI Kit 将组件行为与视觉设计分离的思路影响了 NSH 的分层。NSH 在此基础上使用平台视图和输入基础设施，将原生集成与应用自主设计结合起来。
#一套跨平台组件模型
开关在手机、桌面和 Web 上表达相同的含义。nsh/base 提供状态、输入处理、焦点与无障碍；应用为 Switch 的轨道、滑块和各个状态设置样式。按钮、复选框和单选框遵循同样的原则。
| 职责 | 归属 | 示例 |
|---|---|---|
| 渲染、布局、响应式与环境 | nsh-core、nsh 及运行时模块 | 视图、文本、signal、样式 |
| 共享行为与无障碍结构 | nsh-base，TSX 中导入 nsh/base | Button、Checkbox、Switch、Tabs |
| 视觉设计与带样式的组件 | 应用或社区组件库 | 品牌控件、卡片、表单行 |
| 平台专属能力 | nsh/mobile、nsh/desktop、nsh/ios、nsh/android | 移动导航栏、桌面窗口控制 |
通用控件在 nsh/base 中有统一的跨平台归属。平台模块按用途与平台语义划定范围。TabBar 服务于移动应用的顶层导航；Tabs 在各平台切换标签内容。两者的职责不同。nsh/mobile 接受具有移动平台专属交互语义的能力；通用控件在外观、尺寸、颜色或动画上的差别，应在共享组件与应用样式中处理。通知或 Toast 这类用途可以共享的能力，应优先设计统一的跨平台契约，并在内部适配呈现方式。
共享组件可以在内部适配交互：菜单在桌面上以弹出菜单打开，在手机上以底部面板打开，应用使用同一套 API 并提供外观。导航标题栏、系统提示框等由系统管理的呈现遵循文档约定的平台规则。应用可以通过嵌入接口开放自己的原生组件与服务。
#无样式基础与组件库层
NSH 提供基础元素与无样式的基础能力（nsh-core 和 nsh-base）。带样式的组件库层由应用和第三方库提供，对应 GPUI Kit 中 gpui-component 的职责。这样，每个产品都能掌握自己的视觉语言，同时复用组件实现中复杂的基础工作。
这个选择来自 GPUI Kit 的实践。它的带样式组件从长桥 Longbridge Pro 的项目经验中逐步发展而来。随着应用需要越来越多不同的设计，定制压力使用户开始 fork 组件。将共享基础能力提取到 gpui-base，让这些行为可以被不同设计复用。带样式组件可以作为设计参考，也适合其定制接口能够满足需求的应用；基础层则让其他应用直接掌握呈现方式。
NSH 从一开始就采用这个分工。nsh/base 承担复杂行为、交互、响应式状态、焦点、无障碍与适应设备的呈现方式，并在行为所属的层次进行测试，包括 Dock 这样的大型结构。应用通过样式、状态、插槽和部件，在此基础上构建多样化设计。组件贡献遵循同样的边界：视觉默认值和品牌样式变体属于应用或第三方组件。已有文档约定的系统呈现与 TextView 阅读默认值继续遵循各自的具体契约（架构）。
#Gallery 展示的是什么
官网演示与 Gallery 是带有样式的示例应用。渐变、阴影、圆角、过渡和各种动效用于验证 NSH 的定制能力，并提供可参考的源码。这些选择属于演示和 Gallery 本身；可复用的基础组件提供其下的行为与部件。应用可以借鉴示例，也可以建立完全不同的视觉语言。
独立发布的带样式组件库属于上述应用与社区层。Gallery 的样式展示了一种设计方向，是否适合某个产品，由这个产品自行判断。
#Rust 与 TSX 共用一个引擎
Rust 应用、TSX 界面和混合项目共享基础元素、基础组件、signal 和布局。Rust 提供编译执行的应用逻辑和可复用的原生组件；TSX 支持快速迭代与运行时下发模块（用 Rust 开发）。
引擎更新依赖已变化 signal 的绑定，并批量提交视图操作。文本布局、原生动画与输入由引擎及其平台后端提供（架构）。性能通过可复现的应用工作负载测量来评估（性能）。
#嵌入、动态交付与 AI
已有原生应用在需要某项功能的位置放入 NSH 视图，并开放自己的原生组件与宿主服务。独立应用使用同样的运行时和组件模型（平台）。
动态下发的 TSX 模块拥有自己的状态、逻辑与布局。签名包确定宿主信任的发布者，沙箱限制与能力配置确定模块可以做什么。信任和权限都由宿主决定（签名包、沙箱与能力）。
AI 生成的界面遵循同样的契约：根据已声明的 API 生成 TSX，检查并测试，构建与签名模块，再按宿主策略验证和运行。自动生成的类型声明、供模型读取的文档和 CLI 测试，让这个流程可检查、可重复（测试与追踪）。
#如何据此扩展 NSH
- 明确用户行为，以及这个行为是否跨平台共享。
- 将共享行为放入现有基础元素或基础组件，暴露应用定制所需的状态与部件。
- 将具有平台专属语义的能力放入对应的平台模块，说明适用范围以及如何与共享 UI 组合。
- 在应用或社区组件库中构建带样式的组件。
- 在受影响的平台验证行为、无障碍、布局和输入，并同步编写中英文公共契约文档。
这些原则让 NSH 在扩展时保持视觉设计的灵活性、共享组件 API 的一致性，以及清晰的平台集成边界。