From bd27bba66d5b419008ce4afe02a87fd2d8a7f1c3 Mon Sep 17 00:00:00 2001
From: Sergey Krylov <ksv741@mail.ru>
Date: Sun, 21 Jun 2026 18:00:39 +0300
Subject: [PATCH] docs(sdd): add broker account sections DS migration
 spec/plan/tasks

---
 .../plan.md                                   | 144 ++++++++++++++++++
 .../spec.md                                   |  69 +++++++++
 .../tasks.md                                  | 100 ++++++++++++
 3 files changed, 313 insertions(+)
 create mode 100644 docs/features/broker-account-sections-ds-migration/plan.md
 create mode 100644 docs/features/broker-account-sections-ds-migration/spec.md
 create mode 100644 docs/features/broker-account-sections-ds-migration/tasks.md

diff --git a/docs/features/broker-account-sections-ds-migration/plan.md b/docs/features/broker-account-sections-ds-migration/plan.md
new file mode 100644
index 0000000..dd016b7
--- /dev/null
+++ b/docs/features/broker-account-sections-ds-migration/plan.md
@@ -0,0 +1,144 @@
+# Дизайн-системный рефакторинг брокерских страниц — Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
+> (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use
+> checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Удалить legacy-стили из страниц и компонентов брокерского раздела: CSS-классы,
+`inline styles`, `SkeletonBlock`, `TableSkeleton` → перевести на `@moex-vibe/design-system`.
+
+**Architecture:** Бизнес-логика, контракты и маршрутизация меняться не будут.  
+Градиенты героических секций, которые не имеют DS-эквивалента, сохраняются как `sx`-инлайн-стили.  
+SVG-диаграмма (`BrokerAllocationChart`) сохраняется как есть, меняются только обёртки.
+
+**Tech Stack:** React 18, MUI 6.5, `@moex-vibe/design-system` 0.1.0, CSS custom properties.
+
+**Связанные документы:**
+
+- Epic: `docs/epics/BrokerPortfolio.md`
+- Функциональная базовая фича: `docs/features/broker-account-sections/spec.md`
+- Research: `docs/research/2026-06-18-broker-account-sections.md`
+
+---
+
+## Task 1: BrokerAccountLayout
+
+Заменить layout shell на DS.
+
+- `div.broker-account` → `<Box component="div">`
+- `header.broker-account__header` → `<Box>` flex
+- `h1` → `<Heading level={1}>`
+- `nav.broker-account__navigation` → `<Box component="nav">`
+- `NavLink` классы → при оставлении `className` callback (уникальный prefix для active state), но в первую очередь сменить на `Box` + `<Button>` или DS Tabs если доступен (DS Tabs/doc check)
+- `div.broker-account__workspace` → `<Box>` grid (desktop sidebar + mobile row)
+- `div.broker-account__content` → `<Box>` c overflow-auto
+- Удалить CSS для `.broker-account__header`, `.broker-account__workspace`, `.broker-account__navigation`, `.broker-account__link`, `.broker-account__content` в `styles.css`
+
+## Task 2: BrokerAccountOverviewPage, BrokerSummary, BrokerAssetCards
+
+Перевести три связанных компонента overview на DS.
+
+- `div.broker-overview` → `<Box component="div">`
+- `section.broker-overview__summary` → `<Box>` grid
+- `div.broker-overview__card` + inline-спаны → `<Box>` (card container) + `<Text>`
+- `<span className="broker-overview__label">` → `<Text variant="label" tone="secondary">`
+- `<strong>` значения → `<Text sx={{ fontWeight: 700 }}>`
+- `ul.broker-overview__cash` → `<Box component="ul">` + `<Box component="li">`
+- `section.broker-overview__assets` → `<Box>` grid
+- `Link.broker-overview__asset-link` → `<Link>` + `<Box>` для layout карточки
+- `<strong className="broker-overview__asset-title">` → `<Text sx={{ fontWeight: 700 }}>`
+- Спаны значений/процентов → `<Box component="span">` + `<Text>`
+- Оставить hero-gradient (`broker-overview__hero`-style) на caretaker'е (см. Out of scope)
+
+## Task 3: BrokerOverviewSkeleton
+
+Заменить старые skeleton на DS-component.
+
+- Импорт `SkeletonBlock` → DS `Skeleton`
+- `div.broker-overview__card` → `<Box>` для контейнера skeleton-элементов
+- `SkeletonBlock height={...} width={...}` → `<Skeleton height={...} width={...} shape="text">`
+- `SkeletonBlock borderRadius={80}` → `<Skeleton height={160} width={160} shape="circular">`
+
+## Task 4: BrokerAllocationChart (wrap only)
+
+Оставить SVG без изменений, мигрировать только обёртки.
+
+- `figure.broker-allocation` → `<Box component="figure">`
+- `figcaption` → `<Box component="figcaption">`
+- `<p>` в пустом состоянии → `<Text tone="muted">`
+- `<ul>` / `<li>` легенды → `<Box component="ul">` + `<Box component="li">`
+- `span.broker-allocation__swatch` → `<Box}` с inline-цветом в `sx`
+- Спаны текста легенды → `<Text>` или `<Box component="span">` с кастомным `fontSize`
+- `ul.broker-allocation__negative` → `<Box component="ul">`
+- Удалить CSS для `.broker-allocation*` в `styles.css` (кроме SVG-правил, которые оставить нетронутыми или перенести в inline)
+
+## Task 5: BrokerPositionTable, PositionTicker
+
+Миграция таблицы позиций.
+
+- Вспомогательные типы для `headerStyle`, `cellStyle`, `pagButtonStyle` → MUI `sx` через `<Box>`, `<Button>`
+- Импорт `SkeletonBlock` в компоненте → удалить, использовать `Skeleton` через `<TableSkeleton>` (см. Task 6)
+- `h2` inline-стили → `<Heading level={2}>` с кастомной `sx` для размера/масштаба
+- Ошибки/пустые `<p>` → `<Text>` через Box с inline-цветом
+- `PositionTicker`: `<Link style={{ fontWeight: 700 }}>` → `<Link>` с `<Text sx={{ fontWeight: 700 }}>` внутри
+- `table` → `<table component="table">` или оставить нативным table, но стилизовать через `sx`
+- Сохранить `loading-spinner` класс в `styles.css` (глобальный):
+  - `TableSkeleton` → `<Skeleton>` after DS migration
+- Keep `table-container` as minimal CSS or remove; convert `loading-overlay` to Box.
+
+## Task 6: TableSkeleton
+
+Заменить импорт `SkeletonBlock` на DS `Skeleton`.
+
+- Убрать импорт `SkeletonBlock`, заменить на `Skeleton` из `@moex-vibe/design-system`.
+- `SkeletonBlock height={12} width={col.width}` → `<Skeleton height={12} width={col.width} shape="text"/>`.
+
+## Task 7: BrokerOperationsTable
+
+Миграция таблицы операций.
+
+- Вспомогательные стили (`tableStyle`, `thStyle`, `tdStyle`, `pagButtonStyle`) → inline-`sx` или `<Box>`
+- Оставить `<select>` нативный, но обёрнуть в `<Box component="label">`
+- `h2 inline` → `<Heading level={2}>` с `sx={{ fontSize: 20 }}`
+- `<span role="status">` с `loading-spinner` → `<Skeleton shape="circular" width={14} height={14} />` (если DS поддерживает) или оставить `<span className="loading-spinner">` временно; DS `Skeleton` не имеет circular-only без width/height — оставить на этой итерации, можно оставить loading-spinner, так как это глобальный анимационный класс, а не DS.
+- Пустые состояния / alert-тексты → `<Text tone="muted">` / `<Text tone="negative">`
+- Пагинация `<button>` → `<Button variant="secondary">`
+- `aria-label` — сохранить.
+
+## Task 8: BrokerPositionsPage, BrokerOperationsPage
+
+Миграция "обёрточных" страниц-секций.
+
+- `section` → `<Box component="section">`
+- `h2 inline` → `<Heading level={2}>` с `sx={{ fontSize: 20 }}`
+- `p role="alert"` → `<Text tone="negative" component="p">` (или `<Box component="p">`)
+- `p.empty` → `<Text tone="muted">`
+- `div.broker-operations__toolbar` → `<Box>` с flex
+- `label > span + select` → `<Box component="label">` + `<Text>` + `<select>`
+
+## Task 9: SkeletonBlock удаление
+
+После замены всех потребителей:
+
+1. Удалить `apps/frontend/src/shared/ui/SkeletonBlock.tsx`.
+2. Удалить экспорт из `apps/frontend/src/shared/ui/index.ts`.
+3. Убедиться, что `import { SkeletonBlock }` не осталось нигде.
+
+## Task 10: Очистка `styles.css`
+
+- Удалить все selector'ы из блока `broker-account__*`, `broker-overview__*`, `broker-allocation__*` (SVG стили оставить), `broker-operations__toolbar*`.
+- Оставить косметические классы, которые ещё не мигрированы (если таковые возникнут).
+- Оставить `.loading-spinner` (глобальный анимационный класс, применяется через `className` где-то еще).
+- Оставить `:root` CSS variables — они DS взаиморасчётные токены.
+
+## Task 11: Тестирование и сборка
+
+- [ ] `npm run test:frontend` — все тесты PASS.
+- [ ] `npm run lint -w apps/frontend` — без ошибок.
+- [ ] `npm run build:frontend` — без TypeScript/Vite ошибок.
+- [ ] Проверить, что нет остатков `SkeletonBlock` импортов в кодовой базе: `grep -r "SkeletonBlock" apps/frontend/src`.
+- [ ] Проверить, что нет остатков `broker-account__*`, `broker-overview__*`, `broker-allocation__*`, `broker-operations__toolbar` в TSX: `grep -rE "broker-(account|overview|allocation|operations)" apps/frontend/src --include='*.{ts,tsx}'`.
+
+## Task 12: Вердикт и записка
+
+- [ ] Обновить `docs/features/broker-account-sections-ds-migration/tasks.md` — отметить все выполненные пункты.
diff --git a/docs/features/broker-account-sections-ds-migration/spec.md b/docs/features/broker-account-sections-ds-migration/spec.md
new file mode 100644
index 0000000..f9981ea
--- /dev/null
+++ b/docs/features/broker-account-sections-ds-migration/spec.md
@@ -0,0 +1,69 @@
+# Дизайн-системный рефакторинг страниц брокерского счёта
+
+Дата: 2026-06-21
+Статус: Draft
+
+## Контекст
+
+Epic `Брокерский портфель` уже покрыт функциональной фичей `broker-account-sections` (реализовано 2026-06-18). Текущая цель — убрать legacy-стили (CSS-классы, inline-стили, `SkeletonBlock`, `loading-spinner`) из страниц и компонентов, относящихся к одному выбранному брокерскому счёту, и перевести их на `@moex-vibe/design-system`.
+
+Страницы в области изменения:
+
+- `BrokerAccountLayout` — навигация и заголовок счёта;
+- `BrokerAccountOverviewPage` — карточки сводки, диаграмма, последние операции;
+- `BrokerSummary` — текстовые показатели портфеля и денежных остатков;
+- `BrokerAssetCards` — карточки акций и облигаций;
+- `BrokerOverviewSkeleton` — loading-состояние overview;
+- `BrokerAllocationChart` — SVG-диаграмма (диаграмма остаётся SVG, меняются обёртки);
+- `BrokerPositionTable` — таблица позиций с пагинацией;
+- `BrokerOperationsTable` — таблица операций с пагинацией;
+- `PositionTicker` — кликабельный тикер в таблице позиций;
+- `BrokerPositionsPage` — страница акций / облигаций;
+- `BrokerOperationsPage` — страница истории операций с фильтром.
+
+## Связанные фичи
+
+- Epic: `docs/epics/BrokerPortfolio.md`
+- Функциональная базовая фича: `docs/features/broker-account-sections/spec.md`
+- DS-пакет: `packages/design-system/`
+
+## Цель
+
+Удалить все CSS-классы (кроме героических градиентов, где нет DS-эквивалента) и `SkeletonBlock` из страниц и компонентов, относящихся к одному брокерскому счёту. Перевести layout, typography, skeleton, метрики, алерты, кнопки, пустые состояния на `@moex-vibe/design-system`. Оставить нетронутыми бизнес-логику, контракты и схему маршрутизации.
+
+## Out of scope
+
+- Изменение бизнес-логики, контрактов API, entity-слоя;
+- Изменение маршрутизации;
+- Изменение SVG-диаграммы;
+- Рефакторинг broker-accounts-page (список счетов) — отдельная фича;
+- Изменение CSS-переменных `:root` и их использования за пределами страниц брокера;
+- Добавление новых тестов (существующие тесты сохраняются, если их контракт не меняется).
+
+## Принципы миграции
+
+- `SkeletonBlock` → DS `Skeleton` (все потребители → удаление `SkeletonBlock` из `shared/ui`);
+- `<h1>`/`<h2>` → `<Heading level={1|2}>`;
+- `<p label>`, `<span>` → `<Text variant="label" tone="secondary">`;
+- `<p>` статические тексты → `<Text variant="body">` или `<Box component="span">` с `sx` (если нужен кастомный размер/цвет);
+- `<strong>` значения → `<Text variant="body" sx={{ fontWeight: 700 }}>`;
+- Inline `<p role="alert">` → `<Text tone="negative">`;
+- Стандартный `<section>` → `<Box component="section">`;
+- Hero-gradient `broker-overview` → `<Box>` с кастомным `sx` (градиент остаётся как inline-стиль);
+- `div.broker-operations__toolbar` → `<Box>` с flex-сеткой;
+- `<select>` элемент — оставить как нативный `<select>`, обёрнуть в `<Box>`.
+
+## Acceptance Criteria
+
+- [ ] `BrokerAccountLayout` не содержит CSS-классов из `styles.css`; используется `<Heading>`, `<Text>`, `<Box>`.
+- [ ] `BrokerAccountOverviewPage` и содержащиеся в нём `BrokerSummary`, `BrokerAssetCards` переведены на DS-компоненты.
+- [ ] `BrokerOverviewSkeleton` использует DS `<Skeleton>`.
+- [ ] `BrokerAllocationChart` обёртки (`<figure>`, `<figcaption>`) переведены на `<Box>`; текст легенды — на `<Text>`.
+- [ ] `BrokerPositionTable` и `BrokerOperationsTable` используют `<Box>` для layout, `<Heading>` для заголовков, `<Button>` или `<Box>` для пагинации, пустые и loading-состояния — через DS.
+- [ ] `TableSkeleton` переведён на DS `<Skeleton>`.
+- [ ] `SkeletonBlock` удалён после замены всех потребителей.
+- [ ] `BrokerPositionsPage` и `BrokerOperationsPage` переведены на `<Box>`, `<Heading>`, `<Text>`.
+- [ ] `PositionTicker` — `<Link>` с `<Text>` (или оставляет `fontWeight: 700` если без `sx`).
+- [ ] ESLint allowlist не нарушен (`no-restricted-imports` разрешает `Box`, `Stack`, `Grid` из `@mui/material` barrel).
+- [ ] `npm run test:frontend && npm run lint -w apps/frontend && npm run build:frontend` проходят.
+- [ ] CSS-классы, оставшиеся без потребителей, удалены из `styles.css` (но сохраняются градиенты hero-секций).
diff --git a/docs/features/broker-account-sections-ds-migration/tasks.md b/docs/features/broker-account-sections-ds-migration/tasks.md
new file mode 100644
index 0000000..11aad48
--- /dev/null
+++ b/docs/features/broker-account-sections-ds-migration/tasks.md
@@ -0,0 +1,100 @@
+# Дизайн-системный рефакторинг брокерских страниц — Tasks
+
+Дата: 2026-06-21
+Связанные документы:
+
+- [Spec](spec.md)
+- [Plan](plan.md)
+
+## Task 1: BrokerAccountLayout
+
+- [ ] Заменить `div.broker-account` на `<Box component="div">`
+- [ ] Перевести `header` + `h1` на `<Box>` + `<Heading level={1}>`
+- [ ] Перевести `nav` на `<Box component="nav">` + `<NavLink>` (оставить className callback)
+- [ ] Перевести `div.broker-account__workspace` на grid `<Box>`
+- [ ] Перевести `div.broker-account__content` на `<Box>`
+- [ ] Удалить соответствующие CSS-selectors из `styles.css`
+
+## Task 2: BrokerAccountOverviewPage + BrokerSummary + BrokerAssetCards
+
+- [ ] Перевести `BrokerSummary` на `<Box>` + `<Text>`
+- [ ] Перевести eyebrow/label на `<Text variant="label" tone="secondary">`
+- [ ] Перевести `<strong>` значений на `<Text sx={{ fontWeight: 700 }}>`
+- [ ] Перевести `<ul>` cash на `<Box component="ul">`
+- [ ] Перевести `BrokerAssetCards` на `<Box>` + `<Link>` + `<Text>`
+- [ ] Перевести `BrokerAccountOverviewPage` container на `<Box component="div">`
+- [ ] Оставить hero-gradient без изменений (Out of scope)
+
+## Task 3: BrokerOverviewSkeleton
+
+- [ ] Заменить импорт `SkeletonBlock` на DS `<Skeleton>`
+- [ ] Перевести контейнеры на `<Box>`
+- [ ] Сделать circular skeleton для портфельной карточки
+- [ ] Сделать text skeleton для текстовых placeholder'ей
+
+## Task 4: BrokerAllocationChart (wrap only)
+
+- [ ] Перевести `<figure>` на `<Box component="figure">`
+- [ ] Перевести `<figcaption>` на `<Box component="figcaption">`
+- [ ] Перевести `<p>` пустого состояния на `<Text tone="muted">`
+- [ ] Перевести `<ul>` / `<li>` легенды на `<Box component="ul">` + `<Box component="li">`
+- [ ] Перевести swatch на `<Box>` с inline-цветом в `sx`
+- [ ] Перевести тексты легенды на `<Text>` / `<Box component="span">`
+- [ ] Перевести negative-список на `<Box component="ul">`
+- [ ] Удалить CSS для `.broker-allocation*` (кроме inline SVG) в `styles.css`
+
+## Task 5: BrokerPositionTable + PositionTicker
+
+- [ ] Перевести вспомогательные стили на `<Box sx={{...}}>`
+- [ ] Перевести `<h2>` на `<Heading level={2}>` с кастомной `sx`
+- [ ] Перевести alert-тексты на `<Text tone="negative">`
+- [ ] Перевести пагинационные `<button>` на `<Button variant="secondary">`
+- [ ] Перевести `loading-overlay` на `<Box>`
+- [ ] Перевести `PositionTicker` ссылки на `<Link>` + `<Text sx={{ fontWeight: 700 }}>`
+- [ ] Сохранить `loading-spinner` (глобальный класс, пока без замены)
+
+## Task 6: TableSkeleton (DS Skeleton)
+
+- [ ] Убрать импорт `SkeletonBlock`
+- [ ] Заменить на `<Skeleton height={12} width={col.width} shape="text" />`
+- [ ] Сделать прогон тестов, убедиться что нет предупреждений
+
+## Task 7: BrokerOperationsTable
+
+- [ ] Перевести вспомогательные стили на `<Box sx={{...}}>`
+- [ ] Перевести `<h2>` на `<Heading level={2}>`
+- [ ] Перевести `headerAction` container на `<Box>`
+- [ ] Перевести пагинационные `<button>` на `<Button variant="secondary">`
+- [ ] Перевести alert-тексты на `<Text tone="negative">`
+- [ ] Перевести empty-тексты на `<Text tone="muted">`
+- [ ] Перевести `<label>` + `<select>` на `<Box component="label">` + `<select>`
+- [ ] Оставить `loading-spinner` для overlay (глобальный класс)
+
+## Task 8: BrokerPositionsPage + BrokerOperationsPage
+
+- [ ] Перевести `BrokerPositionsPage` на `<Box component="section">` + `<Heading>` + `<Text>`
+- [ ] Перевести `BrokerOperationsPage` на `<Box>` + `<Heading>` + `<Box component="label">` + `<select>`
+- [ ] Убедиться, что `role="alert"` сохраняется через `<Text tone="negative">`
+
+## Task 9: SkeletonBlock удаление
+
+- [ ] Удалить `apps/frontend/src/shared/ui/SkeletonBlock.tsx`
+- [ ] Удалить экспорт из `apps/frontend/src/shared/ui/index.ts`
+- [ ] Проверить grep по `SkeletonBlock` — 0 совпадений
+
+## Task 10: Очистка `styles.css`
+
+- [ ] Удалить блоки `.broker-account__*`
+- [ ] Удалить блоки `.broker-overview__*` (кроме SVG-связанных)
+- [ ] Удалить блоки `.broker-allocation__*` (кроме SVG-внутренних, если остались)
+- [ ] Удалить блоки `.broker-operations__toolbar*`
+- [ ] Оставить `.loading-spinner` и `:root` переменные
+
+## Task 11: Финальная проверка
+
+- [ ] `npm run test:frontend`
+- [ ] `npm run lint -w apps/frontend`
+- [ ] `npm run build:frontend`
+- [ ] grep по `broker-(account|overview|allocation)` в TSX — 0 совпадений
+- [ ] grep по `SkeletonBlock` в TSX — 0 совпадений
+- [ ] `npm run format` для форматирования