@central-design-system/skills 4.0.0-alpha.6

package/skills/cds-migrate/references/migration-full.md

@@ -0,0 +1,2225 @@
+# CDS 3 → CDS 4 migration — full guide
+
+> Copy of `MIGRATION.md` from the `@central-design-system/components` npm package,
+> taken by `bun run generate:skill`. Do not edit manually. The guide itself is
+> currently in Russian; an English mirror does not exist yet.
+
+# Миграция на 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-режим).
+- ✅ Проверить [индекс изменений по компонентам](#индекс-изменений-по-компонентам).
+- ✅ Прогнать сборку приложения и проверить консоль: `[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: { appearance: 'secondary' },
+  },
+  // Пресет конфигурации: базовый набор опций, поверх которого мержится остальное.
+  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';
+
+// Дефолт — встроенный iconpack `cds`.
+createCds({
+  icons: {
+    defaultSet: 'cds'
+  }
+});
+```
+
+В рантайме при старом подключении в dev-консоли появится:
+
+```
+[CDS UPGRADE] '@central-design-system/icons' is deprecated and will be removed in future. Please use modern icons instead.
+```
+
+(см. `src/icons.ts`, ветка `Symbol.toStringTag === 'Module'`).
+
+**Действие:** перейти на новые icon packs через опцию `createCds({ icons })`.
+Если миграция постепенная — можно временно использовать поле `legacyIcons`
+(см. `InternalIconOptions` в `src/composables/useIcons/internal/useIcons.types.ts`),
+оно специально оставлено на переходный период и будет удалено в будущих версиях.
+
+<!-- entry-meta: id=icons-legacy-package-deprecated; severity=deprecation; component= -->
+
+### Новая фабрика `createIcons` и iconpacks
+
+> ✨ **NEW**
+
+В CDS 4 иконки конфигурируются через явную фабрику `createIcons`,
+понимающую концепцию **iconpack**. Готовые наборы лежат в
+`src/assets/icons/`: `cds` (по умолчанию), `cdsLegacy` (для совместимости),
+`carbon`, `lucide`, `phosphor`, `remix`. Это позволяет смешивать наборы и
+переопределять алиасы под продукт.
+
+**Было (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 под продукт. По умолчанию активен набор `cds` с алиасами
+из `src/assets/icons/cds.ts`.
+
+<!-- entry-meta: id=icons-createicons-factory; severity=new; component= -->
+
+---
+
+<a id="3-пропсы"></a>
+
+## 3. Пропсы
+
+Сюда попадают общие изменения системы пропсов (фабрики
+`defineXProps()` через `propsFactory`, новые композаблы пропсов).
+Точечные переименования у конкретных компонентов — в разделе [Компоненты](#8-компоненты).
+
+_Пока изменений нет. Записи будут добавляться по мере появления breaking-изменений._
+
+---
+
+<a id="4-стили-и-токены"></a>
+
+## 4. Стили и токены
+
+Сюда попадают изменения CSS-токенов (2 уровня), CSS Layers (ITCSS),
+интеграции с Tailwind, публичных импортов `./styles/...`.
+
+### Изменён путь импорта 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= -->
+
+---
+
+<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`      | ⚠️ удалён автоматический отступ между соседними кнопками                                   | [CdsButton](#cdsbutton)           |
+| `CdsCard`        | ⚠️ удалены `interactive` / `selected`                                                      | [CdsCard](#cdscard)               |
+| `CdsCheckbox`    | ⚠️ удалён `CdsCheckboxGroup`; ⚠️ изменён exposed-API                                       | [CdsCheckbox](#cdscheckbox)       |
+| `CdsContentSwitcher` | ⚠️ Компонент удалён → `CdsTabs` / `CdsTab`                                             | [CdsContentSwitcher](#cdscontentswitcher) |
+| `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` | [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`   | ⚠️ дефолты иконок стрелок `chevron-left`/`chevron-right`→`prev`/`next` (новая система иконок) | [CdsSlideView](#cdsslideview)     |
+| `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)         |
+| `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 -->
+
+### 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 -->
+
+### 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 -->
+
+### 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="prev" next-icon="next">
+  <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` → `prev` / `next` (новая система иконок `IconValue`). Поиск: `grep -rnE "CdsSlideGroup[^>]*(prepend-icon|append-icon)" src/`.
+
+<!-- entry-meta: id=cdsslidegroup-arrow-icon-props-renamed; severity=renamed; component=CdsSlideGroup -->
+
+### CdsSlideView
+
+#### Иконки стрелок `prevIcon` / `nextIcon` переведены на новую систему иконок
+
+> ⚠️ **BREAKING** — имена пропсов `prevIcon` / `nextIcon` не изменились, но дефолтные иконки заменены `chevron-left` / `chevron-right` → `prev` / `next`, а тип пропа теперь `IconValue` (без валидации по `allowedIcons`). Явно переданные старые имена (`chevron-left` / `chevron-right`) в новом наборе иконок не резолвятся.
+
+**Было (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 — дефолты prev / next, тип IconValue -->
+<CdsSlideView prev-icon="prev" next-icon="next">
+  <CdsSlideViewItem v-for="i in items" :key="i" :value="i">{{ i }}</CdsSlideViewItem>
+</CdsSlideView>
+```
+
+**Действие:** если полагались на дефолтные стрелки — проверьте вид (иконки изменены `chevron-left` / `chevron-right` → `prev` / `next`). Явные `prev-icon="chevron-left"` / `next-icon="chevron-right"` замените на имена из активного iconpack (или на `prev` / `next`). Поиск: `grep -rnE "CdsSlideView[^>]*(prev-icon|next-icon)" src/`.
+
+<!-- entry-meta: id=cdsslideview-arrow-icons-iconvalue; severity=breaking; component=CdsSlideView -->
+
+### 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 appearance="tertiary" icon="comment" 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 -->
+
+### 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 -->