@stapel/tokens-mui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @stapel/tokens-mui
+
+The Material UI leg of the **token bridge** (frontend-guidelines §2.4; owner
+decision §38 T3). It projects `@stapel/tokens` L2 core tokens onto a MUI `Theme`
+— the explicit Material alternative to `@stapel/tokens-antd` (§2.3).
+
+There is exactly **one** L2 → design-system role mapping table, and it lives in
+`@stapel/tokens` (`bridgeColorRoles` + the radius/font-size roles). This package
+only renames those neutral roles to MUI's nested `palette`/`shape`/`typography`
+fields and picks the `light`/`dark` half — it holds no colour decisions of its
+own, so it and `@stapel/tokens-antd` cannot drift.
+
+## Usage
+
+```tsx
+import { toMuiTheme } from "@stapel/tokens-mui";
+import { ThemeProvider, CssBaseline } from "@mui/material";
+
+<ThemeProvider theme={toMuiTheme(mode)}>
+  <CssBaseline />
+  <App />
+</ThemeProvider>;
+```
+
+## The mapping (frontend-guidelines §2.4)
+
+| `@stapel/tokens` role | L2 core token | MUI theme field |
+| --- | --- | --- |
+| `brand` | `accent` | `palette.primary.main` |
+| `success` | `text-positive` | `palette.success.main` |
+| `warning` | `text-warning` | `palette.warning.main` |
+| `danger` | `text-negative` | `palette.error.main` |
+| `info` | `text-info` | `palette.info.main` |
+| `bgContainer` | `upperground-primary` | `palette.background.paper` |
+| `bgLayout` | `background-primary` | `palette.background.default` |
+| `textPrimary` | `text-primary` | `palette.text.primary` |
+| radius `md` | — | `shape.borderRadius` |
+| font-size `md` | — | `typography.fontSize` |
+
+`@mui/material` (and its `@emotion/*` peers) are peer dependencies — the
+consuming app brings its own copy.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { Theme } from "@mui/material/styles";
+/** Light or dark — the half of every L2 core token's `{light,dark}` pair. */
+export type ThemeMode = "light" | "dark";
+/**
+ * `@stapel/tokens` L2 → a MUI `Theme` (frontend-guidelines §2.4 table). Pure:
+ * same `mode` in, an equivalent theme out; reads no globals.
+ */
+export declare function toMuiTheme(mode: ThemeMode): Theme;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAYlD,6EAA6E;AAC7E,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAOzC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CA2BjD"}

package/dist/index.js

