@sberbusiness/triplex-next-mcp-server 0.24.0-beta1

package/bundle/components/DesignTokens.md

@@ -0,0 +1,385 @@
+---
+component: DesignTokens
+category: Infrastructure
+figma-node: ""
+figma-file: ""
+related: [ThemeProvider, All components]
+tokens: []
+stories: stories/DesignTokens/DesignTokens.stories.tsx
+version: "1.0"
+---
+
+# DesignTokens
+
+## Назначение
+
+Это **не визуальный компонент**, а инфраструктурный модуль: единственный
+источник истины для **дизайн-токенов** библиотеки. Определяет:
+
+1. **Core-токены** — общая палитра (ColorBrand, ColorNeutral, ColorError,
+   ColorInfo, ColorSuccess, ColorSystem, ColorWarning, ColorDarkNeutral,
+   ColorNeutralAlpha, ColorDarkNeutralAlpha).
+2. **Component-токены** — специфические токены на каждый компонент
+   (Button, Chip, Calendar, Card, Checkbox, FormField, Island, …).
+3. **Тёмная тема** — параллельные объекты `*ThemeDark` с теми же
+   ключами, но другими значениями.
+4. **Утилиты** — `DesignTokenUtils` (`getStyle`, `getCSSVariableByTokenGroup`,
+   `getTokenValue`, `getComponentTokens`, `getStyleByTokens`) для сборки
+   CSS-переменных и разрешения ref'ов.
+
+`ThemeProvider` использует этот модуль, чтобы вставить `<style>` с
+CSS-переменными (по текущей теме) в DOM. Компоненты читают переменные
+через `var(--triplex-next-{group}-{token}-{version})`.
+
+Используй когда: нужно расширить / кастомизировать токены; узнать
+точный список токенов какого-то компонента; понять разрешение ref'а
+(`{ref: "ColorBrand.60"}` → финальное значение).
+Не используй как: обычный React-компонент — это TS-объекты и утилиты,
+не JSX.
+
+---
+
+## Файловая структура
+
+```text
+src/components/DesignTokens/
+├── DesignTokensCore.ts                   # Light-тема core-токенов (общая палитра)
+├── DesignTokensCoreThemeDark.ts          # Dark-тема core-токенов
+├── DesignTokensComponents.ts             # Light-тема component-токенов (сбор всех компонентов)
+├── DesignTokensComponentsThemeDark.ts    # Dark-тема component-токенов
+├── DesignTokenUtils.ts                   # Утилиты: getStyle, getTokenValue, getCSSVariableByTokenGroup…
+├── GetTokensValueByTheme.ts              # Хелпер: выбор { value | ref } по теме из [light, dark]
+├── index.ts                              # Barrel: 4 объекта токенов
+├── components/                           # По файлу на компонент: keys + types + base-токены
+│   ├── Button.ts, Chip.ts, Calendar.ts,
+│   └── … (~54 файла, по одному на компонент)
+├── types/
+│   ├── DesignTokenTypes.ts               # IDesignTokenValueString, IDesignTokenValueRef, TDesignTokenValues
+│   └── DesignTokensTypes.ts              # TDesignTokensCore, TDesignTokensComponents, TDesignTokens*
+└── __tests__/
+```
+
+Особенности:
+- **`__tests__` есть** — проверяют, что токены разрешаются корректно
+  и что тёмная тема покрывает все ключи светлой.
+- **~54 файла в `components/`** — по файлу на компонент. Каждый
+  определяет `designTokensComponents{Name}Keys` (as const) + типы +
+  базовые значения.
+- **Публичный API через `index.ts`**: 4 объекта — `DesignTokensCore`,
+  `DesignTokensCoreThemeDark`, `DesignTokensComponents`,
+  `DesignTokensComponentsThemeDark`. Утилиты импортируются отдельно.
+- **Генерация типов**: `src/generated/refTokenTypes.ts` содержит
+  `designTokensRefs` — union всех валидных путей ref'а (авто-генерация).
+
+---
+
+## Core API
+
+### `TDesignTokenValue`
+
+```ts
+interface IDesignTokenValueString {
+    ref?: undefined;
+    value: string;     // "#fff", "16px", "rgba(...)"
+}
+interface IDesignTokenValueRef {
+    value?: undefined;
+    ref: (typeof designTokensRefs)[number];  // "ColorBrand.60" и т. п.
+}
+type TDesignTokenValue = IDesignTokenValueString | IDesignTokenValueRef;
+type TDesignTokenValues = [TDesignTokenValue, TDesignTokenValue];  // [light, dark]
+```
+
+**Инвариант типа:** либо `value` либо `ref`, не оба. Это через
+`?: undefined` гарантировано на уровне типа (дискриминированный union).
+
+### Core-группы (`DesignTokensCore`)
+
+```ts
+TDesignTokensCore = ColorBrand &
+    ColorDarkNeutralAlpha & ColorDarkNeutral &
+    ColorError & ColorInfo &
+    ColorNeutralAlpha & ColorNeutral &
+    ColorSuccess & ColorSystem & ColorWarning;
+```
+
+**Keys** у каждой группы — `"0" | "10" | ... | "100"` (шаг 10),
+у `ColorBrand` и `ColorSystem` дополнительно `"95"`. Это палитра
+оттенков — 0 = чёрный конец, 100 = светлый конец.
+
+**Пример:**
+```ts
+ColorBrand: {
+    60: { value: "#19BDB0" },    // "основной" брендовый
+    50: { value: "#21A19A" },
+    ...
+}
+```
+
+Core-токены **всегда `{value: "..."}`**, не `ref`. Ref используется
+только в component-токенах, которые ссылаются на core.
+
+### Component-токены
+
+Каждый компонент в `components/*.ts`:
+
+```ts
+export const designTokensComponentsButtonKeys = [
+    "General_Background_Active",
+    "General_Background_Default",
+    "General_Background_Disabled",
+    "General_Background_Hover",
+    "General_Color_Active",
+    "General_Color_Default",
+    ...
+] as const;
+
+export type TDesignTokensComponentsButtonKeys = (typeof designTokensComponentsButtonKeys)[number];
+export type TDesignTokensComponentsButtonValue = Record<TDesignTokensComponentsButtonKeys, TDesignTokenValue>;
+export type TDesignTokensComponentsButtonValues = Record<TDesignTokensComponentsButtonKeys, TDesignTokenValues>;
+export type TDesignTokensComponentsButton = { Button: TDesignTokensComponentsButtonValue };
+
+// Базовые токены (раскрываются через GetTokensValueByTheme):
+export const Button_Tokens: TDesignTokensComponentsButtonValues = {
+    General_Background_Default: [
+        { ref: "ColorBrand.60" },    // light
+        { ref: "ColorBrand.50" },    // dark
+    ],
+    ...
+};
+```
+
+### Naming convention для токенов компонента
+
+Имена токенов — **`{Variant}_{Property}_{State}`** (snake-case
+подлиннее):
+- `General_Background_Default`
+- `Secondary_Color_Hover`
+- `Danger_Shadow_Focus`
+- `SecondaryLight_Background_Active`
+- `Link_Color_Disabled`
+
+Paттерн — variant (General/Primary/Secondary/Danger/Link/Icon/…),
+свойство (Background/Color/Shadow/Border), состояние
+(Default/Hover/Active/Focus/Disabled).
+
+Не все компоненты имеют одну и ту же структуру — например, у Chip или
+FormField другие variants/states, см. соответствующие `components/*.ts`.
+
+### CSS-переменные имеют версионный суффикс
+
+```ts
+// DesignTokenUtils.getCSSVariableByTokenGroup:
+let tokenVersion = process.env.npm_package_version;
+tokenVersion = tokenVersion!.replace(/\./g, "-");
+// → --triplex-next-Button-General_Background_Default-1-0-0: #19BDB0;
+```
+
+**`process.env.npm_package_version` подставляется в CSS-переменные** и
+**в `data-tx`** атрибуты компонентов. Позволяет держать несколько
+версий библиотеки параллельно без конфликта переменных. **Не объединять
+в одну строку** (`.replace` на `process.env.npm_package_version!`) —
+rollup не заменяет в сложных выражениях, нужна отдельная строка
+присвоения.
+
+---
+
+## `DesignTokenUtils` API
+
+```ts
+interface IDesignTokenUtils {
+    getCSSVariableByTokenGroup(tokenGroup, tokens): string
+    getComponentTokens(componentName): { core: string[]; components: string[] }
+    getStyle(theme, tokens): string
+    getStyleByTokens(tokens): string
+    getTokenValue(tokenValue, tokens): string
+}
+```
+
+### `getStyle(theme, tokens)` — главный entry для ThemeProvider
+
+```ts
+getStyle(ETriplexNextTheme.LIGHT, {}) →
+    "--triplex-next-ColorBrand-0-1-0-0: #1F3336;
+     --triplex-next-ColorBrand-10-1-0-0: #0B3A3C;
+     ...
+     --triplex-next-Button-General_Background_Default-1-0-0: #19BDB0;"
+```
+
+Реализация использует `defaultsDeep` из `lodash-es` для мерджа
+переопределений потребителя с дефолтами библиотеки:
+
+```ts
+const nextTokens = defaultsDeep({}, tokens, DesignTokensCore, DesignTokensComponents);
+```
+
+**Порядок важен:** `tokens` (переопределения) побеждают дефолты.
+
+### `getTokenValue(tokenValue, tokens)` — разрешение ref'ов
+
+```ts
+{ref: "ColorBrand.60"} → "#19BDB0"
+```
+
+Рекурсивно: если `ref` ведёт на другой `ref`, идёт дальше. **Без
+защиты от цикла** — если токен ссылается сам на себя или образует
+цикл, будет бесконечная рекурсия. Инвариант:
+`designTokensRefs` генерируется так, что циклов быть не должно.
+
+### `GetTokensValueByTheme(theme, tokens)` — выбор [light, dark]
+
+```ts
+GetTokensValueByTheme(ETriplexNextTheme.DARK, {
+    Primary_Background: [{value: "white"}, {value: "black"}]
+})
+// → { Primary_Background: {value: "black"} }
+```
+
+Преобразует `Record<Key, [light, dark]>` → `Record<Key, TDesignTokenValue>`,
+выбирая значение по `theme`. Используется в `Button_Tokens` и т. п.
+для компактного объявления обеих тем в одном файле.
+
+---
+
+## Ключевые особенности реализации
+
+### `process.env.npm_package_version` в CSS-переменных
+
+Версия библиотеки встраивается в имя каждой CSS-переменной с
+заменой `.` → `-`. Это позволяет **двум версиям библиотеки
+сосуществовать** на одной странице (например, legacy + new). Цена —
+все потребители `var(...)` должны использовать актуальный суффикс
+версии.
+
+LESS mixin'ы, использующие эти переменные, заменяют суффикс на лету
+(через rollup-плагин). Потребители **не должны** хардкодить версию
+в своих стилях.
+
+### `defaultsDeep` (lodash-es) — мердж
+
+```ts
+defaultsDeep({}, tokens, DesignTokensCore, DesignTokensComponents)
+```
+
+**`defaultsDeep` vs `merge`**: defaults НЕ переписывают уже заданные
+ключи — они лишь **дозаполняют** отсутствующие. Поэтому порядок в
+`defaultsDeep` — обратный от `merge` (правее = более дефолтное).
+
+**Потребитель:** `tokens` (опциональные переопределения) — первый,
+он "побеждает". Core и Components — последние дефолты.
+
+### `getComponentTokens(componentName)` — возвращает список имён
+
+```ts
+getComponentTokens("Button") → {
+    components: ["Button.General_Background_Active", ...],
+    core: [],
+}
+```
+
+Используется в DocBlock'ах и туллингах. **Core сейчас всегда пустой**
+(см. реализацию) — не сканирует core-токены, возвращает только
+component-local. Если нужны core-зависимости — они выводятся из
+`ref` в component-tokens, но этот util не разворачивает их.
+
+### Ссылочные токены через `ref` — один уровень косвенности
+
+```ts
+// Button.ts:
+General_Background_Default: [{ref: "ColorBrand.60"}, {ref: "ColorBrand.50"}]
+```
+
+Переопределяя `ColorBrand.60` в темах, потребитель меняет **все**
+компоненты, использующие этот ref. Это **главное преимущество**
+архитектуры — центральный контроль палитры.
+
+### `ThemeProvider` — единственный консумент
+
+`DesignTokens` сам по себе **не подключается в DOM**. `ThemeProvider`
+вызывает `DesignTokenUtils.getStyle(theme, userOverrides)` и вставляет
+результат в `<style>` или использует via `:root { --... }`. Смотри
+`ThemeProvider-AI.md` (ещё не создан).
+
+---
+
+## Инварианты
+
+- **`IDesignTokenValueString` и `IDesignTokenValueRef`** — discriminated
+  union, `ref?: undefined` / `value?: undefined` нужны для дискриминации.
+  Не удалять `?: undefined`.
+- **Core-токены всегда `{value: "..."}`** — не используют `ref`. Если
+  нужно — будет циклическая ссылка.
+- **`TDesignTokenValues = [light, dark]`** — кортеж ровно из двух
+  элементов. Третья тема потребует расширения типа.
+- **CSS-переменные имеют суффикс `process.env.npm_package_version`** —
+  не удалять. Необходим для multi-version coexistence.
+- **`defaultsDeep` порядок** — `tokens` первый, `Core`/`Components`
+  последние. Обратный порядок сломает override.
+- **Naming convention `{Variant}_{Property}_{State}`** — менять только
+  с миграцией потребителей (CSS переменная — public API).
+- **`designTokensComponents*Keys as const`** — обязателен `as const`
+  для точной типизации.
+- **`DesignTokensComponentsThemeDark` должен покрывать те же ключи**,
+  что `DesignTokensComponents`. Тесты проверяют.
+- **Утилиты не мутируют входные объекты** — `defaultsDeep({}, ...)`
+  с пустым первым аргументом.
+- **`getTokenValue` не имеет cycle-detection** — структура токенов
+  должна быть ациклична.
+
+---
+
+## Accessibility
+
+N/A — это инфраструктура. Но именно через токены реализуется "contrast
+themes" и tuning цветов для accessibility. Потребитель передаёт
+переопределения в `ThemeProvider.tokens={...}`, получает новую палитру.
+
+---
+
+## Дизайн-токены
+
+Сам модуль **производит** все токены библиотеки. Список групп:
+
+**Core:**
+ColorBrand, ColorDarkNeutral, ColorDarkNeutralAlpha, ColorError,
+ColorInfo, ColorNeutral, ColorNeutralAlpha, ColorSuccess, ColorSystem,
+ColorWarning (по 11–12 оттенков каждая).
+
+**Components (~54):**
+AlertContext, AlertProcess, Avatar, Badge, Button, Calendar, Card,
+Checkbox, Chip, Divider, Dropdown, DropdownList, DropdownMobile,
+DropdownMobileList, FooterPage, FormField, HeaderPage, Island,
+IslandAccordion, IslandWidget, LightBox, Link, ListItem,
+ListItemControlsButton, ListMaster, Loader, LoaderScreen, Marker,
+MarkerStatus, ModalWindow, MultiselectField, Notification, Overlay,
+Pagination, Radio, SegmentedControl, SegmentedControlSegment, Skeleton,
+Slider, SmallInput, SMSField, StatusTracker, Step, Stepper, TableBasic,
+Tabs, TabsLine, Tag, TagColor, Tooltip, TopOverlay, Typography,
+UploadZone.
+
+---
+
+## Связанные компоненты
+
+- `ThemeProvider` — единственный консумент. Ставит `<style>` с
+  `getStyle(theme, tokens)`.
+- **Все визуальные компоненты** — используют
+  `var(--triplex-next-{group}-{token}-{version})` через LESS mixin'ы.
+- `generated/refTokenTypes.ts` — сгенерированный union всех валидных
+  ref-путей.
+
+---
+
+## Stories
+
+`stories/DesignTokens/DesignTokens.stories.tsx`
+
+Демонстрируют палитру core-токенов (визуальный шоукейс цветов).
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |

