SASS-переменные

Стили CDS 4 написаны на SASS/SCSS, и часть внутренних настроек — базовый reset, глобальная типографика, шрифт, сетка и брейкпоинты — вынесена в SASS-переменные с флагом !default. Их можно переопределить при сборке приложения через стандартный механизм конфигурации модулей: @use '…' with (…).

SASS-переменные — компайл-тайм слой настройки. Цвета, отступы и остальные дизайн-токены компонентов живут в CSS-переменных (--cds-*) и настраиваются темами в рантайме — см. Тематизацию. Начинайте с темы; к SASS-переменным спускайтесь, когда нужно поменять именно базовый слой: reset, типографику, сетку.

Установка

Vite компилирует SCSS из коробки — нужен только сам препроцессор:

npm

npm install -D sass-embedded

pnpm

pnpm add -D sass-embedded

yarn

yarn add -D sass-embedded

bun

bun add -d sass-embedded

Подойдёт и классический sass, но sass-embedded заметно быстрее. Для ускорения больших сборок укажите современный API компилятора:

// vite.config.ts
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: { api: 'modern-compiler' }
    }
  }
});

Подключение с конфигурацией

Обычно базовые стили подключаются готовым CSS — import '@central-design-system/components/styles'. Чтобы переопределить SASS-переменные, замените этот импорт на собственный SCSS-файл: точка входа @central-design-system/components/styles в SCSS резолвится в исходники базового слоя (экспорт-условие sass в package.json), и конфигурация применяется при компиляции.

// main.ts
import { createApp } from 'vue';

- import '@central-design-system/components/styles';
+ import './styles/main.scss';

// src/styles/main.scss
@use '@central-design-system/components/styles' with (
  $reset: false,
  $body-font-family: ('Inter', sans-serif)
);

Стили самих компонентов при этом ничего дополнительно не требуют: они прекомпилированы и приезжают вместе с JS-чанками компонентов — как при точечной, так и при полной регистрации (см. Tree-shaking).

Значение с запятыми — например, $body-font-family из нескольких шрифтов — оборачивайте в скобки, иначе SASS разберёт его как несколько аргументов.

Файл настроек

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

// src/styles/settings.scss
@forward '@central-design-system/components/styles/settings' with (
  $body-font-family: ('Inter', sans-serif),
  $grid-gutter: 24px
);

// src/styles/main.scss
@use './settings'; // конфигурирует переменные CDS
@use '@central-design-system/components/styles'; // база собирается уже с ними

<!-- Component.vue -->
<style lang="scss">
@use '@/styles/settings' as s;

.card {
  gap: s.$grid-gutter;
  font-family: s.$body-font-family;
}
</style>

Каждый <style>-блок компилируется отдельно, поэтому «настроить в main.scss и читать напрямую из пакета» не сработает — прямой @use '@central-design-system/components/styles/settings' в компоненте вернул бы значения по умолчанию. Общий файл настроек гарантирует одинаковые значения во всех точках компиляции.

Вход styles/settings содержит только переменные и не эмитит ни байта CSS — его можно безопасно подключать в любом количестве файлов.

Глобальные переменные

Переменная	По умолчанию	Что делает
$reset	true	Эмитить CSS-reset базового слоя
$legacy-reset	false	Reset для совместимости с разметкой CDS 3
$enable-typography	true	Глобальная типографика (h1–h6, .h1–.h6 и т.д.)
$body-font-family	var(--cds-font-family), 'PT Root UI VF', …	Шрифт body
$font-size-root	var(--cds-base-unit) (16px)	Корневой размер шрифта
$line-height-root	1.5	Корневой межстрочный интервал
$border-color-root	transparent	Цвет рамок по умолчанию
$border-style-root	solid	Стиль рамок по умолчанию
$border-radius-root	var(--cds-border-radius-200)	Базовый радиус скругления
$size-scale	4px	Шаг шкалы размеров
$sizes	('xs', 'sm', 'md', 'lg', 'xl')	Имена размеров
$rounded	карта	Шкала скруглений (sm, md, lg, xl, pill, circle, …)

