@atomazing-org/design-system 2.0.1 → 2.0.2

package/migrations/README.UPDATE.md

@@ -1,29 +1,41 @@
-# Что здесь должно быть (исправленный формат)
+# Migration And Agent Entry Points
 
-Вы правы: для этой задачи в `migrations/` нужны не исполняемые `mjs`-скрипты, а **инструкции для ИИ/агента**, который выполняет миграцию по runbook'ам.
+This folder ships migration guidance and AI-facing instructions with
+`@atomazing-org/design-system`.
 
-## Source of truth
+## Source Of Truth
 
-- `migrations/skills/design-system-migration-agent/SKILL.md` — инструкция для ИИ (главная точка входа)
-- `migrations/docs/migrations/design-system/*` — маршруты миграции, runbook'и, shared criteria
+- `AGENTS.md`
+- `migrations/skills/design-system-consumer-agent/SKILL.md`
+- `migrations/skills/design-system-migration-agent/SKILL.md`
+- `migrations/docs/migrations/design-system/README.md`
+- `migrations/docs/migrations/design-system/shared/WORKING-RULES.md`
 
-## Как использовать (через ИИ)
+## What Ships With The Package
 
-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.
+- working rules for application repositories
+- route-based migration docs and shared gates
+- AI skills for standard adoption and migration-heavy adoption
+- a concrete `adopt-existing` case study in `routes/adopt-existing/AEROCRM-EXAMPLE.md`
 
-## Что настроить перед запуском
+## Which Entry Point To Use
 
-- Заменить `<SET_VERSION>` в route spec (или сообщить версию агенту явно).
-- Для token migration подготовить mapping (`token-map.csv`) под конкретный проект.
-- Для route `adopt-existing` определить список legacy token imports/identifiers (для search/gates).
+- standard integration or maintenance:
+  - `migrations/skills/design-system-consumer-agent/SKILL.md`
+- route-based migration:
+  - `migrations/skills/design-system-migration-agent/SKILL.md`
 
-## Про `migrations/scripts/*`
+## When To Prefer Migration
 
-`migrations/scripts/*` сейчас можно считать **необязательной/избыточной реализацией** (референс для автоматизации). Для вашего исходного запроса source of truth — именно skill + docs.
+Use route-based migration instead of ad hoc edits when the target app has:
+
+- `@material-ui/*`
+- a custom token or theme layer
+- multiple theme providers or persistence stores
+- a broad request to standardize the UI foundation on this package
+
+## Notes
+
+- `migrations/scripts/*` is optional legacy automation.
+- The docs and skills are the source of truth for AI-driven migration work.
+- Migration closeout now requires a real app startup check, not only lint/test/build.

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

@@ -6,7 +6,7 @@ This folder contains the migration router, runbooks, and route specs used to ado
 Target baseline:
 - design-system v2 contract
 - MUI v7
-- React 18/19
+- React 18 or 19
 
 Repo route model (canonical):
 - `mui4-to-latest` (backlog alias: `mui4-to-v7`)
@@ -17,53 +17,84 @@ Repo route model (canonical):
 
 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:
+2. Else if the app is new or 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:
+Use the AI skill or instructions as the primary execution method:
 
+- `migrations/skills/design-system-consumer-agent/SKILL.md`
 - `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:
+1. Read `shared/WORKING-RULES.md`.
+2. Read `shared/phases.md`.
+3. Detect route manually (inspect `package.json`, imports, and current theme setup).
+4. Read the selected route spec plus 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
-```
+5. Build a phased plan before editing the target repo.
+6. Execute the route phase by phase instead of batching unrelated changes together.
+7. Run quality gates and checks after each meaningful phase, including a real app boot check before closeout.
+
+## Phase Discipline For Large Projects
+
+For large repos, route execution must stay phase-gated:
+
+- keep the app runnable at the end of every phase
+- keep one main change class per phase:
+  - dependency landing
+  - mechanical migration
+  - root theme unification
+  - runtime cleanup
+  - shared infrastructure
+  - domain waves
+  - final token and closeout cleanup
+- do not combine dependency upgrades, shell rewrites, and broad token cleanup into one unvalidated batch
+- add or tighten a smoke safety net before broad shell, overlay, or shared-component rewrites
+- stabilize shared infrastructure before domain-by-domain feature waves
+- checkpoint each phase with a commit or equivalent rollback point before continuing
 
 Recommended manual gate equivalents:
 - search for `@material-ui/*` in source and `package.json`
