@atomazing-org/design-system 2.0.1 → 3.7.2

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

@@ -1,27 +1,83 @@
-# Общие критерии готовности (Acceptance Criteria)
+# Shared Acceptance Criteria
 
-Миграция считается завершённой, когда:
+A migration is complete only when all of the following are true.
 
-## 1) Зависимости
-- В проекте присутствует `@atomazing-org/design-system`.
-- Для MUI присутствуют совместимые версии `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`.
+## 0. Execution Discipline
 
-## 2) Источник истины для темы
-- Корень приложения обёрнут в `ThemeProviderWrapper`.
-- Нет второго конкурентного `ThemeProvider` (если он не нужен как thin-wrapper вокруг DS).
+- The route was executed in phases, not as one giant unvalidated diff.
+- The app remained runnable at the end of each committed phase.
+- If the project is large and broad shell, overlay, or shared-component rewrites were in scope, a smoke safety net existed before those rewrites began.
 
-## 3) Отсутствие legacy MUI v4
-- В `package.json` отсутствуют `@material-ui/*`.
-- В коде отсутствуют импорты из `@material-ui/*`.
+## 1. Dependencies
 
-## 4) Токены
-- Нет прямых импортов/использований устаревших token-файлов (список определяется маршрутом).
-- Основные UI-поверхности (фон/текст/бордеры/основные кнопки) используют `theme.palette`.
-- Основные тексты используют `Typography` variants (или `theme.typography`).
+- The repo installs `@atomazing-org/design-system`.
+- Compatible peer runtimes are present for `@mui/material`, `@mui/icons-material` when needed, `@emotion/react`, and `@emotion/styled`.
 
-## 5) Качество
-- `npm test` проходит.
-- `npm run build` проходит.
-- Quality gates проходят (через `migrations/scripts/*` или эквивалентные ручные проверки поиска по коду/импортам).
+## 2. Theme Source Of Truth
 
