@octoguide/mui-ui-toolkit 0.1.0

package/README.md

@@ -0,0 +1,231 @@
+# 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
+```
+
+## command used to create the foundational components
+
+nder the src/components/foundation folder i want to add  
+wrapper objects for each of the following. these objects will  
+live in their own component file. not 1 big file  
+each component will extend the base typography component in the  
+mui-design library  
+H1
+
+<div class="css-1pjc7v5"><h1 class="MuiTypography-root           
+MuiTypography-h1 css-p6re0n">How can you choose a                
+typeface?</h1><pre class="MuiBox-root css-6cymt6">{              
+  "fontWeight": 800,                                             
+  "fontSize": "2.5rem (40px)",                                   
+  "lineHeight": 1.25,                                            
+  "@media (min-width:600px)": {                                  
+    "fontSize": "3.25rem (52px)"                                 
+  },                                                             
+  "@media (min-width:900px)": {                                  
+    "fontSize": "3.625rem (58px)"                                
+  },                                                             
+  "@media (min-width:1200px)": {                                 
+    "fontSize": "4rem (64px)"                                    
+  }                                                              
+}</pre></div>                                                    
+  ⎿  Interrupted · What should Claude do instead?
+
+[Image #2] (↑ to select)
+─────────────────────────────────────────────────────────── ▪▪▪ ─
+❯ under the src/components/foundation folder i want to add
+wrapper objects for each of the following. these objects will
+live in their own component file. not 1 big file
+each component will extend the base typography component in
+the mui-design library
+for each component i will give 2 lines for the name of the
+component and what to export it as, the div element that
+contains the component itself as it is used on a web page and
+the pre object that contains the styles for the component
+rules for each component
+always use the theme values rather than hardcoding values
+i.e fontweight:800, the 800 should come from the theme
+definition
+also create the storybook entry from the component entry i
+have provided above showing the component name, example text,
+and the styles from the pre section to show the styles that
+make up the component all on a card like this
+
+all the theme elements can be found in docs/theme.json which
+is a json object showing all the current default theme values
+H1
+[Pasted text #1 +13 lines]
+H2
+[Pasted text #3 +13 lines]  
+ H3  
+ [Pasted text #4 +13 lines]  
+ H4  
+ [Pasted text #5 +7 lines]  
+ H5  
+ [Pasted text #6 +7 lines]  
+ H6  
+ [Pasted text #7 +7 lines]  
+ Subtitle1  
+ [Pasted text #8 +4 lines]  
+ Subtitle2  
+ [Pasted text #9 +4 lines]  
+ Body1  
+ [Pasted text #10 +4 lines]  
+ Body2  
+ [Pasted text #11 +4 lines]  
+ Caption  
+ [Pasted text #12 +4 lines]  
+ Overline  
+ [Pasted text #13 +4 lines]  
+ Button  
+ [Pasted text #14 +4 lines]  
+ use the text.primary values from the theme palette object as  
+ the text colour and use the theme entry from the typeography  
+ object for each component  
+ for example H1 fontweight should come from the them value  
+ typography.h1.fontWeight  
+ at the end if you can add tests for each component  
+ build and check for completness  
+ i can use storybook to see if the components creation worked