@atomazing-org/design-system 1.2.9 → 2.0.2

package/AGENTS.md

@@ -0,0 +1,92 @@
+# @atomazing-org/design-system Agent Rules
+
+These instructions apply when a repository depends on `@atomazing-org/design-system`
+or when an AI agent is asked to integrate, upgrade, or refactor work around this library.
+
+## Source Of Truth
+
+- `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`
+
+If you are working inside `examples/next-app-router`, load
+`examples/next-app-router/AGENTS.md` and treat it as the local source of truth for
+that starter.
+
+## Default Integration Rules
+
+1. Use only public imports:
+   - `@atomazing-org/design-system`
+   - `@atomazing-org/design-system/presets`
+2. Do not deep-import internal files from `src/*`, `dist/*`, or private folders.
+3. Use `ThemeProviderWrapper` as the app-level design-system entrypoint.
+4. Use `useThemeSettings()` for theme and dark-mode UI state instead of parallel custom state.
+5. Prefer:
+   - `defaultThemes` for standard application surfaces
+   - `landingPageThemes` for landing and marketing surfaces
+   - `allBuiltInThemes` only when the consumer intentionally wants both packs
+6. Custom presets must use the `ThemePreset` contract with both light and dark schemes.
+7. Do not create a competing root `ThemeProvider` unless it is a thin wrapper around the design system.
+8. For SSR and Next.js:
+   - keep the provider in a client boundary
+   - do not access `window`, `document`, or `localStorage` at module scope
+9. After dependency, provider, or theme-state changes, the app must still boot in a real browser without startup console errors.
+10. Fix duplicated runtime singleton warnings for `react`, `react-dom`, `@emotion/react`, or `@emotion/styled` before closing migration work.
+11. The active preset must own the application background.
+12. Do not hardcode page-level backgrounds on app shells, route layouts, or page wrappers when that overrides the preset background.
+13. Prefer direct MUI primitives or thin wrappers around them for base controls.
+14. Do not preserve consumer-owned substitute atoms for stock MUI controls unless they carry real custom behavior.
+15. Visible application text should be rendered through `Typography` with an explicit semantic variant.
+16. When MUI interactive controls render visible text, wrap that text in `Typography component="span"` instead of leaving raw text nodes in place.
+17. Shared dialogs, drawers, and bottom sheets must expose stable `aria-labelledby` and `aria-describedby`.
+18. Shared overlay close actions must have explicit accessible labels.
+19. Search overlays that own keyboard-filtered results should use `combobox` and `listbox` semantics.
+20. Browser event listeners belong in effects with cleanup, not render paths or module scope.
+21. Keep preset selection explicit in one app-owned theme module.
+22. Remove zero-value wrappers that only rename a stock MUI primitive or surface.
+23. Use theme helpers such as `alpha()` instead of palette-string alpha suffix hacks.
+24. Decorative gradients and shadow styling do not belong in normal consumer surfaces.
+25. If several app pages share the same workflow shell, extract one shared layout contract.
+26. If local app barrel exports introduce circular chunk warnings, use direct local imports instead.
+27. Fix consumer-owned build warnings with config changes, not warning suppression.
+
+## Generic Landing Principles
+
+Apply these rules when working on landing-style consumers in general:
+
+1. Use `landingPageThemes` intentionally for landing and marketing surfaces.
+2. Let the active preset own the page background.
+3. Keep one primary focus per major section.
+4. Keep scroll natural; avoid forced snap or automatic section scrolling.
+5. Prefer product-facing labels over template-facing labels in visible UI.
+6. Do not recreate preset-owned surface styling in app components.
+7. Prefer MUI-native composition over custom decorative UI logic.
+8. Do not build nested rectangular surface hierarchies.
+9. Keep landing content concise and easy to scan.
+
+## When To Propose A Migration
+
+Propose a route-based migration before making piecemeal edits if any of the following are true:
+
+- the app uses `@material-ui/*`
+- the app already has a custom theme or token layer
+- the app has widespread hardcoded UI tokens that should move to theme values
+- the user asks to adopt, align, standardize, upgrade, or replace the current UI foundation
+- partial integration would leave two competing sources of truth for theme state
+- the app hardcodes root-level page backgrounds that should instead come from the active preset
+
+## Route Selection
+
+- `@material-ui/*` found in dependencies or imports: use `mui4-to-latest`
+- no existing theme or token migration is needed: use `greenfield`
+- otherwise: use `adopt-existing`
+
+## Required Migration Response
+
+When migration is the correct path, the agent should:
+
+1. Say that route-based migration is recommended instead of ad hoc edits.
+2. Name the selected route and why it applies.
+3. Load `migrations/skills/design-system-migration-agent/SKILL.md`.
+4. Use the runbook and shared gates from `migrations/docs/migrations/design-system/`.

