@central-design-system/components 4.0.0-alpha.3 → 4.0.0-alpha.4

package/llms/llms-full.txt

@@ -1,6 +1,6 @@
 # Central Design System (CDS 4) — полная документация
 
-> Версия: 4.0.0-alpha.3
+> Версия: 4.0.0-alpha.4
 > Всё сразу: гайды, токены и темы, компоненты с примерами и контрактом API, миграция с CDS 3.
 > Сгенерировано автоматически (`bun run generate:meta` → `bun run generate:llms`). Не редактировать вручную.
 
@@ -421,16 +421,18 @@ ThemeDefinition (TS)  →  --cds-color-* / --cds-* (CSS-переменные)
 
 ## Подключение темы
 
-CDS 4 поставляет шесть готовых тем:
+CDS 4 поставляет восемь готовых тем:
 
-| Тема          | Описание                                    |
-| ------------- | ------------------------------------------- |
-| `cdsLight`    | светлая тема, используется по умолчанию      |
-| `cdsDark`     | тёмная тема                                  |
-| `b2bLight`    | светлая тема для приложений B2B-Center       |
-| `b2bDark`     | тёмная тема для приложений B2B-Center        |
-| `promoLight`  | светлая промо-тема                           |
-| `promoDark`   | тёмная промо-тема                            |
+| Тема          | Описание                                |
+| ------------- |-----------------------------------------|
+| `cdsLight`    | светлая тема, используется по умолчанию |
+| `cdsDark`     | тёмная тема                             |
+| `b2bLight`    | светлая тема для приложений B2B-Center  |
+| `b2bDark`     | тёмная тема для приложений B2B-Center   |
+| `lumaLight`   | светлая тема Luma                       |
+| `lumaDark`    | тёмная тема Luma                        |
+| `promoLight`  | светлая промо-тема                      |
+| `promoDark`   | тёмная промо-тема                       |
 
 > По умолчанию используется `cdsLight` — подключать её не нужно.
 
