docs(design-system): add foundation specification

docs/features/design-system-foundation/spec.md

@@ -0,0 +1,168 @@
+# Design System Foundation
+
+## Статус
+
+Draft — ожидает ревью пользователя.
+
+## Цель
+
+Создать внутреннюю дизайн-систему MoexVibe поверх MUI, которая задаёт единый визуальный язык,
+контролируемый набор UI-компонентов и правила их применения. Первая версия должна обслуживать web-
+приложение MoexVibe и сохранять нейтральную к платформе модель токенов для будущих адаптеров,
+включая Android.
+
+## Принципы
+
+- MUI является компонентным и accessibility-движком, но не определяет визуальную идентичность
+  MoexVibe.
+- Визуальное направление: спокойный нейтральный финансовый интерфейс со сбалансированной плотностью.
+- Текущие стили приложения не являются источником дизайн-решений. Их миграция выполняется после
+  foundation отдельными фичами.
+- Дизайн-система не содержит бизнес-логику, API-клиенты, маршрутизацию и доменные компоненты.
+- Docusaurus остаётся единственной опубликованной человекочитаемой документацией проекта.
+
+## Артефакты
+
+### Workspace-пакет
+
+В monorepo должен появиться внутренний пакет `@moex-vibe/design-system` со следующими границами:
+
+- platform-neutral токены без зависимостей от React и MUI;
+- MUI-адаптер, создающий тему и CSS variables из токенов;
+- Core UI и повторяемые product patterns;
+- стабильные subpath exports для токенов, темы и компонентов.
+
+Продуктовый frontend использует компоненты дизайн-системы. Прямые импорты MUI разрешены только для
+компоновки (`Box`, `Stack`, `Grid` и системные layout utilities). Интерактивные и визуально значимые
+компоненты должны поступать из `@moex-vibe/design-system`.
+
+### Storybook
+
+Storybook является локальным и CI-стендом дизайн-системы. Он показывает варианты, состояния,
+адаптивное поведение и accessibility-контракты компонентов, но не считается опубликованной
+документацией для пользователей проекта.
+
+### Docusaurus
+
+В `apps/docs` должен появиться раздел «Дизайн-система» со страницами:
+
+- обзор и принципы;
+- foundations: цвет, типографика, spacing, размеры, радиусы, elevation и motion;
+- модель токенов и правила их изменения;
+- каталог компонентов и product patterns;
+- accessibility;
+- contribution и governance.
+
+Каждая карточка компонента описывает: назначение и запреты, anatomy, разрешённые варианты, состояния,
+keyboard behavior, accessibility, content rules, responsive behavior, корректные примеры и
+антипаттерны.
+
+## Модель токенов
+
+Source of truth первой версии — типизированные TypeScript-объекты. Их схема и имена не должны
+зависеть от MUI, React или CSS. Формат должен оставаться JSON-совместимым, чтобы позднее добавить
+экспорт в DTCG/Android resources без изменения семантических имён.
+
+Токены состоят из трёх уровней с однонаправленными зависимостями:
+
+1. **Primitive/reference** — сырые палитры, шкалы spacing и размеров, типографика, радиусы, тени и
+   motion. Только на этом уровне допустимы абсолютные визуальные значения.
+2. **Semantic/system** — роли: canvas, surface, text, border, action, feedback и финансовая семантика
+   positive/negative/neutral. Будущая тёмная тема переопределяет этот уровень, не меняя компоненты.
+3. **Component** — устойчивые решения конкретных компонентов и вариантов. Они ссылаются на semantic
+   tokens и создаются только для повторяемых или тематизируемых решений, а не для каждого CSS-
+   свойства MUI.
+
+Приложение не должно использовать primitive tokens или произвольные визуальные значения напрямую.
+Цвет не может быть единственным способом сообщить финансовое состояние.
+
+## Тема и визуальные основы
+
+- Первая версия включает только светлую тему. API темы должен допускать добавление новых color schemes
+  без изменения API компонентов.
+- MUI theme использует CSS variables и получает palette, typography, spacing, shape, elevation, motion,
+  defaults, variants и style overrides из токенов.
+- Основная плотность интерфейса — сбалансированная. Компактный вариант допускается как явный вариант
+  data-heavy компонентов, но не как глобальный режим v1.
+- Все состояния focus-visible должны быть заметны; компоненты поддерживают keyboard navigation и
+  `prefers-reduced-motion` там, где используется анимация.
+- Целевой уровень доступности — WCAG 2.2 AA для применимых web-компонентов.
+
+## Компонентная модель
+
+### Core UI v1
+
+- Typography: `Text`, `Heading`, `Link`.
+- Actions: `Button`, `IconButton`.
+- Inputs: `TextField`, `Select`, `Checkbox`.
+- Surfaces and labels: `Surface`, `Card`, `Chip`, `Badge`.
+- Feedback: `Alert`, `Dialog`, `Skeleton`, `Progress`.
+
+Core UI ограничивает разрешённые variants и состояния MUI, сохраняет доступность и не содержит
+доменной логики.
+
+### Product patterns v1
+
+- Data display: `DataTable`, `Metric`, `Money`, `PriceChange`.
+- Forms and filtering: `FormField`, `FilterBar`.
+- Page states: `EmptyState`, `ErrorState`, `LoadingState`.
+
+Product pattern попадает в пакет, если он не знает бизнес-домен и имеет минимум два подтверждённых
+места использования. Исключение — базовые интерактивные Core UI primitives, необходимые для
+целостного API.
+
+Доменные компоненты, включая broker-, portfolio- и screener-specific композиции, остаются в
+соответствующих FSD-слоях frontend.
+
+## Governance
+
+- Изменение значения primitive token не должно молча менять смысл semantic token.
+- Новый token требует описания роли и проверки существующих эквивалентов.
+- Новый variant или компонент требует documented use case; API «на всякий случай» не добавляется.
+- Breaking changes внутреннего пакета фиксируются в changelog и миграционной заметке, даже пока пакет
+  не публикуется во внешний npm registry.
+- Архитектура пакета и граница прямого использования MUI фиксируются отдельным ADR.
+
+## Проверки качества
+
+- Unit-тесты проверяют token contracts, уникальность имён, допустимые ссылки и отсутствие циклов.
+- Type tests проверяют публичные exports и разрешённые component variants.
+- Interaction tests проверяют keyboard и пользовательские состояния интерактивных компонентов.
+- Storybook содержит stories для default, hover/focus reference, disabled, loading, error и responsive
+  состояний, когда они применимы.
+- Автоматические accessibility-проверки выполняются для stories и не допускают серьёзных нарушений.
+- Visual regression покрывает репрезентативные состояния Core UI и product patterns.
+- CI собирает workspace-пакет, Storybook, frontend и Docusaurus; затронутые lint и tests проходят.
+
+## Вне scope
+
+- Тёмная тема и UI-переключатель темы.
+- Android-адаптер, DTCG/JSON export и синхронизация с Figma.
+- Публикация пакета во внешний npm registry.
+- Backend-driven UI.
+- Массовая миграция существующих страниц и удаление legacy CSS.
+- Редизайн доменных экранов, графиков и визуализаций данных.
+
+## Последовательность внедрения
+
+1. Эта фича создаёт Design System Foundation и не переписывает продуктовые экраны.
+2. Отдельная фича мигрирует один репрезентативный pilot-экран и возвращает подтверждённые изменения в
+   tokens/component API.
+3. Остальные области мигрируются отдельными вертикальными срезами; legacy styles удаляются только
+   после миграции всех их потребителей.
+
+## Acceptance Criteria
+
+- [ ] `@moex-vibe/design-system` подключён как внутренний workspace-пакет с документированными public
+      exports.
+- [ ] Реализованы три уровня platform-neutral TypeScript tokens и автоматические проверки их
+      контрактов.
+- [ ] Light MUI theme полностью строится из токенов и предоставляет CSS variables.
+- [ ] Реализован и задокументирован каталог Core UI v1 и product patterns v1.
+- [ ] Прямое использование MUI ограничено documented allowlist для layout utilities.
+- [ ] Storybook локально запускается, собирается в CI и содержит обязательные состояния компонентов.
+- [ ] Accessibility и visual regression checks проходят для согласованного набора stories.
+- [ ] В Docusaurus опубликован полный раздел дизайн-системы и правила выбора компонентов.
+- [ ] Создан ADR о границах пакета, MUI-адаптере и будущих platform adapters.
+- [ ] Frontend, docs и design-system package проходят build, lint и tests.
+- [ ] Существующие продуктовые страницы визуально не мигрированы в рамках этой фичи.