@atomazing-org/design-system/README.MD

A library providing a set of useful utils, MUI style extensions, and components to build your application.

@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?: { name: string; primaryColor: string; secondaryColor?: string }[]`
- `fontFamily?: string`
- `colorPaletteOverride?: Partial<ColorPaletteType>`

Dynamic Themes (array)
Provide a fully dynamic list of themes to the provider. This takes priority over static defaults.

```tsx
<ThemeProviderWrapper
  themes={[
    { name: 'Blue', primaryColor: '#3B82F6' },
    {
      name: 'Aurora',
      primaryColor: '#00E952',
      secondaryColor: '#011926',
      background: {
        light: { default: '#F0FFF6', paper: '#FFFFFF' },
        dark: { default: '#071B13', paper: '#0E2A1F' },
      },
    },
    { name: 'Gray', primaryColor: '#64748B' },
  ]}
>
  {/* ... */}
</ThemeProviderWrapper>
```

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)