package/README.MD

@@ -1,46 +1,28 @@
 # @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.
-
-## 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.
-
----
-
+Modern MUI v7 + Emotion design system with strongly differentiated visual presets,
+scheme-based light and dark tokens, SSR-safe theming, and persistence.
 
 ## Installation
 
-Install the library:
-
 ```bash
 npm install @atomazing-org/design-system
+npm install react react-dom @mui/material @emotion/react @emotion/styled
 ```
 
-Install required peer dependencies (MUI v7 + Emotion):
-
-```bash
-npm install @mui/material @mui/icons-material @emotion/react @emotion/styled
-```
-
-Optional (only if your project uses Emotion `css` helpers):
+Optional peers:
 
-```bash
-npm install @emotion/css
-```
+- `@mui/icons-material`
+- `@emotion/css`
 
----
+## Package Format
 
-## Quick start
+- ESM-only package
+- Public entrypoints:
+  - `@atomazing-org/design-system`
+  - `@atomazing-org/design-system/presets`
 
-Use built-in presets (recommended starting point):
+## Quick Start
 
 ```tsx
 import { ThemeProviderWrapper } from "@atomazing-org/design-system";
@@ -55,388 +37,61 @@ export function App() {
 }
 ```
 
-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();
-
-  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>
-  );
-}
-```
-
----
-
-## Dark mode
-
-Dark mode switches the active **scheme** inside the current preset.
-
-### Supported values
+Use `useThemeSettings()` for runtime preset and dark-mode controls.
 
-- `light` — always use the preset’s light scheme
-- `dark` — always use the preset’s dark scheme
-- `system` — follow OS/browser preference (`prefers-color-scheme`)
+## Built-In Preset Packs
 
-### Why `system` exists
+- `defaultThemes`: baseline application presets
+- `landingPageThemes`: extended landing and marketing presets
+- `allBuiltInThemes`: combined pack
 
-It’s the most common UX: the app automatically follows the user’s OS preference without custom code in every project.
+## Custom Presets
 
-### What about `auto`?
+Custom presets must follow the `ThemePreset` contract:
 
-`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`.
+- stable `id`
+- human-readable `label`
+- `colorSchemes.light`
+- `colorSchemes.dark`
 
-Example selector:
+Each scheme should define:
 
-```tsx
-import { RadioGroup, FormControlLabel, Radio } from "@mui/material";
-import { useThemeSettings } from "@atomazing-org/design-system";
-
-export function DarkModeSelector() {
-  const { darkMode, 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>
-  );
-}
-```
-
-### Forcing mode (optional)
-
-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";
-
-export function App() {
-  return (
-    <ThemeProviderWrapper themes={defaultThemes} darkMode="light">
-      {/* your app */}
-    </ThemeProviderWrapper>
-  );
-}
-```
-
-Note: when `darkMode` is set, `darkMode` is locked and `setDarkMode` is ignored.
-
----
-
-## Custom themes
-
-Provide your own preset(s) to the provider. A preset is one identifiable theme with **two schemes**: `light` and `dark`.
-
-### API reference — `ThemePreset`
-
-| 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. |
-
-### Minimum required tokens per scheme
-
-Each scheme must define:
-- `palette.background.default` — page background
-- `palette.background.paper` — Card/Paper background
+- `palette.background.default`
+- `palette.background.paper`
 - `palette.text.primary`
 - `palette.text.secondary`
 - `palette.divider`
 
