npm package: @octoguide/mui-ui-toolkit
Description: Extended MUI component library with multi-theme support
Latest version: 0.10.0

# mui-ui-toolkit

A TypeScript component library that extends every MUI component with a
fully token-driven, multi-theme design system. No hard-coded CSS values
anywhere — every colour, radius, spacing, shadow, and transition comes
from a typed token set.

---

## Architecture

```
src/
├── themes/
│   ├── tokens.ts          # ThemeTokens interface — the single source of truth
│   ├── registry.ts        # Maps theme names → token objects
│   ├── config.ts          # Reads active theme from .env
│   ├── createMuiTheme.ts  # Converts tokens → MUI Theme
│   ├── theme1/            # "Ocean Blue" — blue primary, sharper corners
│   │   └── index.ts
│   └── theme2/            # "Forest Green" — green primary, rounder corners
│       └── index.ts
├── types/
│   └── mui.d.ts           # Augments MUI Theme with `theme.tokens`
├── components/
│   ├── Button/
│   ├── Card/
│   └── TextField/
├── ThemeProvider.tsx      # Drop-in provider for consuming apps
└── index.ts               # Public API
```

---

## Selecting a theme

In your app's `.env` file, set the theme via an environment variable.
The variable name depends on your build tool:

```bash
# Vite
VITE_THEME=theme2

# Create React App
REACT_APP_THEME=theme2

# Next.js
NEXT_PUBLIC_THEME=theme2
```

Copy `.env.example` to `.env` and uncomment the right line.

---

## Basic usage

```tsx
// main.tsx (or _app.tsx, layout.tsx, etc.)
import { ToolkitThemeProvider } from '@mui-ui-toolkit/core';

export default function Root() {
	return (
		<ToolkitThemeProvider>
			{' '}
			{/* reads VITE_THEME from .env */}
			<App />
		</ToolkitThemeProvider>
	);
}
```

### Override the theme at runtime (e.g. user preference)

```tsx
<ToolkitThemeProvider theme="theme1">
	<App />
</ToolkitThemeProvider>
```

---

## How the token system works

Every theme implements the `ThemeTokens` interface (`src/themes/tokens.ts`).
TypeScript will fail to compile if a theme is missing any token, guaranteeing
complete coverage.

```
ThemeTokens
├── colors.*          primary, secondary, background, text, divider, …
├── typography.*      fontFamily, fontSize*, fontWeight*, lineHeight*, …
├── spacing.*         unit, xs, sm, md, lg, xl, xxl
├── borderRadius.*    none, xs, sm, md, lg, xl, full
├── shadows.*         none, xs, sm, md, lg, xl
├── transitions.*     duration*, easing*
├── zIndex.*          base, dropdown, sticky, overlay, modal, …
└── components.*      button.*, input.*, card.*, chip.*, …
```

`createMuiTheme(tokens)` converts these into a MUI `Theme` and also
attaches the raw tokens as `theme.tokens` (via TypeScript module
augmentation). So inside any styled component you can write:

```ts
const StyledDiv = styled('div')(({ theme }) => ({
	borderRadius: theme.tokens.borderRadius.md, // ✅  from active theme
	padding: theme.tokens.spacing.lg, // ✅  from active theme
	color: theme.tokens.colors.textPrimary, // ✅  from active theme
	// borderRadius: '8px',                        // ❌  never do this
}));
```

---

## Adding a new theme

1. Create `src/themes/theme3/index.ts` and export a `ThemeTokens` object.
2. Add `'theme3'` to the `ThemeName` union in `src/themes/registry.ts`.
3. Register it in the `themeRegistry` map in the same file.
4. Set `VITE_THEME=theme3` (or equivalent) in your `.env`.

TypeScript will enforce that every token is provided — no partial themes.

---

## Adding a new component

1. Create `src/components/MyComponent/MyComponent.tsx`.
2. Use `styled()` from `@mui/material/styles` and reference **only**
   `theme.tokens.*` values — never string literals for visual properties.
3. Export from `src/components/MyComponent/index.ts`.
4. Re-export from `src/index.ts`.

---

## Installation

```bash
yarn install
yarn build
```

Peer dependencies (install in your consuming app):

```bash
yarn add @mui/material @emotion/react @emotion/styled react react-dom
```