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