-
+- The app root is wrapped with `ThemeProviderWrapper` or an approved thin wrapper around it.
+- There is no second competing root `ThemeProvider`.
+- Theme selection and dark-mode state do not live in a parallel app-specific source of truth unless it only mirrors design-system state.
+- Preset selection is exposed through one explicit app-level theme module, not hidden across generic constants passthrough files.
+
+## 3. Legacy MUI Removal
+
+- `package.json` does not contain `@material-ui/*`.
+- App source does not import `@material-ui/*`.
+
+## 4. Token Adoption
+
+- Forbidden legacy token imports and identifiers for the selected route are removed.
+- Main UI surfaces use `theme.palette` instead of hardcoded project token files.
+- Main typography uses MUI variants or `theme.typography`.
+- Visible app text is rendered through `Typography` or approved text-owning MUI APIs, not as raw JSX text in layout wrappers.
+- Every `Typography` used by the consumer declares an explicit `variant`.
+- Interactive labels rendered through `Button`, `ToggleButton`, `MenuItem`, `Chip`, or `Alert` use `Typography component="span"` with an explicit variant when they render visible text.
+- Zero-value wrapper components that merely rename stock MUI primitives or surfaces are removed or collapsed into thin MUI wrappers with real behavior.
+- Zero-value surface wrappers that merely forward to MUI `Card`, `Paper`, or similar components are removed.
+- Large inline `sx` objects are not left in migrated consumer components; substantial styling is extracted into local `styled(...)` components declared in the same file near the bottom.
+- Consumer styling does not rely on decorative gradients, direct shadow styling, or palette alpha suffix hacks in normal app surfaces.
+- If the app keeps a preview-only exception such as a theme swatch, that exception is documented and allowlisted explicitly in the repo-local design-contract gate.
+
+## 5. Runtime Startup Health
+
+- The app starts with the repo's normal dev or start command.
+- The first route opens successfully in a real browser.
+- Browser console startup errors are fixed before closeout.
+- Startup warnings caused by the migration are fixed before closeout, not merely recorded.
+- Duplicate runtime singleton warnings for `react`, `react-dom`, `@emotion/react`, or `@emotion/styled` are resolved with bundler or runtime alignment.
+- Module-scope code does not depend on browser APIs, storage, or i18n locale activation before app initialization.
+- Core application shell layout is preserved after migration.
+- On desktop layouts, structural regions such as sidebar or menu stay in their intended column and page content stays in its own content region.
+- On mobile layouts, stacked navigation and scroll containers still behave as before.
+- Route roots and primary page containers still fill the intended workspace or content pane; the migration does not leave partial-width page shells, collapsed dashboards, or unused work areas.
+- Shared padded containers such as app-owned cards, page roots, and shell content panes do not overflow horizontally because of `width: 100%` under content-box sizing.
+- The application background is still owned by the active preset; root shells and page wrappers do not hardcode a competing page-level background over it.
+- Shared UI primitives do not regress into placeholder wrappers or empty visual shells; cards, dialogs, drawers, charts, filters, and nav controls still render usable spacing, hierarchy, and interaction states.
+- Shared legends, compact filters, chips, segmented controls, and metric badges remain visually aligned with the active preset; the migration does not replace them with ad hoc chip chrome that fights the preset.
+- Analytics dashboards and metric surfaces keep a clear typographic split between labels and values, and dashboard cards do not drift into accidental full-width spans or mismatched gap patterns on desktop layouts.
+- Shared base primitives that map directly to MUI are implemented with MUI components or thin wrappers around them, not hand-rolled substitutes built from generic nodes.
+- Shared overlays rendered as dialogs, drawers, or bottom sheets expose stable `aria-labelledby` and `aria-describedby` semantics.
+- Shared overlay close actions are labeled, and decorative handles or chrome are hidden from assistive technology when they carry no state.
+- Search overlays that own keyboard-filtered results expose `combobox` and `listbox` semantics instead of generic wrapper markup.
+- Browser event listeners introduced or touched during migration are registered in effects with cleanup rather than render paths or module scope.
+- If smoke or test mode disables auth redirect, the migration provides a deterministic role-bearing user so protected routes can be validated as real screens instead of fallback routes.
+- Automated route checks validate at least one protected content page in addition to shell boot.
+- Automated route checks validate at least one stable overlay interaction when the migration touches shared overlay infrastructure.
+- Touched localized copy, fixtures, and mocks render readable text; the migration does not leave mojibake, replacement characters, or broken non-Latin strings in the shipped UI or smoke-visible test data.
+- Repeated workflow pages that share the same structural shell use a shared layout contract instead of duplicating the page shell across roles.
+- The migration does not leave new circular chunk warnings from local app barrel re-exports when direct local imports are the safer option.
+
+## 6. Quality Gates
+
+- `npm test` passes when the repo has tests.
+- `npm run build` passes.
+- `npm run lint` passes when it is part of the repo's normal gate. If baseline lint is already red for unrelated files, record that baseline explicitly and keep the migration diff green.
+- `npm run test:smoke` or the repo's equivalent smoke or e2e route gate passes when the repo provides that check for shell, protected routes, overlays, or other runtime-critical flows touched by the migration.
+- `npm run lint:style-contract` passes when the repo provides a local style-contract or styleless-UI gate.
+- `npm run lint:design-contract` passes when the repo provides a design-token or design-contract check.
+- `npm run lint:design-contract` catches decorative gradient or shadow drift, palette alpha suffix hacks, and unapproved visual-token exceptions when the repo provides that gate.
+- `npm run lint:typography-contract` passes when the repo provides a typography contract check.
+- Consumer-owned build warnings caused by asset config drift or oversized local chunks are fixed rather than silenced.
+- If a remaining build warning comes from an upstream third-party toolchain package, the migration report names that package and warning explicitly.
+- Route-specific and shared migration gates pass through scripts or equivalent manual checks.

package/migrations/docs/migrations/design-system/shared/common-regressions.md

