@atomazing-org/design-system 1.2.8 → 2.0.1

package/README.MD

@@ -24,18 +24,26 @@ Install the library:
 npm install @atomazing-org/design-system
 ```
 
-Install required peer dependencies (MUI v7 + Emotion):
+Install required peer dependencies (React 18/19 + MUI v7 + Emotion core):
 
 ```bash
-npm install @mui/material @mui/icons-material @emotion/react @emotion/styled
+npm install react react-dom @mui/material @emotion/react @emotion/styled
 ```
 
-Optional (only if your project uses Emotion `css` helpers):
+Optional peers:
+
+- `@mui/icons-material` (only if your app imports MUI icons)
+- `@emotion/css` (only if your project uses Emotion `css` helpers)
 
 ```bash
-npm install @emotion/css
+npm install @mui/icons-material @emotion/css
 ```
 
+### Package format (v2)
+
+`@atomazing-org/design-system` v2 is **ESM-only**.
+Use ESM imports (`import ... from ...`). CommonJS `require()` is not supported.
+
 ---
 
 ## Quick start
@@ -125,11 +133,6 @@ Dark mode switches the active **scheme** inside the current preset.
 
 It’s the most common UX: the app automatically follows the user’s OS preference without custom code in every project.
 
-### What about `auto`?
-
-`auto` is a **legacy alias** of `system` kept for backward compatibility (e.g., older stored settings).  
-Recommendation: show **System** in UI, but accept `auto` as input and normalize it to `system`.
-
 Example selector:
 
 ```tsx
@@ -170,6 +173,34 @@ Note: when `darkMode` is set, `darkMode` is locked and `setDarkMode` is ignored.
 
 ---
 
+## Persistence (`appSettings`)
+
+Theme selection is persisted in `localStorage` under the key `appSettings`.
+
+v2 JSON shape:
+
+```json
+{ "themeId": "editorial-classic", "darkMode": "system" }
+```
+
+Notes:
+- v2 stores only `themeId` and `darkMode`.
+- v2 does not migrate legacy stored formats (`theme`, `version`, `auto`); invalid/legacy payloads reset to defaults.
+
+---
+
+## App migration routes (repo docs)
+
+If you are migrating an app to v2, use the route runbooks under:
+
+- `migrations/docs/migrations/design-system/README.md`
+- `migrations/docs/migrations/design-system/routes/*`
+
+`examples/react-app` is the canonical Vite consumer smoke app for local v2 validation (`npm run smoke:react-app`).
+`examples/next-app-router` is the canonical Next.js App Router SSR reference consumer (`npm run smoke:next`).
+
+---
+
 ## Custom themes
 
 Provide your own preset(s) to the provider. A preset is one identifiable theme with **two schemes**: `light` and `dark`.
@@ -314,7 +345,8 @@ From the repository root:
 pnpm lint
 pnpm build
 pnpm test
-pnpm -C examples/repro dev
+pnpm -C examples/react-app dev
+pnpm -C examples/next-app-router dev
 ```
 
 ---
@@ -351,24 +383,27 @@ Make sure your app installs these (MUI v7 + Emotion):
 - Create a `ThemePreset` with `colorSchemes.light` and `colorSchemes.dark`.
 - Combine with defaults: `const themes = [...defaultThemes, myPreset];`
 
-## Examples (examples/repro)
+## Examples (`examples/react-app`, `examples/next-app-router`)
 
-The repo includes a runnable example app that demonstrates:
+The repo includes runnable example apps that demonstrate:
 - preset switching
 - dark mode switching
 - background + card surfaces changing correctly
 - token/debug view (if enabled in the example)
+- Next.js App Router SSR integration with a client provider boundary
 
 Run it from the repository root:
 
 ```bash
-pnpm -C examples/repro dev
+pnpm -C examples/react-app dev
+pnpm -C examples/next-app-router dev
 ```
 
 What to check in the UI:
 - switching to **dark** changes the **page background** and **Card/Paper** background
 - text stays readable on both backgrounds
 - inputs, buttons, menus, and dialogs remain usable
+- Next.js example keeps SSR stable while theme state finalizes on the client
 
 ---