@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 1.40.0-beta

package/bundle/guides/context.md

@@ -12,7 +12,7 @@ React-библиотека компонентов дизайн-системы.
 Основная линия разработки: `main` → v1.x на React 18 + TypeScript strict.
 Поддерживаемая legacy-линия: `release-0` → v0.x на React 17, синхронизируется мейнтейнерами.
 
-**Основной сценарий работы агента:** добавить новый prop или вариант к существующему компоненту по описанию и/или макету из Figma.
+**Основной сценарий работы агента:** добавить новый prop или вариант к существующему компоненту по текстовому описанию или скриншоту.
 
 ---
 
@@ -48,7 +48,7 @@ src/components/Button/
 │   └── ButtonGeneral.module.less  # Стили по теме/варианту
 ├── __tests__/
 │   └── Button.test.tsx        # Unit-тесты
-└── Button-AI.md               # Документация для AI-агентов (если компонент уже задокументирован)
+└── Button-ai.md               # Документация для AI-агентов (если компонент уже задокументирован)
 ```
 
 Истории (stories) хранятся отдельно. В репозитории встречаются как flat-path файлы
@@ -90,7 +90,7 @@ src/components/Button/
 
 Токены генерируются в `src/generated/themesCssVariables.css`. Не редактируй этот файл вручную.
 
-Если добавляешь новое визуальное состояние — нужен новый токен. Имя токена согласуй с дизайнером в Figma.
+Если добавляешь новое визуальное состояние — нужен новый токен. Имя токена согласуй с дизайнером.
 
 ---
 
@@ -115,14 +115,14 @@ src/components/Button/
 
 Если инструкции расходятся, ориентируйся на них в таком порядке:
 
-1. `src/components/{ComponentName}/{ComponentName}-AI.md` для конкретного компонента, если файл существует
+1. `src/components/{ComponentName}/{ComponentName}-ai.md` для конкретного компонента, если файл существует
 2. `docs/ai/codestyle.md`
 3. Профильный подробный гайд по зоне изменений (`codestyle.md`, `tests.md`, `stories-guide.md`, `commits.md`)
 4. Этот файл (`docs/ai/CONTEXT.md`)
 5. Локальный паттерн исходников компонента, stories и тестов
 
 Не предполагай, что у каждого компонента уже есть AI-документация. Если файла
-`{ComponentName}-AI.md` нет, ориентируйся на код, stories, тесты и общие правила
+`{ComponentName}-ai.md` нет, ориентируйся на код, stories, тесты и общие правила
 репозитория.
 
 ---
@@ -227,28 +227,6 @@ className={clsx(styles.button, styles.general, { [styles.loading]: loading })}
 
 ---
 
-## Figma и MCP
-
-Не у каждого компонента уже есть `{ComponentName}-AI.md`. Если компонент
-задокументирован, Figma-метаданные лежат в frontmatter этого файла.
-
-Формат frontmatter:
-- `figma-node` — значение параметра `node-id` из URL Figma (например, `1-328`)
-- `figma-file` — URL файла / design-ссылка на Figma-файл
-
-Если в вашем окружении настроен Figma MCP или другой интеграционный инструмент:
-1. Возьми `figma-node` из frontmatter компонента
-2. Возьми `figma-file` из frontmatter компонента, если инструменту нужен file key или URL
-3. Используй их для получения дизайн-спецификации
-4. Сравни с текущим кодом и внеси нужные изменения
-
-Если Figma-метаданные для компонента отсутствуют, не выдумывай их: попроси
-ссылку у разработчика или работай по текстовому описанию/скриншоту.
-
-Настройка MCP: см. `docs/ai/ROADMAP.md` → секция "Figma MCP Setup".
-
----
-
 ## Минимальная проверка перед завершением задачи
 
 - Правки документации и конфигов: проверь ссылки, команды, примеры кода и согласованность между файлами.
@@ -262,11 +240,37 @@ className={clsx(styles.button, styles.general, { [styles.loading]: loading })}
 ## Навигация по документации компонентов
 
 Если компонент уже задокументирован, его AI-документация лежит в:
-`src/components/{ComponentName}/{ComponentName}-AI.md`
+`src/components/{ComponentName}/{ComponentName}-ai.md`
+
+Пример: `src/components/Button/Button-ai.md`
 
-Пример: `src/components/Button/Button-AI.md`
+Шаблон для новых компонентов: `docs/ai/template-ai.md`
+
+### Когда создавать `{ComponentName}-ai.md`
+
+Не для каждого экспорта из barrel `index.ts` нужен отдельный AI.md — это
+раздуло бы `mcp-data.json` тривиальными wrapper'ами и снизило сигнал/шум для
+AI-агента.
+
+Создавай отдельный AI.md, когда выполняются **оба** условия:
+
+1. Компонент экспортируется из barrel `src/components/{Family}/index.ts`
+   (внутренние/приватные — нет).
+2. У компонента есть нетривиальный API или поведение: собственные props
+   сверх `className + ref + ...rest`, либо state, контекст, клавиатура,
+   callback'и, accessibility-контракт, render-prop, discriminated union.
+
+Тривиальные wrapper'ы (`className + spread + forwardRef` без своей логики)
+описывай разделом **«Связанные компоненты»** в AI.md родителя.
+
+**Пример из семейства List:**
+
+| Создаём AI.md | Описываем в родителе |
+|---|---|
+| `List`, `ListItem`, `ListActionItem`, `ListTableItem`, `ListItemSelectable`, `ListItemControlsButton`, `ListItemControlsButtonDropdown`, `ListSortable`, `ListSortableItem` | `ListItemControls`, `ListItemContent`, `ListEmptyState`, `ListItemLoading`, `ListItemTailLeft`, `ListItemTailRight`, `ListSortableItemTarget`, `ListSortableItemControls` |
 
-Шаблон для новых компонентов: `docs/ai/template-AI.md`
+В ROADMAP-таблице каждый AI.md-достойный компонент идёт отдельной строкой —
+так считается прогресс покрытия и видны субкомпоненты с собственным API.
 
 ---
 

package/bundle/guides/stories.md

@@ -32,13 +32,13 @@ Stories выполняют несколько функций (в порядке
 
 ### Всегда
 
-- **Playground** — добавить новый prop в `args` (дефолтное значение) и в `argTypes` (описание и контрол).
-- **`ArgTypes`** в docs page автоматически покажет новый prop, если он типизирован в интерфейсе.
+- **Playground** — добавить новый prop в `args` (дефолтное значение) и в `argTypes` (контрол).
+- **`argTypes`** в docs page автоматически покажет новый prop, если он типизирован в интерфейсе.
 
 ### Если prop имеет несколько визуальных вариантов (enum, размер, тема)
 
 - Добавить новую named story: `Sizes`, `Themes`, `Statuses` — в зависимости от типа prop.
-- Создать файл `examples/{PropName}Example.tsx` и реэкспортировать через `examples/index.ts`.
+- Создать файл `examples/{PropName}.tsx` и реэкспортировать через `examples/index.ts`.
 
 ### Если prop — boolean-состояние с видимым эффектом
 
@@ -79,10 +79,10 @@ stories/
       ComponentName.stories.tsx    # основной файл стори
       examples/
         index.ts                   # реэкспорт всех примеров
-        DefaultExample.tsx
-        SizesExample.tsx
-        StatusesExample.tsx
-        ProductionExample.tsx
+        Default.tsx
+        Sizes.tsx
+        Statuses.tsx
+        Production.tsx
         ...
 ```
 
