> ## 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.

# Основы CSS, применение темы и переменные

> Основы CSS, архитектура применения темы в лаунчере и полный обзор переменных палитры.

## Основы CSS

### Правило, селектор, свойство и значение

CSS-файл — обычный текст с расширением `.css`. Вот **условный учебный пример**, которого нет в разметке лаунчера:

```css theme={null}
.example-card {
  background-color: #15171c;
  color: #ffffff;
  border: 1px solid #30343d;
  padding: 16px;
  border-radius: 8px;
}
```

`.example-card` — **селектор**, адрес элементов с классом `example-card`. Точка означает класс. Фигурные скобки содержат настройки. Каждая строка — **объявление**: свойство слева от двоеточия и значение справа. Точка с запятой завершает объявление.

`background-color` задаёт фон, `color` — текст, `border` — границу толщиной 1 пиксель со сплошной линией заданного цвета. `padding` оставляет 16 пикселей внутри вокруг содержимого. `border-radius` скругляет углы на 8 пикселей. Этот пример ничего не изменит в Xneon Launcher: класса `.example-card` там нет.

### Адреса элементов

Следующие селекторы уже относятся к реальному лаунчеру:

```css theme={null}
/* ID: решётка, затем точное имя. */
#home-play-button { font-weight: 700; }

/* Класс: точка, затем имя. Все кнопки навигации. */
.sidebar-item-btn { border-radius: 10px; }

/* Пробел: любой подходящий потомок внутри контейнера. */
#launcher-sidebar .sidebar-item-btn { letter-spacing: 0.02em; }

/* Запятая: одинаковое правило для нескольких адресов. */
#home-account-card,
#home-version-card { border-color: #38445d; }

/* Атрибут: компонент с указанным именем. */
[data-component="build-card"] { border-radius: 14px; }

/* Псевдокласс: применяется при наведении. */
.sidebar-item-btn:hover { color: var(--sidebar-primary); }
```

Потомок — элемент внутри другого элемента, в том числе через промежуточные контейнеры. Знак `>` выбирает только непосредственного ребёнка. Например, `.code-editor-wrapper > textarea` относится к многострочному полю непосредственно в обёртке редактора кода. Селектор без пробела `.sidebar-item-btn[data-active="true"]` требует одновременно класс и атрибут на одном узле.

### Переменные

CSS-переменная — именованное значение. Её имя начинается с двух дефисов; `var()` подставляет значение в свойство. `:root` выбирает корневой HTML-элемент, от которого переменные наследуются интерфейсом.

```css theme={null}
:root {
  --primary: #91a6ff;
}

#home-play-button {
  outline-color: var(--primary);
}
```

Объявление переменной не перекрашивает элементы само: они должны читать её через `var()` прямо или через Tailwind-утилиту. Своя переменная допустима, если вы сами её используете. Например, в этом **учебном дополнении** `--my-shadow` придумана автором темы, а ID кнопки — реальный:

```css theme={null}
:root { --my-shadow: 0 6px 18px #00000033; }
#home-play-button { box-shadow: var(--my-shadow); }
```

### Оформление небольшого элемента

```css theme={null}
#home-play-button {
  color: #111827;
  background: linear-gradient(135deg, #a5b4fc, #67e8f9);
  border: 1px solid #c7d2fe;
  border-radius: 12px;
  box-shadow: 0 4px 16px #00000033;
  letter-spacing: 0.02em;
  transition: filter 160ms ease-out;
}

#home-play-button:enabled:hover {
  filter: brightness(1.06);
}
```

Это реальное правило для главной кнопки: градиент плавно смешивает два цвета под углом 135°, тень смещена вниз на 4px и размыта на 16px. `#00000033` — чёрный с прозрачностью. `letter-spacing` меняет расстояние между буквами. `transition` делает изменение фильтра плавным. После вставки проверьте также состояние остановки и загрузки; CSS не меняет их логику.

### Каскад и `!important`