-- search for legacy token imports/identifiers defined for the route/project
+- search for legacy token imports or identifiers defined for the route or project
+- start the app with the repo's normal dev or start command
+- open the first route in a real browser and confirm there are no browser console startup errors
+- fix migration-caused startup warnings before closeout, especially duplicate runtime singleton warnings (`react`, `react-dom`, `@emotion/react`, `@emotion/styled`)
+- if route guards exist, verify at least one protected route as a real screen rather than a fallback page
+- if overlays are in scope, verify at least one stable overlay interaction through smoke or manual QA
+- if shell workspaces or page-root containers were touched, verify the main content fully occupies the workspace and dashboard or form grids do not collapse into partial-width stacks
+- if shared charts, legends, chips, segmented filters, or metric badges were touched, verify compact controls still align with the active preset instead of drifting into ad hoc chip-like chrome
+- if bulk replacements or non-Latin copy were touched, scan for mojibake or replacement characters and verify readable localized text on at least one real route
+
+If normal integration would leave dual theme systems or a large unresolved token layer,
+do not treat the task as a small refactor. Select a migration route instead.
 
 ## 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)
+- `adopt-existing`: `./routes/adopt-existing/RUNBOOK.md`
+- `adopt-existing` example: `./routes/adopt-existing/AEROCRM-EXAMPLE.md`
 
 ## Shared gates
 
 Common migration gates are documented in:
 
+- `./shared/phases.md`
+- `./shared/phase-exit-criteria.md`
+- `./shared/common-regressions.md`
+- `./shared/manual-qa-matrix.md`
 - `./shared/gates.md`
 - `./shared/acceptance.md`
 
-Routes should reference the shared gates docs instead of duplicating the full gate list.
+Routes should reference the shared gate 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/AEROCRM-EXAMPLE.md

