文件
目標與設計原則
Native Shell 在 iOS、Android、macOS、Windows、Linux 和網頁上提供原生視圖與互動。視覺設計由應用程式自行掌握。同一套元件模型可用於完整應用程式、嵌入式功能和動態派發的 UI。
#原生基礎，應用程式自主設計
NSH 建基於各平台的視圖、文字和輸入基礎設施，並按裝置調整互動方式，包括鍵盤導覽、指標與觸控輸入、文字編輯、捲動和無障礙功能（簡介）。
應用程式定義顏色、字體排印、間距、形狀、狀態回饋和動畫。設定畫面在 iOS 和 Android 上可以跟隨應用程式的品牌風格，而輸入和導覽則依循各裝置的慣例。設計師透過樣式和元件部件來精細調整這套視覺語言。
原生視圖是渲染的基礎。系統樣式的控件只是其中一種特定的視覺與行為選擇。NSH 的常用控件提供共用行為和可自訂的部件，讓應用程式能建立自己的設計系統。
#原生整合的實際做法
原生基礎包括渲染、由影格驅動的動畫、輸入和無障礙語意。在 iOS 和 Android 上，Input 使用平台的文字欄位：編輯、選取選單、輸入法和受支援的自動填寫服務均由平台處理。應用程式透過 autoComplete 描述欄位，例如 current-password 或 postal-code，系統則根據其設定和服務提供可用的建議（表單與鍵盤）。為欄位設定樣式並不影響這項系統整合。
這與完全在自訂渲染器內繪製文字欄位有架構上的分別：自訂渲染器需自行提供與系統編輯和無障礙服務的整合，而 NSH 則在其後端提供平台文字控件時加以採用。各後端的文件會說明其整合方式，包括 NSH 在 Windows 上自家的編輯器和 GPUI 嵌入後端（平台）。
GPUI Kit 將元件行為與視覺設計分離的做法，為 NSH 的分層提供了參考。NSH 在此原則上，進一步建基於平台的視圖和輸入基礎設施。原生整合與應用程式自主設計在整個模型中相輔相成。
#跨平台的單一元件模型
開關在手機、桌面和網頁上的意思都相同。nsh/base 提供狀態、輸入處理、焦點和無障礙功能；應用程式則為 Switch 的軌道、滑塊和各種狀態設定樣式。按鈕、核取方塊和單選按鈕也遵循同一原則。
| 職責 | 所屬位置 | 範例 |
|---|---|---|
| 渲染、版面配置、響應式和環境 | nsh-core、nsh 及執行階段模組 |
視圖、文字、signal、樣式 |
| 共用行為和無障礙結構 | nsh-base，在 TSX 中以 nsh/base 匯入 |
Button、Checkbox、Switch、Tabs |
| 視覺設計和已套用樣式的元件 | 應用程式或社群函式庫 | 品牌化控件、卡片、表單列 |
| 平台專屬功能 | nsh/mobile、nsh/desktop |
行動版導覽列、桌面視窗控制項 |
常用控件在 nsh/base 中有唯一的跨平台歸屬。平台模組按用途和平台語意劃定範圍。TabBar 用於行動版的頂層導覽；Tabs 則在各平台之間切換分頁內容。兩者的角色各不相同。nsh/mobile 只接納具備行動裝置專屬互動語意的功能；常用控件在外觀、尺寸、色調或動畫上的差異，則屬於其共用元件和應用程式樣式的範疇。擁有共同角色的通知或 toast，應先圍繞單一跨平台契約來設計，再在內部調整其呈現方式。
共用元件可以在內部調整互動方式：選單在桌面上以彈出視窗開啟，在手機上則以底部面板開啟，而應用程式只需使用同一套 API 並提供自己的外觀。由系統管理的呈現方式，例如導覽標題列和警示，遵循文件中所述的平台呈現規則。應用程式可以透過嵌入介面公開自己的原生元件和服務。
#無樣式基礎與元件函式庫層
NSH 負責基本元件和無樣式的基礎（nsh-core 和 nsh-base）。應用程式和第三方函式庫則負責已套用樣式的元件函式庫層，即 gpui-component 在 GPUI Kit 中所擔當的角色。這種分工讓每個產品都能掌控自己的視覺語言，同時重用元件實作中最困難的部分。
這項選擇源自 GPUI Kit 的經驗。其已套用樣式的元件，是在開發 Longbridge Pro 的過程中逐步形成的。隨著應用程式需要的設計愈來愈不同，客製化的壓力促使使用者 fork 元件。將共用基礎抽出為 gpui-base 後，各種設計便能重用同一套行為。已套用樣式的元件仍可作為設計參考，並適合需求落在其客製化範圍內的應用程式；而這套基礎則讓其他應用程式能直接掌控呈現方式。
NSH 從一開始就應用了這個教訓。nsh/base 負責複雜行為、互動、響應式狀態、焦點、無障礙功能和自適應呈現，並在負責各項行為的層級進行測試。這包括 Dock 等較大型的結構。應用程式透過樣式、狀態、slot 和部件，在這個基礎上建立多樣的設計。元件貢獻也遵循同一界線：視覺預設值和品牌化變體屬於應用程式或第三方元件。文件中所述由系統管理的呈現方式，以及 TextView 的閱讀預設值，則保留其特定的契約（架構）。
#Gallery 展示的內容
網站示範和 Gallery 是已套用樣式的範例應用程式。其中的漸層、陰影、圓角、過渡效果和動態，用來展現 NSH 的客製化能力，並提供原始碼範例。這些選擇屬於示範和 Gallery 本身；可重用的基礎元件則在其底層提供行為和部件。應用程式可以借用這些範例，也可以建立不同的視覺語言。
獨立發佈的已套用樣式函式庫，會屬於上述的應用程式／社群層。Gallery 的樣式展示的是其中一個設計方向；是否適合某個產品，則由該產品自行作設計決定。
#以同一引擎運行 Rust 和 TSX
Rust 應用程式、TSX 畫面和混合專案共用基本元件、基礎元件、signal 和版面配置。Rust 提供已編譯的應用程式邏輯和可重用的原生元件。TSX 則支援快速迭代和在執行時派發的模組（使用 Rust 建構）。
引擎會更新依賴已變更 signal 的綁定，並將視圖操作批次處理。文字版面配置、原生動畫和輸入由引擎及其平台後端負責（架構）。效能以可重現的應用程式工作負載來評估（效能）。
#嵌入、動態派發與 AI
現有的原生應用程式可以在功能所需的位置放置 NSH 視圖，並公開自己的原生元件和主機服務。獨立應用程式則使用相同的執行階段和元件模型（平台）。
動態派發的 TSX 模組自行管理狀態、邏輯和版面配置。已簽署的套件用來確立主機信任哪些發佈者；沙盒限制和權限則界定模組可以做什麼。信任與權限均由主機決定（簽署套件、沙盒與權限）。
AI 生成的 UI 同樣遵循這份契約：根據已宣告的 API 生成 TSX，進行檢查和測試，建構並簽署模組，然後在主機政策下驗證並執行。生成的宣告檔、模型可讀的文件和 CLI 測試，讓整個工作流程可供檢視且可重複（測試與追蹤）。
#這些目標如何指引新功能的加入
- 確立使用者行為，以及該行為是否跨平台共用。
- 將共用行為放入現有的基本元件或基礎元件，並公開狀態和部件供應用程式客製化。
- 將具備平台專屬語意的功能放入其平台模組，並記錄其適用範圍以及如何與共用 UI 組合。
- 在應用程式或社群函式庫中建立已套用樣式的元件。
- 在受影響的平台上驗證行為、無障礙功能、版面配置和輸入，並以兩種語言記錄公開契約。
隨著 NSH 不斷發展，這些原則可以讓視覺設計保持靈活、共用元件的 API 保持一致，並讓平台整合保持明確。