@atomazing-org/design-system 2.0.1 → 2.0.2

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: `header_*`
+  - main body copy and helper text: `text_*_regular`
+  - button and action labels: compact semibold text such as `text_sm_semibold`
+  - chip, badge, and compact status labels: compact text such as `text_xs_semibold`
+- 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.`

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