@@ -0,0 +1,58 @@
+/**
+ * `@stapel/tokens-mui` — the Material UI leg of the token bridge
+ * (frontend-guidelines §2.4, owner decision §38 T3). It translates the ONE
+ * neutral role table in `@stapel/tokens` (`bridgeColorRoles` + the radius/
+ * font-size roles) into a MUI `Theme`. The L2 → role decision is NOT duplicated
+ * here — this file only renames roles to MUI's nested `palette`/`shape`/
+ * `typography` fields and picks the light/dark half, so it and
+ * `@stapel/tokens-antd` cannot drift.
+ *
+ * ```tsx
+ * import { toMuiTheme } from "@stapel/tokens-mui";
+ * import { ThemeProvider, CssBaseline } from "@mui/material";
+ *
+ * <ThemeProvider theme={toMuiTheme(mode)}>
+ *   <CssBaseline />
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+import { createTheme } from "@mui/material/styles";
+import { bridgeColorRoles, bridgeFontSizeRole, bridgeRadiusRole, colors, fontFamily, fontSize, radii, } from "@stapel/tokens";
+/** Resolve a neutral colour role to its hex for `mode` via the shared table. */
+function role(name, mode) {
+    return colors[bridgeColorRoles[name]][mode];
+}
+/**
+ * `@stapel/tokens` L2 → a MUI `Theme` (frontend-guidelines §2.4 table). Pure:
+ * same `mode` in, an equivalent theme out; reads no globals.
+ */
+export function toMuiTheme(mode) {
+    return createTheme({
+        palette: {
+            mode,
+            primary: { main: role("brand", mode), contrastText: role("textOnBrand", mode) },
+            success: { main: role("success", mode) },
+            warning: { main: role("warning", mode) },
+            error: { main: role("danger", mode) },
+            info: { main: role("info", mode) },
+            text: {
+                primary: role("textPrimary", mode),
+                secondary: role("textSecondary", mode),
+            },
+            background: {
+                default: role("bgLayout", mode),
+                paper: role("bgContainer", mode),
+            },
+            divider: role("border", mode),
+        },
+        shape: {
+            borderRadius: radii[bridgeRadiusRole],
+        },
+        typography: {
+            fontFamily: fontFamily.sans,
+            fontSize: fontSize[bridgeFontSizeRole].fontSize,
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,KAAK,GACN,MAAM,gBAAgB,CAAC;AAMxB,gFAAgF;AAChF,SAAS,IAAI,CAAC,IAAqB,EAAE,IAAe;IAClD,OAAO,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAe;IACxC,OAAO,WAAW,CAAC;QACjB,OAAO,EAAE;YACP,IAAI;YACJ,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,EAAE;YAC/E,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE;YACxC,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE;YACxC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE;YACrC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE;YAClC,IAAI,EAAE;gBACJ,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC;gBAClC,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC;aACvC;YACD,UAAU,EAAE;gBACV,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC;gBAC/B,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC;aACjC;YACD,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC;SAC9B;QACD,KAAK,EAAE;YACL,YAAY,EAAE,KAAK,CAAC,gBAAgB,CAAC;SACtC;QACD,UAAU,EAAE;YACV,UAAU,EAAE,UAAU,CAAC,IAAI;YAC3B,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC,QAAQ;SAChD;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@stapel/tokens-mui",
+  "version": "0.1.0",
+  "description": "Token bridge (frontend-guidelines §2.4, §38 T3): projects @stapel/tokens L2 core tokens onto a Material UI theme. `toMuiTheme(mode)` → a MUI Theme (createTheme). Pure function, one mapping table shared with @stapel/tokens-antd. Not components.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usestapel/stapel-react.git",
+    "directory": "packages/tokens-mui"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "3 KB"
+    }
+  ],
+  "peerDependencies": {
+    "@mui/material": ">=5.15.0 <8"
+  },
+  "dependencies": {
+    "@stapel/tokens": "^0.3.0"
+  },
+  "devDependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.0",
+    "@mui/material": "^7.3.0",
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "size-limit": "^11.2.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "size": "size-limit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * `@stapel/tokens-mui` — the Material UI leg of the token bridge
+ * (frontend-guidelines §2.4, owner decision §38 T3). It translates the ONE
+ * neutral role table in `@stapel/tokens` (`bridgeColorRoles` + the radius/
+ * font-size roles) into a MUI `Theme`. The L2 → role decision is NOT duplicated
+ * here — this file only renames roles to MUI's nested `palette`/`shape`/
+ * `typography` fields and picks the light/dark half, so it and
+ * `@stapel/tokens-antd` cannot drift.
+ *
+ * ```tsx
+ * import { toMuiTheme } from "@stapel/tokens-mui";
+ * import { ThemeProvider, CssBaseline } from "@mui/material";
+ *
+ * <ThemeProvider theme={toMuiTheme(mode)}>
+ *   <CssBaseline />
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+import { createTheme } from "@mui/material/styles";
+import type { Theme } from "@mui/material/styles";
+import {
+  bridgeColorRoles,
+  bridgeFontSizeRole,
+  bridgeRadiusRole,
+  colors,
+  fontFamily,
+  fontSize,
+  radii,
+} from "@stapel/tokens";
+import type { BridgeColorRole } from "@stapel/tokens";
+
+/** Light or dark — the half of every L2 core token's `{light,dark}` pair. */
+export type ThemeMode = "light" | "dark";
+
+/** Resolve a neutral colour role to its hex for `mode` via the shared table. */
+function role(name: BridgeColorRole, mode: ThemeMode): string {
+  return colors[bridgeColorRoles[name]][mode];
+}
+
+/**
+ * `@stapel/tokens` L2 → a MUI `Theme` (frontend-guidelines §2.4 table). Pure:
+ * same `mode` in, an equivalent theme out; reads no globals.
+ */
+export function toMuiTheme(mode: ThemeMode): Theme {
+  return createTheme({
+    palette: {
+      mode,
+      primary: { main: role("brand", mode), contrastText: role("textOnBrand", mode) },
+      success: { main: role("success", mode) },
+      warning: { main: role("warning", mode) },
+      error: { main: role("danger", mode) },
+      info: { main: role("info", mode) },
+      text: {
+        primary: role("textPrimary", mode),
+        secondary: role("textSecondary", mode),
+      },
+      background: {
+        default: role("bgLayout", mode),
+        paper: role("bgContainer", mode),
+      },
+      divider: role("border", mode),
+    },
+    shape: {
+      borderRadius: radii[bridgeRadiusRole],
+    },
+    typography: {
+      fontFamily: fontFamily.sans,
+      fontSize: fontSize[bridgeFontSizeRole].fontSize,
+    },
+  });
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "_comment": "Self-contained on purpose: standalone-buildable per frontend-standard §7. Mirrors the root tsconfig.base.json settings.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "isolatedDeclarations": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}