@atomazing-org/design-system 1.2.8 → 2.0.1

package/dist/{typography-Dq0wCojD.d.mts → typography-B-BeIk0v.d.ts}

@@ -4,11 +4,10 @@ import { ReactNode, CSSProperties } from 'react';
 /**
  * Available options for dark mode configuration.
  * - `system`: Follows the operating system preference.
- * - `auto`: Alias of `system` (no contrast-based detection in current contract).
  * - `light`: Forces light mode.
  * - `dark`: Forces dark mode.
  */
-type DarkModeOptions = "system" | "auto" | "light" | "dark";
+type DarkModeOptions = "system" | "light" | "dark";
 interface OptionItem {
     label: string;
     value: DarkModeOptions;
@@ -24,10 +23,10 @@ type NamedThemeOptions = ThemeOptions & {
  */
 interface AppSettings {
     /**
-     * The selected theme name from the available themes list.
+     * The selected preset id from the available themes list.
      * Invalid or missing values are normalized to the first available theme.
      */
-    theme: string;
+    themeId: string;
     /**
      * Controls how dark mode is applied in the app.
      */
@@ -118,4 +117,4 @@ declare module "@mui/material/Typography" {
     }
 }
 
-export type { AppSettings as A, CustomTypographyVariants as C, DarkModeOptions as D, NamedThemeOptions as N, OptionItem as O, ThemeContextProps as T, ThemePreset as a, ThemeModeBackground as b, NormalizedPreset as c, DarkModeSetting as d, ThemeId as e, ThemeScheme as f };
+export type { AppSettings as A, CustomTypographyVariants as C, DarkModeOptions as D, NamedThemeOptions as N, OptionItem as O, ThemeContextProps as T, ThemePreset as a, ThemeModeBackground as b, NormalizedPreset as c, ThemeId as d, ThemeScheme as e, DarkModeSetting as f };

package/migrations/README.UPDATE.md

@@ -0,0 +1,29 @@
+# Что здесь должно быть (исправленный формат)
+
+Вы правы: для этой задачи в `migrations/` нужны не исполняемые `mjs`-скрипты, а **инструкции для ИИ/агента**, который выполняет миграцию по runbook'ам.
+
+## Source of truth
+
+- `migrations/skills/design-system-migration-agent/SKILL.md` — инструкция для ИИ (главная точка входа)
+- `migrations/docs/migrations/design-system/*` — маршруты миграции, runbook'и, shared criteria
+
+## Как использовать (через ИИ)
+
+1) Дайте агенту задачу на миграцию проекта к `@atomazing-org/design-system`.
+2) Укажите использовать skill:
+   - `migrations/skills/design-system-migration-agent/SKILL.md`
+3) Агент сам:
+   - выберет route (`greenfield` / `adopt-existing` / `mui4-to-latest`);
+   - прочитает нужный `RUNBOOK.md` и `migration.spec.json`;
+   - выполнит шаги вручную (без обязательной зависимости от `migrations/scripts/*`);
+   - прогонит проверки (`lint/test/build`) и acceptance criteria.
+
+## Что настроить перед запуском
+
+- Заменить `<SET_VERSION>` в route spec (или сообщить версию агенту явно).
+- Для token migration подготовить mapping (`token-map.csv`) под конкретный проект.
+- Для route `adopt-existing` определить список legacy token imports/identifiers (для search/gates).
+
+## Про `migrations/scripts/*`
+
+`migrations/scripts/*` сейчас можно считать **необязательной/избыточной реализацией** (референс для автоматизации). Для вашего исходного запроса source of truth — именно skill + docs.

package/migrations/docs/migrations/design-system/README.md

