# Central Design System — CDS 3 → CDS 4 migration

> Version: 4.0.0-alpha.13
> The full migration guide (currently in Russian): breaking changes, renames, deprecations, and migration steps.
> Generated automatically (`bun run generate:meta` → `bun run generate:llms`). Do not edit manually.

---

# Миграция на CDS 4

`@central-design-system/components` v4 — мажорное обновление дизайн-системы.
Этот документ — **живой** migration guide: записи добавляются по мере появления
breaking-изменений в alpha/beta релизах CDS 4.

> Версии: CDS 3 — `3.10.1` (стабильная), CDS 4 — `4.0.0-alpha.4` (в разработке).

## Как читать этот документ

- Каждая запись имеет **severity** (см. ниже). Сначала разбирайтесь с `BREAKING`,
  затем с `RENAMED`, затем с `DEPRECATED`.
- Записи сгруппированы по **категориям** (Архитектура, Иконки, …). Изменения
  по конкретным компонентам — в разделе [Компоненты](#8-компоненты).
- Каждая запись содержит блоки **Было (CDS 3)** и **Стало (CDS 4)** с примерами
  кода и поле **Действие** — конкретный шаг миграции.
- При запуске приложения смотрите на консольные `[CDS UPGRADE]` warnings —
  они подсказывают точки миграции в рантайме
  (реализация: `src/utils/dom/warn.ts → deprecate()`).

## Легенда severity

| Маркер | Что значит |
| --- | --- |
| ⚠️ **BREAKING** | Ломает существующий код — обязательное действие. |
| 🔁 **RENAMED** | Переименование (частный случай breaking) — механический поиск/замена. |
| 🟠 **DEPRECATED** | Работает в 4.x, будет удалено в 5.x. Желательно обновить. |
| ✨ **NEW** | Новая возможность без ломки. Информативно. |

## Оглавление

- [Быстрый чек-лист](#быстрый-чек-лист)
- [1. Архитектура](#1-архитектура)
- [2. Иконки](#2-иконки)
- [3. Пропсы](#3-пропсы)
- [4. Стили и токены](#4-стили-и-токены)
- [5. Композаблы](#5-композаблы)
- [6. Hooks](#6-hooks)
- [7. Сборка и экспорты](#7-сборка-и-экспорты)
- [8. Компоненты](#8-компоненты)

<a id="быстрый-чек-лист"></a>

## Быстрый чек-лист

- ✅ Прочитать раздел [«Архитектура»](#1-архитектура) — публичный API инициализации мог измениться.
- ✅ Если используете `@central-design-system/icons` — см. раздел [«Иконки»](#2-иконки) (есть legacy-режим).
- ✅ Заменить `rgb(var(--cds-…))` на `var(--cds-…)` — цвета в переменных теперь готовые значения (скилл `cds-migrate`, см. [«Стили и токены»](#4-стили-и-токены)).
- ✅ Проверить [индекс изменений по компонентам](#индекс-изменений-по-компонентам).
- ✅ Прогнать сборку приложения и проверить консоль: `[CDS UPGRADE]` warnings указывают на устаревшие пропсы.

---

<a id="1-архитектура"></a>

## 1. Архитектура

Сюда попадают изменения публичного API инициализации (`createCds`),
DI через `provide/inject`, точек входа и общих принципов работы фреймворка.

### Библиотека переписана на новую архитектуру (JSX, `propsFactory`, `composables` / `hooks`)

> ✨ **NEW** — внутренняя архитектура CDS 4 переписана с нуля. На публичный API компонентов это, как правило, не влияет, но меняет способ расширения библиотеки и пути «глубоких» импортов.

**Было (CDS 3):**

```ts
// CDS 3 — SFC на <template>, пропсы inline, композаблы в composable/ (ед. ч.)
import { createCds, components, directives, plugin, utils } from '@central-design-system/components';
import { useTheme } from '@central-design-system/components'; // из ./composable
import { CdsTransitionFade } from '@central-design-system/components'; // из ./transitions
```

**Стало (CDS 4):**

```ts
// CDS 4 — компоненты на JSX defineRender + propsFactory,
// композаблы в composables/ (мн. ч.), низкоуровневые примитивы в hooks/
import { createCds, utils } from '@central-design-system/components';
import { useTheme } from '@central-design-system/components';   // из ./composables
import { CdsTransitionFade } from '@central-design-system/components'; // из ./transitions
import { createContext, useResizeObserver } from '@central-design-system/components'; // ./hooks

// Внутри пакета — alias @cds/* (@cds/composables/useTheme, @cds/core, @cds/utils)
```

**Действие:** для обычного использования компонентов миграция не требуется. Если вы импортировали внутренние сущности напрямую — учтите: каталог `composable/` переименован в `composables/`, добавлен слой `hooks/`. Namespace `utils` и плоские экспорты `transitions` (`CdsTransitionFade`, …) сохранены как в CDS 3; убран только корневой реэкспорт `plugin`. Пропсы компонентов теперь собираются фабриками `propsFactory` (`@cds/core`), рендер — через `defineRender(() => <jsx/>)`.

<!-- entry-meta: id=architecture-library-rewrite; severity=new; component= -->

### `createCds`: новые опции `defaults`, `blueprint`, `goTo`, `aliases`

> ✨ **NEW** — фабрика `createCds` получила новые подсистемы конфигурации. Все они аддитивны — существующий вызов `createCds()` продолжает работать.

**Было (CDS 3):**

```ts
// CDS 3 — ICdsOptions: components, directives, icons, illustrations,
//         display, theme, cssGrid, ssr, locale, teleport
import { createCds } from '@central-design-system/components';

app.use(createCds({
  theme: { defaultTheme: 'light' },
  locale: 'ru',
}));
```

**Стало (CDS 4):**

```ts
// CDS 4 — добавлены defaults, blueprint, goTo, aliases
import { createCds } from '@central-design-system/components';

app.use(createCds({
  // Глобальные дефолты пропсов компонентов.
  // Локально переопределяются компонентом <CdsDefaultsProvider>.
  defaults: {
    global: { rounded: 'md' },
    CdsButton: { variant: 'soft' },
  },
  // Пресет конфигурации: базовый набор опций, поверх которого мержится остальное.
  blueprint: { theme: { defaultTheme: 'light' } },
  // Подсистема программной прокрутки (composable useGoTo).
  goTo: { duration: 300, offset: 0 },
}));
```

**Действие:** миграция не требуется. Новое: `defaults` задаёт глобальные значения пропсов (переопределяются компонентом `CdsDefaultsProvider` и composable `useDefaults`); `blueprint` — пресет опций, на который накладывается остальная конфигурация (`mergeDeep(blueprint, rest)`); `goTo` — программная прокрутка через `useGoTo`; `aliases` — регистрация компонентов-алиасов. Символы DI: `DefaultsSymbol`, `GoToSymbol`, `IconSymbol` (см. `src/cds.ts`).

<!-- entry-meta: id=architecture-createcds-new-options; severity=new; component= -->

### Глобальная опция `createCds({ teleport })` удалена

> ⚠️ **BREAKING** — глобальная конфигурация телепорта всплывающих компонентов (`teleport` → `TeleportSymbol`) убрана из `createCds`. Цель телепорта теперь задаётся per-component через пропсы `attach` / `contained`.

**Было (CDS 3):**

```ts
// CDS 3 — глобально для всех оверлеев (модалки, тултипы, меню, тосты)
import { createCds } from '@central-design-system/components';

app.use(createCds({
  teleport: {
    target: document.getElementById('app')!,
    contained: false,
    root: false,
    containerClassName: 'cds-overlay-container',
  },
}));
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — цель телепорта указывается на конкретном компоненте -->
<CdsModal v-model="modal" attach="#app">…</CdsModal>
<CdsTooltip contained text="Подсказка">…</CdsTooltip>
```

**Действие:** удалить опцию `teleport` из `createCds()`. Там, где нужен нестандартный контейнер телепорта, задать проп `attach` (`boolean | string | Element`) или `contained` на самих оверлейных компонентах (`CdsOverlay` и производные: `CdsModal`, `CdsTooltip`, `CdsMenu`, `CdsDrawer` и т. д.). Поиск: `grep -rn "teleport" src/` в местах вызова `createCds`.

<!-- entry-meta: id=architecture-teleport-option-removed; severity=breaking; component= -->

### Опция `locale` стала объектом `LocaleOptions` (+ RTL)

> ⚠️ **BREAKING** — в CDS 3 `locale` принимал строку (`'ru'`) или объект `ILocale`. В CDS 4 это объект `LocaleOptions & RtlOptions` с полем `locale`, сообщениями, fallback и настройкой RTL.

**Было (CDS 3):**

```ts
// CDS 3 — locale: TAvailableLocale | ILocale (по умолчанию строка 'ru')
import { createCds } from '@central-design-system/components';

app.use(createCds({
  locale: 'ru',
}));
```

**Стало (CDS 4):**

```ts
// CDS 4 — locale: LocaleOptions & RtlOptions
import { createCds } from '@central-design-system/components';

app.use(createCds({
  locale: {
    locale: 'ru',
    fallback: 'en',
    messages: { /* переопределения строк */ },
    rtl: { ar: true },
  },
}));
```

**Действие:** заменить строковое значение `locale: 'ru'` на объект `locale: { locale: 'ru' }`. Полный набор полей: `locale`, `fallback`, `messages`, `decimalSeparator`, `adapter`, `rtl` (см. `LocaleOptions` / `RtlOptions` в `src/composables/useLocale/internal/useLocale.types.ts`). Доступ в рантайме — через composable `useLocale`. Поиск: `grep -rn "createCds" src/` и проверить поле `locale`.

<!-- entry-meta: id=architecture-locale-options-object; severity=breaking; component= -->

---

<a id="2-иконки"></a>

## 2. Иконки

### Пакет `@central-design-system/icons` помечен deprecated

> 🟠 **DEPRECATED** — пакет продолжает работать через legacy-режим, но будет удалён в будущих версиях.

**Было (CDS 3):**

```ts
// CDS 3
import * as legacyIcons from '@central-design-system/icons';
import { createCds } from '@central-design-system/components';

createCds({
  icons: legacyIcons
});
```

**Стало (CDS 4):**

```ts
// CDS 4
import { createCds } from '@central-design-system/components';

// Вид CDS 3 сохраняет устаревший iconpack `cds`.
createCds({
  icons: {
    defaultSet: 'cds'
  }
});
```

В рантайме при старом подключении в dev-консоли появится:

```
[CDS UPGRADE] '@central-design-system/icons' is deprecated, use 'an icon pack' instead.
```

(см. `src/icons.ts`, ветка `Symbol.toStringTag === 'Module'`).

**Действие:** перейти на новые icon packs через опцию `createCds({ icons })`.
Пока пакет подключён, иконки компонентов рисует пак `cds`, а компоненты `Icon*`
остаются зарегистрированными глобально. Пакет будет удалён в 5.0.

<!-- entry-meta: id=icons-legacy-package-deprecated; severity=deprecation; component= -->

### Новая фабрика `createIcons` и iconpacks

> ✨ **NEW**

В CDS 4 иконки конфигурируются через явную фабрику `createIcons`,
понимающую концепцию **iconpack**. Готовые наборы лежат в
`src/assets/icons/`: `phosphor` (по умолчанию), `lucide`, `materialSymbols`,
`remix`, `tabler` и устаревший `cds`. Это позволяет смешивать наборы и
переопределять алиасы под продукт.

**Было (CDS 3):**

```ts
// CDS 3
import * as icons from '@central-design-system/icons';
import { createCds } from '@central-design-system/components';

createCds({ icons });
```

**Стало (CDS 4):**

```ts
// CDS 4
import { createCds, iconsets } from '@central-design-system/components';

createCds({
  icons: {
    defaultSet: 'remix',
    sets: { remix: iconsets.remix.icons, },
    aliases: iconsets.remix.aliases,
  }
});
```

**Действие:** ознакомиться с [Icons Installation](/docs/icons-installation--docs)
и выбрать iconpack под продукт. По умолчанию активен набор `phosphor` с алиасами
из `src/assets/icons/phosphor.ts`.

<!-- entry-meta: id=icons-createicons-factory; severity=new; component= -->

### Иконки отправки `send-*` сведены к `send` и `send-fill`

> ⚠️ **BREAKING** — `send-right` / `send-right-fill` переименованы, остальные направления удалены.

В CDS 3 (3.12.0) иконка отправки шла в четырёх направлениях, каждое в
контурном и залитом варианте. Это одна и та же иконка, повёрнутая на 90°,
поэтому в CDS 4 осталась одна пара: `send` и `send-fill` (самолётик
смотрит вправо). Во всех iconpack'ах (`phosphor`, `remix`, `lucide`, `tabler`,
`materialSymbols`, `cds`) они лежат под этими же именами.

| CDS 3                                              | CDS 4       |
| -------------------------------------------------- | ----------- |
| `send-right`                                       | `send`      |
| `send-right-fill`                                  | `send-fill` |
| `send-up`, `send-down`, `send-left`                | — удалены   |
| `send-up-fill`, `send-down-fill`, `send-left-fill` | — удалены   |

**Было (CDS 3):**

```vue
<!-- CDS 3 -->
<CdsIcon name="send-right" />
<CdsIcon name="send-up-fill" />
```

**Стало (CDS 4):**

```vue
<!-- CDS 4 -->
<CdsIcon icon="send" />
<CdsIcon icon="send-fill" />
```

**Действие:** заменить `send-right` → `send` и `send-right-fill` → `send-fill`.
Остальные направления заменить на `send` / `send-fill`; если направление
принципиально, повернуть иконку через CSS (`transform: rotate(…)`).
Поиск: `grep -rnE "send-(up|down|left|right)(-fill)?|IconSend(Up|Down|Left|Right)" src/`.

<!-- entry-meta: id=icons-send-directions-to-send; severity=breaking; component= -->

### Имена иконок по назначению, Phosphor по умолчанию

> ⚠️ **BREAKING** — компоненты рисуют новые имена, `createCds()` без опций рисует Phosphor; старые имена работают весь 4.x и будут удалены в 5.0.

**Было (CDS 3):**

```vue
<!-- CDS 3 -->
<CdsIcon name="doc" />
<CdsButton prepend-icon="plus" />
```

**Стало (CDS 4):**

```vue
<!-- CDS 4 -->
<CdsIcon name="file" />
<CdsButton prepend-icon="add" />
```

Устанавливать ничего не нужно: CSS иконок Phosphor входит в пакет. Иконки
хранятся как `data:` URI, поэтому Content Security Policy должен разрешать
`img-src data:`. При печати иконки чёрные.

Иконки крупнее прежних в той же рамке, размеры компонентов не менялись.

| Имя CDS 3 | Имя CDS 4 |
| --- | --- |
| `alert` | `warning` |
| `alert-fill` | `warning-fill` |
| `analog` | `nested` |
| `arrow-left-bottom` | `arrow-down-left` |
| `arrow-left-top` | `arrow-up-left` |
| `arrow-right-bottom` | `arrow-down-right` |
| `arrow-right-top` | `arrow-up-right` |
| `arrows-vertical` | `swap` |
| `card-bank` | `credit-card` |
| `category` | `tree` |
| `check-fill` | `success-fill` |
| `checkbox` | `checkbox-on` |
| `checkbox-fill` | `checkbox-on-fill` |
| `chocholate-menu` | `apps` |
| `chocolate-menu` | `apps` |
| `clock` | `time` |
| `clock-fill` | `time-fill` |
| `collapse` | `panel-left-close` |
| `comment` | `message` |
| `data-cards` | `view-rows` |
| `delimiter` | `dot` |
| `directory` | `folder` |
| `directory-open` | `folder-open` |
| `doc` | `file` |
| `doc-download` | `file-download` |
| `draggable` | `drag` |
| `enter` | `external-link` |
| `expand` | `panel-left-open` |
| `external` | `external-link` |
| `facebook-fill` | `facebook` |
| `fill` | `fill-color` |
| `filters` | `adjust` |
| `first` | `first-page` |
| `format` | `format-clear` |
| `funnel` | `filter` |
| `insert` | `paste` |
| `last` | `last-page` |
| `list` | `list-bullet` |
| `locked` | `lock` |
| `moon` | `dark-mode` |
| `next` | `chevron-right` |
| `overflow-menu-horizontal` | `more-horizontal` |
| `overflow-menu-vertical` | `more-vertical` |
| `password` | `key` |
| `plus` | `add` |
| `prev` | `chevron-left` |
| `printer` | `print` |
| `question` | `help` |
| `question-fill` | `help-fill` |
| `sandglass` | `hourglass` |
| `scale-left` | `maximize` |
| `scale-right` | `minimize` |
| `sort-date` | `sort` |
| `sorting` | `sort` |
| `sorting-down` | `sort-desc` |
| `sorting-up` | `sort-asc` |
| `source` | `code` |
| `sun` | `light-mode` |
| `tab-backward` | `indent-decrease` |
| `tab-forward` | `indent-increase` |
| `thumb-down` | `dislike` |
| `thumb-down-fill` | `dislike-fill` |
| `thumb-up` | `like` |
| `thumb-up-fill` | `like-fill` |
| `truck` | `delivery` |
| `unlocked` | `unlock` |
| `unlocked-left` | `unlock` |
| `user-avatar` | `user` |
| `visibility-on` | `visibility` |
| `winner` | `trophy` |
| `workspace` | `dashboard` |

Часть имён осталась, но сменила рисунок: предупреждения о них не будет.
`add` теперь плюс без круга (круг — `add-circle`), `check` — галочка без круга
(круг — `success`), `error` и `error-fill` — круг с восклицательным знаком
(запрет — `blocked`), `checkbox-on` — контурный квадрат с галочкой (залитый —
`checkbox-on-fill`).

Своя карта `aliases` теперь дополняет пак, а не заменяет его. Если в ней задано
старое имя, например `alert`, компонент, запрашивающий `warning`, нарисует глиф
пака: задайте в карте новое имя.

**Действие:** заменить имена по таблице, предупреждения `[CDS UPGRADE]` в
dev-консоли покажут оставшиеся. Чтобы сохранить вид CDS 3, укажите
`icons: { defaultSet: 'cds' }`. Этот пак устарел.

<!-- entry-meta: id=icons-reference-aliases-phosphor; severity=breaking; component= -->

---

<a id="3-пропсы"></a>

## 3. Пропсы

Сюда попадают общие изменения системы пропсов (фабрики
`defineXProps()` через `propsFactory`, новые композаблы пропсов).
Точечные переименования у конкретных компонентов — в разделе [Компоненты](#8-компоненты).

_Пока изменений нет. Записи будут добавляться по мере появления breaking-изменений._

---

<a id="4-стили-и-токены"></a>

## 4. Стили и токены

Сюда попадают изменения CSS-токенов (2 уровня), CSS Layers (ITCSS),
интеграции с Tailwind, публичных импортов `./styles/...`.

### Цвета в CSS-переменных — готовые значения, а не каналы RGB

> ⚠️ **BREAKING** — `--cds-color-*` и `--cds-alpha-*` хранят
> готовый цвет (у встроенных тем — `oklch()`), обёртка `rgb()`
> делает свойство невалидным.

**Было (CDS 3):**

```scss
// CDS 3
.my-block {
  color: rgb(var(--cds-color-content-primary));
  background: rgb(var(--cds-color-fill-secondary), 0.4);
}
```

**Стало (CDS 4):**

```scss
// CDS 4
.my-block {
  color: var(--cds-color-content-primary);
  background: color-mix(in srgb, var(--cds-color-fill-secondary) 40%, transparent);
}
```

**Действие:** заменить `rgb(var(--cds-X))` / `rgba(var(--cds-X))`
на `var(--cds-X)`, альфу поверх — на `color-mix(…, transparent)`.
Замену делает скилл `cds-migrate` (LDS-218); проверка —
`grep -rnE "rgba?\(\s*var\(--cds-" src` пуст. Своя тема может
задавать цвета в hex, `rgb()` или `oklch()` — значение попадёт
в CSS как написано. Палитра-примитивы (`utils/colors`) удалена.

<!-- entry-meta: id=styles-color-vars-ready-values; severity=breaking; component= -->

### Изменён путь импорта CSS

> ⚠️ **BREAKING** — собранный `dist/cds.css` больше не является публичной точкой входа.

**Было (CDS 3):**

```ts
// CDS 3
import '@central-design-system/components/dist/cds.css';
```

**Стало (CDS 4):**

```ts
// CDS 4
import '@central-design-system/components/styles';
```

**Действие:** заменить во всех приложениях-потребителях импорт `@central-design-system/components/dist/cds.css` на `@central-design-system/components/styles`. Поиск: `grep -rn "@central-design-system/components/dist/cds.css" .`.

<!-- entry-meta: id=styles-css-import-path; severity=breaking; component= -->

### Legacy reset вынесен в опциональный флаг

> ⚠️ **BREAKING** — `styles/utilities/legacy/legacy.scss` теперь содержит только утилитарные классы (display / layout / spacing / flexbox / typography); глобальный reset из CDS 3 больше не подключается по умолчанию.

**Было (CDS 3):**

```scss
// CDS 3 — legacy.scss тянул за собой полный глобальный reset
// (box-sizing, обнуление margin, list-style, media-query'и и т.д.)
// автоматически при подключении стилей CDS.
@use '@central-design-system/components/styles';
```

**Стало (CDS 4):**

```scss
// CDS 4 — legacy.scss содержит только утилиты; старый reset вынесен
// в generic/_legacy-reset.scss и выключен по умолчанию.
// Чтобы вернуть поведение CDS 3, передайте $legacy-reset через with():
@use '@central-design-system/components/styles' with (
  $legacy-reset: true
);
```

**Действие:** если приложение полагалось на глобальный reset из CDS 3 (обнулённые `margin`, `list-style: none`, `box-sizing: border-box` на `*` и т.д.) — включите его явно через `$legacy-reset: true` в `settings` (см. `src/styles/settings/_variables.scss`). Иначе — проверьте вёрстку и доверьтесь нативным дефолтам браузера.

<!-- entry-meta: id=styles-legacy-reset-opt-in; severity=breaking; component= -->

### CSS-архитектура переписана на ITCSS + CSS Layers

> ⚠️ **BREAKING** — порядок каскада теперь определяется нативными `@layer`. Глобальные переопределения стилей CDS, написанные без `!important`, могут сработать иначе.

**Было (CDS 3):**

```scss
// CDS 3 — плоская структура без cascade layers.
// Все стили компонентов и утилит грузились в обычный каскад,
// побеждал последний по специфичности / порядку импорта.
@import '@central-design-system/components/dist/cds.css';

// Переопределение приходилось делать через повышение специфичности
// или !important:
.cds-button { color: red !important; }
```

**Стало (CDS 4):**

```scss
// CDS 4 — ITCSS + нативные CSS Layers.
// Каскад: cds-core → cds-components → cds-overrides → cds-utilities,
// см. src/styles/generic/_layers.scss.
@use '@central-design-system/components/styles';

@layer cds-overrides {
  .cds-button { color: red; }
}
```

**Действие:** ознакомиться с [ITCSS](https://developer.helpscout.com/seed/glossary/itcss/) и порядком слоёв в `src/styles/generic/_layers.scss` (`cds-core` → `cds-components` → `cds-overrides` → `cds-utilities` c вложенными `theme-base`, `helpers`, `grid`, `tailwind`, `theme-background`, `theme-foreground`). Проверьте свои глобальные переопределения CDS — если они были написаны без `!important` и полагались на порядок импорта, теперь они **гарантированно** перебивают `@layer cds-components`. Для контролируемого переопределения используйте слой `cds-overrides` (через `@include tools.layer('overrides') { … }`) — он специально расположен между компонентами и утилитами.

<!-- entry-meta: id=styles-itcss-css-layers-architecture; severity=breaking; component= -->

### Утилитарные классы CDS 3 отключены по умолчанию

> ⚠️ **BREAKING** — классы `cds-flex`, `cds-flex-col`, `cds-px-4`, `cds-my-*`, цветов, типографики и т. п. больше не подключаются автоматически.

**Было (CDS 3):**

```ts
// CDS 3
import '@central-design-system/components/dist/cds.css';
import { createCds } from '@central-design-system/components';

app.use(createCds());
```

```vue
<!-- CDS 3 -->
<div class="cds-flex cds-flex-col cds-px-4">…</div>
```

**Стало (CDS 4):**

```ts
// CDS 4 — временно включить легаси-утилиты на период миграции
import '@central-design-system/components/styles';
import '@central-design-system/components/styles/legacy';
import { createCds } from '@central-design-system/components';

app.use(createCds({
  theme: { legacyClasses: true },
}));
```

**Действие:** мигрировать на Tailwind CSS v4 (см. запись «Интеграция с Tailwind CSS v4» ниже). На переходный период включите легаси-утилиты комбинацией `theme: { legacyClasses: true }` в `createCds()` + импорт `@central-design-system/components/styles/legacy`. Источник: `src/styles/utilities/legacy/legacy.scss` (display, layout, spacing, flexbox, typography).

<!-- entry-meta: id=styles-legacy-utilities-disabled; severity=breaking; component= -->

### Интеграция с Tailwind CSS v4

> ✨ **NEW** — CDS из коробки поставляет конфигурацию Tailwind v4 с design-токенами как утилитарными классами.

**Было (CDS 3):**

```vue
<!-- CDS 3 — собственные утилитарные классы CDS -->
<div class="cds-flex cds-flex-col cds-px-4 cds-text-surface-primary">…</div>
```

**Стало (CDS 4):**

```css
/* CDS 4 — main.css */
@import "@central-design-system/components/styles/tailwind";
@import "tailwindcss/theme" layer(cds-utilities.tailwind);
@import "tailwindcss/utilities" layer(cds-utilities.tailwind);
```

```vue
<!-- CDS 4 — Tailwind v4 + CDS-токены как утилиты -->
<div class="flex flex-col p-4 text-surface-primary">…</div>
```

**Действие:** установить Tailwind CSS v4 по [официальной документации](https://tailwindcss.com/) и подключить конфигурацию `@central-design-system/components/styles/tailwind` — она расширяет тему Tailwind токенами CDS (`bg-surface-*`, `text-content-*`, `rounded-200`, …) и автоматически реагирует на смену темы. Отступы пишутся стандартной числовой шкалой Tailwind (`p-4`, `gap-2`) — шкала отступов CDS с ней совпадает.

<!-- entry-meta: id=styles-tailwind-v4-integration; severity=new; component= -->

### Семантика миксина `cds-breakpoint-down` выровнена с JS `useDisplay`

> ⚠️ **BREAKING** — в CDS 3 SCSS-миксин `cds-breakpoint-down($name)` следовал конвенции «строго ниже начала брейкпоинта», а JS-composable `useDisplay` — конвенции «брейкпоинт и всё, что ниже». Из-за этого `cds-breakpoint-down('sm')` и `display.smDown` покрывали **разные** диапазоны (сдвиг на один брейкпоинт). В CDS 4 CSS выровнен под JS: `down('<name>')` теперь означает «`<name>` и ниже».

**Было (CDS 3):**

```scss
// CDS 3 — max-width = ширина САМОГО брейкпоинта − 0.02 («строго ниже sm»)
// down('sm')  → @media (max-width: 671.98px)   // только диапазон xs
// down('md')  → @media (max-width: 1055.98px)  // xs + sm
// down('lg')  → @media (max-width: 1311.98px)  // xs + sm + md
// НЕ совпадает с JS: display.smDown === (width < 1056)
.card { @include cds-breakpoint-down(sm) { display: none; } }
```

**Стало (CDS 4):**

```scss
// CDS 4 — max-width = ширина СЛЕДУЮЩЕГО брейкпоинта − 0.02 («sm и ниже»)
// down('sm')  → @media (max-width: 1055.98px)  // xs + sm
// down('md')  → @media (max-width: 1311.98px)  // xs + sm + md
// down('lg')  → @media (max-width: 1583.98px)  // xs + sm + md + lg
// down('xl')  → без media query (все ширины)
// Совпадает с JS: display.smDown === (width < 1056)
.card { @include cds-breakpoint-down(sm) { display: none; } }
```

**Действие:** пройтись по использованиям `cds-breakpoint-down(...)` (и `cds-breakpoint-between(...)` с именованной нижней/верхней границей — она делегирует в тот же миксин). Если код полагался на старую логику «строго ниже названного брейкпоинта», сдвиньте аргумент на один вниз: старый `down('md')` ⇒ новый `down('sm')`, старый `down('lg')` ⇒ `down('md')` и т. д. Миксины `cds-breakpoint-up` / значения порогов (`320 / 672 / 1056 / 1312 / 1584`) не менялись. Поиск: `grep -rnE "cds-breakpoint-down\(" src/`.

<!-- entry-meta: id=styles-breakpoint-down-semantics; severity=breaking; component= -->

### Сетка и брейкпоинты заданы в px вместо rem

> ⚠️ **BREAKING** — в CDS 3 вся геометрия сетки (`$grid-gutter`, `margin` и `width` брейкпоинтов) прогонялась через `convert.toRem` и зависела от размера корневого шрифта. В CDS 4 значения намеренно заданы в px: каркас страницы не зависит от `html { font-size }` хоста, а CSS-медиазапросы гарантированно совпадают с px-порогами JS-композабла `useDisplay` (rem в медиазапросах считается от настройки шрифта браузера и расходится с `window.innerWidth`).

**Было (CDS 3):**

```scss
// CDS 3 — rem от корневого шрифта: хост с html { font-size: 14px }
// получал gutter 28px вместо 32px, а rem-медиазапросы срабатывали
// не там, где JS-логика в px
$grid-gutter: convert.toRem(32px); // 2rem
$grid-breakpoints: (
  sm: (columns: 8, margin: convert.toRem(16px), width: convert.toRem(672px)),
  // …
);
```

**Стало (CDS 4):**

```scss
// CDS 4 — px: геометрия сетки стабильна в любом хосте и совпадает
// с порогами useDisplay (320 / 672 / 1056 / 1312 / 1584)
$grid-gutter: 32px;
$grid-breakpoints: (
  sm: (columns: 8, margin: 16px, width: 672px),
  // …
);
```

**Действие:** в большинстве приложений ничего делать не нужно — браузерный зум масштабирует px-макет целиком. Если хост менял `html { font-size }` в расчёте на масштабирование сетки, этот механизм больше не работает: сетка и брейкпоинты фиксированы, масштабируемый слой — rem-токены `--cds-spacing-*` (отступы контента и типографика).

<!-- entry-meta: id=styles-grid-px-instead-of-rem; severity=breaking; component= -->

### Переменные `$standard-easing` / `$decelerated-easing` / `$accelerated-easing` удалены

> ⚠️ **BREAKING** — кривые Material 2 из `settings` заменены кривыми шкалы движения Luma: `standard`, `enter`, `exit`. Вместе с ними из `tools` убраны `$cds-duration-*`, `get-motion` и `cds-animation-motion`.

**Было (CDS 3):**

```scss
// CDS 3
@use '@central-design-system/components/styles/settings';

.panel {
  transition: transform 300ms settings.$decelerated-easing;
}

.panel--closing {
  transition: transform 200ms settings.$accelerated-easing;
}
```

**Стало (CDS 4):**

```scss
// CDS 4
@use '@central-design-system/components/styles/motion';

.panel {
  transition: transform motion.duration(normal) motion.easing(enter);
}

.panel--closing {
  transition: transform motion.duration(fast) motion.easing(exit);
}
```

**Действие:** убрать `$standard-easing`, `$decelerated-easing` и `$accelerated-easing` из `@use '…/styles/settings' with (…)` и из `styles.configFile` vite-плагина: теперь это ошибка Sass (переменная не объявлена в модуле, переопределить её нельзя). Дальше заменить `settings.$standard-easing` на `motion.easing(standard)`, `$decelerated-easing` (появление) на `motion.easing(enter)`, `$accelerated-easing` (уход) на `motion.easing(exit)`, а литеральные длительности — на `motion.duration(<ступень>)` (`instant` 50 … `very-slow` 500). Поиск: `grep -rnE "standard-easing|decelerated-easing|accelerated-easing|cds-duration-|get-motion|cds-animation-motion" src/`. Значения для JS — `motion.easings.*` и `motion.durations.*` из `@central-design-system/components`. Гайд — «Анимации».

<!-- entry-meta: id=styles-motion-easing-variables-removed; severity=breaking; component= -->

### Анимации компонентов переведены на шкалу движения Luma

> ✨ **NEW** — все анимации компонентов идут по одной шкале: семь длительностей и кривые `standard` / `enter` / `exit` вместо кривых Material 2. Публичные переменные вроде `$select-transition` или `$badge-transition` сохранили имя и форму значения (`<длительность> <кривая>`), поменялись значения по умолчанию. Не все `$*-transition` имеют такую форму: `$list-subheader-transition`, `$responsive-sizer-transition` и `$progress-circle-overlay-transition` перечисляют свойства.

**Было (CDS 3):**

```scss
// CDS 3 — кривая Material 2 из settings
$select-transition: .2s settings.$standard-easing !default;
```

**Стало (CDS 4):**

```scss
// CDS 4 — шкала Luma: ступень и кривая из модуля motion
@use '@central-design-system/components/styles/motion';

$select-transition: motion.duration(fast) motion.easing(standard);
```

**Действие:** миграция не требуется. Если вы переопределяли переменные `$*-transition` или подстраивали тайминги под старые кривые, сверьтесь с таблицами шкалы в гайде «Анимации» и по возможности берите ступени вместо литералов. Переходы `CdsTransition*`, модалка (появление `normal` вместо 225ms, уход `fast`), тултипы (появление `fast` вместо 100ms) и тосты перенесены на ступени шкалы: часть значений стала короче, часть длиннее, поэтому единой «скорости» у них больше нет. При `prefers-reduced-motion` сдвиг и масштаб заменяются затуханием, а декоративные полосы `striped` у `CdsProgressBar` останавливаются (цикл неопределённого прогресса идёт как раньше).

Форма значения у `$list-subheader-transition` (`<длительность> min-height <кривая>`), `$responsive-sizer-transition` (`padding-bottom <длительность> <кривая>`) и `$progress-circle-overlay-transition` (список из свойств) включает свойства. У последней переменной теперь три элемента вместо двух (`stroke-dashoffset`, `stroke`, `stroke-width 0s`), и `CdsProgressCircle` рассчитывает на три: переопределение из двух элементов, оставшееся от CDS 3, анимирует `stroke-width` во время появления круга. Переопределяйте её целиком, тремя элементами.

<!-- entry-meta: id=styles-motion-scale-for-components; severity=new; component= -->

### `surface-overlay` непрозрачный, подложку разбавляет компонент

> ⚠️ **BREAKING** — во всех темах `--cds-color-surface-overlay` стал непрозрачным: альфа (0.5 в светлых темах, 0.8 в тёмных) ушла из токена в компоненты. Это модель эталонной темы `lumaLight`.

**Было (CDS 3):**

```scss
// CDS 3 — полупрозрачность приходила из токена
.my-backdrop {
  background: rgb(var(--cds-color-surface-overlay));
}
```

**Стало (CDS 4):**

```scss
// CDS 4 — токен сплошной, долю задаёт потребитель
.my-backdrop {
  background: color-mix(in srgb, var(--cds-color-surface-overlay) 50%, transparent);
}
```

**Действие:** найти свои подложки на токене (`grep -rn "surface-overlay" src`) и разбавить их через `color-mix(…, transparent)` или `opacity`, иначе они закроют страницу сплошным цветом. Подложки `CdsOverlay` (модалки, диалоги), `CdsDrawer`, `CdsLoader` и кнопки `CdsCarousel` разбавляют токен сами, на общую долю `$overlay-opacity` (50%). У дровера она вынесена в `$drawer-overlay-opacity`. Вид меняется: подложка модалки в светлых темах темнее (50% вместо ~25%), подложки дровера и лоадера в тёмных темах светлее (50% вместо 80%).

<!-- entry-meta: id=styles-surface-overlay-opaque; severity=breaking; component= -->

---

<a id="5-композаблы"></a>

## 5. Композаблы

Сюда попадают изменения API композаблов (`useTheme`, `useIcons`, `useDisplay`,
`useLocale`, `useDefaults`, `useForm` и др.) и injection-системы
(`DefaultsSymbol`, `ThemeSymbol`, `IconSymbol`, …).

_Пока изменений нет. Записи будут добавляться по мере появления breaking-изменений._

---

## 6. Hooks

Сюда попадают изменения API хуков из `src/hooks/`
(`createContext`, `createObserver`, `createPlugin`, `createTrinity`,
`useHydration`, `useIntersectionObserver`, `useResizeObserver`).

_Пока изменений нет. Записи будут добавляться по мере появления breaking-изменений._

---

<a id="7-сборка-и-экспорты"></a>

## 7. Сборка и экспорты

Сюда попадают изменения целей сборки (CJS / ESM / MJS / IIFE / WC / Styles),
полей `exports` / `main` / `module` / `types` в `package.json`, путей
импортов `@central-design-system/components/...`.

_Пока изменений нет. Записи будут добавляться по мере появления breaking-изменений._

---

<a id="8-компоненты"></a>

## 8. Компоненты

Точечные изменения по конкретным компонентам: переименования пропсов,
удалённые слоты, изменения событий и т. п.

<a id="индекс-изменений-по-компонентам"></a>

### Индекс изменений по компонентам

| Компонент        | Изменения                                                                                  | Подробнее                         |
|------------------|--------------------------------------------------------------------------------------------|-----------------------------------|
| `CdsBadge`       | 🔁 `count`→`content`, `limited`→`max`; ⚠️ удалён `invertColor`, изменён дефолт `inline`    | [CdsBadge](#cdsbadge)             |
| `CdsBreadcrumbsItem` | 🔁 `text`→`title`; ⚠️ удалён deprecated `currentPage`                                  | [CdsBreadcrumbsItem](#cdsbreadcrumbsitem) |
| `CdsButton`      | ⚠️ удалён автоматический отступ между соседними кнопками; 🟠 `appearance` → `variant` + `color`; ⚠️ `$button-appearances` → `$button-colors`; ⚠️ удалена `constants.appearances` | [CdsButton](#cdsbutton)           |
| `CdsCard`        | ⚠️ удалены `interactive` / `selected`                                                      | [CdsCard](#cdscard)               |
| `CdsCheckbox`    | ⚠️ удалён `CdsCheckboxGroup`; ⚠️ изменён exposed-API                                       | [CdsCheckbox](#cdscheckbox)       |
| `CdsContentSwitcher` | ⚠️ Компонент удалён → `CdsTabs` / `CdsTab`                                             | [CdsContentSwitcher](#cdscontentswitcher) |
| `CdsDrawer`      | ⚠️ `v-model` управляет видимостью и на широком экране; синхронизация с шириной экрана     | [CdsDrawer](#cdsdrawer)           |
| `CdsForm`        | ⚠️ изменён exposed-API — убраны обёртки `form` / `formRef`                                 | [CdsForm](#cdsform)               |
| `CdsIcon`        | ⚠️ удалён deprecated `invertColor` → цветовые пропсы `color` / `baseColor` / `textColor`   | [CdsIcon](#cdsicon)               |
| `CdsList`        | ⚠️ удалён `invertColor`; `CdsListItem` — удалён `isClickable` (→ `link`) и изменён exposed-API; `CdsListGroup` — удалён слот `title`, проп `title` стал текстом активатора (статичная подпись → `CdsListSubheader`), изменён exposed-API; payload `click:open`/`click:select` без `event` | [CdsList](#cdslist)               |
| `CdsModal`       | ⚠️ удалены `loading` и `dismissBtn`; ⚠️ изменён exposed-API                                | [CdsModal](#cdsmodal)             |
| `CdsNotification` | 🔁 `status="error"`→`"danger"`; ⚠️ удалён `customIcon`; ✨ `variant="flat"`, тень у `important`, `bgColor`/`textColor`; ⚠️ `update:modelValue` после ухода | [CdsNotification](#cdsnotification) |
| `CdsNotificationAlert` | 🟠 Мост миграции на `CdsToast`; внутри `CdsNotification` (`variant="important"`); будет удалён | [CdsNotificationAlert](#cdsnotificationalert) |
| `CdsRadioButton` | 🔁 Переименован в `CdsRadioGroup`; ✨ новые пропсы                                          | [CdsRadioButton](#cdsradiobutton) |
| `CdsDropdown`    | 🔁 Переименован в `CdsSelect`; ⚠️ нативный `CdsSelect` (CDS 3) теперь через `native-select` | [CdsSelect](#cdsselect)           |
| `CdsProgress`    | 🔁 Переименован в `CdsProgressBar`; ✨ новые пропсы стилизации                              | [CdsProgress](#cdsprogress)       |
| `CdsSlideGroup`  | 🔁 `prependIcon`/`appendIcon`→`prevIcon`/`nextIcon` (новая система иконок)                  | [CdsSlideGroup](#cdsslidegroup)   |
| `CdsSlideView`   | ✨ иконки стрелок переведены на новую систему иконок                                       | [CdsSlideView](#cdsslideview)     |
| `CdsStages`      | 🟠 Помечен deprecated → `CdsSteps` без `interactive`; будет удалён в 5.0                    | [CdsStages](#cdsstages)           |
| `CdsStatus`      | 🔁 значение `status="error"`→`"danger"`; ⚠️ булев `icon`→`variant="text"`                   | [CdsStatus](#cdsstatus)           |
| `CdsSteps`       | ⚠️ дефолт `interactive` изменён `true`→`false`; ✨ проп `items`, контентная часть и кнопки навигации | [CdsSteps](#cdssteps)             |
| `CdsTabsV2`      | 🔁 Переименован в `CdsTabs`; 🔁 `prependIcon`/`appendIcon`→`prevIcon`/`nextIcon`; ✨ новые пропсы | [CdsTabsV2](#cdstabsv2)           |
| `CdsTag`         | 🔁 `remove`→`click:close`; ⚠️ удалён слот `text`; иконки → `IconValue`; ✨ новые пропсы | [CdsTag](#cdstag)                 |
| `CdsTextArea`    | ⚠️ удалён `limit`; ⚠️ изменён exposed-API; | [CdsTextArea](#cdstextarea)       |
| `CdsTextInput`   | ⚠️ удалён `limit`; ⚠️ удалён `persistentMessages`, `messages` теперь видны всегда; ⚠️ изменён exposed-API; иконки → `IconValue` | [CdsTextInput](#cdstextinput)     |
| `CdsTooltip`     | ⚠️ hover на контент закрывает подсказку; интерактивный контент — через новый проп `interactive`; изменён exposed-API | [CdsTooltip](#cdstooltip)         |
| `CdsTransitionCollapse` | ⚠️ Удалён → `CdsTransitionPresence`                                                 | [CdsTransitionCollapse](#cdstransitioncollapse) |
| `CdsContainer`   | ⚠️ Компонент удален;                                                                       | [CdsContainer](#cdscontainer)     |

### CdsNotification

#### Новое значение `flat` у `variant`; `important` получил тень

> ✨ **NEW** — набор вариантов CDS 3 сохранён (`default` / `compact` / `important`, по умолчанию `default`), добавлено значение `flat` — уведомление без рамки. Вариант `important` (в CDS 3 не имел собственных стилей) теперь воспроизводит вид `CdsNotificationAlert`: нейтральный фон (`surface-elevated`) и тень (`cds-shadow-bottom-300`), статус задаёт только цвета контента и рамки.

**Было (CDS 3):**

```html
<!-- CDS 3 — variant: 'default' | 'compact' | 'important' (default 'default') -->
<cds-notification title="Заголовок" text="Описание уведомления" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — variant: 'default' | 'flat' | 'compact' | 'important' (default 'default') -->
<CdsNotification variant="flat" title="Заголовок" text="Описание уведомления" />
```

**Действие:** миграция не требуется — существующие значения работают как раньше. Учтите, что `variant="important"` теперь визуально отличается (нейтральный фон + тень, как у тоста `CdsNotificationAlert` в CDS 3).

<!-- entry-meta: id=cdsnotification-variant-flat-important; severity=new; component=CdsNotification -->

#### Значение `status="error"` переименовано в `status="danger"`

> 🔁 **RENAMED** — как и у `CdsStatus`, набор статусов выровнен с токенами `--cds-color-status-*`.

**Было (CDS 3):**

```html
<!-- CDS 3 — status: 'info' | 'success' | 'warning' | 'error' | 'progress' -->
<cds-notification status="error" title="Ошибка" text="Что-то пошло не так" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — status: 'info' | 'success' | 'warning' | 'danger' | 'progress' -->
<CdsNotification status="danger" title="Ошибка" text="Что-то пошло не так" />
```

**Действие:** заменить `status="error"` на `status="danger"`. Поиск: `grep -rnE "(cds-notification|CdsNotification)[^>]*status=\"error\"" src/`.

<!-- entry-meta: id=cdsnotification-status-error-to-danger; severity=renamed; component=CdsNotification -->

#### Проп `customIcon` удалён

> ⚠️ **BREAKING** — своя иконка задаётся через единый проп `icon` (`false` — скрыть иконку; по умолчанию иконка берётся из `status`).

**Было (CDS 3):**

```html
<!-- CDS 3 — отдельные пропсы icon (false | имя) и customIcon -->
<cds-notification custom-icon="bookmark" title="Заголовок" text="Описание уведомления" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — только icon: false | IconValue -->
<CdsNotification icon="bookmark" title="Заголовок" text="Описание уведомления" />
```

**Действие:** заменить `custom-icon` / `customIcon` на `icon`. Поиск: `grep -rnE "custom-icon|customIcon" src/`.

<!-- entry-meta: id=cdsnotification-customicon-removed; severity=breaking; component=CdsNotification -->

#### Новые пропсы `bgColor` / `textColor`

> ✨ **NEW** — цвет фона и контента можно переопределить через `useColor`; без них действуют цвета статуса (миграция не требуется).

**Было (CDS 3):**

```html
<!-- CDS 3 — цвета жёстко привязаны к status -->
<cds-notification status="info" title="Заголовок" text="Описание уведомления" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — фон и текст можно переопределить (alias-токен или raw CSS-цвет) -->
<CdsNotification bg-color="brand-primary" text-color="content-on-dark" title="Заголовок" text="Описание уведомления" />
```

**Действие:** миграция не требуется. Alias-цвета резолвятся в tier `fill` (фон) и `content` (текст); raw CSS-цвета применяются инлайн-стилем.

<!-- entry-meta: id=cdsnotification-bgcolor-textcolor; severity=new; component=CdsNotification -->

#### Событие `update:modelValue` приходит после ухода, `click:close` — сразу

> ⚠️ **BREAKING** — уведомление теперь плавно появляется и уходит (`CdsTransitionPresence`), поэтому `update:modelValue` срабатывает по окончании анимации ухода, а не в момент клика. Событие `click:close` по-прежнему приходит сразу.

**Было (CDS 3):**

```html
<!-- CDS 3 — update:modelValue приходит в момент клика, уведомление исчезает сразу -->
<cds-notification v-model="visible" closable text="Сохранено" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — click:close сразу; update:modelValue после ухода (до 300ms) -->
<CdsNotification v-model="visible" closable text="Сохранено" @click:close="onClose" />
```

**Действие:** если обработчик `update:modelValue` должен сработать мгновенно (аналитика, убрать элемент из списка), перенесите его на `click:close`. Уведомление, скрытое родителем через `v-model`, тоже уходит плавно, но повторного события не будет. Если родитель управляет `modelValue` и игнорирует `update:modelValue`, то после клика на закрытие уведомление остаётся скрытым, а `modelValue` так и остаётся `true`: чтобы показать его снова, сначала переведите `modelValue` в `false`, затем в `true`. Отступ между уведомлениями в списке задавайте `margin`, а не `gap`: `margin` схлопывается вместе с блоком.

<!-- entry-meta: id=cdsnotification-update-modelvalue-after-leave; severity=breaking; component=CdsNotification -->

### CdsBadge

#### Пропс `count` переименован в `content`

> 🔁 **RENAMED** — пропс приходит из общей фабрики `defineTextProps()` и теперь называется `content`.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsBadge :count="5" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<CdsBadge :content="5" />
```

**Действие:** заменить `:count` на `:content`. Поиск использований: `grep -rn "CdsBadge[^/>]*\bcount=" src/`.

<!-- entry-meta: id=cdsbadge-count-to-content; severity=renamed; component=CdsBadge -->

#### Пропс `limited` заменён на `max` со значением

> 🔁 **RENAMED** — вместо булева флага теперь явное число-порог.

**Было (CDS 3):**

```html
<!-- CDS 3 — limited отрезал значение по фиксированному порогу (99) -->
<CdsBadge :count="120" limited />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — порог задаётся явно через max -->
<CdsBadge :content="120" :max="99" />
```

**Действие:** заменить `limited` на `:max="<число>"`. В CDS 3 порог по умолчанию был `99` — оставьте это значение, чтобы поведение не изменилось.

<!-- entry-meta: id=cdsbadge-limited-to-max; severity=renamed; component=CdsBadge -->

#### Пропс `invertColor` удалён

> ⚠️ **BREAKING** — в CDS 3 был помечен `deprecated`, в CDS 4 удалён.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsBadge :count="5" invert-color />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — для смены цвета используются color / textColor -->
<CdsBadge :content="5" color="surface-primary" text-color="content-on-primary" />
```

**Действие:** удалить использования `invert-color` / `invertColor`. Если нужен инвертированный вид — задайте `color` и `textColor` явно.

<!-- entry-meta: id=cdsbadge-invertcolor-removed; severity=breaking; component=CdsBadge -->

#### Дефолт пропса `inline` изменён с `true` на `undefined`

> ⚠️ **BREAKING** — без явного `inline` бейдж теперь позиционируется абсолютно (`location: 'top end'`), а не как inline-блок.

**Было (CDS 3):**

```html
<!-- CDS 3 — по умолчанию inline=true: бейдж рендерился inline-блоком рядом с контентом -->
<CdsBadge :content="5">
  <CdsFunctionalButton icon="notification" />
</CdsBadge>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — по умолчанию inline=false: бейдж абсолютно позиционируется над контентом.
     Чтобы вернуть прежнее поведение — указать inline явно. -->
<CdsBadge :content="5" inline>
  <CdsFunctionalButton icon="notification" />
</CdsBadge>
```

**Действие:** проверить все использования `CdsBadge` без явного `inline`. Если требуется прежнее inline-поведение — добавить пропс `inline`. Если нужен бейдж-«накладка» — оставить как есть (теперь это поведение по умолчанию, см. `defineLocationProps({ location: 'top end' })`).

<!-- entry-meta: id=cdsbadge-inline-default-changed; severity=breaking; component=CdsBadge -->

### CdsBreadcrumbsItem

#### Пропс `text` переименован в `title`

> 🔁 **RENAMED**

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<cds-breadcrumbs-item text="Каталог" to="/catalog" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<cds-breadcrumbs-item title="Каталог" to="/catalog" />
```

**Действие:** переименуйте пропс `text` → `title` на всех использованиях `CdsBreadcrumbsItem`. Найти: `grep -rn "cds-breadcrumbs-item" | grep "text="`.

<!-- entry-meta: id=cdsbreadcrumbsitem-text-to-title; severity=renamed; component=CdsBreadcrumbsItem -->

#### Удалён устаревший пропс `currentPage`

> ⚠️ **BREAKING**

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<cds-breadcrumbs-item text="Текущая страница" current-page />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<cds-breadcrumbs-item title="Текущая страница" disabled />
```

**Действие:** замените `current-page` на `disabled` (неактивная/текущая страница) либо `active` (подсветка текущего маршрута). В CDS 3 пропс уже выводил `[CDS UPGRADE]` warning через `deprecate('currentPage', 'disabled')`; в CDS 4 он удалён полностью.

<!-- entry-meta: id=cdsbreadcrumbsitem-currentpage-removed; severity=breaking; component=CdsBreadcrumbsItem -->

### CdsButton

#### Удалён автоматический отступ между соседними кнопками

> ⚠️ **BREAKING** — глобальное CSS-правило, добавлявшее `margin-left` между соседними кнопками, было помечено `@deprecated` ещё в CDS 3 и в CDS 4 удалено полностью.

**Было (CDS 3):**

```scss
// CDS 3 — глобальное правило в CdsButton.scss (@deprecated)
.cds-button + .cds-button:not(.cds-functional-button) {
  margin-left: var(--cds-spacing-200);
}
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — отступ задаёт контейнер -->
<div style="display: flex; gap: var(--cds-spacing-200)">
  <CdsButton>Отменить</CdsButton>
  <CdsButton>Сохранить</CdsButton>
</div>
```

**Действие:** найдите группы соседних кнопок, полагавшиеся на автоматический отступ, и задайте расстояние явно на контейнере (`display: flex` + `gap`). Поиск кандидатов: `rg -lU '</(cds-button|CdsButton)>\s*<(cds-button|CdsButton)' src/`.

<!-- entry-meta: id=cdsbutton-adjacent-margin-removed; severity=breaking; component=CdsButton -->

#### `appearance` → `variant` + `color`

> 🟠 **DEPRECATED** — вид и цвет кнопки разведены на два пропа: `variant` (как нарисована) и `color` (каким цветом). `appearance` работает и выводит пару по таблице, а в консоли разработки один раз на значение пишет `[CDS UPGRADE] 'appearance="…"' is deprecated, use 'variant="…" color="…"' instead.` Так же работают `CdsButtonGroup` и `CdsButtonToggle`.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<cds-button appearance="primary" text="Сохранить" />
<cds-button appearance="tertiary" text="Отмена" />
<cds-button appearance="transparent" text="Подробнее" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — solid + brand по умолчанию -->
<CdsButton text="Сохранить" />
<CdsButton variant="soft" color="neutral" text="Отмена" />
<CdsButton variant="ghost" text="Подробнее" />
```

| `appearance`  | `variant` | `color`   |
|---------------|-----------|-----------|
| `primary`     | `solid`   | `brand`   |
| `secondary`   | `soft`    | `brand`   |
| `tertiary`    | `soft`    | `neutral` |
| `inverse`     | `solid`   | `inverse` |
| `transparent` | `ghost`   | `brand`   |

**Действие:** замените `appearance` по таблице; найти места: `rg -n 'appearance=' src/`. Явные `variant`/`color` важнее `appearance`. Если вместе с `appearance` задан `color`, вид берётся из `appearance`: `secondary` + `color` даёт бледный `soft`. Для насыщенной заливки укажите `variant="solid"`.

<!-- entry-meta: id=cdsbutton-appearance-to-variant-color; severity=deprecation; component=CdsButton -->

#### SASS: `$button-appearances` → `$button-colors`

> ⚠️ **BREAKING** — цвета кнопки в SASS задаются не по состояниям каждого `appearance`, а слотами цветовой роли. Ховер, нажатие и недоступность строит плёнка состояний, поэтому ключей `hover` / `active` / `disabled` в карте больше нет. `$button-toggle-appearances` тоже удалена.

**Было (CDS 3):**

```scss
// CDS 3
$button-appearances: (
  primary: (
    'background': rgb(var(--cds-color-brand-primary)),
    'color': …,
    'hover': …,
    // …
  ),
);
```

**Стало (CDS 4):**

```scss
// CDS 4
@use '@central-design-system/components/styles' with (
  $button-colors: (
    brand: (
      'fill': …,      // заливка solid
      'on-fill': …,   // текст на заливке
      'soft': …,      // фон soft
      'on-soft': …,   // текст на soft
      'content': …,   // текст outline / surface / ghost
      'line': …,      // рамка outline / surface
      'film': …,      // плёнка состояний
    ),
  )
);
```

**Действие:** если вы перекрашивали кнопку через `$button-appearances`, переопределите слоты в `$button-colors`, а состояния не задавайте. `with` заменяет карту целиком, поэтому передавайте **все** роли (`brand` / `accent` / `neutral` / `danger` / `inverse`) со всеми семью слотами — роль, которой нет в карте, теряет класс `cds-button--color-<роль>`, а без слота `film` пропадает ховер. Перекрасить одну роль проще CSS-переменными, без SASS:

```css
.cds-button--color-brand {
  --cds-button-color-fill: var(--cds-color-brand-secondary);
  --cds-button-color-on-fill: var(--cds-color-content-primary);
}
```

Разовый цвет — пропом `color`.

<!-- entry-meta: id=cdsbutton-sass-appearances-to-colors; severity=breaking; component=CdsButton -->

#### Удалена константа `CdsButton.constants.appearances`

> ⚠️ **BREAKING** — список значений `appearance` в константах кнопки удалён вместе с переходом на `variant` + `color` (в CDS 3 констант не было, изменение затрагивает только код на альфах CDS 4). Вместо него — `CdsButton.constants.variants` и `CdsButton.constants.colors`, те же массивы экспортируются из пакета как `availableVariants` и `availableColorRoles`.

**Было (CDS 4 alpha):**

```ts
// CDS 4 alpha
import { CdsButton } from '@central-design-system/components';

CdsButton.constants.appearances; // ['primary', 'secondary', 'tertiary', 'inverse']
```

**Стало (CDS 4):**

```ts
// CDS 4
import { availableColorRoles, availableVariants, CdsButton } from '@central-design-system/components';

CdsButton.constants.variants; // ['solid', 'soft', 'outline', 'surface', 'ghost']
CdsButton.constants.colors; // ['brand', 'accent', 'neutral', 'danger', 'inverse']
availableVariants; // то же, что CdsButton.constants.variants
availableColorRoles; // то же, что CdsButton.constants.colors
```

**Действие:** найдите обращения `rg -n 'constants\.appearances' src/` и перейдите на перебор `variants` × `colors`; соответствие старых значений — таблица в записи «`appearance` → `variant` + `color`» выше.

<!-- entry-meta: id=cdsbutton-constants-appearances-removed; severity=breaking; component=CdsButton -->

### CdsCard

#### Удалены пропсы `interactive` / `selected`

> ⚠️ **BREAKING** — модель кликабельности и выбора переработана. Кликабельность теперь включается пропсом `link` (или автоматически при `href` / `to` / членстве в `CdsCardGroup`), а выбранное состояние управляется только через `CdsCardGroup` + `value`.

**Было (CDS 3):**

```html
<!-- CDS 3 — interactive делал карточку кликабельной, selected — выбранной -->
<cds-card interactive :selected="isSelected" @click="onClick">…</cds-card>

<!-- выбор в группе -->
<cds-card-group v-model="selected" multiple>
  <cds-card :value="1">…</cds-card>
</cds-card-group>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — кликабельность через link (или href/to/членство в группе) -->
<CdsCard link @click="onClick">…</CdsCard>

<!-- выбор управляется CdsCardGroup + value; standalone-проп selected удалён -->
<CdsCardGroup v-model="selected" multiple>
  <CdsCard :value="1">…</CdsCard>
</CdsCardGroup>
```

**Действие:** заменить `interactive` на `link` (либо положиться на `href` / `to` / членство в `CdsCardGroup` — карточка станет кликабельной автоматически). Убрать standalone-проп `selected`: выбранное состояние теперь задаётся группой `CdsCardGroup` через `v-model` + `value` (визуально — класс из `selectedClass`). Нативный `@click` на `CdsCard` продолжает работать. Поиск: `grep -rnE "cds-card[^>]*(interactive|selected)" src/`.

> ℹ️ Событие `group:selected` убрано из публичного API `CdsCard` (в CDS 3 было объявлено в `emits`, в CDS 4 отсутствует в типах / `meta.json`), но всё ещё эмитится общим composable `useGroupItem` — существующие слушатели `@group:selected` продолжают срабатывать. Рекомендуется наблюдать за выбором на уровне группы: через `v-model` (`update:modelValue`) на `CdsCardGroup`.

<!-- entry-meta: id=cdscard-interactive-selected-removed; severity=breaking; component=CdsCard -->

### CdsCheckbox

#### Компонент-обёртка `CdsCheckboxGroup` удалён

> ⚠️ **BREAKING** — отдельного компонента `CdsCheckboxGroup` больше нет. Группа собирается из `CdsLabel`, `CdsDescription` и нескольких `CdsCheckbox` с общим `v-model`-массивом.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<script setup lang="ts">
import { ref } from 'vue';

const selected = ref(['first']);
</script>

<template>
  <cds-checkbox-group
    v-model="selected"
    label="Заголовок группы чекбоксов"
    description="Вспомогательное описание"
  >
    <cds-checkbox label="Значение чекбокса 1" value="first" />
    <cds-checkbox label="Значение чекбокса 2" value="second" />
    <cds-checkbox label="Значение чекбокса 3" value="third" />
  </cds-checkbox-group>
  <div>{{ selected }}</div>
</template>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<script setup lang="ts">
import { ref } from 'vue';

const selected = ref(['first']);
</script>

<template>
  <div class="w-full">
    <CdsLabel class="mb-1">Заголовок группы чекбоксов</CdsLabel>
    <CdsDescription class="mb-1">Вспомогательное описание</CdsDescription>
    <div class="flex flex-col gap-2">
      <CdsCheckbox v-model="selected" label="Значение чекбокса 1" hide-details value="first" />
      <CdsCheckbox v-model="selected" label="Значение чекбокса 2" hide-details value="second" />
      <CdsCheckbox v-model="selected" label="Значение чекбокса 3" hide-details value="third" />
    </div>
    <p>{{ selected }}</p>
  </div>
</template>
```

**Действие:** убрать обёртку `<cds-checkbox-group>` и заменить её связкой `CdsLabel` + `CdsDescription` + flex-контейнер с обычными `CdsCheckbox`. На каждом чекбоксе укажите общий массив в `v-model`, уникальный `value` и `hide-details`, чтобы убрать индивидуальные слоты описаний. Пример — `packages/components/src/components/CdsCheckbox/docs/CdsCheckbox.stories.ts` (story `Group`). Поиск использований: `grep -rn "cds-checkbox-group\|CdsCheckboxGroup" src/`.

<!-- entry-meta: id=cdscheckbox-checkboxgroup-removed; severity=breaking; component=CdsCheckbox -->

#### Изменён exposed-API

> ⚠️ **BREAKING** — вместо `id` / `isGroup` / `validationRef` компонент отдаёт унифицированный validation-API.

**Было (CDS 3):**

```ts
// CDS 3
const cb = ref();
cb.value.validationRef; // инстанс CdsInput
cb.value.isGroup;       // находится ли чекбокс в группе
```

**Стало (CDS 4):**

```ts
// CDS 4 — методы и флаги валидации
const cb = ref();
cb.value.validate();        // запуск валидации
cb.value.reset();           // сброс значения
cb.value.resetValidation(); // сброс ошибок
cb.value.isValid;           // Ref<boolean | null>
```

**Действие:** заменить обращения к `ref.id` / `ref.isGroup` / `ref.validationRef` на методы и флаги валидации (`validate`, `reset`, `resetValidation`, `isValid`, `isDirty`, `isValidating`, `isDisabled`, `isReadonly`, `isPure`).

<!-- entry-meta: id=cdscheckbox-exposed-api-changed; severity=breaking; component=CdsCheckbox -->

### CdsContentSwitcher

#### Компонент `CdsContentSwitcher` удалён — используйте `CdsTabs`

> ⚠️ **BREAKING** — `CdsContentSwitcher` (и `CdsContentSwitcherItem`) был помечен `deprecated` ещё в CDS 3 (обёртка над табами) и удалён в CDS 4. Замена — `CdsTabs` / `CdsTab` (бывший `CdsTabsV2`, см. [CdsTabsV2](#cdstabsv2)).

**Было (CDS 3):**

```html
<!-- CDS 3 — CdsContentSwitcher был помечен deprecated -->
<script setup lang="ts">
import { CdsContentSwitcher, CdsContentSwitcherItem } from '@central-design-system/components';
import { ref } from 'vue';

const model = ref(0);
</script>

<template>
  <cds-content-switcher v-model="model">
    <cds-content-switcher-item>Россия</cds-content-switcher-item>
    <cds-content-switcher-item>Египет</cds-content-switcher-item>
    <cds-content-switcher-item>Аргентина</cds-content-switcher-item>
  </cds-content-switcher>
</template>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — вместо CdsContentSwitcher используйте CdsTabs + CdsTab -->
<script setup lang="ts">
import { CdsTabs, CdsTab } from '@central-design-system/components';
import { ref } from 'vue';

const model = ref('ru');
</script>

<template>
  <CdsTabs v-model="model" grow>
    <CdsTab value="ru">Россия</CdsTab>
    <CdsTab value="eg">Египет</CdsTab>
    <CdsTab value="ar">Аргентина</CdsTab>
  </CdsTabs>
</template>
```

**Действие:** заменить `CdsContentSwitcher` → `CdsTabs` и `CdsContentSwitcherItem` → `CdsTab` (включая kebab-case `cds-content-switcher` → `cds-tabs`, `cds-content-switcher-item` → `cds-tab`). Чтобы табы занимали всё доступное пространство, как `CdsContentSwitcher` по умолчанию, добавьте проп `grow`. В CDS 3 компонент выводил в консоль `[CDS UPGRADE]` warning (`deprecate()`); в CDS 4 он удалён. Поиск: `grep -rnE "CdsContentSwitcher|cds-content-switcher" src/`.

<!-- entry-meta: id=cdscontentswitcher-removed; severity=breaking; component=CdsContentSwitcher -->

### CdsDrawer

#### `v-model` управляет видимостью панели и на широком экране

> ⚠️ **BREAKING** — `false` больше не игнорируется на экранах от 1056 px.

**Было (CDS 3):**

```vue
<!-- CDS 3 -->
<script setup>
const drawer = ref(false); // для мобильной кнопки-бургера
</script>

<template>
  <!-- на широком экране панель видна при любом значении drawer -->
  <CdsDrawer v-model="drawer">…</CdsDrawer>
</template>
```

**Стало (CDS 4):**

```vue
<!-- CDS 4 -->
<script setup>
// null — панель сама открыта на широком экране и закрыта на узком
const drawer = ref<boolean | null>(null);
</script>

<template>
  <!-- false скрывает панель на любой ширине и освобождает место в макете -->
  <CdsDrawer v-model="drawer">…</CdsDrawer>
</template>
```

**Действие:** если `v-model` обычной панели (без `permanent` / `temporary`) стартует с `false` в расчёте на то, что на десктопе панель всё равно видна, — заменить начальное значение на `null` (или убрать `v-model`) или на `true`. При переходе через 1056 px панель теперь сама меняет `v-model` (закрывается при сужении, открывается при расширении) — если это мешает, добавить `disable-resize-watcher`. `permanent` на узком экране теперь занимает место в макете, а не накрывает контент. Поиск: `grep -rnE "<CdsDrawer[^>]*(v-model|:model-value)" src/`.

<!-- entry-meta: id=cdsdrawer-v-model-controls-visibility; severity=breaking; component=CdsDrawer -->

### CdsForm

#### Изменён exposed-API — убраны обёртки `form` / `formRef`

> ⚠️ **BREAKING** — методы валидации и состояние доступны напрямую через ref.

**Было (CDS 3):**

```ts
// CDS 3
const formRef = ref();
// exposed: { ...form, form, formRef }
formRef.value.validate();
formRef.value.form;    // объект формы
formRef.value.formRef; // ссылка на <form>
```

**Стало (CDS 4):**

```ts
// CDS 4
const formRef = ref();
// плоский набор — без обёрток form / formRef
formRef.value.validate();
formRef.value.reset();
formRef.value.resetValidation();
formRef.value.isValid; // isValidating / isDisabled / isReadonly, errors / items
```

**Действие:** убрать обращения к `formRef.value.form` и `formRef.value.formRef` — методы (`validate` / `reset` / `resetValidation`) и состояние (`isValid` / `isValidating` / `isDisabled` / `isReadonly`, `errors` / `items`) доступны прямо на ref формы. Поиск: `grep -rnE "\.(form|formRef)\b" src/`.

<!-- entry-meta: id=cdsform-exposed-api; severity=breaking; component=CdsForm -->

### CdsIcon

#### Удалён устаревший пропс `invertColor`

> ⚠️ **BREAKING** — инверсия цвета через `invertColor` убрана; цвет иконки задаётся цветовыми пропсами.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsIcon name="add" invert-color />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<CdsIcon icon="add" color="content-inverse" />
```

**Действие:** убрать проп `invertColor` у `CdsIcon` и задавать цвет через `color` / `baseColor` / `textColor`. Поиск: `grep -rnE "<[Cc]ds[- ]?[Ii]con[^>]*invert-?[Cc]olor" src/`.

<!-- entry-meta: id=cdsicon-invertcolor-removed; severity=breaking; component=CdsIcon -->

### CdsList

#### Удалён устаревший пропс `invertColor`

> ⚠️ **BREAKING** — инверсия цвета через `invertColor` убрана; цвет списка задаётся цветовыми пропсами.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<cds-list invert-color :items="items" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — цвет задаётся цветовыми пропсами -->
<CdsList :items="items" color="content-inverse" bg-color="surface-primary" />
```

**Действие:** убрать `invert-color` / `invertColor` у `CdsList`; для инверсного/произвольного оформления использовать `color` / `baseColor` / `bgColor` / `textColor`. Поиск: `grep -rnE "cds-list[^>]*invert-?[Cc]olor|CdsList[^>]*invertColor" src/`.

<!-- entry-meta: id=cdslist-invertcolor-removed; severity=breaking; component=CdsList -->

#### `CdsListItem`: удалён пропс `isClickable`

> ⚠️ **BREAKING** — принудительная кликабельность через `isClickable` убрана; теперь включается пропсом `link` (либо автоматически при `href` / `to` или наличии `value` внутри списка).

**Было (CDS 3):**

```html
<!-- CDS 3 — isClickable принудительно делал элемент кликабельным -->
<cds-list-item is-clickable title="Пункт" @click="onClick" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — кликабельность через link -->
<CdsListItem link title="Пункт" @click="onClick" />
```

**Действие:** заменить `is-clickable` / `isClickable` на `link`. Если у элемента есть `href` / `to` или `value` внутри `CdsList` — он станет кликабельным автоматически. Поиск: `grep -rnE "cds-list-item[^>]*is-clickable|CdsListItem[^>]*isClickable" src/`.

<!-- entry-meta: id=cdslistitem-isclickable-removed; severity=breaking; component=CdsListItem -->

#### `CdsListItem`: изменён exposed-API

> ⚠️ **BREAKING** — вместо `isActive` / `isIndeterminate` компонент отдаёт `isActivated` / `activate`; поле `isIndeterminate` удалено.

**Было (CDS 3):**

```ts
// CDS 3 — exposed: isActive, isSelected, isIndeterminate, select
const item = ref();
item.value.isActive;
item.value.isIndeterminate;
```

**Стало (CDS 4):**

```ts
// CDS 4 — isActive → isActivated, добавлен activate(); isIndeterminate удалён
const item = ref();
item.value.isActivated;
item.value.activate(true);
item.value.isSelected;
item.value.select(true);
```

**Действие:** заменить обращения к `isActive` на `isActivated`, для смены активного состояния использовать `activate(value)`; `isIndeterminate` больше не экспонируется. Дополнительно доступны `isGroupActivator` и контексты `list` / `root`.

<!-- entry-meta: id=cdslistitem-exposed-api-changed; severity=breaking; component=CdsListItem -->

#### `CdsListGroup`: удалён слот `title`, изменён смысл пропа `title`

> ⚠️ **BREAKING** — В CDS 3 `title` (и слот `#title`) рисовал **отдельную статичную некликабельную подпись** над активатором (блок `.cds-list-group__title`). В CDS 4 этот блок и слот удалены, а проп `title` стал **текстом кликабельного активатора**. Статичная подпись группы теперь делается компонентом `CdsListSubheader`.

**Было (CDS 3):**

```html
<!-- CDS 3 — title/#title = статичная подпись над кликабельным #activator -->
<cds-list-group>
  <template #title>Заголовок группы</template>
  <template #activator="{ props }">
    <cds-list-item v-bind="props" title="Раскрыть" />
  </template>
  <cds-list-item title="Пункт" />
</cds-list-group>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — статичная подпись через CdsListSubheader; title = текст активатора -->
<CdsListSubheader title="Заголовок группы" />
<CdsListGroup title="Раскрыть">
  <CdsListItem title="Пункт" />
</CdsListGroup>
```

**Действие:** статичную подпись группы (бывший блок `.cds-list-group__title` / слот `#title`) вынести в отдельный `<CdsListSubheader title="…" />`. Учтите, что проп `title` у `CdsListGroup` теперь задаёт текст кликабельного активатора, а не статичную подпись; для полностью кастомного активатора используйте слот `#activator`. Поиск: `grep -rn "cds-list-group" src/`.

<!-- entry-meta: id=cdslistgroup-title-slot-removed; severity=breaking; component=CdsListGroup -->

#### `CdsListGroup`: изменён exposed-API

> ⚠️ **BREAKING** — вместо `id` / `isExpandable` группа отдаёт только `isOpen`.

**Было (CDS 3):**

```ts
// CDS 3 — exposed: id, isOpen, isExpandable
const group = ref();
group.value.id;
group.value.isExpandable;
```

**Стало (CDS 4):**

```ts
// CDS 4 — только isOpen
const group = ref();
group.value.isOpen;
```

**Действие:** убрать обращения к `id` / `isExpandable` у `CdsListGroup` — публично экспонируется только `isOpen`.

<!-- entry-meta: id=cdslistgroup-exposed-api-changed; severity=breaking; component=CdsListGroup -->

#### Изменён payload событий `click:open` / `click:select`

> ⚠️ **BREAKING** — из payload убрано поле `event`; передаётся `{ id, value, path }`.

**Было (CDS 3):**

```ts
// CDS 3 — payload: { id, value, path, event }
function onOpen({ id, value, path, event }) {}
```

**Стало (CDS 4):**

```ts
// CDS 4 — payload без event: { id, value, path }
function onOpen({ id, value, path }) {}
```

**Действие:** убрать обращение к полю `event` в обработчиках `@click:open` / `@click:select` у `CdsList`. Поиск: `grep -rnE "click:(open|select)" src/`.

<!-- entry-meta: id=cdslist-click-events-payload-changed; severity=breaking; component=CdsList -->

### CdsModal

#### Удалены пропсы `loading` и `dismissBtn` (и слот `dismissBtn`)

> ⚠️ **BREAKING** — `dismissBtn` был помечен deprecated ещё в CDS 3; `loading` удалён вместе с ним. Лоадер и кнопка закрытия добавляются в контент вручную. Остальной API (`fullscreen`, `scrollable`, `size`, `persistent`, активаторы) совместим с CDS 3.

**Было (CDS 3):**

```html
<!-- CDS 3 — лоадер и кнопка закрытия рендерились самим компонентом -->
<cds-modal v-model="modal" :loading="isLoading" dismiss-btn>
  <h4>Заголовок</h4>
  <p>Контент модального окна</p>
</cds-modal>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — добавьте CdsLoader и CdsFunctionalButton в контент сами -->
<CdsModal v-model="modal">
  <CdsLoader v-if="isLoading" fixed overlay />

  <div class="flex items-center justify-between">
    <span class="h4">Заголовок</span>
    <CdsFunctionalButton icon="remove" @click="modal = false" />
  </div>

  <p>Контент модального окна</p>
</CdsModal>
```

**Действие:** удалить `loading` / `dismiss-btn` (и слот `#dismissBtn`) из использований `CdsModal`; лоадер (`CdsLoader fixed overlay`) и кнопку закрытия (`CdsFunctionalButton icon="remove"`) разместить в контенте модалки. Поиск: `grep -rnE "cds-modal[^>]*(loading|dismiss-btn)|CdsModal[^>]*(loading|dismissBtn)" src/`.

<!-- entry-meta: id=cdsmodal-loading-dismissbtn-removed; severity=breaking; component=CdsModal -->

#### Изменён exposed-API

> ⚠️ **BREAKING** — вместо ссылки `overlay` компонент отдаёт элементы и методы оверлея напрямую.

**Было (CDS 3):**

```ts
// CDS 3
const modal = ref();
modal.value.overlay; // инстанс CdsOverlay
```

**Стало (CDS 4):**

```ts
// CDS 4
const modal = ref();
modal.value.contentEl;            // DOM-элемент контента
modal.value.activatorEl;          // DOM-элемент активатора
modal.value.updateLocation?.(e);  // пересчёт позиции
```

**Действие:** заменить обращения к `ref.overlay` на новые exposed-поля (`contentEl`, `activatorEl`, `rootEl`, `updateLocation`, `animateClick`).

<!-- entry-meta: id=cdsmodal-exposed-api-changed; severity=breaking; component=CdsModal -->

### CdsNotificationAlert

#### Компонент-обёртка `CdsNotificationAlert` — временный мост, мигрируйте на `CdsToast`

> 🟠 **DEPRECATED** — в CDS 4 компонент перенесён как мост для плавной миграции: сохранён API-стиль (`timeout`, `location`, `status`, `title`, `text`, `closable`, слоты `activator` / `actions`), но внутри теперь рендерит `CdsNotification` (`variant="important"`) в `CdsOverlay`. Работает в 4.x, будет удалён в 5.x.

**Было (CDS 3):**

```html
<!-- CDS 3 — обёртка-тост поверх CdsNotification -->
<cds-notification-alert v-model="active" title="Заголовок" text="Описание уведомления" status="info" location="top left" :timeout="5000" closable>
  <template #actions>
    <cds-button>Кнопка</cds-button>
  </template>
</cds-notification-alert>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — рекомендуется CdsToast (для очереди/стека — CdsToastQueue) -->
<CdsToast v-model="active" title="Заголовок" text="Описание уведомления" status="info" location="top left" :timeout="5000">
  <template #actions="{ isActive }">
    <CdsButton @click="isActive.value = false">Кнопка</CdsButton>
  </template>
</CdsToast>
```

**Действие:** `CdsNotificationAlert` продолжает работать в 4.x (рендерит `CdsNotification variant="important"` внутри `CdsOverlay`), но в dev-консоли выводит `[CDS UPGRADE] 'CdsNotificationAlert' is deprecated, use 'CdsToast' instead.` (см. `deprecate()` в `src/utils/dom/console.ts`) и будет удалён. Перейдите на `CdsToast`; для вертикального стека нескольких уведомлений используйте `CdsToast` + `CdsToastQueue`. Поиск: `grep -rnE "CdsNotificationAlert|cds-notification-alert" src/`.

<!-- entry-meta: id=cdsnotificationalert-deprecated-use-cdstoast; severity=deprecation; component=CdsNotificationAlert -->

### CdsRadioButton

#### Компонент `CdsRadioButton` переименован в `CdsRadioGroup`

> 🔁 **RENAMED** — публичный API (пропсы, слоты, события) не изменился, переименовано только имя компонента-обёртки и путь импорта/тега.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<script setup lang="ts">
import { CdsRadio, CdsRadioButton } from '@central-design-system/components';
import { ref } from 'vue';

const selected = ref('val-1');
</script>

<template>
  <CdsRadioButton v-model="selected" label="Заголовок" description="Описание">
    <CdsRadio label="Значение радио-кнопки 1" value="val-1" />
    <CdsRadio label="Значение радио-кнопки 2" value="val-2" />
    <CdsRadio label="Значение радио-кнопки 3" value="val-3" />
  </CdsRadioButton>
</template>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<script setup lang="ts">
import { CdsRadio, CdsRadioGroup } from '@central-design-system/components';
import { ref } from 'vue';

const selected = ref('val-1');
</script>

<template>
  <CdsRadioGroup v-model="selected" label="Заголовок" description="Описание">
    <CdsRadio label="Значение радио-кнопки 1" value="val-1" />
    <CdsRadio label="Значение радио-кнопки 2" value="val-2" />
    <CdsRadio label="Значение радио-кнопки 3" value="val-3" />
  </CdsRadioGroup>
</template>
```

**Действие:** заменить импорт и тег `CdsRadioButton` → `CdsRadioGroup` (включая kebab-case вариант `cds-radio-button` → `cds-radio-group`). Поиск использований: `grep -rnE "CdsRadioButton|cds-radio-button" src/`. Дочерние `<CdsRadio>` остаются без изменений.

<!-- entry-meta: id=cdsradiogroup-renamed-from-cdsradiobutton; severity=renamed; component=CdsRadioGroup -->

#### Новые пропсы (цвета, иконки, inline, size)

> ✨ **NEW** — помимо переименования компонент получил аддитивные пропсы из унифицированного input-API (миграция не требуется).

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsRadioButton v-model="selected" label="Заголовок" description="Описание" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<CdsRadioGroup
  v-model="selected"
  label="Заголовок"
  description="Описание"
  color="surface-primary"
  inline
  size="lg"
/>
```

**Действие:** миграция не требуется. Новые возможности: цветовые пропсы `color` / `baseColor` / `activeColor` / `textColor` / `iconColor`, иконочные `prependIcon` / `appendIcon` / `trueIcon` / `falseIcon`, `inline`, `size` и exposed-методы валидации (`validate` / `reset` / `resetValidation`).

<!-- entry-meta: id=cdsradiogroup-new-props; severity=new; component=CdsRadioGroup -->

### CdsSelect

#### Компонент `CdsDropdown` переименован в `CdsSelect`

> 🔁 **RENAMED** — богатый выпадающий список с кастомным меню (`CdsMenu`), множественным выбором и фильтрацией из CDS 3 `CdsDropdown` теперь называется `CdsSelect`.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<script setup lang="ts">
import { CdsDropdown } from '@central-design-system/components';
import { ref } from 'vue';

const selected = ref(null);
const items = ref(['Первый', 'Второй', 'Третий']);
</script>

<template>
  <CdsDropdown v-model="selected" :items="items" label="Выберите значение" />
</template>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<script setup lang="ts">
import { CdsSelect } from '@central-design-system/components';
import { ref } from 'vue';

const selected = ref(null);
const items = ref(['Первый', 'Второй', 'Третий']);
</script>

<template>
  <CdsSelect v-model="selected" :items="items" label="Выберите значение" />
</template>
```

**Действие:** заменить импорт и тег `CdsDropdown` → `CdsSelect` (включая kebab-case `cds-dropdown` → `cds-select`). Поиск использований: `grep -rnE "CdsDropdown|cds-dropdown" src/`.

<!-- entry-meta: id=cdsselect-renamed-from-cdsdropdown; severity=renamed; component=CdsSelect -->

#### Нативный `CdsSelect` (CDS 3) заменён пропсом `native-select`

> ⚠️ **BREAKING** — старый `CdsSelect` из CDS 3 (обёртка над нативным HTML `<select>`, был помечен deprecated) удалён. Его имя теперь занимает бывший `CdsDropdown`. Чтобы получить нативный выпадающий список, используйте новый `CdsSelect` с пропсом `native-select`.

**Было (CDS 3):**

```html
<!-- CDS 3 — CdsSelect рендерил нативный <select> -->
<script setup lang="ts">
import { CdsSelect } from '@central-design-system/components';
import { ref } from 'vue';

const selected = ref(null);
const items = ref(['Первый', 'Второй', 'Третий']);
</script>

<template>
  <CdsSelect v-model="selected" :items="items" label="Выберите значение" />
</template>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — нативный список доступен через native-select -->
<script setup lang="ts">
import { CdsSelect } from '@central-design-system/components';
import { ref } from 'vue';

const selected = ref(null);
const items = ref(['Первый', 'Второй', 'Третий']);
</script>

<template>
  <CdsSelect v-model="selected" :items="items" native-select label="Выберите значение" />
</template>
```

**Действие:** использования старого `CdsSelect` из CDS 3 дополнить пропсом `native-select`, чтобы сохранить нативное поведение `<select>`. Без этого пропса `CdsSelect` в CDS 4 — это богатый список с кастомным меню (бывший `CdsDropdown`). Проверьте каждое использование `CdsSelect` и решите, какое поведение требуется: `grep -rnE "CdsSelect|cds-select" src/`.

<!-- entry-meta: id=cdsselect-native-select-prop; severity=breaking; component=CdsSelect -->

### CdsProgress

#### Компонент `CdsProgress` переименован в `CdsProgressBar`

> 🔁 **RENAMED** — публичный API (пропсы, слоты, события) не изменился, переименовано только имя компонента и путь импорта/тега.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<script setup lang="ts">
import { CdsProgress } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref(35);
</script>

<template>
  <CdsProgress v-model="value" />
</template>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<script setup lang="ts">
import { CdsProgressBar } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref(35);
</script>

<template>
  <CdsProgressBar v-model="value" />
</template>
```

**Действие:** заменить импорт и тег `CdsProgress` → `CdsProgressBar` (включая kebab-case вариант `cds-progress` → `cds-progress-bar`). Поиск использований: `grep -rnE "CdsProgress|cds-progress-bar" src/`.

<!-- entry-meta: id=cdsprogressbar-renamed-from-cdsprogress; severity=renamed; component=CdsProgressBar -->

#### Новые пропсы стилизации

> ✨ **NEW** — помимо переименования компонент получил набор аддитивных пропсов (миграция не требуется).

**Было (CDS 3):**

```html
<!-- CDS 3 — базовый прогресс-бар -->
<cds-progress v-model="value" :buffer-value="60" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — цвета, буфер, сегменты, полосы -->
<CdsProgressBar
  v-model="value"
  color="surface-primary"
  base-color="surface-tertiary"
  buffer-color="surface-secondary"
  variant="split"
  :chunk-count="10"
  striped
  rounded-bar
/>
```

**Действие:** миграция не требуется. Новые возможности: цветовые пропсы `color` / `baseColor` / `activeColor` / `textColor`, стилизация буфера `bufferColor` / `bufferOpacity`, сегментный режим `variant: 'split'` (`chunkCount` / `chunkGap` / `chunkWidth`), а также `striped` / `roundedBar` / `opacity`.

<!-- entry-meta: id=cdsprogressbar-styling-props; severity=new; component=CdsProgressBar -->

### CdsSlideGroup

#### Пропсы иконок стрелок прокрутки переименованы

> 🔁 **RENAMED** — иконки кнопок прокрутки задаются через `prevIcon` / `nextIcon` вместо `prependIcon` / `appendIcon`.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsSlideGroup prepend-icon="arrow-left" append-icon="arrow-right">
  <CdsSlideGroupItem v-for="i in items" :key="i" :value="i">{{ i }}</CdsSlideGroupItem>
</CdsSlideGroup>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<CdsSlideGroup prev-icon="chevron-left" next-icon="chevron-right">
  <CdsSlideGroupItem v-for="i in items" :key="i" :value="i">{{ i }}</CdsSlideGroupItem>
</CdsSlideGroup>
```

**Действие:** заменить `prepend-icon` / `append-icon` на `prev-icon` / `next-icon` у `CdsSlideGroup`; учесть, что дефолтные иконки изменены `arrow-left` / `arrow-right` → `chevron-left` / `chevron-right` (новая система иконок `IconValue`). Поиск: `grep -rnE "CdsSlideGroup[^>]*(prepend-icon|append-icon)" src/`.

<!-- entry-meta: id=cdsslidegroup-arrow-icon-props-renamed; severity=renamed; component=CdsSlideGroup -->

### CdsSlideView

#### Иконки стрелок `prevIcon` / `nextIcon` переведены на новую систему иконок

> ✨ **NEW** — имена пропсов `prevIcon` / `nextIcon` и дефолтные стрелки не изменились, но тип пропа теперь `IconValue` (без валидации по `allowedIcons`).

**Было (CDS 3):**

```html
<!-- CDS 3 — дефолты chevron-left / chevron-right, имя валидируется по allowedIcons -->
<CdsSlideView prev-icon="chevron-left" next-icon="chevron-right">
  <CdsSlideViewItem v-for="i in items" :key="i" :value="i">{{ i }}</CdsSlideViewItem>
</CdsSlideView>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — дефолты chevron-left / chevron-right, тип IconValue -->
<CdsSlideView prev-icon="chevron-left" next-icon="chevron-right">
  <CdsSlideViewItem v-for="i in items" :key="i" :value="i">{{ i }}</CdsSlideViewItem>
</CdsSlideView>
```

**Действие:** менять ничего не нужно: явные `prev-icon="chevron-left"` / `next-icon="chevron-right"` работают. Другую стрелку можно задать любым значением `IconValue`.

<!-- entry-meta: id=cdsslideview-arrow-icons-iconvalue; severity=new; component=CdsSlideView -->

### CdsStages

#### Компонент `CdsStages` помечен deprecated — переходите на `CdsSteps`

> 🟠 **DEPRECATED** — публичный API компонента не изменился (`items`, `current`, `finished`, exposed `isCurrent` / `isFinished` работают как в CDS 3), но сценарий полностью закрывает `CdsSteps`, поэтому новый код на `CdsStages` писать не нужно. Компонент остаётся рабочим во всей ветке 4.x и будет удалён в 5.0.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsStages :items="stages" :current="current" :finished="finished" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — шапка степпера без items работает как трекер статуса -->
<CdsSteps :model-value="current">
  <CdsStepsItem v-for="stage in stages" :key="stage.value" :value="stage.value" :title="stage.title" :error="stage.error" />
</CdsSteps>
```

**Действие:** `CdsStages` продолжает работать в 4.x, но в dev-консоли выводит `[CDS UPGRADE] 'CdsStages' is deprecated, use 'CdsSteps' instead.` (см. `deprecate()` в `src/utils/dom/console.ts`). Переходите на `CdsSteps`: без пропа `interactive` шаги некликабельны (дефолт `false`), `readonly` отключает переходы принудительно, а шапка без `items` рендерится без контентной части и кнопок навигации. Учтите, что вид отличается: `CdsStages` — стрелочная лента, `CdsSteps` — индикаторы с линией прогресса; для вертикального трекера есть проп `vertical`. Поиск: `grep -rnE "CdsStages|cds-stages" src/`.

<!-- entry-meta: id=cdsstages-deprecated-use-cdssteps; severity=deprecation; component=CdsStages -->

### CdsStatus

#### Значение `status="error"` переименовано в `status="danger"`

> 🔁 **RENAMED** — набор статусов выровнен с токенами `--cds-color-status-*`: вместо `error` теперь `danger`.

**Было (CDS 3):**

```html
<!-- CDS 3 — status: 'info' | 'success' | 'warning' | 'error' | 'progress' -->
<cds-status status="error" text="Ошибка" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — status: 'info' | 'success' | 'warning' | 'danger' | 'progress' -->
<CdsStatus status="danger" text="Ошибка" />
```

**Действие:** заменить `status="error"` на `status="danger"`. Поиск: `grep -rnE "cds-status[^>]*status=\"error\"|CdsStatus[^>]*status=\"error\"" src/`.

<!-- entry-meta: id=cdsstatus-status-error-to-danger; severity=renamed; component=CdsStatus -->

#### Булев проп `icon` заменён на `variant`

> ⚠️ **BREAKING** — вместо булева флага режима отображения теперь проп `variant: 'fill' | 'text'` (по умолчанию `fill`).

**Было (CDS 3):**

```html
<!-- CDS 3 — icon переключал режим: без него заливка-бейдж, с ним — иконка + нейтральный текст -->
<cds-status status="success" text="Готово" />
<cds-status icon status="success" text="Готово" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — режим задаётся через variant -->
<CdsStatus status="success" text="Готово" />
<CdsStatus variant="text" status="success" text="Готово" />
```

**Действие:** заменить булев `icon` на `variant="text"`. Заливку-бейдж (когда `icon` отсутствовал) менять не нужно — это дефолт `variant="fill"`. Поиск: `grep -rnE "cds-status[^>]*\bicon\b|CdsStatus[^>]*\bicon\b" src/`.

<!-- entry-meta: id=cdsstatus-icon-to-variant; severity=breaking; component=CdsStatus -->

### CdsSteps

#### Дефолт пропса `interactive` изменён с `true` на `false`

> ⚠️ **BREAKING** — по умолчанию шаги больше не кликабельны. В CDS 3 переход по клику работал из коробки, а отключался через `:interactive="false"`.

**Было (CDS 3):**

```html
<!-- CDS 3 — interactive по умолчанию true: шаги кликабельны из коробки -->
<cds-steps v-model="step">
  <cds-steps-item title="ФИО" text="Имя и фамилия" />
  <cds-steps-item title="Подтверждение" text="Код из смс" />
</cds-steps>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — interactive по умолчанию false: для кликов укажите проп явно -->
<CdsSteps v-model="step" interactive>
  <CdsStepsItem title="ФИО" text="Имя и фамилия" />
  <CdsStepsItem title="Подтверждение" text="Код из смс" />
</CdsSteps>
```

**Действие:** проверить все использования `CdsSteps`: где нужен переход по клику — добавить проп `interactive`; явные `:interactive="false"` можно удалить (теперь это поведение по умолчанию). Поиск: `grep -rnE "cds-steps|CdsSteps" src/`.

<!-- entry-meta: id=cdssteps-interactive-default-false; severity=breaking; component=CdsSteps -->

#### Проп `items`, контентная часть и кнопки навигации

> ✨ **NEW** — помимо шапки появились контентная часть (`CdsStepsView` / `CdsStepsViewItem`) и кнопки «Назад»/«Далее» (`CdsStepsActions`). Прежний способ с default-слотом и `CdsStepsItem` продолжает работать без изменений.

**Было (CDS 3):**

```html
<!-- CDS 3 — компонент рендерил только шапку шагов; контент и навигацию собирали вручную -->
<cds-steps v-model="step">
  <cds-steps-item title="ФИО" text="Имя и фамилия" />
  <cds-steps-item title="Подтверждение" text="Код из смс" />
</cds-steps>
<div v-if="step === 0">Контент первого шага</div>
<button @click="step++">Далее</button>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — при передаче items рендерятся шапка, контент шагов и кнопки навигации -->
<CdsSteps
  v-model="step"
  :items="[
    { title: 'ФИО', text: 'Имя и фамилия' },
    { title: 'Подтверждение', text: 'Код из смс' }
  ]"
>
  <template #item.1>Контент первого шага</template>
  <template #item.2>Контент второго шага</template>
</CdsSteps>
```

**Действие:** миграция не требуется — использование с default-слотом совместимо (без `items` контентная часть и кнопки не рендерятся). Новые возможности: пропсы `items` / `itemTitle` / `itemText` / `itemValue` / `itemProps`, `hideActions`, `prevText` / `nextText`, слоты `header-item(.{value})`, `item(.{value})`, `actions`, `prev`, `next`, методы `prev()` / `next()` через ref, субкомпоненты `CdsStepsView` / `CdsStepsViewItem` / `CdsStepsActions`.

<!-- entry-meta: id=cdssteps-items-view-actions; severity=new; component=CdsSteps -->

### CdsTabsV2

#### Компонент `CdsTabsV2` переименован в `CdsTabs`
#### Компонент `CdsTabV2` переименован в `CdsTab`

> 🔁 **RENAMED** — публичный API (пропсы, слоты, события) не изменился, переименовано только имя компонента и путь импорта/тега.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<script setup lang="ts">
import { CdsTabsV2, CdsTabV2 } from '@central-design-system/components';
</script>

<template>
  <CdsTabsV2>
    <CdsTabV2>Элемент 1</CdsTabV2>
    <CdsTabV2>Элемент 2</CdsTabV2>
    <CdsTabV2>Элемент 3</CdsTabV2>
  </CdsTabsV2>
</template>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<script setup lang="ts">
import { CdsTabs, CdsTab } from '@central-design-system/components';
</script>

<template>
  <CdsTabs>
    <CdsTab>Элемент 1</CdsTab>
    <CdsTab>Элемент 2</CdsTab>
    <CdsTab>Элемент 3</CdsTab>
  </CdsTabs>
</template>
```

**Действие:** заменить импорт и тег `CdsTabV2` → `CdsTab` (включая kebab-case вариант `cds-tabs-v2` → `cds-tabs`). Поиск использований: `grep -rnE "CdsTabsV2|cds-tabs-v2" src/`.
**Действие:** заменить импорт и тег `CdsTabV2` → `CdsTab` (включая kebab-case вариант `cds-tab-v2` → `cds-tab`). Поиск использований: `grep -rnE "CdsTabV2|cds-tab-v2" src/`.

<!-- entry-meta: id=cdstabs-renamed-from-cdstabsv2; severity=renamed; component=CdsTabs -->

#### Пропсы иконок стрелок прокрутки переименованы

> 🔁 **RENAMED** — иконки кнопок прокрутки табов задаются через `prevIcon` / `nextIcon` вместо `prependIcon` / `appendIcon`.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsTabsV2 prepend-icon="chevron-left" append-icon="chevron-right" :items="items" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<CdsTabs prev-icon="chevron-left" next-icon="chevron-right" :items="items" />
```

**Действие:** заменить `prepend-icon` / `append-icon` на `prev-icon` / `next-icon` у `CdsTabs`. Поиск: `grep -rnE "CdsTabs(V2)?[^>]*(prepend-icon|append-icon)" src/`.

<!-- entry-meta: id=cdstabs-arrow-icon-props-renamed; severity=renamed; component=CdsTabs -->

#### Новые пропсы (цвета, слайдер, режимы, слоты)

> ✨ **NEW** — помимо переименования компонент существенно расширен (миграция не требуется).

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsTabsV2 :items="items" grow />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<CdsTabs
  :items="items"
  color="surface-primary"
  slider-transition="grow"
  inset
  center-active
>
  <template #view>…</template>
</CdsTabs>
```

**Действие:** миграция не требуется. Новые возможности: цветовые пропсы `color` / `baseColor` / `activeColor` / `textColor`, настройка слайдера `hideSlider` / `sliderTransition` / `sliderTransitionDuration`, режимы `inset` / `fixedTabs` / `centerActive` / `mobile`, слоты `tab` / `item` / `view`.

<!-- entry-meta: id=cdstabs-new-props; severity=new; component=CdsTabs -->

### CdsTag

#### Событие `remove` переименовано в `click:close`

> 🔁 **RENAMED** — кнопку удаления теперь эмитит унифицированное событие `click:close`; проп `removable` сохранён как псевдоним `closable`.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsTag removable @remove="onRemove">Тег</CdsTag>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — removable = closable; событие переименовано -->
<CdsTag closable @click:close="onRemove">Тег</CdsTag>
```

**Действие:** заменить `@remove` на `@click:close`. Поиск: `grep -rnE "(cds-tag|CdsTag)[^>]*@remove" src/`. Дополнительно тегом теперь можно управлять через `v-model` (проп `modelValue`, при `false` тег скрыт).

<!-- entry-meta: id=cdstag-remove-to-clickclose; severity=renamed; component=CdsTag -->

#### Удалён слот `text`

> ⚠️ **BREAKING** — отдельного слота `text` больше нет; текст задаётся пропсами `text` / `content` или слотом по умолчанию.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsTag>
  <template #text>Метка</template>
</CdsTag>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — проп text/content или слот по умолчанию -->
<CdsTag text="Метка" />
<CdsTag>Метка</CdsTag>
```

**Действие:** заменить `<template #text>` на проп `text` (или `content`), либо на слот по умолчанию. Поиск: `grep -rn "cds-tag" src/ | grep "#text"`.

<!-- entry-meta: id=cdstag-text-slot-removed; severity=breaking; component=CdsTag -->

#### Иконки `prependIcon` / `appendIcon` переведены на новую систему иконок

> ⚠️ **BREAKING** — вместо строкового имени с валидацией по `allowedIcons` пропсы принимают `IconValue` и резолвятся через iconpacks (см. раздел [«Иконки»](#2-иконки)).

**Было (CDS 3):**

```html
<!-- CDS 3 — имя иконки валидировалось по allowedIcons -->
<CdsTag prepend-icon="bookmark" text="Метка" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — IconValue: имя из iconpack, компонент или булево -->
<CdsTag prepend-icon="bookmark" text="Метка" />
```

**Действие:** убедиться, что используемые имена иконок есть в подключённом iconpack (см. раздел «Иконки»). Синтаксис использования не меняется, но резолвинг и валидация теперь идут через новую систему иконок.

<!-- entry-meta: id=cdstag-icons-iconvalue; severity=breaking; component=CdsTag -->

### CdsTextArea

#### Удалён пропс `limit`

> ⚠️ **BREAKING** — в CDS 3 `limit` задавал одновременно ограничение ввода (`maxlength`) и максимум счётчика. В CDS 4 он удалён: ограничение ввода — нативный атрибут `maxlength`, счётчик — проп `counter` / `counterValue`.

**Было (CDS 3):**

```html
<!-- CDS 3 — limit = maxlength + максимум счётчика -->
<cds-text-area v-model="text" :limit="200" counter />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — maxlength ограничивает ввод, counter задаёт счётчик и его максимум -->
<CdsTextArea v-model="text" maxlength="200" :counter="200" />
```

**Действие:** убрать `:limit="N"`; ограничение ввода задать нативным `maxlength="N"`, а счётчик — пропсом `counter` (`boolean | number | string`; число/строка задаёт максимум) или `counterValue`. Поиск: `grep -rnE "cds-text-area[^>]*limit|CdsTextArea[^>]*limit" src/`.

<!-- entry-meta: id=cdstextarea-limit-removed; severity=breaking; component=CdsTextArea -->

#### Изменён exposed-API

> ⚠️ **BREAKING** — вместо `id` / `isFocused` / `fieldRef` / `textareaRef` / `validationRef` / `sizerRef` / `focus` / `blur` компонент отдаёт унифицированный validation-API и `controlRef` (как у `CdsInput`).

**Было (CDS 3):**

```ts
// CDS 3 — exposed: id, isFocused, fieldRef, textareaRef, validationRef, sizerRef, focus, blur
const area = ref();
area.value.textareaRef;   // <textarea>
area.value.validationRef; // инстанс CdsInput
area.value.focus();
```

**Стало (CDS 4):**

```ts
// CDS 4 — методы и флаги валидации + controlRef
const area = ref();
area.value.validate();        // запуск валидации
area.value.reset();           // сброс значения
area.value.resetValidation(); // сброс ошибок
area.value.isValid;           // isDirty / isDisabled / isReadonly / isPure / isValidating
area.value.controlRef;        // DOM-элемент контрола (<textarea>)
```

**Действие:** заменить обращения к `ref.textareaRef` / `ref.validationRef` / `ref.fieldRef` / `ref.sizerRef` / `ref.focus()` / `ref.blur()` на validation-API (`validate` / `reset` / `resetValidation`, флаги `isValid` / `isDirty` / `isValidating` / `isDisabled` / `isReadonly` / `isPure`) и `controlRef` для доступа к DOM-элементу поля.

<!-- entry-meta: id=cdstextarea-exposed-api-changed; severity=breaking; component=CdsTextArea -->

### CdsTextInput

#### Удалён пропс `limit`

> ⚠️ **BREAKING** — в CDS 3 `limit` задавал одновременно ограничение ввода (`maxlength`) и максимум счётчика. В CDS 4 он удалён: ограничение ввода — нативный атрибут `maxlength`, счётчик — проп `counter` / `counterValue`.

**Было (CDS 3):**

```html
<!-- CDS 3 — limit = maxlength + максимум счётчика -->
<cds-text-input v-model="text" :limit="60" counter />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — maxlength ограничивает ввод, counter задаёт счётчик и его максимум -->
<CdsTextInput v-model="text" maxlength="60" :counter="60" />
```

**Действие:** убрать `:limit="N"`; ограничение ввода задать нативным `maxlength="N"`, а счётчик — пропсом `counter` (`boolean | number | string`; число/строка задаёт максимум) или `counterValue`. Поиск: `grep -rnE "cds-text-input[^>]*limit|CdsTextInput[^>]*limit" src/`.

<!-- entry-meta: id=cdstextinput-limit-removed; severity=breaking; component=CdsTextInput -->

#### Удалён пропс `persistentMessages`, а `messages` видны всегда

> ⚠️ **BREAKING** — роли разошлись. В CDS 3 `messages` показывались только в фокусе, а `persistentMessages` их закреплял. В CDS 4 `messages` видны **всегда**, поэтому `persistentMessages` удалён за ненадобностью, а «только в фокусе» — это отдельный пропс `hint` (с `persistentHint`, если подсказку нужно закрепить).

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<cds-text-input v-model="text" :messages="hint" persistent-messages />
<cds-text-input v-model="text" :messages="hint" />
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — messages видны всегда; показ по фокусу даёт hint -->
<CdsTextInput v-model="text" :messages="hint" />
<CdsTextInput v-model="text" :hint="hint" />
```

**Действие:** там, где стоял `persistent-messages`, достаточно удалить пропс — `messages` и так видны всегда, переносить текст в `hint` не нужно. Там, где `messages` использовались **без** него, перенести текст в `hint`: иначе подсказка, которая раньше появлялась по фокусу, после апгрейда будет висеть постоянно — код не сломается, но поле станет выглядеть иначе. Поиск: `grep -rnE "persistent-messages|persistentMessages|:messages|messages=" src/`. Начиная с CDS 3.11.0 оба случая предупреждают в консоли (`[CDS UPGRADE]`), а `hint` / `persistent-hint` там уже работают — переписать можно до апгрейда.

<!-- entry-meta: id=cdstextinput-persistentmessages-removed; severity=breaking; component=CdsTextInput -->

#### Изменён exposed-API

> ⚠️ **BREAKING** — вместо `fieldRef` / `inputRef` / `validationRef` / `focus` / `blur` компонент отдаёт унифицированный validation-API и `controlRef` (как у `CdsInput`).

**Было (CDS 3):**

```ts
// CDS 3 — exposed: fieldRef, inputRef, validationRef, focus, blur
const input = ref();
input.value.inputRef;      // <input>
input.value.validationRef; // инстанс CdsInput
input.value.focus();
```

**Стало (CDS 4):**

```ts
// CDS 4 — методы и флаги валидации + controlRef
const input = ref();
input.value.validate();        // запуск валидации
input.value.reset();           // сброс значения
input.value.resetValidation(); // сброс ошибок
input.value.isValid;           // isDirty / isDisabled / isReadonly / isPure / isValidating
input.value.controlRef;        // DOM-элемент контрола (<input>)
```

**Действие:** заменить обращения к `ref.inputRef` / `ref.fieldRef` / `ref.validationRef` / `ref.focus()` / `ref.blur()` на validation-API (`validate` / `reset` / `resetValidation`, флаги `isValid` / `isDirty` / `isValidating` / `isDisabled` / `isReadonly` / `isPure`) и `controlRef` для доступа к DOM-элементу поля.

<!-- entry-meta: id=cdstextinput-exposed-api-changed; severity=breaking; component=CdsTextInput -->

### CdsTooltip

#### Наведение на контент подсказки теперь закрывает её — интерактивность через проп `interactive`

> ⚠️ **BREAKING** — по умолчанию контент подсказки получил `pointer-events: none`: при переносе курсора с активатора на контент подсказка закрывается. В CDS 3 подсказка оставалась открытой, и внутри можно было кликать ссылки и кнопки без дополнительных пропсов.

**Было (CDS 3):**

```html
<!-- CDS 3 — контент подсказки был интерактивен по умолчанию -->
<cds-tooltip v-model="active" location="end" open-on-click :open-on-hover="false">
  <template #activator="{ props }">
    <cds-button appearance="tertiary" icon="comment" v-bind="props" @click="active = true" />
  </template>
  <p>Текст подсказки</p>
  <cds-link href="/docs" text="Узнать больше" />
</cds-tooltip>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — для кликабельного контента нужен проп interactive -->
<CdsTooltip v-model="active" interactive location="end" open-on-click :open-on-hover="false">
  <template #activator="{ props }">
    <CdsButton variant="soft" color="neutral" icon="message" v-bind="props" @click="active = true" />
  </template>
  <p>Текст подсказки</p>
  <a href="/docs">Узнать больше</a>
</CdsTooltip>
```

**Действие:** найти тултипы с интерактивным контентом (ссылки, кнопки, выделяемый текст) и добавить им проп `interactive`. Простые текстовые подсказки менять не нужно. Поиск кандидатов: `grep -rnE "cds-tooltip|CdsTooltip" src/` — проверить те, у кого в default-слоте есть `<a>`, `CdsButton` и т. п.

<!-- entry-meta: id=cdstooltip-interactive-prop-required; severity=breaking; component=CdsTooltip -->

#### Изменён exposed-API

> ⚠️ **BREAKING** — вместо `id` / `overlay` компонент отдаёт элементы и методы оверлея напрямую.

**Было (CDS 3):**

```ts
// CDS 3
const tip = ref();
tip.value.overlay; // инстанс CdsOverlay
tip.value.id;      // id подсказки
```

**Стало (CDS 4):**

```ts
// CDS 4
const tip = ref();
tip.value.contentEl;             // DOM-элемент контента
tip.value.activatorEl;           // DOM-элемент активатора
tip.value.updateLocation?.(e);   // пересчёт позиции
```

**Действие:** заменить обращения к `ref.overlay` / `ref.id` на новые exposed-поля (`contentEl`, `activatorEl`, `rootEl`, `targetEl`, `updateLocation`, `animateClick`).

<!-- entry-meta: id=cdstooltip-exposed-api-changed; severity=breaking; component=CdsTooltip -->

### CdsTransitionCollapse

#### `CdsTransitionCollapse` удалён

> ⚠️ **BREAKING** — фабрика пропсов для `<Transition>` (высота и прозрачность ветви, кривая Material 2) удалена. Замена — `CdsTransitionPresence`: затухание, затем схлопывание высоты, отступов и рамки. `CdsTree` теперь раскрывает ветви через него.

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<Transition v-bind="CdsTransitionCollapse()">
  <div v-if="open">Содержимое</div>
</Transition>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 -->
<CdsTransitionPresence>
  <div v-if="open">Содержимое</div>
</CdsTransitionPresence>
```

**Действие:** заменить `CdsTransitionCollapse` на `CdsTransitionPresence` (или `CdsTransitionExpand`, если нужна только высота). Поиск: `grep -rn "CdsTransitionCollapse" src/`. Свой `openAnimation` у `CdsTree` по-прежнему подменяет анимацию целиком.

<!-- entry-meta: id=cdstransitioncollapse-removed; severity=breaking; component=CdsTransitionCollapse -->

### CdsContainer

> ⚠️ **BREAKING** — Компонент `CdsContainer` (и `CdsContainerItem`) был помечен `deprecated` ещё в CDS 3 и удалён в CDS 4. Способ миграции зависит от того, как контейнер использовался: обычный/вложенный → нативный `<div>`; выбираемый/множественный → `CdsCard` + `CdsCardGroup`; кликабельный → `CdsCard` со ссылкой.

#### Обычный и вложенный контейнер → нативный `<div>`

**Было (CDS 3):**

```html
<!-- CDS 3 -->
<CdsContainer>
  <CdsContainerItem>
      <div class="h6 cds-mb-xs">Заголовок контейнера</div>
      <p>Используется в качестве элемента, где вся область контейнера — это интерактивное состояние.</p>
  </CdsContainerItem>
</CdsContainer>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — обычный div + утилиты Tailwind и токены CDS -->
<div class="rounded-200 bg-surface-primary p-4">
  <div class="h6 mb-1">Заголовок контейнера</div>
  <p>Используется в качестве элемента, где вся область контейнера — это интерактивное состояние.</p>
</div>
```

**Действие:** заменить `CdsContainer` / `<div class="cds-container-default …">` обычным `<div>` с утилитарными классами. В CDS 3 этот же совет давался прямо в сторибуке (`CdsContainer/stories/features.stories.ts`, story «Обычный контейнер»/«Вложенные контейнеры»), а в CDS 4 он тем более уместен — доступны Tailwind v4 и design-токены как утилиты (`bg-surface-*`, `rounded-200`, см. раздел «Интеграция с Tailwind CSS v4»). Поиск: `grep -rnE "CdsContainer|cds-container|cds-container-default" src/`.

#### Выбираемый и множественный контейнер → `CdsCard` + `CdsCardGroup`

**Было (CDS 3):**

```html
<!-- CDS 3 — выбираемые контейнеры через CdsContainer + CdsContainerItem -->
<script setup lang="ts">
import { CdsContainer, CdsContainerItem } from '@central-design-system/components';
import { ref } from 'vue';

const model = ref(1);        // множественный: ref([2]) + проп multiple
</script>

<template>
  <cds-container v-model="model" required>
    <cds-container-item :value="1">
      <h6>Заголовок контейнера</h6>
      <p>Используется в качестве элемента, где вся область контейнера — это интерактивное состояние.</p>
    </cds-container-item>
    <cds-container-item :value="2">…</cds-container-item>
    <cds-container-item :value="3">…</cds-container-item>
  </cds-container>
</template>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — та же логика выбора на CdsCardGroup + CdsCard -->
<script setup lang="ts">
import { CdsCard, CdsCardGroup } from '@central-design-system/components';
import { ref } from 'vue';

const selected = ref(1);     // множественный: ref([2]) + проп multiple на CdsCardGroup
const items = [1, 2, 3];
</script>

<template>
  <CdsCardGroup v-model="selected" required class="gap-4">
    <CdsCard
      v-for="item in items"
      :key="item"
      title="Заголовок карточки"
      text="Используется в качестве элемента, где вся область карточки — это интерактивное состояние."
      :value="item"
    />
  </CdsCardGroup>
</template>
```

**Действие:** заменить `CdsContainer` c `v-model` на `CdsCardGroup`, а каждый `CdsContainerItem` — на `CdsCard` с `:value`. Пропсы `required` и `multiple` переносятся на `CdsCardGroup` без изменений (одиночный выбор — `v-model` числом, множественный — массивом + `multiple`). Готовые примеры: `packages/components/src/components/CdsCard/docs/CdsCard.stories.ts` — story `Group` (выбираемая группа) и `Multiselectable` (множественный выбор).

#### Кликабельный контейнер → `CdsCard` со ссылкой

**Было (CDS 3):**

```html
<!-- CDS 3 — кликабельный контейнер-ссылка через обёртку CdsLink -->
<cds-container>
  <cds-link href="#">
    <cds-container-item>
      <h6>Заголовок контейнера</h6>
      <p>Используется в качестве элемента, где вся область контейнера — это интерактивное состояние.</p>
    </cds-container-item>
  </cds-link>
</cds-container>
```

**Стало (CDS 4):**

```html
<!-- CDS 4 — CdsCard сам становится ссылкой через href / to -->
<CdsCard
  title="Заголовок карточки"
  text="Используется в качестве элемента, где вся область карточки — это интерактивное состояние."
  href="#"
/>
```

**Действие:** заменить связку `CdsContainer` + `CdsLink` + `CdsContainerItem` одним `CdsCard` со свойством `href` (внешняя ссылка) или `to` (vue-router). Пример: `CdsCard.stories.ts`, story `Link`.

<!-- entry-meta: id=cdscontainer-removed; severity=breaking; component=CdsContainer -->