@@ -1339,6 +1341,801 @@ defineRender(() => (
 
 ---
 
+# Глобальная конфигурация
+
+CDS 4 позволяет задать значения пропсов по умолчанию — глобально, для конкретного компонента
+или только внутри определённого поддерева. Так вы один раз описываете «как выглядят кнопки
+в нашем продукте» и перестаёте дублировать одни и те же пропсы в каждом шаблоне.
+
+## Настройка
+
+Значения по умолчанию задаются опцией `defaults` в `createCds`. Ключ `global` действует на все
+компоненты, ключ с именем компонента — только на него.
+
+```ts
+import { createApp } from 'vue';
+import '@central-design-system/components/styles';
+import { createCds, components, directives } from '@central-design-system/components';
+
+import App from './App.vue';
+
+const cds = createCds({
+  components,
+  directives,
+  defaults: {
+    global: {
+      size: 'sm'
+    },
+    CdsButton: {
+      appearance: 'secondary'
+    },
+    CdsTextInput: {
+      hideDetails: 'auto'
+    }
+  }
+});
+
+createApp(App).use(cds);
+```
+
+**Важно.** Пропсы в `defaults` пишутся в camelCase: `hideDetails`, а не `hide-details`.
+
+Ключ компонента — это его имя из `defineOptions({ name })`, то есть `CdsButton`, `CdsTextInput`,
+`CdsCardActions` и так далее. Имена подкомпонентов (`CdsCardTitle`, `CdsListItem`) работают так же,
+как имена корневых.
+
+### Порядок разрешения значения
+
+Для каждого пропса CDS берёт первое подходящее значение:
+
+1. проп, явно переданный в шаблоне;
+2. `defaults.<ИмяКомпонента>.<проп>` из ближайшего контекста дефолтов;
+3. `defaults.global.<проп>`;
+4. значение по умолчанию, объявленное в самом компоненте.
+
+Явно переданный проп всегда выигрывает — дефолты не могут «перебить» шаблон.
+
+### Изменение дефолтов в рантайме
+
+`createCds` возвращает инстанс, у которого дефолты лежат в реактивной ссылке. Их можно менять
+на лету — все смонтированные компоненты пересчитаются:
+
+```ts
+const cds = createCds({ components, directives });
+
+// например, включить компактный режим по настройке пользователя
+cds.defaults.value = {
+  ...cds.defaults.value,
+  global: { size: 'sm' }
+};
+```
+
+## Контекстные дефолты
+
+Дефолты можно задать для компонентов, вложенных в другой компонент. Например, чтобы все кнопки
+внутри карточки по умолчанию были вторичными:
+
+```ts
+createCds({
+  defaults: {
+    CdsCard: {
+      CdsButton: { appearance: 'secondary' }
+    }
+  }
+});
+```
+
+Правило простое: ключ с заглавной буквы — это имя вложенного компонента, ключ со строчной —
+проп текущего компонента. Вложенность не ограничена одним уровнем:
+
+```ts
+createCds({
+  defaults: {
+    CdsCard: {
+      CdsCardActions: {
+        CdsButton: { appearance: 'tertiary', size: 'sm' }
+      }
+    }
+  }
+});
+```
+
+Тот же механизм библиотека использует внутри себя, чтобы группирующие компоненты раздавали
+свои настройки детям:
+
+- `CdsButtonGroup` задаёт вложенным `CdsButton` пропсы `appearance`, `color`, `baseColor`, `size`;
+- `CdsTagGroup` задаёт `CdsTag` пропсы `color`, `activeColor`, `disabled`, `filter`;
+- `CdsSelectionControlGroup` раздаёт настройки контролам, имя целевого компонента задаётся
+  пропом `defaultsTarget` (`CdsCheckbox`, `CdsRadio` и т. д.);
+- так же работают `CdsTabs`, `CdsSteps`, `CdsList`, `CdsBreadcrumbs`, `CdsButtonToggle`,
+  `CdsExpandablePanels`, `CdsOtpInput`.
+
+Поэтому `<CdsButtonGroup size="sm">` делает маленькими все кнопки внутри — вам не нужно
+проставлять `size` каждой.
+
+## Глобальные класс и стиль
+
+В дефолтах компонента, помимо пропсов, можно задать `class` и `style`. Это удобный способ
+навесить продуктовые правила на все экземпляры компонента, не трогая шаблоны:
+
+```ts
+createCds({
+  defaults: {
+    CdsButton: {
+      class: 'my-button'
+    }
+  }
+});
+```
+
+Работает любое значение, которое принимает Vue, — строка, объект, массив:
+
+```ts
+createCds({
+  defaults: {
+    CdsButton: {
+      style: [{ textTransform: 'none' }]
+    }
+  }
+});
+```
+
+В отличие от обычных пропсов, `class` и `style` не перезаписываются шаблоном, а **объединяются**
+с ним. То есть `<CdsButton class="mt-200">` получит и `my-button`, и `mt-200`.
+
+**Важно.** `class` и `style` работают только в ключе конкретного компонента. В `global` они
+игнорируются.
+
+## Алиасы
+
+Алиас — это тот же компонент, зарегистрированный под другим именем и со своими дефолтами.
+Из алиасов удобно собирать «продуктовые» варианты компонентов.
+
+```ts
+import { createCds, components, directives, CdsButton } from '@central-design-system/components';
+
+const cds = createCds({
+  components,
+  directives,
+  aliases: {
+    CdsButtonPrimary: CdsButton,
+    CdsButtonDanger: CdsButton
+  },
+  defaults: {
+    CdsButtonPrimary: {
+      appearance: 'primary',
+      class: 'my-button--primary'
+    },
+    CdsButtonDanger: {
+      appearance: 'primary',
+      color: 'red',
+      class: 'my-button--danger'
+    }
+  }
+});
+```
+
+Алиасы регистрируются глобально, поэтому в шаблоне их можно использовать сразу:
+
+```vue
+<template>
+  <CdsButtonPrimary>Сохранить</CdsButtonPrimary>
+  <CdsButtonDanger class="ml-200">Удалить</CdsButtonDanger>
+</template>
+```
+
+**Важно.** Алиас не наследует дефолты базового компонента. Если в конфигурации есть
+`defaults.CdsButton`, к `<CdsButtonPrimary>` они не применятся — дефолты ищутся по имени алиаса.
+Общие настройки для обоих выносите в `global` или дублируйте в ключе алиаса.
+
+## Дефолты для части приложения
+
+Чтобы задать дефолты не глобально, а в поддереве, используйте компонент `CdsDefaultsProvider`.
+На нём же построена панель Controls в Storybook: значения из панели применяются
+к компонентам примера как дефолты.
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsDefaultsProvider } from '@central-design-system/components';
+</script>
+
+<template>
+  <CdsDefaultsProvider :defaults="{ CdsButton: { appearance: 'tertiary', size: 'sm' } }">
+    <CdsButton>Второстепенная маленькая кнопка</CdsButton>
+  </CdsDefaultsProvider>
+</template>
+```
+
+| Проп       | Тип                 | Назначение                                                                                   |
+| ---------- | ------------------- | -------------------------------------------------------------------------------------------- |
+| `defaults` | `DefaultsOptions`   | Дефолты для поддерева; по умолчанию мержатся с унаследованными                                 |
+| `scoped`   | `boolean`           | Не смешивать с родительскими дефолтами — действуют только заданные здесь                        |
+| `reset`    | `number \| string`  | Подняться на N уровней вверх по цепочке дефолтов                                                |
+| `root`     | `boolean \| string` | Вернуться к корневым дефолтам из `createCds`; строкой — к именованной группе внутри них          |
+| `disabled` | `boolean`           | Ничего не провайдить — поддерево получает дефолты родителя как есть                              |
+
+Типичный сценарий `scoped` — «островок» в чужом окружении: вложенные группы (например,
+`CdsButtonGroup`) не должны навязывать свои настройки вашему блоку.
+
+## Свои компоненты
+
+Собственные компоненты приложения тоже могут участвовать в системе дефолтов. Для этого
+пропустите пропсы через `useDefaults`:
+
+```vue
+<script setup lang="ts">
+import { useDefaults } from '@central-design-system/components';
+
+const _props = defineProps<{ foo?: string }>();
+const props = useDefaults(_props, 'MyComponent');
+</script>
+
+<template>
+  <div>Я {{ props.foo }}</div>
+</template>
+```
+
+У `useDefaults` два аргумента, оба опциональные:
+
+- `props` — объект пропсов, возвращённый `defineProps`;
+- `name` — имя компонента, по которому ищется ключ в `defaults`. Если не передать, берётся имя
+  из `defineOptions({ name })`, а при его отсутствии — имя файла.
+
+Теперь компонент настраивается из общей конфигурации:
+
+```ts
+createCds({
+  defaults: {
+    MyComponent: { foo: 'бар' }
+  }
+});
+```
+
+**Важно.** В шаблоне обращайтесь к `props.foo`, а не к `foo`. `useDefaults` возвращает прокси
+над пропсами, и распакованные `defineProps` переменные его минуют:
+
+```diff
+-<div>Я {{ foo }}</div>
++<div>Я {{ props.foo }}</div>
+```
+
+### Вложенные дефолты в своих компонентах
+
+Чтобы ваш компонент раздавал дефолты детям (как это делает `CdsButtonGroup`), достаточно
+вызвать `useDefaults()` без аргументов — вложенные ключи из его секции `defaults` уйдут в
+дочерний контекст:
+
+```vue
+<script setup lang="ts">
+import { useDefaults } from '@central-design-system/components';
+
+useDefaults();
+</script>
+
+<template>
+  <div class="my-panel">
+    <slot />
+  </div>
+</template>
+```
+
+```ts
+createCds({
+  defaults: {
+    MyPanel: {
+      CdsButton: { appearance: 'tertiary' }
+    }
+  }
+});
+```
+
+Если дефолты детей зависят от пропсов компонента, используйте `provideDefaults` напрямую:
+
+```vue
+<script setup lang="ts">
+import { provideDefaults } from '@central-design-system/components';
+import { toRef } from 'vue';
+
+const props = defineProps<{ size?: 'sm' | 'md' }>();
+
+provideDefaults({
+  CdsButton: {
+    size: toRef(() => props.size)
+  }
+});
+</script>
+
+<template>
+  <div class="my-toolbar">
+    <slot />
+  </div>
+</template>
+```
+
+## Blueprint — пресет конфигурации
+
+Если один и тот же набор опций нужен нескольким приложениям, вынесите его в `blueprint`:
+это обычный объект опций `createCds`, на который сверху накладывается остальная конфигурация.
+
+```ts
+import { createCds, components, directives } from '@central-design-system/components';
+import type { Blueprint } from '@central-design-system/components';
+
+const productBlueprint: Blueprint = {
+  theme: { defaultTheme: 'b2bLight' },
+  defaults: {
+    CdsButton: { appearance: 'secondary' }
+  }
+};
+
+const cds = createCds({
+  blueprint: productBlueprint,
+  components,
+  directives,
+  // перекрывает значение из blueprint
+  defaults: {
+    CdsButton: { size: 'sm' }
+  }
+});
+```
+
+Опции сливаются глубоко (`mergeDeep`), поэтому в примере выше у кнопок останется
+`appearance: 'secondary'` из пресета и добавится `size: 'sm'`.
+
+---
+
+# Интернационализация (i18n)
+
+У компонентов CDS есть собственные тексты: «Отсутствуют данные» в селекте, подписи фильтров
+таблицы, `aria-label` кнопки закрытия, счётчик файлов. Все они идут через встроенный слой
+локализации, поэтому вы можете перевести их на другой язык, переопределить отдельную строку под
+свой продукт или переключать язык на лету — не переписывая компоненты.
+
+В библиотеку встроены два словаря — русский и английский. По умолчанию активен `ru`, поэтому без
+настройки всё уже на русском.
+
+## Настройка
+
+Локаль настраивается опцией `locale` в `createCds`. Переключиться на встроенный английский —
+одна строка, словари для этого передавать не нужно:
+
+```ts
+import { createApp } from 'vue';
+import '@central-design-system/components/styles';
+import { createCds, components, directives } from '@central-design-system/components';
+
+import App from './App.vue';
+
+const cds = createCds({
+  components,
+  directives,
+  locale: {
+    locale: 'en'
+  }
+});
+
+createApp(App).use(cds);
+```
+
+Языки, которых в библиотеке нет, добавляются словарём в `messages`:
+
+```ts
+import de from './locales/cds-de';
+
+createCds({
+  components,
+  directives,
+  locale: {
+    locale: 'de',
+    fallback: 'en',
+    messages: { de }
+  }
+});
+```
+
+| Опция              | Тип                       | Назначение                                                                    |
+| ------------------ | ------------------------- | ----------------------------------------------------------------------------- |
+| `locale`           | `string`                  | Активный язык; из коробки доступны `ru` (по умолчанию) и `en`                  |
+| `fallback`         | `string`                  | Язык, из которого берётся строка, если в активном её нет; по умолчанию `ru`    |
+| `messages`         | `LocaleMessages`          | Словари дополнительных языков; словарь одноимённого встроенного заменяется целиком |
+| `decimalSeparator` | `string`                  | Разделитель дробной части; по умолчанию выводится из активной локали           |
+| `rtl`              | `Record<string, boolean>` | Карта языков с письмом справа налево (см. [RTL](#rtl))                        |
+| `adapter`          | `LocaleInstance`          | Свой движок переводов вместо встроенного (см. [Свой адаптер](#свои-адаптер))   |
+
+Встроенные словари доступны и вам — они лежат в экспорте `locales`. Берите их за основу для
+своего языка или чтобы поправить пару строк:
+
+```ts
+import { locales } from '@central-design-system/components';
+
+locales.ru; // русский словарь
+locales.en; // английский словарь
+```
+
+Полный набор ключей — в разделе [Ключи сообщений](#ключи-сообщении).
+
+## Как компоненты берут текст
+
+Строки компонентов — это ключи с префиксом `$cds.`, которые библиотека прогоняет через функцию
+перевода. Часть ключей объявлена значениями пропсов по умолчанию, поэтому их видно в API:
+`text` у `CdsFileUpload` — `$cds.fileUpload.browse`, `closeLabel` у `CdsNotification` — `$cds.close`,
+`noDataText` у `CdsSelect` — `$cds.noDataText`.
+
+Отсюда три способа поменять текст.
+
+**Сменить язык целиком** — опцией `locale`:
+
+```ts
+createCds({ locale: { locale: 'en' } });
+```
+
+**Поменять надписи во всём продукте** — словарём поверх встроенного:
+
+```ts
+import { createCds, locales } from '@central-design-system/components';
+
+createCds({
+  locale: {
+    messages: {
+      ru: { ...locales.ru, noDataText: 'Ничего не нашлось' }
+    }
+  }
+});
+```
+
+**Важно.** Словарь языка заменяется целиком, а не сливается по ключам. Без спреда
+`...locales.ru` в русской локали останется один ключ, а остальные строки превратятся
+в свои же ключи (`$cds.close` вместо «Закрыть»). Вложенные секции спредьте отдельно:
+`table: { ...locales.ru.table, emptyText: '…' }`.
+
+**Поменять одну надпись в одном месте** — пропсом:
+
+```vue
+<CdsSelect :items="items" no-data-text="Подходящих поставщиков нет" />
+```
+
+Тот же проп можно задать значением по умолчанию для всех экземпляров компонента —
+см. глобальную конфигурацию:
+
+```ts
+createCds({
+  defaults: {
+    CdsSelect: { noDataText: 'Ничего не нашлось' }
+  }
+});
+```
+
+Функция перевода принимает и обычный текст: строка без префикса `$cds.` возвращается как есть,
+подставляя параметры. Так пропсы с локализуемым значением работают одинаково и с ключом,
+и с готовой фразой.
+
+Если ключа нет ни в активной локали, ни в `fallback`, компонент покажет сам ключ, а в dev-режиме
+в консоли появится предупреждение `[CDS: useLocale] Translation key … not found`.
+
+## Смена языка в рантайме
+
+`createCds` возвращает инстанс, у которого локаль лежит в реактивных ссылках — переключение
+языка достаточно записать в `current`:
+
+```ts
+const cds = createCds({ components, directives });
+
+// например, по выбору пользователя в настройках профиля
+cds.locale.current.value = 'en';
+```
+
+Внутри компонентов то же делает композабл `useLocale`:
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsButtonToggle, useLocale } from '@central-design-system/components';
+
+const { current } = useLocale();
+</script>
+
+<template>
+  <CdsButtonToggle v-model="current" appearance="tertiary">
+    <CdsButton value="ru" text="Русский" />
+    <CdsButton value="en" text="English" />
+  </CdsButtonToggle>
+</template>
+```
+
+Все смонтированные компоненты пересчитают свои строки сами — перезагрузка страницы не нужна.
+
+## Локаль для части приложения
+
+Отдельному поддереву можно задать свой язык — например, показать англоязычный виджет внутри
+русского интерфейса. Для этого в компоненте-обёртке вызовите `provideLocale`: он берёт локаль
+из контекста, накладывает переданные пропсы и провайдит результат детям.
+
+```vue
+<script setup lang="ts">
+import { provideLocale } from '@central-design-system/components';
+
+const props = defineProps<{ locale?: string; fallback?: string }>();
+
+provideLocale(props);
+</script>
+
+<template>
+  <div>
+    <slot />
+  </div>
+</template>
+```
+
+```vue
+<template>
+  <LocaleProvider locale="en">
+    <CdsSelect :items="items" />
+  </LocaleProvider>
+</template>
+```
+
+Не переданные пропсы наследуются от родительской локали, поэтому обёртка с одним `locale`
+не теряет ни `fallback`, ни словари.
+
+## useLocale
+
+Композабл отдаёт текущую локаль и её функции — используйте его в своих компонентах, чтобы их
+тексты жили в тех же словарях, что и тексты CDS.
+
+```vue
+<script setup lang="ts">
+import { useLocale } from '@central-design-system/components';
+
+const { t, n } = useLocale();
+</script>
+
+<template>
+  <p>{{ t('$cds.table.emptyText') }}</p>
+  <p>{{ n(1234.56) }}</p>
+</template>
+```
+
+| Свойство           | Тип                                            | Назначение                                                    |
+| ------------------ | ---------------------------------------------- | ------------------------------------------------------------- |
+| `t`                | `(key: string, ...params: unknown[]) => string` | Перевод ключа `$cds.…` с подстановкой параметров               |
+| `n`                | `(value: number) => string`                    | Форматирование числа по активной локали                        |
+| `current`          | `Ref<string>`                                  | Активный язык; запись меняет язык                              |
+| `fallback`         | `Ref<string>`                                  | Язык-подстраховка                                              |
+| `messages`         | `Ref<LocaleMessages>`                          | Словари; можно дописывать в рантайме                           |
+| `decimalSeparator` | `ShallowRef<string>`                           | Разделитель дробной части активной локали                      |
+
+Параметры в строках нумерованные — `{0}`, `{1}`:
+
+```ts
+const { t } = useLocale();
+
+t('$cds.carousel.delimiter', 3, 8); // «Слайд 3 из 8»
+t('Осталось дней: {0}', 5); // «Осталось дней: 5»
+```
+
+`n` под капотом — `Intl.NumberFormat` с активной локалью и `fallback`, так что разделители групп
+и дробной части приходят из браузера. `decimalSeparator` библиотека выводит из той же локали
+(`,` для `ru`, `.` для `en`); если в продукте принят другой — задайте его явно в `createCds`.
+
+## Даты
+
+Названия месяцев и дней недели живут в отдельных date-локалях: их везут `ru` и `en`. Компоненты
+даты и времени берут date-локаль по активному языку, поэтому после `current.value = 'en'` календарь
+переключится сам.
+
+Одному компоненту язык задаётся пропом `locale` — он есть у `CdsDatePicker`, `CdsDateInput`
+и `CdsTimePicker`:
+
+```vue
+<CdsDatePicker v-model="value" locale="en" :first-day-of-week="0" header />
+```
+
+Проп принимает не только имя языка, но и свой объект date-локали (тип `TDateLocale`) — так
+подключается язык, которого в библиотеке нет. Встроенные date-локали для сверки и переиспользования
+лежат в том же экспорте `locales`: `locales.ruDate`, `locales.enDate` и карта `locales.dateLocales`.
+
+```ts
+const de = {
+  days: 'Sonntag_Montag_Dienstag_Mittwoch_Donnerstag_Freitag_Samstag'.split('_'),
+  daysShort: 'So_Mo_Di_Mi_Do_Fr_Sa'.split('_'),
+  months: 'Januar_Februar_März_April_Mai_Juni_Juli_August_September_Oktober_November_Dezember'.split('_'),
+  monthsLong: 'Januar_Februar_März_April_Mai_Juni_Juli_August_September_Oktober_November_Dezember'.split('_'),
+  monthsShort: 'Jan_Feb_Mär_Apr_Mai_Jun_Jul_Aug_Sep_Okt_Nov_Dez'.split('_'),
+  today: 'Heute',
+  now: 'Jetzt',
+  firstDayOfWeek: 1,
+  format24h: true,
+  pluralDay: (day = 0) => (day === 1 ? 'Tag' : 'Tage')
+};
+```
+
+```vue
+<CdsDatePicker v-model="value" :locale="de" />
+```
+
+## Таблица
+
+`CdsTable` собирает свои подписи из ключей `$cds.table.*`, но принимает и точечное
+переопределение пропом `locale` — он перекрывает только переданные строки:
+
+```vue
+<CdsTable :columns="columns" :data="data" :locale="{ emptyText: 'Заявок пока нет' }" />
+```
+
+## RTL
+
+Языки с письмом справа налево описываются картой `rtl`: ключ — язык, значение — направление.
+
+```ts
+createCds({
+  locale: {
+    locale: 'ar',
+    messages: { ar },
+    rtl: { ar: true }
+  }
+});
+```
+
+Компоненты читают направление через `useRtl` и разворачивают то, что зависит от оси: сторону
+раскрытия меню и тултипов, стрелки пагинации, порядок ячеек `CdsOtpInput`, заливку
+`CdsProgressBar`. Отступы и границы в стилях в основном описаны логическими свойствами
+(`margin-inline`, `inset-inline`) и зеркалятся браузером сами — но полноценной поддержки RTL
+дизайн-система пока не заявляет, отдельные места потребуют доводки на вашей стороне.
+
+Атрибут направления библиотека за вас не проставляет — повесьте его на корень приложения сами:
+
+```vue
+<script setup lang="ts">
+import { useRtl } from '@central-design-system/components';
+
+const { isRtl } = useRtl();
+</script>
+
+<template>
+  <div :dir="isRtl ? 'rtl' : 'ltr'">
+    <slot />
+  </div>
+</template>
+```
+
+`useRtl` отдаёт `isRtl` и `rtlClasses` — готовый класс `cds-locale--is-rtl` / `cds-locale--is-ltr`
+для ваших собственных стилей.
+
+## Свой адаптер
+
+Если в приложении уже есть i18n-библиотека, отдайте переводы ей: опция `adapter` принимает любой
+объект, реализующий интерфейс `LocaleInstance`. Тогда `messages`, `locale` и `fallback` из
+`createCds` не используются — источником истины становится ваш движок, а строки CDS живут
+в общих словарях приложения под ключом `$cds`.
+
+```ts
+import type { LocaleInstance, LocaleOptions } from '@central-design-system/components';
+import { toRef } from 'vue';
+import type { I18n } from 'vue-i18n';
+
+export function createVueI18nAdapter(i18n: I18n<any, any, any, string, false>): LocaleInstance {
+  const format = (value: number) => i18n.global.n(value);
+
+  return {
+    name: 'vue-i18n',
+    current: i18n.global.locale,
+    fallback: i18n.global.fallbackLocale as never,
+    messages: i18n.global.messages as never,
+    decimalSeparator: toRef(() => (format(0.1).includes(',') ? ',' : '.')),
+    t: (key, ...params) => i18n.global.t(key, params as never),
+    n: format,
+    provide: () => createVueI18nAdapter(i18n)
+  };
+}
+```
+
+```ts
+import { createI18n } from 'vue-i18n';
+
+const i18n = createI18n({
+  legacy: false,
+  locale: 'ru',
+  messages: {
+    ru: {
+      $cds: { noDataText: 'Отсутствуют данные' },
+      profile: { title: 'Профиль' }
+    }
+  }
+});
+
+const cds = createCds({
+  components,
+  directives,
+  locale: {
+    adapter: createVueI18nAdapter(i18n)
+  }
+});
+```
+
+Обязательные члены `LocaleInstance`: `name` (по нему адаптер и распознаётся), `current`,
+`fallback`, `messages`, `decimalSeparator`, `t`, `n` и `provide` — фабрика вложенной локали
+для `provideLocale`. Если поддержка «локали в поддереве» вам не нужна, `provide` может возвращать
+тот же инстанс, как в примере выше.
+
+## Ключи сообщений
+
+Встроенный русский словарь — шаблон для перевода на новый язык. Скопируйте его, переведите
+значения и передайте в `messages` под ключом своего языка; его английская версия доступна как
+`locales.en`.
+
+```ts
+export default {
+  badge: 'Бейдж',
+  noDataText: 'Отсутствуют данные',
+  selectAll: 'Выбрать все',
+  close: 'Закрыть',
+  open: 'Открыть',
+  dismiss: 'Отклонить',
+  confirmEdit: {
+    ok: 'ОК',
+    cancel: 'Отмена'
+  },
+  carousel: {
+    prev: 'Предыдущий слайд',
+    next: 'Следующий слайд',
+    delimiter: 'Слайд {0} из {1}'
+  },
+  input: {
+    clear: 'Очистить {0}',
+    otp: 'Введите одноразовый код',
+    prependAction: '{0} предварительных действий',
+    appendAction: '{0} добавочных действий'
+  },
+  fileInput: {
+    counter: 'Файлов: {0}',
+    counterSize: 'Файлов: {0} ({1} всего)'
+  },
+  fileUpload: {
+    title: 'Перетащите файлы сюда',
+    divider: 'или',
+    browse: 'Выберите файлы'
+  },
+  steps: {
+    prev: 'Назад',
+    next: 'Далее'
+  },
+  table: {
+    filterTitle: 'Фильтр меню',
+    filterConfirm: 'Выбрать',
+    filterReset: 'Сброс',
+    filterEmptyText: 'Нет фильтров',
+    filterCheckAll: 'Выбрать все элементы',
+    filterSearchPlaceholder: 'Поиск фильтров',
+    emptyText: 'Нет данных',
+    selectAll: 'Выбрать текущую страницу',
+    selectInvert: 'Инвертировать текущую страницу',
+    selectNone: 'Очистить все данные',
+    selectionAll: 'Выбрать все данные',
+    sortTitle: 'Сортировка',
+    expand: 'Раскрыть строку',
+    collapse: 'Свернуть строку',
+    triggerDesc: 'Отсортировать по убыванию',
+    triggerAsc: 'Отсортировать по возрастанию',
+    cancelSort: 'Отменить сортировку',
+    showed: 'Отображено',
+    from: 'из',
+    rowOnPage: 'Строк на странице'
+  },
+  uploader: {
+    uploading: 'Загрузка...',
+    uploadFile: 'Загрузить файл',
+    downloadFile: 'Скачать файл',
+    removeFile: 'Удалить файл',
+    uploadError: 'Ошибка загрузки',
+    previewFile: 'Предпросмотр файла'
+  }
+};
+```
+
+Словарь можно оставить неполным: недостающие ключи возьмутся из `fallback`, то есть по умолчанию
+из русского.
+
+---
+
 # Темы и глобальные цветовые токены (уровень 2)
 
 > Сгенерировано из `src/themes/*.ts` скриптом `bun run generate:skill`. Не редактировать вручную.
@@ -1837,6 +2634,248 @@ const cds = createCds({ theme: { defaultTheme: 'cdsLight' } });
 | `--cds-color-brand-primary-active` | `#014F77` |
 | `--cds-color-brand-primary` | `#0287CA` |
 
+## lumaLight (светлая)
+
+| Токен | Значение |
+| --- | --- |
+| `--cds-color-surface-secondary` | `#ECEEF2` |
+| `--cds-color-surface-primary` | `#FFFFFF` |
+| `--cds-color-surface-overlay` | `#272A3080` |
+| `--cds-color-surface-inverse` | `#404653` |
+| `--cds-color-surface-elevated` | `#FFFFFF` |
+| `--cds-color-status-warning-surface` | `#A6840A` |
+| `--cds-color-status-warning-line` | `#B69210` |
+| `--cds-color-status-warning-fill-hover` | `#DEC048` |
+| `--cds-color-status-warning-fill` | `#F2DB82` |
+| `--cds-color-status-warning-content` | `#584001` |
+| `--cds-color-status-success-surface` | `#3C9C2C` |
+| `--cds-color-status-success-line` | `#50A946` |
+| `--cds-color-status-success-fill-hover` | `#97D283` |
+| `--cds-color-status-success-fill` | `#BCE8AB` |
+| `--cds-color-status-success-content` | `#005005` |
+| `--cds-color-status-progress-surface` | `#198FD8` |
+| `--cds-color-status-progress-line` | `#2B9DE9` |
+| `--cds-color-status-progress-fill-hover` | `#90C8FF` |
+| `--cds-color-status-progress-fill` | `#C3DFFF` |
+| `--cds-color-status-progress-content` | `#004871` |
+| `--cds-color-status-info-surface` | `#828A97` |
+| `--cds-color-status-info-line` | `#9298A4` |
+| `--cds-color-status-info-fill-hover` | `#C0C3CB` |
+| `--cds-color-status-info-fill` | `#DADDE2` |
+| `--cds-color-status-info-content` | `#404653` |
+| `--cds-color-status-indication-surface` | `#D1453F` |
+| `--cds-color-status-indication-line` | `#D1453F` |
+| `--cds-color-status-indication-fill-hover` | `#FFAE9E` |
+| `--cds-color-status-indication-fill` | `#FFD1C6` |
+| `--cds-color-status-indication-content` | `#831118` |
+| `--cds-color-status-danger-surface` | `#D1453F` |
+| `--cds-color-status-danger-line` | `#D1453F` |
+| `--cds-color-status-danger-fill-hover` | `#FFAE9E` |
+| `--cds-color-status-danger-fill` | `#FFD1C6` |
+| `--cds-color-status-danger-content` | `#831118` |
+| `--cds-color-page-primary` | `#ECEEF2` |
+| `--cds-color-other-teal-surface` | `#3A969E` |
+| `--cds-color-other-teal-line` | `#3CA5AD` |
+| `--cds-color-other-teal-fill-hover` | `#48D6DB` |
+| `--cds-color-other-teal-fill` | `#A1E9E9` |
+| `--cds-color-other-teal-content` | `#022B2F` |
+| `--cds-color-other-purple-surface` | `#A96FDE` |
+| `--cds-color-other-purple-line` | `#B381E1` |
+| `--cds-color-other-purple-fill-hover` | `#D6B8EF` |
+| `--cds-color-other-purple-fill` | `#E8D5F6` |
+| `--cds-color-other-purple-content` | `#2F0F50` |
+| `--cds-color-other-pink-surface` | `#D25CB8` |
+| `--cds-color-other-pink-line` | `#DB70C4` |
+| `--cds-color-other-pink-fill-hover` | `#F3ACE7` |
+| `--cds-color-other-pink-fill` | `#F8D1F2` |
+| `--cds-color-other-pink-content` | `#420D35` |
+| `--cds-color-other-lime-surface` | `#78922C` |
+| `--cds-color-other-lime-line` | `#85A12D` |
+| `--cds-color-other-lime-fill-hover` | `#B6CC65` |
+| `--cds-color-other-lime-fill` | `#D4E490` |
+| `--cds-color-other-lime-content` | `#202901` |
+| `--cds-color-other-lemon-surface` | `#8E8C23` |
+| `--cds-color-other-lemon-line` | `#9D9B25` |
+| `--cds-color-other-lemon-fill-hover` | `#CBC65F` |
+| `--cds-color-other-lemon-fill` | `#E6DF83` |
+| `--cds-color-other-lemon-content` | `#282601` |
+| `--cds-color-other-indigo-surface` | `#807EEC` |
+| `--cds-color-other-indigo-line` | `#918DEC` |
+| `--cds-color-other-indigo-fill-hover` | `#C3BDF9` |
+| `--cds-color-other-indigo-fill` | `#DDD9FC` |
+| `--cds-color-other-indigo-content` | `#1F1F55` |
+| `--cds-color-other-cyan-surface` | `#439786` |
+| `--cds-color-other-cyan-line` | `#48A692` |
+| `--cds-color-other-cyan-fill-hover` | `#58D8BE` |
+| `--cds-color-other-cyan-fill` | `#9FEBD8` |
+| `--cds-color-other-cyan-content` | `#052B24` |
+| `--cds-color-other-chocolate-surface` | `#AC7F58` |
+| `--cds-color-other-chocolate-line` | `#B78F6D` |
+| `--cds-color-other-chocolate-fill-hover` | `#D8BEA9` |
+| `--cds-color-other-chocolate-fill` | `#E7D9CC` |
+| `--cds-color-other-chocolate-content` | `#361D01` |
+| `--cds-color-line-tertiary-hover` | `#AFB3BD` |
+| `--cds-color-line-tertiary` | `#CCCFD6` |
+| `--cds-color-line-selected-hover` | `#2978D4` |
+| `--cds-color-line-selected` | `#4D98F9` |
+| `--cds-color-line-secondary-hover` | `#9298A4` |
+| `--cds-color-line-secondary` | `#AFB3BD` |
+| `--cds-color-line-primary-hover` | `#727987` |
+| `--cds-color-line-primary` | `#9298A4` |
+| `--cds-color-line-focus-outline` | `#A4C5FE` |
+| `--cds-color-line-focus` | `#4D98F9` |
+| `--cds-color-line-elevated` | `#FFFFFF00` |
+| `--cds-color-line-disable` | `#C0C3CB` |
+| `--cds-color-fill-selected-hover` | `#2978D4` |
+| `--cds-color-fill-selected` | `#4D98F9` |
+| `--cds-color-fill-secondary-hover` | `#CCCFD6` |
+| `--cds-color-fill-secondary-active` | `#C0C3CB` |
+| `--cds-color-fill-secondary` | `#DADDE2` |
+| `--cds-color-fill-primary-hover` | `#DADDE2` |
+| `--cds-color-fill-primary-active` | `#CCCFD6` |
+| `--cds-color-fill-primary` | `#FFFFFF` |
+| `--cds-color-fill-elevated` | `#FFFFFF` |
+| `--cds-color-fill-disable` | `#DADDE2` |
+| `--cds-color-content-tertiary` | `#727987` |
+| `--cds-color-content-secondary` | `#4F5666` |
+| `--cds-color-content-primary` | `#212631` |
+| `--cds-color-content-placeholder` | `#828A97` |
+| `--cds-color-content-on-dark` | `#FFFFFF` |
+| `--cds-color-content-link-visited` | `#955EC8` |
+| `--cds-color-content-link` | `#2978D4` |
+| `--cds-color-content-inverse` | `#FFFFFF` |
+| `--cds-color-content-disable` | `#9298A4` |
+| `--cds-color-brand-secondary-hover` | `#F7CFDA` |
+| `--cds-color-brand-secondary-border` | `#FBE7EC` |
+| `--cds-color-brand-secondary-active` | `#F0A8BC` |
+| `--cds-color-brand-secondary` | `#FBE7EC` |
+| `--cds-color-brand-primary-hover` | `#D2154B` |
+| `--cds-color-brand-primary-content` | `#7D0E27` |
+| `--cds-color-brand-primary-border` | `#C71B3C` |
+| `--cds-color-brand-primary-active` | `#E0476E` |
+| `--cds-color-brand-primary` | `#C71B3C` |
+
+## lumaDark (тёмная)
+
+| Токен | Значение |
+| --- | --- |
+| `--cds-color-surface-secondary` | `#33373F` |
+| `--cds-color-surface-primary` | `#272A30` |
+| `--cds-color-surface-overlay` | `#272A30CC` |
+| `--cds-color-surface-inverse` | `#DCDDE3` |
+| `--cds-color-surface-elevated` | `#33373F` |
+| `--cds-color-status-warning-surface` | `#C9A449` |
+| `--cds-color-status-warning-line` | `#BE9737` |
+| `--cds-color-status-warning-fill-hover` | `#8A6502` |
+| `--cds-color-status-warning-fill` | `#614301` |
+| `--cds-color-status-warning-content` | `#EADBBA` |
+| `--cds-color-status-success-surface` | `#6EBA66` |
+| `--cds-color-status-success-line` | `#5DAF55` |
+| `--cds-color-status-success-fill-hover` | `#1F7C22` |
+| `--cds-color-status-success-fill` | `#0D5512` |
+| `--cds-color-status-success-content` | `#CAE4C4` |
+| `--cds-color-status-progress-surface` | `#4DB1FF` |
+| `--cds-color-status-progress-line` | `#0EA4F8` |
+| `--cds-color-status-progress-fill-hover` | `#0172AC` |
+| `--cds-color-status-progress-fill` | `#014F77` |
+| `--cds-color-status-progress-content` | `#C7E0FF` |
+| `--cds-color-status-info-surface` | `#A5A9B2` |
+| `--cds-color-status-info-line` | `#989DA8` |
+| `--cds-color-status-info-fill-hover` | `#666C79` |
+| `--cds-color-status-info-fill` | `#454951` |
+| `--cds-color-status-info-content` | `#DCDDE3` |
+| `--cds-color-status-indication-surface` | `#FF9E92` |
+| `--cds-color-status-indication-line` | `#FF9E92` |
+| `--cds-color-status-indication-fill-hover` | `#B8423D` |
+| `--cds-color-status-indication-fill` | `#822825` |
+| `--cds-color-status-indication-content` | `#FFD2CC` |
+| `--cds-color-status-danger-surface` | `#FF9E92` |
+| `--cds-color-status-danger-line` | `#FF9E92` |
+| `--cds-color-status-danger-fill-hover` | `#B8423D` |
+| `--cds-color-status-danger-fill` | `#822825` |
+| `--cds-color-status-danger-content` | `#FFD2CC` |
+| `--cds-color-page-primary` | `#1A1A1A` |
+| `--cds-color-other-teal-surface` | `#0ABACE` |
+| `--cds-color-other-teal-line` | `#01ACBF` |
+| `--cds-color-other-teal-fill-hover` | `#007886` |
+| `--cds-color-other-teal-fill` | `#04525B` |
+| `--cds-color-other-teal-content` | `#D4F2F7` |
+| `--cds-color-other-purple-surface` | `#B79AF5` |
+| `--cds-color-other-purple-line` | `#AE8BEE` |
+| `--cds-color-other-purple-fill-hover` | `#8457B8` |
+| `--cds-color-other-purple-fill` | `#5E3882` |
+| `--cds-color-other-purple-content` | `#F3E9FE` |
+| `--cds-color-other-pink-surface` | `#E889D1` |
+| `--cds-color-other-pink-line` | `#E078C7` |
+| `--cds-color-other-pink-fill-hover` | `#AC4296` |
+| `--cds-color-other-pink-fill` | `#7A2869` |
+| `--cds-color-other-pink-content` | `#FDE6F6` |
+| `--cds-color-other-lime-surface` | `#9BB24D` |
+| `--cds-color-other-lime-line` | `#8DA63B` |
+| `--cds-color-other-lime-fill-hover` | `#5B7400` |
+| `--cds-color-other-lime-fill` | `#3D4F00` |
+| `--cds-color-other-lime-content` | `#EBEED8` |
+| `--cds-color-other-lemon-surface` | `#ABAE48` |
+| `--cds-color-other-lemon-line` | `#9DA235` |
+| `--cds-color-other-lemon-fill-hover` | `#6A7100` |
+| `--cds-color-other-lemon-fill` | `#484C01` |
+| `--cds-color-other-lemon-content` | `#EEEED9` |
+| `--cds-color-other-indigo-surface` | `#96A4FF` |
+| `--cds-color-other-indigo-line` | `#8B95F9` |
+| `--cds-color-other-indigo-fill-hover` | `#6362C5` |
+| `--cds-color-other-indigo-fill` | `#40428D` |
+| `--cds-color-other-indigo-content` | `#EBEBFF` |
+| `--cds-color-other-cyan-surface` | `#0ABEA3` |
+| `--cds-color-other-cyan-line` | `#0AB098` |
+| `--cds-color-other-cyan-fill-hover` | `#067A69` |
+| `--cds-color-other-cyan-fill` | `#005348` |
+| `--cds-color-other-cyan-content` | `#D5F3EB` |
+| `--cds-color-other-chocolate-surface` | `#D49E6D` |
+| `--cds-color-other-chocolate-line` | `#CA915C` |
+| `--cds-color-other-chocolate-fill-hover` | `#985E1F` |
+| `--cds-color-other-chocolate-fill` | `#6E3B01` |
+| `--cds-color-other-chocolate-content` | `#FAEADB` |
+| `--cds-color-line-tertiary-hover` | `#7A808E` |
+| `--cds-color-line-tertiary` | `#565D67` |
+| `--cds-color-line-selected-hover` | `#92BAFE` |
+| `--cds-color-line-selected` | `#5D9DFC` |
+| `--cds-color-line-secondary-hover` | `#989DA8` |
+| `--cds-color-line-secondary` | `#7A808E` |
+| `--cds-color-line-primary-hover` | `#B5B7C0` |
+| `--cds-color-line-primary` | `#989DA8` |
+| `--cds-color-line-focus-outline` | `#1159B5` |
+| `--cds-color-line-focus` | `#5D9DFC` |
+| `--cds-color-line-elevated` | `#828A9766` |
+| `--cds-color-line-disable` | `#666C79` |
+| `--cds-color-fill-selected-hover` | `#92BAFE` |
+| `--cds-color-fill-selected` | `#5D9DFC` |
+| `--cds-color-fill-secondary-hover` | `#565D67` |
+| `--cds-color-fill-secondary-active` | `#666C79` |
+| `--cds-color-fill-secondary` | `#454951` |
+| `--cds-color-fill-primary-hover` | `#454951` |
+| `--cds-color-fill-primary-active` | `#565D67` |
+| `--cds-color-fill-primary` | `#272A30` |
+| `--cds-color-fill-elevated` | `#7A808E` |
+| `--cds-color-fill-disable` | `#454951` |
+| `--cds-color-content-tertiary` | `#B5B7C0` |
+| `--cds-color-content-secondary` | `#CFD2D7` |
+| `--cds-color-content-primary` | `#ECECEF` |
+| `--cds-color-content-placeholder` | `#A5A9B2` |
+| `--cds-color-content-on-dark` | `#F9F9FC` |
+| `--cds-color-content-link-visited` | `#C0AEF8` |
+| `--cds-color-content-link` | `#92BAFE` |
+| `--cds-color-content-inverse` | `#1A1A1A` |
+| `--cds-color-content-disable` | `#989DA8` |
+| `--cds-color-brand-secondary-hover` | `#650B25` |
+| `--cds-color-brand-secondary-border` | `#8A1034` |
+| `--cds-color-brand-secondary-active` | `#8A1034` |
+| `--cds-color-brand-secondary` | `#3A0715` |
+| `--cds-color-brand-primary-hover` | `#8A1034` |
+| `--cds-color-brand-primary-content` | `#FFD9E1` |
+| `--cds-color-brand-primary-border` | `#D2154B` |
+| `--cds-color-brand-primary-active` | `#650B25` |
+| `--cds-color-brand-primary` | `#D2154B` |
+
 ## promoLight (светлая)
 
 | Токен | Значение |
@@ -41603,7 +42642,7 @@ function toggle(id: number) {
 Этот документ — **живой** migration guide: записи добавляются по мере появления
 breaking-изменений в alpha/beta релизах CDS 4.
 
-> Версии: CDS 3 — `3.10.1` (стабильная), CDS 4 — `4.0.0-alpha.3` (в разработке).
+> Версии: CDS 3 — `3.10.1` (стабильная), CDS 4 — `4.0.0-alpha.4` (в разработке).
 
 ## Как читать этот документ