Branding и тема

Branding отвечает за title/label/logo/favicons/mode/size. Настройки settings.theme (светлая, тёмная или системная схема), modal_blur и ui_radius принимают только значения из списка. Читатель может переопределить в панели только тему; размытие и закругление задаёт автор.

{
  "branding": {"title": "Docara", "mode": "compact", "size": "large", "logo": "assets/docara-mark.svg", "favicon": "assets/favicon.ico"},
  "settings": {"theme": "system", "modal_blur": "none", "ui_radius": "default"}
}

ui_radius выбирает Framework-owned CSS variable --sf-radius--ui: compact/default/comfortable меняют один токен, а components используют свои variables с fallback на него. modal_blur=none убирает backdrop blur поиска и настроек по умолчанию. Произвольный CSS из config не принимается: theme принимает только цвет, а стили строит Framework.

Цвета сайта из одного цвета

Ключ theme в docara.json задаёт основной цвет сайта, остальные цвета Docara получает из него:

{
  "theme": {"color": "#0a7d4f"}
}

При сборке Docara передаёт цвет генератору темы SIMAI Framework (SF.ThemePalette, тот же расчёт, что у компонента sf-theme-generator). Генератор строит восемь тональных палитр: основную, вторичную, дополнительную, нейтральную, ошибки, предупреждения, успеха и информации, по 16 тонов в каждой, — 128 переменных --sf-<палитра>-<тон>, — и 98 их полупрозрачных оттенков --sf-<палитра>-<тон>--alfa-<n>, всего 226 переменных. Из них Framework берёт все семантические цвета (--sf-primary, --sf-surface, --sf-outline и другие), поэтому кнопки, ссылки, фон и рамки меняются в светлой и тёмной схеме сразу. Примеры в рамках получают те же цвета вместе с остальными токенами страницы.

• color — обязательный, #rgb или #rrggbb, регистр не важен.
• hue (0–360) и chroma (0–150) — необязательные, это тон и насыщенность генератора, как в полях «Тонкая настройка» sf-theme-generator. Заданные, они важнее того, как прочитан цвет. Если сайт хранит выбор из sf-theme-generator, перенесите в theme все три значения: value как color, hue и chroma.
• Без ключа theme сайт использует собственные цвета Framework, и сборка совпадает со сборкой без этой настройки байт в байт.

Основной тон палитры не обязан совпасть с выбранным цветом: генератор берёт у цвета тон и насыщенность и строит палитру по своим правилам. Для #0a7d4f основной цвет светлой схемы (--sf-primary-40) получается #006d44.

Полупрозрачные оттенки дают заливки контейнеров, тональные кнопки и фон при наведении или выборе, поэтому и они следуют выбранному цвету.

Тема общая для всего сайта и задаётся только в docara.json, не в section.json и не на странице. Не путайте её с settings.theme: там выбирается светлая или тёмная схема, а theme задаёт сами цвета.

Сборка публикует тему одним файлом _docara/docara-theme.<sha256>.css, который каждая страница подключает после своих стилей первого экрана. Ссылку на этот файл и всё, что нужно для проверки, сборка записывает в resolved-page-plans.json (раздел build.theme), а docara verify-static проверяет, что файл совпадает с записью, содержит только эти переменные (тона и их полупрозрачные оттенки) и подключён на каждой странице.

Ошибки:

• THEME_COLOR_INVALID — color не #rgb и не #rrggbb, например "green" или "#0a7d4";
• THEME_HUE_INVALID, THEME_CHROMA_INVALID — число вне диапазона;
• THEME_FRAMEWORK_UNSUPPORTED — в simai-framework.lock.json закреплён релиз Framework без генератора темы. Замените lock на vendor/simai/docara/stubs/portable/simai-framework.lock.json;
• PORTABLE_INCREMENTAL_THEME_CHANGED — после смены цвета пересобирается одна страница (build --page). Соберите сайт целиком: остальные страницы ссылаются на прежнюю тему.