@atomazing-org/design-system 2.0.1 → 3.7.2

package/README.MD

@@ -1,232 +1,214 @@
 # @atomazing-org/design-system
 
-Modern MUI v7 + Emotion design system with strongly differentiated visual presets, scheme-based light/dark tokens, SSR-safe theming, and persistence.
+Modern MUI v7 + Emotion design system built around visual presets, explicit
+light and dark schemes, SSR-safe theming, and persisted runtime settings.
 
 ## Preview
-![Design system preview](https://raw.githubusercontent.com/atomazing/design-system/master/preview.gif)
-
-## Why use it
-
-- **True light/dark themes**: each preset ships **two curated schemes** (`light` + `dark`), so backgrounds, cards, and text actually change (not just `palette.mode`).
-- **Works out of the box**: includes ready-made presets you can use immediately.
-- **Easy to extend**: bring your own presets, or combine defaults + custom.
-- **Consistent UI**: global styles + MUI component overrides for predictable visuals.
-- **Safe persistence**: remembers selected theme + dark mode with SSR-safe guards.
-
----
 
+![Design system preview](./preview.gif)
+
+## At A Glance
+
+- React 18 and 19 support
+- MUI 7 + Emotion 11
+- Preset-first theming via `ThemePreset`
+- Runtime theme and dark-mode switching
+- SSR-safe provider flow
+- Curated root API plus `/presets` entrypoint
+
+## Contents
+
+- [Why This Library](#why-this-library)
+- [Installation](#installation)
+- [Package Format](#package-format)
+- [Quick Start](#quick-start)
+- [Built-In Presets](#built-in-presets)
+- [Dark Mode](#dark-mode)
+- [Custom Presets](#custom-presets)
+- [Persistence](#persistence)
+- [SSR Notes](#ssr-notes)
+- [API Reference](#api-reference)
+- [Migration Docs](#migration-docs)
+- [Examples](#examples)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [Releases](#releases)
+- [License](#license)
+
+## Why This Library
+
+- Preset-first theming built on `ThemePreset`, not ad hoc per-app theme files
+- True light and dark schemes via `colorSchemes`, not only `palette.mode`
+- Strong visual differentiation between presets instead of subtle palette swaps
+- Runtime theme selection and dark-mode switching with persisted settings
+- SSR-safe provider flow with no browser APIs touched at module scope
+- Curated public API for app integrations and consumer documentation
+- Test coverage for contrast, baseline preset shape, and SSR behavior
 
 ## Installation
 
-Install the library:
+### npm
 
 ```bash
-npm install @atomazing-org/design-system
+npm install @atomazing-org/design-system react react-dom @mui/material @emotion/react @emotion/styled
 ```
 
-Install required peer dependencies (React 18/19 + MUI v7 + Emotion core):
+### pnpm
 
 ```bash
-npm install react react-dom @mui/material @emotion/react @emotion/styled
+pnpm add @atomazing-org/design-system react react-dom @mui/material @emotion/react @emotion/styled
 ```
 
-Optional peers:
+Optional peer:
 
-- `@mui/icons-material` (only if your app imports MUI icons)
-- `@emotion/css` (only if your project uses Emotion `css` helpers)
+- `@mui/icons-material`
 
-```bash
-npm install @mui/icons-material @emotion/css
-```
+Expected ecosystem:
 
-### Package format (v2)
+- React `^18 || ^19`
+- React DOM `^18 || ^19`
+- MUI `^7`
+- Emotion `^11`
 
-`@atomazing-org/design-system` v2 is **ESM-only**.
-Use ESM imports (`import ... from ...`). CommonJS `require()` is not supported.
+## Package Format
 
----
+- ESM-only package
+- Public entrypoints:
+  - `@atomazing-org/design-system`
+  - `@atomazing-org/design-system/presets`
 
-## Quick start
+The root entrypoint is intentionally curated. Preset registries and individual
+presets live under the `/presets` subpath.
 
-Use built-in presets (recommended starting point):
+## Quick Start
 
 ```tsx
+import ReactDOM from "react-dom/client";
 import { ThemeProviderWrapper } from "@atomazing-org/design-system";
 import { defaultThemes } from "@atomazing-org/design-system/presets";
 
-export function App() {
-  return (
-    <ThemeProviderWrapper themes={defaultThemes}>
-      {/* your app */}
-    </ThemeProviderWrapper>
-  );
-}
-```
-
-Notes:
-- `themes` can be **default presets**, **your presets**, or **both**.
-- Theme choice + dark mode are persisted (storage key: `appSettings`).
-
----
-
-## Built-in presets
-
-Built-in presets are **ready-made theme packs shipped with the library**.  
-You can use them as-is, or add your own presets alongside them.
-
-| Preset | Stable id | Best for |
-|---|---|---|
-| Warm Earth | `warm-earth` | Warm and friendly apps |
-| Editorial Classic | `editorial-classic` | Content-heavy UIs |
-| Modern Minimal | `modern-minimal` | Dashboards and tooling |
-| Neo Glass | `neo-glass` | Modern “glass” style UIs |
-| Retro Terminal | `retro-terminal` | Terminal-inspired branding |
-
-Import them from:
-
-```ts
-import { defaultThemes } from "@atomazing-org/design-system/presets";
-```
-
-## Switching theme (UI)
-
-Build a simple theme switcher using the library’s theme settings hook.
-
-```tsx
-import { ToggleButton, ToggleButtonGroup } from "@mui/material";
-import { useThemeSettings } from "@atomazing-org/design-system";
-import { defaultThemes } from "@atomazing-org/design-system/presets";
-
-export function ThemeSwitcher() {
-  const { theme, setTheme } = useThemeSettings();
+import App from "./App";
 
-  return (
-    <ToggleButtonGroup
-      size="small"
-      exclusive
-      value={theme}
-      onChange={(_, next) => next && setTheme(next)}
-    >
-      {defaultThemes.map((t) => (
-        <ToggleButton key={t.id} value={t.id}>
-          {t.label}
-        </ToggleButton>
-      ))}
-    </ToggleButtonGroup>
-  );
-}
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <ThemeProviderWrapper themes={defaultThemes}>
+    <App />
+  </ThemeProviderWrapper>,
+);
 ```
 
----
-
-## Dark mode
+Use `useThemeSettings()` when you need runtime access to:
 
-Dark mode switches the active **scheme** inside the current preset.
+- the selected preset id
+- the current dark-mode setting
+- setters for both
 
-### Supported values
-
-- `light` — always use the preset’s light scheme
-- `dark` — always use the preset’s dark scheme
-- `system` — follow OS/browser preference (`prefers-color-scheme`)
-
-### Why `system` exists
-
-It’s the most common UX: the app automatically follows the user’s OS preference without custom code in every project.
-
-Example selector:
+Example:
 
 ```tsx
-import { RadioGroup, FormControlLabel, Radio } from "@mui/material";
 import { useThemeSettings } from "@atomazing-org/design-system";
 
-export function DarkModeSelector() {
-  const { darkMode, setDarkMode } = useThemeSettings();
+export function ThemeDebug() {
+  const { theme, darkMode, setTheme, setDarkMode } = useThemeSettings();
 
   return (
-    <RadioGroup row value={darkMode} onChange={(e) => setDarkMode(e.target.value as any)}>
-      <FormControlLabel value="system" control={<Radio />} label="System" />
-      <FormControlLabel value="light" control={<Radio />} label="Light" />
-      <FormControlLabel value="dark" control={<Radio />} label="Dark" />
-    </RadioGroup>
+    <>
+      <button onClick={() => setTheme("modern-minimal")}>Modern Minimal</button>
+      <button onClick={() => setDarkMode("dark")}>Dark</button>
+      <pre>{JSON.stringify({ theme, darkMode }, null, 2)}</pre>
+    </>
   );
 }
 ```
 
-### Forcing mode (optional)
+## Built-In Presets
 
-If your app does not support dark mode, you can force the effective palette mode:
-
-```tsx
-import { ThemeProviderWrapper } from "@atomazing-org/design-system";
-import { defaultThemes } from "@atomazing-org/design-system/presets";
+Ship-ready preset packs live under `@atomazing-org/design-system/presets`.
 
-export function App() {
-  return (
-    <ThemeProviderWrapper themes={defaultThemes} darkMode="light">
-      {/* your app */}
-    </ThemeProviderWrapper>
-  );
-}
+```ts
+import {
+  allBuiltInThemes,
+  defaultThemes,
+  landingPageThemes,
+  modernMinimal,
+} from "@atomazing-org/design-system/presets";
 ```
 
-Note: when `darkMode` is set, `darkMode` is locked and `setDarkMode` is ignored.
-
----
-
-## Persistence (`appSettings`)
+### `defaultThemes`
 
-Theme selection is persisted in `localStorage` under the key `appSettings`.
+Baseline application presets:
 
-v2 JSON shape:
-
-```json
-{ "themeId": "editorial-classic", "darkMode": "system" }
-```
+- `Editorial Classic`
+- `Airport Ops`
+- `Modern Minimal`
+- `Neo Glass`
+- `Retro Terminal`
+- `Warm Earth`
 
-Notes:
-- v2 stores only `themeId` and `darkMode`.
-- v2 does not migrate legacy stored formats (`theme`, `version`, `auto`); invalid/legacy payloads reset to defaults.
+### `landingPageThemes`
 
----
+Extended pack for landing pages, brand-heavy surfaces, and more expressive
+visual directions. Representative families include:
 
-## App migration routes (repo docs)
+- `Flow Editorial`
+- `Acid Editorial`
+- `Bauhaus Ops`
+- `Neon Bauhaus Grid`
+- `Neon Bauhaus Ops`
+- `Brutalist Sprint`
+- `Brand Neon Motion`
+- `Glass Reactor`
+- `Holographic Ledger`
+- `Kintsugi Protocol`
+- `Solarpunk Enterprise`
 
-If you are migrating an app to v2, use the route runbooks under:
+### `allBuiltInThemes`
 
-- `migrations/docs/migrations/design-system/README.md`
-- `migrations/docs/migrations/design-system/routes/*`
+Combined pack of `defaultThemes` and `landingPageThemes`.
 
-`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`).
+## Dark Mode
 
----
+Supported dark-mode values:
 
-## Custom themes
+- `light`
+- `dark`
+- `system`
 
-Provide your own preset(s) to the provider. A preset is one identifiable theme with **two schemes**: `light` and `dark`.
+`ThemeProviderWrapper` resolves the effective scheme from the selected dark-mode
+value and the current system preference. The root export `darkModeOptions` is
+available for building dark-mode UI controls.
 
-### API reference — `ThemePreset`
+```tsx
+import { darkModeOptions, useThemeSettings } from "@atomazing-org/design-system";
+import { FormControlLabel, Radio, RadioGroup } from "@mui/material";
 
-| Field | Type | What it means |
-|---|---|---|
-| `id` | `string` | Stable identifier used for persistence and deduplication. Must be unique. |
-| `label` | `string` | Name shown in UI selectors. |
-| `colorSchemes.light` | `ThemeOptions` | MUI ThemeOptions for light mode. |
-| `colorSchemes.dark` | `ThemeOptions` | MUI ThemeOptions for dark mode. |
+export function DarkModeSelector() {
+  const { darkMode, setDarkMode } = useThemeSettings();
 
-### Minimum required tokens per scheme
+  return (
+    <RadioGroup
+      row
+      value={darkMode}
+      onChange={(event) => setDarkMode(event.target.value as typeof darkMode)}
+    >
+      {darkModeOptions.map((option) => (
+        <FormControlLabel
+          key={option.value}
+          control={<Radio />}
+          label={option.label}
+          value={option.value}
+        />
+      ))}
+    </RadioGroup>
+  );
+}
+```
 
-Each scheme must define:
-- `palette.background.default` — page background
-- `palette.background.paper` — Card/Paper background
-- `palette.text.primary`
-- `palette.text.secondary`
-- `palette.divider`
+## Custom Presets
 
-Example:
+Custom presets should follow the `ThemePreset` contract.
 
 ```ts
-import type { ThemePreset } from "@atomazing-org/design-system";
+import type { ThemePreset } from "@atomazing-org/design-system/presets";
 
 export const myPreset: ThemePreset = {
   id: "my-brand",
@@ -236,241 +218,187 @@ export const myPreset: ThemePreset = {
       palette: {
         background: { default: "#ffffff", paper: "#ffffff" },
         text: { primary: "#111111", secondary: "#444444" },
-        divider: "rgba(0,0,0,0.12)",
+        divider: "rgba(0, 0, 0, 0.12)",
       },
     },
     dark: {
       palette: {
         background: { default: "#0f1115", paper: "#151922" },
         text: { primary: "#f1f3f5", secondary: "#c6cbd1" },
-        divider: "rgba(241,243,245,0.16)",
+        divider: "rgba(241, 243, 245, 0.16)",
       },
     },
   },
 };
 ```
 
-### Using defaults + custom presets
+Merge custom presets with the built-ins:
 
 ```ts
-import { defaultThemes } from "@atomazing-org/design-system/presets";
-
 const themes = [...defaultThemes, myPreset];
 ```
 
-Then pass `themes` into `ThemeProviderWrapper`.
+Rules worth keeping in mind:
 
----
+- preset ids must be unique and non-empty
+- duplicate ids are deduped by id with last-wins token resolution
+- first occurrence order is preserved for the visible preset list
 
-## Typography variants
+## Persistence
 
-The library adds extra typography variants (beyond MUI defaults) so your text styles are consistent across the app.
+Theme settings are stored in `localStorage` under `appSettings` by default.
 
-```tsx
-import { Typography } from "@mui/material";
+Current JSON shape:
 
-export function TypographyDemo() {
-  return (
-    <>
-      <Typography variant="header_lg_bold">Page title</Typography>
-      <Typography variant="text_md_regular">Body text</Typography>
-      <Typography variant="text_sm_bold">Caption / label</Typography>
-    </>
-  );
-}
+```json
+{ "themeId": "editorial-classic", "darkMode": "system" }
 ```
 
-Notes:
-- Typography sizing is expected to be **rem-based** (scales with the user’s browser font size settings).
-- Variants are defined in the design system theme (no local “one-off” styles needed).
-
----
-
-## Global styles
-
-`ThemeProviderWrapper` applies global styles (via Emotion) and MUI component defaults, so the app looks consistent immediately.
-
-Set a custom font stack:
+If multiple applications share the same origin, override the storage key with
+`settingsStorageKey` on `ThemeProviderWrapper`.
 
 ```tsx
-import { ThemeProviderWrapper } from "@atomazing-org/design-system";
-
-export function App() {
-  return (
-    <ThemeProviderWrapper fontFamily="Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Arial, sans-serif">
-      {/* your app */}
-    </ThemeProviderWrapper>
-  );
-}
+<ThemeProviderWrapper
+  themes={defaultThemes}
+  settingsStorageKey="pampaLegacyThemeSettings"
+>
+  <App />
+</ThemeProviderWrapper>
 ```
 
----
-
-## Animations
+## SSR Notes
 
-The library exports reusable keyframes so you can keep motion consistent.
+- Keep `ThemeProviderWrapper` inside a client boundary for Next.js and other SSR
+  apps.
+- Do not access `window`, `document`, or `localStorage` at module scope.
+- When dark mode uses `system`, the effective mode resolves on the client after
+  hydration.
 
-```tsx
-import styled from "@emotion/styled";
-import { fadeIn } from "@atomazing-org/design-system";
+## API Reference
 
-const Panel = styled.div`
-  animation: ${fadeIn} 240ms ease-in both;
-`;
+### `ThemeProviderWrapper`
 
-export function AnimatedPanel() {
-  return <Panel>Content</Panel>;
-}
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `themes` | `ThemePreset[]` | `defaultThemes` | Preset list used by the provider. |
+| `fontFamily` | `string` | `undefined` | Optional global font stack applied by `GlobalStyles`. |
+| `darkMode` | `"light" \| "dark" \| "system"` | `undefined` | Optional hard override for dark mode. |
+| `initialThemeId` | `string` | `undefined` | Fallback theme id when persisted settings are absent. |
+| `initialDarkMode` | `"light" \| "dark" \| "system"` | `undefined` | Fallback dark mode when persisted settings are absent. |
+| `settingsStorageKey` | `string` | `"appSettings"` | Optional localStorage key override. |
+| `children` | `ReactNode` | required | Application content. |
 
----
+If `darkMode` is passed as a prop, `setDarkMode()` becomes a no-op because the
+provider is operating in controlled override mode.
 
-## SSR notes
+### `useThemeSettings()`
 
-- The library is written to be **SSR-safe**: no `window`/`document`/`localStorage` access at module scope.
-- If you use **system** dark mode, the effective mode is derived from `prefers-color-scheme` on the client.
-- In Next.js, place the provider inside a client boundary (e.g., a component with `"use client"`), then wrap your app with `ThemeProviderWrapper`.
+Returns:
 
-## Consumer alias guidance (optional)
+- `theme`
+- `setTheme(themeId)`
+- `darkMode`
+- `setDarkMode(mode)`
+- `themes`
+- `selectedTheme`
+- `defaultThemeName`
 
-Aliases are **optional**. They help you avoid long relative imports **inside your app**.
+### Root Exports
 
----
+The curated root entrypoint exports:
 
-## Local development (repo)
+- `ThemeProviderWrapper`
+- `useThemeSettings`
+- `mergeThemes`
+- `normalizeThemes`
+- `resolveDefaultThemeName`
+- `resolveThemeById`
+- `GlobalStyles`
+- `buildMuiTheme`
+- `resolveEffectiveMode`
+- `selectThemeOptions`
+- `validateSchemeTokens`
+- `darkModeOptions`
+- `useSystemTheme`
+- `readAppSettings`
+- `writeAppSettings`
 
-From the repository root:
+Preset registries and individual presets live under
+`@atomazing-org/design-system/presets`.
 
-```bash
-pnpm lint
-pnpm build
-pnpm test
-pnpm -C examples/react-app dev
-pnpm -C examples/next-app-router dev
-```
+## Migration Docs
 
----
+If you are migrating an existing app to this package, start with:
 
-## Peer dependencies
-
-Make sure your app installs these (MUI v7 + Emotion):
-
-- `react`
-- `react-dom`
-- `@mui/material`
-- `@mui/icons-material` (optional, only if you use icons from MUI)
-- `@emotion/react`
-- `@emotion/styled`
-- `@emotion/css` (optional)
-
----
-
-## Troubleshooting
-
-### Dark mode switches, but background/cards do not change
-- Ensure your preset provides **both schemes**:
-  - `colorSchemes.light.palette.background.default/paper`
-  - `colorSchemes.dark.palette.background.default/paper`
-- Avoid hardcoded colors in overrides. Use `theme.palette.*` tokens.
-
-### Text is hard to read in dark mode
-- Do not reuse light “ink” constants in dark mode.
-- Check:
-  - `palette.text.primary` vs `palette.background.default`
-  - `palette.text.secondary` vs `palette.background.paper`
+- `migrations/README.UPDATE.md`
+- `migrations/docs/migrations/design-system/README.md`
+- `migrations/docs/migrations/design-system/shared/WORKING-RULES.md`
+- `migrations/skills/design-system-consumer-agent/SKILL.md`
+- `migrations/skills/design-system-migration-agent/SKILL.md`
 
-### I want to add my own presets
-- Create a `ThemePreset` with `colorSchemes.light` and `colorSchemes.dark`.
-- Combine with defaults: `const themes = [...defaultThemes, myPreset];`
+## Examples
 
-## Examples (`examples/react-app`, `examples/next-app-router`)
+Run examples from the repository root after `pnpm install`.
 
-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
+### React App Smoke Consumer
 
-Run it from the repository root:
+Fastest local validation path for presets and runtime theme switching:
 
 ```bash
-pnpm -C examples/react-app dev
-pnpm -C examples/next-app-router dev
+pnpm --dir examples/react-app 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
+### Next.js App Router Reference
 
----
-
-## API reference — `ThemeProviderWrapper`
-
-`ThemeProviderWrapper` wires MUI ThemeProvider, global styles, and persisted settings.
-
-| Prop | Type | Default | What it does |
-|---|---|---|---|
-| `themes` | `ThemePreset[]` (or built-in `defaultThemes`) | `defaultThemes` | List of presets available to the user. |
-| `fontFamily` | `string` | (theme default) | Optional global font stack for the whole app. |
-| `darkMode` | `DarkModeOptions` | - | Forces mode regardless of persisted settings and system preference. |
-| `children` | `ReactNode` | — | Your application tree. |
-
-Minimal usage:
-
-```tsx
-import { ThemeProviderWrapper } from "@atomazing-org/design-system";
-import { defaultThemes } from "@atomazing-org/design-system/presets";
+Starter reference for SSR-safe integration:
 
-export function App() {
-  return (
-    <ThemeProviderWrapper themes={defaultThemes}>
-      {/* your app */}
-    </ThemeProviderWrapper>
-  );
-}
+```bash
+pnpm --dir examples/next-app-router dev
 ```
 
----
-
-## Public exports (recommended imports)
+## Troubleshooting
 
-Use only these stable entry points:
+- Dark mode does not visibly change the app:
+  Ensure both `colorSchemes.light` and `colorSchemes.dark` define
+  `palette.background.default`, `palette.background.paper`, and readable text
+  colors.
+- Preset switching appears stuck:
+  Check for duplicate or empty preset ids and clear the relevant
+  `localStorage` key if invalid persisted state exists.
+- One app keeps overwriting another app's theme:
+  Use a custom `settingsStorageKey` instead of the shared default key.
+- SSR build or hydration warnings appear:
+  Make sure the provider is mounted in a client boundary and that no browser API
+  access happens at module scope.
+
+## Contributing
 
-### Core API
-```ts
-import { ThemeProviderWrapper, useThemeSettings } from "@atomazing-org/design-system";
-```
-
-### Built-in presets
-```ts
-import { defaultThemes } from "@atomazing-org/design-system/presets";
+```bash
+pnpm lint
+pnpm test
+pnpm build
+pnpm run smoke:esm
+pnpm run smoke:react-app
+pnpm run smoke:next
+pnpm run check:migration-readiness
 ```
 
-Tip:
-- Avoid deep imports from internal folders. They may change during refactors.
+## Releases
 
----
+This repo uses Changesets for package versioning and release automation.
 
-## Migration notes (if upgrading)
+Intended flow:
 
-If you previously passed a single theme object or a legacy “theme list”:
-1) Move your theme into a preset shape with **two schemes**:
-   - `colorSchemes.light`
-   - `colorSchemes.dark`
-2) Ensure each scheme defines the required tokens:
-   - `background.default`, `background.paper`
-   - `text.primary`, `text.secondary`
-   - `divider`
-3) Pass presets into the provider:
-   - `themes={[...defaultThemes, myPreset]}` or only `[myPreset]`
+- run `pnpm changeset`
+- merge changes into `master`
+- GitHub Actions opens or updates a release PR
+- merge the release PR to publish to npm
 
-Goal:
-- dark mode changes **real palette tokens**, so backgrounds/cards/text update together.
+See:
 
----
+- `RELEASING.md` for the release checklist and example changeset
+- `RELEASE-STATUS.md` if automation is temporarily blocked by GitHub
+  organization permissions
 
 ## License