Theme SDK 개요
Theme SDK는 NeoTavern의 전체 시각적 셸을 교체하기 위한 버전이 있는 계약입니다. 단순한 색상 변경이 아닙니다.
Theme SDK란?
테마는 애플리케이션의 모양과 주요 영역의 구성 방식을 제어하는
패키지(.sttheme)입니다. 플러그인과 달리 테마에는 JavaScript가
없습니다. CSS, 의미적 토큰, 매니페스트의 선언적 셸 레이아웃입니다.
SDK가 선언적이므로 테마는 애플리케이션의 동작을 깨거나 데이터에
도달할 수 없습니다.
@neotavern/theme-sdk 패키지는 계약 자체를 제공합니다. 표준 토큰 이름,
매니페스트 검증, 상속 해석, CSS 변수 생성입니다. 호스트의 참조
구현은 문서 루트에 --st-* 사용자 지정 속성을 쓰고 정의된 순서로
테마 스타일시트를 로드해 테마를 적용합니다.
세 가지 레벨
테마는 세 가지 레벨로 구성되며, 테마는 그중 어떤 것이든 사용할 수 있습니다.
- 디자인 토큰 — 색상, 글꼴, 간격, 모서리 반경, 그림자, z-index 레이어, 모션, 컨트롤 크기의 의미적 변수. 컴포넌트는 이 토큰만 참조하므로 토큰 하나를 오버라이드하면 인터페이스 전체가 일관되게 다시 스타일링됩니다.
- 컴포넌트 스킨 — 안정적인
data-component,data-part,data-role,data-state훅으로 컴포넌트를 다시 스타일링하는 CSS. - 셸 레이아웃 — 주요 영역의 선언적 구성: 내비게이션 레일, 관리 패널, 채팅 워크스페이스.
채팅 로직, 데이터 모델, 동작은 건드리지 않으므로 테마는 어떤 기능도 깨지 않고 운영 체제, 게임 콘솔, 비주얼 노벨 인터페이스, 모바일 앱 레이아웃을 흉내낼 수 있습니다. 자세한 내용은 레벨을 참조하세요.
빌드 단계 없는 작성
테마는 theme.json, components.css, shell.css가 있는 ZIP입니다.
손으로 만들 수 있습니다.
- 테마 관리자를 열고 테마 스타터 키트를 내려받습니다.
- 압축을 풀고
theme.json,components.css,shell.css를 편집합니다. - 파일을 아카이브 루트에 다시 압축하고 패키지를 설치합니다.
- 라이트/다크 모드, 모바일, 키보드 포커스, RTL, 세이프 모드를 확인한 뒤 테마를 적용합니다.
첫 테마에 Node.js, npm, JavaScript, Theme SDK CLI가 필요하지 않습니다.
설치와 활성화
패키지를 설치한다고 활성화되지는 않습니다. 활성화는 extends 체인
전체를 누락된 부모와 순환에 대해 검증한 다음, 활성 테마와 저장된
테마 선택을 하나의 트랜잭션으로 업데이트합니다. 같은 id의 패키지를
업데이트하면 디렉터리가 원자적으로 교체되고 현재 활성화 상태가
유지됩니다. 레지스트리 오류 시 이전 디렉터리가 복원됩니다.
배포판에는 AMOLED, GitHub Dark, Matrix, Nord, Gruvbox, Dracula, Tokyo Night, Catppuccin Mocha, Solarized Dark, One Dark 같은 기본 제공 테마 세트가 포함되어 있어 테마 관리자가 빈 채로 열리지 않습니다.
안전성
테마는 채팅, API 키, 파일 시스템을 읽을 수 없고 실행 가능한 코드도 없습니다. 모든 스타일시트는 금지된 구문에 대해 검사되며, 세이프 모드는 타사 테마를 완전히 비활성화합니다. 보장 사항은 세이프 모드, 전체 API는 생성된 Theme SDK 레퍼런스를 참조하세요.