@@ -0,0 +1,197 @@
+# AeroCRM Frontend Example For `adopt-existing`
+
+This example captures a full migration of
+`C:\Users\Lenovo\Desktop\DEV_PRESALE\aerocrm\frontend` to
+`@atomazing-org/design-system@2.0.1`.
+
+## Why `adopt-existing`
+
+The app already had:
+
+- React 19
+- MUI 7
+- `@atomazing-org/design-system`
+- an app-level wrapper around `ThemeProviderWrapper`
+
+This was not a greenfield integration and not a Material UI v4 migration.
+
+## Real Problems Found
+
+1. A consumer component still imported `useResponsiveDisplay` from the old design-system root API.
+2. The app crashed on startup because a Lingui translation was evaluated at module scope before locale activation.
+3. After the crash was fixed, the app still warned that `@emotion/react` was loaded more than once in dev.
+4. A shell refactor temporarily broke the desktop layout, so the original `sidebar + content` grid was lost.
+5. The app had no automated shell smoke-check, so the layout regression was caught manually at first.
+6. Several shared UI components were flattened into pass-through wrappers or empty placeholders, which degraded charts, drawers, segmented controls, cards, and toolbars across multiple screens.
+7. Smoke mode disabled auth redirect, but without a seeded user it only exercised route fallbacks like `NotFound` instead of the protected pages that actually matter.
+8. Some consumer-owned atoms still reimplemented stock MUI primitives with generic wrappers such as `Box`, raw `label`, or `div`, which made the shared layer inconsistent and easy to regress.
+9. Text rendering was inconsistent across shared and page UI: raw text remained inside buttons, chips, alerts, and wrappers, and some `Typography` nodes had no explicit variant.
+10. Preset selection lived behind a generic constants passthrough layer instead of one explicit app-owned theme module.
+11. Role-based ticket workflows duplicated the same two-column form shell across `NewTicket`, `Responsible`, and `Approver`.
+12. Local barrel re-exports produced chunk-cycle build warnings until workflow-local modules were imported directly.
+13. Workbox still looked for `favicon.svg` even though the app emitted `logo192.png`, `logo256.png`, `logo384.png`, and `logo512.png`.
+14. Build output contained oversized consumer-owned chunks until vendor splitting was configured explicitly.
+15. Shared overlays had semantic drift: dialog and drawer wrappers no longer exposed stable label or description wiring, command palette search behaved like generic markup instead of combobox or listbox UI, and decorative bottom-sheet chrome remained visible to assistive technology.
+16. `PwaInitializer` attached browser listeners from the render path, which risked duplicate `beforeinstallprompt` and display-mode handlers after rerenders.
+17. The app still kept a zero-value `SurfaceCard` wrapper that only forwarded to MUI `Card`, which blurred ownership between app primitives and stock MUI surfaces.
+18. Shared consumer styling still contained design-contract drift:
+   - the PWA install banner injected its own gradient chrome
+   - sidebar selection used palette-string alpha suffix hacks instead of theme helpers
+   - the repo-local design-contract lint did not yet protect against those patterns
+19. A later QA pass found compact analytics legend chips that no longer matched the active preset and read like ad hoc consumer chrome instead of neutral shared UI.
+20. Some page roots stopped filling the workspace, so tickets and analytics could collapse into partial-width content with broken grids and unused work area.
+21. A later text-integrity pass found mojibake and replacement characters in Cyrillic copy across screens, fixtures, and mock data.
+22. A later shell-sizing pass found the shared workspace overflowing on the right edge across routes because some shared containers mixed `width: 100%` with internal padding under content-box sizing.
+23. A later analytics QA pass found metric labels, values, and helper text collapsing into the same visual level, while the reasons card still carried an accidental full-width span and inconsistent gaps.
+
+## Applied Fixes
+
+1. Upgrade `@atomazing-org/design-system` from `1.2.9` to `2.0.1`.
+2. Replace the outdated root import in `ResponsiveModal` with the app's local `@hooks` export.
+3. Remove module-scope translation from the toast layer:
+   - do not call translation helpers at module scope before `i18n.loadAndActivate()`
+   - move the translated label into component render with `Trans`
+4. Deduplicate singleton runtimes in Vite:
+   - add `resolve.dedupe` for `react`, `react-dom`, `@emotion/react`, and `@emotion/styled`
+5. Restore the app shell layout in `Harness.tsx`:
+   - keep an explicit desktop grid for `sidebar + content`
+   - preserve content scrolling and sizing with `minHeight`, `minWidth`, and `overflow`
+6. Add an automated smoke-check:
+   - run the app in mock mode
+   - disable silent auth redirect only for smoke mode
+   - seed a deterministic demo user with required roles in smoke mode
+   - assert desktop and mobile shell layout with Playwright
+   - assert role-protected pages render real content, not only shell plus fallback
+7. Restore shared UI contracts when they were simplified into placeholders:
+   - rebuild shared cards, overlays, radio groups, charts, and nav actions with explicit spacing, sizing, and interaction states
+   - do not accept placeholder structures like empty `Box` tracks or pass-through wrappers as "good enough" migration output
+8. Replace substitute shared primitives with MUI-based equivalents when no real custom behavior exists:
+   - move atoms like `IconButton`, `FormLabel`, `FormError`, and `Skeleton` onto direct MUI primitives or thin wrappers
+   - move picker clear affordances into MUI `InputAdornment` instead of keeping floating ad hoc controls
+9. Normalize the text layer:
+   - render visible text through `Typography` with explicit variants
+   - wrap button, chip, alert, menu-item, and toggle labels in `Typography component="span"`
+   - add a small typography contract lint so future refactors cannot silently reintroduce raw text nodes
+10. Make preset policy explicit:
+   - replace generic constants passthrough exports with one theme-owned `appThemes` module
+   - keep the consumer's allowed preset pack visible near `AppThemeProvider`
+11. Add a design-contract guard:
+   - fail the migration on hardcoded colors, raw numeric type scale, and ad hoc radius or opacity values when those patterns are widespread
+12. Collapse repeated workflow page shells into one layout contract:
+   - extract a shared `TicketFormLayout` for the common two-column form shell
+   - keep page-specific behavior in headers and sections
+   - import workflow-local modules directly when barrel exports create chunk-cycle warnings
+13. Align PWA asset config with real app assets:
+   - replace the stale `favicon.svg` Workbox glob with the actual emitted logo files
+14. Split oversized local bundles intentionally:
+   - add targeted `manualChunks` groups for React, MUI, Emotion, forms, auth, i18n, design-system, and module-federation vendor code
+   - remove chunk warnings by changing bundling strategy, not by inflating the warning threshold
+15. Refresh the local browser-target database:
+   - update `caniuse-lite` / Browserslist data so the build reflects the current target matrix
+16. Restore overlay semantics and overlay-smoke coverage:
+   - wire `ResponsiveModal`, shared dialog titles, and notification drawer through stable `aria-labelledby` and `aria-describedby` ids
+   - add explicit accessible labels to shared close actions
+   - hide decorative bottom-sheet handles from assistive technology
+   - update smoke checks through stable overlay entrypoints such as notifications and command palette
+17. Normalize command palette search semantics:
+   - make the search field a real combobox
+   - make the result list a real listbox with active option tracking and keyboard-help text
+18. Move browser-only PWA listeners into effects with cleanup:
+   - attach `beforeinstallprompt` and display-mode listeners from `useEffect`
+   - remove duplicate subscriptions on rerender
+19. Remove zero-value surface wrappers:
+   - delete `SurfaceCard`
+   - use direct MUI `Card` composition in analytics, profile, tickets, and metric surfaces
+20. Harden the consumer visual-token contract:
+   - simplify the PWA install banner to a standard MUI surface instead of a local gradient panel
+   - replace palette alpha suffix hacks with `alpha()`
+   - expand `lint:design-contract` to fail on decorative gradients, direct shadow styling, theme shadow-token drift, and palette suffix hacks
+   - keep the theme swatch as the only documented exception because it intentionally previews preset colors
+21. Rework preset-drifted analytics legends:
+   - replace custom chip-like legend chrome with neutral marker plus `Typography` composition
+   - keep compact analytic labels visually aligned with the preset instead of recreating local chip styling
+22. Restore workspace fill behavior:
+   - preserve flex growth and min-size constraints in the shell content area
+   - make ticket and analytics page roots fill the available content pane instead of shrinking to content width
+23. Normalize Cyrillic text integrity:
+   - repair mojibake and replacement-character corruption in touched UI files and mocks
+   - keep rewritten files in UTF-8
+   - recheck smoke-visible strings after bulk fixes
+24. Harden shared box sizing for shell-critical containers:
+   - remove shell sizing that makes the main content column wider than the visible desktop workspace
+   - apply `box-sizing: border-box` to shared padded containers such as app-owned cards and page roots when they are also expected to fill available width
+   - add smoke assertions that fail on horizontal overflow in the shared content pane and routed page roots
+25. Restore analytics dashboard hierarchy and grid discipline:
+   - separate metric labels, values, and helper text into different text scales instead of relying on one blended default
+   - emphasize numeric values in breakdown lists and timeline rows so they do not read like surrounding labels
+   - remove the accidental full-width analytics-card span and keep one consistent desktop gap contract across the dashboard grid
+   - add smoke assertions that fail if metric value emphasis disappears or if the desktop analytics cards stop sharing the intended row
+
+## Resulting Validation
+
+- `npm run lint` passed
+- `npm run lint:style-contract` passed
+- `npm run lint:design-contract` passed
+- `npm run lint:typography-contract` passed
+- `npm run lint:ts` passed
+- `npm run build` passed
+- `npm run test:smoke` passed
+- the app started successfully in the browser
+- first page load completed with `0` browser console errors
+- first page load completed with `0` browser console warnings
+- desktop layout again renders with the menu on the left and page content on the right
+- ticket and analytics pages again occupy the full workspace instead of collapsing into partial-width stacks
+- shared workspace content no longer protrudes past the visible right edge when routed pages render padded full-width surfaces
+- analytics metrics again read as metrics instead of plain helper text, and the reasons card no longer drops onto its own desktop row
+- `npm run test:smoke` now protects the shell layout, smoke auth bootstrapping, profile rendering, and analytics route against the same regression class
+- `npm run test:smoke` now also protects notification drawer and command palette overlay behavior through stable entrypoints
+- `npm run test:smoke` now also fails if the shared content pane or routed page roots overflow horizontally on desktop
+- `npm run test:smoke` now also fails if analytics metric emphasis disappears or if the three desktop analytics cards stop aligning in the intended row
+- preset selection is now explicit in a theme-owned `appThemes` module instead of a generic constants passthrough
+- repeated ticket workflow pages now share a `TicketFormLayout` contract instead of duplicating the same shell three times
+- build no longer reports the previous local chunk-cycle warning around `UploadedFiles`
+- Workbox no longer warns about a missing `favicon.svg`
+- local chunk-size warnings are gone after targeted vendor splitting
+- the stale Browserslist database warning is gone after refreshing `caniuse-lite`
+- shared overlays now expose stable dialog semantics instead of relying on incidental text structure
+- command palette search now follows explicit combobox or listbox accessibility semantics
+- browser-driven PWA listeners no longer attach during render
+- analytics, profile, and ticket surfaces no longer depend on a zero-value `SurfaceCard` wrapper
+- the PWA install banner no longer competes with preset styling through a local gradient surface
+- sidebar state styling now uses theme helpers instead of palette-string alpha suffix hacks
+- `lint:design-contract` now enforces decorative-token drift rules with a documented swatch exception
+- analytics legends no longer use preset-breaking custom chip chrome
+- the post-fix text scan no longer finds mojibake or replacement characters in the touched migration surface
+
+## Lessons To Reuse
+
+- A green build does not prove the app actually boots after migration.
+- Startup console errors must be part of the migration gate, not an optional QA note.
+- Module-scope i18n work is a migration risk in apps that initialize locale asynchronously.
+- Duplicate React or Emotion runtime warnings should be fixed immediately with bundler dedupe or the repo's equivalent singleton-sharing mechanism.
+- Layout wrappers are behavioral infrastructure. Replacing them with plain containers without porting grid or flex constraints can break the whole app shell even when TypeScript and build are green.
+- Route roots need the same discipline as shell wrappers. If they stop stretching to fill the workspace, dashboards and work areas can look broken even though the route still technically renders.
+- Width filling plus internal padding needs explicit box-sizing discipline in shared containers. A padded app-owned `Card` or page root with `width: 100%` can silently overflow the workspace by a few pixels on every route.
+- Dashboard metrics need their own hierarchy gate. If labels, values, and helper text collapse to one scale, the screen still renders but stops communicating status.
+- Desktop dashboard grids need explicit span discipline. A stale full-width card prop can silently break row alignment even when the page still compiles and passes a basic render check.
+- Route-protected pages need a deterministic smoke user; otherwise automated checks may "pass" against `NotFound` or fail for the wrong reason.
+- Shared UI regressions often show up as flattened pass-through wrappers or empty placeholder markup. Search for those patterns explicitly after migration.
+- Compact shared UI can regress without turning into placeholders. Chart legends, chips, and segmented filters should be checked for preset drift, not only for presence.
+- Shared UI layers can also hide substitute atoms that duplicate stock MUI controls. Replace them during migration instead of treating them as acceptable legacy structure.
+- Overlay wrappers can silently lose semantic wiring even when the visual layout still looks acceptable. Keep stable title or description ids, labeled close actions, and combobox or listbox roles under test when overlays are touched.
+- Decorative overlay chrome such as bottom-sheet grab handles should be hidden from assistive technology unless it conveys state.
+- Browser event listeners belong in effects with cleanup. Render-path subscriptions can create duplicated runtime behavior without tripping TypeScript or build.
+- Zero-value surface wrappers are not harmless convenience. If a wrapper only forwards MUI `Card` or `Paper`, delete it and keep the component tree honest.
+- Design-contract lint should guard against decorative gradients, direct shadow styling, and palette alpha suffix hacks, not only raw hex colors.
+- If a visual-preview component really needs gradient or shadow styling, document that exception inline and keep it on a tiny explicit allowlist instead of letting the pattern spread.
+- Keep preset policy explicit in the theme layer. Generic constants passthrough files hide the real allowed preset pack and make later migration drift easier.
+- If several role-based pages share the same shell, extract one layout contract before making further visual changes. Duplicated workflow shells drift quickly.
+- Local app barrels are optional, not sacred. If a barrel creates chunk-cycle warnings, use direct imports for the affected workflow internals.
+- A small design-contract lint is worth adding when raw colors, raw numeric font sizes, or ad hoc radius/opacity values are already spreading through the UI.
+- Asset globs are part of migration correctness. If PWA config points at files the app does not emit, fix the config instead of carrying the warning forward.
+- For chunk warnings, prefer targeted vendor splitting or new lazy boundaries. Raising the warning limit is not a migration fix.
+- If one warning remains and it comes from an upstream toolchain package, record it precisely as external debt instead of treating it as unresolved app work.
+- Text regressions deserve their own gate. If an app has broad UI churn, add a typography contract check so raw text nodes and variantless typography fail fast.
+- Encoding regressions deserve their own gate too. After bulk rewrites, scan for mojibake or replacement characters and verify at least one real localized route before closing the migration.
+- For important shell layouts and core pages, add a dedicated smoke-check instead of relying only on manual QA after migration.
+- For overlay-heavy apps, prefer smoke coverage through stable entrypoints such as notification drawers or command palettes instead of brittle settings-modal paths that are not consistently reachable in the current route.

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