@@ -0,0 +1,69 @@
+# design-system v2 migration routes (MUI v7 target)
+
+This folder contains the migration router, runbooks, and route specs used to adopt
+`@atomazing-org/design-system` v2.
+
+Target baseline:
+- design-system v2 contract
+- MUI v7
+- React 18/19
+
+Repo route model (canonical):
+- `mui4-to-latest` (backlog alias: `mui4-to-v7`)
+- `greenfield`
+- `adopt-existing` (covers backlog `mui5-6-to-v7` unless a dedicated split route is added later)
+
+## Route selection (decision tree)
+
+1. If `package.json` contains `@material-ui/*` dependencies:
+   - use `routes/mui4-to-latest/`
+2. Else if the app is new / no existing theme-token migration is needed:
+   - use `routes/greenfield/`
+3. Else:
+   - use `routes/adopt-existing/`
+
+## Agent workflow (scriptless default)
+
+Use the AI skill/instructions as the primary execution method:
+
+- `migrations/skills/design-system-migration-agent/SKILL.md`
+
+Default flow:
+
+1. Detect route manually (inspect `package.json`, imports, and current theme setup).
+2. Read the selected route spec + runbook:
+   - `routes/<routeId>/migration.spec.json`
+   - `routes/<routeId>/RUNBOOK.md`
+3. Execute steps from the spec/runbook in the target repo.
+4. Run quality gates / checks (scripted or equivalent manual checks):
+
+```bash
+npm test
+npm run build
+```
+
+Recommended manual gate equivalents:
+- search for `@material-ui/*` in source and `package.json`
+- search for legacy token imports/identifiers defined for the route/project
+
+## Route index
+
+- `mui4-to-latest`: `./routes/mui4-to-latest/RUNBOOK.md`
+- `greenfield`: `./routes/greenfield/RUNBOOK.md`
+- `adopt-existing`: `./routes/adopt-existing/RUNBOOK.md` (also used for backlog Phase 14 specialization)
+
+## Shared gates
+
+Common migration gates are documented in:
+
+- `./shared/gates.md`
+- `./shared/acceptance.md`
+
+Routes should reference the shared gates docs instead of duplicating the full gate list.
+
+## Notes
+
+- Route phases in this repo backlog may be completed in `docs/spec-first` mode before real app dry-runs.
+- A dedicated `mui5-6-to-v7` route split is a post-v2 option, not a blocker for the current repo route model.
+
+

package/migrations/docs/migrations/design-system/routes/adopt-existing/RUNBOOK.md

@@ -0,0 +1,34 @@
+# Маршрут: Рефакторинг на актуальном MUI + применение дизайн-системы (adopt-existing)
+
+## Когда использовать
+
+- Проект уже использует `@mui/material` (v5/v6/v7).
+- Нужна унификация темы/типографики/палитры через `@atomazing-org/design-system`.
+- Основная работа — убрать хардкоды токенов и перейти на `theme.*`.
+
+## Результат
+
+- `ThemeProviderWrapper` — единственный источник настроек темы.
+- Токены из проекта либо удалены, либо превращены в thin-adapter вокруг `theme`.
+
+## Шаги
+
+1) Preflight: тесты и сборка зелёные.
+2) Установить `@atomazing-org/design-system` и peer deps (если не установлены).
+3) Подключить `ThemeProviderWrapper` на корне приложения.
+4) Сделать инвентаризацию токенов:
+   - где лежат цвета/типографика/spacing/радиусы;
+   - какие алиасы используются чаще всего.
+5) Заполнить mapping (CSV/JSON) и применить безопасные замены.
+6) Прогнать gates + тесты + сборку.
+
+## Стратегия переносов (рекомендуется)
+
+- Сначала цвета поверхностей и текстов (фон/текст/бордер/brand).
+- Затем типографика (перевод на variants или `theme.typography`).
+- Затем компонентные размеры/spacing.
+## Shared gates (repo)
+
+Use common gate definitions from:
+- `../../shared/gates.md`
+- `../../shared/acceptance.md`