package/bundle/components/Divider.md

@@ -0,0 +1,196 @@
+---
+component: Divider
+category: Layout
+figma-node: ""
+figma-file: ""
+related: [Gap, Row, Col]
+tokens: [Divider_Background]
+stories: stories/Divider/Divider.stories.tsx
+version: "1.0"
+---
+
+# Divider
+
+## Назначение
+
+Горизонтальная линия-разделитель (`<hr>`) высотой 1px с токенизированным
+фоном (`--triplex-next-Divider-Background`) и опциональными top/bottom
+отступами из фиксированной шкалы 4/8/12/16/20/24/28/32 px.
+
+Используется для визуального разделения секций внутри Card, Island,
+формы и т. п.
+
+Используй когда: нужна тонкая разделительная линия между блоками.
+Не используй когда: нужен вертикальный разделитель (`Divider` только
+горизонтальный); нужны только отступы без линии — бери `Gap`.
+
+---
+
+## Файловая структура
+
+```text
+src/components/Divider/
+├── Divider.tsx                         # FC, НЕ forwardRef
+├── index.ts                            # Barrel
+├── styles/Divider.module.less          # background + each-loop для margin-top/bottom
+└── __tests__/Divider.test.tsx
+```
+
+Особенности:
+- **НЕ `forwardRef`** — FC без ref-форвардинга. Известный debt. Не
+  добавлять точечно.
+- **Рендерит семантичный `<hr>`** (не `<div>`). Это важно для a11y —
+  screen reader'ы объявят как разделитель.
+- **Нет `data-tx`** — не ставит атрибут версии.
+- **Тесты есть** — `Divider.test.tsx` проверяет классы по размерам.
+
+---
+
+## Варианты и props
+
+### `IDividerProps extends React.HTMLAttributes<HTMLHRElement>`
+
+| Prop | Тип | Default | Описание |
+|---|---|---|---|
+| `marginTopSize` | `TDividerMarginSize` (4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 28 \| 32) | — | Отступ сверху в px. Если не задан — 0. |
+| `marginBottomSize` | `TDividerMarginSize` | — | Отступ снизу в px. Если не задан — 0. |
+| `className` | `string` | — | Через `clsx`. |
+| `...HTMLHRAttributes` | — | — | Стандартные атрибуты `<hr>`. |
+
+### `TDividerMarginSize = 4 | 8 | 12 | 16 | 20 | 24 | 28 | 32`
+
+Литерально-числовой union. **Не `number`** — типизация закрывает
+кастомные значения. Если нужно 0 — не передавать пропс. Если нужно 40 —
+не поддерживается, разделитель не ставится туда, где нужен нестандартный
+gap.
+
+---
+
+## Ключевые особенности реализации
+
+### CSS-классы по размеру через LESS `each` + shape
+
+```less
+@size: 4, 8, 12, 16, 20, 24, 28, 32;
+each(@size, {
+    .marginTopSize-@{value} { margin-top: ~'@{value}px'; }
+    .marginBottomSize-@{value} { margin-bottom: ~'@{value}px'; }
+});
+```
+
+**LESS `each`** + **escape-строка** `~'@{value}px'` генерирует по два
+класса на каждый размер (16 классов всего). Если нужен новый размер —
+добавить в `@size` список и в `TDividerMarginSize` TS-литерал.
+**TS-литерал — единственная связь между LESS и TS**: TS проверяет
+что пропс в списке, LESS обеспечивает наличие класса. Если
+рассинхронизировать — получишь `styles[undefined]`.
+
+### Сборка `className` через `clsx`
+
+```ts
+const classNames = clsx(
+    styles.divider,
+    marginTopSize && styles[`marginTopSize-${marginTopSize}`],
+    marginBottomSize && styles[`marginBottomSize-${marginBottomSize}`],
+    className,
+);
+```
+
+**Дефолт `styles.divider`** задаёт фон + height 1px + `margin: 0` +
+`border: none`. Без `border: none` браузерный `<hr>` имеет свою
+border/margin.
+
+**Если `marginTopSize` undefined/0 — класс не добавляется** (короткое
+замыкание `&&`). 0 не поддерживается, но undefined — да.
+
+### Токен `--triplex-next-Divider-Background`
+
+```less
+.divider {
+    height: 1px;
+    margin: 0;
+    background: var(--triplex-next-Divider-Background);
+    border: none;
+}
+```
+
+Цвет разделителя задаётся одним токеном (см. компонент Divider в
+`DesignTokens/components/Divider.ts`). В тёмной теме меняется
+автоматически через ThemeProvider.
+
+### Override через `style` / `className`
+
+Потребитель может:
+1. Передать `className` — мержится через clsx.
+2. Передать `style={{margin: ...}}` — перебьёт встроенные margin-классы.
+3. Переопределить `--triplex-next-Divider-Background` в scope.
+
+### `hr` — не `div`
+
+Семантичность: screen reader'ы читают `<hr>` как разделитель
+(`role="separator"` по умолчанию).
+
+---
+
+## Инварианты
+
+- **Рендерит `<hr>`**, не `<div>`. Не менять — пострадает семантика.
+- **`TDividerMarginSize` фиксирован 4/8/12/16/20/24/28/32** — не
+  расширять без выравнивания с дизайн-системой и LESS-списком.
+- **LESS `@size` и TS-литерал должны совпадать** — иначе классы
+  не сгенерируются для нового размера.
+- **`border: none; margin: 0;`** в base-классе — без них браузерный
+  `<hr>` ломает дизайн.
+- **`--triplex-next-Divider-Background` токен** — единственный способ
+  поменять цвет. Не хардкодить hex.
+- **НЕТ forwardRef** — известный debt.
+- **НЕТ `data-tx`** — наследованный пропуск.
+
+---
+
+## Accessibility
+
+- **`<hr>`** — встроенная семантика разделителя (`role="separator"`).
+  Screen reader'ы читают как "separator" / "разделитель".
+- **Не интерактивный** — tabindex не ставится, клавиатурой не
+  взаимодействует.
+- **Если нужен "assistive"-разделитель внутри списка** — оборачивать
+  в `<li role="separator">`. Divider сам этого не делает.
+
+---
+
+## Дизайн-токены
+
+- `--triplex-next-Divider-Background` — цвет линии.
+
+Определение в `src/components/DesignTokens/components/Divider.ts`.
+
+---
+
+## Связанные компоненты
+
+- `Gap` (`src/components/Gap`) — отступ без линии.
+- `Row`/`Col` — grid-система (Divider часто между Row'ами).
+- `Card`, `Island`, `Page` — типичные контейнеры с разделителями
+  внутри.
+
+---
+
+## Stories
+
+`stories/Divider/Divider.stories.tsx`
+Примеры: `stories/Divider/examples/`
+
+Типовые stories:
+- `Default` — разделитель без отступов
+- `WithMargins` — разделитель с margin-top/bottom
+- `AllSizes` — таблица всех поддерживаемых размеров
+- `Playground` — интерактив
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-04-18 | Создан документ |