@atomazing-org/design-system 1.1.1 → 1.2.0

package/README.MD

@@ -1,345 +1,257 @@
-@atomazing-org/design-system
-
-Modern MUI + Emotion design system with a ready theme factory, extended typography, global styles, component overrides, animations, and handy utilities.
-
-Contents
-- Introduction
-- Installation
-- Quick Start
-- Provider Props
-- Dynamic Themes (array)
-- Theme Switching (UI)
-- Dark Mode Control
-- Extended Palette (4 variants)
-- Palette Overrides
-- Using Palette In SX
-- Typography Variants
-- Global Styles
-- Animations
-- Components
-- Utilities
-- SSR Notes
-- Peer Dependencies
-
-Introduction
-The package streamlines consistent theming across apps: dark/light mode, typography variants, global styles, and component defaults. Built on MUI v7 + Emotion.
-
-Installation
-```bash
-npm install @atomazing-org/design-system
-npm install @mui/material @mui/icons-material @emotion/react @emotion/styled @emotion/css
-```
-
-Quick Start
-```tsx
-import { ThemeProviderWrapper } from '@atomazing-org/design-system';
-
-export function App() {
-  return (
-    <ThemeProviderWrapper>
-      {/* your app */}
-    </ThemeProviderWrapper>
-  );
-}
-```
-
-If `themes` is not provided, the provider falls back to a single "Default" theme using the current palette brand color.
-
-Provider Props
-- `themes?: ThemesProp` (single theme may omit `name`, multiple themes require `name`)
-- `fontFamily?: string`
-- `colorPaletteOverride?: Partial<ColorPaletteType>`
-`ThemeOptions` is the MUI theme options type from `@mui/material/styles`.
-
-Theme Names
-Single theme can omit `name` (defaults to `"Default"`). Multiple themes require a non-empty `name` for each theme.
-
-Before (single theme required a name):
-```tsx
-<ThemeProviderWrapper
-  themes={[
-    {
-      name: 'Blue',
-      palette: { primary: { main: '#3B82F6' } },
-    },
-  ]}
-/>
-```
-
-After (single theme name omitted):
-```tsx
-<ThemeProviderWrapper
-  themes={[
-    {
-      palette: { primary: { main: '#3B82F6' } },
-    },
-  ]}
-/>
-```
-
-Multiple themes (name required):
-```tsx
-<ThemeProviderWrapper
-  themes={[
-    {
-      name: 'BrandA',
-      palette: { primary: { main: '#00A3FF' } },
-    },
-    {
-      name: 'BrandB',
-      palette: { primary: { main: '#10B981' } },
-    },
-  ]}
-/>
-```
-
-Dynamic Themes (array)
-Provide a fully dynamic list of `ThemeOptions` overrides. Names are required when supplying multiple themes. Provider-controlled `palette.mode` always wins.
-
-Minimal example (primary color only):
-```tsx
-<ThemeProviderWrapper
-  themes={[
-    {
-      name: 'Blue',
-      palette: {
-        primary: { main: '#3B82F6' },
-      },
-    },
-  ]}
->
-  {/* ... */}
-</ThemeProviderWrapper>
-```
-
-Advanced example (palette + components overrides):
-```tsx
-<ThemeProviderWrapper
-  themes={[
-    {
-      name: 'BrandA',
-      palette: {
-        primary: { main: '#00A3FF' },
-        background: { default: '#F7FAFF', paper: '#FFFFFF' },
-      },
-      components: {
-        MuiButton: {
-          styleOverrides: {
-            root: { textTransform: 'none' },
-          },
-        },
-      },
-    },
-  ]}
->
-  {/* ... */}
-</ThemeProviderWrapper>
-```
-
-Migration Notes (breaking)
-- Legacy `themes` shape (`primaryColor`, `secondaryColor`, `background`) removed.
-- `themeOverrides` prop removed.
-- Use `themes: ThemesProp` for customization (single theme may omit `name`, multiple themes require `name`).
-
-Theme Switching (UI)
-Use the theme context to read and change the active theme.
-
-```tsx
-import { useThemeSettings } from '@atomazing-org/design-system';
-import { ToggleButton, ToggleButtonGroup } from '@mui/material';
-
-export function ThemeToggle() {
-  const { theme, setTheme } = useThemeSettings();
-  const options = ['Blue', 'Green', 'Gray'];
-
-  return (
-    <ToggleButtonGroup
-      size="small"
-      exclusive
-      color="brand"
-      value={theme}
-      onChange={(_, v) => v && setTheme(v)}
-    >
-      {options.map((o) => (
-        <ToggleButton key={o} value={o}>{o}</ToggleButton>
-      ))}
-    </ToggleButtonGroup>
-  );
-}
-```
-
-Dark Mode Control
-Use `useThemeSettings()` to read and set dark mode. Modes: `light | dark | system | auto`.
-
-```tsx
-import { useThemeSettings, darkModeOptions } from '@atomazing-org/design-system';
-import { RadioGroup, FormControlLabel, Radio } from '@mui/material';
-
-export function DarkModeSelector() {
-  const { darkMode, setDarkMode } = useThemeSettings();
-  const options = darkModeOptions; // label + icon
-
-  return (
-    <RadioGroup
-      row
-      value={darkMode}
-      onChange={(e) => setDarkMode(e.target.value as any)}
-    >
-      {options.map((o) => (
-        <FormControlLabel key={o.value} value={o.value} control={<Radio />} label={o.label} />
-      ))}
-    </RadioGroup>
-  );
-}
-```
-
-Extended Palette (4 variants)
-The design system adds four typed colors to the MUI palette, available on common components via the `color` prop:
-
-- brand: project brand color (uses the active theme `primary`).
-- neutral: neutral/gray scale color (from the design-system palette).
-- accent: supporting accent color (from palette `accent`).
-- muted: soft/desaturated color (based on neutral by default).
-
-Supported components: `Button`, `Chip`, `Badge`, `Alert`.
-
-```tsx
-import { Button, Chip, Alert } from '@mui/material';
-
-<Button color="brand" variant="contained">Brand</Button>
-<Button color="neutral" variant="outlined">Neutral</Button>
-<Chip color="accent" label="Accent" />
-<Alert color="muted" variant="filled">Muted Alert</Alert>
-```
-
-Palette Overrides
-Override base palette tokens for the whole app.
-
-```tsx
-<ThemeProviderWrapper
-  colorPaletteOverride={{
-    brand: '#4F46E5',
-    accent: '#F59E0B',
-    muted: '#94A3B8',
-    neutral: '#64748B',
-    success: '#16A34A',
-    warning: '#D97706',
-    error: '#DC2626',
-    info: '#0284C7',
-  }}
->
-  {/* ... */}
-</ThemeProviderWrapper>
-```
-
-Using Palette In SX
-```tsx
-import { Box } from '@mui/material';
-
-<Box sx={{ bgcolor: (t) => t.palette.accent.main, color: (t) => t.palette.getContrastText(t.palette.accent.main) }}>
-  Accent surface
-</Box>
-```
-
-Typography Variants
-Extra variants are available (mapping to `<p>`/headers). Examples:
-
-```tsx
-import { Typography } from '@mui/material';
-
-<Typography variant="text_md_regular">Body text</Typography>
-<Typography variant="text_sm_bold">Strong caption</Typography>
-<Typography variant="header_lg_bold">Section Title</Typography>
-<Typography variant="header_md_semibold">Semibold Heading</Typography>
-```
-
-Global Styles
-`ThemeProviderWrapper` injects global styles via Emotion. You can also set a custom font family:
-
-```tsx
-<ThemeProviderWrapper fontFamily="Inter, system-ui, -apple-system, 'Segoe UI', Roboto, Arial, sans-serif">
-  {/* ... */}
-</ThemeProviderWrapper>
-```
-
-Animations
-Keyframes ready for use in Emotion/MUI `sx`:
-
-```tsx
-import { keyframes } from '@emotion/react';
-import { fadeIn, slideIn, scale, pulseAnimation, progressPulse } from '@atomazing-org/design-system';
-import styled from '@emotion/styled';
-
-const Card = styled.div`
-  animation: ${fadeIn} 300ms ease-in both;
-`;
-
-const Glowing = styled.div`
-  animation: ${progressPulse('#9FA9EA')} 2s ease-in-out infinite;
-`;
-```
-
-Components
-- ErrorBoundary
-```tsx
-import { ErrorBoundary } from '@atomazing-org/design-system';
-
-<ErrorBoundary>
-  <App />
-</ErrorBoundary>
-```
-
-- Loading
-```tsx
-import { Loading } from '@atomazing-org/design-system';
-
-<Loading />
-```
-
-- PathName / DialogBtn
-```tsx
-import { PathName, DialogBtn } from '@atomazing-org/design-system';
-
-<PathName>/settings/profile</PathName>
-<DialogBtn variant="contained" color="brand">OK</DialogBtn>
-```
-
-Utilities
-```tsx
-import {
-  getFontColor, isFontLight, isHexColor,
-  timeAgo, timeAgoFromStart,
-  useResponsiveDisplay, useSystemTheme,
-  displayGreeting, getDayIdentifier,
-  systemInfo,
-} from '@atomazing-org/design-system';
-
-// Colors
-getFontColor('#ffffff'); // '#101727' | '#f0f0f0'
-isFontLight('#222');
-isHexColor('#abc');
-
-// Time
-timeAgo(new Date(Date.now() - 3600_000));
-timeAgoFromStart(new Date(Date.now() + 90_000));
-
-// Device
-const isMobile = useResponsiveDisplay(768);
-const sysTheme = useSystemTheme(); // 'light' | 'dark' | 'unknown'
-
-// Misc
-displayGreeting(); // Good morning / afternoon / evening
-getDayIdentifier(new Date()); // 'YYYY-MM-DD'
-console.log(systemInfo.os, systemInfo.browser);
-```
-
-SSR Notes
-- The library guards `localStorage`/`navigator`. Use normally in SSR apps; hydration updates settings on client.
-- For Next.js, place the provider in a client boundary (e.g., `layout.tsx` with `"use client"`).
-
-Peer Dependencies
-- `@mui/material` ^7
-- `@mui/icons-material` ^7
-- `@emotion/react` ^11
-- `@emotion/styled` ^11
-- `@emotion/css` ^11 (optional)
+# @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)
+
+## Contents
+- Preview
+- Why this library
+- Installation
+- Quickstart
+- Presets
+- Dark mode
+- Custom presets
+- API reference
+- Examples
+- Troubleshooting
+- Consumer alias guidance
+- Contributing
+- Release notes
+- License
+
+## Why this library
+- True light/dark presets via colorSchemes (not just palette.mode)
+- Distinct preset identities (minimal, liquid glass, editorial, warm organic, retro terminal)
+- Persisted theme and darkMode with safe defaults
+- SSR-safe (no module-scope browser APIs)
+- MUI v7 + Emotion ready, with typography variants and component overrides
+- Guardrails: contrast checks on preset tokens
+- Easy to extend with custom presets
+
+## Installation
+```bash
+npm install @atomazing-org/design-system
+npm install @mui/material @mui/icons-material @emotion/react @emotion/styled @emotion/css
+```
+
+## Quickstart
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { ThemeProviderWrapper } from "@atomazing-org/design-system";
+import { defaultThemes } from "@atomazing-org/design-system/presets";
+
+import App from "./App";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <ThemeProviderWrapper themes={defaultThemes}>
+    <App />
+  </ThemeProviderWrapper>
+);
+```
+
+## Presets
+Ship-ready presets live under the `/presets` subpath. `defaultThemes` contains all built-in presets.
+
+```ts
+import { defaultThemes, modernMinimal } from "@atomazing-org/design-system/presets";
+```
+
+Built-in presets:
+- Warm Earth
+- Editorial Classic
+- Modern Minimal
+- Neo Glass
+- Retro Terminal
+- Kids Cartoon
+
+## Dark mode
+`darkMode` controls which scheme is active. Supported values:
+- `light`
+- `dark`
+- `system`
+- `auto` (alias of `system`)
+
+`effectiveMode` is derived from `darkMode` + the OS preference. If the system preference is unknown, the library falls back to `light`.
+
+```tsx
+import { useThemeSettings, darkModeOptions } from "@atomazing-org/design-system";
+import { FormControlLabel, Radio, RadioGroup } from "@mui/material";
+
+export function DarkModeSelector() {
+  const { darkMode, setDarkMode } = useThemeSettings();
+
+  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>
+  );
+}
+```
+
+## Custom presets
+Define a `ThemePreset` with `colorSchemes.light` and `colorSchemes.dark`.
+
+```ts
+import type { ThemePreset } from "@atomazing-org/design-system";
+
+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)",
+      },
+    },
+  },
+};
+```
+
+Merge with built-ins:
+```ts
+const themes = [...defaultThemes, myPreset];
+```
+
+Duplicate preset ids are resolved by last-wins while preserving the first-occurrence order.
+
+## API reference
+
+### ThemeProviderWrapper
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `themes` | `ThemesInput` | `Default` preset | `ThemePreset[]` list used for runtime preset selection. |
+| `fontFamily` | `string` | `undefined` | Optional global font stack. |
+| `children` | `ReactNode` | required | Application content. |
+
+`ThemeProviderWrapper` no longer supports legacy theme tuple/object contracts (`Theme1`, `ThemeN`, `ThemesProp`) and expects `ThemePreset[]` only.
+
+### ThemePreset
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Stable preset identifier (used for selection + persistence). |
+| `label` | `string` | Human-friendly preset name. |
+| `colorSchemes.light` | `ThemeOptions` | Light scheme tokens. |
+| `colorSchemes.dark` | `ThemeOptions` | Dark scheme tokens. |
+| `description` | `string?` | Optional description. |
+| `tags` | `string[]?` | Optional tags. |
+| `version` | `string?` | Optional preset version. |
+
+### DarkModeSetting
+| Value | Meaning |
+| --- | --- |
+| `light` | Force light scheme |
+| `dark` | Force dark scheme |
+| `system` | Follow OS preference |
+| `auto` | Alias of `system` |
+
+### useThemeSettings
+Returns:
+- `theme`, `setTheme`
+- `darkMode`, `setDarkMode`
+- `themes`, `selectedTheme`, `defaultThemeName`
+
+### Presets exports
+`@atomazing-org/design-system/presets` exports:
+- `defaultThemes`
+- `editorialClassic`, `modernMinimal`, `neoGlass`, `retroTerminal`, `warmEarth`
+
+## Examples
+The repro app is the fastest way to validate presets and dark mode:
+
+```bash
+pnpm -C examples/repro install
+pnpm -C examples/repro dev
+```
+
+Look for:
+- Theme controls (preset + mode)
+- Token Debug Panel (tokens + persistence)
+- Smoke Gate checklist and overlay demos
+
+## Troubleshooting
+- Dark mode does not change background:
+  - Ensure both `colorSchemes.light` and `colorSchemes.dark` set `palette.background.default` and `palette.background.paper`.
+  - Remove hardcoded `#fff`/`#000` from layouts that override theme tokens.
+- Text is unreadable in dark mode:
+  - Verify `palette.text.primary`/`secondary` for dark schemes.
+  - Check divider and surface contrast in the repro app.
+- Preset switching does not update:
+  - Ensure preset ids are unique and non-empty.
+  - Clear `localStorage` key `appSettings` if persisted values are invalid.
+- SSR warnings:
+  - Ensure the provider is mounted inside a client boundary for SSR apps.
+
+## Consumer alias guidance
+These aliases are for your application code (not library internals).
+
+`tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@components/*": ["src/components/*"],
+      "@features/*": ["src/features/*"]
+    }
+  }
+}
+```
+
+`vite.config.ts`:
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { resolve } from "path";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": resolve(__dirname, "src"),
+      "@components": resolve(__dirname, "src/components"),
+      "@features": resolve(__dirname, "src/features"),
+    },
+  },
+});
+```
+
+## Contributing
+```bash
+pnpm lint
+pnpm build
+pnpm test
+pnpm -C examples/repro dev
+```
+
+## Release notes
+Current release highlights:
+- Scheme-based presets with explicit light/dark schemes
+- Improved dark mode and persistence alignment
+- Stable `@atomazing-org/design-system/presets` subpath export
+
+## License
+MIT