package/migrations/docs/migrations/design-system/routes/adopt-existing/migration.spec.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../schema/migration.spec.schema.json",
+  "id": "adopt-existing",
+  "title": "Adopt @atomazing-org/design-system in an existing MUI project",
+  "detect": {
+    "packageJson": {
+      "anyDependencies": ["@mui/material"]
+    }
+  },
+  "entryConditions": ["проект уже на @mui/material"],
+  "exitConditions": [
+    "ThemeProviderWrapper подключён",
+    "нет запрещённых токенов/импортов",
+    "tests/build зелёные"
+  ],
+  "steps": [
+    {
+      "name": "Preflight",
+      "run": ["npm ci", "npm test", "npm run build"]
+    },
+    {
+      "name": "Add design-system deps",
+      "run": [
+        "node migrations/scripts/migrations/design-system/actions/update-package-json.mjs --add @atomazing-org/design-system:<SET_VERSION>"
+      ]
+    },
+    {
+      "name": "Install deps",
+      "run": ["npm install"]
+    },
+    {
+      "name": "Manual integration",
+      "manualReview": [
+        "Подключите ThemeProviderWrapper в корне приложения.",
+        "Удалите/упростите существующий ThemeProvider, чтобы не было конфликтов."
+      ]
+    },
+    {
+      "name": "Token cleanup",
+      "manualReview": [
+        "Заполните migrations/scripts/migrations/design-system/shared/token-gate.config.json под ваш проект.",
+        "Подготовьте CSV mapping и примените apply-replacements-from-csv.mjs."
+      ]
+    },
+    {
+      "name": "Quality gates",
+      "run": [
+        "node migrations/scripts/migrations/design-system/gates/no-hardcoded-tokens.mjs --root src --config migrations/scripts/migrations/design-system/shared/token-gate.config.json",
+        "npm test",
+        "npm run build"
+      ]
+    }
+  ]
+}

package/migrations/docs/migrations/design-system/routes/greenfield/RUNBOOK.md

@@ -0,0 +1,29 @@
+# Маршрут: Установка с нуля (greenfield)
+
+## Когда использовать
+
+- Новый проект.
+- Нет унаследованных token-файлов и старой темы.
+
+## Результат
+
+- `ThemeProviderWrapper` подключён на корне.
+- (Опционально) настроены список динамических тем и UI-переключатели.
+
+## Шаги
+
+1) Установить зависимости.
+2) Обернуть приложение в `ThemeProviderWrapper`.
+3) (Опционально) передать список тем `themes` и/или `colorPaletteOverride`.
+4) (Опционально) добавить UI для переключения темы и dark mode.
+5) Прогнать тесты и сборку.
+
+## SSR / Next.js
+
+Если проект на Next.js:
+- провайдер разместить в клиентской границе (`"use client"`).
+## Shared gates (repo)
+
+Use common gate definitions from:
+- `../../shared/gates.md`
+- `../../shared/acceptance.md`

package/migrations/docs/migrations/design-system/routes/greenfield/migration.spec.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "../../schema/migration.spec.schema.json",
+  "id": "greenfield",
+  "title": "Greenfield install of @atomazing-org/design-system",
+  "detect": {
+    "packageJson": {
+      "allDependencies": []
+    }
+  },
+  "entryConditions": ["проект инициализирован (package.json существует)"],
+  "exitConditions": ["ThemeProviderWrapper подключён", "tests/build зелёные"],
+  "steps": [
+    {
+      "name": "Add deps",
+      "run": [
+        "node migrations/scripts/migrations/design-system/actions/update-package-json.mjs --add @atomazing-org/design-system:<SET_VERSION> --add @mui/material:^7 --add @mui/icons-material:^7 --add @emotion/react:^11 --add @emotion/styled:^11"
+      ]
+    },
+    {
+      "name": "Install deps",
+      "run": ["npm install"]
+    },
+    {
+      "name": "Manual integration",
+      "manualReview": [
+        "Подключите ThemeProviderWrapper в корне приложения.",
+        "Если Next.js — убедитесь, что это client boundary (\"use client\")."
+      ]
+    },
+    {
+      "name": "Quality",
+      "run": ["npm test", "npm run build"]
+    }
+  ],
+  "gates": ["tests", "build"]
+}

package/migrations/docs/migrations/design-system/routes/mui4-to-latest/RUNBOOK.md

