@atomazing-org/design-system 2.0.1 → 3.7.2

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

@@ -1,81 +1,140 @@
-# Маршрут: 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)
+# Route: mui4-to-latest
+
+Use this route when the target app still depends on Material-UI v4 and must land
+on the `@atomazing-org/design-system` v2 contract with a MUI v7 baseline.
+
+## Use This Route When
+
+- `package.json` still contains `@material-ui/*`
+- the app still uses legacy styling APIs such as `makeStyles`, `withStyles`, or `createMuiTheme`
+- a piecemeal integration would otherwise leave the repo in a mixed MUI v4 and MUI v7 state
+
+## Target Outcome
+
+- the project runs on `@mui/material` v7 plus Emotion
+- `ThemeProviderWrapper` is the only app-level theme root
+- legacy MUI v4 imports and styling APIs are removed
+- major UI surfaces and typography rely on modern MUI theme contracts instead of legacy local tokens
+- the app boots cleanly after migration, not just after a codemod
+
+Use `../../shared/phases.md` as the canonical step-by-step phase checklist, then
+apply the route-specific requirements below.
+
+## Large-Project Execution Model
+
+- keep the app runnable at the end of every phase
+- keep one main change class per phase:
+  - dependency landing
+  - mechanical codemod
+  - legacy styling cleanup
+  - root theme unification
+  - runtime cleanup
+  - shared infrastructure
+  - domain waves
+  - final token cleanup
+- do not mix shell rewrites, broad token cleanup, and dependency upgrades in one unvalidated batch
+- checkpoint each phase with a commit or equivalent rollback point before continuing
+
+## Required Workflow (Phases)
+
+1. Inventory and segmentation
+   - map `@material-ui/*` dependencies and imports
+   - map `makeStyles`, `withStyles`, `createStyles`, `StylesProvider`, `ServerStyleSheets`, and `createMuiTheme`
+   - map local token modules, app shell entrypoints, shared overlays, auth-guarded routes, and build-system risks
+   - split the migration into shared-infrastructure scope plus domain waves
+2. Baseline and safety net
+   - run the repo's normal validation commands
+   - record pre-existing red checks separately from migration defects
+   - add or tighten smoke coverage for:
+     - the application shell
+     - at least one protected content route when route guards exist
+     - at least one stable overlay interaction when dialogs, drawers, or command surfaces are in scope
+3. Dependency landing zone
+   - remove `@material-ui/*`
+   - add `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`, and `@atomazing-org/design-system`
+   - separately align adjacent packages such as pickers, data-grid, lab, or other MUI ecosystem packages
+4. Mechanical v4 to v5 migration
+   - run the official MUI codemod
+   - resolve compile failures and TODO markers left by the codemod
+   - keep the output as a mechanical landing step, not a full visual cleanup
+5. Legacy styling and theme API cleanup
+   - replace `makeStyles`, `withStyles`, `createStyles`, and other JSS-specific patterns
+   - replace `createMuiTheme`, legacy `overrides` or `props`, and deprecated spacing or theme API usage
+   - remove legacy styling providers that no longer belong in the runtime
+6. Stabilize on modern MUI before design-system adoption
+   - get the app compiling and booting on modern MUI plus Emotion before changing the theme source of truth
+   - resolve duplicate React or Emotion runtime loading
+   - preserve the structural shell layout while removing legacy APIs
+7. Root theme unification
+   - connect `ThemeProviderWrapper` at the app root
+   - remove competing root `ThemeProvider` instances unless they are thin wrappers around the design system
+   - move preset selection into one explicit app-level theme module such as `src/theme/appThemes.ts`
+8. Runtime boot cleanup
+   - start the app with the repo's normal dev or start command
+   - open the first route in a real browser
+   - fix startup console errors before continuing
+   - fix migration-caused startup warnings before continuing
+   - remove module-scope code that depends on browser APIs, storage, or i18n locale activation
+   - move browser listeners such as `beforeinstallprompt`, `matchMedia`, or resize subscriptions into effects with cleanup
+   - if smoke mode disables auth redirects, seed a deterministic role-bearing user so protected routes can render real content
+9. Shared infrastructure migration
+   - stabilize the app shell, route wrappers, and shared layout containers first
+   - migrate shared primitives that should now use MUI directly or thin MUI wrappers
+   - restore shared dialogs, drawers, bottom sheets, and search overlays with stable semantics and layout contracts
+   - explicitly preserve `display`, grid or flex templates, `min-width`, `min-height`, `overflow`, and scroll behavior when refactoring shell containers
+   - if shell workspaces, route wrappers, or page roots were touched, verify the main content still fills the available content region instead of collapsing into partial-width cards or broken dashboard stacks
+   - audit compact shared UI such as chart legends, chips, segmented filters, and metric badges for preset drift; if they now read as ad hoc chip chrome, rebuild them with neutral MUI composition
+10. Token and consumer cleanup
+   - apply token remaps in controlled batches instead of one repo-wide blind replace
+   - replace hardcoded tokens with `theme.palette`, `theme.typography`, and MUI theme helpers
+   - remove zero-value wrappers and zero-value surface wrappers
+   - normalize visible text to `Typography` with explicit variants
+   - replace palette alpha suffix hacks with `alpha()`
+   - remove app-owned gradient or shadow chrome from normal consumer surfaces
+   - if codemods, token remaps, or file rewrites touched localized copy, keep files in UTF-8, scan for mojibake or replacement characters, and verify at least one real localized route renders readable text
+11. Domain waves
+   - migrate feature areas in waves after shared infrastructure is stable
+   - keep each wave small enough to validate independently
+   - run smoke and visual checks after each wave before moving to the next domain
+12. Final quality gates and closeout
+   - re-run lint, tests, build, and route-specific gates
+   - verify no `@material-ui/*` dependencies remain
+   - verify no `@material-ui/*` imports remain in source
+   - verify the app root uses `ThemeProviderWrapper`
+   - verify the first route boots without browser console startup errors or migration-caused runtime warnings
+
+## Common Failure Modes
+
+- treating the codemod result as a finished migration instead of a mechanical landing step
+- removing `@material-ui/*` but leaving JSS runtime or theme APIs in place
+- adopting the design system before the app is stable on modern MUI plus Emotion
+- mixing dependency upgrades, shell rewrites, and token cleanup into one giant diff that cannot be debugged safely
+- module-scope `window`, `document`, `navigator`, or storage access that breaks startup once providers move
+- module-scope i18n work that runs before locale activation
+- duplicate React or Emotion runtimes after moving to modern MUI
+- protected-route smoke checks that only render fallback pages instead of real product screens
+- shared shell or overlay rewrites that accidentally drop layout constraints, semantics, or spacing
+- route roots or page containers lose fill behavior, so the workspace shows partial-width cards, collapsed analytics grids, or unused content area
+- compact legends, analytics chips, metric badges, or segmented filters drift into consumer-owned chip chrome that visibly fights the preset
+- codemods or encoding fixes leave mojibake, replacement characters, or broken non-Latin text in screens, fixtures, or mock data
+- repo-wide token replacements applied before shared infrastructure is stabilized
+
+## Practical Fix Patterns
+
+- land on modern MUI plus Emotion first, then adopt `ThemeProviderWrapper`
+- keep a dedicated app theme module for preset selection
+- treat shell wrappers and overlay wrappers as behavior, not decoration
+- if a shell exposes a workspace pane, keep route roots and page containers on explicit flex growth with preserved `min-width`, `min-height`, and width constraints so the page actually fills the workspace
+- add smoke coverage before broad shared-component rewrites
+- migrate shared infrastructure before feature-specific pages
+- batch token replacement by shared area or domain instead of by global search alone
+- if compact legends, chips, or segmented filters drift away from the preset, rebuild them from `Stack`, markers, and `Typography` instead of preserving ad hoc chip styling
+- after bulk replacements or encoding-sensitive edits, run a mojibake scan and verify one localized route in a real browser before closing the migration
+- expand repo-local design and typography gates once the broad cleanup begins
+
+## Shared Gates
 
 Use common gate definitions from:
+
 - `../../shared/gates.md`
 - `../../shared/acceptance.md`

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

@@ -1,7 +1,7 @@
 {
   "$schema": "../../schema/migration.spec.schema.json",
   "id": "mui4-to-latest",
-  "title": "MUI v4 → MUI v7 + adopt @atomazing-org/design-system",
+  "title": "MUI v4 to MUI v7 plus @atomazing-org/design-system",
   "detect": {
     "packageJson": {
       "anyDependencies": [
@@ -12,59 +12,134 @@
     }
   },
   "entryConditions": [
-    "package.json содержит @material-ui/*",
-    "тесты/сборка до миграции зелёные"
+    "package.json contains @material-ui/*",
+    "the migration needs a full route-based upgrade instead of piecemeal edits"
   ],
   "exitConditions": [
-    "в package.json отсутствуют @material-ui/*",
-    "код не импортирует @material-ui/*",
-    "корень приложения использует ThemeProviderWrapper"
+    "package.json does not contain @material-ui/*",
+    "app source no longer imports @material-ui/*",
+    "the app root uses ThemeProviderWrapper",
+    "the app boots without migration-caused startup console errors",
+    "tests and build are green"
   ],
   "steps": [
     {
-      "name": "Preflight",
-      "run": ["npm ci", "npm test", "npm run build"]
+      "name": "Inventory and baseline",
+      "manualReview": [
+        "Map @material-ui/* imports and dependencies plus legacy styling APIs such as makeStyles, withStyles, createMuiTheme, StylesProvider, and ServerStyleSheets.",
+        "Record pre-existing failing checks separately from migration defects.",
+        "Split the repo into shared-infrastructure scope and domain migration waves before broad edits begin.",
+        "Run baseline checks with the target repository package manager (for example install/ci, tests, and build as available)."
+      ]
     },
     {
-      "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>"
-      ],
+      "name": "Add safety net",
       "manualReview": [
-        "Проверьте наличие альтернативных зависимостей (mui lab, x-пакеты, date-pickers, data-grid) и обновите их отдельно."
+        "Add or tighten smoke coverage for the application shell before broad refactors.",
+        "If route guards exist, ensure at least one protected content route can be validated as a real screen.",
+        "If shared overlays will be touched, add at least one stable overlay interaction to smoke coverage."
+      ]
+    },
+    {
+      "name": "Update package.json deps (v4 to modern MUI plus design-system)",
+      "manualReview": [
+        "Edit package.json directly: remove @material-ui/core, @material-ui/styles, and @material-ui/icons; add @mui/material:^7, @mui/icons-material:^7, @emotion/react:^11, @emotion/styled:^11, and @atomazing-org/design-system:<SET_VERSION>.",
+        "Check for adjacent ecosystem packages such as mui lab, x packages, date-pickers, or data-grid and align them separately.",
+        "Treat this as a dependency landing step only; do not mix in broad visual cleanup."
       ]
     },
     {
       "name": "Install deps",
-      "run": ["npm install"]
+      "manualReview": [
+        "Install dependencies with the target repository package manager (npm, pnpm, yarn, or bun)."
+      ]
     },
     {
-      "name": "Run official codemod (v4 → v5)",
-      "run": ["npx @mui/codemod@latest v5.0.0/preset-safe src"],
+      "name": "Run official codemod (v4 to v5)",
       "manualReview": [
-        "Просмотрите TODO и ошибки компиляции после codemod.",
-        "Проверьте стили на JSS (makeStyles/withStyles)."
+        "Run the official MUI codemod with a package-manager-appropriate executor (for example pnpm dlx, npm exec, yarn dlx, or bunx): @mui/codemod@latest v5.0.0/preset-safe src.",
+        "Review TODO markers and compile errors left by the codemod.",
+        "Treat the codemod output as a mechanical landing step, not as a finished migration."
+      ]
+    },
+    {
+      "name": "Remove legacy styling and theme APIs",
+      "manualReview": [
+        "Replace makeStyles, withStyles, createStyles, and other JSS-only patterns.",
+        "Replace createMuiTheme, legacy overrides or props usage, and deprecated theme API calls such as theme.spacing.unit.",
+        "Remove legacy styling providers that no longer belong in the runtime."
+      ]
+    },
+    {
+      "name": "Stabilize on modern MUI baseline",
+      "manualReview": [
+        "Get the app compiling and booting on modern MUI plus Emotion before changing the theme root.",
+        "Resolve duplicate React or Emotion runtime loading before design-system adoption.",
+        "Preserve the structural shell layout while modernizing the underlying MUI stack."
+      ]
+    },
+    {
+      "name": "Connect design-system provider",
+      "manualReview": [
+        "Connect ThemeProviderWrapper at the application root.",
+        "Remove or collapse any competing root ThemeProvider so the design system becomes the single theme source of truth.",
+        "Move preset selection into one explicit app-level theme module instead of leaving it scattered across generic constants layers."
+      ]
+    },
+    {
+      "name": "Runtime boot cleanup",
+      "manualReview": [
+        "Start the app with the repo's normal dev or start command and open the first route in a real browser.",
+        "Fix startup console errors before continuing.",
+        "Fix migration-caused startup warnings before continuing, especially duplicate runtime singleton warnings for react, react-dom, @emotion/react, and @emotion/styled.",
+        "Remove module-scope code that requires browser APIs, storage, or i18n locale activation.",
+        "Move browser event listeners into effects with cleanup instead of render paths or module scope.",
+        "If smoke mode disables auth redirect, seed a deterministic role-bearing user so protected routes can render real content."
+      ]
+    },
+    {
+      "name": "Shared infrastructure migration",
+      "manualReview": [
+        "Stabilize the app shell, route wrappers, and shared layout containers before domain-by-domain work.",
+        "Migrate shared primitives that should now use MUI directly or thin MUI wrappers.",
+        "Restore dialog, drawer, bottom-sheet, and search-overlay semantics before broad feature cleanup.",
+        "Preserve display, grid or flex templates, min-width, min-height, overflow, and scroll behavior when refactoring shell containers.",
+        "If shell workspaces, route wrappers, or page roots were touched, verify the main content still fills the available content region and that dashboard or workflow grids did not collapse into partial-width stacks.",
+        "Audit compact shared UI such as chart legends, chips, segmented filters, and metric badges for preset drift; replace ad hoc chip-like chrome with neutral MUI composition when needed."
       ]
     },
     {
       "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) и проверьте дифф.",
-        "Для сложных замен добавьте отдельные правила или выполните ручные правки."
+        "Use token-map.csv as a reference for targeted replacements and apply changes in controlled batches.",
+        "Enable only the rows needed in token-map.csv and review the diff in controlled batches.",
+        "For large repos, apply token replacement after shared infrastructure is stable instead of doing a blind repo-wide rewrite first.",
+        "For complex replacements, add dedicated rules or perform manual edits.",
+        "If bulk replacements or file rewrites touched localized copy, scan for mojibake or replacement characters and verify non-Latin UI text still renders readable strings."
+      ]
+    },
+    {
+      "name": "Domain migration waves",
+      "manualReview": [
+        "Migrate feature areas in waves after the shared shell and shared primitives are stable.",
+        "Keep each wave small enough to validate independently.",
+        "Re-run the relevant smoke or route checks after each wave before moving to the next domain."
       ]
     },
     {
       "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"
+      "manualReview": [
+        "Re-run the target repository closeout gates with its package manager: lint, tests, and build (when available).",
+        "Verify package.json and source contain no @material-ui/* dependencies or imports (for example with rg).",
+        "Run repo-local token/design-contract gates when available and manually verify forbidden legacy token usage is removed."
       ]
     }
   ],
