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

package/llms/llms-full.txt

@@ -1,6 +1,6 @@
 # Central Design System (CDS 4) — полная документация
 
-> Версия: 4.0.0-alpha.2
+> Версия: 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 (светлая)
 
 | Токен | Значение |
@@ -22304,6 +23343,517 @@ function onUpdateModelValue(value: boolean, id: number) {
 
 ---
 
+# CdsOtpInput
+
+_Категория: Controls · появился в 4.0.0 · статус: new_
+
+Поле ввода одноразового кода — из SMS, письма или приложения-аутентификатора. Внешне это ряд отдельных ячеек, но ввод принимает один скрытый `input`: поэтому работают автозаполнение кода из SMS, вставка целой строкой из буфера, выделение и стрелки, а фокус не приходится перепрыгивать между ячейками вручную.
+
+**Смотрите также:** Для обычного короткого текста или числа возьмите CdsTextInput: `CdsOtpInput` нужен там, где длина ввода известна заранее и каждый символ показывается отдельной ячейкой.
+
+## Анатомия
+
+Ячейки (`CdsOtpField`) только рисуют код — введённый символ, заполнитель или
+мигающую каретку. Настоящий ввод принимает скрытый `input`: он прижат к нижнему
+краю компонента, поэтому подсказка автозаполнения из SMS появляется под ячейками
+и ничего не перекрывает. Между ячейками может стоять разделитель
+(`CdsOtpSeparator`), а в слитном виде ячейки собираются в группу (`CdsOtpGroup`).
+
+**Пример — `Anatomy.vue`:**
+
+```vue
+<script setup lang="ts">
+import AnatomyDemo from '@cds/utils/docs/AnatomyDemo.vue';
+import { CdsOtpInput } from '@central-design-system/components';
+
+// Схема 1: обычный ряд — ячейки и разделители между ними
+const fieldsMarkers = [
+  { selector: '.cds-otp-input__content', label: 'Ряд ячеек', side: 'right' as const },
+  { selector: '.cds-otp-field', label: 'Ячейка (CdsOtpField)', side: 'top' as const },
+  { selector: '.cds-otp-separator', label: 'Разделитель (CdsOtpSeparator)', side: 'bottom' as const },
+  { selector: '.cds-otp-field__placeholder', label: 'Символ-заполнитель', side: 'bottom' as const }
+];
+
+// Схема 2: слитный вид — ячейки собраны в общую группу
+const mergedMarkers = [
+  { selector: '.cds-otp-field', label: 'Ячейка (CdsOtpField)', side: 'top' as const },
+  { selector: '.cds-otp-group', label: 'Группа (CdsOtpGroup)', side: 'bottom' as const }
+];
+</script>
+
+<template>
+  <div class="flex flex-col gap-600">
+    <AnatomyDemo :markers="fieldsMarkers">
+      <CdsOtpInput model-value="12" divider="-" placeholder="0" />
+    </AnatomyDemo>
+
+    <AnatomyDemo :markers="mergedMarkers">
+      <CdsOtpInput model-value="12" merged />
+    </AnatomyDemo>
+  </div>
+</template>
+```
+
+## Вариации
+
+### Длина и тип кода
+
+Свойство `length` задаёт число ячеек, `type` — что можно вводить: `number`
+(по умолчанию) принимает только цифры и открывает цифровую клавиатуру на
+мобильных, `text` — любые символы, `password` дополнительно скрывает введённое
+точками. Тот же эффект без смены типа даёт `masked`.
+
+**Пример — `LengthAndType.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput :length="4" model-value="1234" />
+    <CdsOtpInput type="text" model-value="AB12CD" />
+    <CdsOtpInput type="password" model-value="123456" />
+  </div>
+</template>
+```
+
+### Допустимые символы
+
+Свойство `pattern` сужает набор символов: имя готового набора (`numeric`,
+`alpha`, `alphanumeric`, `unicode-alpha`, `unicode-alphanumeric`) или своё
+регулярное выражение. Проверка идёт посимвольно — лишние символы не попадут в
+поле ни с клавиатуры, ни из буфера обмена.
+
+**Пример — `Pattern.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput type="text" pattern="alpha" :length="4" placeholder="A" />
+    <CdsOtpInput type="text" pattern="alphanumeric" placeholder="X" />
+    <CdsOtpInput type="text" :pattern="/[0-9A-F]/" placeholder="F" />
+  </div>
+</template>
+```
+
+### Разделитель
+
+Свойство `divider` ставит символ между ячейками — например, дефис в коде вида
+`123-456`. Слот `divider` даёт полную свободу разметки и получает `index` —
+номер ячейки слева от разделителя, так что разделитель можно поставить только
+в нужном месте.
+
+**Пример — `Divider.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsIcon, CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput divider="-" model-value="123456" />
+
+    <CdsOtpInput model-value="123456">
+      <template #divider="{ index }">
+        <CdsIcon v-if="index === 2" name="minus" size="sm" />
+      </template>
+    </CdsOtpInput>
+  </div>
+</template>
+```
+
+### Слитный вид
+
+Свойство `merged` убирает промежутки: ячейки становятся одним полем с общей
+рамкой. Такой вид компактнее и меньше дробит форму.
+
+**Пример — `Merged.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsOtpInput merged model-value="1234" />
+  </div>
+</template>
+```
+
+### Заполнитель
+
+Свойство `placeholder` показывает символ в пустых ячейках — подсказку формата
+или просто точку, чтобы ряд не выглядел пустым.
+
+**Пример — `Placeholder.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput placeholder="0" />
+    <CdsOtpInput placeholder="•" />
+  </div>
+</template>
+```
+
+### Размеры
+
+Свойство `size` меняет высоту ячеек и размер шрифта. Размер по умолчанию — `md`.
+
+**Пример — `Sizes.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+
+const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput v-for="size of sizes" :key="size" :size="size" :length="4" model-value="1234" />
+  </div>
+</template>
+```
+
+### Состояния
+
+`disabled` блокирует ввод, `error` подсвечивает весь ряд ошибкой, `loading`
+показывает индикатор поверх ячеек и не стирает набранный код. `focus-all`
+подсвечивает весь ряд, пока поле в фокусе, а не только активную ячейку.
+
+**Пример — `States.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-400">
+    <CdsOtpInput :length="4" model-value="12" disabled />
+    <CdsOtpInput :length="4" model-value="1234" error />
+    <CdsOtpInput :length="4" model-value="1234" loading />
+    <CdsOtpInput :length="4" model-value="12" focus-all />
+  </div>
+</template>
+```
+
+### Слоты
+
+| Слот      | Описание                                                                      |
+| :-------- | :---------------------------------------------------------------------------- |
+| `fields`  | Ряд ячеек целиком — своя разметка из `CdsOtpGroup`, `CdsOtpField` и `CdsOtpSeparator` |
+| `divider` | Разделитель между ячейками, `index` — номер ячейки слева от него               |
+| `loader`  | Свой индикатор загрузки (при `loading`)                                        |
+| `default` | Произвольный контент поверх ячеек                                              |
+
+Слот `fields` нужен, когда ячейки собираются в группы: каждая `CdsOtpField`
+получает свой `index`, а `CdsOtpGroup` объединяет соседние ячейки в общую рамку.
+
+**Пример — `CustomFields.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpField, CdsOtpGroup, CdsOtpInput, CdsOtpSeparator } from '@central-design-system/components';
+</script>
+
+<template>
+  <div class="flex justify-center">
+    <CdsOtpInput model-value="123456">
+      <template #fields>
+        <CdsOtpGroup merged>
+          <CdsOtpField v-for="index of [0, 1, 2]" :key="index" :index="index" />
+        </CdsOtpGroup>
+
+        <CdsOtpSeparator>—</CdsOtpSeparator>
+
+        <CdsOtpGroup merged>
+          <CdsOtpField v-for="index of [3, 4, 5]" :key="index" :index="index" />
+        </CdsOtpGroup>
+      </template>
+    </CdsOtpInput>
+  </div>
+</template>
+```
+
+## Рекомендации
+
+| ✅ Хорошо | ❌ Плохо |
+| --- | --- |
+| Число ячеек равно длине кода — пользователь сразу видит, сколько символов вводить. | Лишние ячейки заставляют гадать, весь ли код набран. |
+| Код целиком набирается в одном поле: вставка из буфера и автозаполнение из SMS работают. | Отдельные текстовые поля ломают вставку кода и заставляют вручную перепрыгивать фокус. |
+| При ошибке поле остаётся доступным, а текст рядом говорит, что делать дальше. | Заблокированное поле без объяснения не даёт исправить код. |
+
+## Сценарии использования
+
+### Подтверждение по SMS
+
+Событие `finish` срабатывает, как только код набран целиком, — отправляйте
+запрос по нему, отдельная кнопка не нужна. На время проверки включите `loading`:
+код остаётся на экране, а поле не выглядит сломанным. Если сервер не принял код,
+`error` подсвечивает ряд, а методы `reset()` и `focus()` через ref очищают поле
+и возвращают в него курсор.
+
+**Пример — `SmsConfirmation.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsOtpInput } from '@central-design-system/components';
+import { ref } from 'vue';
+
+const otpRef = ref<InstanceType<typeof CdsOtpInput>>();
+
+const code = ref('');
+const loading = ref(false);
+const status = ref<'idle' | 'success' | 'error'>('idle');
+
+// Имитация проверки кода на сервере: верный код — 123456
+function onFinish(value: string) {
+  loading.value = true;
+  status.value = 'idle';
+
+  setTimeout(() => {
+    loading.value = false;
+    status.value = value === '123456' ? 'success' : 'error';
+
+    if (status.value === 'error') {
+      otpRef.value?.reset();
+      otpRef.value?.focus();
+    }
+  }, 1000);
+}
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-300">
+    <p class="text-200 text-content-secondary">Код отправлен на +7 999 000-00-00</p>
+
+    <CdsOtpInput
+      ref="otpRef"
+      v-model="code"
+      :loading="loading"
+      :error="status === 'error'"
+      @finish="onFinish"
+      @update:model-value="status = 'idle'"
+    />
+
+    <p v-if="status === 'success'" class="text-200 text-status-success-content">Код подтверждён</p>
+    <p v-else-if="status === 'error'" class="text-200 text-status-danger-content">
+      Код неверный — введите последние цифры из SMS ещё раз
+    </p>
+    <p v-else class="text-200 text-content-tertiary">Введите 123456, чтобы увидеть подтверждение</p>
+  </div>
+</template>
+```
+
+### Повторная отправка кода
+
+Кнопка «Отправить снова» открывается по таймеру — так пользователь не завалит
+запросами шлюз. Вместе с новым кодом сбрасывайте поле: `reset()` очищает ячейки,
+`focus()` ставит курсор в первую, и старый код не смешивается с новым.
+
+**Пример — `ResendCode.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsOtpInput } from '@central-design-system/components';
+import { onScopeDispose, ref } from 'vue';
+
+const otpRef = ref<InstanceType<typeof CdsOtpInput>>();
+
+const code = ref('');
+const seconds = ref(15);
+
+let timer: ReturnType<typeof setInterval> | undefined;
+
+function countdown() {
+  clearInterval(timer);
+
+  timer = setInterval(() => {
+    seconds.value -= 1;
+
+    if (seconds.value <= 0) clearInterval(timer);
+  }, 1000);
+}
+
+function resend() {
+  seconds.value = 15;
+  countdown();
+
+  otpRef.value?.reset();
+  otpRef.value?.focus();
+}
+
+countdown();
+onScopeDispose(() => clearInterval(timer));
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-300">
+    <CdsOtpInput ref="otpRef" v-model="code" placeholder="•" />
+
+    <CdsButton
+      appearance="tertiary"
+      size="sm"
+      :disabled="seconds > 0"
+      :text="seconds > 0 ? `Отправить снова через ${seconds} с` : 'Отправить код снова'"
+      @click="resend"
+    />
+  </div>
+</template>
+```
+
+### Код в форме
+
+Когда код — часть формы входа, оставьте кнопку подтверждения: она даёт явный
+момент отправки. Кнопка ждёт, пока набраны все символы, — длину кода видно из
+`v-model`, а `disabled` на поле фиксирует уже подтверждённый код.
+
+**Пример — `TwoFactorForm.vue`:**
+
+```vue
+<script setup lang="ts">
+import { CdsButton, CdsForm, CdsOtpInput } from '@central-design-system/components';
+import { computed, ref } from 'vue';
+
+const code = ref('');
+const loading = ref(false);
+const confirmed = ref(false);
+
+const isComplete = computed(() => code.value.length === 6);
+
+function submit() {
+  loading.value = true;
+
+  setTimeout(() => {
+    loading.value = false;
+    confirmed.value = true;
+  }, 1000);
+}
+</script>
+
+<template>
+  <CdsForm class="flex flex-col items-center gap-300 w-[350px] m-auto" @submit.prevent="submit">
+    <p class="text-200 text-content-secondary">Введите код из приложения-аутентификатора</p>
+
+    <CdsOtpInput v-model="code" :disabled="confirmed" divider="-" />
+
+    <CdsButton type="submit" text="Подтвердить вход" :disabled="!isComplete || confirmed" :loading="loading" block />
+
+    <p v-if="confirmed" class="text-200 text-status-success-content">Вход подтверждён</p>
+  </CdsForm>
+</template>
+```
+
+## API
+
+### CdsOtpInput
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activeColor` | `string \| undefined` | — | no | Цвет компонента, когда он находится в активном состоянии |
+| `autofocus` | `boolean \| undefined` | — | no | Включает автофокус |
+| `baseColor` | `string \| undefined` | — | no | Цвет неактивного компонента |
+| `bgColor` | `string \| undefined` | — | no | Цвет фона компонента |
+| `color` | `string \| undefined` | — | no | Цвет компонента |
+| `disabled` | `boolean \| null \| undefined` | `null` | no | Заблокированное состояние |
+| `divider` | `string \| undefined` | — | no | Символ-разделитель, который ставится между ячейками кода |
+| `error` | `boolean \| undefined` | — | no | Состояние ошибки |
+| `focusAll` | `boolean \| undefined` | — | no | Подсвечивать все ячейки, пока поле находится в фокусе, а не только активную |
+| `focused` | `boolean \| undefined` | — | no | Управляет состоянием фокуса компонента. Когда `true`, компонент считается сфокусированным и может применять соответствующие стили или поведение. |
+| `height` | `string \| number \| undefined` | — | no | Высота компонента |
+| `label` | `string \| undefined` | `'$cds.input.otp'` | no | Доступное имя поля (`aria-label`). Принимает ключ локализации вида `$cds.input.otp` |
+| `length` | `string \| number \| undefined` | `6` | no | Количество ячеек кода |
+| `loading` | `string \| boolean \| undefined` | — | no | Индикатор загрузки для компонента |
+| `masked` | `boolean \| undefined` | — | no | Скрывать введённые символы точками |
+| `maxHeight` | `string \| number \| undefined` | — | no | Максимальная высота компонента |
+| `maxWidth` | `string \| number \| undefined` | — | no | Максимальная ширина компонента |
+| `merged` | `boolean \| undefined` | — | no | Слитный вид: ячейки объединяются в одно поле без промежутков между ними |
+| `minHeight` | `string \| number \| undefined` | — | no | Минимальная высота компонента |
+| `minWidth` | `string \| number \| undefined` | — | no | Минимальная ширина компонента |
+| `modelValue` | `string \| number \| undefined` | — | no | Значение компонента v-model |
+| `pattern` | `RegExp \| "numeric" \| "alpha" \| "alphanumeric" \| "unicode-alpha" \| "unicode-alphanumeric" \| undefined` | — | no | Допустимые символы: имя готового паттерна (`numeric`, `alpha`, `alphanumeric`, `unicode-alpha`, `unicode-alphanumeric`) или собственное регулярное выражение |
+| `placeholder` | `string \| undefined` | — | no | Символ-заполнитель, который показывается в пустой ячейке |
+| `size` | `number \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined` | `'md'` | no | Размер компонента |
+| `textColor` | `string \| undefined` | — | no | Цвет текста компонента |
+| `theme` | `string \| undefined` | — | no | Тема компонента |
+| `type` | `CdsOtpInputType \| undefined` | `'number'` | no | Тип вводимого кода. `number` ограничивает ввод цифрами, `password` скрывает символы |
+| `width` | `string \| number \| undefined` | — | no | Ширина компонента |
+
+**Events**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `finish` | `[value: string]` | Срабатывает, когда код набран полностью |
+| `update:focused` | `[focused: boolean]` | Срабатывает при получении или потере фокуса |
+| `update:modelValue` | `[value: string]` | Срабатывает при изменении значения компонента |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Произвольный контент поверх ячеек кода |
+| `divider` | `{ index: number; }` | Разделитель между ячейками. `index` — номер ячейки слева от разделителя |
+| `fields` | `any` | Полностью заменяет ряд ячеек собственной разметкой из `CdsOtpGroup`, `CdsOtpField` и `CdsOtpSeparator` |
+| `loader` | `any` | Пользовательский индикатор загрузки |
+
+**Exposed**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `blur` | `() => void` | Снять фокус с поля |
+| `focus` | `() => void` | Установить фокус на поле |
+| `inputRef` | `HTMLInputElement \| undefined` | Ref-ссылка на скрытый input, который принимает ввод кода |
+| `isFocused` | `boolean \| undefined` | Состояние фокуса поля |
+| `reset` | `() => void` | Очистить введённый код |
+
+### CdsOtpField
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `index` | `number` | — | yes | Порядковый номер ячейки, начиная с нуля |
+
+### CdsOtpGroup
+
+**Props**
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `merged` | `boolean \| null \| undefined` | — | no | Слитный вид группы. По умолчанию наследуется от родительского `CdsOtpInput` |
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Ячейки кода группы |
+
+### CdsOtpSeparator
+
+**Slots**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `default` | `any` | Содержимое разделителя |
+
+---
+
 # CdsOverlay
 
 _Категория: Content · появился в 4.0.0_
@@ -41092,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.2` (в разработке).
+> Версии: CDS 3 — `3.10.1` (стабильная), CDS 4 — `4.0.0-alpha.4` (в разработке).
 
 ## Как читать этот документ