문서
목표와 설계 원칙
Native Shell은 iOS, Android, macOS, Windows, Linux, 웹에서 플랫폼 고유의 뷰와 상호작용을 제공합니다. 화면의 시각 디자인은 앱이 결정합니다. 하나의 컴포넌트 모델로 독립 실행형 앱, 기존 앱에 임베딩하는 기능, 실행 중에 배포하는 UI를 모두 구현합니다.
#플랫폼의 기반과 앱의 디자인
NSH는 각 플랫폼의 뷰, 텍스트, 입력 체계를 사용합니다. 키보드 탐색, 포인터와 터치 입력, 텍스트 편집, 스크롤, 접근성 동작은 기기에 맞게 조정합니다(소개).
색상, 타이포그래피, 간격, 모양, 상태 변화의 시각적 표현, 애니메이션은 앱이 정의합니다. 예를 들어 설정 화면은 iOS와 Android에서 같은 브랜드 디자인을 쓰면서도 입력과 탐색 방식은 각 기기의 관례를 따를 수 있습니다. 디자이너는 스타일과 컴포넌트의 각 부분을 조정해 제품의 디자인을 다듬습니다.
네이티브 뷰는 화면을 그리는 기반입니다. 시스템 스타일의 컨트롤은 그 위에서 선택할 수 있는 외형과 동작 중 하나입니다. NSH의 공통 컨트롤은 여러 플랫폼에서 공유하는 동작과 개별적으로 꾸밀 수 있는 부분을 제공하므로, 앱이 자체 디자인 시스템을 만들 수 있습니다.
#네이티브 기능의 실제 연동
네이티브 기반에는 렌더링, 화면 주사 주기에 맞춘 애니메이션, 입력, 접근성 정보가 포함됩니다. iOS와 Android의 Input은 플랫폼의 텍스트 필드를 사용합니다. 텍스트 편집, 선택 메뉴, 입력기, 지원되는 자동 완성 서비스는 플랫폼이 맡습니다. 앱이 autoComplete를 current-password나 postal-code 등으로 지정하면 시스템은 기기의 설정과 서비스에 맞는 항목을 제안합니다(폼과 키보드). 필드의 스타일을 앱에 맞게 바꿔도 시스템과의 연동은 유지됩니다.
텍스트 필드 전체를 직접 그리는 렌더러는 시스템 편집 및 접근성 서비스와의 연동도 구현해야 합니다. NSH는 해당 백엔드에서 플랫폼 텍스트 컨트롤을 제공하는 경우 이를 사용합니다. Windows의 NSH 자체 편집기나 GPUI 임베딩 백엔드처럼 구체적인 연동 방식은 플랫폼별 문서에서 확인할 수 있습니다.
NSH의 계층 구조는 컴포넌트 동작을 시각 디자인과 분리한 GPUI Kit의 설계를 따릅니다. 여기에 플랫폼 고유의 뷰와 입력 체계를 결합해, 시스템 기능을 그대로 사용하면서 앱이 디자인을 직접 결정할 수 있게 했습니다.
#여러 플랫폼에서 공유하는 컴포넌트 모델
휴대폰과 데스크톱, 웹에서 스위치의 역할은 같습니다. nsh/base가 상태, 입력, 포커스, 접근성을 처리하고 앱은 Switch의 트랙, 손잡이, 상태별 모양을 꾸밉니다. 버튼, 체크박스, 라디오 버튼도 같은 원리를 따릅니다.
| 역할 | 담당 계층 | 예 |
|---|---|---|
| 렌더링, 레이아웃, 반응성, 실행 환경 | nsh-core, nsh, 런타임 모듈 | 뷰, 텍스트, 시그널, 스타일 |
| 공통 동작과 접근성 구조 | nsh-base(TSX에서는 nsh/base로 가져옴) | Button, Checkbox, Switch, Tabs |
| 시각 디자인과 스타일이 적용된 컴포넌트 | 앱이나 커뮤니티 라이브러리 | 브랜드에 맞춘 컨트롤, 카드, 폼의 행 |
| 플랫폼 고유 기능 | nsh/mobile, nsh/desktop | 모바일 탐색 막대, 데스크톱 창 컨트롤 |
여러 플랫폼이 공유하는 컨트롤은 nsh/base에서 제공합니다. 플랫폼 모듈의 범위는 기능의 목적과 플랫폼에서의 역할에 따라 정합니다. 예를 들어 TabBar는 모바일 앱의 최상위 탐색에 쓰이고, Tabs는 어느 플랫폼에서나 탭으로 콘텐츠를 전환합니다. nsh/mobile에는 모바일에 고유한 상호작용을 담습니다. 공통 컨트롤의 외형, 크기, 색조, 애니메이션 차이는 공유 컴포넌트와 앱 스타일에서 처리합니다. 알림이나 토스트처럼 역할이 같다면 먼저 하나의 크로스 플랫폼 API를 설계하고 표시 방식은 내부에서 조정합니다.
공유 컴포넌트 안에서도 기기에 맞게 상호작용을 바꿀 수 있습니다. 메뉴는 데스크톱에서는 팝업으로, 휴대폰에서는 시트로 열리지만 앱은 하나의 API로 메뉴를 정의하고 모양을 지정합니다. 탐색 헤더나 경고창처럼 시스템이 관리하는 UI는 문서에 명시된 플랫폼별 표시 규칙을 따릅니다. 앱은 임베딩 인터페이스를 통해 자체 네이티브 컴포넌트와 서비스도 제공할 수 있습니다.
#기본 컴포넌트와 스타일 라이브러리의 역할
NSH는 기본 요소와 시각 스타일을 정하지 않은 공통 기반(nsh-core, nsh-base)을 맡습니다. GPUI Kit에서 gpui-component가 맡는 스타일 컴포넌트 라이브러리 계층은 NSH에서는 앱이나 서드파티 라이브러리가 담당합니다. 각 제품은 구현하기 까다로운 컴포넌트 동작을 재사용하면서 자체 디자인을 적용할 수 있습니다.
이 결정에는 GPUI Kit 개발 경험이 반영되어 있습니다. GPUI Kit의 스타일 컴포넌트는 Longbridge Pro를 개발하면서 만들어졌습니다. 앱마다 원하는 디자인의 차이가 커지자 기존 컴포넌트를 포크해 수정하는 사용자가 늘었습니다. 이에 공통 기반을 gpui-base로 분리해 서로 다른 디자인에서도 같은 동작을 재사용할 수 있게 했습니다. 스타일 컴포넌트는 디자인 참고 자료로 쓰거나 제공되는 조정 범위가 제품에 잘 맞을 때 그대로 사용할 수 있습니다. 외형을 직접 설계하려는 앱은 기반 계층을 사용할 수 있습니다.
NSH는 처음부터 이 구조를 채택했습니다. nsh/base는 복잡한 동작과 상호작용, 반응형 상태, 포커스, 접근성, 기기에 맞는 표시 방식을 맡습니다. 테스트는 각 동작을 구현한 계층에 둡니다. Dock 같은 큰 구조도 이 범위에 포함됩니다. 앱은 이 기반 위에서 스타일, 상태, 슬롯, 구성 요소별 부분(parts)을 활용해 다양한 화면을 만듭니다. 컴포넌트를 기여할 때도 시각적 기본값과 브랜드별 변형은 앱이나 서드파티 컴포넌트에 둡니다. 시스템이 관리하는 UI와 TextView의 읽기용 기본 스타일은 각각 문서에 명시된 규칙을 따릅니다(아키텍처).
#갤러리에서 볼 수 있는 것
웹사이트의 데모와 갤러리는 스타일을 적용한 예제 앱입니다. 그라디언트, 그림자, 둥근 모서리, 전환, 모션을 어떻게 구현했는지 화면과 소스 코드에서 함께 확인할 수 있습니다. 이 시각적 선택은 데모와 갤러리의 디자인이며, 재사용할 수 있는 기본 컴포넌트는 그 밑의 동작과 구성 요소를 제공합니다. 앱은 예제 디자인을 활용하거나 자체 디자인을 만들 수 있습니다.
독립적으로 배포되는 스타일 라이브러리 역시 앞에서 설명한 앱·커뮤니티 계층에 속합니다. 갤러리는 하나의 디자인 방향을 보여주며, 이를 채택할지는 각 제품이 결정합니다.
#하나의 엔진에서 실행하는 Rust와 TSX
Rust 앱, TSX 화면, 두 언어를 함께 쓰는 프로젝트는 기본 요소, 기본 컴포넌트, 시그널, 레이아웃을 공유합니다. Rust로는 컴파일되는 앱 로직과 재사용 가능한 네이티브 컴포넌트를 작성합니다. TSX는 빠른 수정과 반복 개발, 실행 중에 배포하는 모듈에 적합합니다(Rust로 앱 개발).
엔진은 바뀐 시그널에 의존하는 바인딩을 갱신하고 뷰 연산을 모아서 처리합니다. 텍스트 레이아웃, 네이티브 애니메이션, 입력은 엔진과 각 플랫폼 백엔드가 담당합니다(아키텍처). 성능은 재현 가능한 앱 워크로드로 측정합니다(성능).
#임베딩, 동적 배포, AI
기존 네이티브 앱은 기능을 배치할 위치에 NSH 뷰를 넣고 자체 네이티브 컴포넌트와 호스트 서비스를 노출합니다. 독립 실행형 앱도 같은 런타임과 컴포넌트 모델을 사용합니다(플랫폼).
동적으로 배포하는 TSX 모듈은 자체 상태, 로직, 레이아웃을 가집니다. 서명 패키지로 호스트가 신뢰하는 배포자를 확인하고, 샌드박스의 제한과 권한으로 모듈이 할 수 있는 일을 정합니다. 누구를 신뢰하고 어떤 권한을 허용할지는 호스트가 결정합니다(서명 패키지, 샌드박스와 권한).
AI가 생성한 UI도 같은 규칙을 따릅니다. 선언된 API에 맞춰 TSX를 생성하고, 검사와 테스트를 거쳐 모듈을 빌드하고 서명한 뒤, 호스트 정책에 따라 검증하고 실행합니다. 자동 생성된 타입 선언과 모델이 읽을 수 있는 문서, CLI 테스트로 각 단계를 확인하고 반복할 수 있습니다(테스트와 실행 추적).
#새 기능을 설계할 때의 기준
- 사용자가 수행할 동작을 정의하고, 여러 플랫폼에서 그 동작을 공유하는지 확인합니다.
- 공통 동작은 기존 기본 요소나 기본 컴포넌트에 넣고, 앱이 디자인을 조정할 수 있도록 상태와 구성 요소를 노출합니다.
- 플랫폼 고유의 동작은 해당 플랫폼 모듈에 두고, 적용 범위와 공통 UI에 결합하는 방법을 문서화합니다.
- 스타일이 적용된 컴포넌트는 앱이나 커뮤니티 라이브러리에서 구현합니다.
- 영향을 받는 플랫폼에서 동작, 접근성, 레이아웃, 입력을 검증하고 공개 API 규약을 영어와 중국어 문서에 기록합니다.
이 원칙에 따라 NSH가 성장해도 앱은 자유롭게 디자인을 정할 수 있고, 공유 컴포넌트의 API는 일관성을 유지하며, 플랫폼과 연동되는 방식도 명확하게 드러납니다.