-  "gates": ["no-legacy-material-ui", "no-hardcoded-tokens", "tests", "build"]
+  "gates": [
+    "no-legacy-material-ui",
+    "no-hardcoded-tokens",
+    "lint",
+    "tests",
+    "build"
+  ]
 }

package/migrations/docs/migrations/design-system/shared/WORKING-RULES.md

@@ -0,0 +1,194 @@
+# Working Rules For Consumer Repositories
+
+Use this document when integrating or maintaining `@atomazing-org/design-system`
+inside an application repository.
+
+## Public Surface Only
+
+- Import runtime APIs from `@atomazing-org/design-system`.
+- Import shipped presets from `@atomazing-org/design-system/presets`.
+- Do not import internal files from `src/*`, `dist/*`, or unpublished paths.
+
+## Standard Integration Contract
+
+- Wrap the app with `ThemeProviderWrapper`.
+- Use `useThemeSettings()` for runtime theme selection and dark-mode changes.
+- Treat the design system as the single source of truth for theme state.
+- Do not keep a second app-level theme state store unless it only mirrors design-system state.
+- Let the active preset own the application background.
+- Do not set app-level background colors or fills on root shells, route wrappers, or page containers when that would override the preset background supplied by the design system.
+- Treat `theme.palette.background.paper` and other surface tokens as component surfaces, not as a replacement for the preset-controlled page background.
+- If the app shell exposes a dedicated workspace or content pane, route roots and page containers must stretch to fill that region instead of shrinking to intrinsic content width.
+
+## Preset Selection Rules
+
+- `defaultThemes`: baseline application presets.
+- `landingPageThemes`: extended preset pack for landing pages and marketing surfaces.
+- `allBuiltInThemes`: combined pack for showcases or apps that intentionally want both sets.
+- Keep preset selection in one explicit app-owned theme module such as `src/theme/appThemes.ts`.
+- Do not hide preset choice behind generic constants passthrough files such as `src/constants/themes/themes.ts`.
+
+If the consumer app only needs one or two presets, prefer importing the named presets explicitly
+instead of building a new parallel preset registry.
+If the consumer needs a curated subset, export that subset from the app theme module instead of
+rebuilding theme state or duplicating preset metadata elsewhere.
+
+## Landing Composition Rules
+
+When the consumer app uses landing or marketing surfaces:
+
+- use `landingPageThemes` intentionally
+- let the active preset own the page background
+- let the active preset own the surface character of landing panels
+- do not hand-style landing `Paper` or `Card` surfaces with local glow, bloom, blur, decorative borders, gradient washes, or pseudo-element chrome
+- app code may control layout, spacing, sizing, and content hierarchy, but the visual treatment of surfaces must come from the preset/theme layer
+- prefer standard MUI composition for previews and proof blocks
+- avoid custom decorative shapes and pseudo-graphics when a simple MUI layout can express the same state
+- avoid nested rectangular surface hierarchies such as `card inside card inside card`
+- keep one primary outer surface and use lightweight MUI primitives inside it
+- if a preview block becomes dense, remove secondary content before tightening spacing
+
+## Surface Composition Rules
+
+Across consumer components in general:
+
+- one logical block should have one primary rectangular surface
+- let the active preset own the visual treatment of `Paper`, `Card`, `Dialog`, `Drawer`, and similar surfaces
+- do not hand-style consumer surfaces with local glow, halo, bloom, decorative borders, blur, gradient washes, or pseudo-element chrome
+- do not keep zero-value surface wrappers such as a local `SurfaceCard` that only forwards props to MUI `Card` without adding real behavior
+- do not keep large inline `sx` objects in JSX; if a component needs substantial styling, extract a local `styled(...)` component in the same file and keep those styled declarations near the bottom of the file
+- keep app styling focused on layout, spacing, sizing, and content hierarchy; move distinct surface looks into presets or MUI theme overrides
+- prefer `Stack`, `List`, `Divider`, `Typography`, `Chip`, and `Avatar` for internal composition
+- do not add extra bordered or elevated rectangular layers unless they carry a separate semantic role
+- do not restyle chart legends, compact filters, segmented controls, or status chips into ad hoc chip-like chrome that competes with the active preset; prefer neutral MUI composition and let the preset own the surface character
+
+## Design Token Hardening Rules
+
+- Use theme helpers such as `alpha()` instead of string-concatenated palette hacks like `${theme.palette.primary.main}1a`.
+- Decorative gradients and shadow styling are forbidden in normal consumer UI, especially on shared surfaces and shell infrastructure.
+- If a component must visually preview preset data, such as a theme swatch, document that exception inline and keep it on a small explicit allowlist in the repo-local design-contract check.
+- Repo-local design-contract lint should protect against decorative gradients, direct shadow styling, theme shadow-token drift, and palette alpha suffix hacks in addition to raw colors and numeric visual tokens.
+
+## MUI-First Component Rules
+
+- Prefer direct MUI primitives for base UI elements such as buttons, icon buttons, labels, helper text, skeletons, lists, drawers, and dialog sections.
+- Do not keep consumer-owned substitute atoms that merely recreate an existing MUI primitive with `div`, `label`, `span`, `Box`, or other generic wrappers.
+- If a consumer abstraction is still useful, keep it as a thin wrapper around the MUI primitive rather than a parallel hand-rolled implementation.
+- Remove zero-value wrappers that only rename a MUI primitive or surface without adding behavior, state policy, or accessibility value.
+- Exceptions are allowed only when there is clear custom logic or a pattern MUI does not provide directly, such as drag-and-drop zones, app-specific charts, or brand artwork.
+- Even when an exception is justified, compose it from MUI layout and surface primitives where possible.
+
+## Typography Contract Rules
+
+- Visible application text should be rendered through `Typography`, not left as raw JSX text inside layout wrappers.
+- Every `Typography` must declare an explicit `variant`.
+- Pick variants by semantics, not convenience:
+  - headings and section titles: `h1` through `h6`
+  - main body copy and helper text: `subtitle1`, `body1`, `body2`
+  - button and action labels: compact standard variants such as `subtitle2` or `button`
+  - chip, badge, and compact status labels: compact standard variants such as `caption`
+- When MUI interactive components such as `Button`, `ToggleButton`, `MenuItem`, `Chip`, or `Alert` need visible text, wrap that text in `Typography component="span"` with an explicit variant.
+- If the repo has a typography contract lint or script, keep it green as part of the migration gate.
+- If bulk replacements or file rewrites touch localized copy, keep files in UTF-8 and scan touched files for mojibake or replacement characters before closeout.
+- Validate at least one real route with non-Latin copy when the migration touched translated strings, mocks, or fixtures.
+
+## Overlay And Semantic Contract Rules
+
+- Dialogs, drawers, bottom sheets, and other overlay containers must expose stable `aria-labelledby` and `aria-describedby` semantics.
+- Shared dialog-title abstractions should accept stable title and subtitle ids so the overlay can wire those semantics directly instead of relying on incidental text structure.
+- Close buttons inside shared overlays must have explicit accessible labels.
+- Command palettes, searchable pickers, and other overlay search surfaces should use `combobox` plus `listbox` semantics when they own filtered keyboard navigation.
+- Decorative overlay chrome such as drag handles or visual grabbers should be hidden from assistive technology when it does not convey state.
+- Prefer stable overlay test hooks or landmarks for smoke coverage, and avoid brittle tests that depend on incidental navigation paths just to reach a modal.
+
+## Workflow Composition Rules
+
+- If multiple pages share the same workflow shell, form layout, or section grid, extract one shared layout contract instead of duplicating the page structure per role or route.
+- Keep role-specific behavior in headers, sections, and policy hooks; keep shared structure in a dedicated workflow layout component.
+- Prefer direct local imports for chunk-sensitive app internals when a barrel re-export introduces circular chunk warnings in build output.
+- Do not preserve convenience barrels for local app modules when they make execution order less reliable than direct feature-local imports.
+
+## Custom Preset Rules
+
+Custom presets must follow `ThemePreset` exactly:
+
+- stable string `id`
+- human-readable `label`
+- `colorSchemes.light`
+- `colorSchemes.dark`
+
+Each scheme should define:
+
+- `palette.background.default`
+- `palette.background.paper`
+- `palette.text.primary`
+- `palette.text.secondary`
+- `palette.divider`
+
+## SSR And Next.js Rules
+
+- Keep `ThemeProviderWrapper` inside a client boundary.
+- Do not access `window`, `document`, `navigator`, or `localStorage` at module scope.
+- If theme preference must be bridged through cookies or storage, keep the browser-specific logic client-safe.
+
+## Runtime Startup Rules
+
+- A green build is not enough to close a migration.
+- After dependency, provider, or theme-state changes, start the app with the repo's normal dev/start command.
+- Open the app in a real browser and fix startup console errors before closeout.
+- Fix migration-caused startup warnings before closeout when they indicate broken runtime alignment.
+- If runtime singleton warnings appear for `react`, `react-dom`, `@emotion/react`, or `@emotion/styled`, align the bundler config so only one runtime copy loads.
+- Avoid module-scope calls that require browser APIs, storage, or an activated i18n locale.
+- Register browser event listeners such as `beforeinstallprompt`, `matchMedia`, or other window-driven subscriptions inside effects with cleanup instead of render paths or module scope.
+- Verify that the app background still comes from the active preset after migration.
+- If the consumer uses root shells such as `AppShell`, `Layout`, `PageContainer`, or route wrappers, keep them transparent unless they intentionally represent a surface layer.
+- If token drift is broad, add or tighten a repo-local design contract gate for hardcoded colors, raw numeric type scale, ad hoc radius/opacity values, decorative gradients, shadow styling, and palette alpha suffix hacks, and keep it green.
+
+## Build Hygiene Rules
+
+- Fix consumer-owned build warnings that come from the app's own config, imports, or chunking strategy.
+- If PWA or Workbox config references asset names, keep those glob patterns aligned with the actual files emitted from `public/` or equivalent static assets.
+- If Vite or Rollup reports oversized consumer-owned chunks, prefer targeted `manualChunks` or additional lazy boundaries over simply increasing `chunkSizeWarningLimit`.
+- Do not silence a real warning when the app can fix the underlying config or bundling cause directly.
+- If the only remaining warning comes from an upstream toolchain package outside the consumer app's control, record the exact package and file instead of misclassifying it as an app regression.
+
+## Anti-Patterns
+
+Avoid these patterns:
+
+- deep imports from internal design-system files
+- a second competing root `ThemeProvider`
+- hardcoded theme colors when a theme token exists
+- hardcoded root-level page backgrounds that override the active preset background
+- hand-rolled substitute primitives for components MUI already provides
+- zero-value wrapper components that only rename a stock MUI primitive or surface
+- decorative gradients or shadow styling applied directly in consumer shells and shared surfaces
+- string-concatenated palette alpha hacks instead of theme helpers such as `alpha()`
+- local storage access outside SSR-safe guards
+- dialogs, drawers, or bottom sheets without stable semantic labeling
+- browser event listeners attached from render flow without cleanup
+- maintaining a parallel dark-mode enum or persistence format
+- role-based workflow pages that duplicate the same layout shell instead of sharing one structural contract
+- local barrel re-exports that introduce circular chunk warnings for app internals
+
+## When Migration Is Required
+
+Do not treat these as small integration tasks. Use route-based migration instead:
+
+- the app still uses `@material-ui/*`
+- the app has a custom token layer that should be replaced or normalized
+- the app mixes multiple theme providers or theme sources of truth
+- the user asks to standardize the project on this library
+- the migration touches a broad set of colors, typography, spacing, or component overrides
+
+## Route Selection
+
+- `mui4-to-latest`: legacy Material UI v4 imports or dependencies
+- `greenfield`: new app, or no legacy theme/token migration required
+- `adopt-existing`: app already uses modern MUI but needs theme/token adoption
+
+## Recommended User Request
+
+Use a request like this with an AI agent:
+
+`Adopt @atomazing-org/design-system in this repo. If the current theme stack is legacy or custom, choose the correct migration route and execute the migration runbook.`