> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xneon.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Темы оформления Xneon Launcher

> Полное руководство по созданию и редактированию тем оформления в Xneon Launcher 1.0.7.

Руководство для Xneon Launcher **1.0.7**. Текст и иллюстрации обновлены **25 октября 2026 года** по текущим исходникам. Для публичных ID и data-селекторов действует версионированный CSS API v1 с проверкой совместимости; внутреннюю структуру сторонних библиотек проверяйте отдельно.

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

![Раздел тем: готовые пресеты и переход к своим темам](https://mintcdn.com/xneonteam/H7G_ob3YgMSRI-iv/images/themes/presets-v4.png?fit=max\&auto=format\&n=H7G_ob3YgMSRI-iv\&q=85\&s=02381d5d84b90c9d0c3a2c66c346ea61)

Настройки тем. Скриншоты сделаны с настоящих компонентов текущего лаунчера на отдельном демонстрационном профиле. Палитра Midnight выбрана для читаемости; окружающая оболочка на снимках упрощена. Личные темы и аккаунты пользователя при съёмке не использовались.

**Как читать:** для создания темы без кода достаточно разделов [1](https://docs.xneon.org/guide/themes.md), [2](https://docs.xneon.org/guide/themes.md) и [визуального редактора](https://docs.xneon.org/guide/themes.md#visual-editor). Для своей CSS-темы продолжайте с [основ CSS](https://docs.xneon.org/guide/themes/css-basics.md). За конкретной переменной или адресом элемента переходите в связанные справочники ниже.

Основной текст рассчитан на последовательное чтение. Подробные таблицы вынесены отдельно, чтобы не искать инструкцию среди тысяч строк:

* [Все переменные, значения, назначение и места использования](https://github.com/XneonTeam/Xneon-Launcher/blob/main/docs/THEME_VARIABLES.md).
* [Селекторы по страницам, состояния, ограничения и примеры](https://github.com/XneonTeam/Xneon-Launcher/blob/main/docs/CSS_REFERENCE.md).

> [card] [Основы CSS и палитра](https://docs.xneon.org/guide/themes/css-basics.md)
>
> Переменные, архитектура темы и базовый CSS

> [card] [Селекторы и компоненты](https://docs.xneon.org/guide/themes/components.md)
>
> Как найти элементы и оформить страницы

> [card] [Midnight и рецепты](https://docs.xneon.org/guide/themes/recipes.md)
>
> Полная тема Midnight и готовые рецепты оформления

> [card] [Цвета, шрифты и анимации](https://docs.xneon.org/guide/themes/styling.md)
>
> Согласованная палитра, типографика, состояния и движение

> [card] [Медиа, инспектор и DevTools](https://docs.xneon.org/guide/themes/advanced.md)
>
> Работа с изображениями, Electron, инспектором и DevTools

> [card] [Ошибки и безопасность](https://docs.xneon.org/guide/themes/troubleshooting.md)
>
> Поиск проблем, проверка качества и безопасность CSS

> [card] [FAQ и обмен темами](https://docs.xneon.org/guide/themes/sharing.md)
>
> Частые вопросы, публикация тем и сообщество

## Возможности и ограничения

В настройках есть «Готовые темы» и «Мои темы». Готовые пресеты в основном меняют акценты. У своей темы есть полная палитра из 20 цветов, параметры свечения, шрифт, фон и режим CSS. В редакторе также есть настройки светлого/тёмного/системного режима, семантических цветов и эффектов.

CSS может менять поверхности, текст, границы, скругления, тени, размеры, отступы и состояния элементов. Он действует на основной HTML-документ: оболочку, страницы, панели и окна, открытые через портал в этом документе. Правило продолжает действовать и на элементы, появившиеся после загрузки данных.

Доступные способы создания и переноса тем:

* **«Импорт .xntheme»** принимает архив темы прямо в настройках, без облачного подключения.
* **«Экспорт .xntheme»** сохраняет настройки, CSS и локальные ресурсы темы одним архивом.
* Архив включает локальные ресурсы и зависимости вложенных таблиц стилей; при восстановлении ссылки обновляются под хранилище текущего лаунчера.
* **Единый CSS-редактор** задаёт правила интерфейса и статьи внутри читалки. Для 3D-превью есть CSS-параметры камеры, освещения и анимации.
* Общий `--radius` управляет радиусами утилит Tailwind и собственных CSS-компонентов; `--radius-round` отдельно задаёт круглые и овальные элементы. Цвет `--card-foreground` распространяется на обычный текст поверхности карточки, сохраняя смысловые цвета ошибок и акцентов.
* Публичные адреса ID/data-атрибутов закреплены [контрактом API v1](https://github.com/XneonTeam/Xneon-Launcher/blob/main/docs/theme-selector-api-v1.json). Проверка `pnpm run test:theme-api` выявляет их удаление.

Границы языка и среды остаются явными. CSS оформляет существующий интерфейс; игровые действия, новые вкладки и изменение данных реализуются логикой приложения. Нативные окна ОС и внешняя авторизация принадлежат другим документам или операционной системе. Объекты WebGL не являются DOM-узлами: для них применяются предоставленные параметры 3D-превью, а не произвольные селекторы пикселей. Эти границы нельзя устранить заменой стилей или отключением изоляции Electron.

Создавать и редактировать тему можно целиком в лаунчере: внешний редактор и заранее созданный файл не требуются. Перед изменением рабочей темы сделайте её копию через «Дублировать» или экспорт. Сначала меняйте цвета, затем отдельные элементы. На первом этапе не трогайте `display`, `position`, `overflow` и большие размеры.

## Первая работающая тема

### Быстрый старт без CSS

1. Откройте **Настройки → Темы**. Нажатие карточки готового пресета сразу применяет его.
2. Прокрутите до **«Мои темы»** и нажмите **«Создать тему»**.
3. Задайте название. Если нужна определённая основа, выберите её **до** изменения цветов.
4. Оставаясь в режиме **«Визуально»**, на вкладке **«Акцент»** задайте основной цвет `#8b9dff`, дополнительный `#67e8f9`, обводку фокуса `#8b9dff`.
5. Для текста на этих светлых акцентах выберите тёмный цвет `#111827`. Остальные цвета пока оставьте от основы.
6. Нажмите **«Сохранить»**. Тема появится в «Мои темы» и станет выбранной.

Это уже полноценная тема: CSS для неё не требуется. Ниже можно пройти все настройки и затем добавить правила оформления отдельных элементов.

![Мои темы: импорт, создание, изменение, копирование и экспорт](https://mintcdn.com/xneonteam/H7G_ob3YgMSRI-iv/images/themes/my-themes-v3.png?fit=max\&auto=format\&n=H7G_ob3YgMSRI-iv\&q=85\&s=4b5b40a605b7fc00ffe6925d41a6b0a8)

Свои темы находятся ниже пресетов. Под карточкой доступны «Изменить», «Дублировать», «Удалить» и «Экспорт .xntheme». Кнопка импорта находится рядом с созданием темы.

### Создание и применение

1. Откройте **«Настройки» → «Темы»** через боковую навигацию.
2. В разделе **«Мои темы»** нажмите **«Создать тему»**. У существующей темы можно нажать **«Изменить»**, а для копии — **«Дублировать»**.
3. Дайте теме имя, например `Мой Midnight`. При необходимости выберите тему в поле **«Взять за основу»** до внесения своих правок: выбор основы заменяет настройки черновика.
4. Перейдите в режим **CSS**. Откроется встроенный редактор с подсветкой синтаксиса **Prism.js** и готовым блоком `:root` с палитрой. CSS можно писать прямо здесь или вставить из буфера обмена.
5. В существующем блоке замените `--primary` и `--ring` на `#8b9dff`. Ниже блока добавьте правило кнопки из примера.
6. Убедитесь, что включено **«Применять пользовательский CSS»**. Нажмите **«Применить CSS»** или **Ctrl+Enter** (в обработчике также поддержан Meta+Enter).
7. Оцените предпросмотр и нажмите **«Сохранить»**. Тема записывается в «Мои темы» и выбирается. Затем перейдите на главную страницу и проверьте кнопку запуска.

Минимальный самостоятельный пример: его можно вставить вместо всего текста, если вы создаёте новую тему и пока не хотите сохранить другие CSS-правила.

```css theme={null}
:root {
  --primary: #8b9dff;
  --ring: #8b9dff;
}

#home-play-button {
  border-radius: 12px;
}
```

`--primary` меняет основной акцент, `--ring` — использующие его кольца фокуса, `#home-play-button` — радиус главной кнопки запуска/остановки. Неперечисленные цвета остаются от основы. Во время открытого редактора кнопка главной страницы может отсутствовать в DOM; правило сработает после перехода на неё.

Ввод текста сам по себе не применяет CSS. «Применить CSS» обновляет черновик и окно, но ещё не является сохранением. «Сохранить» в режиме CSS также разбирает введённый текст — отдельное применение перед ним необязательно. При переходе в визуальный режим CSS тоже обрабатывается. Закрытие редактора без сохранения возвращает ранее выбранную тему.

### Встроенный CSS-редактор

![Режим CSS: переключатель, применение и редактор с подсветкой](https://mintcdn.com/xneonteam/H7G_ob3YgMSRI-iv/images/themes/css-v3.png?fit=max\&auto=format\&n=H7G_ob3YgMSRI-iv\&q=85\&s=63d175aa8efb21269a40e4c32989ee30)

CSS редактируется в том же окне. Переключатель применения, инспектор и кнопка «Применить CSS» находятся над текстом; «Сохранить» — внизу окна.

Редактор использует `react-simple-code-editor` и Prism.js для подсветки CSS: селекторы, свойства и значения визуально различаются. Подсветка помогает читать текст; результат проверяйте применением. Подсвеченное правило ещё не означает, что его селектор совпадает с элементом или браузер поддерживает каждое значение.

| Элемент | Что делает |
| - | - |
| **«Визуально» / «CSS»** | Переключает способы редактирования одной темы. При переходе к визуальным настройкам CSS разбирается; поддерживаемые значения палитры переносятся в поля цветов. |
| **«Применить CSS»**, **Ctrl+Enter** | Применяет текст к предпросмотру до сохранения темы. |
| **«Инспектор CSS»** | Открывает выбор элемента и копирование его селектора. Подробный сценарий — [в разделе инспектора](https://docs.xneon.org/guide/themes/advanced.md). |
| **«Применять пользовательский CSS»** | Управляет применением дополнительных правил; текст сохраняется и при выключенном переключателе. |
| **«Сохранить»** | Сохраняет тему, включая введённый CSS, и выбирает её в лаунчере. |
| **«Отмена»** или крестик | Возвращает ранее выбранную тему без сохранения черновика. |
| **«Сбросить»** | Заменяет настройки черновика тёмной базой; результат ещё нужно сохранить. |

В текущей русской локализации кнопка сброса подписана **«Сбросить»**. Далее в руководстве выражение «сбросить к тёмной базе» описывает её действие, а не отдельную кнопку.

### Визуальный редактор: все вкладки

Верх окна общий для всех вкладок: **название**, **«Взять за основу»**, **описание**, переключатель **«Визуально / CSS»**. Основная область прокручивается, а кнопки сохранения и отмены остаются внизу. Если не видите часть полей, прокрутите **внутри редактора**, а не страницу за ним.

Изменения визуальных полей применяются к открытому окну как предпросмотр. Это ещё не сохранение: **«Отмена»** возвращает выбранную до редактирования тему. Выбор основы заменяет визуальные настройки черновика, в том числе его CSS, фон и эффекты.

| Вкладка | Что настраивается | С чего начать |
| - | - | - |
| **Акцент** | Основной и дополнительный цвета, текст на них, обводка фокуса | Два сочетающихся цвета и контрастный текст |
| **Фон и поверхности** | Общий фон, карточки, приглушённые поверхности; режим оформления, верхняя панель и смысловые цвета | Сначала фон окна и карточек, затем ошибки и предупреждения |
| **Границы и поля** | Разделители, рамки, фон полей ввода | Чуть более светлая граница на тёмной поверхности |
| **Боковая панель** | Фон, текст, акценты и рамки навигации | Проверить выбранную вкладку и наведение |
| **Текст** | Гарнитура, размер, файл шрифта и цвета обычного/приглушённого текста | Читаемый основной текст и различимые подписи |
| **Фон** | Изображение или видео, масштабирование и параметры медиа | Локальная картинка с затемнением |
| **Эффекты интерфейса** | Размытие поверхностей, скругление, появление содержимого | Небольшое скругление и короткая анимация |
| **Свечение** | Цвет и прозрачность двух декоративных свечений | Небольшая прозрачность, близкий к акценту оттенок |

#### Акцент и текст на кнопках

![Настройка основного и дополнительного акцента](https://mintcdn.com/xneonteam/H7G_ob3YgMSRI-iv/images/themes/editor-colors-v3.png?fit=max\&auto=format\&n=H7G_ob3YgMSRI-iv\&q=85\&s=339de80518b64088f78c76f77e122463)

Слева задаются акценты, справа — цвет текста и иконок поверх них. Цвет фокуса настраивается отдельно.

Нажмите цветной квадрат для выбора цвета либо введите hex в соседнее поле. Для основной палитры используйте, например, `#8b9dff`. Значение с ошибкой отмечается в поле; завершите ввод корректным цветом перед сохранением.

**Основной акцент** обычно виден на кнопках действий и выбранных элементах. **Дополнительный** помогает расставить вторичные акценты. Цвет текста на акценте не обязан совпадать с обычным текстом страницы: на светлой кнопке чаще нужен тёмный текст. **Обводка фокуса** должна оставаться заметной при навигации клавишей Tab.

#### Поверхности и светлый/тёмный режим

![Режим оформления, верхняя панель и цвета состояний](https://mintcdn.com/xneonteam/ErdmN4so50YjnVFT/images/themes/08-surfaces.png?fit=max\&auto=format\&n=ErdmN4so50YjnVFT\&q=85\&s=777c2d0c7b93a3ccb231379be75b082c)

В «Фон и поверхности» находятся дополнительные параметры. Остальные поля этой вкладки видны при прокрутке.

Не путайте **«Фон и поверхности»** с вкладкой **«Фон»**. Первая задаёт цвета интерфейса; вторая добавляет картинку или видео под ним. Если карточки непрозрачные, обои могут быть видны только в свободных областях.

Режим оформления предлагает **«Как в палитре»**, **«Светлый»**, **«Тёмный»**, **«Как в системе»**. При смене режима меняются нейтральные поверхности и текст; акценты сохраняются. Светлую и тёмную нейтральную палитру можно настроить отдельно. Для проверки системного варианта переключите режим оформления ОС.

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

#### Границы, поля и боковая панель

Граница отделяет карточку от фона, а фон поля помогает распознать место ввода. Не делайте всё одним цветом: проверьте хотя бы поиск и поле названия темы. Цвет фокуса нужен и при одинаково тонких границах.

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

#### Текст и загрузка шрифта

![Гарнитура, размер и загрузка файла шрифта](https://mintcdn.com/xneonteam/ErdmN4so50YjnVFT/images/themes/04-font.png?fit=max\&auto=format\&n=ErdmN4so50YjnVFT\&q=85\&s=a81ef1da7d35199364c574a002c88747)

Вкладка «Текст» объединяет шрифт и цвета текста. Список цветов продолжается ниже видимой области.

Выберите гарнитуру из списка либо укажите свою. Гарнитура по имени должна быть установлена на компьютере; для переноса вместе с темой используйте **«Загрузить файл шрифта»**. Поддерживаются `ttf`, `otf`, `woff`, `woff2`.

Базовый размер регулируется от **11 до 20 px**, по умолчанию **16 px**. Некоторые компоненты задают собственный размер; увеличение базового размера не означает одинаковое увеличение каждой подписи. После изменения проверьте длинные названия, нижние кнопки диалогов и окна при минимальном размере лаунчера.

#### Картинка и видео на фоне

![Выбор фонового изображения, источника и эффектов](https://mintcdn.com/xneonteam/ErdmN4so50YjnVFT/images/themes/05-background.png?fit=max\&auto=format\&n=ErdmN4so50YjnVFT\&q=85\&s=411545a34eb7d4c106054cd2d3c73903)

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

1. Перейдите на вкладку **«Фон»**.
2. Выберите **«Изображение»** или **«Видео»**.
3. Нажмите **«Выбрать файл»** либо вставьте прямую ссылку на медиа. Страница с картинкой и сама картинка — разные адреса.
4. Выберите масштабирование: **заполнить с обрезкой** заполняет окно, но может обрезать края; **вписать целиком** сохраняет всё изображение и может оставить свободные поля.
5. Подстройте **затемнение**, **размытие**, **прозрачность**. При нулевой непрозрачности фон полностью скрывается.
6. Для видео при необходимости измените громкость; по умолчанию она нулевая.
7. Сохраните тему и проверьте читаемость поверх обоев на нескольких вкладках.

Изображения: `png`, `jpg`, `jpeg`, `webp`, `gif`, `avif`, `bmp`, `svg`. Видео: `mp4`, `webm`, `ogv`. Один выбираемый файл — не больше **128 МиБ**. Поддержка конкретного видео зависит от кодека, а не только от расширения.

Кнопка получения палитры из изображения или видео извлекает цвета из источника. Результат — отправная точка: после генерации проверьте текст и контраст кнопок. Если источник не читается или формат не поддерживается, выберите другой файл. Для видео используется кадр, поэтому результат не описывает все сцены ролика.

Для распространения удобнее локальные ресурсы и архив `.xntheme`: удалённые ссылки остаются ссылками, зависят от сети и не превращаются автоматически в файлы архива. Штатный выбор файла копирует ресурс в хранилище лаунчера, поэтому после выбора исходный файл не требуется держать на прежнем месте.

#### Эффекты и анимация появления

![Размытие, скругление и параметры появления элементов](https://mintcdn.com/xneonteam/ErdmN4so50YjnVFT/images/themes/06-effects.png?fit=max\&auto=format\&n=ErdmN4so50YjnVFT\&q=85\&s=e50c2f9caa05d9ebcef1ac2e992656b4)

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

Размытие поверхностей полезно, когда под ними есть картинка или градиент: на однотонном фоне разница может быть едва заметна. Не путайте размытие **карточки** с размытием **фоновой картинки** — это разные настройки.

Для появления содержимого доступны стандартный вариант, плавное появление, сдвиг снизу, сдвиг сбоку, масштаб, размытие, отключение и своя анимация через CSS. Длительность — **100–2000 мс**; начните с **200–350 мс**. Это анимация интерфейса, а не время загрузки данных или продолжительность стартового splash.

Для своей анимации выберите соответствующий вариант, укажите имя `@keyframes` и определите его в CSS. Пошаговые примеры находятся в [разделе анимаций](https://docs.xneon.org/guide/themes/styling.md). Соблюдайте пользовательскую настройку уменьшения движения.

#### Декоративное свечение

![Цвет и прозрачность основного и дополнительного свечения](https://mintcdn.com/xneonteam/ErdmN4so50YjnVFT/images/themes/07-glow.png?fit=max\&auto=format\&n=ErdmN4so50YjnVFT\&q=85\&s=4b7bac19a45f249c1e30b5d1b1376404)

У каждого свечения свой цвет и ползунок прозрачности. Это оформление, а не цвет текста или подложки кнопки.

Задайте цвет, близкий к своему акценту, и начните с небольшой прозрачности. Одинаковый цвет может выглядеть по-разному в шапке, панели библиотеки скинов и 3D-превью: компоненты сами определяют площадь и интенсивность декоративного освещения. Не пытайтесь исправить контраст текста усилением свечения — для текста есть отдельные поля.

### Сохранение, копия и перенос: что выбрать

| Задача | Действие | Результат |
| - | - | - |
| Использовать пресет | Нажать его карточку | Применение без создания копии |
| Создать свою тему | «Создать тему» → настроить → «Сохранить» | Новая запись в «Мои темы» |
| Изменить существующую | «Изменить» → «Сохранить» | Обновление этой темы |
| Поэкспериментировать без потери оригинала | «Дублировать» → менять копию | Отдельная тема |
| Забрать тему на другой компьютер | «Экспорт .xntheme» | Архив настроек и включённых локальных ресурсов |
| Установить полученный архив | «Импорт .xntheme» → выбрать файл | Отдельная тема, которая сразу выбирается |
| Передать только несколько CSS-правил | Скопировать текст из CSS-редактора | Получателю нужно вставить его в свою тему |
| Отказаться от несохранённых правок | «Отмена» или крестик | Возвращается прежняя выбранная тема |
| Вернуться к стандартному виду | Выбрать Core | Переключение на пресет по умолчанию |

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

Обычный путь — **«Создать тему» → CSS → написать или вставить правила → «Применить CSS» → «Сохранить»**. Лаунчер сам создаёт файлы сохранённой темы в своей папке.

### Экспорт и резервная копия

Создайте тему в лаунчере и нажмите «Экспорт .xntheme» на её карточке. Архив переносит структурированные настройки, CSS, фон, шрифт и локальные ресурсы. Для восстановления нажмите «Импорт .xntheme» и выберите архив: он добавится как отдельная тема и сразу применится.

Для обмена текстом можно скопировать CSS из встроенного редактора и вставить в редактор другой темы. Файлы `.css` через диалоги импорта и экспорта не переносятся. Внешние HTTP-ресурсы в архиве остаются ссылками.

### Как отменить изменения

* Для несохранённого черновика нажмите **«Отмена»** или закройте редактор.
* Для отдельного эффекта удалите добавленное правило, примените CSS и сохраните.
* Для временного отключения дополнительных правил снимите **«Применять пользовательский CSS»** и сохраните. Цвета, которые уже перенесены в палитру при разборе CSS, останутся: этот переключатель не восстанавливает прежнюю палитру.
* Для полного возврата выберите **Core** в «Готовых темах». Он является первым пресетом и темой по умолчанию в текущих исходниках.
* **«Сбросить к тёмной базе»** внутри редактора сбрасывает палитру, фон, шрифт, CSS и эффекты черновика. После этого нужно сохранить. Это именно тёмная база, её дополнительный акцент может отличаться от Core.
* Удаление выбранной своей темы переключает лаунчер на пресет по умолчанию. Для простого отключения удалять тему не требуется.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.