feat(docs): v17 -> v18 migration guide (#DS-3848) (#871)

Author: NikGurev

apps/docs/src/app/services/documentation-items.ts

@@ -129,8 +129,19 @@ const DOCS: { [key: string]: DocsDocCategory[] } = {
                     },
                     svgPreview: 'schematics',
                     hasApi: false,
+                    hasExamples: false
+                },
+
+                {
+                    id: 'migration',
+                    name: {
+                        ru: 'Гайды по миграции',
+                        en: 'Migration guides'
+                    },
+                    svgPreview: '',
+                    hasApi: false,
                     hasExamples: false,
-                    isNew: expiresAt('2025-06-01')
+                    isNew: expiresAt('2025-07-13')
                 }
             ]
         }

docs/guides/migration.en.md

@@ -0,0 +1,83 @@
+## How to Upgrade from Koobiq v17
+
+New versions bring improvements, but include **breaking changes** — these should be applied gradually.
+
+---
+
+### Quick Plan
+
+1. **Up to 18.5.3** – safe base update with new theming and icon package
+2. **18.6** – token updates
+3. **18.22** – attribute name changes in components
+4. **After** – final upgrade to the latest version (with modern theming support)
+
+---
+
+### 1. Upgrade to 18.5.3
+
+```bash
+npm install @koobiq/cdk@18.5.3
+npm install @koobiq/components@18.5.3
+npm install @koobiq/icons@^9.0.0
+npm install @koobiq/design-tokens@~3.7.3
+npm install @koobiq/angular-luxon-adapter@18.5.3
+npm install @koobiq/date-adapter^3.1.3
+npm install @koobiq/date-formatter^3.1.3
+npm install luxon
+npm install @messageformat/core
+npm install @radix-ng/primitives@0.14.0
+```
+
+#### New Theming System
+
+Theming is now simpler and built on CSS variables.
+
+See examples in the repo:
+
+- [`apps/docs/src/main.scss`](https://github.com/koobiq/angular-components/blob/main/apps/docs/src/main.scss)
+- [`apps/docs/src/styles/_theme-kbq.scss`](https://github.com/koobiq/angular-components/blob/main/apps/docs/src/styles/_theme-kbq.scss)
+
+#### Icon Package Update
+
+- Install the updated icon package:
+
+```bash
+npm install @koobiq/icons@9.1.0
+```
+
+- Apply the schematic:
+
+```bash
+ng g @koobiq/angular-components:new-icons-pack --project <your project>
+```
+
+---
+
+### 2. Token Update (18.6.x)
+
+- Deprecated color tokens were removed and typography token names were changed.
+
+The schematic will replace typography names and highlight where color tokens need manual cleanup:
+
+```bash
+ng g @koobiq/angular-components:css-selectors --fix=true --project <your project>
+```
+
+- For manual control, use `--fix=false`. The schematic will only highlight where changes are needed:
+
+```bash
+ng g @koobiq/angular-components:css-selectors --fix=false --project <your project>
+```
+
+---
+
+### 3. Attribute Updates (18.22.0)
+
+- Attribute names were changed in the following components:
+    - `KbqLoaderOverlay`: `compact` → `size`
+    - `KbqEmptyState`: `big` → `size`
+
+```bash
+ng g @koobiq/angular-components:loader-overlay-size-attr --project <your project>
+ng g @koobiq/angular-components:empty-state-size-attr --project <your project>
+```

docs/guides/migration.ru.md

@@ -0,0 +1,85 @@
+## Как обновиться с Koobiq v17
+
+Новые версии включают улучшения, но содержат **ломающие изменения** — их нужно применять постепенно.
+
+---
+
+### Краткий план
+
+1. **До 18.5.3** – безопасная база с обновлением темизации и иконок
+2. **18.6** – обновление токенов
+3. **18.22** – изменение атрибутов компонентов
+4. **После** – финальное обновление до последней версии (с актуальной темизацией)
+
+---
+
+### 1. Обновление до 18.5.3
+
+```bash
+npm install @koobiq/cdk@18.5.3
+npm install @koobiq/components@18.5.3
+npm install @koobiq/icons@^9.0.0
+npm install @koobiq/design-tokens@~3.7.3
+npm install @koobiq/angular-luxon-adapter@18.5.3
+npm install @koobiq/date-adapter^3.1.3
+npm install @koobiq/date-formatter^3.1.3
+npm install luxon
+npm install @messageformat/core
+npm install @radix-ng/primitives@0.14.0
+```
+
+#### Новая темизация
+
+Теперь темизация более простая и строится на основе CSS-переменных.
+
+Подробнее [по ссылке.](https://koobiq.io/ru/main/theming/overview#как-использовать?)
+
+Смотрите примеры в репозитории:
+
+- [`apps/docs/src/main.scss`](https://github.com/koobiq/angular-components/blob/main/apps/docs/src/main.scss)
+- [`apps/docs/src/styles/_theme-kbq.scss`](https://github.com/koobiq/angular-components/blob/main/apps/docs/src/styles/_theme-kbq.scss)
+
+#### Обновление пакета иконок
+
+- Установите новую версию иконок:
+
+```bash
+npm install @koobiq/icons@9.1.0
+```
+
+- Примените схематик
+
+```bash
+ng g @koobiq/angular-components:new-icons-pack --project <your project>
+```
+
+---
+
+### 2. Обновление токенов (18.6.x)
+
+- Были удалены устаревшие токены цветов и заменены названия типографики.
+
+Скрипт заменит названия типографики на новые и подсветит места, где нужно удалить/заменить устаревшие цвета:
+
+```bash
+ng g @koobiq/angular-components:css-selectors --fix=true --project <your project>
+```
+
+- Для ручного контроля добавьте `--fix=false`. Скрипт подсветит места, где нужно удалить/заменить цвета и названия типографики
+
+```bash
+ng g @koobiq/angular-components:css-selectors --fix=false --project <your project>
+```
+
+---
+
+### 3. Обновление атрибутов (18.22.0)
+
+- Изменились имена атрибутов компонентов:
+    - `KbqLoaderOverlay`: `compact` → `size`
+    - `KbqEmptyState`: `big` → `size`
+
+```bash
+ng g @koobiq/angular-components:loader-overlay-size-attr --project <your project>
+ng g @koobiq/angular-components:empty-state-size-attr --project <your project>
+```

tools/cspell-locales/ru.json

@@ -117,6 +117,7 @@
         "таймпикер",
         "темизации",
         "темизация",
+        "темизацией",
         "тенант",
         "техдолг",
         "типографики",