@atomazing-org/design-system 2.0.1 → 2.0.2

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

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

@@ -0,0 +1,377 @@
+# Shared Migration Phases
+
+Use this document as the canonical step-by-step execution checklist for future
+consumer app migrations to `@atomazing-org/design-system`.
+
+Read this after route selection and before editing the target app.
+Then combine it with:
+
+- the selected route runbook
+- the selected route `migration.spec.json`
+- `shared/common-regressions.md`
+- `shared/phase-exit-criteria.md`
+- `shared/manual-qa-matrix.md`
+- `shared/gates.md`
+- `shared/acceptance.md`
+
+## How To Use This Playbook
+
+1. Detect the route first:
+   - `greenfield`
+   - `adopt-existing`
+   - `mui4-to-latest`
+2. Build the migration plan from the phases below.
+3. Keep the app runnable at the end of each phase.
+4. Run the relevant checks before moving to the next phase.
+5. Do not merge unrelated change classes into one unvalidated batch.
+
+## Phase Map
+
+1. Route selection and scope
+2. Baseline and safety net
+3. Dependency landing
+4. Mechanical migration or provider landing
+5. Runtime startup cleanup
+6. Shared infrastructure stabilization
+7. Token, typography, and primitive cleanup
+8. Domain migration waves
+9. Final gates and closeout
+
+## Phase 1: Route Selection And Scope
+
+Goal:
+Select the correct route and define the migration boundary before code changes.
+
+Do:
+
+- inspect `package.json`, imports, theme entrypoints, and current design-system usage
+- choose the route:
+  - `mui4-to-latest` if `@material-ui/*` is present
+  - `greenfield` if the app is new and has no legacy theme or token layer
+  - `adopt-existing` otherwise
+- identify:
+  - app root and provider wiring
+  - theme state source of truth
+  - shared shell and layout containers
+  - shared overlays
+  - protected routes
+  - token modules and hardcoded visual drift
+  - repo-local gates such as style, design, or typography contract scripts
+
+Output:
+
+- selected route and why
+- initial migration scope
+- list of required validation commands
+
+Stop gate:
+
+- the route is explicit
+- the app areas at highest regression risk are named
+
+Route notes:
+
+- `greenfield`: scope is usually limited to provider wiring, app theme module, and startup safety
+- `adopt-existing`: include provider, tokens, shared shell, shared overlays, and consumer primitives
+- `mui4-to-latest`: also inventory legacy styling APIs, MUI v4 imports, and codemod impact zones
+
+## Phase 2: Baseline And Safety Net
+
+Goal:
+Capture the repo state before migration and make regressions visible early.
+
+Do:
+
+- run the repo's normal commands:
+  - `npm run lint` when present
+  - `npm test` when present
+  - `npm run build`
+- run repo-local contract gates when present:
+  - `npm run lint:style-contract`
+  - `npm run lint:design-contract`
+  - `npm run lint:typography-contract`
+- record pre-existing red checks separately from migration defects
+- add or tighten smoke coverage before broad rewrites when the app has:
+  - a shared shell
+  - protected routes
+  - shared overlays
+  - dashboards, analytics, or dense workflow screens
+
+Output:
+
+- baseline check matrix
+- known pre-existing failures
+- smoke coverage plan
+
+Stop gate:
+
+- you can tell whether a later failure is new or pre-existing
+- shell-critical or overlay-critical changes are covered by at least one route check
+
+Route notes:
+
+- `greenfield`: a simple startup check may be enough
+- `adopt-existing`: shell and at least one real content route should be covered
+- `mui4-to-latest`: add smoke coverage before codemod fallout reaches shared UI
+
+## Phase 3: Dependency Landing
+
+Goal:
+Land the dependency set needed for the target route without mixing in broad UI cleanup.
+
+Do:
+
+- update `package.json` directly
+- add or align:
+  - `@atomazing-org/design-system`
+  - `@mui/material`
+  - `@mui/icons-material` when needed
+  - `@emotion/react`
+  - `@emotion/styled`
+- remove route-incompatible packages such as `@material-ui/*`
+- install dependencies with the repo's package manager
+- if install scripts fail because of local tooling, retry with the package manager's `--ignore-scripts` equivalent only as recovery
+
+Output:
+
+- dependency set aligned with the chosen route
+- install completed
+
+Stop gate:
+
+- the repo installs successfully
+- dependency conflicts do not block the next phase
+
+Route notes:
+
+- `greenfield`: this is usually the main dependency phase
+- `adopt-existing`: keep adjacent runtime alignment small and controlled
+- `mui4-to-latest`: remove legacy Material-UI packages before broad theme unification
+
+## Phase 4: Mechanical Migration Or Provider Landing
+
+Goal:
+Reach the route-specific structural landing point before visual cleanup.
+
+Do:
+
+- `greenfield`:
+  - connect `ThemeProviderWrapper` at the app root
+  - create one explicit app theme module for preset choice when needed
+  - add theme controls only through `useThemeSettings()`
+- `adopt-existing`:
+  - connect or normalize `ThemeProviderWrapper`
+  - remove competing root theme providers
+  - replace outdated design-system imports with public APIs or local app abstractions
+  - move preset selection into one app-owned theme module
+- `mui4-to-latest`:
+  - run the official MUI codemod
+  - resolve compile breaks from the codemod
+  - replace JSS-only APIs and legacy theme APIs
+  - get the app stable on modern MUI plus Emotion before provider unification
+
+Output:
+
+- route-specific mechanical landing completed
+
+Stop gate:
+
+- the app compiles after the structural change
+- there is one clear theme-root direction
+
+## Phase 5: Runtime Startup Cleanup
+
+Goal:
+Prove the app actually boots in a browser and remove startup defects before deeper cleanup.
+
+Do:
+
+- start the app with the normal dev or start command
+- open the first route in a real browser
+- fix:
+  - browser console startup errors
+  - migration-caused startup warnings
+  - duplicate runtime singleton loading for `react`, `react-dom`, `@emotion/react`, `@emotion/styled`
+- remove module-scope code that depends on:
+  - `window`
+  - `document`
+  - `navigator`
+  - storage
+  - i18n locale activation
+- move browser listeners into effects with cleanup
+- if smoke mode bypasses auth, seed a deterministic role-bearing user for protected routes
+
+Output:
+
+- startup-clean browser boot
+
+Stop gate:
+
+- first route loads successfully
+- migration-caused startup errors are gone
+
+## Phase 6: Shared Infrastructure Stabilization
+
+Goal:
+Stabilize the app shell and shared UI contracts before domain-by-domain feature work.
+
+Do:
+
+- preserve shell layout behavior:
+  - display mode
+  - grid or flex template
+  - `min-width`
+  - `min-height`
+  - `overflow`
+  - scroll behavior
+- keep route roots and page containers filling the intended workspace
+- if shared padded containers also fill width, normalize with `box-sizing: border-box` or remove forced width
+- restore overlay semantics:
+  - stable `aria-labelledby`
+  - stable `aria-describedby`
+  - labeled close actions
+  - `combobox` and `listbox` semantics for searchable overlays
+- audit shared charts, legends, chips, metric badges, and segmented filters for preset drift
+- remove placeholder regressions and low-fidelity pass-through wrappers
+- if analytics dashboards or metric cards are touched:
+  - keep labels and values on different hierarchy levels
+  - keep one explicit grid gap contract
+  - remove accidental full-width spans that break desktop rows
+
+Output:
+
+- stable shared shell
+- stable shared overlays
+- stable shared dashboard or compact-control contracts
+
+Stop gate:
+
+- desktop and mobile shell behavior matches the intended layout
+- shared UI is usable and semantically wired
+
+## Phase 7: Token, Typography, And Primitive Cleanup
+
+Goal:
+Move the consumer toward the design-system contract instead of preserving legacy local drift.
+
+Do:
+
+- replace legacy tokens with `theme.palette`, `theme.typography`, and helpers such as `alpha()`
+- normalize visible text:
+  - `Typography`
+  - explicit semantic `variant`
+  - `Typography component="span"` for visible text inside interactive controls
+- remove zero-value wrappers:
+  - primitive wrappers
+  - surface wrappers
+- simplify decorative consumer chrome that fights the preset:
+  - gradients
+  - direct shadow styling
+  - palette alpha suffix hacks
+- if the repo needs guardrails, add or tighten:
+  - design-contract lint
+  - typography-contract lint
+- if localized copy was touched, scan for mojibake or replacement characters and verify a real localized route
+
+Output:
+
+- token and text layer aligned with the design-system contract
+
+Stop gate:
+
+- typography and design drift are reduced, not just moved around
+- the repo has enough local gates to keep the fix from regressing
+
+## Phase 8: Domain Migration Waves
+
+Goal:
+Migrate feature areas in controlled batches after shared infrastructure is stable.
+
+Do:
+
+- move feature areas one wave at a time
+- keep each wave small enough to validate independently
+- after each wave, re-run the relevant checks:
+  - smoke
+  - lint
+  - route checks
+  - build when the wave changes bundling or shared runtime behavior
+- stop if a wave reintroduces shell, overlay, typography, or token regressions
+
+Output:
+
+- migrated domains with isolated validation history
+
+Stop gate:
+
+- each wave ends in a runnable, validated state
+
+## Phase 9: Final Gates And Closeout
+
+Goal:
+Close the migration only after runtime, route, and contract checks are all green.
+
+Do:
+
+- re-run:
+  - `npm run lint`
+  - `npm test`
+  - `npm run build`
+  - `npm run test:smoke` when present
+  - repo-local contract gates when present
+- verify route-specific exit conditions:
+  - no `@material-ui/*` left for `mui4-to-latest`
+  - provider wiring and preset ownership are correct
+  - no migration-caused startup warnings remain
+- record any remaining upstream-only warnings precisely by package and file
+- write the migration summary:
+  - route used
+  - commands run
+  - startup issues fixed
+  - remaining manual QA
+  - rollback guidance if partial
+
+Output:
+
+- migration report suitable for future reuse
+
+Stop gate:
+
+- shared acceptance is satisfied
+- the app is browser-runnable, not only build-green
+
+## Recommended Phase Splits By Route
+
+`greenfield`:
+
+1. Route selection and baseline
+2. Dependency landing
+3. Provider landing
+4. Runtime startup cleanup
+5. Final gates
+
+`adopt-existing`:
+
+1. Route selection and baseline
+2. Safety net
+3. Dependency landing
+4. Provider and theme unification
+5. Runtime cleanup
+6. Shared infrastructure stabilization
+7. Token and typography cleanup
+8. Domain waves
+9. Final gates
+
+`mui4-to-latest`:
+
+1. Route selection and baseline
+2. Safety net
+3. Dependency landing
+4. Mechanical MUI migration
+5. Legacy styling cleanup
+6. Provider and theme unification
+7. Runtime cleanup
+8. Shared infrastructure stabilization
+9. Token and typography cleanup
+10. Domain waves
+11. Final gates

