@sberbusiness/triplex-next-mcp-server 1.44.0-beta → 1.46.0-beta

package/bundle/components/DatePickerExtended.md

@@ -1,7 +1,7 @@
 ---
 component: DatePickerExtended
 category: Date components
-related: [Calendar, Dropdown, DateField, MonthYearField, ChipDatePicker]
+related: [Calendar, Dropdown, DateField, MonthYearField, ChipDatePicker, ChipMonthYearPicker]
 tokens: []
 stories: stories/DatePickerExtended/DatePickerExtended.stories.tsx
 version: "1.0"
@@ -97,6 +97,7 @@ version: "1.0"
 - `DateField` — поле ввода даты; передаёт `dropdownTargetRef` и открывает календарь из `DateFieldTarget` через контекст.
 - `MonthYearField` — выбор месяца и года; конфигурирует `pickType={ECalendarPickType.MONTH_YEAR}`.
 - `ChipDatePicker` — чип-фильтр с календарём; открывает дропдаун из `ChipDatePickerTarget` через контекст.
+- `ChipMonthYearPicker` — чип-фильтр с выбором месяца (`pickType` фиксирован в `MONTH_YEAR`); открывает дропдаун из `ChipMonthYearPickerTarget` через контекст.
 - `DatePickerExtendedContext` — контекст открытости дропдауна для целевого элемента. Экспортируется из barrel вместе с типом `IDatePickerExtendedContext`, отдельного AI.md не имеет.
 
 Внутренние части (в barrel не экспортируются, отдельного AI.md не имеют):
@@ -130,6 +131,7 @@ version: "1.0"
 
 | Дата | Изменение |
 |---|---|
+| 2026-09-07 | В потребители базы добавлен `ChipMonthYearPicker` (чип-фильтр с `pickType` `MONTH_YEAR`) |
 | 2026-08-24 | `DatePickerExtendedContext` и `IDatePickerExtendedContext` экспортируются из barrel — целевой элемент можно написать снаружи библиотеки. `adaptiveMode` исключён из `IDatePickerExtendedProps` (ломающее изменение, затрагивает также `DateField`, `MonthYearField`, `ChipDatePicker`) |
 | 2026-08-20 | Создан документ. AI-рефакторинг, unit-тесты (`__tests__/DatePickerExtended.test.tsx`), stories по modern pattern. Исправлено: `yesterdayButtonProps` / `tomorrowButtonProps` пробрасываются в `Calendar`, `adaptiveMode` больше не попадает в DOM |
 

package/bundle/components/Dropdown.md

@@ -3,19 +3,21 @@ component: Dropdown
 category: Dropdown
 related: [ButtonDropdown, ButtonDropdownExtended, Portal, MobileView, OverlayBase, SelectField, SelectExtendedField, SuggestField, MultiselectField, TabsLine]
 tokens:
-  - --triplex-next-Dropdown-Background
-  - --triplex-next-Dropdown-Shadow
-  - --triplex-next-DropdownList-Color
-  - --triplex-next-DropdownList-Background_Default
-  - --triplex-next-DropdownList-Background_Active
-  - --triplex-next-DropdownList-Background_Selected
-  - --triplex-next-DropdownMobile-Backdrop
-  - --triplex-next-DropdownMobile-Header_Background
-  - --triplex-next-DropdownMobile-Content_Background
-  - --triplex-next-DropdownMobile-Footer_Background
-  - --triplex-next-DropdownMobile-Border_Color
-  - --triplex-next-DropdownMobileList-Active_Background
-  - --triplex-next-DropdownMobileList-Selected_Background
+  - Dropdown.Background
+  - Dropdown.Shadow
+  - DropdownList.Color
+  - DropdownList.Background_Default
+  - DropdownList.Background_Active
+  - DropdownList.Background_Selected
+  - DropdownMobile.Backdrop
+  - DropdownMobile.Header_Background
+  - DropdownMobile.Content_Background
+  - DropdownMobile.Footer_Background
+  - DropdownMobile.Border_Color
+  - DropdownMobileList.Active_Background
+  - DropdownMobileList.Selected_Background
+  - FormField.Input_Color_Default
+  - FormField.Placeholder_Color
 stories: stories/Dropdown/Dropdown.stories.tsx
 version: "1.0"
 ---
