Перейти к основному содержимому

Обзор Theme SDK

Theme SDK — это версионируемый контракт для замены всей визуальной оболочки NeoTavern, а не только её перекраски.

Что такое Theme SDK​

Тема — это пакет (.sttheme), управляющий тем, как выглядит приложение и как скомпонованы его основные области. В отличие от плагина, у темы нет JavaScript: это CSS, семантические токены и декларативный макет оболочки в манифесте. Поскольку SDK декларативен, тема не может сломать поведение приложения или добраться до его данных.

Пакет @neotavern/theme-sdk предоставляет сам контракт: канонические имена токенов, проверку манифеста, разрешение наследования и генерацию CSS-переменных. Эталонная реализация хоста применяет тему, записывая кастомные свойства --st-* на корень документа и загружая таблицы стилей темы в определённом порядке.

Три уровня​

Темизация структурирована на трёх уровнях, и тема может использовать любой из них:

  1. Дизайн-токены — семантические переменные для цветов, шрифтов, отступов, радиусов, теней, слоёв z-index, анимаций и размеров элементов управления. Компоненты ссылаются исключительно на эти токены, поэтому переопределение токена согласованно перестилизует весь интерфейс.
  2. Скин компонентов — CSS, перестилизующий компоненты через стабильные хуки data-component, data-part, data-role и data-state.
  3. Макет оболочки — декларативная композиция основных областей: навигационная панель, панели управления и рабочее пространство чата.

Поскольку логика чата, модель данных и поведение не затрагиваются, тема может имитировать операционную систему, игровую консоль, интерфейс визуальной новеллы или макет мобильного приложения, не ломая ни одной функции. Подробности см. в Уровни.

Создание без шага сборки​

Тема — это ZIP с theme.json, components.css и shell.css. Вы можете собрать её вручную:

  1. Откройте менеджер тем и скачайте стартовый набор темы.
  2. Распакуйте его и отредактируйте theme.json, components.css и shell.css.
  3. Заархивируйте файлы заново в корне архива и установите пакет.
  4. Проверьте светлый и тёмный режимы, мобильный вид, фокус клавиатуры, RTL и безопасный режим, затем примените тему.

Для первой темы не нужны Node.js, npm, JavaScript или CLI Theme SDK.

Установка и активация​

Установка пакета не активирует его. Активация проверяет всю цепочку extends на отсутствие родителей и циклов, затем одной транзакцией обновляет активную тему и сохранённый выбор темы. Обновление пакета с тем же идентификатором атомарно заменяет его каталог и сохраняет текущее состояние активации; при ошибке реестра восстанавливается предыдущий каталог.

Дистрибутив поставляет набор встроенных тем, таких как AMOLED, GitHub Dark, Matrix, Nord, Gruvbox, Dracula, Tokyo Night, Catppuccin Mocha, Solarized Dark и One Dark, поэтому менеджер тем никогда не открывается пустым.

Безопасность​

Темы не могут читать чаты, API-ключи или файловую систему и не содержат исполняемого кода. Каждая таблица стилей сканируется на запрещённые конструкции, а безопасный режим полностью отключает сторонние темы. Гарантии см. в Безопасный режим, а полный API — в генерируемом справочнике Theme SDK.

Следующие шаги​