@@ -0,0 +1,81 @@
+# Маршрут: MUI v4 → MUI v7 + @atomazing-org/design-system
+
+## Когда использовать
+
+- В проекте есть `@material-ui/*` (Material-UI v4).
+- Есть собственные token-файлы/константы, которые используются напрямую в компонентах.
+
+## Результат
+
+- Проект на `@mui/material` (v7) + Emotion.
+- Корневой провайдер темы: `ThemeProviderWrapper`.
+- Основные токены и типографика берутся из MUI theme.
+
+## Шаги (высокий уровень)
+
+1) Зафиксировать baseline: тесты/сборка зелёные.
+2) Обновить зависимости и перейти с `@material-ui/*` на `@mui/*`.
+3) Запустить официальные codemod'ы для v4 → v5.
+4) Довести проект до актуальной версии MUI (v6 → v7) по гайдам.
+5) Подключить `@atomazing-org/design-system` и заменить корневой ThemeProvider.
+6) Перенести токены: заменить импорты/использования локальных токенов на `theme.palette` и `theme.typography`.
+7) Прогнать gates + тесты + сборку.
+
+## Детальные команды (ориентир)
+
+> Порядок и точные команды могут отличаться в зависимости от пакетного менеджера и инфраструктуры.
+
+### A) Preflight
+
+- Создайте ветку.
+- Выполните:
+
+```bash
+npm ci
+npm test
+npm run build
+```
+
+### B) Upgrade deps до MUI v5 (первый major)
+
+- Удалите `@material-ui/*`.
+- Установите `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`.
+
+### C) Codemod v4 → v5
+
+Запустить preset-safe codemod на исходниках (обычно `src`):
+
+```bash
+npx @mui/codemod@latest v5.0.0/preset-safe src
+```
+
+После codemod:
+- исправить TODO/ошибки TypeScript;
+- пройтись по стилям JSS (`makeStyles/withStyles`) и заменить на совместимые подходы.
+
+### D) Upgrade v5 → v6 → v7
+
+- Выполнить апгрейд до v6 по официальному гайду.
+- Затем апгрейд до v7 по официальному гайду.
+
+### E) Подключение дизайн-системы
+
+- Установить `@atomazing-org/design-system`.
+- Подключить `ThemeProviderWrapper` на корне приложения.
+
+### F) Перенос токенов
+
+1) Соберите список файлов, где импортируются токены.
+2) Заполните `token-map.csv` (пример в этом же каталоге).
+3) Примените текстовые замены через скрипт `apply-replacements-from-csv.mjs` (см. `migration.spec.json`).
+4) Для сложных случаев внесите правки вручную и отметьте это в отчёте.
+
+## Ручной контроль (обязательно)
+
+- Проверить визуально минимум 5–10 ключевых экранов.
+- Проверить состояния компонентов (hover/active/disabled) для ключевых кнопок, инпутов, алертов.
+## Shared gates (repo)
+
+Use common gate definitions from:
+- `../../shared/gates.md`
+- `../../shared/acceptance.md`