Сетка и брейкпоинты

Переменная	По умолчанию	Что делает
$prefix	'cds'	Префикс CSS-классов сетки
$flex-grid-columns	16	Число колонок flex-сетки (поддерживается и 12)
$grid-gutter	32px	Гаттер сетки
$grid-gutter-condensed	1px	Гаттер уплотнённой сетки
$grid-breakpoints	карта	Брейкпоинты: ширина, колонки и отступы для xs–xl

Грид-переменные входят в тот же модуль настроек, а миксины брейкпоинтов и сетки живут в отдельном входе styles/breakpoints — он тоже не эмитит CSS:

@use '@/styles/settings' as s;
@use '@central-design-system/components/styles/breakpoints' as bp;

.sidebar {
  gap: s.$grid-gutter;

  @include bp.cds-breakpoint-up('md') {
    width: 320px;
  }
}

SASS-брейкпоинты влияют на ваши стили и миксины сетки. Рантайм-брейкпоинты useDisplay настраиваются отдельно — опцией display в createCds (см. Display и Platform). По умолчанию оба набора совпадают; меняя один, не забудьте про второй.

Переменные компонентов и vite-plugin

Через @use … with без плагина настраивается только базовый слой: CSS компонентов прекомпилирован. Плагин @central-design-system/vite-plugin снимает это ограничение — он перекомпилирует стили каждого используемого компонента с вашим файлом настроек:

// vite.config.ts
import cds from '@central-design-system/vite-plugin';

export default defineConfig({
  plugins: [
    vue(),
    cds({ styles: { configFile: 'src/styles/settings.scss' } })
  ]
});

Файл настроек тот же, но форвардить нужно styles/component-settings — агрегат, включающий и глобальные, и компонентные переменные:

// src/styles/settings.scss
@forward '@central-design-system/components/styles/component-settings' with (
  $border-radius-root: 0,          // глобальная
  $button-border-radius: 9999px    // компонентная
);

С плагином импорт @central-design-system/components/styles в main.ts менять не нужно — он сам начинает означать «сконфигурированный базовый слой», а стили компонентов пересобираются на лету. Плагин также умеет авто-импорт компонентов из шаблонов (autoImport: true по умолчанию) — регистрация в createCds({ components }) становится необязательной.

Что нельзя настроить через SASS

• Локальные переменные компонентов ($button-border-radius и подобные из styles/_CdsX.variables.scss). Без плагина недоступны: CSS компонентов публикуется прекомпилированным, поэтому их локальные переменные фиксированы на момент сборки библиотеки. С @central-design-system/vite-plugin настраиваются через styles/component-settings — плагин перекомпилирует опубликованные SCSS-исходники компонентов с вашим файлом настроек (см. выше).
• Отключение отдельных утилити-классов. Вместо карты-переключателя выбирайте вход по составу: styles/core — только слои, шрифты и reset; styles/common — плюс типографика и хелперы.
• CSS-слои. @layer cds-* включены всегда: порядок слоёв объявляется в базовом слое стилей, и обычный CSS приложения (вне @layer) всегда побеждает стили дизайн-системы — отключать здесь нечего.

Подводные камни

• Только переменные в файле настроек. Любые стили или импорты обычных стилевых файлов в settings.scss продублируются в каждом файле, который его подключает. Стили — в main.scss, в настройках — переменные, миксины, функции.
• Конфигурация — до первой загрузки модуля. @use … with упадёт с ошибкой module was already loaded, если модуль настроек уже был загружен без конфигурации выше по цепочке. Подключайте файл настроек первым.
• Скорость сборки. С готовым CSS ничего компилировать не нужно; с конфигурацией базовый слой собирается вместе с приложением. Объём небольшой, но на холодных сборках разница заметна — sass-embedded и api: 'modern-compiler' сводят её к минимуму.
• Резолв рассчитан на бандлер. Bare-импорты вида @use '@central-design-system/components/styles' резолвят Vite и webpack (sass-loader) через экспорт-условие sass. В чистом sass CLI без бандлера пути придётся указывать до файлов в node_modules вручную.