Каскад — способ выбрать итоговое значение, когда несколько правил задают одно свойство. В пределах одинакового источника и уровня важности сначала учитываются слои CSS, затем специфичность, затем порядок. Специфичность — «точность адреса»: ID обычно сильнее класса/атрибута/псевдокласса, они сильнее селектора тега. Например, `#launcher-sidebar .sidebar-item-btn` сильнее `.sidebar-item-btn`. При одинаковой специфичности побеждает более позднее правило.

Обычный inline-стиль `style="..."` сильнее обычного правила таблицы стилей. `!important` повышает приоритет отдельного объявления; его не следует писать повсюду. У важных объявлений порядок слоёв обращается, поэтому простое увеличение числа ID не решает все конфликты.

```css theme={null}
/* Пример точечного переопределения размера inline-редактора. */
#theme-css-editor {
  font-size: 13px !important;
}
```

В `ThemeEditor` размер редактора задаётся inline как 12px, поэтому такой приём имеет конкретную причину. Для переменных обычного CSS темы `!important` обычно не нужен: лаунчер переносит свою базу в предшествующий `<style>`. Сначала ищите конфликт, затем повышайте приоритет.

### Комментарии и ошибки

Комментарий записывается как `/* пояснение */`. Строка `// пояснение` не является обычным CSS-комментарием. Не забудьте `;`, двоеточие и закрывающую `}`. Используйте `#ffffff`, а не `ffffff` для обычного CSS-цвета; исключения визуального HEX-поля не меняют синтаксис CSS.

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

## Как лаунчер применяет тему

### Файлы и способы стилизации