@@ -0,0 +1,218 @@
+# Common Migration Regressions
+
+Use this document as a fast lookup when a migrated consumer app "builds fine"
+but still looks or behaves wrong at runtime.
+
+For each regression class below:
+
+- confirm the symptom on a real route
+- fix the structural cause, not only the visible symptom
+- add or tighten smoke or lint coverage when the regression is likely to return
+
+## Startup Crash On First Route
+
+Symptom:
+
+- app opens to a blank page, hard crash, or startup error in the browser console
+
+Common causes:
+
+- module-scope i18n work before locale activation
+- module-scope `window`, `document`, `navigator`, or storage access
+- broken root provider wiring
+
+Fix:
+
+- move browser-only or locale-dependent work into runtime-safe component or hook code
+- verify the root uses the intended provider stack
+
+Catch it with:
+
+- real browser startup check
+- smoke route that fails on console or page errors
+
+## Duplicate React Or Emotion Runtime
+
+Symptom:
+
+- startup warning about duplicated `react`, `react-dom`, `@emotion/react`, or `@emotion/styled`
+
+Common causes:
+
+- bundler dedupe or singleton-sharing not aligned after migration
+
+Fix:
+
+- align bundler runtime resolution with dedupe, aliasing, or singleton-sharing
+
+Catch it with:
+
+- browser startup check
+- migration closeout report that records warnings by exact package
+
+## Workspace Does Not Fill The Content Region
+
+Symptom:
+
+- page content collapses into partial-width cards
+- dashboard or form area leaves empty workspace
+
+Common causes:
+
+- route roots or page containers lost flex growth, `min-width`, or `min-height`
+
+Fix:
+
+- restore the shared shell and page-root layout contract
+
+Catch it with:
+
+- shell smoke check on a real content route
+
+## Right Edge Overflow On Desktop
+
+Symptom:
+
+- content protrudes past the visible right edge
+- horizontal scrolling appears unexpectedly
+
+Common causes:
+
+- `width: 100%` plus internal padding under content-box sizing
+- shell content panes or page roots forced wider than the workspace
+
+Fix:
+
+- use `box-sizing: border-box` on shared padded full-width containers
+- remove forced width where it is not needed
+
+Catch it with:
+
+- overflow assertion on the shared content pane
+- overflow assertion on at least one routed page root
+
+## Dashboard Metrics Lose Hierarchy
+
+Symptom:
+
+- metric labels, values, and helper text read like one text level
+- numbers no longer stand out from titles
+
+Common causes:
+
+- label and value typography share the same effective size and weight
+- broad card cleanup flattened the text hierarchy
+
+Fix:
+
+- restore distinct label, value, and helper text scales
+- keep metric emphasis explicit instead of relying on defaults
+
+Catch it with:
+
+- smoke assertion on computed metric label vs value emphasis
+- visual QA on analytics or dashboard routes
+
+## Dashboard Card Falls Into Full-Width Row
+
+Symptom:
+
+- one analytics or dashboard card drops onto its own row on desktop
+- gaps between dashboard cards become inconsistent
+
+Common causes:
+
+- stale `gridColumn: 1 / -1`
+- mixed grid gap contracts between dashboard panels
+
+Fix:
+
+- remove accidental full-width spans
+- keep one explicit grid template and gap rhythm per dashboard surface
+
+Catch it with:
+
+- smoke assertion on desktop card alignment
+
+## Overlay Semantics Drift
+
+Symptom:
+
+- dialog or drawer still opens, but labels, descriptions, or close controls are wrong or missing
+
+Common causes:
+
+- wrapper refactor dropped stable ids
+- decorative overlay chrome was left visible to assistive tech
+- searchable overlay uses generic markup instead of `combobox` or `listbox`
+
+Fix:
+
+- restore stable `aria-labelledby` and `aria-describedby`
+- label close actions
+- restore proper overlay search semantics
+
+Catch it with:
+
+- smoke coverage through stable overlay entrypoints
+
+## Compact Controls Drift Away From The Preset
+
+Symptom:
+
+- legends, chips, segmented filters, or compact badges look like app-local chrome instead of preset-aligned UI
+
+Common causes:
+
+- consumer restyling replaced neutral shared composition with ad hoc chip-like surfaces
+
+Fix:
+
+- rebuild compact controls from neutral MUI composition such as `Stack`, markers, and `Typography`
+
+Catch it with:
+
+- visual QA on charts, segmented controls, and compact summary areas
+
+## Mojibake Or Broken Non-Latin Text
+
+Symptom:
+
+- Cyrillic or other non-Latin copy renders as broken symbols or replacement characters
+
+Common causes:
+
+- encoding-sensitive rewrites
+- bulk replacements across localized files
+
+Fix:
+
+- keep touched files in UTF-8
+- restore corrupted copy from a valid source
+
+Catch it with:
+
+- mojibake scan
+- real-route verification of localized text
+
+## Consumer Build Warning Left Unowned
+
+Symptom:
+
+- build stays noisy and nobody knows whether the app or an upstream package owns the warning
+
+Common causes:
+
+- stale asset globs
+- oversized local chunks
+- local barrel import cycles
+- upstream toolchain warning misclassified as app debt
+
+Fix:
+
+- fix consumer-owned warnings in the app
+- record upstream-only warnings by exact package and file
+
+Catch it with:
+
+- final build review during closeout

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

