@atomazing-org/design-system 1.2.9 → 2.0.2

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

@@ -0,0 +1,109 @@
+{
+  "$schema": "../../schema/migration.spec.schema.json",
+  "id": "adopt-existing",
+  "title": "Adopt @atomazing-org/design-system in an existing modern MUI project",
+  "detect": {
+    "packageJson": {
+      "anyDependencies": ["@mui/material"]
+    }
+  },
+  "entryConditions": [
+    "the project already uses @mui/material",
+    "the migration is normalizing an existing app instead of bootstrapping a new one"
+  ],
+  "exitConditions": [
+    "ThemeProviderWrapper is connected at the app root",
+    "forbidden token imports and outdated design-system imports are removed",
+    "the app boots without browser console startup errors",
+    "migration-caused startup warnings are fixed",
+    "tests and build are green"
+  ],
+  "steps": [
+    {
+      "name": "Inventory and baseline",
+      "run": ["npm test", "npm run build"],
+      "manualReview": [
+        "Map current design-system usage, theme entrypoints, local token modules, shared shell code, shared overlays, and protected routes.",
+        "Record pre-existing failing checks separately from migration defects.",
+        "Split the repo into shared-infrastructure scope and domain migration waves before broad edits begin."
+      ]
+    },
+    {
+      "name": "Add safety net",
+      "manualReview": [
+        "Add or tighten smoke coverage for the application shell before broad refactors.",
+        "If route guards exist, ensure at least one protected content route can be validated as a real screen.",
+        "If shared overlays will be touched, add at least one stable overlay interaction to smoke coverage."
+      ]
+    },
+    {
+      "name": "Add design-system deps",
+      "run": [
+        "node migrations/scripts/migrations/design-system/actions/update-package-json.mjs --add @atomazing-org/design-system:<SET_VERSION>"
+      ]
+    },
+    {
+      "name": "Install deps",
+      "run": ["npm install"]
+    },
+    {
+      "name": "Root theme unification",
+      "manualReview": [
+        "Connect ThemeProviderWrapper at the application root.",
+        "Remove or collapse any competing root ThemeProvider so the design system becomes the single theme source of truth.",
+        "Replace outdated or removed design-system root imports with the correct public API or local app abstractions.",
+        "Move preset selection into one explicit app-level theme module instead of leaving it scattered across generic constants layers."
+      ]
+    },
+    {
+      "name": "Runtime boot cleanup",
+      "manualReview": [
+        "Start the app with the repo's normal dev/start command and open the first route in a real browser.",
+        "Fix startup console errors before continuing.",
+        "Fix migration-caused startup warnings before continuing, especially duplicate runtime singleton warnings for react, react-dom, @emotion/react, and @emotion/styled.",
+        "Remove module-scope code that requires browser APIs, storage, or i18n locale activation.",
+        "Move browser event listeners into effects with cleanup instead of render paths or module scope.",
+        "If smoke mode disables auth redirect, seed a deterministic role-bearing user so protected routes can render real content."
+      ]
+    },
+    {
+      "name": "Shared infrastructure stabilization",
+      "manualReview": [
+        "Stabilize the application shell, route wrappers, and shared layout containers before domain-by-domain work.",
+        "Restore dialog, drawer, bottom-sheet, and search-overlay semantics before broad feature cleanup.",
+        "Preserve display, grid or flex templates, min-width, min-height, overflow, and scroll behavior when refactoring shell containers.",
+        "If shell workspaces, route wrappers, or page roots were touched, verify the main content still fills the available content region and that dashboard or workflow grids did not collapse into partial-width stacks.",
+        "Audit compact shared UI such as chart legends, chips, segmented filters, and metric badges for preset drift; replace ad hoc chip-like chrome with neutral MUI composition when needed.",
+        "Search for placeholder regressions in shared UI and restore explicit visual contracts before closeout."
+      ]
+    },
+    {
+      "name": "Token and primitive cleanup",
+      "manualReview": [
+        "Fill token-gate.config.json for the target project.",
+        "Prepare CSV or targeted replacements for legacy tokens and review the diff file by file.",
+        "Normalize visible text to Typography with explicit semantic variants.",
+        "Remove zero-value wrapper components and zero-value surface wrappers.",
+        "Replace palette alpha suffix hacks with alpha() and simplify decorative consumer surface chrome.",
+        "If bulk replacements or file rewrites touched localized copy, scan for mojibake or replacement characters and verify non-Latin UI text still renders readable strings."
+      ]
+    },
+    {
+      "name": "Domain migration waves",
+      "manualReview": [
+        "Migrate feature areas in waves after shared infrastructure is stable.",
+        "Keep each wave small enough to validate independently.",
+        "Re-run the relevant smoke or route checks after each wave before moving to the next domain."
+      ]
+    },
+    {
+      "name": "Quality gates",
+      "run": [
+        "node migrations/scripts/migrations/design-system/gates/no-hardcoded-tokens.mjs --root src --config migrations/scripts/migrations/design-system/shared/token-gate.config.json",
+        "npm run lint",
+        "npm test",
+        "npm run build"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,61 @@
+# Route: greenfield
+
+Use this route when the target app is new and does not need a legacy theme or
+token migration before adopting `@atomazing-org/design-system`.
+
+## Use This Route When
+
+- the project is new or lightly scaffolded
+- there is no inherited token layer to normalize
+- there is no legacy MUI v4 migration path to perform first
+
+## Target Outcome
+
+- `ThemeProviderWrapper` is connected at the app root
+- preset choice lives in one explicit app-level theme module when the app exposes multiple presets
+- theme switching, if added, uses `useThemeSettings()`
+- the app boots cleanly with the new provider wiring
+
+Use `../../shared/phases.md` as the canonical step-by-step phase checklist, then
+apply the route-specific requirements below.
+
+## Required Workflow (Phases)
+
+1. Baseline the repo
+   - confirm the repo installs and the normal validation commands can run
+   - record any pre-existing setup failures separately from integration defects
+2. Add dependencies
+   - add `@atomazing-org/design-system`
+   - add `@mui/material`, `@mui/icons-material`, `@emotion/react`, and `@emotion/styled` when the scaffold does not already include them
+3. Connect the root provider
+   - wrap the app root with `ThemeProviderWrapper`
+   - do not add a competing root `ThemeProvider`
+   - if the app will expose multiple presets, keep selection in one explicit app-level theme module
+4. Add optional theme controls
+   - if the app needs theme switching or dark-mode controls, wire them through `useThemeSettings()`
+   - keep UI labels and visible text aligned with the typography contract from the start
+5. Runtime-safe integration
+   - if the app uses SSR or Next.js, keep provider wiring inside a client boundary
+   - keep browser-only APIs out of module scope
+   - start the app and verify the first route boots cleanly in a real browser
+   - if the app shell exposes a dedicated workspace or content pane, verify the first route root actually fills that region instead of shrinking to intrinsic content width
+   - if the app ships non-Latin copy or seeds localized mocks, keep files in UTF-8 and verify the first route does not render mojibake or replacement characters
+6. Run quality gates
+   - run the repo's validation commands
+   - verify build, tests, and runtime startup are clean before closeout
+
+## Common Failure Modes
+
+- adding `ThemeProviderWrapper` while leaving a second competing root theme provider in place
+- keeping preset choice scattered across constants passthrough files instead of one app theme module
+- adding browser-only logic at module scope during initial provider setup
+- first-route page roots or layout containers not stretching to fill the intended workspace
+- localized starter copy or mock data landing in the repo with mojibake because file encoding was not validated
+- declaring greenfield success on build output alone without an actual browser startup check
+
+## Shared Gates
+
+Use common gate definitions from:
+
+- `../../shared/gates.md`
+- `../../shared/acceptance.md`

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

@@ -0,0 +1,58 @@
+{
+  "$schema": "../../schema/migration.spec.schema.json",
+  "id": "greenfield",
+  "title": "Greenfield install of @atomazing-org/design-system",
+  "detect": {
+    "packageJson": {
+      "allDependencies": []
+    }
+  },
+  "entryConditions": ["package.json exists"],
+  "exitConditions": [
+    "ThemeProviderWrapper is connected at the app root",
+    "the app boots cleanly on the first route",
+    "tests and build are green"
+  ],
+  "steps": [
+    {
+      "name": "Baseline",
+      "manualReview": [
+        "Confirm the repo installs and the normal validation commands can run.",
+        "Record any pre-existing setup failures separately from integration defects."
+      ]
+    },
+    {
+      "name": "Add deps",
+      "run": [
+        "node migrations/scripts/migrations/design-system/actions/update-package-json.mjs --add @atomazing-org/design-system:<SET_VERSION> --add @mui/material:^7 --add @mui/icons-material:^7 --add @emotion/react:^11 --add @emotion/styled:^11"
+      ]
+    },
+    {
+      "name": "Install deps",
+      "run": ["npm install"]
+    },
+    {
+      "name": "Manual integration",
+      "manualReview": [
+        "Connect ThemeProviderWrapper at the application root.",
+        "If the app exposes multiple presets, keep selection in one explicit app-level theme module.",
+        "If Next.js or another SSR framework is in use, ensure the provider lives in a client boundary."
+      ]
+    },
+    {
+      "name": "Runtime boot verification",
+      "manualReview": [
+        "Start the app with the repo's normal dev/start command and open the first route in a real browser.",
+        "Fix startup console errors before closeout.",
+        "Keep browser-only APIs out of module scope during initial provider integration.",
+        "If the app shell exposes a dedicated workspace or content pane, verify the first route root fills that region instead of shrinking to intrinsic content width.",
+        "If the app ships non-Latin copy or localized mocks, scan for mojibake or replacement characters and verify readable text on the first route."
+      ]
+    },
+    {
+      "name": "Quality",
+      "run": ["npm run lint", "npm test", "npm run build"]
+    }
+  ],
+  "gates": ["lint", "tests", "build"]
+}

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

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

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

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

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

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

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

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

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

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