Уровни тем

Тема построена из трёх независимых уровней. Понимание разделения позволяет теме менять вид всего приложения, не затрагивая его поведение.

Уровень 1: дизайн-токены

Токены — это семантические CSS-кастомные свойства с префиксом --st-. Они покрывают цвета, типографику, отступы, радиусы, границы, тени, слои z-index, анимации, размеры элементов управления, скроллбары и холст чата.

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

{
  "tokens": {
    "dark": {
      "color-accent": "#ff00aa",
      "font-ui": "'Atkinson Hyperlegible', system-ui, sans-serif"
    }
  }
}

Токены разрешаются через цепочку наследования: встроенные значения по умолчанию для режима, затем родительские темы, затем сама тема. Тёмный режим переключается на светлые токены темы, когда тёмного оверрайда нет. Полный контракт см. в Дизайн-токены.

Уровень 2: скин компонентов

Скин компонентов — это CSS, перестилизующий встроенные компоненты через стабильные хуки. Хост публикует атрибуты data-component, data-part, data-role и data-state; тема стилизует эти атрибуты, а не генерируемые имена классов CSS-modules:

@layer theme {
  [data-component='button'][data-variant='primary'] {
    background: var(--st-color-accent);
  }
}

Скин применяется через каскадные слои в фиксированном порядке, при этом слой пользовательских оверрайдов последний. !important запрещён в CSS темы, кроме слоя предпочтений доступности. О порядке слоёв и справочнике хуков см. Скин компонентов.

Уровень 3: макет оболочки

Макет оболочки — это композиция основных областей: навигационной панели, панелей управления и рабочего пространства чата. Он декларативен и выражается в theme.json — никогда в JavaScript:

{
  "shellLayout": {
    "navigationRail": {
      "main": [
        "menu-toggle",
        "chats",
        "characters",
        "personas",
        "lorebooks",
        "backgrounds",
        "ai-settings",
        "plugins"
      ],
      "bottom": ["settings"]
    }
  }
}

Допустимые элементы панели: chats, characters, personas, lorebooks, backgrounds, ai-settings, plugins, settings и необязательный menu-toggle. Группа main течёт сверху; bottom закреплена у нижнего края. Пропущенные элементы добавляются обратно в стандартном порядке, поэтому тема не может случайно скрыть Settings и заблокировать пользователю восстановление.

Имитация других интерфейсов

Поскольку уровни независимы, тема может имитировать совершенно другую парадигму интерфейса:

• Консольная тема меняет токены и скины, делая панель, панели и кнопки похожими на игровой UI.
• Тема визуальной новеллы перестилизует область просмотра чата, сообщения и заголовок персонажа, пока логика чата остаётся нетронутой.
• Тема мобильного приложения использует декларативный макет оболочки, чтобы переупорядочить панель и панели.

Ни для одного из них не нужно трогать логику чата, данные или поведение плагинов — именно поэтому поверхность темы можно заменять целиком. Единственное, чего не предоставляет v1, — свободная перестановка областей оболочки: слоты стилизуются и заполняются, а не перемещаются. О том, что входит в область действия, см. Контракт оболочки.