@@ -13,18 +13,54 @@ npm test
 npm run build
 ```
 
+If the target repo exposes repo-local contract gates such as
+`npm run lint:style-contract`, `npm run lint:design-contract`, or
+`npm run lint:typography-contract`, run them as part of the migration.
+
+If the target repo exposes smoke or e2e coverage for shell, protected routes,
+or overlays such as `npm run test:smoke`, run that as part of the migration too.
+
+Also run the repo's normal dev or start command and open the app in a real browser.
+
+## Phase gates for large projects
+
+For large migrations, do not wait until the end of the route to validate.
+
+- Re-run the relevant checks after each meaningful phase.
+- Keep the app runnable at the end of every phase before moving to the next one.
+- At minimum, re-run the repo's typecheck or lint-equivalent after broad mechanical edits and re-run build after dependency or bundler changes.
+- Before broad shell, overlay, or shared-component rewrites, make sure smoke coverage exists 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
+  - at least one content-dense route such as a dashboard, analytics page, or workflow screen when shared charts, filters, or page-level layout containers are in scope
+- Do not continue to the next phase when the current phase introduced startup console errors or route-blocking runtime warnings.
+
 ## 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).
+- The app reaches the v2 target state (MUI v7 plus design-system v2 contract).
+- The app boots on the first route after migration.
+- Browser console startup errors are fixed before closeout.
+- Startup warnings introduced or exposed by the migration are fixed before closeout when they indicate broken runtime alignment.
+- If the repo provides smoke or e2e checks for shell, protected routes, overlays, or other runtime-critical flows touched by the migration, those checks pass before closeout.
+- If the repo provides a local style-contract or styleless-UI gate, keep that gate green during the migration.
+- If the app reports duplicated runtime singleton warnings (`react`, `react-dom`, `@emotion/react`, `@emotion/styled`), fix bundler or runtime alignment with dedupe, aliasing, or the repo's equivalent singleton-sharing mechanism.
+- The migration does not introduce local barrel-based chunk cycle warnings when direct app-local imports resolve them.
+- Consumer-owned build warnings from stale asset globs or oversized local chunks are fixed before closeout.
+- If shell workspaces or page-root containers were touched, verify the main content still fills the content region and that page grids did not collapse into partial-width stacks.
+- If shell workspaces, shared cards, or page-root containers were touched, verify shared padded containers do not overflow horizontally because of `width: 100%` plus content-box sizing.
+- If shared charts, legends, chips, segmented filters, or compact badges were touched, verify compact controls remain preset-aligned instead of drifting into ad hoc chip-like chrome.
+- If analytics dashboards, metric cards, or dashboard grids were touched, verify labels and values still read as different hierarchy levels and desktop cards do not accidentally fall into full-width or broken-row spans.
+- If bulk replacements or localized non-Latin copy were touched, scan for mojibake or replacement characters and verify readable text on at least one real route.
 
 ## 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:
+- `adopt-existing` or `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)
@@ -32,4 +68,4 @@ npm run build
 ## 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.
+- Real app dry-runs can be deferred in this repo backlog flow (`docs/spec-first`) and executed later in app repos or optional closeout.

package/migrations/docs/migrations/design-system/shared/manual-qa-matrix.md

@@ -0,0 +1,70 @@
+# Manual QA Matrix
+
+Use this matrix after automated gates pass.
+
+Skip rows that are clearly out of scope for the target app, but do not skip a row
+just because build and lint are green.
+
+## Startup And Runtime
+
+- Open the first route and confirm there are no startup console errors.
+- Confirm any migration-caused warnings were removed, not just recorded.
+- If the app uses non-Latin text, verify at least one real localized route renders readable copy.
+
+## Shell And Layout
+
+- Desktop:
+  - sidebar or navigation stays in its intended column
+  - content stays inside the visible workspace
+  - routed page roots fill the content pane
+- Mobile:
+  - stacked shell still behaves correctly
+  - scroll containers and navigation still feel normal
+
+## Theme And Preset Ownership
+
+- Verify the active preset still owns the page background.
+- Verify root shells and page wrappers do not paint a competing page-level background.
+- If the app exposes multiple presets or theme switching, verify the selection still works from the intended app theme module.
+
+## Protected Routes
+
+- Verify at least one protected route as real product content, not a fallback page.
+- If smoke mode or QA mode bypasses auth redirect, verify the seeded user still has the required roles.
+
+## Overlays
+
+- Dialogs, drawers, and bottom sheets:
+  - open correctly
+  - expose the expected title and description
+  - have labeled close actions
+- Search overlays:
+  - keyboard filtering still works
+  - combobox or listbox semantics still match the behavior
+
+## Dashboards And Dense Screens
+
+- Metric cards:
+  - labels are visually quieter than values
+  - values remain the primary reading target
+  - helper text does not compete with the metric
+- Dashboard grids:
+  - cards align on desktop as intended
+  - no accidental full-width spans appear
+  - gap rhythm is consistent
+- Compact legends, badges, and segmented filters:
+  - still look preset-aligned
+  - do not drift into app-local chip chrome
+
+## Forms And Workflow Screens
+
+- Shared workflow layouts still align correctly across the related pages.
+- Inputs, labels, helper text, and errors still render through the intended MUI or Typography contract.
+- Clear buttons, adornments, drawers, and form overlays still behave correctly after primitive cleanup.
+
+## Build And Asset Hygiene
+
+- If the app uses PWA or Workbox, verify referenced static assets actually exist in the emitted app.
+- If build output still warns, confirm whether the warning is:
+  - consumer-owned and must be fixed
+  - or upstream-only and should be recorded precisely

