npm package: @ortha/design-system
Description: MUI-based design system for the Ortha platform — provides theme creation, design tokens, a theme provider, and shared UI components. All admin plugins use this package for consistent styling.
Latest version: 0.0.4

# @ortha/design-system

MUI-based design system for the Ortha platform — provides theme creation, design tokens, a theme provider, and shared UI components. All admin plugins use this package for consistent styling.

## Installation

Internal monorepo dependency — import directly:

```ts
import { createTheme, ThemeProvider } from '@ortha/design-system';
```

## Usage

### Theme provider

```tsx
import { ThemeProvider } from '@ortha/design-system';

const App = () => (
    <ThemeProvider>
        <MyApplication />
    </ThemeProvider>
);
```

The `ThemeProvider` wraps the application with MUI's `ThemeProvider` and optional `CssBaseline` for consistent baseline styles.

### Custom theme

```ts
import { createTheme } from '@ortha/design-system';

const theme = createTheme();
// Returns a MUI theme with custom palette, typography, breakpoints,
// shape, and component overrides
```

### Design tokens

```ts
import { palette, spacing, typography } from '@ortha/design-system';

// Access colour palette, spacing scale, and typography tokens
```

### Shared components

```tsx
import { SomeComponent } from '@ortha/design-system';

// Shared UI components used across feature plugins
```

## API Reference

| Export Area | Description                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| Theme       | `createTheme()` factory — MUI theme with custom palette, typography, breakpoints, overrides |
| Providers   | `ThemeProvider` — wraps app with MUI `ThemeProvider` + optional `CssBaseline`               |
| Tokens      | Design tokens — colour palette, spacing scales, typography definitions                      |
| Components  | Shared UI components used across feature plugins                                            |
| Utils       | Utility functions for common UI operations                                                  |

## Theme Customisation

The `createTheme()` factory configures:

- **Palette** — custom primary, secondary, error, warning, success, and info colours
- **Typography** — font family, size scale, and weight definitions
- **Breakpoints** — responsive breakpoint values
- **Shape** — border radius tokens
- **Component overrides** — default props and style overrides for `MuiTextField`, `MuiInputLabel`, `MuiCard`, `MuiLink`, and others

## Internal Structure

```
src/lib/
├── theme/
│   └── create-theme/index.ts      # MUI createTheme factory
├── tokens/                        # Design token definitions
├── providers/
│   └── ThemeProvider/index.tsx     # Theme + CssBaseline provider
├── components/                    # Shared React components
└── utils/                         # Utility functions
```

## Key Patterns

- Theme uses `alpha()` helper from MUI for opacity adjustments.
- Component overrides are defined in the theme factory — not in individual components.
- Light theme is the default.
- All components use the MUI `sx` prop — no external CSS files.
- `LocalizationProvider` (for date pickers) is colocated with date components, not in `ThemeProvider`.
- Package declares `"sideEffects": false` to enable tree-shaking of unused components.

## Building

```bash
nx build design-system
```