@@ -90,6 +90,14 @@ stories/
 
 Все стори выносятся в подпапку `examples/` и импортируются в основной файл. Если в основной папке находятся несколько файлов с расширением `.stories.tsx`, внутри подпапки `examples` необходимо создать подпапки по названию компонентов из файлов с расширением `.stories.tsx`. Также необходимо в каждой такой подпапке создать отдельный файл `index.ts`.
 
+### Именование файлов примеров
+
+- Имя файла = имя story: `Default` → `Default.tsx`, `Sizes` → `Sizes.tsx`, `Playground` → `Playground.tsx`.
+- **Без постфикса `Example`** — не пиши `DefaultExample.tsx`, `SizesExample.tsx`. Если встретишь старые файлы с этим постфиксом, сохраняй локальный паттерн до миграции, но новые файлы создавай без него.
+- Имя экспорта-функции внутри файла совпадает с именем файла: `export const Default = () => ...`.
+- Source-константа: `{StoryName}Source` — `DefaultSource`, `SizesSource`, `PlaygroundSource`.
+- В story-файле импорт компонента-примера делается через alias, чтобы избежать коллизии со story-экспортом: `Default as DefaultRender`, `Playground as PlaygroundRender`. Source без alias.
+
 ---
 
 ## Обязательные стори