@@ -92,23 +94,26 @@ version: "1.0"
 
 ## Дизайн-токены
 
-```
---triplex-next-Dropdown-Background
---triplex-next-Dropdown-Shadow
---triplex-next-DropdownList-Color
---triplex-next-DropdownList-Background_Default
---triplex-next-DropdownList-Background_Active
---triplex-next-DropdownList-Background_Selected
---triplex-next-DropdownMobile-Backdrop
---triplex-next-DropdownMobile-Header_Background
---triplex-next-DropdownMobile-Content_Background
---triplex-next-DropdownMobile-Footer_Background
---triplex-next-DropdownMobile-Border_Color
---triplex-next-DropdownMobileList-Active_Background
---triplex-next-DropdownMobileList-Selected_Background
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — файлы групп `Dropdown`, `DropdownList`, `DropdownMobile`, `DropdownMobileList` в `src/components/DesignTokens/components/`.
+
+```text
+Dropdown.Background
+Dropdown.Shadow
+DropdownList.Color
+DropdownList.Background_Default
+DropdownList.Background_Active
+DropdownList.Background_Selected
+DropdownMobile.Backdrop
+DropdownMobile.Header_Background
+DropdownMobile.Content_Background
+DropdownMobile.Footer_Background
+DropdownMobile.Border_Color
+DropdownMobileList.Active_Background
+DropdownMobileList.Selected_Background
 ```
 
-`DropdownMobileInput` дополнительно использует токены поля ввода: `--triplex-next-FormField-Input_Color_Default`, `--triplex-next-FormField-Placeholder_Color`.
+`DropdownMobileInput` дополнительно использует токены поля ввода: `FormField.Input_Color_Default`, `FormField.Placeholder_Color`.
 
 ---
 

package/bundle/components/EmptyView.md

@@ -3,8 +3,8 @@ component: EmptyView
 category: Feedback
 related: [Button]
 tokens:
-  - --triplex-next-Typography-Primary_Color
-  - --triplex-next-Typography-Secondary_Color
+  - Typography.Primary_Color
+  - Typography.Secondary_Color
 stories: stories/EmptyView/EmptyView.stories.tsx
 version: "1.0"
 ---
@@ -47,10 +47,16 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/Typography.ts`.
+
+```text
+Typography.Primary_Color    (title, description без title)
+Typography.Secondary_Color  (description с title, caption)
 ```
---triplex-next-Typography-Primary_Color    (title, description без title)
---triplex-next-Typography-Secondary_Color  (description с title, caption)
-```
+
+Собственных токенов у компонента нет: цвета приходят от вложенных `Title` и `Text`,
+в `styles/EmptyView.module.less` заданы только отступы и выравнивание.
 
 ---
 
@@ -96,6 +102,7 @@ version: "1.0"
 |---|---|
 | 2026-04-09 | Создан компонент и документ. |
 | 2026-04-27 | Приведён в соответствие с `docs/ai/template-ai.md`: добавлена колонка `Example file`, переименована подсекция «Поведение описания» в «Ограничения по темам». |
+| 2026-08-31 | Заголовок всегда рендерится как `Title` с `ETitleSize.H3` и `EFontWeightTitle.MEDIUM`: убран `TITLE_CONFIG`, типографика `title` больше не зависит от `size`. |
 
 ---
 

package/bundle/components/FooterPage.md

@@ -2,7 +2,8 @@
 component: FooterPage
 category: Page
 related: [Page, HeaderPage, BodyPage, Footer, Island, LightBox]
-tokens: [--triplex-next-FooterPage-StickyShadow]
+tokens:
+  - FooterPage.StickyShadow
 stories: stories/Page/FooterPage/FooterPage.stories.tsx
 version: "1.0"
 ---
@@ -51,9 +52,12 @@ version: "1.0"
 
 ## Дизайн-токены
 
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/FooterPage.ts`.
+
 | Токен | Назначение |
 |---|---|