@@ -1,34 +1,194 @@
-# Маршрут: Рефакторинг на актуальном MUI + применение дизайн-системы (adopt-existing)
+# Route: adopt-existing
 
-## Когда использовать
+Use this route when the target app already runs on modern MUI and needs to adopt
+or normalize `@atomazing-org/design-system` without a legacy Material UI v4 jump.
 
-- Проект уже использует `@mui/material` (v5/v6/v7).
-- Нужна унификация темы/типографики/палитры через `@atomazing-org/design-system`.
-- Основная работа — убрать хардкоды токенов и перейти на `theme.*`.
+## Use This Route When
 
-## Результат
+- the project already depends on `@mui/material`
+- the project already has a theme setup, token layer, or design-system usage to normalize
+- the migration is about aligning an existing app, not bootstrapping a new one
 
-- `ThemeProviderWrapper` — единственный источник настроек темы.
-- Токены из проекта либо удалены, либо превращены в thin-adapter вокруг `theme`.
+## Target Outcome
 
-## Шаги
+- `ThemeProviderWrapper` is the only app-level source of truth for theme state
+- old design-system integration points are removed or normalized
+- token usage moves toward `theme.*`
+- the app boots cleanly after migration, not just compiles
 
-1) Preflight: тесты и сборка зелёные.
-2) Установить `@atomazing-org/design-system` и peer deps (если не установлены).
-3) Подключить `ThemeProviderWrapper` на корне приложения.
-4) Сделать инвентаризацию токенов:
-   - где лежат цвета/типографика/spacing/радиусы;
-   - какие алиасы используются чаще всего.
-5) Заполнить mapping (CSV/JSON) и применить безопасные замены.
-6) Прогнать gates + тесты + сборку.
+Use `../../shared/phases.md` as the canonical step-by-step phase checklist, then
+apply the route-specific requirements below.
 