| Источник | Роль |
| - | - |
| [src/main.tsx](https://github.com/XneonTeam/Xneon-Launcher/blob/main/src/main.tsx) | Подключает четыре начертания Plus Jakarta Sans, глобальный CSS, инициализирует тему до рендера приложения |
| [src/index.css](https://github.com/XneonTeam/Xneon-Launcher/blob/main/src/index.css) | Tailwind CSS 4, tw-animate-css, светлая/тёмная база, мосты токенов, скроллбары, ползунки, градиенты, Prism, иконки, эффекты |
| [theme-surfaces.css](https://github.com/XneonTeam/Xneon-Launcher/blob/main/src/theme-surfaces.css) | Наследование цвета семантических поверхностей и токен круглых элементов |
| [theme-library.ts](https://github.com/XneonTeam/Xneon-Launcher/blob/main/electron/main/theme-library.ts) | CSS-файлы, метаданные, перенос и экспорт относительных ресурсов |
| [settings-motion.css](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/settings-motion.css) | Анимации появления страниц; импортируется через settings-motion.ts |
| [agent.css](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/agent/agent.css) | Отдельные стили AI-ассистента, его меню, сообщений, вложений и состояний; импортируется страницей агента |
| [index.html](https://github.com/XneonTeam/Xneon-Launcher/blob/main/index.html) | Встроенный CSS временной заставки до готовности React |
| [theme-model.ts](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/theme-model.ts) | Применяет палитру, классы режима, фон, эффекты и произвольный CSS |
| [theme-store.ts](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/theme-store.ts) | Выбор темы, сохранение и восстановление, обновления настроек |
| [theme-runtime.tsx](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/settings/theme-runtime.tsx) | Системный режим, загрузка файла шрифта и распознавание видео из CSS |
| [theme-background-layer.tsx](https://github.com/XneonTeam/Xneon-Launcher/blob/main/components/launcher/theme-background-layer.tsx) | DOM-слой изображения, видео, частиц или свечения |

В `src/` и `components/` найдены четыре собственных CSS-файла. SCSS, Less и CSS Modules в этой области исходников не обнаружены. Это не отменяет CSS зависимостей: Tailwind, tw-animate-css и подключённых шрифтов.

Большинство JSX-компонентов содержит `className` с Tailwind-утилитами (`bg-card`, `text-muted-foreground`, `rounded-xl`, `hover:...`). Tailwind генерирует CSS при сборке. `@theme inline` связывает цветовые утилиты с базовыми переменными, например `bg-card` читает `--card`. В файле пользовательской темы пишите обычный CSS: директивы сборки `@apply`, `@theme` и `@custom-variant` не обрабатываются редактором.

JSX также использует условные классы через `cn`, SVG-атрибуты и inline-стили — ширины прогресса, координаты, цвета превью, размер шрифта редактора. React обновляет их при изменении данных. Правило CSS сохраняется при перерисовке, ручная правка DOM через DevTools может быть заменена следующим рендером.

### Применение и порядок

**Инжекция CSS** здесь означает подключение текста оформления к документу лаунчера через элементы `<style>`. Её выполняет механизм применения темы после «Применить CSS», сохранения или выбора темы. Prism.js отвечает за подсветку текста в редакторе, а **«Инспектор CSS»** помогает найти селектор. Это разные части работы с темой.

1. `applyTheme` убирает переменные, классы эффектов и оба `<style>` предыдущей темы.
2. Выбирает режим, переключает `.dark` и `data-theme-mode` на `<html>`.
3. Применяет палитру/акценты, семантические цвета, шрифт, фон и эффекты.
4. Если включён непустой пользовательский CSS, переносит управляемые корневые inline-значения в **`style#theme-base-css`**, а после него создаёт **`style#theme-custom-css`** с вашим CSS.
5. При смене темы эти правила заменяются; при выборе пресета пользовательский CSS прежней темы не остаётся.

Поэтому обычный поздний `:root { --primary: ...; }` работает без `!important` против базы темы. Но адресный селектор с ID или inline-стиль конкретного элемента может потребовать более точного переопределения. Большая часть Tailwind находится в именованных слоях, обычное правило темы вне слоя имеет приоритет над обычными правилами этих слоёв. В `src/index.css` есть и правила вне слоёв — с ними учитываются специфичность и порядок.

CSS ленивой страницы может подключиться при первом открытии, особенно в dev. Для `.agent-*` не полагайтесь только на расположение одинаковых правил: задавайте контекст, например `.agent-page .agent-composer`. Итог проверяйте после открытия страницы.

### Разбор текста и сохранение

Парсер читает **первый** блок `:root`. Распознанные HEX-значения 20 цветов переносит в палитру, восьмизначные HEX свечения — в параметры свечения, основную гарнитуру и размер в px — в настройки шрифта. Остальной CSS хранится как текст. Восстановимые ведущие блоки палитры удаляются из этого текстового хвоста, чтобы при повторном открытии не накапливались копии. Блок с собственными объявлениями сохраняется.

Практическое правило: держите палитру в первом `:root`, используйте `#rrggbb`, а адресные правила размещайте ниже. RGB/HSL/OKLCH допустимы в CSS, но могут не синхронизироваться с визуальным выбором цветов и миниатюрой. Парсер формата — не полноценный CSS-валидатор. Ограничение сохранённого `theme.css` при нормализации — 1 МиБ текста.

CSS связанных тем читается из папки `themes`; файл обновляет сохранённый снимок темы. БД (`customThemes`, выбранный ID — `theme`) хранит реестр и последнюю рабочую копию, localStorage ускоряет запуск. Соседние `.css.json` сохраняют структурированные настройки. Очистка только localStorage не удаляет тему. События `settings:updated` обновляют реестр без перезапуска. Для заставки кешируется отдельный снимок восьми цветов; произвольный CSS и медиа не применяются к самому раннему кадру запуска.

## Переменные и палитра

Полная таблица из **166 имён**, включая мосты Tailwind и внутренние параметры, находится в [THEME\_VARIABLES.md](https://github.com/XneonTeam/Xneon-Launcher/blob/main/docs/THEME_VARIABLES.md). В ней указаны исходные светлые и тёмные значения, результат применения темы, назначение, потребители и рекомендации. Число не включает все автоматически генерируемые `--tw-*` зависимостей.

### 20 цветов визуального редактора

Это HEX-значения `DARK_PALETTE`, с которых начинается новая своя тема без основы. Активный Core использует собственные OKLCH-акценты; не путайте его с этой базой.

| Переменная | Тёмная база | Что меняет |
| - | - | - |
| `--background` | `#010203` | Фон приложения |
| `--foreground` | `#ffffff` | Основной текст |
| `--card` | `#020204` | Поверхности карточек |
| `--card-foreground` | `#ffffff` | Текст, использующий токен карточки |
| `--muted` | `#07090d` | Приглушённые поверхности |
| `--muted-foreground` | `#555555` | Второстепенный текст |
| `--border` | `#0d1014` | Общие границы |
| `--input` | `#040609` | Токен поля/Select, не обязательно фон любого input |
| `--primary` | `#f64b00` | Главный акцент |
| `--primary-foreground` | `#030303` | Текст на главном акценте |
| `--accent` | `#ca6100` | Второй акцент |
| `--accent-foreground` | `#ffffff` | Текст на втором акценте |
| `--ring` | `#f64b00` | Кольца фокуса |
| `--sidebar` | `#000102` | Фон боковой и по умолчанию верхней панели |
| `--sidebar-foreground` | `#ffffff` | Текст боковой навигации |
| `--sidebar-primary` | `#f64b00` | Её главный акцент |
| `--sidebar-primary-foreground` | `#030303` | Текст на нём |
| `--sidebar-accent` | `#ca6100` | Её второй акцент |
| `--sidebar-accent-foreground` | `#ffffff` | Текст на нём |
| `--sidebar-border` | `#090b0f` | Граница боковой и верхней панели |

С палитрой `--popover` следует за `--card`, `--popover-foreground` — за `--card-foreground`, `--secondary` — за `--muted`, `--secondary-foreground` — за `--foreground`. Стеклянные поверхности и пять токенов графиков также получают ссылки на палитру. Это позволяет переопределять их отдельным CSS.

### Статусы, свечение и размеры

По умолчанию `--destructive` и `--info` следуют `--primary`, а `--warning` и `--success` — `--accent`. Это реальное поведение проекта: фиксированные красный/зелёный для всех тем не гарантируются. Расширенные настройки задают явные цвета статусов; старые Tailwind-цвета red/rose, yellow/amber, blue/sky, green/emerald оттенков 300–700 переназначаются на соответствующий статус. Значки и текст должны помогать различать смысл независимо от цвета.

`--glow-primary` и `--glow-accent` включают прозрачность; при обычном создании это цвет акцента с альфой 0.4. `--ambient-primary`/`--ambient-accent` — только цвета фоновых свечений, силу отдельного свечения задаёт его компонент. Изменение `--primary` только произвольным поздним CSS не обязано автоматически пересчитать независимые `--ambient-*`; при необходимости задайте их тоже.

`--radius` имеет исходное значение `0.75rem`. sm/md ограничены снизу нулём и вычисляются как −4px/−2px, lg равен базе, xl — база +4px. xs, 2xl, 3xl и 4xl также привязаны к базе; собственные CSS-компоненты используют пропорциональные значения. Отдельный `--radius-round` задаёт круглые/овальные элементы. Поле радиуса в эффектах выставляет и `--theme-radius`, и общую базу `--radius`. Адресное авторское правило с явным border-radius по-прежнему имеет собственный смысл и может переопределить токен.

`--theme-bg-*` влияет на уже созданный слой фона, но не создаёт изображение само. `--theme-blur-*` требует соответствующей архитектуры эффектов; проще сначала включить эффект визуально. `--current-value`, `--min-value`, `--max-value` — значения реального ползунка, их не нужно подменять ради цвета. Единой пользовательской переменной «все отступы» или «все тени» в проекте нет.


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