Правила коммитов и сообщений собраны в файле commit-messages.md. Редакторские правила оформления и стандарты качества статей описаны в руководстве content-style-guide.md.
Основные настройки форматирования задаются в конфигурационных файлах eslint.config.js и .prettierrc.json. Требования линтеров ESLint, SonarJS и Stylelint являются обязательными, их локальный или глобальный обход через комментарии отключения правил запрещен. Предупреждения линтеров должны исправляться структурно через качественный код, например, с помощью мемоизации компонентов или вынесения булевых параметров в константы. Для автоматического форматирования и проверки кода используется команда yarn format, которая запускает компилятор TypeScript, а затем выполняет исправление стилей, кода и форматирования.
Для настройки интерактивных состояний используются семантические токены --color-interaction-* вместо локального указания цвета в SCSS. В светлой и темной темах базовый цвет смешивается с тоном --color-interaction-mix-color на процент смещения из --color-interaction-*-shift. Сила этих эффектов регулируется глобально. Тексты и ссылки используют прозрачности для наведения и активации, а для эффектов нажатия предназначен токен --color-interaction-ripple.
Цветовая схема строится по трехслойному принципу, включающему примитивный уровень базовых цветов тем, семантический уровень для поведения и состояний и компонентный уровень для зональных настроек вида --color-<zone>-<role>-<state>. Прямое указание цветовых моделей в SCSS-компонентах запрещено, кроме согласованных исключений. Канонический формат токенов включает обязательные состояния по типу обычного, наведенного, активного, отключенного, фокусного и других. Шкала важности реализуется через токены primary, secondary и tertiary на семантическом слое. Вложенность элементов настраивается токенами уровней от нуля до трех, при этом компоненты details и addition учитывают глубину вложенности для фонов и границ.
Радиусы скругления элементов базируются на переменной $roundness. Вложенные контентные уровни рассчитываются через множитель 0.75, а более плотные вложенные элементы используют множитель 0.5. Введение дополнительных прокси-переменных для текущего радиуса не рекомендуется.
Нецветовые значения импортируются из файла src/styles/abstracts/_tokens.scss, а в файле src/styles/abstracts/_mixins.scss остаются только переиспользуемые функции и примеси. Использование произвольных размеров для отступов и рамок не допускается, базовая сетка включает стандартные шаги от нуля до 64 пикселей. Длительности переходов задаются токенами duration, слои позиционирования настраиваются через переменные z-*, а тени определяются контекстными токенами для мягких, жестких и интерактивных вариантов. Размеры шрифтов привязываются к семантическим токенам от мелких подписей до крупных заголовков, при этом базовым размером текста является body-md со значением один рем.
Если стиль используется однократно, его допускается оставлять в виде inline-свойства. При повторении одинаковых свойств оформление выносится в общие SCSS-классы с семантическими именами. Связанные стили одного объекта группируются под общим префиксом по паттерну вложенности, что исключает разрозненные плоские селекторы.
.chat-rules {
&-container {
padding: 12px;
}
&-muted {
opacity: 0.7;
}
}Порядок импорта в файлах статей src/pages/sections/**/*.tsx предполагает сначала библиотеки и React, затем контентные компоненты проекта, а после них локальные стили и утилиты. Пустые строки между группами обязательны, пути пишутся относительно без использования алиасов.
import React from "react";
import {Divider} from "antd";
import Addition from "../../../components/content/Addition";
import {ArticleMedia} from "../../../components/content/ArticleMedia";
import DetailsSummary from "../../../components/detailsSummary/DetailsSummary";React-компоненты и файлы с расширением .tsx именуются в формате PascalCase, а утилиты, хуки и файлы TypeScript используют camelCase. Интерфейсы пропсов получают обязательный суффикс Properties. Компоненты в проекте описываются как функциональные компоненты React.FC.
Верстка статей в src/pages/sections/** требует использования корневого контейнера с классом article-content, а каждый вопрос выделяется в отдельный спойлер с осмысленным заголовком и стабильным латинским якорем. Для повторяющегося текста используются ссылки на существующие якоря.
Ссылки в статьях оформляются так, чтобы в теге <a> оставалось только слово «этой», а остальные слова выносились за пределы тега.
Перед созданием новых элементов проверяется наличие готовых компонентов Addition, ArticleMedia, CodeSnippet, ContentFilter, NestedDetailsSummary и HostsAdobeModal. Если задача решается существующим компонентом, его логику не следует дублировать в JSX вручную.
Для прикладных инструментов используются функциональные компоненты SearchEngine, EasingEditor, ConverterJsonToTgs и ConverterTgsToJson. Их описание находится в файле components-features.md.
При добавлении таймеров, дебаунсов, подписок или слушателей событий в React-компонентах всегда реализуйте их очистку в функции возврата хука useEffect. В SCSS-модулях с расширением *.module.scss переопределение глобальных стилей через :global не рекомендуется, а в логических функциях применяется ранний возврат. Перемещение файлов осуществляется командой git mv.
Вся техническая документация в каталоге docs/ оформляется в едином стиле сплошного связного повествования на русском языке. Использование любых маркированных или нумерованных списков в текстовом описании запрещено, любые перечисления и шаги должны быть сформулированы в виде предложений в составе обычных абзацев.
Для обеспечения удобства чтения плотный текст обязательно разделяется на короткие логические абзацы по два, три или четыре предложения. Каждый абзац должен отделяться от соседних пустой строкой. Любые технические параметры, примеры кода или команды оформляются в виде стандартных блоков кода, а при упоминании смежных файлов документации или ключевых файлов проекта обязательно проставляются перекрестные ссылки.
Этот документ определяет только правила кода и структуры файлов. За качество текстов и редактуру отвечают соответствующие руководства по стилю и качеству статей. Проверка изменений включает успешное выполнение команды yarn format, правильное расположение файлов в каталогах разделов и отсутствие дублирования логики существующих компонентов.