-## Стратегия переносов (рекомендуется)
+## Large-Project Execution Model
 
-- Сначала цвета поверхностей и текстов (фон/текст/бордер/brand).
-- Затем типографика (перевод на variants или `theme.typography`).
-- Затем компонентные размеры/spacing.
-## Shared gates (repo)
+- keep the app runnable at the end of every phase
+- keep one main change class per phase:
+  - dependency alignment
+  - root theme unification
+  - runtime cleanup
+  - shared infrastructure
+  - token and wrapper cleanup
+  - domain waves
+  - final gate pass
+- do not mix shell rewrites, broad token cleanup, and bundler hygiene changes into one unvalidated batch
+- checkpoint each phase with a commit or equivalent rollback point before continuing
 
-Use common gate definitions from:
-- `../../shared/gates.md`
-- `../../shared/acceptance.md`
+## Required Workflow (Phases)
+
+1. Inventory and segmentation
+   - map current design-system usage, theme entrypoints, local token modules, shared shell code, shared overlays, and protected routes
+   - split the repo into shared-infrastructure scope plus domain migration waves
+2. Baseline and safety net
+   - run the normal validation commands that exist in the repo
+   - 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 overlays are in scope
+3. Update dependencies
+   - add or upgrade `@atomazing-org/design-system`
+   - ensure peer runtimes are compatible
+   - align adjacent runtime packages before moving deeper into UI cleanup
+4. Align provider wiring and public API usage
+   - connect `ThemeProviderWrapper` at the app root
+   - remove competing root theme providers unless they are thin wrappers around the design system
+   - replace removed or old root imports
+   - stop deep-importing design-system internals
+   - remove parallel theme state when it conflicts with design-system state
+   - move preset selection into one explicit app-level theme module instead of leaving it split across generic constants passthrough files
+5. Runtime boot cleanup
+   - start the app with the repo's normal dev/start command
+   - open the first route in a real browser
+   - fix startup console errors before continuing
+   - fix migration-caused startup warnings before continuing
+   - specifically resolve duplicated runtime singleton warnings for `react`, `react-dom`, `@emotion/react`, and `@emotion/styled`
+   - remove module-scope code that depends on browser APIs, storage, or i18n locale activation
+   - move browser event listeners such as `beforeinstallprompt` or `matchMedia` subscriptions into effects with cleanup
+   - if smoke or test mode disables auth redirect, seed a deterministic user with enough roles to exercise protected routes
+6. Shared infrastructure stabilization
+   - verify the structural app shell still matches the pre-migration layout on desktop and mobile
+   - verify the app background still comes from the selected preset and is not replaced by a hardcoded app-shell or page-wrapper background
+   - if a layout container is simplified or rewritten, explicitly preserve its `display`, column or row template, `min-width`, `min-height`, `overflow`, and scroll behavior
+   - if shared containers combine `width: 100%` with internal padding, normalize them with explicit `box-sizing: border-box` or remove the forced width so the content pane does not overflow horizontally
+   - 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
+   - if analytics dashboards or metric cards were touched, keep label and value typography clearly separated and make sure dashboard cards do not inherit accidental full-width spans or inconsistent gap rhythms on desktop
+   - restore shared overlays with stable dialog semantics:
+     - dialogs, drawers, and bottom sheets should wire `aria-labelledby` and `aria-describedby`
+     - close buttons should keep explicit accessible labels
+     - decorative overlay handles should stay hidden from assistive tech
+   - if an overlay owns keyboard-filtered search results, expose `combobox` and `listbox` semantics instead of generic wrapper markup
+   - inspect shared UI primitives for placeholder regressions:
+     - empty `Box` or `Stack` shells where charts or progress bars used to render
+     - pass-through wrappers that dropped padding, borders, hover states, or sizing
+     - simplified nav, dialog, drawer, and card components that no longer preserve spacing or alignment
+     - root shells or route wrappers that set `background` or `backgroundColor` and hide the preset background
+7. Token, typography, and wrapper cleanup
+   - replace legacy token files and hardcoded theme values with `theme.palette`, `theme.typography`, and design-system contracts
+   - normalize visible text so headings, body copy, helper text, and compact labels use explicit `Typography` variants instead of raw JSX text
+   - wrap raw text inside `Button`, `ToggleButton`, `MenuItem`, `Chip`, and `Alert` with `Typography component="span"`
+   - add explicit `variant` to every `Typography` and choose variants semantically instead of relying on defaults
+   - replace consumer-owned substitute primitives with MUI equivalents when the code only reimplements a stock MUI control such as `IconButton`, `FormLabel`, `FormHelperText`, or `Skeleton`
+   - remove zero-value wrappers that only rename stock MUI primitives or surfaces without adding meaningful behavior
+   - remove zero-value surface wrappers that only forward to MUI `Card`, `Paper`, or similar components without adding real behavior
+   - replace palette alpha suffix hacks with theme helpers such as `alpha()`
+   - if consumer surfaces use app-owned gradient washes, decorative shadows, or other preset-competing chrome, simplify them back to standard MUI surfaces unless the component is an intentional preset-preview exception
+   - if raw visual token drift is broad, add or tighten a repo-local design-contract lint or script gate and keep it green
+   - if the repo has no typography contract check and text regressions are widespread, add a small lint or script gate so future migrations cannot reintroduce raw text or variantless typography
+   - if the repo keeps a design-contract lint, expand it to catch decorative gradients, direct shadow styling, palette alpha suffix hacks, and any file-local allowlist drift
+   - if codemods, bulk replacements, 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
+8. Shared workflow extraction and bundler hygiene
+   - if multiple pages share the same workflow shell, extract a shared layout contract and keep role-specific differences in header or section composition
+   - if local barrels introduce circular chunk warnings for app internals, replace those imports with direct local module imports
+   - if Workbox or PWA config references assets that the app does not actually emit, align the glob patterns with the real static files instead of leaving the warning in place
+   - if Vite reports oversized local chunks, add targeted `manualChunks` or lazy boundaries before considering any warning-limit change
+9. Domain waves
+   - migrate feature areas after shared infrastructure is stable
+   - keep each wave small enough to validate independently
+   - re-run the relevant smoke and route checks after each wave before moving on
+10. Re-run the shared gates and route checks
+   - lint, tests, and build where available
+   - browser startup verification
+   - verify smoke checks cover page content on protected routes, not only the surrounding shell
+   - verify smoke coverage still includes stable entrypoints for shell-critical overlays such as notifications or command palette when overlay infrastructure changed
+
+## Common Failure Modes
+
+- removed or no-longer-public root imports still referenced from app code
+- module-scope i18n translation calls before locale activation
+- module-scope `window`, `document`, `navigator`, or storage access
+- duplicate Emotion or React runtime copies in Vite, Next.js, or module federation setups
+- preset selection hidden behind generic constants passthrough layers instead of one explicit app theme module
+- structural layout containers replaced with plain wrappers that drop grid or flex behavior
+- lost `min-width`, `min-height`, or `overflow` constraints that previously kept sidebar and content regions stable
+- shared padded containers keep `width: 100%` under content-box sizing, so the workspace silently protrudes past the visible right edge
+- route roots or page containers lose fill behavior, so the workspace shows partial-width cards, collapsed analytics grids, or unused content area
+- analytics metric labels and values collapse to the same text scale, so dashboard numbers no longer stand out from titles or helper text
+- dashboard cards keep an old `gridColumn: 1 / -1` or mixed gap contract, so one analytics panel falls onto its own row while neighboring cards use a different rhythm
+- protected routes only tested in guest mode, so smoke checks exercise `NotFound` instead of real product screens
+- shared charts, cards, drawers, or segmented controls reduced to pass-through wrappers or empty placeholder nodes
+- compact legends, analytics chips, metric badges, or segmented filters drift into consumer-owned chip chrome that visibly fights the preset
+- root app containers hardcode their own page background and visually cancel the active preset background
+- dialogs, drawers, or bottom sheets lose semantic labeling during wrapper refactors
+- browser event listeners attach from render flow and duplicate behavior across rerenders
+- search overlays filter results visually but expose no combobox or listbox semantics
+- raw JSX text left inside app layout wrappers, buttons, chips, or menu items after refactors
+- `Typography` used without an explicit semantic `variant`, which makes text hierarchy drift across screens
+- zero-value wrapper components preserved even though they only rename stock MUI controls
+- zero-value surface wrappers preserved even though direct MUI `Card` or `Paper` usage would be clearer
+- app-owned gradient or shadow chrome left on consumer surfaces after the design system already defines surface character
+- palette alpha suffix hacks such as `${theme.palette.primary.main}1a` left in shared styling instead of `alpha()`
+- codemods or encoding fixes leave mojibake, replacement characters, or broken non-Latin text in screens, fixtures, or mock data
+- repeated workflow pages keep copied layout shells instead of sharing one structural contract
+- local barrel re-exports create circular chunk warnings for app internals during build
+- stale Workbox or PWA asset globs point to files the app does not emit
+- oversized local vendor or app chunks are left unresolved even though targeted chunk splitting is possible
+
+## Practical Fix Patterns
+
+- import only from `@atomazing-org/design-system` or `@atomazing-org/design-system/presets`
+- move browser-only or locale-dependent work out of module scope and into runtime-safe component or hook code
+- if the bundler loads duplicate React or Emotion runtimes, add the repo's equivalent of runtime dedupe or singleton sharing
+- move preset selection into a dedicated app theme module such as `src/theme/appThemes.ts`
+- when refactoring shell components, treat layout 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
+- if a shared card, page root, or shell content container must both fill width and keep internal padding, use `box-sizing: border-box` so the padding does not enlarge the rendered width past the workspace
+- seed a deterministic smoke user when route guards would otherwise hide the real target screens
+- search for placeholder regressions in shared UI and restore explicit visual contracts before closeout
+- 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
+- if analytics metrics lose hierarchy, restore distinct label, value, and helper text scales with explicit typography tokens instead of leaving them on one visual level
+- if dashboard cards should share one desktop row, remove accidental full-width spans and keep one explicit grid gap contract across all analytics panels
+- if a consumer abstraction only restyles a stock MUI primitive, collapse it into a thin MUI wrapper instead of preserving a hand-built substitute
+- delete zero-value wrapper components that only rename MUI primitives or surfaces
+- delete zero-value surface wrappers that only forward to MUI `Card` or `Paper`
+- replace palette suffix hacks with `alpha()` or equivalent theme helpers
+- keep decorative gradients and shadow styling out of normal consumer surfaces; if a preview component is the exception, document it and allowlist it explicitly
+- keep root shells transparent unless they are true surfaces, so the preset background remains visible
+- wire overlay titles and descriptions through stable ids instead of relying on incidental text nodes inside dialogs or drawers
+- use labeled close controls and proper `combobox` or `listbox` semantics for search overlays with keyboard navigation
+- move browser event subscriptions into effects with cleanup before validating runtime behavior
+- add a browser screenshot or visual smoke check for the desktop shell and at least one protected content route before closing the migration
+- use stable overlay entrypoints for smoke checks instead of forcing flaky tests through incidental modal access paths
+- add an overflow assertion for the desktop content pane and at least one routed page root when shell or page-level layout containers are touched
+- add or keep a typography contract check so visible text and action labels cannot regress back to raw text nodes
+- add or keep a design-contract check when raw colors, font sizes, radius values, or opacity drift is widespread
+- after bulk replacements or encoding-sensitive edits, run a mojibake scan and verify one localized route in a real browser before closing the migration
+- extract shared workflow page shells into one layout component and use direct local imports if barrels introduce chunk-cycle warnings
+- update Workbox or PWA asset globs to match the actual emitted icon and manifest files
+- use targeted vendor chunk groups or additional lazy boundaries to resolve consumer-owned chunk warnings instead of just raising the warning limit
+
+## Example
+
+See `./AEROCRM-EXAMPLE.md` for a full `adopt-existing` migration that includes:
+
+- upgrading an existing consumer from `@atomazing-org/design-system@1.2.9` to `2.0.1`
+- replacing an outdated root import
+- fixing a startup-breaking Lingui initialization bug
+- fixing duplicate Emotion runtime loading in Vite
+- restoring a broken desktop `sidebar + content` shell after a layout wrapper regression
+- restoring page-root fill behavior after tickets and analytics screens stopped occupying the full workspace
+- fixing shared workspace overflow caused by padded full-width containers under content-box sizing
+- reworking analytics legend chips that drifted away from the preset into neutral preset-aligned legend composition
+- restoring analytics metric hierarchy and removing an accidental full-width dashboard card span so desktop analytics panels align again
+- restoring dialog, drawer, and command-palette semantics after overlay wrappers drifted
+- repairing broken Cyrillic text and mock data after encoding drift introduced unreadable strings