package/migrations/docs/migrations/design-system/shared/phase-exit-criteria.md

@@ -0,0 +1,129 @@
+# Phase Exit Criteria
+
+Use this document with `shared/phases.md`.
+
+Do not move to the next migration phase until the current phase satisfies its
+exit criteria.
+
+## Phase 1: Route Selection And Scope
+
+Exit when:
+
+- the route is explicit
+- the app root, theme source, shell, overlays, and protected routes are identified
+- required validation commands are listed
+
+Do not proceed if:
+
+- route choice is still ambiguous
+- the migration boundary is undefined
+
+## Phase 2: Baseline And Safety Net
+
+Exit when:
+
+- baseline lint, test, and build state is recorded
+- pre-existing failures are separated from migration failures
+- shell or route smoke coverage exists when broad shared rewrites are planned
+
+Do not proceed if:
+
+- you cannot distinguish old failures from new ones
+- broad shell or overlay changes would be untested
+
+## Phase 3: Dependency Landing
+
+Exit when:
+
+- dependency changes install successfully
+- route-incompatible packages are removed or isolated
+- dependency conflicts are not blocking compile or startup work
+
+Do not proceed if:
+
+- install is still broken
+- dependency state is half-migrated and unstable
+
+## Phase 4: Mechanical Migration Or Provider Landing
+
+Exit when:
+
+- the route-specific mechanical landing is complete
+- the app compiles after the structural change
+- the theme-root direction is clear and not duplicated
+
+Do not proceed if:
+
+- competing root providers still exist
+- codemod or provider landing left the app uncompilable
+
+## Phase 5: Runtime Startup Cleanup
+
+Exit when:
+
+- the first route opens in a real browser
+- startup console errors are fixed
+- migration-caused startup warnings are fixed
+- protected routes can render real content when they are in scope
+
+Do not proceed if:
+
+- the app is only build-green but not browser-runnable
+- duplicate runtime warnings still remain unresolved
+
+## Phase 6: Shared Infrastructure Stabilization
+
+Exit when:
+
+- desktop and mobile shell layout behaves as intended
+- page roots still fill the workspace
+- shared padded containers do not overflow horizontally
+- overlays keep stable semantics
+- shared dashboards or compact controls do not show preset drift
+
+Do not proceed if:
+
+- the shell still has layout regressions
+- shared dashboards, overlays, or route roots are visually or semantically broken
+
+## Phase 7: Token, Typography, And Primitive Cleanup
+
+Exit when:
+
+- visible text uses `Typography` with explicit variants
+- zero-value primitive and surface wrappers are removed or collapsed
+- token drift is reduced through `theme.*` usage and helpers
+- localized copy remains readable if touched
+
+Do not proceed if:
+
+- raw text nodes, variantless typography, or visual-token drift are still spreading
+- decorative consumer chrome is still replacing preset-owned surface behavior
+
+## Phase 8: Domain Migration Waves
+
+Exit when:
+
+- the current feature wave is validated independently
+- route-specific smoke or lint checks are green again
+- the app remains runnable before the next feature wave starts
+
+Do not proceed if:
+
+- the current wave reintroduced shared regressions
+- multiple unfinished feature waves are open at once
+
+## Phase 9: Final Gates And Closeout
+
+Exit when:
+
+- shared gates and route-specific exit conditions are satisfied
+- lint, build, tests, and smoke gates are green when available
+- remaining warnings are either fixed or recorded as upstream-only by exact package
+- manual QA follow-up is documented
+
+Do not close the migration if:
+
+- runtime startup still depends on manual excuses
+- unresolved warnings are consumer-owned
+- the app is not verified on a real route in a browser