@@ -105,7 +113,9 @@ stories/
 
 > **Правило:** только Playground имеет Controls. Документационные стори (`Default`, `Sizes / Themes / Statuses`, `Edge cases`, `Examples`) не имеют Controls и показывают пример кода. `Visual tests` не имеют Controls и не показывают код.
 
-> **MCP bundle:** `Playground` и `VisualTests` не попадают в `mcp-data.json` — у них нет кода для агента (Playground интерактивен, VisualTests — скриншот-регрессия). Фильтр реализован в `scripts/generateMcpData.ts` (`EXCLUDED_STORIES`). В остальном для MCP нужен файл примера в `examples/{Component}/` и ссылка на него из колонки `Example file` в `{Component}-AI.md`.
+> **Исключение для компонентов без props:** если у компонента нет настраиваемых props (например, контейнер-обёртка с одним только `children` и стандартными HTML-атрибутами), Playground не создаётся — интерактивность нечего показывать. Также убирается блок `Heading>Props` + `ArgTypes` — таблица будет пустой. В этом случае из docs page убираются `Heading>Props`, `ArgTypes`, `Heading>Playground`, `Primary` и `Controls of={Playground}` (см. раздел [Структура docs page](#структура-docs-page)).
+
+> **MCP bundle:** `Playground` и `VisualTests` не попадают в `mcp-data.json` — у них нет кода для агента (Playground интерактивен, VisualTests — скриншот-регрессия). Фильтр реализован в `scripts/generateMcpData.ts` (`EXCLUDED_STORIES`). В остальном для MCP нужен файл примера в `examples/{Component}/` и ссылка на него из колонки `Example file` в `{Component}-ai.md`.
 
 ---
 
@@ -144,6 +154,22 @@ parameters: {
 },
 ```
 
+Если у компонента нет настраиваемых props (см. [Когда не создавать Playground](#когда-не-создавать-playground)), блок Playground убирается, а вместе с ним и блок `Props` — `ArgTypes` без props покажет пустую таблицу:
+
+```tsx
+parameters: {
+    docs: {
+        page: () => (
+            <>
+                <Title />
+                <Description />
+                <Stories />
+            </>
+        ),
+    },
+},
+```
+
 ---
 
 ## Playground
@@ -152,6 +178,21 @@ parameters: {
 
 Playground показывает только те props, которые реально помогают исследовать компонент.
 
+### Когда не создавать Playground
+
+Если у компонента нет настраиваемых props (только `children` и стандартные HTML-атрибуты), Playground не создаётся — нечего класть в Controls. Типичный случай: контейнер-обёртка вроде `ListItem`, `ListItemControls`, `ChipGroup`.
+
+В этом случае:
+
+- В файле stories нет экспорта `Playground` и связанного с ним example-файла.
+- В docs page убираются:
+  - `Heading>Props` и `ArgTypes of={Component}` — без props таблица будет пустой.
+  - `Heading>Playground`, `Primary`, `Controls of={Playground}`.
+  - См. вариант без Playground в разделе [Структура docs page](#структура-docs-page).
+- Из импортов `@storybook/addon-docs/blocks` удаляются `ArgTypes`, `Heading`, `Primary`, `Controls` — остаются только `Title`, `Description`, `Stories`.
+
+Если props всего один-два, но они имеют визуальный эффект — Playground всё равно создаётся, и блок `Props` остаётся.
+
 ### Разделение Controls
 
 - Свойства, являющиеся props компонента, располагаются в блоке **Props** (по умолчанию).
@@ -210,7 +251,7 @@ tags: ["!autodocs"],
 | Заполнение необязательного props       | Название props **как есть**               | `disabled` → `Disabled` |
 | Нестандартные варианты наполнения      | `With` + вариант                          | `WithTextAndIcon`       |
 | Композиции / production примеры        | `Example`                                 | `Example`               |
-| Скриншот-тесты                         | `Visual tests`                            | `Visual tests`          |
+| Скриншот-тесты                         | `VisualTests`                             | `VisualTests`           |
 
 ---
 
@@ -255,6 +296,25 @@ import { Button } from "../../../src/components/Button/Button";
 
 Для legacy story-файлов не нужно устраивать отдельную миграцию импортов без задачи.
 
+### Колбэки в примерах
+
+| Файл | Что использовать | Почему |
+| --- | --- | --- |
+| `Playground.tsx`, `VisualTests`-рендеры | `action("eventName")` из `storybook/actions` | Код не показывается через `?raw`, поэтому storybook-импорт допустим. Помогает увидеть события во вкладке Actions при ручной проверке. |
+| Копируемые примеры (`Default`, `Sizes`, `Statuses`, `With*`, production-like `Example`) | Пустые функции `() => {}` | Код показывается через `?raw` и должен копироваться без правок. `alert()`, `console.log()` и `import { action } from "storybook/actions"` ломают копируемость и создают side effects. |
+
+```tsx
+// Playground.tsx
+import { action } from "storybook/actions";
+
+<Component onChange={action("onChange")} />;
+```
+
+```tsx
+// Default.tsx
+<Component onChange={() => {}} />;
+```
+
 ---
 
 ## Скриншот-тесты
@@ -386,12 +446,14 @@ render: () => (
 В modern pattern для каждого примера экспортируются два значения — сам компонент и его исходный код:
 
 ```ts
-export * from "./DefaultExample";
-export { default as DefaultExampleSource } from "./DefaultExample?raw";
-export * from "./SizesExample";
-export { default as SizesExampleSource } from "./SizesExample?raw";
+export * from "./Default";
+export { default as DefaultSource } from "./Default?raw";
+export * from "./Sizes";
+export { default as SizesSource } from "./Sizes?raw";
 ```
 
+> **Имена.** Файл и экспорт-функция называются как story (`Default.tsx` экспортирует `Default`). Source-константа добавляет суффикс `Source` (`DefaultSource`). Из-за коллизии с именем story-экспорта в `*.stories.tsx` импорт компонента-примера делается через alias — см. ниже.
+
 ---
 
 ## Подключение примеров к стори
@@ -399,14 +461,15 @@ export { default as SizesExampleSource } from "./SizesExample?raw";
 В modern pattern каждая документационная стори подключает пример и его исходный код через `?raw`:
 
 ```tsx
+import { Default as DefaultRender, DefaultSource } from "./examples";
+
 export const Default: StoryObj<typeof Component> = {
-    name: "Default",
-    render: DefaultExample,
+    render: DefaultRender,
     parameters: {
+        controls: { disable: true },
         docs: {
-            controls: { disable: true },
             source: {
-                code: DefaultExampleSource,
+                code: DefaultSource,
                 language: "tsx",
             },
         },
@@ -414,6 +477,8 @@ export const Default: StoryObj<typeof Component> = {
 };
 ```
 
+> **Alias обязателен.** Имя экспорта-функции (`Default`) совпадает с именем story-экспорта (`Default: StoryObj`), поэтому в импорте используется `Default as DefaultRender`. Source-константа конфликта не вызывает (`DefaultSource`), её импортируем без alias. То же относится к Playground (`Playground as PlaygroundRender`).
+
 ---
 
 ## Полный пример
@@ -425,7 +490,13 @@ import React, { useState, useCallback } from "react";
 import { Meta, StoryObj } from "@storybook/react";
 import { Title, Description, Primary, Controls, Stories, ArgTypes, Heading } from "@storybook/addon-docs/blocks";
 import { ComponentName, EComponentSize } from "@sberbusiness/triplex-next";
-import { DefaultExample, DefaultExampleSource, SizesExample, SizesExampleSource } from "./examples";
+import {
+    Default as DefaultRender,
+    DefaultSource,
+    Playground as PlaygroundRender,
+    Sizes as SizesRender,
+    SizesSource,
+} from "./examples";
 
 const meta = {
     title: "Components/Group/ComponentName",
@@ -457,9 +528,7 @@ export const Playground: StoryObj<typeof meta> = {
         size: EComponentSize.LG,
         // ...остальные args
     },
-    render: ({ ...args }) => {
-        // ...render с useState и обработчиками
-    },
+    render: PlaygroundRender,
     argTypes: {
         size: {
             control: { type: "select" },
@@ -481,13 +550,12 @@ export const Playground: StoryObj<typeof meta> = {
 };
 
 export const Default: StoryObj<typeof ComponentName> = {
-    name: "Default",
-    render: DefaultExample,
+    render: DefaultRender,
     parameters: {
         controls: { disable: true },
         docs: {
             source: {
-                code: DefaultExampleSource,
+                code: DefaultSource,
                 language: "tsx",
             },
         },
@@ -495,13 +563,12 @@ export const Default: StoryObj<typeof ComponentName> = {
 };
 
 export const Sizes: StoryObj<typeof ComponentName> = {
-    name: "Sizes",
-    render: SizesExample,
+    render: SizesRender,
     parameters: {
         controls: { disable: true },
         docs: {
             source: {
-                code: SizesExampleSource,
+                code: SizesSource,
                 language: "tsx",
             },
         },
@@ -509,13 +576,13 @@ export const Sizes: StoryObj<typeof ComponentName> = {
 };
 ```
 
-### `examples/DefaultExample.tsx`
+### `examples/Default.tsx`
 
 ```tsx
 import React, { useState } from "react";
 import { ComponentName, EComponentSize } from "@sberbusiness/triplex-next";
 
-export const DefaultExample = () => {
+export const Default = () => {
     const [value, setValue] = useState<string>("");
 
     const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => setValue(event.target.value);
@@ -528,7 +595,7 @@ export const DefaultExample = () => {
 };
 ```
 
-### `examples/SizesExample.tsx`
+### `examples/Sizes.tsx`
 
 ```tsx
 import React, { useState } from "react";
@@ -553,7 +620,7 @@ const SizeItem = ({ size }: ISizeItemProps) => {
 
 const SIZES = Object.values(EComponentSize);
 
-export const SizesExample = () => (
+export const Sizes = () => (
     <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
         {SIZES.map((size) => (
             <SizeItem key={size} size={size} />
@@ -565,10 +632,10 @@ export const SizesExample = () => (
 ### `examples/index.ts`
 
 ```ts
-export * from "./DefaultExample";
-export { default as DefaultExampleSource } from "./DefaultExample?raw";
-export * from "./SizesExample";
-export { default as SizesExampleSource } from "./SizesExample?raw";
+export * from "./Default";
+export { default as DefaultSource } from "./Default?raw";
+export * from "./Sizes";
+export { default as SizesSource } from "./Sizes?raw";
 ```
 
 ---
@@ -579,10 +646,10 @@ export { default as SizesExampleSource } from "./SizesExample?raw";
 
 ### Документация и структура
 
-- [ ] Есть docs page с `Title`, `Description`, `ArgTypes`, `Playground`, `Stories`
-- [ ] Playground имеет Controls, не показывает код (`sourceState: "none"`)
-- [ ] Playground исключён из скриншот-тестов (`testRunner: { skip: true }`)
-- [ ] Playground скрыт из autodocs (`tags: ["!autodocs"]`)
+- [ ] Есть docs page с `Title`, `Description`, `ArgTypes`, `Playground`, `Stories` (если у компонента нет настраиваемых props — блоки `Props`/`ArgTypes` и `Playground` пропускаются)
+- [ ] Playground имеет Controls, не показывает код (`sourceState: "none"`) — если есть
+- [ ] Playground исключён из скриншот-тестов (`testRunner: { skip: true }`) — если есть
+- [ ] Playground скрыт из autodocs (`tags: ["!autodocs"]`) — если есть
 - [ ] Все документационные стори, кроме Playground, **не** имеют Controls (`controls: { disable: true }`)
 - [ ] Все документационные стори, кроме Playground, показывают пример кода через `source.code`
 - [ ] Все примеры вынесены в `examples/` и реэкспортированы через `index.ts`
@@ -595,14 +662,17 @@ export { default as SizesExampleSource } from "./SizesExample?raw";
 
 ### Скриншот-тесты
 
+Скриншот-тесты обязательны для UI-компонентов. Без baseline-файлов в `__screenshots__/` регрессию не поймать.
+
 - [ ] Playground исключён из скриншот-тестов (`testRunner: { skip: true }`)
 - [ ] Нет дублирующих скриншотов — визуально идентичные стори исключены через `testRunner: { skip: true }`
 - [ ] Все ключевые визуальные состояния покрыты (размеры, статусы, заполненные поля, фокус)
 - [ ] Если основных сторей недостаточно — создана Visual tests с недостающими состояниями
 - [ ] Visual tests скрыта из autodocs (`tags: ["!autodocs"]`) и не показывает код
-- [ ] Если компонент требует взаимодействия (dropdown, tooltip) — реализован `play` в Visual tests
+- [ ] Если компонент требует взаимодействия (dropdown, tooltip, modal, popover) — реализован `play` в Visual tests
 - [ ] Данные в Visual tests захардкожены (нет `new Date()`, `Math.random()`)
 - [ ] Контейнеры имеют фиксированные размеры для стабильного layout'а
+- [ ] Для каждой не-skip story есть baseline-файлы в `__screenshots__/{story-id}--xs.png` и `--xl.png`. Если baseline ещё нет — запустить `GitHub Actions → Update Visual Snapshots` на ветке (CI закоммитит скриншоты), и только потом мержить.
 
 ### Для небольших изменений в legacy stories
 

package/bundle/guides/template.md

@@ -1,8 +1,6 @@
 ---
 component: ComponentName
 category: Category
-figma-node: "NODE_ID"
-figma-file: "https://www.figma.com/design/FILE_KEY/..."
 related: []
 tokens: []
 stories: stories/Category/ComponentName.stories.tsx
@@ -19,8 +17,6 @@ version: "1.0"
 Описывай намерения и ограничения, которые не видны из кода.
 
 Frontmatter:
-- figma-node: raw-значение параметра `node-id` из URL Figma, например `1-328`
-- figma-file: URL файла / design-ссылка, из которой при необходимости можно получить file key
 - tokens: список CSS-переменных, которые компонент использует
 - related: список связанных компонентов (строки, имена)
 
@@ -139,9 +135,9 @@ VisualTests — скриншот-регрессия. Но в таблице их
 
 | Story | Example file | Что демонстрирует |
 |---|---|---|
-| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль всех props |
-| `Themes` | `ThemesExample.tsx` | Все визуальные темы |
-| `Sizes` | `SizesExample.tsx` | Размеры SM / MD / LG |
+| `Playground` | `Playground.tsx` | Интерактивный контроль всех props |
+| `Themes` | `Themes.tsx` | Все визуальные темы |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG |
 
 ---
 

package/bundle/guides/tests.md

@@ -38,6 +38,48 @@ src/components/{ComponentName}/__tests__/{ComponentName}.test.tsx
 
 Один файл на компонент. Если компонент имеет субкомпоненты (ButtonIcon, ButtonDropdown), тесты субкомпонентов — в отдельных файлах той же локальной папки тестов.
 
+### Импорты `vitest` — только в `*.test.ts` / `*.test.tsx` ⚠️
+
+**Правило:** `import ... from "vitest"` (а также `@testing-library/*`, `storybook/test`)
+допустим **исключительно** в файлах с постфиксом `.test.ts` / `.test.tsx`,
+в `vitest.setup.ts` и в `test-utils/`. Нигде больше.
+
+Причина — сборка. `vite.config.ts` строит entry-точку из **каждого** файла
+`src/**/*.{ts,tsx}`, кроме исключённых глобом. Любой файл внутри `src/`, который
+импортирует `vitest` и не подпадает под исключения, попадает в бандл, а вместе с
+ним vitest уезжает в общий чанк `vendor` — тот самый, который тянут почти все
+компоненты. Потребитель падает на старте:
+
+```text
+Uncaught Error: Vitest failed to access its internal state.
+```
+
+Именно это произошло в 1.39.0 из-за файла `src/components/Carousel/__tests__/utils.ts`
+(хелпер без постфикса `.test`). Чанк `vendor` вырос с 640 KB до 1.28 MB.
+
+**Общие тестовые хелперы** (моки `ResizeObserver`, фейковые `Touch`, подмена
+размеров элементов и т.п.) кладём в `test-utils/` в корне репозитория — вне `src/`,
+поэтому сборка их физически не видит:
+
+```typescript
+// ✅ src/components/Carousel/__tests__/CarouselRoot.test.tsx
+import { getResizeCallback, mockElementSize } from "../../../../test-utils/dom";
+
+// ❌ src/components/Carousel/__tests__/utils.ts — станет entry-точкой сборки
+import { vi } from "vitest";
+```
+
+Не называй хелпер `utils.ts` рядом с `utils.test.tsx`: `__tests__/utils.test.tsx` —
+это **тесты для `../utils.ts`** компонента, а не тесты хелпера. Хелперы нельзя
+класть и в сам `*.test.tsx`-файл: при импорте из другого теста его `describe`
+зарегистрируется повторно и тесты прогонятся несколько раз.
+
+Страховка на уровне сборки: `npm run build` запускает `scripts/checkBundleSize.js`
+и падает, если в `dist` превышен один из двух лимитов — **700 KB на отдельный
+JS-файл** (ловит распухший `vendor`: всё из `node_modules` сливается в него
+единственным чанком) или **2000 KB суммарно по всем JS-файлам** (ловит утечку
+кода мимо `node_modules` и медленный рост множества мелких файлов).
+
 ### Импорты
 
 ```typescript
@@ -216,11 +258,15 @@ afterEach(() => {
 
 ### Когда нужны Visual tests
 
-Создавай отдельную `VisualTests` story если:
-- Компонент требует взаимодействия перед скриншотом (открыть dropdown, hover, focus).
+**Скриншот-тесты обязательны для любого компонента с видимым UI.** По умолчанию все не-Playground stories автоматически снимаются на двух viewport'ах (xs/xl) — это базовое покрытие. Если оно недостаточно, создавай отдельную `VisualTests` story.
+
+Создавай `VisualTests` story если:
+- Компонент требует взаимодействия перед скриншотом (открыть dropdown, hover, focus, открыть модалку/попап) — **обязательно** для overlay-компонентов (Modal, Tooltip, Popover, Dropdown, LightBox).
 - Нужно покрыть состояние, которого нет в документационных stories.
 - Нужно объединить несколько вариантов в один скриншот.
 
+После добавления новых stories обязательно сгенерируй baseline-скриншоты через CI workflow — без baseline скриншот-теста фактически нет, и regression не поймается.
+
 ### Обновление baseline
 
 ```text