-Example:
-
-```ts
-import type { ThemePreset } from "@atomazing-org/design-system";
+## Persistence
 
-export const myPreset: ThemePreset = {
-  id: "my-brand",
-  label: "My Brand",
-  colorSchemes: {
-    light: {
-      palette: {
-        background: { default: "#ffffff", paper: "#ffffff" },
-        text: { primary: "#111111", secondary: "#444444" },
-        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)",
-      },
-    },
-  },
-};
-```
-
-### Using defaults + custom presets
+Theme settings are stored in `localStorage` under `appSettings`.
 
-```ts
-import { defaultThemes } from "@atomazing-org/design-system/presets";
-
-const themes = [...defaultThemes, myPreset];
-```
+Current JSON shape:
 
-Then pass `themes` into `ThemeProviderWrapper`.
-
----
-
-## Typography variants
-
-The library adds extra typography variants (beyond MUI defaults) so your text styles are consistent across the app.
-
-```tsx
-import { Typography } from "@mui/material";
-
-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>
-    </>
-  );
-}
-```
-
-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:
-
-```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>
-  );
-}
-```
-
----
-
-## Animations
-
-The library exports reusable keyframes so you can keep motion consistent.
-
-```tsx
-import styled from "@emotion/styled";
-import { fadeIn } from "@atomazing-org/design-system";
-
-const Panel = styled.div`
-  animation: ${fadeIn} 240ms ease-in both;
-`;
-
-export function AnimatedPanel() {
-  return <Panel>Content</Panel>;
-}
-```
-
----
-
-## SSR notes
-
-- 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`.
-
-## Consumer alias guidance (optional)
-
-Aliases are **optional**. They help you avoid long relative imports **inside your app**.
-
----
-
-## Local development (repo)
-
-From the repository root:
-
-```bash
-pnpm lint
-pnpm build
-pnpm test
-pnpm -C examples/repro dev
-```
-
----
-
-## 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`
-
-### 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/repro)
-
-The repo includes a runnable example app that demonstrates:
-- preset switching
-- dark mode switching
-- background + card surfaces changing correctly
-- token/debug view (if enabled in the example)
-
-Run it from the repository root:
-
-```bash
-pnpm -C examples/repro 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
-
----
-
-## 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";
-
-export function App() {
-  return (
-    <ThemeProviderWrapper themes={defaultThemes}>
-      {/* your app */}
-    </ThemeProviderWrapper>
-  );
-}
-```
-
----
-
-## Public exports (recommended imports)
-
-Use only these stable entry points:
-
-### Core API
-```ts
-import { ThemeProviderWrapper, useThemeSettings } from "@atomazing-org/design-system";
-```
-
-### Built-in presets
-```ts
-import { defaultThemes } from "@atomazing-org/design-system/presets";
+```json
+{ "themeId": "editorial-classic", "darkMode": "system" }
 ```
 
-Tip:
-- Avoid deep imports from internal folders. They may change during refactors.
+## SSR Notes
 
----
+- 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.
 
-## Migration notes (if upgrading)
+## Migration Docs
 
-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]`
+If you are migrating an app to this package, start with:
 
-Goal:
-- dark mode changes **real palette tokens**, so backgrounds/cards/text update together.
+- `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`
 
----
+## Examples
 
-## License
+- `examples/react-app`: canonical Vite smoke consumer for local package validation
+- `examples/next-app-router`: canonical Next.js App Router starter reference
 
-MIT
+For starter-specific rules, runbooks, and customization guidance, use the local docs
+pack under `examples/next-app-router/`.