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:

# 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

// 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)

<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:

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

yarn install
yarn build

Peer dependencies (install in your consuming app):

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