package/migrations/docs/migrations/design-system/routes/mui4-to-latest/migration.spec.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "../../schema/migration.spec.schema.json",
+  "id": "mui4-to-latest",
+  "title": "MUI v4 → MUI v7 + adopt @atomazing-org/design-system",
+  "detect": {
+    "packageJson": {
+      "anyDependencies": [
+        "@material-ui/core",
+        "@material-ui/styles",
+        "@material-ui/icons"
+      ]
+    }
+  },
+  "entryConditions": [
+    "package.json содержит @material-ui/*",
+    "тесты/сборка до миграции зелёные"
+  ],
+  "exitConditions": [
+    "в package.json отсутствуют @material-ui/*",
+    "код не импортирует @material-ui/*",
+    "корень приложения использует ThemeProviderWrapper"
+  ],
+  "steps": [
+    {
+      "name": "Preflight",
+      "run": ["npm ci", "npm test", "npm run build"]
+    },
+    {
+      "name": "Update package.json deps (v4 → v5 baseline + design-system)",
+      "run": [
+        "node migrations/scripts/migrations/design-system/actions/update-package-json.mjs --remove @material-ui/core --remove @material-ui/styles --remove @material-ui/icons --add @mui/material:^7 --add @mui/icons-material:^7 --add @emotion/react:^11 --add @emotion/styled:^11 --add @atomazing-org/design-system:<SET_VERSION>"
+      ],
+      "manualReview": [
+        "Проверьте наличие альтернативных зависимостей (mui lab, x-пакеты, date-pickers, data-grid) и обновите их отдельно."
+      ]
+    },
+    {
+      "name": "Install deps",
+      "run": ["npm install"]
+    },
+    {
+      "name": "Run official codemod (v4 → v5)",
+      "run": ["npx @mui/codemod@latest v5.0.0/preset-safe src"],
+      "manualReview": [
+        "Просмотрите TODO и ошибки компиляции после codemod.",
+        "Проверьте стили на JSS (makeStyles/withStyles)."
+      ]
+    },
+    {
+      "name": "Apply token remap (project-specific)",
+      "run": [
+        "node migrations/scripts/migrations/design-system/shared/apply-replacements-from-csv.mjs --csv migrations/docs/migrations/design-system/routes/mui4-to-latest/token-map.csv --root src"
+      ],
+      "manualReview": [
+        "Включите нужные строки в token-map.csv (enabled=true) и проверьте дифф.",
+        "Для сложных замен добавьте отдельные правила или выполните ручные правки."
+      ]
+    },
+    {
+      "name": "Quality gates",
+      "run": [
+        "node migrations/scripts/migrations/design-system/gates/no-legacy-material-ui.mjs --root src",
+        "node migrations/scripts/migrations/design-system/gates/no-hardcoded-tokens.mjs --root src --config migrations/scripts/migrations/design-system/shared/token-gate.config.json",
+        "npm test",
+        "npm run build"
+      ]
+    }
+  ],
+  "gates": ["no-legacy-material-ui", "no-hardcoded-tokens", "tests", "build"]
+}

package/migrations/docs/migrations/design-system/routes/mui4-to-latest/token-map.csv

@@ -0,0 +1,4 @@
+kind,from,to,notes,enabled
+literal,colors.primary,"(t) => t.palette.brand.main","пример: локальный colors.primary → theme.palette.brand.main",false
+literal,colors.accent,"(t) => t.palette.accent.main",,"",false
+regex,"\\bspacing\\((\\d+)\\)","(t) => t.spacing($1)","пример: перенос spacing() на theme.spacing",false