package/migrations/skills/design-system-consumer-agent/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: design-system-consumer-agent
+description: Rules for integrating and maintaining @atomazing-org/design-system in application repos. Use when an AI agent needs to add the library, wire it into an app, or decide whether the request should become a route-based migration.
+---
+
+# Design System Consumer Agent
+
+Use this skill whenever the task is about adopting, integrating, or maintaining
+`@atomazing-org/design-system` in an application repository.
+
+## Source Of Truth
+
+1. Read `../../docs/migrations/design-system/shared/WORKING-RULES.md`.
+2. Use `../../docs/migrations/design-system/README.md` for route selection context.
+3. If migration is needed, switch to `../design-system-migration-agent/SKILL.md`.
+
+## Default Workflow
+
+1. Inspect the target app:
+   - current dependencies
+   - current theme provider setup
+   - theme or token modules
+   - SSR or Next.js usage
+2. Apply the working rules from `WORKING-RULES.md`.
+3. Decide whether the task is:
+   - a normal integration task
+   - or a route-based migration
+
+## Escalate To Migration
+
+Escalate to the migration workflow if any of these are true:
+
+- `@material-ui/*` exists
+- the app already has a substantial theme/token system
+- the request would leave dual theme providers or dual sources of truth
+- the user asks to standardize or replace the design foundation
+- changes affect a large set of colors, typography, or component overrides
+
+When escalation is needed:
+
+1. State that route-based migration is recommended.
+2. Select the route:
+   - `mui4-to-latest`
+   - `greenfield`
+   - `adopt-existing`
+3. Load `../design-system-migration-agent/SKILL.md`.
+4. For large repos, execute the selected route phase by phase instead of batching broad edits into one pass.
+
+## Normal Integration Expectations
+
+When migration is not needed:
+
+- use public imports only
+- prefer `ThemeProviderWrapper`
+- prefer `useThemeSettings()`
+- use `defaultThemes`, `landingPageThemes`, or `allBuiltInThemes` intentionally
+- keep preset choice in one explicit app-owned theme module instead of generic constants passthrough files
+- let the active preset own the visual treatment of `Paper`, `Card`, `Dialog`, `Drawer`, and similar surfaces across the app
+- do not hand-style consumer surfaces with app-local glow, bloom, blur, decorative borders, gradient washes, or pseudo-element chrome; those belong in presets/theme overrides
+- keep app styling focused on layout, spacing, sizing, and content hierarchy
+- if the app shell exposes a dedicated workspace or content pane, keep route roots and page containers stretched to fill it instead of shrinking to intrinsic content width
+- for landing and marketing surfaces, prefer MUI-native preview composition over custom decorative UI logic
+- do not hand-style landing surfaces with app-local glow, bloom, blur, decorative borders, gradient washes, or pseudo-element chrome; those belong in presets/theme overrides
+- do not build nested rectangular surface hierarchies such as `card inside card inside card`
+- keep one primary surface per logical block and use `Stack`, `List`, `Divider`, `Typography`, `Chip`, and `Avatar` before introducing another bordered layer
+- keep landing preview blocks spacious and reduce content before compressing spacing
+- remove zero-value wrappers that only rename MUI primitives or surfaces
+- do not leave 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
+- if multiple role pages share the same shell, extract a shared workflow layout before changing visuals independently
+- if a local barrel creates chunk-cycle warnings, prefer direct local imports for the affected workflow internals
+- fix consumer-owned build warnings such as stale PWA asset globs or oversized local chunks instead of silencing them
+- if a remaining warning belongs to an upstream toolchain package, record it precisely as external debt
+- keep visible text on `Typography` with explicit semantic variants instead of raw JSX text nodes
+- when buttons, chips, alerts, menu items, or toggle buttons show text, wrap that label in `Typography component="span"`
+- keep compact legends, chips, segmented filters, and metric badges visually aligned with the active preset instead of restyling them into ad hoc chip-like chrome
+- when shared dialogs, drawers, or bottom sheets are touched, keep stable `aria-labelledby` and `aria-describedby` wiring plus labeled close actions
+- when an overlay owns filtered keyboard navigation, use `combobox` and `listbox` semantics instead of generic wrapper markup
+- keep browser event listeners such as `beforeinstallprompt` or `matchMedia` subscriptions inside effects with cleanup
+- remove zero-value surface wrappers that only forward to MUI `Card` or `Paper`
+- use `alpha()` or equivalent theme helpers instead of palette-string alpha suffix hacks
+- treat decorative gradients and shadow styling as migration defects unless the component is an explicit preview exception documented in the repo-local design-contract gate
+- keep browser-only APIs out of module scope
+- after dependency or provider wiring changes, start the app and verify the first route boots without browser console startup errors
+- if bulk rewrites or localized copy changes were part of the work, keep files in UTF-8, scan for mojibake or replacement characters, and verify readable text on a real route