-| `--triplex-next-FooterPage-StickyShadow` | Тень прилипшего футера (когда `sticky` и футер коснулся нижней границы, `data-stuck="true"`). |
+| `FooterPage.StickyShadow` | Тень прилипшего футера (когда `sticky` и футер коснулся нижней границы, `data-stuck="true"`). |
 
 Внешний вид карточки наследуется от `Island` (`EIslandType.TYPE_1`). Радиус нижних углов при
 прилипании плавно обнуляется через CSS-переменную `--r-bottom` (управляется хуком

package/bundle/components/FormField.md

@@ -3,26 +3,26 @@ component: FormField
 category: FormField
 related: [FormFieldLabel, FormFieldInput, FormFieldTextarea, FormFieldTarget, FormFieldMaskedInput, FormFieldPrefix, FormFieldPostfix, FormFieldClear, FormFieldDescription, FormFieldCounter, FormGroup, TextField, TextareaField, MaskedField, SelectField, SuggestField, DateField]
 tokens:
-  - --triplex-next-FormField-Background_Default
-  - --triplex-next-FormField-Background_Hover
-  - --triplex-next-FormField-Background_Active
-  - --triplex-next-FormField-Background_Disabled
-  - --triplex-next-FormField-Background_Error
-  - --triplex-next-FormField-Background_Error_Hover
-  - --triplex-next-FormField-Background_Warning
-  - --triplex-next-FormField-Background_Warning_Hover
-  - --triplex-next-FormField-Shadow_Default
-  - --triplex-next-FormField-Shadow_Active
-  - --triplex-next-FormField-Shadow_Error_Active
-  - --triplex-next-FormField-Shadow_Warning_Active
-  - --triplex-next-FormField-Input_Color_Default
-  - --triplex-next-FormField-Input_Color_Disabled
-  - --triplex-next-FormField-Label_Color_Default
-  - --triplex-next-FormField-Label_Color_Disabled
-  - --triplex-next-FormField-Placeholder_Color
-  - --triplex-next-FormField-Target_Color_Default
-  - --triplex-next-FormField-Target_Color_Disabled
-  - --triplex-next-FormField-Target_PlaceholderColor_Default
+  - FormField.Background_Default
+  - FormField.Background_Hover
+  - FormField.Background_Active
+  - FormField.Background_Disabled
+  - FormField.Background_Error
+  - FormField.Background_Error_Hover
+  - FormField.Background_Warning
+  - FormField.Background_Warning_Hover
+  - FormField.Shadow_Default
+  - FormField.Shadow_Active
+  - FormField.Shadow_Error_Active
+  - FormField.Shadow_Warning_Active
+  - FormField.Input_Color_Default
+  - FormField.Input_Color_Disabled
+  - FormField.Label_Color_Default
+  - FormField.Label_Color_Disabled
+  - FormField.Placeholder_Color
+  - FormField.Target_Color_Default
+  - FormField.Target_Color_Disabled
+  - FormField.Target_PlaceholderColor_Default
 stories: stories/FormField/FormField.stories.tsx
 version: "1.0"
 ---
@@ -69,27 +69,30 @@ version: "1.0"
 
 ## Дизайн-токены
 
-```
---triplex-next-FormField-Background_Default
---triplex-next-FormField-Background_Hover
---triplex-next-FormField-Background_Active
---triplex-next-FormField-Background_Disabled
---triplex-next-FormField-Background_Error
---triplex-next-FormField-Background_Error_Hover
---triplex-next-FormField-Background_Warning
---triplex-next-FormField-Background_Warning_Hover
---triplex-next-FormField-Shadow_Default
---triplex-next-FormField-Shadow_Active
---triplex-next-FormField-Shadow_Error_Active
---triplex-next-FormField-Shadow_Warning_Active
---triplex-next-FormField-Input_Color_Default
---triplex-next-FormField-Input_Color_Disabled
---triplex-next-FormField-Label_Color_Default
---triplex-next-FormField-Label_Color_Disabled
---triplex-next-FormField-Placeholder_Color
---triplex-next-FormField-Target_Color_Default
---triplex-next-FormField-Target_Color_Disabled
---triplex-next-FormField-Target_PlaceholderColor_Default
+Переопределяются через `ThemeProvider` (prop `tokens`) — см. `ThemeProvider-ai.md` →
+«Как переопределять токены». Значения по умолчанию — `src/components/DesignTokens/components/FormField.ts`.
+
+```text
+FormField.Background_Default
+FormField.Background_Hover
+FormField.Background_Active
+FormField.Background_Disabled
+FormField.Background_Error
+FormField.Background_Error_Hover
+FormField.Background_Warning
+FormField.Background_Warning_Hover
+FormField.Shadow_Default
+FormField.Shadow_Active
+FormField.Shadow_Error_Active
+FormField.Shadow_Warning_Active
+FormField.Input_Color_Default
+FormField.Input_Color_Disabled
+FormField.Label_Color_Default
+FormField.Label_Color_Disabled
+FormField.Placeholder_Color
+FormField.Target_Color_Default
+FormField.Target_Color_Disabled
+FormField.Target_PlaceholderColor_Default
 ```
 
 ---
@@ -123,7 +126,7 @@ version: "1.0"
 
 - `FormFieldLabel` — плавающий лейбл; поднимается над полем, когда поле заполнено или активно (можно форсировать props `floating`).
 - `FormFieldInput` — однострочный ввод; поддерживает render-prop `render` для подмены инпута с сохранением стилизации.
-- `FormFieldTextarea` — многострочный ввод.
+- `FormFieldTextarea` — многострочный ввод. Высота по размеру задана как `min-height`.
 - `FormFieldMaskedInput` — маскированный ввод на базе `react-text-mask`; содержит пресеты масок (`FormFieldMaskedInput.presets`).
 - `FormFieldTarget` — нередактируемое значение с `placeholder`, используется select-подобными полями.
 - `FormFieldPrefix` / `FormFieldPostfix` — контейнеры слева/справа; их измеренная ширина становится внутренним отступом поля. Общая логика измерения и проброса ref вынесена во внутренний хук `components/useFormFieldAffixWidth.ts` (в barrel не экспортируется).
@@ -163,6 +166,8 @@ version: "1.0"
 | 2026-07-31 | AI-рефакторинг распространён на субкомпоненты `FormFieldInput`, `FormFieldLabel`, `FormFieldPrefix`, `FormFieldPostfix`, `FormFieldClear`, `FormFieldDescription`, `FormFieldCounter`: JSDoc с указанием значений по умолчанию, дедупликация `FormFieldPrefix` / `FormFieldPostfix` через внутренний хук `useFormFieldAffixWidth`, общий `setForwardedRef` в `components/utils.ts`, unit-тесты. Публичный API не изменён. `FormFieldTextarea`, `FormFieldTarget` и `FormFieldMaskedInput` намеренно не затронуты — их покрывают задачи `TextareaField`, `SelectField` и `MaskedField`. |
 | 2026-07-31 | Исправлено: `className` у `FormFieldDescription` и `FormFieldCounter` затирал базовый класс — теперь объединяется через `clsx`. Изменение наблюдаемого поведения, зафиксировано в release notes 1.41.0. |
 | 2026-08-03 | Ломающее изменение: `statusToClassNameMap` убран из публичного barrel и переименован во внутреннюю константу `STATUS_TO_CLASS_NAME_MAP`. Зафиксировано в release notes 1.41.0. |
+| 2026-09-04 | Исправлено: у `FormFieldTextarea` фиксированная `height` для размеров `sm` / `md` / `lg` заменена на `min-height`. |
+| 2026-09-09 | Исправлено: значение с кодом страны раскладывалось по маске телефона со сдвигом и теряло последнюю цифру. Нормализация номера вынесена в `normalizePhoneText` и применяется и к внешнему `value`, и к слою с маской |
 
 ---
 

package/bundle/components/FormGroup.md

@@ -1,11 +1,9 @@
 ---
 component: FormGroup
-category: Forms
-figma-node: ""
-figma-file: ""
-related: [FormField, TextField, SelectField, HelpBox, Alert]
+category: FormField
+related: [FormField, TextField, MaskedField]
 tokens: []
-stories: ""
+stories: stories/FormGroup/FormGroup.stories.tsx
 version: "1.0"
 ---
 
@@ -13,87 +11,229 @@ version: "1.0"
 
 ## Назначение
 
-Разметочная обёртка-`<div>` для группировки элементов формы (`FormField`,
-`HelpBox`, `Alert`, `Description`). Сама по себе **не добавляет стилей** —
-только прокидывает `ref` и все `HTMLDivAttributes`. Смысл — именованная
-точка в DOM для data-атрибутов и семантики формы.
+Контейнер формы: объединяет поле ввода с относящимися к нему элементами — `FormField`,
+`FormFieldDescription`, `HelpBox`, `AlertContext` — в один блок. Части передаются декларативно
+через `children`, поэтому каждой можно задать свои props и data-атрибуты.
 
-Используй когда: нужно сгруппировать несколько полей логически (блок "контакты",
-"адрес") и иметь стабильный wrapper под `data-*`/`aria-*`.
-Не используй как: общий flex-контейнер — возьми `Row`/`Col`.
+Рендерит один `div` без собственных классов, стилей и отступов: расстояния между частями
+задают сами части (`FormFieldDescription`, `Gap`), а не группа.
+
+Используй когда: поле нужно показать вместе с описанием, счётчиком, текстом ошибки,
+подсказкой или сообщением `AlertContext`, и эти элементы должны читаться как одна логическая
+группа формы.
+Не используй когда: достаточно готовой обёртки над полем — `TextField`, `TextareaField`,
+`MaskedField`, `AmountField` уже собирают `FormGroup` + `FormField` внутри себя, и снаружи
+их в `FormGroup` заворачивать не нужно.
 
 ---
 
-## Файловая структура
+## Варианты и props
 
-```text
-src/components/FormGroup/
-├── FormGroup.tsx   # forwardRef, <div>, passthrough props
-└── index.ts        # export * from "./FormGroup"
-```
+Настраиваемых props у компонента нет: он принимает `children` и стандартные атрибуты `div`.
+Внутренний `IFormGroupProps` расширяет `React.HTMLAttributes<HTMLDivElement>`:
+все стандартные атрибуты `div` (включая `className`, `style`, `id`, `role`, `aria-*`, `data-*`
+и обработчики событий) уходят через `...rest` на корневой элемент.
 
-Нет styles, нет tests, нет stories. Демонстрируется опосредованно через
-stories типовых полей, где `FormGroup` иногда обёрнут вокруг формы.
+### Опциональные props
 
----
+| Prop       | Тип               | По умолчанию | Описание                                                                   |
+| ---------- | ----------------- | ------------ | -------------------------------------------------------------------------- |
+| `children` | `React.ReactNode` | —            | Части группы: поле ввода и относящиеся к нему подсказки и сообщения.       |
 
-## Варианты и props
+Поскольку настраиваемых props нет, у компонента нет story `Playground`.
 
-### `IFormGroupProps extends React.HTMLAttributes<HTMLDivElement>`
+---
 
-| Prop | Тип | Описание |
-|---|---|---|
-| `children` | `ReactNode` | Обычно несколько `FormField`/`Alert`/`HelpBox`. |
-| `className`, `style`, `...HTMLDivAttributes` | — | Стандартные. |
+## Дизайн-токены
 
-Интерфейс объявлен **локально, не экспортирован**. Если понадобится
-расширить props — сначала экспортировать интерфейс.
+Собственных CSS-переменных нет — у компонента нет файла стилей. Внешний вид группы
+целиком определяют вложенные компоненты.
 
 ---
 
 ## Инварианты
 
-- **`forwardRef`** — есть, не убирать.
-- **Без собственных классов/стилей** — осознанно. Если добавить flex/padding,
-  сломается большинство существующих интеграций, где вёрстку задают потомки.
-- Все атрибуты прокидываются на корневой `<div>` через spread — включая
-  `className`/`style`. Потребитель сам задаёт лейаут.
+- `forwardRef<HTMLDivElement>` — не убирать. Ref указывает на корневой `div` — тот же
+  элемент, который получает `className` и `...rest`.
+- Корневой элемент — ровно один `div`, а `children` рендерятся в него напрямую, без
+  промежуточных обёрток. Уровень вложенности виден потребителям в DOM и в их CSS-селекторах,
+  поэтому добавление обёртки — наблюдаемое изменение и требует записи в release notes.
+- Компонент не задаёт собственных классов и отступов. Появление здесь `margin`/`gap`
+  сдвинет вёрстку всех форм в библиотеке и у потребителей: `FormGroup` используется внутри
+  `TextFieldBase` (а через него — во всех полях, построенных на нём: `TextField`,
+  `MaskedField`, `TextareaField`, `AmountField`, `NumberField`, `SuggestField`) и в
+  `SMSFieldInput`.
+- `displayName = "FormGroup"` — не менять.
+- Экспорт `FormGroup` идёт в barrel `src/components/FormGroup/index.ts` и далее в корневой
+  `src/components/index.ts` — сохранять. `IFormGroupProps` наружу не экспортируется; добавление
+  этого экспорта — расширение публичного API, отдельное решение владельца.
 
 ---
 
 ## Accessibility
 
-- `<div>` без ARIA-роли. Если группа полей должна объявляться как
-  `role="group"`/`role="radiogroup"` — потребитель передаёт `role` и
-  `aria-labelledby`/`aria-label` через `...rest`.
-- Fieldset-семантика (`<fieldset>` + `<legend>`) не используется;
-  FormGroup не пытается её эмулировать.
-
----
-
-## Дизайн-токены
+Собственного a11y-поведения нет: это структурный контейнер без роли и без интерактивности.
+Семантику задаёт потребитель через проброшенные атрибуты — например `role="group"` вместе с
+`aria-labelledby`, если группа должна объявляться скринридером как единое целое.
 
-Нет.
+Лейбл связывается с полем внутри `FormField`: `FormFieldLabel` берёт `htmlFor` из `targetId`
+в `FormFieldContext`. Описание автоматически не связывается — `aria-describedby` на элементе
+ввода (как и `aria-invalid` для ошибки) задаёт потребитель, см. `FormField-ai.md`. `FormGroup`
+не участвует ни в том, ни в другом.
 
 ---
 
 ## Связанные компоненты
 
-- `FormField` — основной контент внутри FormGroup.
-- `HelpBox`, `Alert` — вспомогательные элементы формы.
-- `Row`, `Col`, `Gap` — предпочтительны, если нужен layout, а не именованная группа.
+- `FormField` — само поле ввода; основной ребёнок группы. О `FormGroup` не знает и на нём
+  не построен: это `FormField` кладут внутрь группы, а не наоборот.
+- `FormFieldDescription` (часть семейства `FormField`) — описание, текст ошибки и счётчик
+  под полем; второй типичный ребёнок группы, отступ от поля задаёт сам (`padding-top`).
+- `TextField`, `MaskedField` — готовые однострочные поля; компактная альтернатива ручной
+  сборке `FormGroup` + `FormField`. Внутри они уже используют `FormGroup` (через
+  `TextFieldBase`), поэтому оборачивать их в него ещё раз не нужно.
+- `HelpBox`, `AlertContext` — подсказка и сообщение, которые кладут в группу рядом с полем.
 
 ---
 
 ## Stories
 
-Нет собственных stories. Используется в примерах `TextField`, `SelectField`,
-`SelectExtendedField`, `FormField`.
+Основные истории: `stories/FormGroup/FormGroup.stories.tsx`
+Файлы примеров: `stories/FormGroup/examples/`
+
+| Story         | Example file      | Что демонстрирует                                                                     |
+| ------------- | ----------------- | ------------------------------------------------------------------------------------- |
+| `Default`     | `Default.tsx`     | Минимальная группа: поле с лейблом и описанием под ним                                |
+| `Example`     | `Example.tsx`     | Production-like форма: поле с описанием и поле с ошибкой плюс `AlertContext` в группе |
+| `VisualTests` | `VisualTests.tsx` | Варианты наполнения: только поле, поле с описанием, ошибка, группа с `AlertContext`, поле с `HelpBox` |
+
+### Почему stories участвуют в скриншот-тестах
+
+Своей разметки у `FormGroup` нет, поэтому baseline'ы (`__screenshots__/formgroup--*`)
+фиксируют не саму группу, а композицию её частей: `FormField`, `FormFieldDescription`,
+`AlertContext`, `HelpBox`. Формально это близко к случаю «компонент без визуального
+интерфейса» из `stories-guide.md` § «Скриншот-тесты», где набор исключают целиком через
+`testRunner: { skip: true }`. Здесь решено baseline'ы держать: они страхуют типовые
+композиции форм, которые потребители копируют из примеров. Обратная сторона — перекраска
+`FormField` или `AlertContext` роняет визуальные тесты `FormGroup` и требует перегенерации;
+это ожидаемо, а не регрессия группы. Отсутствие лишней обёртки вокруг `children` проверяет
+unit-тест, а не скриншот.
 
 ---
 
 ## История изменений
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |
+| Дата       | Изменение                                                                                                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-08-28 | Создан документ. AI-рефакторинг (уточнён JSDoc компонента, `children` задокументирован явно), добавлены unit-тесты и stories в modern pattern. Публичный API не менялся. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/FormGroup/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    EFontType,
+    ETextSize,
+    FormField,
+    FormFieldDescription,
+    FormFieldInput,
+    FormFieldLabel,
+    FormGroup,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const Default = () => {
+    const [value, setValue] = useState("");
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <FormGroup>
+                <FormField>
+                    <FormFieldLabel>Название поля</FormFieldLabel>
+                    <FormFieldInput value={value} onChange={(event) => setValue(event.target.value)} />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Описание поля
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+        </div>
+    );
+};
+```
+
+### Example
+
+`stories/FormGroup/examples/Example.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    AlertContext,
+    EAlertType,
+    EFontType,
+    EFormFieldStatus,
+    ETextSize,
+    FormField,
+    FormFieldDescription,
+    FormFieldInput,
+    FormFieldLabel,
+    FormGroup,
+    Gap,
+    Text,
+} from "@sberbusiness/triplex-next";
+
+export const Example = () => {
+    const [account, setAccount] = useState("40702810400000012345");
+    const [amount, setAmount] = useState("");
+
+    return (
+        <div style={{ maxWidth: "360px" }}>
+            <FormGroup>
+                <FormField>
+                    <FormFieldLabel>Счёт списания</FormFieldLabel>
+                    <FormFieldInput value={account} onChange={(event) => setAccount(event.target.value)} />
+                </FormField>
+                <FormFieldDescription>
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.SECONDARY}>
+                        Доступно 125 000,00 ₽
+                    </Text>
+                </FormFieldDescription>
+            </FormGroup>
+
+            <Gap size={24} />
+
+            <FormGroup>
+                <FormField status={EFormFieldStatus.ERROR}>
+                    <FormFieldLabel>Сумма платежа</FormFieldLabel>
+                    <FormFieldInput
+                        value={amount}
+                        onChange={(event) => setAmount(event.target.value)}
+                        aria-invalid
+                        aria-describedby="amount-error"
+                    />
+                </FormField>
+                <FormFieldDescription id="amount-error">
+                    <Text tag="div" size={ETextSize.B4} type={EFontType.ERROR}>
+                        Укажите сумму платежа
+                    </Text>
+                </FormFieldDescription>
+
+                <Gap size={8} />
+
+                <AlertContext type={EAlertType.INFO}>
+                    Платёж на сумму более 150 000 ₽ уходит в банк на подтверждение.
+                </AlertContext>
+            </FormGroup>
+        </div>
+    );
+};
+```
+