package/migrations/docs/migrations/design-system/schema/migration.spec.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://atomazing.org/schemas/design-system/migration.spec.schema.json",
+  "title": "Design System Migration Spec",
+  "type": "object",
+  "required": ["id", "title", "steps"],
+  "properties": {
+    "id": { "type": "string" },
+    "title": { "type": "string" },
+    "detect": {
+      "type": "object",
+      "properties": {
+        "packageJson": {
+          "type": "object",
+          "properties": {
+            "anyDependencies": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "allDependencies": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": true
+    },
+    "entryConditions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "exitConditions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string" },
+          "run": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "manualReview": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "gates": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "additionalProperties": true
+}

package/migrations/docs/migrations/design-system/shared/FOUNDATION.md

@@ -0,0 +1,39 @@
+# Общий фундамент миграции
+
+## Цель
+
+Привести проект к состоянию, где:
+- корневой провайдер темы — **ThemeProviderWrapper** из `@atomazing-org/design-system`;
+- цвета/типографика/компонентные значения берутся из темы (MUI theme), а не из локальных хардкодов;
+- переключение темы/режима (при необходимости) делается через **useThemeSettings**.
+
+## Минимальная интеграция
+
+В корне приложения оборачиваем UI:
+
+```tsx
+import { ThemeProviderWrapper } from "@atomazing-org/design-system";
+
+export function App() {
+  return (
+    <ThemeProviderWrapper>
+      {/* app */}
+    </ThemeProviderWrapper>
+  );
+}
+```
+
+## Типовые элементы дизайн-системы
+
+- **Dynamic themes**: можно передать массив тем `themes` (name + цвета), чтобы UI мог переключаться между ними.
+- **Dark mode**: чтение/запись режима через `useThemeSettings()`.
+- **Расширенная палитра**: дополнительные цвета (например, `brand`, `neutral`, `accent`, `muted`) доступны в `theme.palette.*` и на ряде компонентов через `color`.
+- **Типографика**: расширенные `Typography` variants (например, семейства `text_*` и `header_*`).
+
+## SSR / Next.js
+
+Если проект SSR:
+- избегайте обращения к `window/document/navigator/localStorage` на уровне модуля;
+- провайдер темы размещайте в клиентской границе (например, в `layout.tsx` с директивой `"use client"`).
+
+

package/migrations/docs/migrations/design-system/shared/acceptance.md

@@ -0,0 +1,27 @@
+# Общие критерии готовности (Acceptance Criteria)
+
+Миграция считается завершённой, когда:
+
+## 1) Зависимости
+- В проекте присутствует `@atomazing-org/design-system`.
+- Для MUI присутствуют совместимые версии `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`.
+
+## 2) Источник истины для темы
+- Корень приложения обёрнут в `ThemeProviderWrapper`.
+- Нет второго конкурентного `ThemeProvider` (если он не нужен как thin-wrapper вокруг DS).
+
+## 3) Отсутствие legacy MUI v4
+- В `package.json` отсутствуют `@material-ui/*`.
+- В коде отсутствуют импорты из `@material-ui/*`.
+
+## 4) Токены
+- Нет прямых импортов/использований устаревших token-файлов (список определяется маршрутом).
+- Основные UI-поверхности (фон/текст/бордеры/основные кнопки) используют `theme.palette`.
+- Основные тексты используют `Typography` variants (или `theme.typography`).
+
+## 5) Качество
+- `npm test` проходит.
+- `npm run build` проходит.
+- Quality gates проходят (через `migrations/scripts/*` или эквивалентные ручные проверки поиска по коду/импортам).
+
+

package/migrations/docs/migrations/design-system/shared/gates.md

@@ -0,0 +1,35 @@
+# Shared migration gates (design-system v2)
+
+Use this gate list as the common baseline for all routes under
+`migrations/docs/migrations/design-system/routes/*`.
+
+## Required commands
+
+Run in the target app repository (adjust package manager as needed):
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+## Required checks
+
+- `ThemeProviderWrapper` is wired at the app root (or an approved thin wrapper around it).
+- No route-blocking dependency conflicts remain after dependency updates.
+- The app reaches the v2 target state (MUI v7 + design-system v2 contract).
+
+## Route-specific checks
+
+- `mui4-to-latest`:
+  - no `@material-ui/*` dependencies remain
+  - no `@material-ui/*` imports remain in app source
+- `adopt-existing` / `mui5-6-to-v7` coverage:
+  - no forbidden hardcoded token imports remain (per route config)
+- `greenfield`:
+  - provider wiring compiles and basic theme switching works (if UI switcher is added)
+
+## Notes
+
+- Token hardcode detection is noisy by nature; keep route configs (`token-gate.config.json`) app-specific.
+- Real app dry-runs can be deferred in this repo backlog flow (`docs/spec-first`) and executed later in app repos / optional closeout.

package/migrations/docs/migrations/design-system/shared/rollback.md

@@ -0,0 +1,13 @@
+# Откат (Rollback)
+
+Рекомендуемый подход:
+
+1) Делать миграцию только в отдельной ветке.
+2) Каждый крупный шаг — отдельный коммит (например: deps → codemod → токены → провайдер → фиксы).
+3) Откат выполнять через `git revert` отдельных коммитов или через сброс ветки.
+
+Если миграция включает обновление MUI major-версий:
+- фиксируйте `package-lock.json`/`pnpm-lock.yaml`/`yarn.lock` в каждом шаге;
+- сохраняйте список основных регрессионных сценариев (smoke) и прогоняйте после каждого major.
+
+