Темы и стили
Что такое тема и стили
Стили — правила CSS, которые задают визуал сайта — цвета, шрифты, отступы, тени, градиенты. В браузере они собираются в CSSOM (дерево стилей) и применяются к узлам DOM, построенному из HTML. Подробнее — подключение CSS и основные стили.
Тема в Docusaurus — пакет оформления (@docusaurus/theme-classic на базе Infima) плюс кастомные листы из src/css/. В "Вселенной IT" оформление устроено двумя ортогональными слоями, которые читатель может сочетать независимо.
| Слой | Переключатель | Атрибут на <html> | Хранение |
|---|---|---|---|
| Яркость (color mode) | ColorModeToggle Docusaurus | data-theme="light" / dark | localStorage, ключи theme |
| Палитра (design) | DesignThemePicker | data-design="design-matrix-code" | localStorage, ключ it-universe-design |
Тёмная палитра Matrix + светлый режим ☀, светлая Sakura + тёмный ☾ — допустимые комбинации. Слои ортогональны — меняют разные оси оформления.
См. структуру src/css/, docusaurus.config.js (customCss, inject).
DOM и как темы попадают на страницу
<html data-theme="dark" data-design="design-matrix-code" lang="ru">
<head>...</head>
<body>...</body>
</html>
| Атрибут | Кто меняет | Селекторы в CSS |
|---|---|---|
data-theme | Toggle light/dark | html[data-theme='dark'] |
data-design | Выпадающий список палитр | html[data-design="design-sakura-spring"] |
Перекраска без перезагрузки — смена атрибута на document.documentElement; CSS-переменные пересчитываются, React-дерево остаётся на месте (SPA, клиентская навигация).
Docusaurus, Infima и color mode
Docusaurus подключает тему через preset classic — layout (navbar, sidebar, doc page), typography, admonitions. Базовая сетка и компоненты — Infima с префиксом --ifm-*.
В themeConfig.
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
},
Явный выбор пользователя важнее системной темы ОС — respectPrefersColorScheme: false. Светлая и тёмная темы Infima переключаются через data-theme.
Swizzle Navbar/ColorModeToggle встраивает DesignThemePicker рядом с переключателем яркости — два toggle в одной панели.
Палитры design — каталог и picker
itDesigns.json
{
"id": "design-universe-original",
"name": "Оригинал (Вселенная IT)",
"mode": "light",
"featured": true
}
| Поле | Роль |
|---|---|
id | Значение data-design и селектор в CSS |
name | Подпись в UI |
mode | Рекомендуемая яркость палитры (подсказка, не жёсткое правило) |
featured | Группа "★ Популярные" в списке |
В каталоге 25+ палитр (Matrix, Sakura, Cosmic Void…). API палитр — src/utils/itDesignTheme.ts.
export function applyItDesign(designId: string): ItDesign {
document.documentElement.setAttribute('data-design', design.id);
localStorage.setItem(IT_DESIGN_STORAGE_KEY, design.id);
return design;
}
DesignThemePicker
src/components/DesignThemePicker/index.tsx — <select> с группами тем: "Оригинал", optgroup "★ Популярные", "Все темы". Локальные стили — styles.module.css (хеширование webpack).
При onChange — applyItDesign, обновление state, синхронизация между вкладками через storage event.
Защита от FOUC, inject и clientModules
FOUC (Flash of Unstyled Content) — краткая вспышка "чужой" палитры до применения CSS/атрибутов. См. глоссарий config.
До React плагин it-design-theme-inject в docusaurus.config.js вставляет inline-скрипт в <head>.
(function(){
try {
var id = localStorage.getItem('it-universe-design') || 'design-universe-original';
document.documentElement.setAttribute('data-design', id);
} catch (e) { /* fallback */ }
})();
После загрузки бандла
| Модуль | Роль |
|---|---|
itDesignThemeInit.js | Повтор data-design при SPA-переходах |
itThemeStorageGuard.js | Чистит битые ключи theme (всё, кроме light/dark) — разрыв цикла toggle color mode |
Цикл toggle — повреждённое значение в localStorage заставляет Docusaurus бесконечно переключать data-theme; guard удаляет некорректные записи с префиксом theme.
CSS-переменные и дизайн-токены
CSS-переменные (custom properties) — --имя: значение; на :root или html[data-design="..."]. Подстановка — var(--имя). Каскад и наследование работают как у обычных свойств. См. CSS-переменные в энциклопедии.
Дизайн-токен — именованная величина палитры с префиксом --d-*.
| Токен | Назначение |
|---|---|
--d-primary, --d-accent2 | Акценты, ссылки, кнопки |
--d-bg, --d-surface | Фон страницы и карточек |
--d-text, --d-text-muted | Основной и вторичный текст |
--d-nav, --d-footer | Navbar и footer |
--d-code-bg, --d-code-fg | Блоки кода |
--d-shadow, --d-hero-bg | Тень, градиент hero |
Файл it-design-themes.css — автоген (node scripts/generate-themes.js), блоки такого вида.
html[data-design="design-matrix-code"] {
--d-bg: #0d0208;
--d-primary: #00ff41;
--d-hero-bg: linear-gradient(180deg, #0a1a0a 0%, #0d0208 60%);
}
Bridge — маппинг на Infima
it-design-bridge.css — маппинг --d-* → --ifm-*.
html[data-design]:not([data-design='design-universe-original']) {
--ifm-background-color: var(--d-bg);
--ifm-color-primary: var(--d-primary);
--ifm-navbar-background-color: var(--d-nav);
}
Стандартные компоненты Docusaurus (navbar, menu, footer, cards) наследуют палитру через Infima без правки каждого swizzle-компонента.
Согласование палитры × яркости
| Файл | Роль |
|---|---|
it-design-color-mode.css | Палитра × data-theme — перекраска фонов светлых тем в dark mode |
it-design-scheme.css | color-scheme: light/dark от переключателя ☀/☾ |
it-design-compat.css | Токены статей --it-doc-* под все data-design |
it-design-effects.css | Доп. эффекты, звёзды, свечение |
Согласование — светлая Sakura при data-theme="dark" получает тёмные --d-bg через color-mix, брендовый --d-primary остаётся из it-design-themes.css.
custom.css и цепочка импортов
custom.css (~1800 строк) — главная точка входа глобального стиля. Подключается в preset → customCss (первый в списке).
@import './it-design-themes.css';
@import './it-design-scheme.css';
@import './it-design-color-mode.css';
@import './it-design-bridge.css';
/* ... sidebar, article, search ... */
Layout и chrome
В :root и html[data-theme] — переменные layout — ширина контента, отступы doc, рельсы --it-doc-rail-color, chip-теги --it-tag-chip-*.
article tags и tag
Классы .article-tags, .tag, .complexity-badge — чипы "ОБЯЗАТЕЛЬНО", "ДЛЯ НОВИЧКОВ", аудитория. Стили в custom.css; кликабельность добавляет articleMetaEnhancement.ts.
wiki-links
.wiki-link, .wiki-link--glossary, .wiki-link--encyclopedia — оформление ссылок из remark [[термин]] (wikiLink).
callout
Блоки .callout, .callout--tip, .callout--warning, .callout-title — замена admonition Docusaurus в статьях энциклопедии.
demo-класс
Классы оболочки демо — it-demo-shell.css, placeholder PDF .pdf-export-demo-placeholder, shell для embed.
Типографика статей
article-docs-prime.css — типографика в .theme-doc-markdown.
| Элемент | Что настроено |
|---|---|
| Заголовок h1–h6 | Размеры, отступы до/после, hero-оформление h1 |
| Список | Межстрочные интервалы, вложенность |
| Таблица | Границы, zebra, адаптив |
Горизонтальная линия hr | Отступы --it-doc-hr-gap |
| Callout | Радиус, граница, градиенты |
| Цитаты, figure | Фон, border |
Токены --it-doc-* согласованы с Infima и --d-* через it-design-compat.css. Шрифт палитры — --d-font в bridge.
Sidebar, иконки, космос
sidebar-explorer.css — "проводник" в sidebar.
| Приём | Описание |
|---|---|
| Маска | SVG через mask-image + background-color — иконка красится в --ifm-color-primary |
| Рельсы | Вертикальные линии --it-explorer-rail у пунктов меню |
| Папка/файл/caret | --it-mask-folder-open, --it-mask-file |
sidebar-cosmic-explorer.css — космические акценты для data-theme='dark' — тинт sidebar color-mix с primary, без тяжёлого blur.
DocSearch и блоки кода
doc-search-theme.css — модальное окно поиска Ctrl+K (overlay, результаты, фокус).
it-design-code-overrides.css — подключён вторым в customCss — стиль блоков кода под все палитры, override Prism/One Dark, читаемость при любом data-design и data-theme. Проверять contrast при добавлении палитры.
Локальные стили и CSS modules
Локальные стили — *.module.css рядом с компонентом. Webpack хеширует имена классов CSS (styles.select_a1b2c3), коллизия с глобальным custom.css исключена.
Примеры — DesignThemePicker/styles.module.css, ExternalPlayEmbed.module.css, DocSearch/styles.module.css.
Переопределение глобальное — селекторы в custom.css; локальное — только внутри компонента. Override в it-design-code-overrides.css — принудительные правила для fenced code (!important где нужно).
Embed, iframe и brightness mode
ExternalPlayEmbed передаёт текущий colorMode в query iframe.
url.searchParams.set('theme', theme); // light | dark
На play уходит brightness mode (светлый/тёмный фон демо), без палитры data-design. Согласование визуала embed с сайтом идёт по data-theme; Matrix/Sakura на play не передаются.
Добавление новой палитры
- Запись в
src/data/itDesigns.json. node scripts/generate-themes.js→ обновитьit-design-themes.css.- Проверить contrast текста и стиль блоков кода.
- При необходимости — блок в
it-design-color-mode.cssи эффекты вit-design-effects.css.
Практические советы
| Проблема | Что проверить |
|---|---|
| Мигание палитры при загрузке | inline inject в it-design-theme-inject |
| Сброс design после навигации | itDesignThemeInit.js |
| Код нечитаем в палитре | it-design-code-overrides.css |
| Цикл переключения light/dark | itThemeStorageGuard.js, ключи theme |
| Sidebar "ломает" ширину | resize handle + docSidebarWidth |
Глоссарий
Оформление
Совокупность визуальных решений сайта — цвета, типографика, отступы, эффекты.
Дизайн
В проекте — палитра data-design (Matrix, Sakura…), отдельно от яркости data-theme.
CSS
Язык стилей; файлы в src/css/. Раздел CSS.
Классы CSS
Имена в разметке (.article-tags, .callout--tip); в modules — с хешем.
Тема
Docusaurus theme-classic + Infima + кастомные листы; также разговорно — одна палитра data-design.
Визуал
То, что видит пользователь — цвет, контраст, плотность, анимации.
Светлая и тёмная темы
Режимы яркости Infima — data-theme="light" / dark, переключатель ☀/☾.
Infima
CSS-фреймворк Docusaurus, переменные --ifm-*, сетка. См. package.json и стек.
CSS-переменные
Custom properties --name: value, подстановка var(--name).
Ортогональность
Независимость слоёв data-theme и data-design — можно комбинировать свободно.
Сочетание
Выбранная пара яркости и палитры на <html>.
DOM
Document Object Model — дерево узлов страницы в памяти браузера.
HTML
Разметка страницы; атрибуты data-theme, data-design на <html>. HTML в энциклопедии.
CSSOM
CSS Object Model — дерево правил стилей, связанное с DOM.
color mode
Режим яркости Docusaurus (light/dark); атрибут data-theme.
Ключи theme
Записи localStorage с префиксом theme для color mode Docusaurus.
Docusaurus и темы
themeConfig, customCss, swizzle, colorMode — см. config.
Селекторы
Правила привязки CSS к узлам — html[data-design="..."], .theme-doc-markdown h2.
Палитра
Набор --d-* токенов для одного id в itDesigns.json.
Группы тем
optgroup в picker — Оригинал, Популярные, Все темы.
Выпадающий список
<select> в DesignThemePicker.
swizzle
Кастомные компоненты темы в src/theme/. См. структура src.
Перекраска без перезагрузки
Смена data-design / data-theme без full page reload.
FOUC
Вспышка неверного оформления до применения стилей; лечится inject.
inject
injectHtmlTags — inline-скрипт data-design в <head> до React.
Клиентская навигация
Переходы без перезагрузки в SPA.
SPA
Single Page Application после первой загрузки Docusaurus.
toggle
Переключатель — color mode или выбор палитры.
Цикл toggle
Бесконечное переключение theme из-за битого localStorage; лечит itThemeStorageGuard.
custom.css
Главный глобальный CSS-файл проекта.
layout
Расположение блоков страницы — doc main, sidebar, navbar; переменные ширины/отступов.
tag
Класс чипа метки — .tag-required, .tag-beginner.
article tags
Блок .article-tags в начале статьи.
wiki-links
Стили .wiki-link* для [[термин]].
callout
Выделенные блоки .callout--* в markdown.
demo-класс
CSS-классы оболочки интерактивных демо и embed.
Маппинг
Сопоставление --d-* → --ifm-* в bridge.
Дизайн-токен
Именованная CSS-переменная палитры (--d-primary).
Наследование
Передача значений свойств от родителя к потомкам в CSS.
Согласование
Стыковка палитры, яркости и Infima (it-design-color-mode.css).
Типографика
Шрифты, размеры, интервалы текста статей.
Шрифт
--d-font, --ifm-font-family-base.
Заголовок
h1–h6 в .theme-doc-markdown.
Список
ul/ol в статьях — отступы в article-docs-prime.css.
Таблица
<table> в markdown — стили docs prime.
Горизонтальная линия
Элемент hr — отступы --it-doc-hr-gap.
Иконка
SVG в sidebar (mask) или tech icons в hero.
Маска
CSS mask-image для перекрашиваемых SVG-иконок sidebar.
Рельсы
Вертикальные линии навигации --it-explorer-rail.
Космические акценты
Тинты sidebar в dark mode (sidebar-cosmic-explorer.css).
Модальное окно
Overlay поиска DocSearch Ctrl+K.
Стиль блоков кода
it-design-code-overrides.css — Prism, pre, inline code.
override / переопределение
Принудительная замена стилей темы или Prism (!important, отдельный лист).
Локальные стили
CSS modules компонентов.
Коллизия
Конфликт имён классов; modules её избегают.
Хеширование
Суффикс в имени класса из CSS module при сборке.
webpack
Сборщик, обрабатывает CSS modules. См. config.
Сетка
Layout-система Infima (container, row, col).
bridge
it-design-bridge.css — мост токенов на Infima.
Явный выбор
Пользовательский light/dark вместо prefers-color-scheme.
query
Параметры URL — ?theme=light для iframe play.
iframe
Вложенное окно embed; тема через query.
brightness mode
Светлый/тёмный фон демо в play, без палитры сайта.
contrast
Контрастность текста и кода — проверять при новой палитре.
Тень
--d-shadow, --ifm-global-shadow-md.
Градиент
--d-hero-bg, --d-wide-gradient, callout-фоны.
localStorage
Хранение it-universe-design и ключей theme.
Сборка
npm run build включает все CSS в бандл.
Код
Исходники стилей и компонентов в src/.
Кастомный код
Всё в src/ поверх шаблона Docusaurus.
Связь с другими главами
- docusaurus.config.js —
customCss,it-design-theme-inject,colorMode. - Структура src/ — папка
css/,DesignThemePicker, clientModules. - TypeScript —
itDesignTheme.ts. - Компоненты — embed
themequery. - Архитектура — визуальная связка spirzen ↔ play.